mlx-audio 快速上手指南：安装、CLI 与 Python API 实战

mlx-audio 是基于 Apple MLX 框架构建的语音处理库，覆盖文本转语音（TTS）、语音转文本（STT）与语音转语音（STS）三大任务，专为 Apple Silicon 上的高效推理设计。本文围绕 docs/getting-started/index.md 的完整脉络，系统讲解环境要求、安装方式、命令行工具与 Python API 的实战用法，并结合仓库源码说明背后的实现原理，帮助你在十几分钟内跑通第一条语音合成与语音识别任务。

环境要求与准备

在开始之前，请确认你的环境满足以下条件（详见 docs/getting-started/index.md）：

• Python 3.10+：仓库在 pyproject.toml 中通过 requires-python = ">=3.10" 声明了最低版本要求；
• Apple Silicon Mac（M1 / M2 / M3 / M4）：mlx-audio 依赖 MLX 框架，所有计算在 Apple Silicon 上运行；
• ffmpeg：仅在输出 MP3、FLAC、OGG、Opus 或 Vorbis 格式时需要；如果只输出 WAV，可以完全跳过 ffmpeg。

关于 ffmpeg 的具体作用，audio_io.py 的模块注释写得很清楚：读取音频时 miniaudio 负责 WAV、MP3、FLAC、Vorbis，M4A/AAC、OGG、Opus、WebM 交给 ffmpeg；写入时 WAV 走 miniaudio，其余压缩格式全部经 ffmpeg 编码。这意味着压缩格式的编码解码能力不是库本身实现的，而是依赖系统安装的 ffmpeg 可执行文件。

安装 mlx-audio

pip 快速安装

最简单的安装方式是通过 pip 安装 PyPI 上的发布版本：

pip install mlx-audio

uv 工具安装

如果你想用 uv 把命令行工具安装为全局工具，可以使用：

# 安装 PyPI 最新发布版
uv tool install --force mlx-audio --prerelease=allow

或者直接从源码安装最新代码：

# 安装 GitHub 上的最新代码
uv tool install --force git+https://github.com/Blaizzy/mlx-audio.git --prerelease=allow

可选依赖组（Extras）

mlx-audio 采用可选的依赖组设计，让你只安装需要的部分，避免不必要的包。各依赖组的含义见下表：

Extra	包含内容
tts	文本转语音相关依赖
stt	语音转文本相关依赖
sts	语音转语音相关依赖
docs	MkDocs 与 API 参考文档工具
all	全部功能（TTS + STT + STS）
dev	开发与测试工具

使用方括号语法安装对应依赖组：

# 仅 TTS
pip install "mlx-audio[tts]"

# 仅 STT
pip install "mlx-audio[stt]"

# 全部功能
pip install "mlx-audio[all]"

# 文档工具链
pip install "mlx-audio[docs]"

这些依赖组在 pyproject.toml 的 [project.optional-dependencies] 中有具体定义，例如 tts 组包含 mistral-common[audio] 与 sentencepiece，sts 组额外引入 mlx-lm（用于语音转语音流水线中的默认 LLM 应答器）、webrtcvad 等。

开发模式安装

克隆仓库并以可编辑模式安装（含开发依赖）：

git clone https://github.com/Blaizzy/mlx-audio.git
cd mlx-audio
pip install -e ".[dev]"

如果还需要参与文档站点开发，安装时加上 docs 组：

pip install -e ".[dev,docs]"

安装 ffmpeg

ffmpeg 只在需要保存或处理 MP3、FLAC、OGG、Opus、Vorbis 等压缩格式时使用，WAV 完全不需要：

=== "macOS（Homebrew）"

```bash
brew install ffmpeg
```

=== "Ubuntu / Debian"

```bash
sudo apt install ffmpeg
```

提示：如果只需要 WAV 输出，可以完全跳过 ffmpeg 的安装。若已安装，建议同时确认 ffprobe 可用，因为 audio_io.py 在解码 M4A/AAC 等格式时会调用 ffprobe 探测音频流信息。

命令行快速上手

安装完成后，你可以通过两个命令行入口使用 TTS 与 STT：

