---

name: qwen3-tts description: Qwen3-TTS 文本转语音技能，支持多语言语音合成、语音克隆和语音设计。当用户需要生成语音、转换文本为语音、或使用 TTS 功能时使用此技能。 allowed-tools: Bash(~/.local/bin/mlx_audio.tts.generate, uvx mlx_audio.tts.generate)

Qwen3-TTS 文本转语音

基于 MLX 框架的本地 TTS（文本转语音）解决方案，专为 Apple Silicon M 系列芯片优化。

快速开始

# 安装（仅需一次）
uv tool install --force mlx-audio --prerelease=allow

# 基础使用
~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "你好，欢迎体验 Qwen3-TTS！" \
  --voice "serena" \
  --play

使用已克隆的音色

当用户已经保存了克隆语音配置时（在 ~/.qwen3_tts_voices/ 目录下），可以直接使用保存的语音生成音频：

检查是否有保存的克隆语音

# 列出所有保存的语音
ls -1 ~/.qwen3_tts_voices/

使用保存的克隆语音（推荐方式）

# 使用 voice-clone.sh 脚本（最简单）
~/.claude/skills/qwen3-tts/templates/voice-clone.sh use my_voice "你好，这是测试。" --play

直接使用命令

# 读取配置文件获取参数
CONFIG_FILE="$HOME/.qwen3_tts_voices/my_voice/config.json"

# 如果配置文件存在，直接使用
if [ -f "$CONFIG_FILE" ]; then
  ~/.local/bin/mlx_audio.tts.generate \
    --model "mlx-community/Qwen3-TTS-12Hz-0.6B-Base-bf16" \
    --text "你好，这是测试。" \
    --ref_audio "$HOME/.qwen3_tts_voices/my_voice/reference.wav" \
    --ref_text "你好，这是我的声音克隆测试。今天天气真不错，我很高兴能体验这个功能。" \
    --lang_code "zh" \
    --play
fi

技能调用流程

当用户要求"使用我的音色"或类似请求时：

1. 检查保存的语音：ls ~/.qwen3_tts_voices/
2. 读取配置：cat ~/.qwen3_tts_voices/my_voice/config.json
3. 生成语音：使用 --ref_audio 和 --ref_text 参数

示例对话：

用户：用我的声音说"你好，世界"
AI：让我使用你保存的克隆语音来生成...
    [执行 voice-clone.sh use my_voice "你好，世界" --play]

可用模型

| 模型 | 大小 | 特点 | 用途 | |------|------|------|------| | Qwen3-TTS-12Hz-0.6B-Base-bf16 | 0.6B | 基础模型 | 语音克隆（推荐） | | Qwen3-TTS-12Hz-0.6B-CustomVoice-bf16 | 0.6B | 9 个预设语音 | 使用预设语音生成 | | Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 | 1.7B | 9 个预设语音 | 更高质量的预设语音 | | Qwen3-TTS-12Hz-1.7B-VoiceDesign-bf16 | 1.7B | 语音设计 | 创建自定义语音描述 |

CustomVoice 模型可用语音

中文语音

• serena - 温柔女声（推荐中文）
• vivian - 知性女声
• ryan - 成熟男声

英文语音

• aiden - 青年男声
• ono_anna - 日式女声
• sohee - 韩式女声
• eric - 欧美男声
• dylan - 青少年男声
• uncle_fu - 特色男声

基础用法

生成并播放语音

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "你好，这是一段测试语音。" \
  --voice "serena" \
  --play

保存语音文件

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "你好，这是保存的音频。" \
  --voice "vivian" \
  --file_prefix my_audio \
  --audio_format wav

高级用法

调整语速

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "这是加快语速的示例。" \
  --voice "serena" \
  --speed 1.5

使用温度控制语音多样性

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "同样的文本，不同的语气。" \
  --voice "serena" \
  --temperature 0.8

批量生成长文本

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "第一段。第二段。第三段。" \
  --voice "serena" \
  --split_pattern "。" \
  --join_audio

详细输出信息

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "显示详细生成信息。" \
  --voice "serena" \
  --verbose

语音克隆

重要：语音克隆必须使用 Base 模型

语音克隆应该使用 Base 模型，而不是 CustomVoice 模型！

Base 模型支持从参考音频克隆任意声音，而 CustomVoice 模型只支持预设语音。

基础克隆（正确方式）

# 使用 Base 模型进行语音克隆
~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-0.6B-Base-bf16 \
  --text "这是克隆的语音。" \
  --ref_audio /path/to/reference.wav \
  --ref_text "参考音频的文本内容"

