qwen3-tts-mlx

Qwen3-TTS MLX

使用 MLX 在 Apple Silicon（M1/M2/M3/M4）上本地运行 Qwen3-TTS。支持 11 种语言、9 种内置音色、声音克隆，以及根据文本描述设计音色。

适用场景

• 在 Mac 上完全离线生成语音
• 制作旁白、有声读物、播客或视频配音
• 创建风格和情感可控的多语言 TTS
• 根据简短音频样本克隆任意声音
• 根据文本描述设计自定义音色

快速开始

安装

pip install mlx-audio
brew install ffmpeg

基本用法

python scripts/run_tts.py custom-voice \
  --text "Hello, welcome to local text to speech." \
  --voice Ryan \
  --output output.wav

控制风格

python scripts/run_tts.py custom-voice \
  --text "Breaking news: local AI model achieves human-level speech." \
  --voice Uncle_Fu \
  --instruct "news anchor tone, calm and authoritative" \
  --output news.wav

模型变体

变体	模型	大小	内存	用途
CustomVoice	mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-4bit	~1GB	~4GB	内置音色 + 风格控制（推荐）
VoiceDesign	mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-5bit	~2GB	~5GB	根据文本描述创建音色
Base	mlx-community/Qwen3-TTS-12Hz-0.6B-Base-4bit	~1GB	~4GB	根据参考音频克隆声音

支持的语言

语言	代码	备注
自动检测	auto	默认值，根据文本检测
中文	Chinese	普通话
英语	English
日语	Japanese
韩语	Korean
法语	French
德语	German
西班牙语	Spanish
葡萄牙语	Portuguese
意大利语	Italian
俄语	Russian

内置音色

音色	语言	特点
Vivian	中文	女性，明亮、年轻
Serena	中文	女性，温柔、轻柔
Uncle_Fu	中文	男性，威严，新闻主播风格
Dylan	中文	男性，北京话
Eric	中文	男性，四川话
Ryan	英语	男性，充满活力
Aiden	英语	男性，清晰、中性
Ono_Anna	日语	女性
Sohee	韩语	女性

音色选择指南：

场景	推荐音色
中文新闻/旁白	Uncle_Fu
中文日常/活泼内容	Eric
中文女性、专业风格	Vivian
中文女性、讲故事风格	Serena
英语活力型内容	Ryan
英语中性/教育内容	Aiden
日语内容	Ono_Anna
韩语内容	Sohee

模式

1) CustomVoice

使用内置音色，并可通过 --instruct 控制情绪/风格。

python scripts/run_tts.py custom-voice \
  --text "This is amazing news!" \
  --voice Vivian \
  --instruct "excited and happy" \
  --output excited.wav

风格指令示例：

• "calm and warm" - 语气柔和、亲切
• "news anchor, authoritative" - 专业的广播风格
• "excited and energetic" - 充满活力、热情洋溢
• "sad and melancholic" - 富有情感、忧郁的语气
• "whispering, intimate" - 轻声细语、近距离麦克风效果

2) VoiceDesign

通过自然语言描述，创建全新的音色。

python scripts/run_tts.py voice-design \
  --text "Welcome to our podcast." \
  --instruct "warm, mature male narrator with low pitch and gentle tone" \
  --output podcast_intro.wav

声音描述示例：

• "young cheerful female with high pitch"
• "elderly wise male with deep resonant voice"
• "professional female news anchor, clear articulation"
• "friendly young male, casual and relaxed"

3) VoiceClone

根据参考音频样本克隆任意声音（建议时长为 5-10 秒）。

python scripts/run_tts.py voice-clone \
  --text "This is my cloned voice speaking new content." \
  --ref_audio reference.wav \
  --ref_text "The exact transcript of the reference audio" \
  --output cloned.wav

声音克隆提示：

• 使用没有背景噪音的干净音频
• 5-10 秒的语音效果最佳
• 提供准确的参考音频转录文本
• 参考音频与输出的语言应一致

CLI 参数

参数	必填	默认值	描述
--text	是	-	要合成的文本
--voice	否	Vivian	内置语音（仅限 CustomVoice）
--lang_code	否	auto	语言代码
--instruct	否	-	风格控制或语音描述
--speed	否	1.0	语速倍率
--temperature	否	0.7	采样温度（越高变化越大）
--model	否	(per mode)	覆盖默认模型
--output	否	-	输出文件路径
--out-dir	否	./outputs	未设置 --output 时的输出目录
--ref_audio	VoiceClone	-	参考音频文件
--ref_text	VoiceClone	-	参考音频转录文本

Python API

使用 generate_audio（推荐）

from mlx_audio.tts.generate import generate_audio

# CustomVoice with style control
generate_audio(
    text="Hello from Qwen3-TTS!",
    model="mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-4bit",
    voice="Ryan",
    lang_code="english",
    instruct="friendly and warm",
    output_path=".",
    file_prefix="hello",
    audio_format="wav",
    join_audio=True,
    verbose=True,
)

直接使用 Model

from mlx_audio.tts.utils import load
import soundfile as sf
import numpy as np

# Load model
model = load("mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-4bit")

# Generate audio (returns a generator)
audio_chunks = []
for chunk in model.generate_custom_voice(
    text="Hello from Qwen3-TTS.",
    speaker="Ryan",
    language="english",
    instruct="clear, steady delivery"
):
    if hasattr(chunk, 'audio') and chunk.audio is not None:
        audio_chunks.append(chunk.audio)

# Combine and save
audio = np.concatenate(audio_chunks)
sf.write("output.wav", audio, 24000)

VoiceDesign

from mlx_audio.tts.generate import generate_audio

generate_audio(
    text="Welcome to the show.",
    model="mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-5bit",
    instruct="warm, friendly female narrator with medium pitch",
    lang_code="english",
    output_path=".",
    file_prefix="voice_design",
    join_audio=True,
)

VoiceClone

from mlx_audio.tts.generate import generate_audio

generate_audio(
    text="New content in the cloned voice.",
    model="mlx-community/Qwen3-TTS-12Hz-0.6B-Base-4bit",
    ref_audio="reference.wav",
    ref_text="Transcript of the reference audio",
    output_path=".",
    file_prefix="cloned",
    join_audio=True,
)

批量处理

使用 scripts/batch_dubbing.py 处理多行内容：

python scripts/batch_dubbing.py \
  --input dubbing.json \
  --out-dir outputs

JSON 格式请参阅 references/dubbing_format.md。

性能

指标	值
采样率	24,000 Hz
实时因子	~0.7x（快于实时）
峰值内存	~4-6 GB
首次运行	下载模型（~1-2GB）

故障排除

问题	解决方案
生成缓慢	使用 4-bit CustomVoice 模型
停顿不自然	添加标点，保持句子简短
检测到错误语言	明确指定 --lang_code
语音克隆质量不佳	使用更清晰的参考音频和准确的转录文本
分词器警告	无害，可忽略
内存不足	关闭其他应用，使用 4-bit 模型