本地TTS与Qwen3-TTS

隐私优先 | 离线 | 高质量 | 自然真实语音

使用Qwen3-TTS模型进行本地文本转语音合成。您的文本永远不会离开您的设备。

为什么选择本地TTS？

与云端TTS（Google、AWS、Azure）不同，local-tts确保：

• - 零数据传输 - 100%设备端处理
• 离线运行 - 无需网络
• 无需API密钥 - 无外部依赖
• 符合GDPR/HIPAA - 简化合规性

详见隐私与安全详情。

平台概览

平台	后端	安装方式	最佳适用
macOS（Apple Silicon）	mlx_audio	pip install mlx-audio	M1/M2/M3/M4 Mac
Linux/Windows

qwen-tts | pip install qwen-tts | CUDA GPU |

快速开始

macOS

bash
pip install mlx-audio
brew install ffmpeg

自然女声

python -m mlx_audio.tts.generate \ --text Hello world \ --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit \ --voice Chelsie

Linux/Windows

bash
pip install qwen-tts

带优化（FlashAttention、bfloat16、自动设备）

python scripts/tts_linux.py Hello world --female

核心概念

--voice 与 --instruct（重要）

模型	--voice	--instruct	备注
CustomVoice	选择预设音色	添加风格/情感	可同时使用 - 音色 + 风格控制
VoiceDesign

不适用 | 根据描述创建音色 | 仅使用 --instruct | | Base | 不适用 | 不适用 | 配合 --ref_audio 进行语音克隆 |

带风格控制的CustomVoice：
bash
python -m mlx_audio.tts.generate \
--text Hello there! \
--model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit \
--voice Serena \
--instruct excited and enthusiastic

9种预设音色（开源CustomVoice）

音色	性别	语言	特点
Chelsie	女	英语（美式）	温柔、共情
Serena

女 | 英语 | 温暖、柔和 | | Ono Anna | 女 | 日语 | 俏皮 | | Sohee | 女 | 韩语 | 温暖 | | Aiden | 男 | 英语（美式） | 阳光 | | Dylan | 男 | 英语 | 自然 | | Eric | 男 | 英语 | 真实 | | Ryan | 男 | 英语 | 自然 | | Uncle Fu | 男 | 中文 | 京腔青年 |

默认值： 女声=Serena，男声=Aiden

使用示例

CustomVoice（预设音色）

bash

自然女声

python -m mlx_audio.tts.generate \
--text Your text --voice Serena --lang_code en \
--model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit

真实男声

python -m mlx_audio.tts.generate \ --text Your text --voice Aiden --lang_code en \ --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit

VoiceDesign（基于文本）

bash
python -m mlx_audio.tts.generate \
--text Hello \
--model mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-8bit \
--instruct A warm female voice, professional and clear

长文本生成

对于长文本，增加 --maxtokens 并启用 --joinaudio（仅限macOS/MLX）：

bash
python -m mlx_audio.tts.generate \
--text Your very long text here... \
--model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-8bit \
--voice Serena \
--max_tokens 4096 \
--join_audio \
--output long_audio.wav

语音克隆

bash
python -m mlx_audio.tts.generate \
--text Cloned voice speaking \
--model mlx-community/Qwen3-TTS-12Hz-1.7B-Base-8bit \
--refaudio sample.wav --reftext Sample transcript

参数

参数	描述	取值
--text	要朗读的文本	必填
--model

模型ID | 见下表 | | --voice | 预设音色（CustomVoice） | Chelsie, Serena, Aiden, Ryan... | | --instruct | 音色描述（VoiceDesign）或风格/情感（CustomVoice） | 例如：excited, calm, professional | | --speed | 语速 | 0.5-2.0（默认：1.0） | | --pitch | 音高 | 0.5-2.0（默认：1.0） | | --lang_code | 语言 | en, cn, ja, ko, de, fr... | | --ref_audio | 克隆参考音频 | 文件路径 | | --output | 输出文件 | 路径（省略时自动生成） | | --max_tokens | 最大生成令牌数 | 整数（默认：2048）- 长文本时增加 | | --join_audio | 合并音频片段 | true（默认）或 false - 推荐用于长文本 |

模型

模型	大小	用途
Qwen3-TTS-12Hz-1.7B-CustomVoice	1.7B	9种预设音色 + 风格控制
Qwen3-TTS-12Hz-1.7B-VoiceDesign

1.7B | 基于文本的音色创建 | | Qwen3-TTS-12Hz-1.7B-Base | 1.7B | 语音克隆 | | Qwen3-TTS-12Hz-0.6B-* | 0.6B | 轻量版本 |

macOS：添加 mlx-community/ 前缀（例如：mlx-community/Qwen3-TTS-12Hz-1.7B-Base-8bit）

脚本

• - scripts/ttsmacos.py - macOS封装
• scripts/ttslinux.py - Linux/Windows封装（带优化）

优化（Linux/Windows）

tts_linux.py 自动启用：

• - FlashAttention - 更快，更省内存
• bfloat16 - 更高精度
• 自动设备 - CUDA → CPU 回退
• 混合精度 - 速度 + 质量

故障排除

问题	解决方案
macOS：找不到模型	使用 mlx-community/ 前缀
macOS：音频格式

brew install ffmpeg | | Linux：CUDA内存不足 | 使用 0.6B 模型 | | Linux：速度慢 | 检查CUDA：torch.cuda.is_available() |

参考

• - macOS详情
• Linux/Windows详情
• 隐私与安全

版本

1.0.0 - 详见 VERSION 和 package.json