注意：

• 使用 Base 模型，不是 CustomVoice
• 不需要 --voice 参数（让模型完全从参考音频克隆）
• 只需要 --ref_audio 和 --ref_text

参考音频要求

• 格式: WAV, MP3, FLAC, M4A 等常见格式
• 时长: 建议 3-10 秒
• 内容: 清晰的语音，无背景噪音
• 文本: --ref_text 必须与参考音频的内容完全匹配

引导用户录音流程

由于命令行录音需要用户确认，推荐使用以下步骤引导用户录音：

# 步骤 1: 引导用户使用 macOS 录音应用
echo "请按以下步骤录音："
echo "1. 打开「语音备忘录」应用"
echo "2. 点击红色录音按钮"
echo "3. 清晰朗读以下文本："
echo '   "你好，这是我的声音克隆测试。今天天气真不错，我很高兴能体验这个功能。"'
echo "4. 点击停止按钮"
echo "5. 将录音共享到桌面，命名为 'voice_reference.m4a'"
echo ""
echo "完成后告诉我，继续下一步..."

# 步骤 2: 查找桌面上的录音文件
# 用户录音完成后，查找最新的 m4a 文件
LATEST_AUDIO=$(ls -t ~/Desktop/*.m4a 2>/dev/null | head -1)

# 步骤 3: 转换音频格式（如果需要）
if [ -f "$LATEST_AUDIO" ]; then
  ffmpeg -i "$LATEST_AUDIO" -ar 24000 -ac 1 -acodec pcm_s16le ~/reference.wav -y
  echo "音频已转换: ~/reference.wav"
fi

# 步骤 4: 使用 Base 模型进行语音克隆
~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-0.6B-Base-bf16 \
  --text "你好，这是测试语音克隆效果。" \
  --ref_audio ~/reference.wav \
  --ref_text "你好，这是我的声音克隆测试。今天天气真不错，我很高兴能体验这个功能。" \
  --play

保存和复用克隆语音

使用 templates/voice-clone.sh 脚本可以保存克隆语音配置：

# 首次克隆并保存配置
./templates/voice-clone.sh save my_voice \
  --ref_audio ~/reference.wav \
  --ref_text "你好，这是我的声音克隆测试。今天天气真不错，我很高兴能体验这个功能。"

# 之后直接使用保存的语音
./templates/voice-clone.sh use my_voice "这是要生成的新文本" --play

语音配置保存在 ~/.qwen3_tts_voices/ 目录，包含：

• config.json - 语音配置（参考音频路径、文本等）
• 参考音频文件的副本

完整工作流程示例：

# 1. 引导用户录音（使用语音备忘录）
# 见上面的"引导用户录音流程"

# 2. 保存为克隆语音
./templates/voice-clone.sh save my_custom_voice \
  --ref_audio ~/reference.wav \
  --ref_text "你好，这是我的声音"

# 3. 使用克隆语音生成任意文本
./templates/voice-clone.sh use my_custom_voice "今天天气真好" --play

# 4. 查看所有保存的语音
./templates/voice-clone.sh list

批量克隆管理

# 列出所有保存的克隆语音
./templates/voice-clone.sh list

# 删除某个克隆语音
./templates/voice-clone.sh delete my_voice

# 更新克隆语音的参考音频
./templates/voice-clone.sh update my_voice --ref_audio ~/new_reference.wav

参数说明

| 参数 | 说明 | 默认值 | |------|------|--------| | --model | 模型路径或 HuggingFace ID | mlx-community/Kokoro-82M-bf16 | | --text | 要转换的文本 | 从 stdin 读取 | | --voice | 语音名称（仅 CustomVoice 模型需要） | 模型默认 | | --speed | 播放速度 | 1.0 | | --temperature | 采样温度 (0.1-1.5) | 0.7 | | --top_p | Top-p 采样 | 0.9 | | --top_k | Top-k 采样 | 50 | | --max_tokens | 最大生成 token 数 | 1200 | | --file_prefix | 输出文件前缀 | audio | | --audio_format | 音频格式 (wav/flac/mp3) | wav | | --play | 播放生成的音频 | false | | --join_audio | 合并多个音频段 | false | | --split_pattern | 分段模式 | \n | | --verbose | 显示详细信息 | false | | --ref_audio | 参考音频路径（语音克隆必需） | null | | --ref_text | 参考音频文本（语音克隆必需） | null | | --lang_code | 语言代码（如 zh, en） | 自动检测 |

输出格式

控制台输出

Text: 你好，欢迎体验 Qwen3-TTS！
Voice: None  # Base 模型显示 None
Speed: 1.0x
Language: zh
==========
Duration:              00:00:08.123
Samples/sec:           24000.0
Prompt:                245 tokens, 30.12 tokens-per-sec
Audio:                 194952 samples, 24000.0 samples-per-sec
Real-time factor:      0.42x
Processing time:       19.32s
Peak memory usage:     2.15GB
✅ Audio successfully generated and saving as: audio_000.wav

文件输出

• 默认输出为 WAV 格式
• 采样率：24000 Hz
• 文件命名：{file_prefix}_{索引:03d}.{audio_format}

使用 uvx（无需安装）

uvx mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-0.6B-Base-bf16 \
  --text "使用 uvx 运行" \
  --ref_audio reference.wav \
  --ref_text "参考文本"

常见问题

1. 语音克隆不像我的声音

• 确保使用 Base 模型，不是 CustomVoice 模型
• 确保 --ref_text 与参考音频内容完全匹配
• 参考音频应清晰、无背景噪音
• 尝试使用更长的参考音频（5-10 秒）

2. 音频无法播放

确保已安装音频驱动：

# macOS 自带 afplay
afplay audio_000.wav

# 或使用 ffplay（需要安装 ffmpeg）
brew install ffmpeg
ffplay audio_000.wav

3. 内存不足

• 使用较小的模型（0.6B）
• 减少 --max_tokens 值
• 关闭其他应用释放内存

4. 中文发音不准

• 使用 --lang_code zh 参数
• 调整 --temperature 参数
• 使用 --speed 调整语速

5. 生成速度慢

• 正常现象，实时因子约为 0.3-0.5x
• 即生成 10 秒音频需要 20-30 秒

实用脚本

Ready-to-use 模板脚本

templates/ 目录提供了多个开箱即用的脚本：

| 脚本 | 描述 | |------|------| | simple-tts.sh | 简单语音生成，适合快速测试 | | batch-tts.sh | 批量生成多种语音的相同文本 | | file-to-tts.sh | 从文本文件读取并生成语音 | | voice-clone.sh | 语音克隆管理（保存、使用、列表、删除） | | record-reference.sh | 录制参考音频用于语音克隆 |

使用示例：

# 快速生成语音
./templates/simple-tts.sh "你好，世界" "serena"

# 录制参考音频
./templates/record-reference.sh my_voice.wav 5

# 保存并使用克隆语音
./templates/voice-clone.sh save my_voice \
  --ref_audio my_voice.wav \
  --ref_text "你好，世界"

./templates/voice-clone.sh use my_voice "新的文本内容" --play

批量生成多个语音

#!/bin/bash
TEXT="你好，这是测试文本。"

for voice in serena vivian ryan; do
  ~/.local/bin/mlx_audio.tts.generate \
    --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
    --text "$TEXT" \
    --voice "$voice" \
    --file_prefix "output_${voice}" \
    --audio_format wav
done

从文件读取文本

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --voice "serena" \
  --play \
  < input.txt

流式生成（边生成边播放）

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "这是一段很长的文本..." \
  --voice "serena" \
  --stream \
  --streaming_interval 2.0

Python API 用法

from mlx_audio.tts.utils import load_model
import sounddevice as sd
import numpy as np

# 加载模型
model = load_model("mlx-community/Qwen3-TTS-12Hz-0.6B-Base-bf16")

# 语音克隆
text = "你好，这是测试语音克隆效果。"
results = list(model.generate(
    text=text,
    ref_audio="reference.wav",
    ref_text="你好，这是我的声音克隆测试。今天天气真不错，我很高兴能体验这个功能。",
    verbose=True
))

# 播放音频
audio = results[0].audio
sample_rate = results[0].sample_rate
sd.play(np.array(audio), sample_rate)
sd.wait()

技术规格

• 框架: MLX (Apple Silicon 优化)
• 采样率: 24000 Hz
• 音频编码: SNAC (SoundStream)
• 基础模型: Qwen3 (12Hz)
• 支持语言: 中文、英文、日文、韩文等多语言
• 硬件要求: Apple Silicon (M1/M2/M3/M4)
• Python 要求: 3.10+

参考资源

• MLX-Audio GitHub
• Qwen3-TTS 模型页面
• MLX 官方文档
• mlx-community Qwen3-TTS Collection