Qwen3-TTS with MLX-Audio

Text-to-speech using Qwen3-TTS models on macOS. Accepts input from text files or command line.

Prerequisites

• macOS (Intel or Apple Silicon)
• Python 3.10+
• uv package manager
• Homebrew for system dependencies
• ffmpeg, sox (optional, for audio processing)

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install system dependencies
brew install ffmpeg sox

Known Issues

On Mac (non-NVIDIA GPU), you may see this warning:

Warning: flash-attn is not installed. Will only run the manual PyTorch version.

This is expected - flash-attn only works with NVIDIA CUDA GPUs. The fallback works fine on Mac.

Installation

# Create virtual environment and install
uv venv
uv sync

# Or install in editable mode
uv pip install -e .

MLX-Audio Upgrade (Required for Voice Cloning)

For voice cloning with MLX backend, upgrade to mlx-audio 0.3.1 (required for native m4a support and auto-transcription):

# Activate the virtual environment first
source .venv/bin/activate

# Upgrade mlx-audio (requires --prerelease due to transformers 5.0 dependency)
uv pip install mlx-audio==0.3.1 --prerelease=allow

Downloading Model Weights

Models are available from Qwen on HuggingFace. Download the original (non-MLX) models:

# Install huggingface-hub
pip install huggingface-hub

# Create models directory
mkdir -p models

# Download VoiceDesign model (for voice design via text prompt)
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign --local-dir models/Qwen3-TTS-12Hz-1.7B-VoiceDesign

# Download CustomVoice model (pre-defined voices: Ryan, Aiden, etc.)
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local-dir models/Qwen3-TTS-12Hz-1.7B-CustomVoice

# Download Base model (for voice cloning from reference audio)
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base --local-dir models/Qwen3-TTS-12Hz-1.7B-Base

Note on MLX Backend

The MLX backend now works with the original Qwen models (downloaded above). Make sure to:

1. Upgrade mlx-audio to 0.3.1 (see Installation section)
2. Use the original Qwen models (not MLX community converted models)
3. Place models in the models/ directory as shown above

Usage

Usage

Voice Design (Text Prompt)

Create a voice using a text description:

uv run qwen3tts input.txt -o output.wav \
    --voice-design "female, British narrator, calm and professional" \
    -v

Pre-defined Voices

Use built-in voices (Ryan, Aiden, etc.):

uv run qwen3tts input.txt -o output.wav \
    --voice-name Ryan \
    --voice-style excited \
    -v

Voice Cloning (Base Model)

Clone a voice from a reference audio file (3-10 seconds). You can either provide a transcript or let the model extract the voice embedding automatically:

# Create voices directory
mkdir -p voices

# Your reference audio (3-10 seconds of speech)
# Save audio as voices/ref.wav

# Option 1: With transcript (better quality)
echo "Transcript of your reference audio here" > voices/ref.txt

uv run qwen3tts input.txt -o output.wav \
    --voice-audio voices/ref.wav \
    --voice-text voices/ref.txt \
    -v

# Option 2: Without transcript (faster, uses voice embedding only)
uv run qwen3tts input.txt -o output.wav \
    --voice-audio voices/ref.wav \
    -v

Command Line Input

# Read from stdin
echo "Hello world" | uv run qwen3tts - -o hello.wav

# Or use - as input file
cat myfile.txt | uv run qwen3tts - -o output.wav

MP3 Output

# Requires ffmpeg installed
uv run qwen3tts input.txt -o output.mp3 --format mp3

Project Structure

qwen3-tts-mlx/
├── pyproject.toml          # Project configuration
├── README.md               # This file
├── src/
│   └── qwen3tts/
│       ├── __init__.py     # Package init
│       ├── cli.py          # CLI interface
│       └── generate.py     # TTS generation
├── models/                 # Downloaded model weights
├── voices/                 # Reference audio files
└── output/                 # Generated audio files

Available Models

Configuration

You can also configure the model path in code:

from qwen3tts.generate import TTSGenerator

generator = TTSGenerator(
    model_path="models/Qwen3-TTS-12Hz-1.7B-VoiceDesign",
    model_type="design",
    speaker_design="female, American, calm",
    verbose=True,
)

generator.generate("Your text here", "output.wav")

Performance Tips

• Install flash-attn for faster inference: pip install flash-attn
• Use the smaller 0.6B models if memory is limited
• For best voice cloning results, use clean reference audio with clear speech