Local TTS

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:

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

Optimizations (Linux/Windows)

tts_linux.py automatically enables:

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

Version

1.0.0 - See VERSION and package.json

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

| 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() |