---
name: mlx-tts
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: Apple Silicon 本地语音合成

## Purpose

用 MLX 框架在本机跑 Qwen3-TTS，把文本合成为高质量语音，并可用文字提示词设计音色；
附带 Qwen3-ASR 做语音转文字。全程离线、无 API key。本技能是一套操作协议：装好环境、
跑对命令、验证产物——不做云端调用，也不做提示词音色的临场猜测（那部分查参考文件）。

## When to Use

- 在 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

- 非 Apple Silicon（Intel Mac / Windows / Linux）-> 改用其他 TTS 方案。
- 需要从参考音频做真人音色克隆 -> 本模型只支持提示词式音色设计。
- 内存低于 16GB -> 也许能跑，但更慢。
- 需要把配音逐段对齐到视频时间轴、烧录字幕 -> 交给 `video-dubbing`。
- 需要把整段视频转成结构化纪要 -> 交给 `video-minutes`。

## Workflow

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` 重跑，而不是叠加更多效果器。

## Decision Rules

- 短文本 -> 直接一次生成；超过约 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`。

## Constraints

- **仅 Apple Silicon + macOS 14.0+**：MLX 不支持 Intel Mac 与其他平台。
- **本地运行**：不得引入云端 TTS 或需要 API key 的替代调用。
- **不做真人克隆**：只能提示词式音色设计，不要承诺复刻某个特定真人的声音。
- **长文本必须分块**：不要一次性提交超长文本，否则音频截断或 OOM。
- **不在句子中间切分**：保持句子完整，切分点落在句末标点。
- **首次运行会下载约 2GB 模型**：提前告知用户，不要误判为卡死。

## Verification

交付前逐项确认：

- [ ] `uv tool list | grep mlx` 能列出 mlx-audio；`mlx_audio.tts.generate` 可执行。
- [ ] 输出文件真实存在（默认 WAV，48kHz/16-bit），且时长非零。
- [ ] 文本 > ~500 字时已分块，且拼接后无截断。
- [ ] 若指定了音色，`--instruct` 与用户期望一致，必要时已用首段作 `--ref_audio`。
- [ ] ASR 场景下输出格式（txt/json/srt）与用户需求匹配。
- [ ] 未使用任何云端/付费 TTS 服务。

## Output

- **Outcome**：一个或多个本地音频文件（默认 `./output.wav`），或在 ASR 场景下的
  `transcript.txt` / `.json` / `.srt`。
- **Done when**：文件已生成、可播放/可读，音色与语速符合用户要求，长文本已完整覆盖无截断。
- **Evidence**：输出文件路径与时长；使用的 `--instruct` 与 `--model`；分块数与拼接结果
  （长文本场景）；ASR 的语言与输出格式。

## References

按需加载，不要预先全读：

- `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

- 模型下载失败/超时 -> `HF_ENDPOINT=https://hf-mirror.com` 或 ModelScope。
- Command not found -> 重启终端或 `uv tool update-shell`。
- 音频被截断 -> 文本过长，改分块。
- 完整失败模式表与调试命令见 `references/troubleshooting.md`。

## Related Skills

- `video-dubbing` — 把配音逐段对齐到视频时间轴并烧录字幕，底层调用 `mlx_audio.tts.generate`。
- `video-minutes` — 视频转结构化纪要；本技能可为纪要生成语音摘要。