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

模型变体

支持的语言

内置语音

语音选择指南：

运行模式

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 参数说明

Python API

使用 generate_audio（推荐）

from mlx_audio.tts.generate import generate_audio

# CustomVoice 模式 + 风格控制
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

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

# 生成音频（返回生成器）
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)

# 合并并保存
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。

性能指标

常见问题排查