SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsqwen3-tts-skills

qwen3-tts-skills

Design & creation

View repository

Updated 10-15 23:44

About this skill

Qwen3-TTS Skill

A complete workflow for converting text into high-quality speech.

🚀 Quick Start

Scenario 1: Single-sentence speech generation

Call the script directly to generate speech:

# 中文语音（默认 Vivian 女声）
uv run qwen3-tts-skills/scripts/run_qwen3_tts.py custom-voice \
  --language Chinese \
  --text "你好，欢迎使用语音合成。" \
  --out-dir outputs
English speech (default Ryan male voice)

uv run qwen3-tts-skills/scripts/run_qwen3_tts.py custom-voice
--language English
--text "Hello, welcome to text-to-speech."
--out-dir outputs


### 场景 2：长文稿批量配音

将文章转换为完整语音文件：

User manuscript → [AI analysis generates dubbing script] → [User review] → [Batch TTS] → Complete speech.wav


详见下方 **[长文稿批量配音](#-长文稿批量配音生成)** 章节。

---

## 📋 模型选择指南

根据需求选择合适的模型：

| 模式 | 模型 | 适用场景 | 命令 |
|------|------|----------|------|
| **CustomVoice** | `Qwen3-TTS-12Hz-1.7B-CustomVoice` | 使用内置音色 + 情感控制 | `custom-voice` |
| **VoiceDesign** | `Qwen3-TTS-12Hz-1.7B-VoiceDesign` | 用自然语言描述想要的音色 | `voice-design` |
| **VoiceClone** | `Qwen3-TTS-12Hz-1.7B-Base` | 克隆参考音频的声音 | `voice-clone` |
| **Tokenizer** | `Qwen3-TTS-Tokenizer-12Hz` | 音频编解码 | `tokenizer-roundtrip` |

### 内置 Speaker（CustomVoice 模式）

| 语言 | 默认 Speaker | 说明 |
|------|-------------|------|
| Chinese | Vivian | 女声，自然 |
| English | Ryan | 男声 |
| Japanese | Ono_Anna | 女声 |
| Korean | Sohee | 女声 |

---

## 🎙️ 单句语音生成

### CustomVoice（推荐入门）

使用内置音色，可选情感控制：

```bash
uv run qwen3-tts-skills/scripts/run_qwen3_tts.py custom-voice \
  --language Chinese \
  --text "其实我真的有发现，我是一个特别善于观察别人情绪的人。" \
  --speaker Vivian \
  --instruct "轻松愉快的语气" \
  --out-dir outputs

Parameter description：

  • --language：Chinese / English / Japanese / Korean
  • --speaker: Optional, if not filled, the default is automatically selected based on language
  • --instruct: Optional, emotion/tone control (e.g. "speak happily", "low and slow")
  • --output: Optional, specify the output filename (by default a timestamped filename is automatically generated)

VoiceDesign (design a unique timbre)

Describe the desired timbre in natural language:

uv run qwen3-tts-skills/scripts/run_qwen3_tts.py voice-design \
  --language Chinese \
  --text "哥哥，你回来啦，人家等了你好久好久了，要抱抱！" \
  --instruct "体现撒娇稚嫩的萝莉女声，音调偏高且起伏明显。" \
  --out-dir outputs

Note: VoiceDesign's --instruct isrequired, used to describe timbre characteristics.

VoiceClone (voice cloning)

Clone the voice of a reference audio:

uv run qwen3-tts-skills/scripts/run_qwen3_tts.py voice-clone \
  --language English \
  --ref-audio "path/to/reference.wav" \
  --ref-text "参考音频的文本内容" \
  --text "要合成的新文本" \
  --out-dir outputs

Parameter description：

  • --ref-audio: Reference audio file path or URL
  • --ref-text: Text corresponding to the reference audio (required)
  • --x-vector-only-mode: Optional, use only speaker features (quality may decrease)

⚠️ Note: VoiceClone does not support --instruct emotion control.

Tokenizer (audio encoding and decoding)

Used for audio encoding and decoding verification:

uv run qwen3-tts-skills/scripts/run_qwen3_tts.py tokenizer-roundtrip \
  --audio "path/to/audio.wav" \
  --out-dir outputs

🎬 Long-form batch dubbing generation

Convert long articles, scripts, and audiobook content into complete speech files.

Workflow

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Step 1         │     │  Step 2         │     │  Step 3         │     │  输出           │
│  AI分析文稿     │ ──→ │  用户审核修改   │ ──→ │  批量生成语音   │ ──→ │  完整语音.wav   │
│  生成配音稿JSON │     │  保存.json文件  │     │  FFmpeg合并     │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘

Step 1: Have the AI generate a dubbing script

Say to the AI:"Convert the following article into speech" + paste the article content

The AI will follow the rules of dubbing-skills/SKILL.md :

  1. Intelligent segmentation (200-300 characters per paragraph)
  2. Identify characters (【旁白】、【小明】 , etc.)
  3. Analyze emotion, generate instruct
  4. Output the dubbing script JSON

Step 2: User review and modification

Check the JSON and adjust:

  • Whether the segmentation is reasonable
  • Whether the character assignment is correct
  • Emotion instruct whether it is appropriate
  • Whether the TTS mode needs adjustment

Save as article.dubbing.json file.

Step 3: Batch generate speech

uv run qwen3-tts-skills/scripts/batch_dubbing.py \
  --input article.dubbing.json \
  --out-dir outputs

Parameter description：

Parameter Description Default value
--input Dubbing script JSON file Required
--out-dir Output directory outputs
--silence-gap Silence between normal paragraphs (seconds) 0.3
--character-switch-gap Silence when switching characters (seconds) 0.5
--clean-segments Delete intermediate segments after merging Keep

Output structure

outputs/
├── segments/
│   ├── seg_001_旁白.wav
│   ├── seg_002_小明.wav
│   └── ...
├── article.dubbing.json   # 配音稿备份
└── article_final.wav      # 最终完整语音

Three supported modes

Mode Description Use cases
custom-voice Built-in timbre + emotion instructions Most scenarios (default)
voice-design Natural language voice description Requires a specific voice (loli, older man, etc.)
voice-clone Clone reference audio Requires a real/specific person's voice

🔧 Environment Setup

Recommended method: use uv run directly

Dependencies are already declared in the script, no manual installation needed:

uv run qwen3-tts-skills/scripts/run_qwen3_tts.py -h

Create a fixed virtual environment

uv venv --python 3.12
.\.venv\Scripts\activate
uv pip install -U qwen-tts

Install FlashAttention 2 (optional, reduces VRAM usage)

uv pip install -U flash-attn --no-build-isolation

# 内存 < 96GB 时限制并行任务
MAX_JOBS=4 uv pip install -U flash-attn --no-build-isolation

Usage conditions：

  • Hardware is compatible with FlashAttention 2
  • The model is loaded with torch.float16 or torch.bfloat16 Load

Install FFmpeg (required for batch dubbing)

Windows：

choco install ffmpeg -y

Verify installation:

ffmpeg -version

📥 Offline Model Download

Use ModelScope (recommended for mainland China)

uv pip install -U modelscope
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local_dir ./Qwen3-TTS-12Hz-1.7B-CustomVoice
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign --local_dir ./Qwen3-TTS-12Hz-1.7B-VoiceDesign
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-Base --local_dir ./Qwen3-TTS-12Hz-1.7B-Base
modelscope download --model Qwen/Qwen3-TTS-Tokenizer-12Hz --local_dir ./Qwen3-TTS-Tokenizer-12Hz

Use Hugging Face

uv pip install -U "huggingface_hub[cli]"
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local-dir ./Qwen3-TTS-12Hz-1.7B-CustomVoice
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign --local-dir ./Qwen3-TTS-12Hz-1.7B-VoiceDesign
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base --local-dir ./Qwen3-TTS-12Hz-1.7B-Base
huggingface-cli download Qwen/Qwen3-TTS-Tokenizer-12Hz --local-dir ./Qwen3-TTS-Tokenizer-12Hz

🖥️ Local Web UI Demo

# 查看帮助
qwen-tts-demo --help

# 启动 CustomVoice
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --ip 0.0.0.0 --port 8000

# 启动 VoiceDesign
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign --ip 0.0.0.0 --port 8000

HTTPS support (resolves microphone permission issues)

# 生成自签名证书
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost"

# 启用 HTTPS
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-Base \
  --ip 0.0.0.0 --port 8000 \
  --ssl-certfile cert.pem \
  --ssl-keyfile key.pem \
  --no-ssl-verify

📚 Reference Documentation

Document Description
dubbing-skills/SKILL.md Dubbing script generation specification (for AI reading)
dubbing-skills/references/dubbing_format.md Detailed specification of the dubbing script JSON format
dubbing-skills/references/examples.md Dubbing script examples for various scenarios
references/python_api.md Python API integration guide

⚡ Performance Parameters

uv run qwen3-tts-skills/scripts/run_qwen3_tts.py custom-voice \
  --device-map cuda:0 \
  --dtype bfloat16 \
  --attn flash_attention_2 \
  --language Chinese \
  --text "测试文本" \
  --out-dir outputs
Parameter Description
--device-map Specify GPU (e.g. cuda:0) or CPU
--dtype Data type: auto / bfloat16 / float16 / float32
--attn Attention implementation: auto / flash_attention_2

❓ FAQ

Windows path issues

Absolute paths need to be wrapped in double quotes:

uv run "C:/Users/lee/.config/alma/skills/qwen3-tts-skills/scripts/run_qwen3_tts.py" -h

SoX warning

If you see SoX could not be found!, install SoX (does not affect functionality, only eliminates the warning):

choco install sox.portable -y

Slow model download

Prefer using ModelScope (mainland China) or download to a local directory in advance.