# mherick/voicestudio architecture

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

- Interactive diagram: https://gitdiagram.com/mherick/voicestudio
- Repository: https://github.com/mherick/voicestudio

## Overview

VoiceStudio is a local-first desktop studio for voice creation and audio/video production, with optional remote workers and external integrations. The primary workflow is to choose or create a voice, provide text or media, generate or transform speech, then review and export the result. The graph preserves the README’s other major workflows and shows the Electron UI, API boundary, model engines, and persistence layer. Some backend capabilities are documented or named in the tree but their internal wiring was not sampled, so those links are intentionally conservative.

Main entry points: [`backend/main.py`](https://github.com/mherick/voicestudio/blob/main/backend/main.py) (HTTP API), [`electron/src/renderer/src/app.tsx`](https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/app.tsx) (Electron workspace), [`electron/src/renderer/src/features/clone/clone-page.tsx`](https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/features/clone/clone-page.tsx) (Voice cloning), [`electron/src/renderer/src/features/design/design-page.tsx`](https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/features/design/design-page.tsx) (Voice design)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_desktop_app["Electron workspace<br/>[app.tsx]"]
  node_engine_matrix["Engine catalogue"]
end

subgraph group_voice["Voice creation"]
  node_clone_ui["Voice cloning<br/>[clone-page.tsx]"]
  node_design_ui["Voice design<br/>[design-page.tsx]"]
  node_profiles["Voice profiles<br/>[profiles.py]"]
  node_generation_ui["Speech generation<br/>[script-panel.tsx]"]
  node_generation_api["Generation API<br/>[generation.py]"]
end

subgraph group_production["Audio production"]
  node_dub_ui["Video dubbing<br/>[dub-page.tsx]"]
  node_dub_pipeline["Dub processing<br/>[dub_pipeline.py]"]
  node_dub_api["Dub endpoints<br/>[dub_core.py]"]
  node_dictation["Dictation<br/>[dictation.py]"]
  node_longform_ui["Stories and books<br/>[longform-page.tsx]"]
  node_audiobook["Audiobook service<br/>[audiobook.py]"]
  node_batch["Batch jobs<br/>[batch-page.tsx]"]
end

subgraph group_platform["Runtime platform"]
  node_api["HTTP API<br/>[main.py]"]
  node_tts["TTS engines<br/>[tts_backend.py]"]
  node_engine_registry["Engine discovery<br/>[engines.py]"]
  node_projects[("Project storage<br/>[db.py]")]
  node_worker_pool["Remote workers<br/>[pool.py]"]
end

subgraph group_connect["Integrations"]
  node_integrations["API and MCP<br/>[mcp_server.py]"]
end

node_person(("User"))
node_external["Optional services"]

node_person -->|"uses"| node_desktop_app
node_desktop_app -->|"opens"| node_clone_ui
node_desktop_app -->|"opens"| node_design_ui
node_desktop_app -->|"opens"| node_generation_ui
node_desktop_app -->|"opens"| node_dub_ui
node_desktop_app -->|"opens"| node_longform_ui
node_desktop_app -->|"opens"| node_batch
node_clone_ui -->|"requests"| node_api
node_design_ui -->|"requests"| node_api
node_generation_ui -->|"requests"| node_api
node_api -->|"routes requests"| node_profiles
node_api -->|"routes requests"| node_generation_api
node_generation_api -->|"generates speech"| node_tts
node_api -->|"routes requests"| node_engine_registry
node_engine_matrix -->|"lists engines"| node_engine_registry
node_dub_ui -->|"submits media"| node_dub_api
node_dub_api -->|"runs dubbing"| node_dub_pipeline
node_dub_pipeline -->|"synthesizes lines"| node_tts
node_desktop_app -->|"requests transcription"| node_dictation
node_longform_ui -->|"requests generation"| node_api
node_api -->|"routes book work"| node_audiobook
node_batch -->|"queues jobs"| node_api
node_api -->|"persists state"| node_projects
node_api -.->|"dispatches work"| node_worker_pool
node_api -->|"exposes tools"| node_integrations
node_integrations -.->|"connects optionally"| node_external
node_worker_pool -.->|"uses remote compute"| node_external

click node_desktop_app "https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/app.tsx"
click node_api "https://github.com/mherick/voicestudio/blob/main/backend/main.py"
click node_clone_ui "https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/features/clone/clone-page.tsx"
click node_design_ui "https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/features/design/design-page.tsx"
click node_profiles "https://github.com/mherick/voicestudio/blob/main/backend/api/routers/profiles.py"
click node_generation_ui "https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/features/clone/script-panel.tsx"
click node_generation_api "https://github.com/mherick/voicestudio/blob/main/backend/api/routers/generation.py"
click node_tts "https://github.com/mherick/voicestudio/blob/main/backend/services/tts_backend.py"
click node_engine_registry "https://github.com/mherick/voicestudio/blob/main/backend/api/routers/engines.py"
click node_engine_matrix "https://github.com/mherick/voicestudio/blob/main/electron/src/shared/components/EngineCompatibilityMatrix.jsx"
click node_dub_ui "https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/features/dub/dub-page.tsx"
click node_dub_pipeline "https://github.com/mherick/voicestudio/blob/main/backend/services/dub_pipeline.py"
click node_dub_api "https://github.com/mherick/voicestudio/blob/main/backend/api/routers/dub_core.py"
click node_dictation "https://github.com/mherick/voicestudio/blob/main/backend/api/routers/dictation.py"
click node_longform_ui "https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/features/longform/longform-page.tsx"
click node_audiobook "https://github.com/mherick/voicestudio/blob/main/backend/services/audiobook.py"
click node_batch "https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/features/batch/batch-page.tsx"
click node_projects "https://github.com/mherick/voicestudio/blob/main/backend/core/db.py"
click node_worker_pool "https://github.com/mherick/voicestudio/blob/main/backend/worker/pool.py"
click node_integrations "https://github.com/mherick/voicestudio/blob/main/backend/mcp_server.py"

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_desktop_app,node_engine_matrix,node_person toneBlue
class node_clone_ui,node_design_ui,node_profiles,node_generation_ui,node_generation_api toneAmber
class node_dub_ui,node_dub_pipeline,node_dub_api,node_dictation,node_longform_ui,node_audiobook,node_batch toneMint
class node_api,node_tts,node_engine_registry,node_projects,node_worker_pool toneRose
class node_integrations,node_external toneIndigo
```

## Components

### Desktop experience

- [Electron workspace](https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/app.tsx): `electron/src/renderer/src/app.tsx`
- [Engine catalogue](https://github.com/mherick/voicestudio/blob/main/electron/src/shared/components/EngineCompatibilityMatrix.jsx): `electron/src/shared/components/EngineCompatibilityMatrix.jsx`

### Voice creation

- [Voice cloning](https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/features/clone/clone-page.tsx): `electron/src/renderer/src/features/clone/clone-page.tsx`
- [Voice design](https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/features/design/design-page.tsx): `electron/src/renderer/src/features/design/design-page.tsx`
- [Voice profiles](https://github.com/mherick/voicestudio/blob/main/backend/api/routers/profiles.py): `backend/api/routers/profiles.py`
- [Speech generation](https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/features/clone/script-panel.tsx): `electron/src/renderer/src/features/clone/script-panel.tsx`
- [Generation API](https://github.com/mherick/voicestudio/blob/main/backend/api/routers/generation.py): `backend/api/routers/generation.py`

### Audio production

- [Video dubbing](https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/features/dub/dub-page.tsx): `electron/src/renderer/src/features/dub/dub-page.tsx`
- [Dub processing](https://github.com/mherick/voicestudio/blob/main/backend/services/dub_pipeline.py): `backend/services/dub_pipeline.py`
- [Dub endpoints](https://github.com/mherick/voicestudio/blob/main/backend/api/routers/dub_core.py): `backend/api/routers/dub_core.py`
- [Dictation](https://github.com/mherick/voicestudio/blob/main/backend/api/routers/dictation.py): `backend/api/routers/dictation.py`
- [Stories and books](https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/features/longform/longform-page.tsx): `electron/src/renderer/src/features/longform/longform-page.tsx`
- [Audiobook service](https://github.com/mherick/voicestudio/blob/main/backend/services/audiobook.py): `backend/services/audiobook.py`
- [Batch jobs](https://github.com/mherick/voicestudio/blob/main/electron/src/renderer/src/features/batch/batch-page.tsx): `electron/src/renderer/src/features/batch/batch-page.tsx`

### Runtime platform

- [HTTP API](https://github.com/mherick/voicestudio/blob/main/backend/main.py): `backend/main.py`
- [TTS engines](https://github.com/mherick/voicestudio/blob/main/backend/services/tts_backend.py): `backend/services/tts_backend.py`
- [Engine discovery](https://github.com/mherick/voicestudio/blob/main/backend/api/routers/engines.py): `backend/api/routers/engines.py`
- [Project storage](https://github.com/mherick/voicestudio/blob/main/backend/core/db.py): `backend/core/db.py`
- [Remote workers](https://github.com/mherick/voicestudio/blob/main/backend/worker/pool.py): `backend/worker/pool.py`

### Integrations

- [API and MCP](https://github.com/mherick/voicestudio/blob/main/backend/mcp_server.py): `backend/mcp_server.py`

### Other components

- **User**
- **Optional services**

## Connections

- User → Electron workspace: uses
- Electron workspace → Voice cloning: opens
- Electron workspace → Voice design: opens
- Electron workspace → Speech generation: opens
- Electron workspace → Video dubbing: opens
- Electron workspace → Stories and books: opens
- Electron workspace → Batch jobs: opens
- Voice cloning → HTTP API: requests
- Voice design → HTTP API: requests
- Speech generation → HTTP API: requests
- HTTP API → Voice profiles: routes requests
- HTTP API → Generation API: routes requests
- Generation API → TTS engines: generates speech
- HTTP API → Engine discovery: routes requests
- Engine catalogue → Engine discovery: lists engines
- Video dubbing → Dub endpoints: submits media
- Dub endpoints → Dub processing: runs dubbing
- Dub processing → TTS engines: synthesizes lines
- Electron workspace → Dictation: requests transcription
- Stories and books → HTTP API: requests generation
- HTTP API → Audiobook service: routes book work
- Batch jobs → HTTP API: queues jobs
- HTTP API → Project storage: persists state
- HTTP API → Remote workers: dispatches work
- HTTP API → API and MCP: exposes tools
- API and MCP → Optional services: connects optionally
- Remote workers → Optional services: uses remote compute