mlx-tts · diff
git:20260421.63dcdf9 to git:20260925.32ce6c0
81 added, 507 removed. Audit A to A.
---
name: mlx-tts
- description: Use when needing to generate speech audio from text files on Apple Silicon Mac using Qwen3-TTS (MLX framework, fast, prompt-based voice design)
+ description: "Apple Silicon Mac 本地语音合成 (TTS) 与语音识别 (ASR)，基于 MLX 框架的 Qwen3-TTS 1.7B / Qwen3-ASR，支持用文字提示词设计音色、无需参考音频，全程离线、无 API key。Use when you need to turn text into speech on an M-series Mac, design a voice with a text prompt, or transcribe audio locally. 触发词：文字转语音、文本转语音、TTS、语音合成、生成配音、旁白配音、有声书、语音转文字、ASR、speech synthesis、text to speech、local TTS、voice design on Apple Silicon、Qwen3-TTS。Do NOT use when：非 Apple Silicon（Intel Mac / Windows / Linux）、需要从参考音频做真人音色克隆、内存低于 16GB、或需要把配音对齐到视频时间轴（改用 video-dubbing）。"
---
- # 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.
+ # mlx-tts: Apple Silicon 本地语音合成
- ## Overview
+ ## Purpose
- 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
+ 用 MLX 框架在本机跑 Qwen3-TTS，把文本合成为高质量语音，并可用文字提示词设计音色；
+ 附带 Qwen3-ASR 做语音转文字。全程离线、无 API key。本技能是一套操作协议：装好环境、
+ 跑对命令、验证产物——不做云端调用，也不做提示词音色的临场猜测（那部分查参考文件）。
## 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
+ - 在 Apple Silicon Mac（M1/M2/M3/M4）上需要高质量本地 TTS。
+ - 想用文字提示词设计音色，例如 `"a warm female voice, slightly soft"`。
+ - 需要本机 ASR（语音转文字）。
+ - 希望利用 Apple Neural Engine 获得快速推理，且数据不出本机。
+ - 触发词：文字转语音、TTS、语音合成、生成配音、旁白、有声书、语音转文字、ASR、
+ text to speech、speech synthesis、local TTS、voice design。
## 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
-
- ```bash
- brew install ffmpeg uv && uv tool install --force "mlx-audio" --prerelease=allow
- ```
-
- ### Verify Installation
-
- ```bash
- 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:
- ```bash
- export HF_ENDPOINT=https://hf-mirror.com
- ```
-
- Option 2 - ModelScope (faster):
- ```bash
- 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
-
- ```bash
- mlx_audio.tts.generate \
- --text "你好，这是本地 TTS 测试" \
- --output-path ./output.wav
- ```
-
- ### With Voice Design (Prompt-Based)
-
- ```bash
- 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**:
- ```bash
- --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**
- ```bash
- # Split text into sentences and generate separately
- python3 << 'EOF'
- import subprocess
- import re
-
- text = """Your long text here... Multiple sentences."""
-
- # Split by sentence boundaries
- sentences = re.split(r'(?<=[。！？.!?])\s+', text)
- chunks = []
- current_chunk = ""
-
- for sent in sentences:
- if len(current_chunk) + len(sent) < 300: # Max 300 chars per chunk
- current_chunk += sent
- else:
- if current_chunk:
- chunks.append(current_chunk)
- current_chunk = sent
- if current_chunk:
- chunks.append(current_chunk)
-
- # Generate each chunk
- for i, chunk in enumerate(chunks):
- subprocess.run([
- "mlx_audio.tts.generate",
- "--text", chunk,
- "--instruct", "a warm, gentle female voice",
- "--output-path", f"./chunk_{i:03d}.wav"
- ])
- print(f"Generated {len(chunks)} chunks. Use ffmpeg to concatenate.")
- EOF
- ```
-
- **Option 2: Concatenate with ffmpeg**
- ```bash
- # After generating chunks, merge them
- ffmpeg -i "concat:$(echo chunk_*.wav | tr ' ' '|')" -acodec copy final_output.wav
-
- # Or with crossfade (smooth transition)
- ffmpeg -f concat -safe 0 -i <(for f in chunk_*.wav; do echo "file '$PWD/$f'"; done) -c copy output.wav
- ```
-
- ### ASR (Speech to Text)
-
- ```bash
- mlx_audio.stt.generate \
- --audio ./input.wav \
- --output-path ./transcript.txt \
- --language zh
- ```
-
- Long audio (auto-chunking):
- ```bash
- mlx_audio.stt.generate \
- --audio /path/to/long_audio.m4a \
- --output-path ./transcript.txt \
- --format txt \
- --language zh \
- --chunk-duration 30
- ```
-
- ### Batch Processing
-
- **Batch TTS from file list:**
- ```bash
- # Create text file with lines to synthesize
- cat > texts.txt << 'EOF'
- 第一行要转换的文字
- 第二行要转换的文字
- 第三行要转换的文字
- EOF
-
- # Process each line
- while IFS= read -r line; do
- safe_name=$(echo "$line" | tr -cd '[:alnum:]\n' | cut -c1-20)
- mlx_audio.tts.generate \
- --text "$line" \
- --instruct "a professional news anchor" \
- --output-path "./output/${safe_name}.wav"
- done < texts.txt
- ```
-
- **Batch ASR:**
- ```bash
- # Batch convert all audio files in directory
- for f in *.wav; do
- mlx_audio.stt.generate \
- --audio "$f" \
- --output-path "${f%.wav}.txt" \
- --language zh
- done
- ```
-
- ### Audio Post-Processing (with ffmpeg)
-
- While mlx-audio doesn't have built-in effects like Voicebox, you can use ffmpeg:
-
- **Pitch Shift (音色调整):**
- ```bash
- # Raise pitch by 2 semitones (更尖声)
- ffmpeg -i input.wav -af "asetrate=48000*1.12,aresample=48000" output_high.wav
-
- # Lower pitch by 2 semitones (更低沉)
- ffmpeg -i input.wav -af "asetrate=48000*0.89,aresample=48000" output_low.wav
- ```
-
- **Add Reverb (混响):**
- ```bash
- ffmpeg -i input.wav -af "aecho=0.8:0.9:1000:0.3" output_reverb.wav
- ```
-
- **Speed Control (语速):**
- ```bash
- # Speed up 1.2x (更快)
- ffmpeg -i input.wav -af "atempo=1.2" output_fast.wav
-
- # Slow down 0.8x (更慢)
- ffmpeg -i input.wav -af "atempo=0.8" output_slow.wav
- ```
-
- **Volume Normalize (音量标准化):**
- ```bash
- ffmpeg -i input.wav -af "loudnorm" output_normalized.wav
- ```
-
- **Convert Format (格式转换):**
- ```bash
- # WAV to MP3
- ffmpeg -i input.wav -b:a 192k output.mp3
-
- # WAV to AAC (for Apple devices)
- ffmpeg -i input.wav -c:a aac -b:a 192k output.m4a
-
- # WAV to FLAC (lossless compression)
- ffmpeg -i input.wav output.flac
- ```
-
- ## Create Helper Script
-
- Create `~/bin/tts.sh` for quick TTS:
- ```bash
- #!/bin/bash
- TEXT="${1:-"Hello, Human!"}"
- INSTRUCT="${2:-"a confident teenage girl with a flirtatious, seductive edge"}"
- OUTPUT_DIR=./voice_output
-
- mkdir -p "$OUTPUT_DIR"
-
- mlx_audio.tts.generate \
- --text "$TEXT" \
- --instruct "$INSTRUCT" \
- --output-path "$OUTPUT_DIR/output.wav" \
- --audio-format wav
-
- echo "Generated: $OUTPUT_DIR/output.wav"
- ```
-
- Make executable and use:
- ```bash
- chmod +x ~/bin/tts.sh
-
- # Usage
- tts.sh "要转换的文字"
- tts.sh "要转换的文字" "a warm, gentle female voice"
- ```
-
- ## Advanced Helper Script
-
- Create `~/bin/tts-advanced.sh` with more features:
- ```bash
- #!/bin/bash
- # TTS with auto-chunking for long texts
-
- TEXT="${1:-"Hello"}"
- VOICE="${2:-"a warm, gentle female voice"}"
- OUTPUT="${3:-"./output.wav"}"
- MAX_CHARS=300
-
- # Check if text needs chunking
- if [ ${#TEXT} -le $MAX_CHARS ]; then
- # Short text - direct generation
- mlx_audio.tts.generate \
- --text "$TEXT" \
- --instruct "$VOICE" \
- --output-path "$OUTPUT"
- echo "Generated: $OUTPUT"
- else
- # Long text - need chunking
- echo "Text too long (${#TEXT} chars), auto-chunking..."
-
- # Create temp directory
- TMPDIR=$(mktemp -d)
-
- # Split by sentences (simplified)
- echo "$TEXT" | fold -w $MAX_CHARS -s | split -l 1 - "$TMPDIR/chunk_"
-
- # Generate each chunk
- i=0
- for chunk in "$TMPDIR"/chunk_*; do
- CHUNK_TEXT=$(cat "$chunk")
- [ -z "$CHUNK_TEXT" ] && continue
-
- mlx_audio.tts.generate \
- --text "$CHUNK_TEXT" \
- --instruct "$VOICE" \
- --output-path "$TMPDIR/part_$(printf "%03d" $i).wav"
-
- i=$((i+1))
- done
-
- # Concatenate with ffmpeg
- ffmpeg -f concat -safe 0 -i \
- <(for f in "$TMPDIR"/part_*.wav; do echo "file '$f'"; done) \
- -c copy "$OUTPUT"
-
- # Cleanup
- rm -rf "$TMPDIR"
- echo "Generated: $OUTPUT"
- fi
- ```
-
- ## Voicebox vs MLX-TTS Comparison
-
- | Feature | Voicebox | MLX-TTS (Qwen3-TTS) |
- |---------|----------|---------------------|
- | **Platform** | macOS/Windows/Linux | Apple Silicon only |
- | **GUI** | ✅ Desktop app | ❌ CLI only |
- | **Multi-engine** | 5 engines (Qwen3, Lux, Chatterbox, TADA) | Qwen3-TTS only |
- | **Voice cloning** | ✅ From reference audio | ❌ Prompt-based only |
- | **Effects** | Built-in (reverb, pitch, delay) | ffmpeg post-processing |
- | **Timeline editor** | ✅ Stories editor | ❌ |
- | **Batch processing** | ✅ | Script-based |
- | **API** | REST API | ❌ |
- | **Setup** | Download DMG/MSI | One-command install |
- | **Speed** | Fast | Fast (MLX optimized) |
- | **Memory** | Configurable | ~8GB |
- | **Privacy** | Local | Local |
-
- **When to use Voicebox:**
- - Need GUI and visual timeline
- - Need voice cloning from audio
- - Need built-in effects
- - Multi-platform support
-
- **When to use MLX-TTS:**
- - Apple Silicon Mac only
- - Prefer CLI and scripting
- - Quick setup (`brew install`)
- - Lightweight solution
-
- ## Quick Reference
-
- | Task | Command |
- |------|---------|
- | Basic TTS | `mlx_audio.tts.generate --text "Hello" --output out.wav` |
- | With voice design | Add `--instruct "voice description"` |
- | ASR | `mlx_audio.stt.generate --audio in.wav --output out.txt` |
- | Long audio ASR | Add `--chunk-duration 30` |
- | Batch TTS | See "Batch Processing" section |
- | Pitch shift | Use ffmpeg: `-af "asetrate=48000*1.12,aresample=48000"` |
- | Change format | Use ffmpeg: `-i input.wav -b:a 192k output.mp3` |
-
- ## Output Formats
-
- ### TTS Output
- - **Default**: WAV (48kHz, 16-bit)
- - **Options**: `--audio-format wav|mp3|flac`
-
- **Note**: mlx-audio outputs WAV by default. Convert to other formats with ffmpeg:
- ```bash
- # High-quality MP3
- ffmpeg -i input.wav -b:a 256k output.mp3
-
- # AAC for Apple devices
- ffmpeg -i input.wav -c:a aac -b:a 256k output.m4a
-
- # FLAC for lossless
- ffmpeg -i input.wav output.flac
-
- # OGG Vorbis
- ffmpeg -i input.wav -c:a libvorbis -q:a 6 output.ogg
- ```
-
- ### ASR Output Formats
- - `--format txt`: Plain text (default)
- - `--format json`: JSON with timestamps
- - `--format srt`: Subtitle format
+ - 非 Apple Silicon（Intel Mac / Windows / Linux）-> 改用其他 TTS 方案。
+ - 需要从参考音频做真人音色克隆 -> 本模型只支持提示词式音色设计。
+ - 内存低于 16GB -> 也许能跑，但更慢。
+ - 需要把配音逐段对齐到视频时间轴、烧录字幕 -> 交给 `video-dubbing`。
+ - 需要把整段视频转成结构化纪要 -> 交给 `video-minutes`。
- ## Advanced Use Cases
+ ## Workflow
- ### Podcast/Audio Book Production
+ 1. **安装**（一次性）：
+ `brew install ffmpeg uv && uv tool install --force "mlx-audio" --prerelease=allow`
+ 2. **验证安装**：`uv tool list | grep mlx` 应显示 `mlx-audio v0.4.2`。若命令找不到，
+ 重启终端或 `uv tool update-shell`。首次生成会自动下载模型（约 2GB）。
+ 3. **生成 TTS**：
+ `mlx_audio.tts.generate --text "你好，这是本地 TTS 测试" --output-path ./output.wav`
+ 需要设计音色时追加 `--instruct "a warm, gentle female voice"`。音色示例见
+ `references/voice-design.md`。
+ 4. **长文本分块**：文本超过约 500 字时按句子边界切分（每块 <= 300 字），逐块生成后用 ffmpeg
+ 拼接，避免内存问题与音频截断。做法见 `references/batch-and-long-text.md`。
+ 5. **可选 ASR**：
+ `mlx_audio.stt.generate --audio ./input.wav --output-path ./transcript.txt --language zh`
+ 长音频追加 `--chunk-duration 30`。
+ 6. **可选后处理/转换**：用 ffmpeg 做变调、混响、变速、响度标准化或转 mp3/aac/flac，
+ 命令集见 `references/audio-post-processing.md`。
+ 7. **验证产物**：确认输出 WAV 存在、时长非零、可播放；音色或语气不符合预期时调整
+ `--instruct` 重跑，而不是叠加更多效果器。
- ```bash
- # Create consistent narrator voice
- VOICE="a warm, articulate narrator, clear and engaging"
+ ## Decision Rules
- # Generate chapters
- for chapter in {1..10}; do
- mlx_audio.tts.generate \
- --text "Chapter $chapter" \
- --instruct "a professional announcer, clear and authoritative" \
- --output-path "./podcast/chapter_${chapter}_title.wav"
-
- mlx_audio.tts.generate \
- --text "$(cat chapter_${chapter}.txt)" \
- --instruct "$VOICE" \
- --output-path "./podcast/chapter_${chapter}_content.wav"
- done
+ - 短文本 -> 直接一次生成；超过约 500 字 -> 必须分块（`references/batch-and-long-text.md`）。
+ - 要设计/改变音色 -> 用 `--instruct` 描述；要保持多段音色一致 -> 用首段作 `--ref_audio` 参考
+ （`--ref_audio` + `--ref_text`，见 `references/voice-design.md`）。
+ - 要 mp3 / aac / flac / ogg -> 先生成 WAV，再用 ffmpeg 转换（`references/audio-post-processing.md`）。
+ - 要做语音转文字 -> `mlx_audio.stt.generate`；需要字幕 -> `--format srt`，需要时间戳 -> `--format json`。
+ - 模型下载慢/失败 -> 设 `HF_ENDPOINT=https://hf-mirror.com` 或改用 ModelScope
+ （`references/install-apple-silicon.md`）。
+ - 音色不理想 -> 先简化 `--instruct`；仍不满意再换提示词，不要堆叠复杂指令。
+ - 需要 GUI、可视化时间线或真人克隆 -> 改用 Voicebox，对比见 `references/voicebox-comparison.md`。
- # Merge with ffmpeg
- ffmpeg -f concat -safe 0 -i <(for f in ./podcast/*.wav; do echo "file '$PWD/$f'"; done) -c copy audiobook.wav
- ```
+ ## Constraints
- ### Multi-Voice Dialogue
+ - **仅 Apple Silicon + macOS 14.0+**：MLX 不支持 Intel Mac 与其他平台。
+ - **本地运行**：不得引入云端 TTS 或需要 API key 的替代调用。
+ - **不做真人克隆**：只能提示词式音色设计，不要承诺复刻某个特定真人的声音。
+ - **长文本必须分块**：不要一次性提交超长文本，否则音频截断或 OOM。
+ - **不在句子中间切分**：保持句子完整，切分点落在句末标点。
+ - **首次运行会下载约 2GB 模型**：提前告知用户，不要误判为卡死。
- ```bash
- # Character A (confident young woman)
- mlx_audio.tts.generate \
- --text "I'll take care of this." \
- --instruct "a confident teenage girl, slightly energetic" \
- --output-path ./voice_a.wav
+ ## Verification
- # Character B (elderly wise man)
- mlx_audio.tts.generate \
- --text "Be careful, my child." \
- --instruct "an elderly male voice, wise and gentle, slower pace" \
- --output-path ./voice_b.wav
+ 交付前逐项确认：
- # Character C (robot/AI)
- mlx_audio.tts.generate \
- --text "Processing complete." \
- --instruct "a synthetic robotic voice, monotone, slightly metallic" \
- --output-path ./voice_c.wav
+ - [ ] `uv tool list | grep mlx` 能列出 mlx-audio；`mlx_audio.tts.generate` 可执行。
+ - [ ] 输出文件真实存在（默认 WAV，48kHz/16-bit），且时长非零。
+ - [ ] 文本 > ~500 字时已分块，且拼接后无截断。
+ - [ ] 若指定了音色，`--instruct` 与用户期望一致，必要时已用首段作 `--ref_audio`。
+ - [ ] ASR 场景下输出格式（txt/json/srt）与用户需求匹配。
+ - [ ] 未使用任何云端/付费 TTS 服务。
- # Add robotic effect with ffmpeg
- ffmpeg -i voice_c.wav -af "asetrate=48000*0.95,aresample=48000,aecho=0.6:0.4:300:0.5" voice_c_robot.wav
- ```
+ ## Output
- ### Voice Templates Library
+ - **Outcome**：一个或多个本地音频文件（默认 `./output.wav`），或在 ASR 场景下的
+ `transcript.txt` / `.json` / `.srt`。
+ - **Done when**：文件已生成、可播放/可读，音色与语速符合用户要求，长文本已完整覆盖无截断。
+ - **Evidence**：输出文件路径与时长；使用的 `--instruct` 与 `--model`；分块数与拼接结果
+ （长文本场景）；ASR 的语言与输出格式。
- Create reusable voice templates:
+ ## References
- ```bash
- # Save templates in a file
- cat > ~/voice_templates.txt << 'EOF'
- narration=a warm, articulate narrator, clear and engaging, moderate pace
- news=a professional news anchor, clear and authoritative, precise diction
- friendly=a friendly, approachable voice, warm and inviting
- teacher=a patient educator, clear and encouraging, moderate pace
- storyteller=a mysterious storyteller, dramatic and engaging
- calm=a soothing, meditative voice, very slow and gentle
- excited=a highly energetic voice, fast-paced and enthusiastic
- dramatic=a theatrical voice, expressive and emotional
- EOF
+ 按需加载，不要预先全读：
- # Usage
- VOICE=$(grep "^narration=" ~/voice_templates.txt | cut -d'=' -f2)
- mlx_audio.tts.generate \
- --text "Your text here" \
- --instruct "$VOICE" \
- --output-path output.wav
- ```
+ - `references/voice-design.md` — 要设计/微调音色，或用户问"能否克隆声音"时读。
+ - `references/batch-and-long-text.md` — 文本超过约 500 字、要批量生成，或要搭可复用脚本时读。
+ - `references/audio-post-processing.md` — 需要变调/混响/变速/响度标准化或格式转换时读。
+ - `references/install-apple-silicon.md` — 首次安装、换机、或模型下载失败时读。
+ - `references/troubleshooting.md` — 生成失败、音质异常，或要性能调优时读。
+ - `references/voicebox-comparison.md` — 用户在 MLX-TTS 与其他 TTS 工具之间选型时读。
## Troubleshooting
- ### Common Issues
-
- | Issue | Solution |
- |-------|----------|
- | Model download fails/timeout | Use `HF_ENDPOINT=https://hf-mirror.com` or ModelScope |
- | Memory不足 (OOM) | Model already 8-bit quantized; close other apps; use chunking for long text |
- | Command not found | Restart terminal or run `uv tool update-shell` |
- | Audio format not supported | Convert: `ffmpeg -i input.mp3 output.wav` |
- | M1/M2 errors | Ensure macOS 14.0+; MLX requires Apple Silicon |
- | Model path error | Use absolute path or `realpath` |
- | Poor voice quality | Try different `--instruct` prompts; simpler is often better |
- | Audio cuts off | Text too long; use auto-chunking for >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
- ```
+ - 模型下载失败/超时 -> `HF_ENDPOINT=https://hf-mirror.com` 或 ModelScope。
+ - Command not found -> 重启终端或 `uv tool update-shell`。
+ - 音频被截断 -> 文本过长，改分块。
+ - 完整失败模式表与调试命令见 `references/troubleshooting.md`。
- ## References
+ ## Related Skills
- - [MLX-Audio GitHub](https://github.com/Blaizzy/mlx-audio)
- - [Qwen3-TTS Model](https://huggingface.co/mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-8bit)
- - [Qwen3-ASR Model](https://huggingface.co/mlx-community/Qwen3-ASR-0.6B-bf16)
- - [ModelScope](https://www.modelscope.cn/)
- - [HuggingFace Mirror](https://hf-mirror.com/)
+ - `video-dubbing` — 把配音逐段对齐到视频时间轴并烧录字幕，底层调用 `mlx_audio.tts.generate`。
+ - `video-minutes` — 视频转结构化纪要；本技能可为纪要生成语音摘要。