Mlx Tts

MLX TTS (Qwen3-TTS)

High-quality local text-to-speech synthesis for Apple Silicon Macs using Qwen3-TTS via MLX framework. Optimized for Apple Neural Engine, runs entirely on-device.

Overview

Qwen3-TTS is a 1.7B parameter TTS model optimized for Apple Silicon (M1/M2/M3/M4) using the MLX framework. Features:

• Fast inference: Leverages Apple Neural Engine
• Prompt-based voice design: Describe the voice you want, no reference audio needed
• ASR support: Speech-to-text included
• Low memory: 8-bit quantized, runs on 16GB Mac
• Local only: No cloud, no API keys, fully private

When to Use

• Have an Apple Silicon Mac (M1/M2/M3/M4)
• Need high-quality TTS locally
• Want to design voices with text prompts (e.g., "a warm female voice, slightly soft")
• Need ASR (speech-to-text) capability
• Want fast inference with Apple Neural Engine

When NOT to Use

• Non-Mac system (Intel Mac or Windows/Linux) → Use other TTS solutions
• Need voice cloning from reference audio → Use other tools
• Less than 16GB RAM → May work but slower

Environment Setup

One-Command Install

brew install ffmpeg uv && uv tool install --force "mlx-audio" --prerelease=allow

Verify Installation

uv tool list | grep mlx
# Should show: mlx-audio v0.4.2

Model Download

Models auto-download on first run (~2GB total) to ~/.cache/huggingface/hub/:

• mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-8bit
• mlx-community/Qwen3-ASR-0.6B-bf16

For China users (accelerated download):

Option 1 - HuggingFace mirror:

export HF_ENDPOINT=https://hf-mirror.com

Option 2 - ModelScope (faster):

pip install modelscope

# Download TTS model
modelscope download \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-8bit \
  --local_dir ~/.cache/huggingface/hub/Qwen3-TTS

# Download ASR model
modelscope download \
  --model mlx-community/Qwen3-ASR-0.6B-bf16 \
  --local_dir ~/.cache/huggingface/hub/Qwen3-ASR

Usage

Basic TTS

mlx_audio.tts.generate \
  --text "你好，这是本地 TTS 测试" \
  --output-path ./output.wav

With Voice Design (Prompt-Based)

mlx_audio.tts.generate \
  --text "我是明日香" \
  --instruct "a confident teenage girl, flirtatious, seductive edge" \
  --output-path ./asuka.wav

Voice Prompt Examples

| Style | Prompt | |-------|--------| | 自信少女 | "a confident teenage girl, German-Japanese, EVA pilot" | | 温柔女声 | "a warm, gentle female voice, slightly soft" | | 磁性男声 | "a deep, masculine voice with authority" | | 儿童声音 | "a cheerful little child, about 5 years old" | | 新闻播报 | "a professional news anchor, clear and authoritative" | | 温柔妈妈 | "a caring mother, warm and soothing" | | 神秘低语 | "a mysterious whisper, soft and intimate, close to microphone" | | 激动演讲 | "an energetic public speaker, passionate and enthusiastic" | | 悲伤叙述 | "a melancholic storyteller, slow and reflective" |

Advanced Voice Design Tips

Delivery Instructions (Qwen3-TTS supports these):

• "speak slowly and clearly"
• "whisper gently"
• "speak with excitement"
• "calm and soothing tone"
• "fast-paced, energetic delivery"

Combine multiple descriptors:

--instruct "a warm female voice, slightly soft, speak slowly with gentle pauses"

Long Text TTS (Auto-Chunking)

For texts longer than ~500 characters, use auto-chunking to avoid memory issues:

Option 1: Manual script

# Split text into sentences and generate separately
python3  texts.txt  ~/voice_templates.txt 500 chars |
| Pronunciation issues | Use phonetic spelling or hyphens: "AI" → "A I", "COVID" → "Co-vid" |

### Performance Tips

1. **First run is slow**: Model downloads ~2GB on first use
2. **Keep sentences together**: Don't split mid-sentence
3. **Simple prompts work better**: Avoid overly complex instructions
4. **Use --verbose**: See detailed output for debugging

### Debug Mode

```bash
# Verbose output
mlx_audio.tts.generate --verbose --text "Hello" --output test.wav

# Check model cache
ls -la ~/.cache/huggingface/hub/ | grep mlx

# Check disk space
df -h ~/.cache/huggingface/

# Test with minimal text
mlx_audio.tts.generate --text "Test" --output /tmp/test.wav

References

• MLX-Audio GitHub
• Qwen3-TTS Model
• Qwen3-ASR Model
• ModelScope
• HuggingFace Mirror

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: renky1025
• Source: renky1025/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.