---

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 — 视频转结构化纪要；本技能可为纪要生成语音摘要。