| name | mlx-indextts |
| description | Generate speech from text using MLX-IndexTTS on Apple Silicon. Use this skill whenever the user wants to: synthesize speech, clone voices, generate audio from text, use TTS (text-to-speech), convert voice, or mentions IndexTTS/MLX-IndexTTS. Also trigger when users ask about voice cloning, speaker conditioning, emotion control, or generating audio files from text input. |
MLX-IndexTTS
MLX-IndexTTS is an MLX implementation of IndexTTS that runs natively on Apple Silicon. Supports both v1.5 and v2.0 with automatic version detection.
Project Location
~/Projects/mlx-indextts
All commands must be executed in this directory using uv run.
Quick Start
Generate Speech (Auto-detects version)
cd ~/Projects/mlx-indextts
uv run mlx-indextts generate \
-m models/mlx-indexTTS-1.5 \
-r <reference_audio.wav> \
-t "Text to synthesize" \
-o output.wav \
--quantize 8 \
--play
uv run mlx-indextts generate \
-m models/mlx-indexTTS-2.0 \
-r <reference_audio.wav> \
-t "Text to synthesize" \
-o output.wav && \
ffmpeg -i output/audio_000.wav -c:a libopus -b:a 64k output/audio_000.ogg
uv run mlx-indextts generate \
-m models/mlx-indexTTS-2.0 \
-r <reference_audio.wav> \
-t "今天真是太开心了！" \
-o output.wav \
--emotion happy --emo-alpha 0.6
Common Parameters:
-m, --model: MLX model directory path-r, --ref-audio: Reference audio file (.wav) or pre-computed speaker file (.npz)-t, --text: Text to synthesize-o, --output: Output audio file path-q, --quantize: Runtime quantization (4, 8, or fp32)--seed: Random seed for reproducible generation--temperature: Sampling temperature (default: 1.0 for v1.5, 0.8 for v2.0)-v, --verbose: Show detailed timing info--play: Auto-play after generation--memory-limit: GPU memory limit in GB--max-tokens: Maximum mel tokens (default: 800 for v1.5, 1500 for v2.0)--segment-overlap: Crossfade overlap between segments in ms (default: 50, 0 to disable)--speed: Playback speed 0.5-2.0 (default: 1.0). Uses WSOLA time-stretch, no pitch change. Values around 0.8-1.3 work best.
v2.0-only Parameters:
--emotion: Emotion control: happy/sad/angry/afraid/disgusted/melancholic/surprised/calm--emo-alpha: Emotion intensity 0.0-1.0 (default: 0.6, 0=reference audio emotion). Recommend keeping at or below 0.8 — higher values may cause unnatural artifacts.--diffusion-steps: Diffusion steps (default: 25)--cfg-rate: CFG rate (default: 0.7)
Pre-compute Speaker (Faster Inference)
Pre-compute speaker conditioning to skip audio preprocessing. Recommended for v2.0 - reduces load time from ~9s to ~1.5s.
cd ~/Projects/mlx-indextts
uv run mlx-indextts speaker \
-m models/mlx-indexTTS-1.5 \
-r <reference_audio.wav> \
-o <speaker_v15.npz>
uv run mlx-indextts speaker \
-m models/mlx-indexTTS-2.0 \
-r <reference_audio.wav> \
-o <speaker_v20.npz>
uv run mlx-indextts generate \
-m models/mlx-indexTTS-2.0 \
-r <speaker_v20.npz> \
-t "Hello, world!" \
-o output.wav
Note: v1.5 and v2.0 speaker files are incompatible.
Convert Model (Auto-detects version)
cd ~/Projects/mlx-indextts
uv sync --extra convert
uv run mlx-indextts convert \
--model-dir /path/to/indexTTS-1.5 \
-o models/mlx-indexTTS-1.5
uv run mlx-indextts convert \
--model-dir /path/to/indexTTS-2 \
-o models/mlx-indexTTS-2.0
Available Models
| Model | Path | Status |
|---|
| IndexTTS 1.5 | models/mlx-indexTTS-1.5 | ✅ |
| IndexTTS 2.0 | models/mlx-indexTTS-2.0 | ✅ |
Version Comparison
| Feature | v1.5 | v2.0 |
|---|
| Sample rate | 24000 Hz | 22050 Hz |
| Max tokens | 800 | 1815 |
| Emotion control | ❌ | ✅ 8 emotions |
| Runtime quantization | ✅ | ✅ |
| Speaker pre-compute | ✅ | ✅ |
| RTF (M2 Max) | ~0.65 | ~2.0 |
| Load time (.npz) | ~0.3s | ~1.5s |
Supported Emotions (v2.0)
| English | Chinese |
|---|
| happy | 高兴 |
| angry | 愤怒 |
| sad | 悲伤 |
| afraid | 恐惧 |
| disgusted | 反感 |
| melancholic | 低落 |
| surprised | 惊讶 |
| calm | 自然 |
Mixed emotions: --emotion "happy:0.6,sad:0.4"
Python API
from mlx_indextts.generate import IndexTTS
tts = IndexTTS.load_model(
"~/Projects/mlx-indextts/models/mlx-indexTTS-1.5",
quantize_bits=8,
)
audio = tts.generate(text="Hello", ref_audio="./reference.wav")
tts.save_audio(audio, "./output.wav")
from mlx_indextts.generate_v2 import IndexTTSv2
tts = IndexTTSv2("~/Projects/mlx-indextts/models/mlx-indexTTS-2.0")
audio = tts.generate(
text="Hello",
reference_audio="./reference.wav",
output_path="./output.wav",
emotion="happy",
emo_alpha=0.6,
)
Common Tasks
1. Clone someone's voice (v1.5)
cd ~/Projects/mlx-indextts
uv run mlx-indextts generate \
-m models/mlx-indexTTS-1.5 \
-r person_recording.wav \
-t "Content to speak" \
-o output.wav \
--quantize 8 --play
2. Generate with emotion (v2.0)
cd ~/Projects/mlx-indextts
uv run mlx-indextts generate \
-m models/mlx-indexTTS-2.0 \
-r person_recording.wav \
-t "I'm so happy today!" \
-o output.wav \
--emotion happy --emo-alpha 0.6 --play
3. Ensure reproducible generation
cd ~/Projects/mlx-indextts
uv run mlx-indextts generate \
-m models/mlx-indexTTS-1.5 \
-r voice.wav \
-t "Hello" \
-o output.wav \
--seed 42
Performance
| Version | RTF (M2 Max) | Notes |
|---|
| v1.5 fp32 | ~0.65 | ~1.5x faster than real-time |
| v1.5 8-bit | ~0.55 | Recommended |
| v2.0 fp32 | ~2.0 | With S2Mel CFM |
| v2.0 8-bit | ~1.7 | ~15% speedup |
| v2.0 (.npz) | ~2.0 | 6x faster load than .wav |
Troubleshooting
ModuleNotFoundError: No module named 'torch'
Model conversion requires torch:
cd ~/Projects/mlx-indextts
uv sync --extra convert
v2.0-only parameters with v1.5 model
Error: "Parameters ['--emotion'] are only available for IndexTTS 2.0 models."
Solution: Use a v2.0 model for emotion control.
Want faster inference?
- Use
--quantize 8 for 8-bit quantization
- Use pre-computed speaker (.npz) instead of raw audio (.wav)
- v1.5: Minor speedup
- v2.0: 6x faster load (1.5s vs 9s) - highly recommended
