介绍
# Qwen TTS
使用 Hugging Face 的 Qwen3-TTS-12Hz-1.7B-CustomVoice 模型的本地文本转语音功能。
## 快速开始
从文本生成语音：
```bash scripts/tts.py "Ciao, come va?" -l Italian -o output.wav ```
带语音指令（情感/风格）：
```bash scripts/tts.py "Sono felice!" -i "Parla con entusiasmo" -l Italian -o happy.wav ```
不同说话人：
```bash scripts/tts.py "Hello world" -s Ryan -l English -o hello.wav ```
## 安装
**首次设置**（仅需一次）：
```bash cd skills/public/qwen-tts bash scripts/setup.sh ```
这将创建一个本地虚拟环境并安装 `qwen-tts` 包（约 500MB）。
**注意：** 首次合成时会自动从 Hugging Face 下载约 1.7GB 的模型。
## 使用方法
```bash scripts/tts.py [options] "Text to speak" ```
### 选项
- `-o, --output PATH` - 输出文件路径（默认：qwen_output.wav） - `-s, --speaker NAME` - 说话人声音（默认：Vivian） - `-l, --language LANG` - 语言（默认：Auto） - `-i, --instruct TEXT` - 语音指令（情感、风格、语气） - `--list-speakers` - 显示可用的说话人 - `--model NAME` - 模型名称（默认：CustomVoice 1.7B）
### 示例
**基础意大利语语音：** ```bash scripts/tts.py "Benvenuto nel futuro del text-to-speech" -l Italian -o welcome.wav ```
**带情感/指令：** ```bash scripts/tts.py "Sono molto felice di vederti!" -i "Parla con entusiasmo e gioia" -l Italian -o happy.wav ```
**不同的说话人：** ```bash scripts/tts.py "Hello, nice to meet you" -s Ryan -l English -o ryan.wav ```
**列出可用的说话人：** ```bash scripts/tts.py --list-speakers ```
## 可用说话人
CustomVoice 模型包含 9 种优质声音：
| Speaker | Language | Description | |---------|----------|-------------| | Vivian | Chinese | 明亮、略带个性的年轻女性 | | Serena | Chinese | 温暖、温柔的年轻女性 | | Uncle_Fu | Chinese | 沉稳的男性，低沉醇厚的音色 | | Dylan | Chinese (Beijing) | 充满活力的北京男性，清晰 | | Eric | Chinese (Sichuan) | 充满活力的成都男性，沙哑 | | Ryan | English | 动感男性，有节奏感 | | Aiden | English | 阳光美式男性 | | Ono_Anna | Japanese | 俏皮女性，轻快敏捷 | | Sohee | Korean | 温暖女性，情感丰富 |
**建议：** 为获得最佳质量，请使用各说话人的母语，尽管所有说话人都支持全部 10 种语言（中文、英文、日文、韩文、德文、法文、俄文、葡萄牙文、西班牙文、意大利文）。
## 语音指令
使用 `-i, --instruct` 来控制情感、语气和风格：
**意大利语示例：** - `"Parla con entusiasmo"` - `"Tono serio e professionale"` - `"Voce calma e rilassante"` - `"Leggi come un narratore"`
**英语示例：** - `"Speak with excitement"` - `"Very happy and energetic"` - `"Calm and soothing voice"` - `"Read like a narrator"`
## 与 OpenClaw 集成
该脚本将音频文件路径输出到 stdout（最后一行），使其与 OpenClaw 的 TTS 工作流兼容：
```bash # 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（已安装的依赖项）
## 故障排除
**设置失败：** ```bash # 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 ```
**模型下载缓慢/失败：** ```bash # Use mirror (China mainland) export HF_ENDPOINT=https://hf-mirror.com scripts/tts.py "Test" -o test.wav ```
**内存不足 (GPU)：** 如果 GPU 显存不足，模型将自动回退到 CPU。
**音频质量问题：** - 尝试不同的说话人：`--list-speakers` - 添加指令：`-i "Speak clearly and slowly"` - 检查语言与文本匹配：意大利语文本使用 `-l Italian`
## 模型详情
- **Model:** Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice - **Source:** Hugging Face (https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice) - **License:** 请查看模型卡以了解当前的许可条款 - **Sample Rate:** 16kHz - **Output Format:** WAV (未压缩)