Architecture · Features · Dependencies

Vocello Interactive project map for the QwenVoice monorepo

Local-first text-to-speech on Apple Silicon. One engine core (QwenVoiceCore / MLXTTSEngine) hosted three ways: macOS out-of-process XPC, iOS in-process, and a headless CLI. Model weights download from Hugging Face; only metadata, privacy resources, UI assets, and iOS voice previews are bundled.

2.4.0 · build 23 macOS 26+ · Apple Silicon iOS 26+ · on-device capable Swift 6 · Xcode 26 MLX Qwen3-TTS 1.7B Release-only config

Built-in Voice

Built-in speakers with controllable delivery. Nine voices across English, Chinese, Japanese, and Korean.

Voice Design

Invent a voice from a natural-language brief. Save the result as a Clone reference.

Voice Cloning

Speak in a voice from a 10–20 s reference clip. Delivery follows the reference; emotion-bank personas add a delivery choice between verified references.

01 · Runtime

Three hosts, one engine

All hosts share MLXTTSEngine built by NativeRuntimeFactory. They differ only in where the engine lives and how the UI talks to it.

macOS · Vocello.app

out-of-process XPC

SwiftUI app links the full XPC stack. Engine runs in QwenVoiceEngineService for crash isolation and memory containment.

  • Module QwenVoice
  • Bundle com.qwenvoice.app
  • Sidebar: Custom · Design · Clone · History · Voices · Settings
  • Speed + Quality variants

iOS · Vocello

in-process MLX

SwiftUI app hosts MLXTTSEngine in-process through its platform store. It links the shared engine/packages but deliberately excludes the macOS XPC frameworks.

  • Module QVoiceiOS
  • Bundle com.patricedery.vocello
  • Tabs: Studio · Voices · History · Settings
  • Speed only · App Group storage · Files reference import

CLI · vocello

in-process headless

Same engine contract for generate, batch, bench, voices, and model install. Built via ./scripts/build.sh cli.

  • Module VocelloCLI
  • Commands: generate · custom/design/clone · batch · bench
  • Streaming synthesis by default · event reporting, no live audio player
  • Not shipped in the DMG

project.yml is source of truth

Never hand-edit project.pbxproj. Regenerate with ./scripts/regenerate_project.sh.

Release-only config

No Debug config. Runtime debug via DebugMode.isEnabled / QWENVOICE_DEBUG=1.

MLX pins in lockstep

mlx-swift 0.31.6 and mlx-swift-lm 3.31.4 move together. No Core ML pivot.

iOS = physical device only

Gates never use Simulator. XCUITest drives the paired physical iPhone.

02 · Product

Features across platforms

Three generation modes share one chrome. Library surfaces (Voices, History, Models) are first-class. Platform deltas are intentional, not incomplete ports.

Show:
Feature macOS iOS CLI

03 · Modules

Target dependency graph

14 Swift targets from project.yml; the graph shows ten build-graph participants. The four UI/logic test bundles are omitted; VocelloiOSCandidateUITests is standalone and never builds the production app. Click a node for details. Hover highlights connected edges. Layering rule: BackendCore ← Core ← apps / XPC / CLI.

App / CLI Cross-platform FW macOS XPC stack SPM / packages Tests
Vocello build dependency graphTen Xcode graph participants and their direct package dependencies; UI and logic test bundles are omitted. Select a node for exact dependencies and key paths.

04 · Generation

Synthesis pipeline

End-to-end path inside MLXTTSEngine → VocelloQwen3Engine → GenerationOutputAdapter. Output is 24 kHz mono Int16 WAV with audio QC telemetry.

macOS request path (XPC)

SwiftUI View / Coordinator
TTSEngineStore (QwenVoiceNative)
XPCNativeEngineClient → NSXPCConnection
EngineServiceHost (XPC process)
MLXTTSEngine → events via handleEvent
GenerationChunkBroker → UI / player

iOS request path (in-process)

Studio View / StudioGenerationCoordinator
TTSEngineStore (Sources/iOS)
MLXTTSEngine (same process)
GenerationEvent stream → inline player
GenerationPersistence → App Group DB

05 · Systems

Downloads, persistence, telemetry & release

Generation is only one lifecycle. These companion flows explain how models arrive, how local artifacts persist, how diagnostics join, and how releases leave the repository.

06 · Codebase

Source layout

Sources/ is the product source of truth. SharedSupport compiles into both apps; the XPC stack is macOS-only; iOS has a parallel support layer under iOSSupport/.

07 · Dependencies

SPM, owned runtime & external dependencies

Exact pins in project.yml and Package.resolved. VocelloQwen3Core is the owned Qwen3-TTS core package under Packages/.

Apple frameworks and native services

External systems

08 · Tooling

Scripts, tests & CI

Development is Codex + scripts-first; optional MCP tools assist only when callable. Native builds are the typecheck. Commits, pushes, pull requests, ordinary merges, CI, and release packaging use deterministic checks only. XCUITest smoke, benchmark, and perf lanes are explicit frontend acceptance work.

macOS development

./scripts/check_project_inputs.sh
scripts/macos_test.sh test
./scripts/build.sh build

iOS development

./scripts/check_project_inputs.sh
./scripts/build_foundation_targets.sh ios

XCUITest smoke and benchmark lanes remain available for explicit frontend acceptance. They never block signing, notarization, archive creation, or artifact upload.

09 · Data

Model contract & storage

Schema lives in Sources/Resources/qwenvoice_contract.json. Three modes × Speed (4-bit) / Quality (8-bit). iOS downloads Speed only.

Built-in speakers

Language semantics

Storage and privacy

10 · Ship

Website & distribution

macOS ships via notarized GitHub Release DMG. iOS is on-device-capable on main with an optional TestFlight CI lane. Marketing site deploys from website/.

macOS release

Signed Developer ID + notarized + stapled DMG (Vocello-macos26.dmg) via scripts/release.sh and .github/workflows/release.yml, gated by deterministic release-readiness and artifact checks.

Shipped · 2.4.0

iOS distribution

Public TestFlight beta is live via the public join link (build 23 carries v2.4.0). Builds come from the manual CI job (archive_ios) gated by signing, entitlement, archive, catalog, and artifact checks. App Store listing still needs metadata, screenshots, and submission.

TestFlight beta · live

Marketing site

React 19 + Vite 8 single page at website/. Deployed on Vercel with cookieless Web Analytics. Brand tokens: gold / lavender / terracotta.

vocello.vercel.app
External

Services the product touches

Hugging Face (model download), GitHub Releases (DMG), Apple Notarization / ASC API, optional TestFlight, Vercel (site). No cloud TTS. No bundled weights. No Python runtime in the shippable app.

Hugging Face GitHub Releases notarytool App Store Connect Vercel CoreDevice
Docs index

Where to go deeper

Architecture Agent onboarding macOS app iOS app CLI Testing Language bench Development progress