mlx-audio

python 2026-01-28

mlx-audio

2026-01-28

时间就是能力等等发展的地盘。——马克思

MLX-Audio：把 Apple Silicon 的“音频算力”榨干的全能库

如果你正在用 Apple Silicon（M1/M2/M3/M4）做音频方向的 AI，那么 MLX-Audio 会让你大呼过瘾。它是基于 Apple 的 MLX 框架构建的“全能音频库”，把文本转语音（TTS）、语音转文本（STT）和语音转语音（STS）装进一个统一的工具箱，强调在苹果芯片上的快与稳，并且做了极扎实的工程细节：模型适配、量化、Web UI、OpenAI 兼容 API、Swift 包、乃至大规模合成的示例工程。

仓库：Blaizzy/mlx-audio
描述：TTS / STT / STS 一站式音频处理库，针对 Apple Silicon 优化
许可证：MIT
技术栈：Python + MLX（Apple），Next.js Web UI，OpenAI 兼容 REST API，Swift 侧包可选
特性简述：
- 在 Apple Silicon 上加速推理
- 多模型架构，覆盖 TTS、STT、STS
- 多语言支持、语音自定义��克隆
- 语速可调、3D 可视化 Web 界面
- OpenAI 兼容 API（方便接入已有应用）
- 3/4/6/8bit 等量化支持
- iOS/macOS 的 Swift 包，走端侧

安装与启动：Python 一体，也支持 uv 工具链

最简单的安装：

1	`pip install mlx-audio`

如果你只想要命令行工具，可以用 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

开发或需要 Web 界面：

1
2
3

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

快速体验：命令行与 Python API

命令行（TTS）

# 基础合成
mlx_audio.tts.generate --model mlx-community/Kokoro-82M-bf16 --text 'Hello, world!' --lang_code a

# 选择声音与语速
mlx_audio.tts.generate --model mlx-community/Kokoro-82M-bf16 --text 'Hello!' --voice af_heart --speed 1.2 --lang_code a

# 直接播放
mlx_audio.tts.generate --model mlx-community/Kokoro-82M-bf16 --text 'Hello!' --play --lang_code a

# 指定输出目录
mlx_audio.tts.generate --model mlx-community/Kokoro-82M-bf16 --text 'Hello!' --output_path ./my_audio --lang_code a

Python API（TTS）

from mlx_audio.tts.utils import load_model

# 加载模型
model = load_model("mlx-community/Kokoro-82M-bf16")

# 生成语音
for result in model.generate("Hello from MLX-Audio!", voice="af_heart"):
    print(f"Generated {result.audio.shape[0]} samples")
    # result.audio 是 mx.array 的波形数据

模型一览：从多语言 TTS 到带说话人分离的 STT

MLX-Audio 支持的模型非常丰富，且针对 Apple Silicon 做了适配与转换：

TTS（文本转语音）

Kokoro：快速高质量多语种 TTS（EN/JA/ZH/FR/ES/IT/PT/HI）
Qwen3-TTS：多语种、支持“情感控制 / Voice Design / 语音克隆”
CSM：会话式 TTS，支持语音克隆
Dia：对话风格 TTS
OuteTTS：高效型 TTS
SparkTTS：EN/ZH
Chatterbox：多语种表达力强
Soprano：高质量 EN

Kokoro 示例：

from mlx_audio.tts.utils import load_model

model = load_model("mlx-community/Kokoro-82M-bf16")

for result in model.generate(
    text="Welcome to MLX-Audio!",
    voice="af_heart",  # American female
    speed=1.0,
    lang_code="a"      # American English
):
    audio = result.audio

可用声线（示例）：

美式英语：af_heart, af_bella, af_nova, af_sky, am_adam, am_echo …
英式英语：bf_alice, bf_emma, bm_daniel, bm_george …
日语：jf_alpha, jm_kumo …
中文：zf_xiaobei, zm_yunxi …

语言代码：

a = 美式英语（默认）
b = 英式英语
j = 日语（需要 pip install misaki[ja]）
z = 中文（需要 pip install misaki[zh]）
e = 西语
f = 法语

Qwen3-TTS 示例：

from mlx_audio.tts.utils import load_model

model = load_model("mlx-community/Qwen3-TTS-12Hz-0.6B-Base-bf16")
results = list(model.generate(
    text="Hello, welcome to MLX-Audio!",
    voice="Chelsie",
    language="English",
))
audio = results[0].audio  # mx.array

CSM 语音克隆（CLI）：

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

STT（语音转文本）

Whisper（OpenAI）：99+ 语言
Parakeet（NVIDIA）：英语准确
Voxtral（Mistral）
VibeVoice-ASR（Microsoft 9B）：说话人分离 + 时间戳，长音频（最多 60 分钟）→ 结构化 JSON

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)

VibeVoice-ASR（带分离与时间戳）：

from mlx_audio.stt.utils import load

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

# 基础转写
result = model.generate(audio="meeting.wav", max_tokens=8192, temperature=0.0)
print(result.text)
# [{"Start":0,"End":5.2,"Speaker":0,"Content":"Hello everyone, let's begin."}, ...]

