🌟 项目简介
mlx-audio-plus 是一个基于 Apple 的 MLX 框架构建的 Text-to-Speech (TTS) 和 Speech-to-Speech (STS) 库，专为 Apple Silicon (M 系列芯片) 提供高效的语音合成。
- 项目地址： https://github.com/DePasqualeOrg/mlx-audio-plus
- 核心功能： 在 Apple Silicon 上快速推理、多语言支持、语音定制、语速调节，并提供REST API 等。
💻 部署与安装
步骤一：配置 Conda Python 环境
为了避免包版本冲突，推荐使用 Conda 创建一个隔离的 Python 虚拟环境。
- 打开终端或 Anaconda Prompt。
创建新的 Conda 环境：创建一个名为
mlx_audio_env的 Python 环境（可自定义名称），并指定 Python 版本（例如 3.12.9）。conda create --name mlx_audio_env python=3.12.9激活环境：进入新创建的环境。
conda activate mlx_audio_env
步骤二：安装 mlx-audio-plus
在已激活的 Conda 环境中，使用 pip 安装 mlx-audio-plus 包。
pip install mlx-audio-plus步骤三：通过 huggingface 下载所需模型
# 安装 huggingface_hub
pip install huggingface_hub
# 预先下载推荐的 TTS 模型
hf download mlx-community/CosyVoice2-0.5B-fp16
# 预先下载推荐的 STT 模型
hf download mlx-community/whisper-large-v3-turbo推荐的 TTS 模型包括：
mlx-community/IndexTTS-1.5mlx-community/CosyVoice2-0.5B-fp16mlx-community/Spark-TTS-0.5B-fp16mlx-community/VoxCPM1.5
推荐的 STT 模型包括：
mlx-community/whisper-large-v3-turbo(高性能模型)mlx-community/whisper-small-4bitmlx-community/whisper-tiny-4bit
一、🗣️ 语音生成 (TTS) 功能
1. 参数选项
语音生成使用 mlx_audio.tts.generate 命令行工具。以下是mlx_audio.tts.generate 命令支持的参数选项：
🚀 核心功能参数 (Core Functionality Parameters)
| 参数 | 描述 | 用法示例 |
|---|---|---|
--text TEXT | 必需（Text-to-Speech）：要转换为语音的文本字符串。如果未提供，可能需要使用 --source_audio 进行语音转语音。 | --text "Hello, world!" |
--voice VOICE | 语音选择：指定用于生成语音的预设或自定义声音名称。 | --voice af_heart |
--model MODEL | 模型路径/名称：指定要使用的 TTS 模型的路径或 Hugging Face 仓库名称。 | --model mlx-community/Kokoro-82M-4bit |
⚙️ 语音风格与控制参数 (Voice Style and Control Parameters)
| 参数 | 描述 | 范围/示例 |
|---|---|---|
--speed SPEED | 语速：控制语音的播放速度。通常在 0.5x (慢) 到 2.0x (快) 之间。 | --speed 1.25 |
--gender GENDER | 性别（可能）：用于指定或调整语音的感知性别（取决于模型支持）。 | --gender female |
--pitch PITCH | 音高（可能）：用于调整生成语音的音高（取决于模型支持）。 | --pitch 0.9 |
--lang_code LANG_CODE | 语言代码：为模型提供语言提示，以确保正确的发音和风格。 | --lang_code en |
--ref_audio REF_AUDIO | 参考音频：用于语音克隆或风格转移。模型将尝试模仿此音频的音色、语调或风格。 | --ref_audio path/to/ref.wav |
--ref_text REF_TEXT | 参考文本：与 ref_audio 对应的文本。用于更好地对齐和理解参考音频的风格。 | --ref_text "a quick brown fox" |
--instruct_text INSTRUCT_TEXT | 指令文本：用于指导模型的生成行为，例如指定情感或强调。 | --instruct_text "Speak with a joyful tone." |
--source_audio SOURCE_AUDIO | 源音频：用于语音转语音 (STS) 工作流。模型将转换此音频的内容或风格。 | --source_audio path/to/source.mp3 |
--stt_model STT_MODEL | 语音转文本模型：在 STS 场景中，用于将 source_audio 自动转录为文本的模型。 | --stt_model whisper-tiny |
💾 输出与文件参数 (Output and File Parameters)
| 参数 | 描述 | 用法示例 |
|---|---|---|
--file_prefix FILE_PREFIX | 输出文件前缀：为生成的音频文件设置一个前缀名称。 | --file_prefix audiobook_chapter1 |
--audio_format AUDIO_FORMAT | 音频格式：指定输出音频的文件格式。常见选项包括 wav, mp3 等。 | --audio_format mp3 |
--join_audio | 合并音频段：如果输入文本很长，模型可能会分段生成。此标志将所有生成的音频段合并为一个文件。 | --join_audio |
--play | 播放音频：生成完成后，尝试使用系统默认播放器播放生成的音频文件。 | --play |
⚡ 生成与流式传输参数 (Generation and Streaming Parameters)
这些参数通常用于控制模型的采样和解码过程，影响语音的随机性和质量。
| 参数 | 描述 | 范围/示例 |
|---|---|---|
--max_tokens MAX_TOKENS | 最大令牌数：限制模型在单个生成调用中可以生成的最大音频片段（token）数量。 | --max_tokens 1024 |
--temperature TEMPERATURE | 温度：控制采样的随机性。值越高（如 1.0），结果越随机/富有创意；值越低（如 0.0），结果越确定。 | --temperature 0.7 |
--top_p TOP_P | Top-P 采样：一种解码策略，仅考虑累计概率达到 $P$ 的最小词集进行采样。控制生成的多样性。 | --top_p 0.9 |
--top_k TOP_K | Top-K 采样：一种解码策略，仅从概率最高的 $K$ 个词中进行采样。 | --top_k 50 |
--repetition_penalty REPETITION_PENALTY | 重复惩罚：对已经生成的 token 施加惩罚，以减少重复，提高流畅性。 | --repetition_penalty 1.1 |
--stream | 流式传输：启用音频生成结果的流式传输，允许在整个音频生成完成之前开始播放或处理。 | --stream |
--streaming_interval STREAMING_INTERVAL | 流式传输间隔：指定在流式传输模式下，模型输出音频片段的时间间隔或大小。 | --streaming_interval 0.5 |
2. 基础用法：Zero-Shot 模式 (零样本克隆)
该模式需要一个参考音频 (ref_audio) 和对应的转录文本 (ref_text) 来学习参考语音的风格，并用该风格朗读目标文本 (text)。
mlx_audio.tts.generate --model mlx-community/CosyVoice2-0.5B-fp16 \
--text "Hello, this is a test of text to speech." \
--ref_audio reference.wav \
--ref_text "This is what I said in the reference audio."| 参数 | 解释 |
|---|---|
--model | 必需。指定要使用的 TTS 模型。 |
--text | 必需。希望模型朗读的目标文本。 |
--ref_audio | 必需。提供目标音色的音频文件路径。 |
--ref_text | 必需。参考音频中内容的准确转录文本。 |
3. 进阶用法示例
跨语言模式 (Cross-Lingual):
mlx_audio.tts.generate --model mlx-community/CosyVoice2-0.5B-fp16 \ --text "Bonjour, comment allez-vous?" \ --ref_audio reference.wav指令模式 (Instruct Mode):
mlx_audio.tts.generate --model mlx-community/CosyVoice2-0.5B-fp16 \ --text "I have exciting news!" \ --ref_audio reference.wav \ --instruct_text "Speak with excitement and enthusiasm"语音转换 (Voice Conversion):
mlx_audio.tts.generate --model mlx-community/CosyVoice2-0.5B-fp16 \ --ref_audio target_speaker.wav \ --source_audio source_speech.wav直接播放:
mlx_audio.tts.generate --model mlx-community/CosyVoice2-0.5B-fp16 \ --text "Hello world" \ --ref_audio reference.wav \ --play
二、📝 语音转文字 (STT) 功能
字幕识别（Speech-to-Text）功能使用 mlx_audio.stt.generate 命令行工具，主要基于 Whisper 模型。
1. 参数选项
以下是对mlx_audio.stt.generate 语音转文字（Speech-to-Text, STT）命令行工具支持的参数选项的详细解析，以表格形式呈现：
| 参数 | 类型 | 是否必需 | 描述 | 示例用法 |
|---|---|---|---|---|
-h, --help | 选项 | 否 | 显示帮助信息并退出程序。 | mlx_audio.stt.generate -h |
--model MODEL | 路径/名称 | 否 | 模型路径或名称。指定用于语音转文字的模型路径或 Hugging Face 模型名称（例如 openai/whisper-base）。如果未指定，通常会使用一个默认模型。 | --model whisper-large-v3 |
--audio AUDIO | 路径 | 是 | 输入音频文件路径。指定要进行转录的音频文件（如 .wav, .mp3 等）的路径。 | --audio /data/recording.mp3 |
--output OUTPUT | 路径 | 是 | 输出文件路径。指定转录结果将保存到的文件的路径和名称。文件扩展名不决定格式，格式由 --format 决定。 | --output transcript.txt |
--format {txt,srt,vtt,json} | 选项 | 否 | 输出格式。指定转录结果的输出格式。支持以下四种： - txt: 纯文本格式。 - srt: SubRip 格式，常用于字幕。 - vtt: WebVTT 格式，常用于网页视频字幕。 - json: JSON 格式，包含详细的时间戳和信息。 | --format srt |
--verbose | 标志 | 否 | 详细输出模式。启用后，会在控制台输出更多关于模型加载、转录进度和最终结果的详细信息。 | --verbose |
--max_tokens MAX_TOKENS | 整数 | 否 | 最大生成令牌数。限制模型在转录过程中可以生成的最大新令牌（token）数量，有助于控制生成长度或防止无限循环。 | --max_tokens 4096 |
2. 基础用法：使用 Whisper-Large-V3-Turbo 进行转录
使用高性能的 mlx-community/whisper-large-v3-turbo 模型对音频文件进行转录。
mlx_audio.stt.generate --model mlx-community/whisper-large-v3-turbo \
--audio input_speech.wav --output transcript.txt| 参数 | 解释 |
|---|---|
--audio | 必需。需要转录的音频文件路径。 |
--model | 必需。指定要使用的 Whisper 模型名称或路径。 |
--output | 必需。指定输出的文件路径及文件名。 |
3. 进阶用法：指定输出格式和语言
可以指定输出格式（例如字幕文件格式 srt）以及音频中使用的语言，以提高准确性。
mlx_audio.stt.generate --model mlx-community/whisper-large-v3-turbo \
--audio long_meeting.mp3 \
--format srt \
--output transcript.srt --output_format srt: 将输出格式指定为srt(字幕文件格式)。其他常见格式包括vtt或纯text。
三、🌐 服务器启动功能
mlx-audio-plus 允许启动一个 Web 服务器，通过 REST API 或 Web UI 提供语音合成和识别服务。
1. 基础用法：启动服务器
使用 mlx_audio.server 命令启动服务，默认在本地主机和特定端口运行。
mlx_audio.server --host 0.0.0.0 --port 8000| 参数 | 解释 |
|---|---|
--host | 可选。指定服务器监听的 IP 地址。0.0.0.0 表示监听所有网络接口。 |
--port | 可选。指定服务器监听的端口号。 |
通过浏览器访问 http://localhost:8000/docs/ 查看API接口相关信息
2. 进阶用法：预加载模型
在启动服务器时，可以预先加载特定的 TTS 或 STT 模型，以加快推理速度。
mlx_audio.server --tts_model mlx-community/CosyVoice2-0.5B-fp16 \
--stt_model mlx-community/whisper-large-v3-turbo--tts_model: 指定启动时加载的 TTS 模型。--stt_model: 指定启动时加载的 STT 模型。
服务器启动成功后，即可通过浏览器访问指定的地址（例如 http://localhost:8000）来使用 Web UI，或通过 API 客户端发送 HTTP 请求进行调用。
🗑️ 清理与移除项目
步骤一：使用 pip-autoremove 卸载软件包及依赖
为了彻底清除 mlx-audio-plus 及其不再需要的依赖项，使用 pip-autoremove 工具。
激活环境：
conda activate mlx_audio_env安装 pip-autoremove：
pip install pip-autoremove卸载 mlx-audio-plus 及其依赖：
pip-autoremove mlx-audio-plus huggingface_hub -y
步骤二：移除 Conda 虚拟环境
退出当前环境：
conda deactivate删除 Conda 环境：
conda remove --name mlx_audio_env --all
步骤三：清理缓存的模型文件（可选）
TTS/STT 模型在首次运行时会被下载到本地缓存。可以手动删除 MLX 或 Hugging Face 模型在系统上的默认缓存目录中的文件，以释放磁盘空间。
