VoiceStudio — MLX-Audio 引擎（Apple Silicon）¶

MLX-Audio（Blaizzy/mlx-audio）将 14+ 个 TTS 引擎——Kokoro、CSM、Dia、Qwen3-TTS、Chatterbox、MeloTTS、OuteTTS 等——封装在同一个适配器后面，该适配器运行在 Apple 的 MLX 框架上。它仅支持 Apple Silicon：该引擎不面向 Linux、Windows 或 Intel Mac 发布，且这些平台上任何多余的 wheel 都不会报告为可用（#390）。

何时选择它¶

• 你在使用 M 系列 Mac，并希望使用针对它优化的小型快速模型。
• 你想要某个特定的托管模型（Kokoro 用于小型多语言，CSM 用于克隆，Qwen3-TTS 用于声音设计，Dia 用于对话……）。

安装¶

pip install mlx-audio

将该包安装到运行 VoiceStudio 后端的 Python 环境中。这会安装 MLX-Audio 适配器，而不是每个精选模型的权重。引擎可用并不意味着 CSM 已下载。

然后通过 Model Catalogue（TTS 标签页 → Use）或 OMNIVOICE_TTS_BACKEND=mlx-audio 选择该引擎。

模型选择¶

一个后端承载多个模型。精选集合如下：

在 Model Catalogue 的精选选择器中选取模型（#981），或将 OMNIVOICE_MLX_AUDIO_MODEL 设置为精选键（kokoro）或任何完整的 HF 仓库 ID。该环境变量会覆盖已保存的 UI 选择。

OuteTTS 声音克隆¶

OuteTTS 在克隆声音之前，会先用 Whisper 模型读取参考片段。请先从 Model Catalogue 下载 Whisper large-v3 Turbo（OuteTTS 声音克隆读取器，mlx-audio）（mlx-community/whisper-large-v3-turbo-asr-fp16）；不下载的话，生成会立即停止，并指出该条目，而不会在合成期间进行下载（#2700）。每个片段生成的声音会保存在数据文件夹的 outetts_speakers/ 下，因此后续使用同一片段生成时会跳过这一步。

CSM 首次使用¶

1. 在 Apple Silicon Mac 上，打开 Model Catalogue 并下载 CSM 1B（声音克隆，mlx-audio）（mlx-community/csm-1b-8bit）。如果出现提示，接受其模型许可证并等待下载完成。
2. 在其精选模型选择器中选择 MLX-Audio 和 CSM（声音克隆）。安装或选择 Kokoro 并不会准备 CSM。
3. 使用参考声音生成一个短视频片段。适配器会在首次合成时惰性调用 mlx_audio.tts.utils.load_model(...)，因此首次加载可能比后续片段耗时更长。仅选择模型并不会将其加载到内存中。

如果 CSM 仍然不可用，请检查后端日志中的模型加载错误，并确认下载内容位于该后端使用的缓存中。若已导出 OMNIVOICE_MLX_AUDIO_MODEL，它会覆盖选择器；如果它一直选择其他模型，请移除该变量或将其设置为 csm。

对于源代码安装，可选的诊断步骤可以在同一个 Python 环境中显式获取并准备 CSM。在查看其许可证后，仅当需要该下载时，请从仓库根目录运行以下命令：

uv run --no-sync python -c "from mlx_audio.tts.utils import load_model; load_model('mlx-community/csm-1b-8bit')"

此命令可能会连接 Hugging Face 并下载模型文件。它使用 shell 的 Hugging Face 缓存设置，因此如果你自定义过 HF_HOME/HF_HUB_CACHE，请传入与后端相同的值；预热其他缓存无法修复应用缺失的文件。手动准备成功后，请重启后端并再次选择 CSM。对于打包安装，请使用应用自带的模型下载流程，而不要安装到无关的系统 Python 环境中。

行为说明¶

• 输出为 24 kHz 单声道。对于原生采样率不同的模型（例如 44.1 kHz 的 Dia），其输出会在拼接和导出前进行重采样。
• 模型错误（包括部分音频输出后发生的错误）会停止生成，而不会使用默认声音重试。仅当模型的可调用签名不接受可选输入时，才会省略这些输入；受支持的声音、参考片段和语言输入，以及声音设计指令（instruct），仍保留在同一次请求中。
• 在精选模型中，只有 csm 被确认会使用参考片段；其他模型会忽略参考音频。因此，MLX-Audio 仅在选中 CSM 时才会声明支持克隆，配音和批处理任务也会使用该能力标志。使用其他模型启动配音、批处理或声音转换任务时，会被拒绝并显示错误信息，指明当前活动模型并引导你在 Model Catalogue 中选择 CSM（声音克隆）；切换引擎仍是可行的替代方案。参见 #2201。
• 声音设计（文本描述 → 声音）可通过 Qwen3-TTS VoiceDesign 模型使用。
• 支持哪些语言取决于你加载的模型。Kokoro 支持约八种语言；其他模型各有不同。如果向 Kokoro 传入其语言集之外的语言，错误信息会列出它接受的语言（#977）。请选择其中一种，或改用多语言引擎处理该文本。
• 将选择器设为 Auto 并不能绕开拒绝。Auto 完全不发送语言，因此所选声音配置文件会提供其自身保存的语言（#533）。如果配置文件保存为波斯语，仍然会被传给 Kokoro 并被拒绝，错误信息现在会指出该配置文件就是来源（#2156）。请编辑配置文件的语言，或为该次生成直接选择受支持的语言。

平台说明¶

此引擎作为需显式选择加入的平台专属能力，不受跨平台一致性约束：它仅存在于 Apple 的 MLX 运行时可用的平台。在任何其他平台上，引擎选择器都会将其显示为不可用，并说明原因。

故障排除¶

• 在 M 系列 Mac 上不可用：在 VoiceStudio 的 Python 环境中执行 pip install mlx-audio；在打包的应用构建中，MLX 的原生库可能无法加载——引擎会报告不可用而非崩溃。
• 其他问题：install/troubleshooting.md。

另请参阅：benchmarks.md、languages.md、downloading-models.md、磁盘使用情况。

具有相同原生采样率的连续音频块会被一起重采样，以在块边界处保留滤波器上下文；采样率变化时会开启新的分组。

配置文件语言的拒绝在本地和远程渲染（包括流式渲染）中均属于终止性请求错误。Electron 和 Web 端会显示本地化提示，说明 Auto 会继承配置文件语言；两者都不会静默重试相同的拒绝。

Kokoro 语言错误会列出已安装模型表格中的所有语言。"British English" 和 en-gb 都会选择其英式英语语音管线。较新安装的 Kokoro 表格中的显示名称同样被接受，因此错误消息中列出的语言无需更新硬编码映射即可被选中。