Features · Get Vocello · Command line · For developers
Vocello is a voice studio for your Mac and iPhone. Write a script, pick one of nine voices or describe a new one, and Vocello speaks it with the Qwen3-TTS model running on your own Apple Silicon. A command line brings the same engine to scripts and AI agents.
Three ways to make a voice
- Built-in Voice. Nine speakers in ten languages, with a delivery preset or a few words about how it should sound.
- Voice Design. Describe a voice ("a warm, clear narrator"), hear it, and save the ones you like to use again.
- Voice Cloning. Record or import a clip of a voice you own or have permission to use. Voice Cloning follows the reference voice, so the clip sets its character, and it waits for your consent in Settings.
Made for real projects
- Long scripts. Paste a whole chapter: Vocello plans it into segments that play one after another while the rest generates, then joins them into one file.
- Ten languages. Chinese, English, Japanese, Korean, German, French, Russian, Portuguese, Spanish and Italian, detected from your script. The interface comes in ten languages too, set apart from the speech language.
- Your library. Saved voices, and a searchable History of every take. Pin a take's seed from History to make it again with the same settings.
- Marked as AI-generated. From 3.0, every take Vocello generates carries an inaudible AudioSeal watermark and a note naming the model and mode. Reference clips you record or import are never marked.
- Up to date by itself. The Mac app is signed and notarized, and installs signed updates from Vocello > Check for Updates.
Performance
The speed figures come from a Vocello 3.0 development build on the benchmark Mac. Performance, measured shows them by mode and explains how they were taken.
Get Vocello
On a Mac: download Vocello, drag it to Applications, then install a voice model from Settings > Models & Files.
On iPhone: join the public beta on TestFlight. The beta runs Vocello 3.0, on the same engine as the Mac app, and the App Store release follows.
In Terminal: see Command line and AI agents.
| Platform | Requirements | Models |
|---|
| Mac | macOS 26.0 or newer, Apple Silicon, 8 GB RAM (16 GB or more for Quality and long projects) | Speed (4-bit) and Quality (8-bit) |
| Command line | macOS 26.0 or newer, Apple Silicon | Shared with the Mac app |
| iPhone | iPhone 15 Pro or newer, iOS 26.0 or newer | Speed (4-bit) |
Models download once from Hugging Face and are never bundled. Speed uses less memory and suits 8 GB Macs; Quality is a Mac option for 16 GB or more. → What's new in 3.0.0 · All releases
To upgrade from Vocello 2.x, install the new DMG by hand once: 2.x has no updater, and from 3.0 the app updates itself. History, saved voices and settings carry over, and the model manager offers an update for each model installed with 2.x. Vocello was called QwenVoice before 2.2.0, and old repository links redirect here. Macs on macOS 15 can use the legacy QwenVoice 1.2.3.
[!NOTE]
Take quality is not verified by human listening. Automated checks catch gross failures only (silence, a cut-off take, missing words, the wrong language), so a take can still carry a subtle defect, such as a swallowed syllable or a delivery that misses the requested style. Generate again for a different take. The release notes list the known limitations.
Command line and AI agents
vocello brings the Mac app's features to Terminal, sharing its models, saved voices and settings: every mode, long scripts, saved voices, models and History, with JSON output for scripts and an MCP server for AI agents.
Install it with the signed installer package, which asks for an administrator password, then, from a new Terminal window, check it, install the Built-in Voice Speed model (about 2 GB) and play a first take:
vocello --version
vocello models install pro_custom_speed
vocello custom --variant speed --text "The train left at dawn." --play
To let Claude Code generate speech with Vocello through the installer package's link:
claude mcp add --scope user vocello -- /usr/local/bin/vocello mcp
→ CLI reference: the folder install, updates, removal, the JSON contract and other MCP clients.
For developers
Vocello is a working reference for running a 1.7B-parameter text-to-speech model natively on Apple Silicon: Swift 6 with strict concurrency, a first-party MLX runtime, audio that streams with bounded memory, and a measurement discipline that ties every performance claim to a record.
How it works
One engine serves the Mac app, the iPhone app and the vocello command line. Every request takes one path from conditioning to a verified 24 kHz mono WAV: an engine actor owns the session, the Qwen3-TTS talker and code predictor sample codec frames, the Mimi decoder turns them into audio, and PCM streams back chunk by chunk to the player, a limiter, an atomic WAV writer and a quality check. → Architecture
Engineering highlights
→ Optimization ledger · Testing runbook · MLX guide
Performance, measured
Warm real-time factor (seconds of generation per second of audio, lower is faster) by mode and script length on the Mac mini M6 (16 GB), pooled from the most recent canonical records of one build (record 74f026be, a Vocello 3.0 development build measured on October 7, 2026, before the release's newer MLX, full-precision sampling and whole-script reading):
The speed figures pool warm takes of the Speed models from the canonical benchmark host. No benchmark record of the released 3.0.0 is published yet, so they are not a measurement of 3.0.0 itself. The 8 GB Mac mini M2 is the support floor: its records (the last canonical one, 379db820, measured warm RTF 0.53 to 0.82) form an earlier series that is never compared with the M6's. The memory figures come from that M2: streaming took the peak of the same take from about 8 GB to about 3 GB (benchmarks/OPTIMIZATION.md §F.1), and a 12-segment long-form project (smoke run 8f15c1fd) ended 1.1% below its starting footprint. The charts regenerate from the named records with scripts/generate_readme_charts.py.
→ Benchmark history · Benchmarking method
Build from source
You need full Xcode (the CI version is pinned in config/toolchain.json) on an Apple Silicon Mac with macOS 26 or newer, plus the pinned xcodegen, ripgrep and Python packages; New Mac setup walks through it.
git clone https://github.com/PowerBeef/Vocello.git
cd Vocello
./scripts/regenerate_project.sh
./scripts/build.sh build
project.yml generates the Xcode project, and the repository scripts are the build and test interface: scripts/dev.sh check runs the lint, contracts and tests your changes touch, and scripts/dev.sh ci runs what CI runs. ./scripts/build.sh cli builds a development vocello at build/vocello. Start with CONTRIBUTING.md; coding agents also read CLAUDE.md.
Sources/ the apps and the engine
QwenVoiceApp.swift macOS app (Views/, ViewModels/, Services/)
iOS/ iPhone app
QwenVoiceCore/ engine host: runtime factory, generation, model delivery
VocelloCLI/ the vocello command line
Packages/VocelloQwen3Core/ the owned Qwen3-TTS runtime on MLX, with its own tests
Tests/ unit and iPhone logic tests, Mac and iPhone UI tests
scripts/ build, test, benchmark and release lanes, and the README art
config/ machine-readable contracts: models, privacy, release, roadmap
benchmarks/ published benchmark records and the optimization ledger
website/ vocello.vercel.app (React and Vite)
docs/ architecture, references, audits, release notes
Dark-first, warm neutrals on a charcoal canvas, and one accent per mode. Liquid Glass stays on chrome and falls back to solid surfaces under Reduce Transparency and while audio generates. The tokens live in the app's theme and in website/src/tokens.css, and scripts/readme_art/render.sh draws this page's art from them.
| Token | Color | Use |
|---|
| Gold | | Built-in Voice, the brand accent |
| Lavender | | Voice Design |
| Terracotta | | Voice Cloning |
| Charcoal | | The canvas |
| Text | | Primary text |
Documentation
License and acknowledgements
Vocello is available under the MIT License. It builds on Qwen3-TTS, MLX, mlx-audio-swift and GRDB.swift. Third-party models and assets keep their own terms; see the third-party attributions and the runtime's notices.
