# nethusara003/vocalist architecture

> Architecture diagram of the GitHub repository nethusara003/vocalist, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nethusara003/vocalist
- Repository: https://github.com/nethusara003/vocalist

## Overview

Vocalis is a local text-to-speech application: users edit or import text, choose a local voice and speech settings, generate audio, preview it, and download WAV/MP3 or batch ZIP outputs. The main path runs from the editor through the local HTTP backend, paragraph- and sentence-aware chunking, platform-selected speech workers, and audio merging/conversion to local files. The README documents additional editor, recovery, and desktop capabilities not fully visible in the sampled frontend excerpt; their detailed wiring is therefore omitted.

Main entry points: [`server/server.js`](https://github.com/nethusara003/vocalist/blob/main/server/server.js) (HTTP API), [`output`](https://github.com/nethusara003/vocalist/tree/main/output) (Generated files), [`server/tts_worker.py`](https://github.com/nethusara003/vocalist/blob/main/server/tts_worker.py) (macOS worker), [`server/utils/audioMerger.js`](https://github.com/nethusara003/vocalist/blob/main/server/utils/audioMerger.js) (Audio merger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Text editor"]
  node_editor["Editor and controls<br/>[script.js]"]
  node_batch["Batch workspace<br/>[script.js]"]
  node_player["Audio preview<br/>[script.js]"]
end

subgraph group_backend["Local backend"]
  node_api["HTTP API<br/>[server.js]"]
  node_chunker["Text chunker<br/>[textChunker.js]"]
  node_merger["Audio merger<br/>[audioMerger.js]"]
  node_zip["ZIP export<br/>[server.js]"]
end

subgraph group_speech["Speech runtime"]
  node_service["TTS manager<br/>[ttsService.js]"]
  node_macworker["macOS worker<br/>[tts_worker.py]"]
  node_winworker["Windows worker"]
end

subgraph group_artifacts["Audio artifacts"]
  node_output[("Generated files")]
end

node_user(("User"))
node_desktop["Desktop shell<br/>[main.js]"]
node_kokoro["Kokoro MLX"]
node_macsay["macOS say"]
node_sapi["Windows SAPI"]
node_ffmpeg["FFmpeg"]

node_user -->|"edits text"| node_editor
node_user -->|"selects documents"| node_batch
node_editor -->|"HTTP requests"| node_api
node_batch -->|"HTTP requests"| node_api
node_api -->|"chunks text"| node_chunker
node_api -->|"requests speech"| node_service
node_service -->|"starts and queues"| node_macworker
node_service -->|"starts on Windows"| node_winworker
node_macworker -.->|"synthesizes with"| node_kokoro
node_macworker -.->|"falls back to"| node_macsay
node_winworker -->|"synthesizes with"| node_sapi
node_api -->|"merges and converts"| node_merger
node_merger -->|"runs conversion"| node_ffmpeg
node_macworker -->|"writes WAV chunks"| node_output
node_winworker -->|"writes WAV chunks"| node_output
node_merger -->|"writes final audio"| node_output
node_api -->|"serves and reads"| node_output
node_player -->|"loads audio"| node_api
node_api -->|"dispatches export"| node_zip
node_zip -->|"reads batch files"| node_output
node_desktop -->|"starts and stops"| node_api
node_desktop -->|"loads interface"| node_editor

click node_editor "https://github.com/nethusara003/vocalist/blob/main/script.js"
click node_batch "https://github.com/nethusara003/vocalist/blob/main/script.js"
click node_player "https://github.com/nethusara003/vocalist/blob/main/script.js"
click node_desktop "https://github.com/nethusara003/vocalist/blob/main/electron/main.js"
click node_api "https://github.com/nethusara003/vocalist/blob/main/server/server.js"
click node_chunker "https://github.com/nethusara003/vocalist/blob/main/server/utils/textChunker.js"
click node_service "https://github.com/nethusara003/vocalist/blob/main/server/services/ttsService.js"
click node_macworker "https://github.com/nethusara003/vocalist/blob/main/server/tts_worker.py"
click node_winworker "https://github.com/nethusara003/vocalist/blob/main/server/windows_tts_worker.ps1"
click node_merger "https://github.com/nethusara003/vocalist/blob/main/server/utils/audioMerger.js"
click node_output "https://github.com/nethusara003/vocalist/tree/main/output"
click node_zip "https://github.com/nethusara003/vocalist/blob/main/server/server.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_editor,node_batch,node_player,node_user toneBlue
class node_api,node_chunker,node_merger,node_zip toneAmber
class node_service,node_macworker,node_winworker,node_sapi toneMint
class node_output toneRose
class node_desktop toneTeal
class node_kokoro,node_macsay,node_ffmpeg toneIndigo
```

## Components

### Text editor

- [Editor and controls](https://github.com/nethusara003/vocalist/blob/main/script.js): `script.js`
- [Batch workspace](https://github.com/nethusara003/vocalist/blob/main/script.js): `script.js`
- [Audio preview](https://github.com/nethusara003/vocalist/blob/main/script.js): `script.js`

### Local backend

- [HTTP API](https://github.com/nethusara003/vocalist/blob/main/server/server.js): `server/server.js`
- [Text chunker](https://github.com/nethusara003/vocalist/blob/main/server/utils/textChunker.js): `server/utils/textChunker.js`
- [Audio merger](https://github.com/nethusara003/vocalist/blob/main/server/utils/audioMerger.js): `server/utils/audioMerger.js`
- [ZIP export](https://github.com/nethusara003/vocalist/blob/main/server/server.js): `server/server.js`

### Speech runtime

- [TTS manager](https://github.com/nethusara003/vocalist/blob/main/server/services/ttsService.js): `server/services/ttsService.js`
- [macOS worker](https://github.com/nethusara003/vocalist/blob/main/server/tts_worker.py): `server/tts_worker.py`
- [Windows worker](https://github.com/nethusara003/vocalist/blob/main/server/windows_tts_worker.ps1): `server/windows_tts_worker.ps1`

### Audio artifacts

- [Generated files](https://github.com/nethusara003/vocalist/tree/main/output): `output`

### Other components

- **User**
- [Desktop shell](https://github.com/nethusara003/vocalist/blob/main/electron/main.js): `electron/main.js`
- **Kokoro MLX**
- **macOS say**
- **Windows SAPI**
- **FFmpeg**

## Connections

- User → Editor and controls: edits text
- User → Batch workspace: selects documents
- Editor and controls → HTTP API: HTTP requests
- Batch workspace → HTTP API: HTTP requests
- HTTP API → Text chunker: chunks text
- HTTP API → TTS manager: requests speech
- TTS manager → macOS worker: starts and queues
- TTS manager → Windows worker: starts on Windows
- macOS worker → Kokoro MLX: synthesizes with
- macOS worker → macOS say: falls back to
- Windows worker → Windows SAPI: synthesizes with
- HTTP API → Audio merger: merges and converts
- Audio merger → FFmpeg: runs conversion
- macOS worker → Generated files: writes WAV chunks
- Windows worker → Generated files: writes WAV chunks
- Audio merger → Generated files: writes final audio
- HTTP API → Generated files: serves and reads
- Audio preview → HTTP API: loads audio
- HTTP API → ZIP export: dispatches export
- ZIP export → Generated files: reads batch files
- Desktop shell → HTTP API: starts and stops
- Desktop shell → Editor and controls: loads interface