Qwen TTS

使用Hugging Face的Qwen3-TTS-12Hz-1.7B-CustomVoice模型进行本地文本转语音。

快速开始

从文本生成语音：

scripts/tts.py "Ciao, come va?" -l Italian -o output.wav

带语音指令（情感/风格）：

scripts/tts.py "Sono felice!" -i "Parla con entusiasmo" -l Italian -o happy.wav

不同说话者：

scripts/tts.py "Hello world" -s Ryan -l English -o hello.wav

安装

首次设置（一次性操作）：

cd skills/public/qwen-tts
bash scripts/setup.sh

这将创建一个本地虚拟环境并安装qwen-tts包（约500MB）。

注意：首次合成时会自动从Hugging Face下载约1.7GB的模型。

使用

scripts/tts.py [options] "Text to speak"

选项

• -o, --output 路径- 输出文件路径（默认：qwen_output.wav）
• -s, --speaker 名称- 说话者声音（默认：Vivian）
• -l, --language 语言- 语言（默认：自动）
• -i, --instruct TEXT- 语音指令（情感、风格、语调）
• --list-speakers- 显示可用发言人
• --model NAME- 模型名称（默认：CustomVoice 1.7B）

示例

基础意大利语语音：

scripts/tts.py "Benvenuto nel futuro del text-to-speech" -l Italian -o welcome.wav

带情感/指令：

scripts/tts.py "Sono molto felice di vederti!" -i "Parla con entusiasmo e gioia" -l Italian -o happy.wav

不同发言人：

scripts/tts.py "Hello, nice to meet you" -s Ryan -l English -o ryan.wav

列出可用发言人：

scripts/tts.py --list-speakers

可用发言人

CustomVoice 模型包含 9 种优质语音：

推荐：为获得最佳音质，建议使用每位发言者的母语，不过所有发言者均支持全部10种语言（中文、英语、日语、韩语、德语、法语、俄语、葡萄牙语、西班牙语、意大利语）。

语音指令

使用-i, --instruct用于控制情感、语调和风格：

意大利语示例：

• "热情洋溢地说话"
• "严肃且专业的语气"
• "平静且令人放松的声音"
• "像旁白者一样朗读"

英语示例：

• "以兴奋的语气说话"
• "非常快乐且充满活力"
• "平静且抚慰人心的声音"
• "像旁白者一样朗读"

与 OpenClaw 集成

脚本将音频文件路径输出到标准输出（最后一行），使其与 OpenClaw 的 TTS 工作流兼容：

# OpenClaw captures the output path
cd skills/public/qwen-tts
OUTPUT=$(scripts/tts.py "Ciao" -s Vivian -l Italian -o /tmp/audio.wav 2>/dev/null)
# OUTPUT = /tmp/audio.wav

性能

• GPU（CUDA）：短句约需 1-3 秒
• CPU：短句约需 10-30 秒
• 模型大小：约 1.7GB（首次运行时自动下载）
• 虚拟环境大小：约500MB（已安装依赖项）

故障排除

安装失败：

# Ensure Python 3.10-3.12 is available
python3.12 --version

# Re-run setup
cd skills/public/qwen-tts
rm -rf venv
bash scripts/setup.sh

模型下载缓慢/失败：

# Use mirror (China mainland)
export HF_ENDPOINT=https://hf-mirror.com
scripts/tts.py "Test" -o test.wav

内存不足（GPU）：若GPU内存不足，模型将自动回退至CPU运行。

音频质量问题：

• 尝试更换说话人：--list-speakers
• 添加指令：-i "请清晰且缓慢地说话"
• 检查语言是否与文本匹配：-l Italian用于意大利语文本

模型详情

• 模型：Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice
• 来源：Hugging Face (https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice)
• 许可证：请查看模型卡片以获取当前许可条款
• 采样率：16千赫
• 输出格式：WAV（未压缩）