# no-needs/voicestudio architecture

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

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

## Overview

VoiceStudio is a local-first AI voice studio for cloning and designing voices, generating speech, dubbing video, dictation/transcription, and narration. A typical workflow starts in the desktop workspace, uses backend APIs to configure engines or submit media and text, and returns generated or processed audio/video. The backend also exposes model setup, cloud sync, and telephony capabilities. The graph emphasizes documented backend call relationships; several UI-to-API connections are unverified because the excerpts do not show their transport wiring.

Main entry points: [`backend/api/routers/dub_core.py`](https://github.com/no-needs/voicestudio/blob/main/backend/api/routers/dub_core.py) (Dubbing API), [`backend/api/routers/engines.py`](https://github.com/no-needs/voicestudio/blob/main/backend/api/routers/engines.py) (Engine API), [`backend/main.py`](https://github.com/no-needs/voicestudio/blob/main/backend/main.py) (API application), [`backend/services/dub_pipeline.py`](https://github.com/no-needs/voicestudio/blob/main/backend/services/dub_pipeline.py) (Dubbing pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Desktop experience"]
  node_workspace["Studio workspace<br/>[app.tsx]"]
end

subgraph group_api["Backend API"]
  node_server["API application<br/>[main.py]"]
  node_dub_api["Dubbing API<br/>[dub_core.py]"]
  node_engine_api["Engine API<br/>[engines.py]"]
  node_setup_api["Model setup API<br/>[models.py]"]
end

subgraph group_media["Speech and media"]
  node_dub_service["Dubbing pipeline<br/>[dub_pipeline.py]"]
  node_speech_engines["Speech backends<br/>[tts_backend.py]"]
  node_asr["Transcription<br/>[asr_backend.py]"]
  node_media_tools["Media processing<br/>[ffmpeg_utils.py]"]
end

subgraph group_runtime["Runtime and state"]
  node_model_manager["Model runtime<br/>[model_manager.py]"]
  node_device_caps["Device capabilities<br/>[device_caps.py]"]
  node_config["App configuration<br/>[config.py]"]
  node_preferences["User preferences<br/>[prefs.py]"]
  node_task_manager["Background tasks<br/>[tasks.py]"]
  node_job_store[("Job event store<br/>[job_store.py]")]
  node_failure_handling["Failure reporting<br/>[failure.py]"]
end

subgraph group_capabilities["Additional capabilities"]
  node_cloud_sync["Cloud sync<br/>[engine.py]"]
  node_dictation["Dictation"]
  node_telephony["Telephony<br/>[agent.py]"]
end

node_user(("Studio user"))

node_user -.->|"uses"| node_workspace
node_workspace -.->|"requests"| node_server
node_server -->|"registers tasks"| node_task_manager
node_server -->|"configures"| node_config
node_dub_api -->|"delegates to"| node_dub_service
node_dub_api -->|"uses"| node_model_manager
node_dub_api -->|"transcribes with"| node_asr
node_dub_service -->|"uses"| node_model_manager
node_dub_service -->|"processes media"| node_media_tools
node_engine_api -->|"lists backends"| node_speech_engines
node_engine_api -->|"lists backends"| node_asr
node_engine_api -->|"reads choices"| node_preferences
node_setup_api -->|"checks backends"| node_speech_engines
node_model_manager -->|"routes by device"| node_device_caps
node_task_manager -->|"persists events"| node_job_store
node_task_manager -->|"formats failures"| node_failure_handling

click node_workspace "https://github.com/no-needs/voicestudio/blob/main/electron/src/renderer/src/app.tsx"
click node_server "https://github.com/no-needs/voicestudio/blob/main/backend/main.py"
click node_dub_api "https://github.com/no-needs/voicestudio/blob/main/backend/api/routers/dub_core.py"
click node_engine_api "https://github.com/no-needs/voicestudio/blob/main/backend/api/routers/engines.py"
click node_setup_api "https://github.com/no-needs/voicestudio/blob/main/backend/api/routers/setup/models.py"
click node_dub_service "https://github.com/no-needs/voicestudio/blob/main/backend/services/dub_pipeline.py"
click node_speech_engines "https://github.com/no-needs/voicestudio/blob/main/backend/services/tts_backend.py"
click node_asr "https://github.com/no-needs/voicestudio/blob/main/backend/services/asr_backend.py"
click node_media_tools "https://github.com/no-needs/voicestudio/blob/main/backend/services/ffmpeg_utils.py"
click node_model_manager "https://github.com/no-needs/voicestudio/blob/main/backend/services/model_manager.py"
click node_device_caps "https://github.com/no-needs/voicestudio/blob/main/backend/core/device_caps.py"
click node_config "https://github.com/no-needs/voicestudio/blob/main/backend/core/config.py"
click node_preferences "https://github.com/no-needs/voicestudio/blob/main/backend/core/prefs.py"
click node_task_manager "https://github.com/no-needs/voicestudio/blob/main/backend/core/tasks.py"
click node_job_store "https://github.com/no-needs/voicestudio/blob/main/backend/core/job_store.py"
click node_failure_handling "https://github.com/no-needs/voicestudio/blob/main/backend/core/failure.py"
click node_cloud_sync "https://github.com/no-needs/voicestudio/blob/main/backend/services/cloud_sync/engine.py"
click node_dictation "https://github.com/no-needs/voicestudio/blob/main/backend/services/sherpa_dictation.py"
click node_telephony "https://github.com/no-needs/voicestudio/blob/main/backend/services/telephony/agent.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_workspace,node_user toneBlue
class node_server,node_dub_api,node_engine_api,node_setup_api toneAmber
class node_dub_service,node_speech_engines,node_asr,node_media_tools toneMint
class node_model_manager,node_device_caps,node_config,node_preferences,node_task_manager,node_job_store,node_failure_handling toneRose
class node_cloud_sync,node_dictation,node_telephony toneIndigo
```

## Components

### Desktop experience

- [Studio workspace](https://github.com/no-needs/voicestudio/blob/main/electron/src/renderer/src/app.tsx): `electron/src/renderer/src/app.tsx`

### Backend API

- [API application](https://github.com/no-needs/voicestudio/blob/main/backend/main.py): `backend/main.py`
- [Dubbing API](https://github.com/no-needs/voicestudio/blob/main/backend/api/routers/dub_core.py): `backend/api/routers/dub_core.py`
- [Engine API](https://github.com/no-needs/voicestudio/blob/main/backend/api/routers/engines.py): `backend/api/routers/engines.py`
- [Model setup API](https://github.com/no-needs/voicestudio/blob/main/backend/api/routers/setup/models.py): `backend/api/routers/setup/models.py`

### Speech and media

- [Dubbing pipeline](https://github.com/no-needs/voicestudio/blob/main/backend/services/dub_pipeline.py): `backend/services/dub_pipeline.py`
- [Speech backends](https://github.com/no-needs/voicestudio/blob/main/backend/services/tts_backend.py): `backend/services/tts_backend.py`
- [Transcription](https://github.com/no-needs/voicestudio/blob/main/backend/services/asr_backend.py): `backend/services/asr_backend.py`
- [Media processing](https://github.com/no-needs/voicestudio/blob/main/backend/services/ffmpeg_utils.py): `backend/services/ffmpeg_utils.py`

### Runtime and state

- [Model runtime](https://github.com/no-needs/voicestudio/blob/main/backend/services/model_manager.py): `backend/services/model_manager.py`
- [Device capabilities](https://github.com/no-needs/voicestudio/blob/main/backend/core/device_caps.py): `backend/core/device_caps.py`
- [App configuration](https://github.com/no-needs/voicestudio/blob/main/backend/core/config.py): `backend/core/config.py`
- [User preferences](https://github.com/no-needs/voicestudio/blob/main/backend/core/prefs.py): `backend/core/prefs.py`
- [Background tasks](https://github.com/no-needs/voicestudio/blob/main/backend/core/tasks.py): `backend/core/tasks.py`
- [Job event store](https://github.com/no-needs/voicestudio/blob/main/backend/core/job_store.py): `backend/core/job_store.py`
- [Failure reporting](https://github.com/no-needs/voicestudio/blob/main/backend/core/failure.py): `backend/core/failure.py`

### Additional capabilities

- [Cloud sync](https://github.com/no-needs/voicestudio/blob/main/backend/services/cloud_sync/engine.py): `backend/services/cloud_sync/engine.py`
- [Dictation](https://github.com/no-needs/voicestudio/blob/main/backend/services/sherpa_dictation.py): `backend/services/sherpa_dictation.py`
- [Telephony](https://github.com/no-needs/voicestudio/blob/main/backend/services/telephony/agent.py): `backend/services/telephony/agent.py`

### Other components

- **Studio user**

## Connections

- Studio user → Studio workspace: uses
- Studio workspace → API application: requests
- API application → Background tasks: registers tasks (evidence: `backend/main.py`)
- API application → App configuration: configures (evidence: `backend/main.py`)
- Dubbing API → Dubbing pipeline: delegates to (evidence: `backend/api/routers/dub_core.py`)
- Dubbing API → Model runtime: uses (evidence: `backend/api/routers/dub_core.py`)
- Dubbing API → Transcription: transcribes with (evidence: `backend/api/routers/dub_core.py`)
- Dubbing pipeline → Model runtime: uses (evidence: `backend/services/dub_pipeline.py`)
- Dubbing pipeline → Media processing: processes media (evidence: `backend/services/dub_pipeline.py`)
- Engine API → Speech backends: lists backends (evidence: `backend/api/routers/engines.py`)
- Engine API → Transcription: lists backends (evidence: `backend/api/routers/engines.py`)
- Engine API → User preferences: reads choices (evidence: `backend/api/routers/engines.py`)
- Model setup API → Speech backends: checks backends (evidence: `backend/api/routers/setup/models.py`)
- Model runtime → Device capabilities: routes by device (evidence: `backend/services/model_manager.py`)
- Background tasks → Job event store: persists events (evidence: `backend/core/tasks.py`)
- Background tasks → Failure reporting: formats failures (evidence: `backend/core/tasks.py`)