# 分段访问
for seg in result.segments:
    print(f"[{seg['start_time']:.1f}-{seg['end_time']:.1f}] Speaker {seg['speaker_id']}: {seg['text']}")

流式转写：

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

带上下文热词：

result = model.generate(
    audio="technical_talk.wav",
    context="MLX, Apple Silicon, PyTorch, Transformer",
    max_tokens=8192,
    temperature=0.0,
)

STT CLI：

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

STS（语音转语音 / 音频处理）

SAM-Audio：文本引导的声源分离
Liquid2.5-Audio：语音互转、跨模态
MossFormer2 SE：语音增强与降噪

SAM-Audio 分离示例：

from mlx_audio.sts import SAMAudio, SAMAudioProcessor, save_audio

model = SAMAudio.from_pretrained("mlx-community/sam-audio-large")
processor = SAMAudioProcessor.from_pretrained("mlx-community/sam-audio-large")

batch = processor(
    descriptions=["A person speaking"],
    audios=["mixed_audio.wav"],
)

result = model.separate_long(
    batch.audios,
    descriptions=batch.descriptions,
    anchors=batch.anchor_ids,
    chunk_seconds=10.0,
    overlap_seconds=3.0,
    ode_opt={"method": "midpoint", "step_size": 2/32},
)

save_audio(result.target[0], "voice.wav")
save_audio(result.residual[0], "background.wav")

MossFormer2 增强示例：

from mlx_audio.sts import MossFormer2SEModel, save_audio

model = MossFormer2SEModel.from_pretrained("starkdmi/MossFormer2_SE_48K_MLX")
enhanced = model.enhance("noisy_speech.wav")
save_audio(enhanced, "clean.wav", 48000)

Web 界面与 OpenAI 兼容 API：一边调试一边服务

开启服务：

# API Server
mlx_audio.server --host 0.0.0.0 --port 8000

# Web UI（另一个终端）
cd mlx_audio/ui
npm install && npm run dev

API 示例（OpenAI 兼容）：

TTS：

curl -X POST http://localhost:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model": "mlx-community/Kokoro-82M-bf16", "input": "Hello!", "voice": "af_heart"}' \
  --output speech.wav

STT：

1
2
3

curl -X POST http://localhost:8000/v1/audio/transcriptions \
  -F "file=@audio.wav" \
  -F "model=mlx-community/whisper-large-v3-turbo-asr-fp16"

量化与模型转换：更小更快，适配 MLX

把 Hugging Face 模型转换为 MLX 并量化：

# 4-bit 量化
python -m mlx_audio.convert \
    --hf-path prince-canuma/Kokoro-82M \
    --mlx-path ./Kokoro-82M-4bit \
    --quantize \
    --q-bits 4 \
    --upload-repo username/Kokoro-82M-4bit

# 指定 dtype（bfloat16）
python -m mlx_audio.convert \
    --hf-path prince-canuma/Kokoro-82M \
    --mlx-path ./Kokoro-82M-bf16 \
    --dtype bfloat16 \
    --upload-repo username/Kokoro-82M-bf16

常见参数：

--hf-path 源模型（HF 或本地）
--mlx-path 输出路径
--quantize、--q-bits（4/6/8）、--q-group-size
--dtype（fp16/bf16/fp32）
--upload-repo（上传到 HF Hub）

Swift 包：端侧 TTS

如果你要在 iOS/macOS 端做 TTS，官方提供了独立仓库：

https://github.com/Blaizzy/mlx-audio-swift

示例工程：把“圣经”做成有声书

仓库里有一个 bible-audiobook 的例子，作者用 JS/TS 和 bun，把全本《American King James Bible》逐节合成为音频：

总计 31,102 节 → 合成耗时约 28 小时 05 分钟
输出音频总时长约 86 小时 32 分钟 36 秒
设备：Mac mini M4 Pro（12 核、24GB RAM）

说明了 MLX-Audio 在 Apple Silicon 上进行大规模批处理的稳定性与效率；脚本里还集成了 pm2 来增强容错与自动恢复。步骤包括 WAV→MP3 转换、完整性统计等。

环境要求与 ffmpeg

Python 3.10+
Apple Silicon Mac（M1/M2/M3/M4）
MLX 框架
ffmpeg（保存 MP3/FLAC 所需；WAV 无需）

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

为什么选 MLX-Audio

针对 Apple Silicon 做到“跑起来就很快”，尤其适合端侧与小型工作站
一站式覆盖 TTS、STT、STS，且模型生态丰富
Web UI 与 OpenAI 兼容 API 让集成变得轻松
量化与转换打通了 Hugging Face → MLX 的模型迁移链路
Swift 包加成，真正端到端

如果你要在 Mac 上做语音合成、识别、分离、增强的工程化项目，MLX-Audio 给你一个“从脚本到服务，从本地到端侧”的完整路径。

仓库：https://github.com/Blaizzy/mlx-audio
许可证：MIT
在 Apple Silicon 上享受“音频 AI 的丝滑算力”，今天就装起来试试吧。