• TTS：mlx_audio.tts.generate（定义于 tts/generate.py 的 main()）
• STT：python -m mlx_audio.stt.generate（定义于 stt/generate.py）

这两个入口都在 pyproject.toml 的 [project.scripts] 中注册，安装后即可直接调用。

文本转语音（TTS）

基础生成：用一条命令把文本转成语音。快速入门示例默认使用 mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-8bit，该模型支持通过 --voice 使用预置音色：

mlx_audio.tts.generate \
    --model mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-8bit \
    --text "Hello, world!" \
    --voice Vivian \
    --lang_code English

立即播放：加上 --play 参数，生成后直接通过扬声器播放而不落盘：

mlx_audio.tts.generate \
    --model mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-8bit \
    --text "Hello, world!" \
    --voice Vivian \
    --lang_code English \
    --play

音色与语言选择：切换预置音色（如 Ryan）并给出语言提示：

mlx_audio.tts.generate \
    --model mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-8bit \
    --text "Welcome to MLX-Audio!" \
    --voice Ryan \
    --lang_code English

保存到指定目录：通过 --output_path 把音频文件输出到指定文件夹：

mlx_audio.tts.generate \
    --model mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-8bit \
    --text "Hello!" \
    --voice Vivian \
    --lang_code English \
    --output_path ./my_audio

注意：以上 TTS 示例使用的是 CustomVoice 模型（自带预置音色）。Qwen3-TTS 的 Base 模型（例如 Qwen3-TTS-12Hz-1.7B-Base-8bit）没有预置音色，需要通过参考音频进行音色克隆，详见下文"语音克隆（CSM）"。

语音克隆（CSM）：使用参考音频克隆音色，例如 Sesame CSM-1B 模型：

mlx_audio.tts.generate \
    --model mlx-community/csm-1b \
    --text "Hello from Sesame." \
    --ref_audio ./reference_voice.wav \
    --play

从实现层面看，tts/generate.py 的 generate_audio() 会先检查 --ref_audio 对应的文件是否存在，再决定把参考音频以路径还是波形传给模型。对于接受 ref_text 的模型，如果用户没有提供参考音频的文字描述，它会自动调用 STT 模型（默认 mlx-community/whisper-large-v3-turbo-asr-fp16，可通过 --stt_model 覆盖）对参考音频做转写，生成 ref_text 后用于克隆，这也是"给一段参考录音即可克隆音色"的底层机制。

语音转文本（STT）

使用 Whisper 转写：

python -m mlx_audio.stt.generate \
    --model mlx-community/whisper-large-v3-turbo-asr-fp16 \
    --audio audio.wav \
    --output-path output \
    --format json \
    --verbose

使用 Parakeet 转写：

python -m mlx_audio.stt.generate \
    --model mlx-community/parakeet-tdt-0.6b-v3 \
    --audio speech.wav \
    --output-path output \
    --format json \
    --verbose

使用 VibeVoice-ASR 转写（长音频场景可调大 --max-tokens）：

python -m mlx_audio.stt.generate \
    --model mlx-community/VibeVoice-ASR-bf16 \
    --audio meeting.wav \
    --output-path output \
    --format json \
    --max-tokens 8192 \
    --verbose

添加领域热词（Context/Hotwords）：对包含专业术语的音频，--context 可以提高识别准确率：

python -m mlx_audio.stt.generate \
    --model mlx-community/VibeVoice-ASR-bf16 \
    --audio technical_talk.wav \
    --output-path output \
    --format json \
    --max-tokens 8192 \
    --context "MLX, Apple Silicon, PyTorch, Transformer" \
    --verbose

常用参数速查

下表汇总了 CLI 常用参数（详细定义可分别在 tts/generate.py 与 stt/generate.py 中查到）：

Flag	说明
--model	Hugging Face 模型 ID 或本地路径
--text	TTS 生成的输入文本
--audio	STT 转写的输入音频文件
--voice	预置音色名（如 Vivian、Ryan、casual_male）；仅 CustomVoice 模型支持
--speed	语速倍率（默认 1.0）
--lang_code	语言提示（如 English、Chinese 或 auto）
--play	生成后立即播放
--output_path	输出文件保存目录
--verbose	显示详细生成信息
--format	STT 输出格式（txt、srt、vtt、json）

