Local TTS with Qwen3-TTS

Privacy-First | Offline | High-Quality | Natural Real Voices

Local text-to-speech synthesis using Qwen3-TTS models. Your text never leaves your machine.

Why Local TTS?

Unlike cloud TTS (Google, AWS, Azure), local-tts ensures:

• Zero data transmission - 100% on-device processing
• Works offline - No network required
• No API keys - No external dependencies
• GDPR/HIPAA friendly - Simplified compliance

See privacy & security details.

Platform Overview

Platform	Backend	Installation	Best For
macOS (Apple Silicon)	mlx_audio	pip install mlx-audio	M1/M2/M3/M4 Macs
Linux/Windows	qwen-tts	pip install qwen-tts	CUDA GPUs

Quick Start

macOS

pip install mlx-audio
brew install ffmpeg

# Natural female voice
python -m mlx_audio.tts.generate \
    --text "Hello world" \
    --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit \
    --voice Chelsie

Linux/Windows

pip install qwen-tts

# With optimizations (FlashAttention, bfloat16, auto-device)
python scripts/tts_linux.py "Hello world" --female

Key Concepts

--voice vs --instruct (Important)

Model	--voice	--instruct	Notes
CustomVoice	Select preset voice	Add style/emotion	Can use together - voice + style control
VoiceDesign	N/A	Create voice from description	--instruct only
Base	N/A	N/A	For voice cloning with --ref_audio

CustomVoice with style control:

python -m mlx_audio.tts.generate \
    --text "Hello there!" \
    --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit \
    --voice Serena \
    --instruct "excited and enthusiastic"

9 Preset Voices (Open Source CustomVoice)

Voice	Gender	Language	Character
Chelsie	Female	English (American)	Gentle, empathetic
Serena	Female	English	Warm, gentle
Ono Anna	Female	Japanese	Playful
Sohee	Female	Korean	Warm
Aiden	Male	English (American)	Sunny
Dylan	Male	English	Natural
Eric	Male	English	Real
Ryan	Male	English	Natural
Uncle Fu	Male	Chinese	Youthful Beijing

Defaults: Female=Serena, Male=Aiden

Usage Examples

CustomVoice (Preset Voices)

# Natural female
python -m mlx_audio.tts.generate \
    --text "Your text" --voice Serena --lang_code en \
    --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit

# Real male
python -m mlx_audio.tts.generate \
    --text "Your text" --voice Aiden --lang_code en \
    --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit

VoiceDesign (Text-Based)

python -m mlx_audio.tts.generate \
    --text "Hello" \
    --model mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-8bit \
    --instruct "A warm female voice, professional and clear"

Long Text Generation

For long text, increase --max_tokens and enable --join_audio (macOS/MLX only):

python -m mlx_audio.tts.generate \
    --text "Your very long text here..." \
    --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit \
    --voice Serena \
    --max_tokens 4096 \
    --join_audio \
    --output long_audio.wav

Voice Cloning

python -m mlx_audio.tts.generate \
    --text "Cloned voice speaking" \
    --model mlx-community/Qwen3-TTS-12Hz-1.7B-Base-8bit \
    --ref_audio sample.wav --ref_text "Sample transcript"

Parameters

Parameter	Description	Values
--text	Text to speak	Required
--model	Model ID	See table below
--voice	Preset voice (CustomVoice)	Chelsie, Serena, Aiden, Ryan...
--instruct	Voice description (VoiceDesign) or style/emotion (CustomVoice)	e.g., "excited", "calm", "professional"
--speed	Speaking rate	0.5-2.0 (default: 1.0)
--pitch	Voice pitch	0.5-2.0 (default: 1.0)
--lang_code	Language	en, cn, ja, ko, de, fr...
--ref_audio	Reference for cloning	File path
--output	Output file	Path (auto-generated if omitted)
--max_tokens	Max generation tokens	Integer (default: 2048) - Increase for long text
--join_audio	Merge audio segments	true (default) or false - Recommended for long text

Models

Model	Size	Purpose
Qwen3-TTS-12Hz-1.7B-CustomVoice	1.7B	9 preset voices + style control
Qwen3-TTS-12Hz-1.7B-VoiceDesign	1.7B	Text-based voice creation
Qwen3-TTS-12Hz-1.7B-Base	1.7B	Voice cloning
Qwen3-TTS-12Hz-0.6B-*	0.6B	Lightweight versions

macOS: Add mlx-community/ prefix (e.g., mlx-community/Qwen3-TTS-12Hz-1.7B-Base-8bit)

Scripts

• scripts/tts_macos.py - macOS wrapper
• scripts/tts_linux.py - Linux/Windows wrapper with optimizations

Optimizations (Linux/Windows)

tts_linux.py automatically enables:

• FlashAttention - Faster, less memory
• bfloat16 - Better precision
• Auto device - CUDA → CPU fallback
• Mixed precision - Speed + quality

Troubleshooting

Issue	Solution
macOS: Model not found	Use mlx-community/ prefix
macOS: Audio format	brew install ffmpeg
Linux: CUDA OOM	Use 0.6B models
Linux: Slow	Check CUDA: torch.cuda.is_available()

References

• macOS Details
• Linux/Windows Details
• Privacy & Security

Version

1.0.0 - See VERSION and package.json