# powerbeef/vocello architecture

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

- Interactive diagram: https://gitdiagram.com/powerbeef/vocello
- Repository: https://github.com/powerbeef/vocello

## Overview

Vocello is a local-first voice-generation studio for macOS and iPhone, with a CLI. Its main workflow is to choose or prepare a voice, enter text and delivery settings, generate speech on-device, then listen to and manage the result. Major branches include voice design and cloning, long-form generation, model installation, local history, and export; iOS also documents a purchase gate for some exports. The README supports product-level flows, while sampled sources expose parts of the engine and model-management layers; unsampled implementation links are omitted.

Main entry points: [`Sources/QwenVoiceCore/GenerationSemantics.swift`](https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/GenerationSemantics.swift) (Generation request), [`Sources/QwenVoiceCore/GenerationOutputAdapter.swift`](https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/GenerationOutputAdapter.swift) (Generated audio), [`Sources/Views/Studio/MacStudioCanvas.swift`](https://github.com/powerbeef/vocello/blob/main/Sources/Views/Studio/MacStudioCanvas.swift) (Mac studio), [`Sources/iOSSupport/Services/DatabaseService.swift`](https://github.com/powerbeef/vocello/blob/main/Sources/iOSSupport/Services/DatabaseService.swift) (Generation history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Studio experience"]
  node_mac_studio["Mac studio"]
  node_ios_studio["iPhone studio<br/>[StudioScreen.swift]"]
  node_cli_generate["CLI generation"]
end

subgraph group_voice["Voice workflows"]
  node_voice_catalog["Voice catalog"]
  node_voice_design["Voice design"]
  node_voice_clone["Voice cloning"]
  node_consent["Clone consent"]
  node_prepared_voices["Saved voices"]
end

subgraph group_runtime["Generation runtime"]
  node_request["Generation request"]
  node_engine_store["Engine facade"]
  node_backend["Backend adapter"]
  node_mlx_engine["MLX engine<br/>[MLXTTSEngine.swift]"]
  node_native_runtime["Native runtime"]
  node_qwen_engine["Qwen model engine<br/>[Engine.swift]"]
  node_audio_result["Generated audio"]
end

subgraph group_library["Models and library"]
  node_model_manager["Model manager"]
  node_model_download["Model downloads"]
  node_history[("Generation history")]
  node_live_playback["Live playback"]
end

subgraph group_platform["Platform services"]
  node_audio_marking["Audio marking"]
  node_ios_export["iOS export gate"]
  node_export["Audio export<br/>[AudioService.swift]"]
end

node_mac_user(("Mac user"))
node_ios_user(("iPhone user"))
node_cli_user(("CLI caller"))

node_mac_user -->|"writes and selects"| node_mac_studio
node_ios_user -->|"writes and selects"| node_ios_studio
node_cli_user -->|"submits request"| node_cli_generate
node_mac_studio -->|"configures speech"| node_request
node_ios_studio -->|"configures speech"| node_request
node_cli_generate -->|"configures speech"| node_request
node_voice_catalog -->|"offers speakers"| node_mac_studio
node_voice_design -->|"supplies voice brief"| node_request
node_voice_clone -->|"requires consent"| node_consent
node_voice_clone -->|"saves reference"| node_prepared_voices
node_prepared_voices -->|"conditions voice"| node_request
node_mac_studio -->|"starts design"| node_voice_design
node_ios_studio -->|"starts cloning"| node_voice_clone
node_request -->|"submits generation"| node_engine_store
node_engine_store -->|"delegates calls"| node_backend
node_backend -->|"forwards operations"| node_mlx_engine
node_mlx_engine -->|"runs generation"| node_native_runtime
node_native_runtime -.->|"uses model runtime"| node_qwen_engine
node_qwen_engine -.->|"produces speech"| node_audio_result
node_model_manager -->|"downloads artifacts"| node_model_download
node_model_download -.->|"installs model assets"| node_voice_catalog
node_request -->|"records generation"| node_history
node_audio_result -->|"streams for listening"| node_live_playback
node_audio_result -->|"keeps local result"| node_history
node_audio_result -->|"marks finished take"| node_audio_marking
node_history -->|"exports selected audio"| node_export
node_ios_export -->|"authorizes paid export"| node_export
node_request -->|"stores long-form segments"| node_history

click node_mac_studio "https://github.com/powerbeef/vocello/blob/main/Sources/Views/Studio/MacStudioCanvas.swift"
click node_ios_studio "https://github.com/powerbeef/vocello/blob/main/Sources/iOS/Studio/StudioScreen.swift"
click node_cli_generate "https://github.com/powerbeef/vocello/blob/main/Sources/VocelloCLI/GenerateCommand.swift"
click node_voice_catalog "https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/ProductionModelCatalog.swift"
click node_voice_design "https://github.com/powerbeef/vocello/blob/main/Sources/Views/Studio/MacVoiceDesignScreen.swift"
click node_voice_clone "https://github.com/powerbeef/vocello/blob/main/Sources/Views/Studio/MacVoiceCloningScreen.swift"
click node_consent "https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/VoiceCloningConsentPolicy.swift"
click node_prepared_voices "https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/PreparedVoiceRepository.swift"
click node_request "https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/GenerationSemantics.swift"
click node_engine_store "https://github.com/powerbeef/vocello/blob/main/Sources/iOS/TTSEngineStore.swift"
click node_backend "https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/AnyTTSEngineBackend.swift"
click node_mlx_engine "https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/MLXTTSEngine.swift"
click node_native_runtime "https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/NativeEngineRuntime.swift"
click node_qwen_engine "https://github.com/powerbeef/vocello/blob/main/Packages/VocelloQwen3Core/Sources/VocelloQwen3Core/Engine.swift"
click node_audio_result "https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/GenerationOutputAdapter.swift"
click node_model_manager "https://github.com/powerbeef/vocello/blob/main/Sources/ViewModels/ModelManagerViewModel.swift"
click node_model_download "https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/HuggingFaceDownloader.swift"
click node_history "https://github.com/powerbeef/vocello/blob/main/Sources/iOSSupport/Services/DatabaseService.swift"
click node_live_playback "https://github.com/powerbeef/vocello/blob/main/Sources/SharedSupport/Services/LiveStreamingPlaybackEngine.swift"
click node_audio_marking "https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/AudioPublicationMarking.swift"
click node_ios_export "https://github.com/powerbeef/vocello/blob/main/Sources/iOS/Commerce/IOSExportGate.swift"
click node_export "https://github.com/powerbeef/vocello/blob/main/Sources/Services/AudioService.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_mac_studio,node_ios_studio,node_cli_generate,node_mac_user,node_ios_user toneBlue
class node_voice_catalog,node_voice_design,node_voice_clone,node_consent,node_prepared_voices toneAmber
class node_request,node_engine_store,node_backend,node_mlx_engine,node_native_runtime,node_qwen_engine,node_audio_result toneMint
class node_model_manager,node_model_download,node_history,node_live_playback toneRose
class node_audio_marking,node_ios_export,node_export,node_cli_user toneIndigo
```

## Components

### Studio experience

- [Mac studio](https://github.com/powerbeef/vocello/blob/main/Sources/Views/Studio/MacStudioCanvas.swift): `Sources/Views/Studio/MacStudioCanvas.swift`
- [iPhone studio](https://github.com/powerbeef/vocello/blob/main/Sources/iOS/Studio/StudioScreen.swift): `Sources/iOS/Studio/StudioScreen.swift`
- [CLI generation](https://github.com/powerbeef/vocello/blob/main/Sources/VocelloCLI/GenerateCommand.swift): `Sources/VocelloCLI/GenerateCommand.swift`

### Voice workflows

- [Voice catalog](https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/ProductionModelCatalog.swift): `Sources/QwenVoiceCore/ProductionModelCatalog.swift`
- [Voice design](https://github.com/powerbeef/vocello/blob/main/Sources/Views/Studio/MacVoiceDesignScreen.swift): `Sources/Views/Studio/MacVoiceDesignScreen.swift`
- [Voice cloning](https://github.com/powerbeef/vocello/blob/main/Sources/Views/Studio/MacVoiceCloningScreen.swift): `Sources/Views/Studio/MacVoiceCloningScreen.swift`
- [Clone consent](https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/VoiceCloningConsentPolicy.swift): `Sources/QwenVoiceCore/VoiceCloningConsentPolicy.swift`
- [Saved voices](https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/PreparedVoiceRepository.swift): `Sources/QwenVoiceCore/PreparedVoiceRepository.swift`

### Generation runtime

- [Generation request](https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/GenerationSemantics.swift): `Sources/QwenVoiceCore/GenerationSemantics.swift`
- [Engine facade](https://github.com/powerbeef/vocello/blob/main/Sources/iOS/TTSEngineStore.swift): `Sources/iOS/TTSEngineStore.swift`
- [Backend adapter](https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/AnyTTSEngineBackend.swift): `Sources/QwenVoiceCore/AnyTTSEngineBackend.swift`
- [MLX engine](https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/MLXTTSEngine.swift): `Sources/QwenVoiceCore/MLXTTSEngine.swift`
- [Native runtime](https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/NativeEngineRuntime.swift): `Sources/QwenVoiceCore/NativeEngineRuntime.swift`
- [Qwen model engine](https://github.com/powerbeef/vocello/blob/main/Packages/VocelloQwen3Core/Sources/VocelloQwen3Core/Engine.swift): `Packages/VocelloQwen3Core/Sources/VocelloQwen3Core/Engine.swift`
- [Generated audio](https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/GenerationOutputAdapter.swift): `Sources/QwenVoiceCore/GenerationOutputAdapter.swift`

### Models and library

- [Model manager](https://github.com/powerbeef/vocello/blob/main/Sources/ViewModels/ModelManagerViewModel.swift): `Sources/ViewModels/ModelManagerViewModel.swift`
- [Model downloads](https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/HuggingFaceDownloader.swift): `Sources/QwenVoiceCore/HuggingFaceDownloader.swift`
- [Generation history](https://github.com/powerbeef/vocello/blob/main/Sources/iOSSupport/Services/DatabaseService.swift): `Sources/iOSSupport/Services/DatabaseService.swift`
- [Live playback](https://github.com/powerbeef/vocello/blob/main/Sources/SharedSupport/Services/LiveStreamingPlaybackEngine.swift): `Sources/SharedSupport/Services/LiveStreamingPlaybackEngine.swift`

### Platform services

- [Audio marking](https://github.com/powerbeef/vocello/blob/main/Sources/QwenVoiceCore/AudioPublicationMarking.swift): `Sources/QwenVoiceCore/AudioPublicationMarking.swift`
- [iOS export gate](https://github.com/powerbeef/vocello/blob/main/Sources/iOS/Commerce/IOSExportGate.swift): `Sources/iOS/Commerce/IOSExportGate.swift`
- [Audio export](https://github.com/powerbeef/vocello/blob/main/Sources/Services/AudioService.swift): `Sources/Services/AudioService.swift`

### Other components

- **Mac user**
- **iPhone user**
- **CLI caller**

## Connections

- Mac user → Mac studio: writes and selects (evidence: `README.md`)
- iPhone user → iPhone studio: writes and selects (evidence: `README.md`)
- CLI caller → CLI generation: submits request (evidence: `README.md`)
- Mac studio → Generation request: configures speech (evidence: `README.md`)
- iPhone studio → Generation request: configures speech (evidence: `README.md`)
- CLI generation → Generation request: configures speech (evidence: `README.md`)
- Voice catalog → Mac studio: offers speakers (evidence: `README.md`)
- Voice design → Generation request: supplies voice brief (evidence: `README.md`)
- Voice cloning → Clone consent: requires consent (evidence: `README.md`)
- Voice cloning → Saved voices: saves reference (evidence: `README.md`)
- Saved voices → Generation request: conditions voice (evidence: `README.md`)
- Mac studio → Voice design: starts design (evidence: `README.md`)
- iPhone studio → Voice cloning: starts cloning (evidence: `README.md`)
- Generation request → Engine facade: submits generation (evidence: `README.md`)
- Engine facade → Backend adapter: delegates calls (evidence: `Sources/iOS/TTSEngineStore.swift`)
- Backend adapter → MLX engine: forwards operations (evidence: `Sources/QwenVoiceCore/AnyTTSEngineBackend.swift`)
- MLX engine → Native runtime: runs generation (evidence: `Sources/QwenVoiceCore/MLXTTSEngine.swift`)
- Native runtime → Qwen model engine: uses model runtime
- Qwen model engine → Generated audio: produces speech
- Model manager → Model downloads: downloads artifacts (evidence: `Sources/ViewModels/ModelManagerViewModel.swift`)
- Model downloads → Voice catalog: installs model assets (evidence: `Sources/QwenVoiceCore/ProductionModelCatalog.swift`)
- Generation request → Generation history: records generation (evidence: `README.md`)
- Generated audio → Live playback: streams for listening (evidence: `README.md`)
- Generated audio → Generation history: keeps local result (evidence: `README.md`)
- Generated audio → Audio marking: marks finished take (evidence: `README.md`)
- Generation history → Audio export: exports selected audio (evidence: `README.md`)
- iOS export gate → Audio export: authorizes paid export (evidence: `README.md`)
- Generation request → Generation history: stores long-form segments (evidence: `README.md`)