注意：不同模型支持的参数不同。例如 STT 入口在 stt/generate.py 中还额外支持 --language（语言代码）、--chunk-duration（按秒切分长音频的块时长，默认 30 秒）、--stream（流式输出）、--max-parallel-segments（并行转写分段数）、--prompt（自定义提示词）与 --gen-kwargs（以 JSON 传入更多生成参数）等。具体请查阅 docs/models/index.md 中各模型专属说明。

Python API 实战

文本转语音（TTS）

基础生成：加载模型并逐段产出音频结果：

from mlx_audio.tts.utils import load_model

# 加载 TTS 模型
model = load_model("mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-8bit")

# 生成语音
for result in model.generate_custom_voice(
    "Hello from MLX-Audio!",
    speaker="Vivian",
    language="English",
):
    print(f"Generated {result.audio.shape[0]} samples")
    # result.audio 是包含波形的 mx.array

load_model 位于 tts/utils.py，它通过 MODEL_REMAPPING 字典把模型类型别名（如 csm → sesame）映射到具体的架构模块，再调用底层的 base_load_model 完成加载，因此可以透明地同时支持本地路径与 Hugging Face 仓库 ID。

音色与语言选项：

from mlx_audio.tts.utils import load_model

model = load_model("mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-8bit")

for result in model.generate_custom_voice(
    text="Welcome to MLX-Audio!",
    speaker="Ryan",
    language="English",
):
    audio = result.audio

提示（Qwen3-TTS CustomVoice 模型）：传入 speaker 选择预置音色、language 提示语言，例如 speaker="Vivian"、language="English"。调用 model.get_supported_speakers() 可以列出当前 checkpoint 支持的全部音色——该方法的实现在 qwen3_tts.py 中直接返回 self.supported_speakers 列表，同文件还提供了 get_supported_languages() 查看支持的语言。此外，generate_custom_voice() 还支持 instruct 参数（情感/风格指令，如 "Very happy and excited."）、temperature、top_k、top_p、repetition_penalty、stream 与 streaming_interval 等生成控制参数。

Voxtral TTS：

from mlx_audio.tts.utils import load

model = load("mlx-community/Voxtral-4B-TTS-2603-mlx-bf16")

for result in model.generate(text="Hello, how are you today?", voice="casual_male"):
    print(result.audio_duration)

Qwen3-TTS（收集全部结果）：

from mlx_audio.tts.utils import load_model

model = load_model("mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-8bit")
results = list(model.generate_custom_voice(
    text="Hello, welcome to MLX-Audio!",
    speaker="Vivian",
    language="English",
))

audio = results[0].audio  # mx.array

语音转文本（STT）

Whisper：

from mlx_audio.stt.generate import generate_transcription

result = generate_transcription(
    model="mlx-community/whisper-large-v3-turbo-asr-fp16",
    audio="audio.wav",
)
print(result.text)

generate_transcription 是 stt/generate.py 的核心函数：它支持把模型路径或已加载的模型实例传入，自动按 txt/srt/vtt/json 四种格式写出转写结果（txt 只输出纯文本，srt/vtt 输出带时间戳的字幕，json 则输出含分段、单词级时间戳乃至说话人 ID 的结构化结果），并返回 STTOutput 对象供程序继续处理。

Qwen3-ASR：

from mlx_audio.stt import load

# 语音识别
model = load("mlx-community/Qwen3-ASR-0.6B-8bit")
result = model.generate("audio.wav", language="English")
print(result.text)

词级对齐（Qwen3-ForcedAligner）：

from mlx_audio.stt import load

aligner = load("mlx-community/Qwen3-ForcedAligner-0.6B-8bit")
result = aligner.generate("audio.wav", text="I have a dream", language="English")

for item in result:
    print(f"[{item.start_time:.2f}s - {item.end_time:.2f}s] {item.text}")

