# cosmicrealm/voicestudio architecture

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

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

## Overview

Voice Studio is a local macOS voice-creation workspace. Users configure the local runtime and models, then create audio through built-in, cloned, designed, or multi-role workflows; they can review playback and export results. Script Studio normalizes role-tagged text and prepares synthesis input, while the app view model coordinates generation and persistent workspace state. Separate product branches cover DeepSeek-assisted rewriting, voice-library management, and audio merging. The README documents these capabilities; some implementations are unsampled, so only documented links are shown for them.

Main entry points: [`Sources/MacQwenVoice/StudioViewModel.swift`](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/StudioViewModel.swift) (Studio coordinator), [`Sources/MacQwenVoice/ContentView.swift`](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/ContentView.swift) (Workspace navigation), [`Sources/MacQwenVoice/Views/ScriptStudioView.swift`](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/ScriptStudioView.swift) (Script Studio), [`Sources/MacQwenVoice/BackendJSONClient.swift`](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/BackendJSONClient.swift) (Backend client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop application"]
  node_app["App shell"]
  node_workspace_ui["Workspace navigation<br/>[ContentView.swift]"]
  node_studio_vm["Studio coordinator"]
end

subgraph group_creation["Voice creation"]
  node_premium["Premium voices"]
  node_cloning["Voice cloning"]
  node_design["Voice design"]
  node_voice_library["Saved voice library<br/>[Domain.swift]"]
end

subgraph group_script["Script and dialogue"]
  node_script_view["Script Studio"]
  node_script_workflow["Workflow and prompts"]
  node_role_parser["Role text parsing"]
  node_text_segments["Text segmentation"]
  node_rewrite["Dialogue rewrite"]
  node_results["Generation results"]
  node_playback["Audio playback"]
  node_audio_tools["Audio merge tools"]
end

subgraph group_runtime["Runtime and workspace"]
  node_runtime_ui["Runtime management"]
  node_backend_client["Backend client"]
  node_backend["Local inference backend<br/>[server.py]"]
  node_environment["Runtime environment"]
  node_database[("Workspace database<br/>[AppDatabase.swift]")]
  node_workspace_paths["Workspace paths<br/>[AppPaths.swift]"]
end

node_user(("User"))
node_deepseek{{"DeepSeek service"}}

node_user -->|"opens"| node_app
node_app -->|"shows"| node_workspace_ui
node_workspace_ui -->|"uses"| node_studio_vm
node_workspace_ui -->|"routes to"| node_script_view
node_workspace_ui -->|"routes to"| node_premium
node_workspace_ui -->|"routes to"| node_cloning
node_workspace_ui -->|"routes to"| node_design
node_workspace_ui -->|"routes to"| node_rewrite
node_workspace_ui -->|"routes to"| node_runtime_ui
node_workspace_ui -->|"routes to"| node_audio_tools
node_premium -->|"requests generation"| node_studio_vm
node_cloning -->|"manages voices"| node_studio_vm
node_design -->|"requests design"| node_studio_vm
node_script_view -->|"submits script"| node_studio_vm
node_script_view -->|"configures"| node_script_workflow
node_script_workflow -.->|"supports role scripts"| node_role_parser
node_role_parser -->|"segments text"| node_text_segments
node_rewrite -->|"requests rewrite"| node_studio_vm
node_studio_vm -->|"sends rewrite request"| node_deepseek
node_studio_vm -->|"calls backend"| node_backend_client
node_backend_client -->|"launches script"| node_backend
node_backend_client -->|"configures process"| node_environment
node_runtime_ui -->|"manages models"| node_studio_vm
node_studio_vm -->|"persists workspace"| node_database
node_studio_vm -->|"uses paths"| node_workspace_paths
node_studio_vm -.->|"stores voice profiles"| node_voice_library
node_studio_vm -.->|"provides results"| node_results
node_results -->|"offers playback"| node_playback
node_studio_vm -->|"merges audio"| node_audio_tools
node_studio_vm -.->|"provides generated audio"| node_playback

click node_app "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/MacQwenVoiceApp.swift"
click node_workspace_ui "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/ContentView.swift"
click node_studio_vm "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/StudioViewModel.swift"
click node_premium "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/PremiumVoicesView.swift"
click node_cloning "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/ClonedVoicesView.swift"
click node_design "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/VoiceDesignView.swift"
click node_voice_library "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoiceCore/Domain.swift"
click node_script_view "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/ScriptStudioView.swift"
click node_script_workflow "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoiceCore/ScriptStudioWorkflow.swift"
click node_role_parser "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoiceCore/SpeakerTaggedTextNormalizer.swift"
click node_text_segments "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoiceCore/TextSegmenter.swift"
click node_rewrite "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/ScriptRewriteView.swift"
click node_results "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/GenerationResultsPanel.swift"
click node_playback "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/AudioPlayButton.swift"
click node_audio_tools "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/VoiceToolsView.swift"
click node_runtime_ui "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/ModelRuntimeView.swift"
click node_backend_client "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/BackendJSONClient.swift"
click node_backend "https://github.com/cosmicrealm/voicestudio/blob/main/backend/server.py"
click node_environment "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/VoiceStudioRuntimeEnvironment.swift"
click node_database "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoiceCore/AppDatabase.swift"
click node_workspace_paths "https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoiceCore/AppPaths.swift"

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_app,node_workspace_ui,node_studio_vm,node_user toneBlue
class node_premium,node_cloning,node_design,node_voice_library toneAmber
class node_script_view,node_script_workflow,node_role_parser,node_text_segments,node_rewrite,node_results,node_playback,node_audio_tools toneMint
class node_runtime_ui,node_backend_client,node_backend,node_environment,node_database,node_workspace_paths toneRose
class node_deepseek toneIndigo
```

## Components

### Desktop application

- [App shell](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/MacQwenVoiceApp.swift): `Sources/MacQwenVoice/MacQwenVoiceApp.swift`
- [Workspace navigation](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/ContentView.swift): `Sources/MacQwenVoice/ContentView.swift`
- [Studio coordinator](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/StudioViewModel.swift): `Sources/MacQwenVoice/StudioViewModel.swift`

### Voice creation

- [Premium voices](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/PremiumVoicesView.swift): `Sources/MacQwenVoice/Views/PremiumVoicesView.swift`
- [Voice cloning](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/ClonedVoicesView.swift): `Sources/MacQwenVoice/Views/ClonedVoicesView.swift`
- [Voice design](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/VoiceDesignView.swift): `Sources/MacQwenVoice/Views/VoiceDesignView.swift`
- [Saved voice library](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoiceCore/Domain.swift): `Sources/MacQwenVoiceCore/Domain.swift`

### Script and dialogue

- [Script Studio](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/ScriptStudioView.swift): `Sources/MacQwenVoice/Views/ScriptStudioView.swift`
- [Workflow and prompts](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoiceCore/ScriptStudioWorkflow.swift): `Sources/MacQwenVoiceCore/ScriptStudioWorkflow.swift`
- [Role text parsing](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoiceCore/SpeakerTaggedTextNormalizer.swift): `Sources/MacQwenVoiceCore/SpeakerTaggedTextNormalizer.swift`
- [Text segmentation](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoiceCore/TextSegmenter.swift): `Sources/MacQwenVoiceCore/TextSegmenter.swift`
- [Dialogue rewrite](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/ScriptRewriteView.swift): `Sources/MacQwenVoice/Views/ScriptRewriteView.swift`
- [Generation results](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/GenerationResultsPanel.swift): `Sources/MacQwenVoice/Views/GenerationResultsPanel.swift`
- [Audio playback](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/AudioPlayButton.swift): `Sources/MacQwenVoice/Views/AudioPlayButton.swift`
- [Audio merge tools](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/VoiceToolsView.swift): `Sources/MacQwenVoice/Views/VoiceToolsView.swift`

### Runtime and workspace

- [Runtime management](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/Views/ModelRuntimeView.swift): `Sources/MacQwenVoice/Views/ModelRuntimeView.swift`
- [Backend client](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/BackendJSONClient.swift): `Sources/MacQwenVoice/BackendJSONClient.swift`
- [Local inference backend](https://github.com/cosmicrealm/voicestudio/blob/main/backend/server.py): `backend/server.py`
- [Runtime environment](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoice/VoiceStudioRuntimeEnvironment.swift): `Sources/MacQwenVoice/VoiceStudioRuntimeEnvironment.swift`
- [Workspace database](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoiceCore/AppDatabase.swift): `Sources/MacQwenVoiceCore/AppDatabase.swift`
- [Workspace paths](https://github.com/cosmicrealm/voicestudio/blob/main/Sources/MacQwenVoiceCore/AppPaths.swift): `Sources/MacQwenVoiceCore/AppPaths.swift`

### Other components

- **User**
- **DeepSeek service**

## Connections

- User → App shell: opens (evidence: `README.md`)
- App shell → Workspace navigation: shows (evidence: `Sources/MacQwenVoice/MacQwenVoiceApp.swift`)
- Workspace navigation → Studio coordinator: uses (evidence: `Sources/MacQwenVoice/ContentView.swift`)
- Workspace navigation → Script Studio: routes to (evidence: `Sources/MacQwenVoice/ContentView.swift`)
- Workspace navigation → Premium voices: routes to (evidence: `Sources/MacQwenVoice/ContentView.swift`)
- Workspace navigation → Voice cloning: routes to (evidence: `Sources/MacQwenVoice/ContentView.swift`)
- Workspace navigation → Voice design: routes to (evidence: `Sources/MacQwenVoice/ContentView.swift`)
- Workspace navigation → Dialogue rewrite: routes to (evidence: `Sources/MacQwenVoice/ContentView.swift`)
- Workspace navigation → Runtime management: routes to (evidence: `Sources/MacQwenVoice/ContentView.swift`)
- Workspace navigation → Audio merge tools: routes to (evidence: `Sources/MacQwenVoice/ContentView.swift`)
- Premium voices → Studio coordinator: requests generation (evidence: `Sources/MacQwenVoice/Views/PremiumVoicesView.swift`)
- Voice cloning → Studio coordinator: manages voices (evidence: `Sources/MacQwenVoice/Views/ClonedVoicesView.swift`)
- Voice design → Studio coordinator: requests design (evidence: `Sources/MacQwenVoice/Views/VoiceDesignView.swift`)
- Script Studio → Studio coordinator: submits script (evidence: `Sources/MacQwenVoice/Views/ScriptStudioView.swift`)
- Script Studio → Workflow and prompts: configures (evidence: `Sources/MacQwenVoice/Views/ScriptStudioView.swift`)
- Workflow and prompts → Role text parsing: supports role scripts
- Role text parsing → Text segmentation: segments text (evidence: `Sources/MacQwenVoiceCore/SpeakerTaggedTextNormalizer.swift`)
- Dialogue rewrite → Studio coordinator: requests rewrite (evidence: `Sources/MacQwenVoice/Views/ScriptRewriteView.swift`)
- Studio coordinator → DeepSeek service: sends rewrite request (evidence: `README.md`)
- Studio coordinator → Backend client: calls backend (evidence: `Sources/MacQwenVoice/StudioViewModel.swift`)
- Backend client → Local inference backend: launches script (evidence: `Sources/MacQwenVoice/BackendJSONClient.swift`)
- Backend client → Runtime environment: configures process (evidence: `Sources/MacQwenVoice/BackendJSONClient.swift`)
- Runtime management → Studio coordinator: manages models (evidence: `Sources/MacQwenVoice/Views/ModelRuntimeView.swift`)
- Studio coordinator → Workspace database: persists workspace (evidence: `Sources/MacQwenVoice/StudioViewModel.swift`)
- Studio coordinator → Workspace paths: uses paths (evidence: `Sources/MacQwenVoice/StudioViewModel.swift`)
- Studio coordinator → Saved voice library: stores voice profiles
- Studio coordinator → Generation results: provides results (evidence: `Sources/MacQwenVoice/Views/GenerationResultsPanel.swift`)
- Generation results → Audio playback: offers playback (evidence: `Sources/MacQwenVoice/Views/GenerationResultsPanel.swift`)
- Studio coordinator → Audio merge tools: merges audio (evidence: `README.md`)
- Studio coordinator → Audio playback: provides generated audio (evidence: `Sources/MacQwenVoice/Views/AudioPlayButton.swift`)