Text-to-speech using Qwen3-TTS CustomVoice model, running locally on Apple Silicon via MLX.
Overview
- Model:
mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-4bit(4-bit quantized, ~600MB) - Runtime: MLX (Apple Silicon GPU acceleration)
- Speakers: 9 built-in voices
- Output: WAV audio files
- Auto-cleanup: Files older than 24 hours are removed automatically
First-time Deployment
Prerequisites
- macOS with Apple Silicon (M1/M2/M3/M4)
- Python 3.10+
1. Create virtual environment
cd /path/to/skills/skills/qwen-tts
python3 -m venv venv
source venv/bin/activate
2. Install dependencies
The model is downloaded from the ModelScope mirror (faster in China):
pip install -r scripts/requirements.txt
3. Pre-download model (optional)
The model is automatically downloaded on first run. To download in advance:
source venv/bin/activate
export HF_ENDPOINT="https://hf-mirror.com"
python3 -c "from mlx_audio.tts.utils import load_model; load_model('mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-4bit')"
4. Verify
source venv/bin/activate
python3 scripts/tts.py "你好，这是一段测试语音。" --output /tmp
# Should produce a WAV file in /tmp/
Troubleshooting
| Problem | Solution |
|---|---|
ModuleNotFoundError: mlx |
Confirm you are using an Apple Silicon Mac; MLX does not support Intel Macs |
| Model download is slow | Set export HF_ENDPOINT="https://hf-mirror.com" |
| Insufficient memory | The 4-bit model requires about 1.5GB of memory; close other large applications |
| No audio output | Check whether the output file is 0 bytes; the text may be too short |
Configuration
⚠️ The following are example default values. Modify speaker and instruct according to your actual use case.
- Speaker:
Serena(Example) - Instruct:
撒娇语气(Example) - Language:
Chinese - Speed:
1.0
Available Speakers
| Speaker | Language |
|---|---|
Serena |
Chinese |
Vivian |
Chinese |
Uncle_Fu |
Chinese |
Eric |
Chinese |
Dylan |
Chinese |
Ryan |
English |
Aiden |
English |
Ono_Anna |
Japanese |
Sohee |
Korean |
Available Instructs (emotion/style)
撒娇语气— coquettish冷静分析— calm analysis惊讶— surprised兴奋— excited神秘— mysterious开心— happy委屈— wronged/sad
Also supports free-form natural language instructions, e.g. 用特别愤怒的语气说.
Usage
# Default settings
python3 scripts/tts.py "你好！"
# Custom speaker
python3 scripts/tts.py "Hello!" --speaker Ryan --language English
# Custom emotion
python3 scripts/tts.py "其实我真的有发现..." --instruct 冷静分析
# Full customization
python3 scripts/tts.py "哥哥，你回来啦！" \
--speaker Serena \
--instruct 撒娇语气 \
--speed 1.0
# Custom output directory
python3 scripts/tts.py "测试" --output /tmp
# Skip auto-cleanup of old files
python3 scripts/tts.py "测试" --no-cleanup
Audio Output
- Default directory:
~/tts-output/(override with$QWEN_TTS_OUTPUT_DIR) - File naming:
tts_{timestamp}_{index}.wav - Auto-cleanup: Files older than 24 hours removed on each run (disable with
--no-cleanup)
Integration
- Generate audio using the TTS script
- Send the audio file as a voice message (Telegram, etc.)
- Old files are cleaned up automatically