Parakeet（带时间戳）：

from mlx_audio.stt.utils import load

model = load("mlx-community/parakeet-tdt-0.6b-v3")
result = model.generate("audio.wav")

print(f"Text: {result.text}")

# 句子级时间戳
for sentence in result.sentences:
    print(f"[{sentence.start:.2f}s - {sentence.end:.2f}s] {sentence.text}")

流式转写（Streaming Transcription）

部分 STT 模型支持流式输出，适合对低延迟有要求的场景：

=== "Voxtral Realtime"

```python
from mlx_audio.stt.utils import load

model = load("mlx-community/Voxtral-Mini-4B-Realtime-2602-4bit")

for chunk in model.generate("audio.wav", stream=True):
    print(chunk, end="", flush=True)
```

=== "Parakeet"

```python
from mlx_audio.stt.utils import load

model = load("mlx-community/parakeet-tdt-0.6b-v3")

for chunk in model.generate("long_audio.wav", stream=True):
    print(chunk.text, end="", flush=True)
```

=== "VibeVoice"

```python
from mlx_audio.stt.utils import load

model = load("mlx-community/VibeVoice-ASR-bf16")

for text in model.stream_transcribe(audio="speech.wav", max_tokens=4096):
    print(text, end="", flush=True)
```

从 stt/generate.py 的实现看，流式路径会在每次产出结果时按增量文本累积，最终统一组装成 STTOutput（包含累计 token 数、耗时与吞吐量统计），流式接口 stream_transcribe 则在各模型实现中提供（例如 vibevoice_asr.py）。仓库还提供了可直接运行的示例脚本 examples/streaming_transcription.py 供参考。

保存音频

使用 STS 工具保存

mlx_audio.sts 提供了便捷的 save_audio 函数：

from mlx_audio.sts import save_audio

# 把音频数组保存为 WAV 文件
save_audio(audio_array, "output.wav", sample_rate=24000)

该函数定义于 processor.py，内部会把 mx.array 转换为 numpy 数组并压缩多余维度，最终委托给 audio_io.py 的 write 完成落盘。

注意：保存为 MP3、FLAC、OGG、Opus 或 Vorbis 格式需要安装 ffmpeg，WAV 不需要。从 audio_io.py 的实现看，非 WAV 格式统一走 _encode_ffmpeg，它会通过 shutil.which("ffmpeg") 探测可执行文件，缺失时会发出明确警告并提示改用 WAV。

深入理解：CLI 与 Python API 如何协同

快速上手阶段你只需要记住两个入口：命令行适合一次性任务与脚本化调用，Python API 适合集成到自己的应用流程中。二者最终都汇聚到同一套模型加载与推理链路：

• TTS 侧，mlx_audio.tts.generate 的 main() 解析参数后调用 generate_audio()（tts/generate.py），其中 load_model()（tts/utils.py）负责按模型类型分派到正确的架构，随后统一调用 model.generate(...)；
• STT 侧，python -m mlx_audio.stt.generate 的 main() 调用 generate_transcription()（stt/generate.py），既可以直接接收模型路径自动加载，也可以传入已加载的模型实例，并把结果按指定格式写出。

这一设计意味着：你在 CLI 中验证过的参数，几乎都可以一一对应地搬进 Python 代码；反过来，Python API 里更细粒度的控制（如 generate_custom_voice 的 instruct 情感指令、generate 的 stream=True 流式输出）也能通过 --gen-kwargs 等 JSON 参数在 CLI 中透传。

下一步

• 想了解更多模型与参数差异，请阅读 docs/models/index.md；
• 需要搭建 Web UI 或 API 服务，参考 docs/guides/web-ui-api-server.md；
• 对量化、流式、语音克隆等进阶主题感兴趣，可浏览 docs/guides/index.md；
• 想了解给 mlx-audio 添加新模型的方法，参见 docs/contributing/adding-a-model.md。

现在你可以在 Apple Silicon 机器上安装 mlx-audio，用 mlx_audio.tts.generate 生成第一条语音，或用 python -m mlx_audio.stt.generate 完成第一份转写任务了。