# Qwen3-TTS 本地对白生成环境使用说明

## 环境位置

- 虚拟环境：`/home/ubuntu/SoundGame/.venv-tts`（Python 3.12.14，uv 创建）
- 关键包：`torch 2.11.0+cu128`、`torchaudio 2.11.0+cu128`、`qwen-tts 0.1.1`、`soundfile`、`transformers 4.57.3`
- 模型缓存：`/home/ubuntu/SoundGame/models/hf`（HF_HOME）
  - `Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice`（预置音色 + 情感指令，主力）
  - `Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign`（文字描述造音色）
  - `Qwen/Qwen3-TTS-Tokenizer-12Hz`（语音编解码器，上面两个模型自带副本，这个是独立的）

## 启用环境

```bash
source /home/ubuntu/SoundGame/env.d/tts.sh   # 设置 HF_HOME / HF_ENDPOINT(hf-mirror 镜像)
source /home/ubuntu/SoundGame/.venv-tts/bin/activate
```

注意：本机连不通 huggingface.co，必须走 `HF_ENDPOINT=https://hf-mirror.com`（tts.sh 已设好）。

## 生成对白（CustomVoice：预置音色 + 情感指令）

```python
import torch, soundfile as sf
from qwen_tts import Qwen3TTSModel

model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
    device_map="cuda:0",
    dtype=torch.bfloat16,
)
wavs, sr = model.generate_custom_voice(
    text="快躲开！它来了！",
    language="Chinese",
    speaker="Vivian",
    instruct="用惊恐、急促的语气大声喊出来",   # 不需要情感控制时省略
)
sf.write("out.wav", wavs[0], sr)   # sr = 24000
```

支持批量：`text`/`language`/`speaker`/`instruct` 均可传等长 list。
可透传 HF `generate` 参数，如 `max_new_tokens=2048`。

## VoiceDesign（文字描述造音色）

```python
model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign",
    device_map="cuda:0", dtype=torch.bfloat16,
)
wavs, sr = model.generate_voice_design(
    text="哥哥，你回来啦！",
    language="Chinese",
    instruct="撒娇稚嫩的萝莉女声，音调偏高且起伏明显",
)
```

## 预置音色查询

代码查询：

```python
model.get_supported_speakers()   # ['aiden','dylan','eric','ono_anna','ryan','serena','sohee','uncle_fu','vivian']
model.get_supported_languages()  # auto/chinese/english/french/german/italian/japanese/korean/portuguese/russian/spanish
```

中文对白推荐音色（母语中文）：

| speaker | 描述 |
|---|---|
| Vivian | 明亮略带锋芒的年轻女声 |
| Serena | 温暖柔和的年轻女声 |
| Uncle_Fu | 低沉醇厚的中年男声 |
| Dylan | 北京话年轻男声 |
| Eric | 四川话活泼男声，略带沙哑 |

（其余：Ryan/Aiden 英语男声，Ono_Anna 日语女声，Sohee 韩语女声）

## 冒烟测试

```bash
/home/ubuntu/SoundGame/.venv-tts/bin/python /home/ubuntu/SoundGame/tools/tts_smoke_test.py
# 输出 /home/ubuntu/SoundGame/tools/samples/tts_test.wav（实测 1.92s, 24kHz）
```

## Web UI（可选）

```bash
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --ip 0.0.0.0 --port 8000
```

## 已知事项

- 未装 `flash-attn`（可选加速，编译耗时长；RTX 3090 24GB 不装也完全够用，加载+生成一句仅十几秒）。
- 系统无 `sox` 命令行二进制（无 sudo 装不了），qwen-tts 会打印警告但**不影响生成**；只有用到 sox 音频处理链路时才需要它。
- 显存占用：1.7B 模型 bf16 推理远低于 24GB，充足。