MLX Audio 开发环境搭建指南：在 Apple Silicon 上配置 TTS/STT/STS 本地开发与测试环境

MLX Audio 开发环境搭建指南在 Apple Silicon 上配置 TTS/STT/STS 本地开发与测试环境【免费下载链接】mlx-audioA text-to-speech (TTS), speech-to-text (STT) and speech-to-speech (STS) library built on Apples MLX framework, providing efficient speech analysis on Apple Silicon.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-audioMLX Audio 是一个基于 Apple MLX 框架、专为 Apple Silicon Mac 设计的语音库覆盖文本转语音TTS、语音转文本STT、语音转语音STS与语音活动检测VAD。本文以 docs/contributing/dev-setup.md 为主线完整讲解从克隆仓库、安装可编辑editable开发依赖、运行测试、代码格式化到本地启动 API 服务器与 Web UI 的全流程并结合作品源码与配置文件pyproject.toml、pytest.ini、mkdocs.yml深入说明每个环节的底层细节。读完本文你将能独立搭建一套可复现、可提交代码的 MLX Audio 开发环境。前置条件Prerequisites开始前请确认你的机器满足以下要求条件说明Python 3.10项目在 pyproject.toml 中声明requires-python 3.10低于 3.10 无法安装Apple Silicon Mac面向 M1 / M2 / M3 / M4 系列芯片MLX 依赖 Apple 的统一内存架构Unified Memory与 Metal GPUGit用于克隆仓库与参与版本管理ffmpeg可选仅在处理 WAV 以外的音频格式时需要详见下文ffmpeg 的角色小节从源码结构看mlx_audio/下的模型实现大量直接使用mlx.core与mlx.nn例如 mlx_audio/tts/generate.py 中的mx.array波形处理因此非 Apple Silicon 环境无法运行推理代码。ffmpeg 的角色getting-started/installation.md 明确指出ffmpeg 仅用于保存 MP3、FLAC、OGG、Opus、Vorbis 等格式的音频WAV 输出无需 ffmpeg。在 mlx_audio/audio_io.py 中音频读取优先使用 miniaudio支持 WAV/MP3/FLACM4A/AAC/OGG/Opus 等格式则回退到 ffmpeg写入时 WAV 用 miniaudio其余格式走 ffmpeg。因此如果只是开发调试 TTS/STT 模型跳过 ffmpeg 完全可行。macOS 下用 Homebrew 安装brew install ffmpeg克隆仓库git clone https://gitcode.com/GitHub_Trending/ml/mlx-audio.git cd mlx-audio克隆后建议先浏览顶层目录结构确认 pyproject.toml、pytest.ini、mkdocs.yml 与mlx_audio/源码包均已就位。安装依赖两种官方方式方式一pip可编辑安装 开发 extras以可编辑editable模式安装这样对源码的修改会即时生效无需重新安装pip install -e .[dev]如果同时要参与文档编写追加docsextrapip install -e .[dev,docs]方式二uv推荐给使用 uv 管理项目的开发者uv syncuv sync会安装项目本身以及默认的开发依赖组。extras 按需开启# 包含文档工具链 uv sync --extra docs # 包含所有可选 extras uv sync --all-extras仓库根目录已提供 uv.lock 锁文件uv sync会严格按锁定版本解析依赖保证团队内环境一致。Optional Extras 全览开发时按需安装只引入真正需要的依赖组能显著缩短安装时间# 仅 TTS 依赖 pip install -e .[tts] # 仅 STT 依赖 pip install -e .[stt] # API 服务器依赖 pip install -e .[server] # 文档工具链 pip install -e .[docs] # 全量开发环境 pip install -e .[dev,docs,tts,stt,server]深入 extraspyproject.toml 中的依赖分组pyproject.toml 对可选依赖的划分非常细致理解它们有助于避免装错包Extra包含的关键依赖用途sttsentencepiece0.2.0语音识别分词ttsmistral-common[audio]、sentencepiece文本转语音serverfastapi0.95.0、uvicorn[standard]0.22.0、python-multipart、webrtcvad2.0.10、setuptools81FastAPI API 服务器与实时 VADstsmlx-lm0.31.1、webrtcvad、setuptools81语音转语音管线其默认回复模型由 mlx-lm 负责加载llmmlx-lm0.31.1STS 管线内的进程内 LLM 回复器paritymlx-lm0.31.3与mlx_audio/lm所 vendored 的 mlx-lm 版本做差分测试all上述核心依赖合集一次装全devpytest7.0.0、pytest-asyncio、black24.2.0、isort5.13.2、pre-commit3.7.0测试与代码规范docsmkdocs-material9.6、mkdocstrings[python]0.29MkDocs 文档站点与 API 参考生成值得注意的是server与sts都固定了setuptools81其注释说明setuptools 81 及以上版本移除了pkg_resources会导致webrtcvad无法工作——这是一个典型的版本钉死案例升级依赖时需格外小心。项目核心依赖本身在 pyproject.toml 的dependencies段声明包括mlx0.31.1、huggingface_hub1.0、miniaudio1.61、numpy1.26.4、scipy1.10.0、sounddevice0.5.3、tqdm4.67.1、transformers5.14.0。此外[project.scripts]段定义了六个 CLI 入口mlx_audio.convert、mlx_audio.stt.generate、mlx_audio.tts.generate、mlx_audio.music.generate、mlx_audio.server、mlx_audio.sts.generate——安装后即可在终端直接调用这些命令。运行测试安装完成后用 pytest 验证环境# 运行完整测试套件 pytest # 针对特定模块 pytest mlx_audio/tts/tests/ pytest mlx_audio/stt/tests/ pytest mlx_audio/sts/tests/仓库中的测试布局与上述命令一一对应mlx_audio/tts/tests/、mlx_audio/stt/tests/、mlx_audio/sts/tests/分别存放各语音任务的测试用例此外mlx_audio/codec/tests/、mlx_audio/vad/tests/、mlx_audio/lid/tests/与仓库根级tests/如 tests/test_registry.py、tests/test_whisper_decode_options.py也属于完整套件的一部分。pytest.ini 中声明了两个值得注意的配置asyncio_mode auto测试中的async def测试函数会被 pytest-asyncio 自动识别执行无需手动标注装饰器markers requires_weights: requires downloaded or converted real model weights标有requires_weights的测试需要真实模型权重下载或转换得到跑完整套件前建议先确认网络与磁盘空间。代码格式化与 Linting项目统一使用 Black 作为格式化工具# 仅检查是否合规CI 中常用 black --check . # 自动格式化 black .pyproject.toml 中的[tool.black]将行宽锁定为88 字符、目标 Python 版本为py310[tool.isort]使用profile black以保证 isort 的 import 排序与 Black 兼容。开发组中devextra 已包含black、isort与pre-commit提交代码前可运行# 若项目启用了 ruff 也可执行 ruff check .从devextras 同时包含pre-commit3.7.0可以推断项目推荐在提交前用 pre-commit 钩子统一执行格式化与静态检查具体钩子配置以仓库.pre-commit-config.yaml为准。项目结构速览官方文档给出了如下目录布局本文结合 docs/contributing/architecture.md 稍作补充mlx-audio/ ├── mlx_audio/ │ ├── tts/ # 文本转语音模型实现models/、generate.py CLI、audio_player.py 实时播放 │ ├── stt/ # 语音转文本Whisper、Parakeet、Voxtral、Qwen3-ASR 等 │ ├── sts/ # 语音转语音SAM-Audio、MossFormer2、DeepFilterNet、voice_pipeline.py │ ├── vad/ # 语音活动检测Sortformer 等 │ ├── music/ # 音乐生成如 MiniMax Music 3 │ ├── audio_io.py # 音频读写miniaudio ffmpeg 回退 │ ├── server.py # FastAPI API 服务器 │ ├── server_inference.py # 服务器推理调度 │ ├── convert.py # 模型转换与量化 │ └── ui/ # Next.js Web 界面 ├── docs/ # MkDocs 文档站点mkdocs.yml 配置导航 ├── examples/ # 示例脚本如 higgs_audio_clone_demo.py、qwen3_asr_transcription.py ├── pyproject.toml # 项目配置依赖、extras、CLI 入口、格式化规则 ├── pytest.ini # pytest 配置 └── mkdocs.yml # 文档站点配置从 architecture.md 可以进一步了解所有 TTS/STT/STS 模型遵循统一的加载管线load()→ 读取config.json→ 依据model_type在MODEL_REMAPPING中查找 → 动态导入模型类 → 加载.safetensors权重共享加载逻辑集中在 mlx_audio/utils.py。TTS 模型的generate()是生成器函数逐段产出GenerationResult天然支持流式输出——这解释了为何 TTS 模块拥有独立的 audio_player.py 用于流式实时播放。本地运行 API 服务器与 Web UI启动 FastAPI 服务器# API 服务器 mlx_audio.server --host localhost --port 8000该命令对应 pyproject.toml 中mlx_audio.server mlx_audio.server:main的入口定义。mlx_audio/server.py是一个 FastAPI 应用从源码可见其提供 OpenAI 兼容的音频接口TTS、转写、音源分离与模型加载/卸载管理并通过webrtcvad支持实时转写。若依赖尚未安装如缺fastapi请先补装pip install -e .[server]。启动 Web UI另开终端cd mlx_audio/ui npm install npm run devmlx_audio/ui/是基于 Next.js 的 Studio 界面含 TTS、STT、音源分离页面首次运行前需执行npm install安装前端依赖。常见开发任务添加一个新依赖将依赖加入 pyproject.toml 对应的分组核心依赖放dependencies可选功能放对应的 extras然后重新安装pip install -e .[dev]注意遵守前面提到的钉死约束涉及webrtcvad的环境必须保留setuptools81。快速测试某个模型用 TTS CLI 生成一段语音来验证改动# 使用本地或 HuggingFace 模型生成语音 mlx_audio.tts.generate \ --model mlx-community/Kokoro-82M-bf16 \ --text Testing my changes. \ --lang_code a \ --play其中--play会实时播放生成的音频命令入口定义在mlx_audio.tts.generate mlx_audio.tts.generate:main。Kokoro 是项目内置的小体量 TTS 模型约 82M 参数非常适合作为开发冒烟测试对象。同理可以验证 STTmlx_audio.stt.generate --model 模型名 --audio 文件.wav详见 docs/getting-started/quickstart-cli.md。构建与预览文档# 安装文档依赖 pip install -e .[docs] # 本地实时预览 mkdocs serve # 构建静态站点 mkdocs buildmkdocs serve启动后文档站点默认运行在http://127.0.0.1:8000。站点配置见 mkdocs.yml采用 Material 主题支持深/浅色切换、搜索高亮、代码复制按钮通过mkdocstrings插件直接从 Python docstring 生成 API 参考页本文所在的贡献者文档docs/contributing/dev-setup.md、docs/contributing/architecture.md、docs/contributing/adding-a-model.md也在导航Contributing分组之下。修改文档后运行mkdocs build可检查是否有链接或 Markdown 语法错误。结语搭建开发环境是参与 MLX Audio 的第一步也是理解其依赖体系与模块划分的最佳入口。回顾本文要点Python 3.10 与 Apple Silicon 是硬性前提pip 可编辑安装与 uv 两条路径均可快速就绪按需选择tts/stt/sts/server/docs等 extras 可避免安装冗余依赖pytest、Black 与 ruff 构成了测试与代码规范的闭环mlx_audio.server与mkdocs serve则分别提供了运行期验证与文档预览的手段。完成上述配置后即可参考 docs/contributing/adding-a-model.md 开始为项目贡献新模型。【免费下载链接】mlx-audioA text-to-speech (TTS), speech-to-text (STT) and speech-to-speech (STS) library built on Apples MLX framework, providing efficient speech analysis on Apple Silicon.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-audio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考