# 阿里云百炼 TTS 文档

> 当前线上同时支持 Edge TTS(免费) 和 阿里云百炼(付费,听感更自然)。

**项目当前默认:** Edge TTS(因为免费),阿里云是降级/fallback 选项。要切换默认改 `server/src/config/models.json` 的 `tts.defaultVendor: bailian`。

---

## 📑 文档导览

| 文档 | 内容 |
|------|------|
| 👉 **本文档 (`tts-aliyun-voice.md`)** | 配置 + 项目默认音色 + CosyVoice/Qwen-TTS 指令指南 + Qwen-TTS 完整 48 音色 + 4 个 CosyVoice 模型的系统音色摘要 |
| [`alicloud-tts-lang-voice-matrix.md`](alicloud-tts-lang-voice-matrix.md) | 模型 × 语言 × 音色 矩阵 — **"用户选语言"功能核心数据库** |
| [`cosyvoice-voice-design.md`](cosyvoice-voice-design.md) | 声音设计完整指南(基于阿里云官方页) — v3.5 / v3 / Qwen-TTS 都支持,文本描述即可创建新音色 |
| [`qwen-tts-voices-full.md`](qwen-tts-voices-full.md) | Qwen-TTS 详细附录(含分类速查表) |

**相关但独立的文档:**
- [`tts-edge-languages.md`](tts-edge-languages.md) — Edge TTS 75 语言 / 316 音色
- [`tts-comprehensive.md`](tts-comprehensive.md) — TTS 系统总览(跨 vendor 比较)

---

## 1. 关键配置文件

### 1. `server/.env`

```bash
DASHSCOPE_API_KEY=sk-c25679401ba24c749f53be86b0c9a7a6
DASHSCOPE_MODEL=qwen3-tts-instruct-flash  # 默认 TTS 模型
DASHSCOPE_TTS_MODELS=qwen3-tts-flash      # 备用模型列表(逗号分隔)
DASHSCOPE_VOICE=Cherry                   # Qwen-TTS 默认音色
DASHSCOPE_USE_REALTIME=true              # 启用流式 WebSocket
DASHSCOPE_REALTIME_MODEL=qwen3-tts-instruct-flash-realtime
```

### 2. `server/src/config/models.json`

TTS 供应商注册(在 vendor registry 里维护):

```json
{
  "tts": {
    "defaultVendor": "edge",                    // 当前默认
    "defaultModel": "edge-tts",
    "defaultVoice": "zh-CN-XiaoxiaoNeural",
    "bailian": {
      "priority": 3,
      "models": [
        { "id": "cosyvoice-v3-flash",   "enabled": true },
        { "id": "qwen3-tts-instruct-flash", "enabled": true },
        { "id": "qwen3-tts-flash",        "enabled": true }
      ]
    }
  }
}

### 3. `server/src/modules/tts/tts.service.ts:243` ALIYUN_VOICE_MAP

前端统一 ID(voice_01~voice_10)→ 阿里云真实音色的映射(代码里):

| 前端 ID | 阿里云音色 | 描述 |
|---------|------------|------|

> 命名规律:"龙"+性格(安欢/安洋/呼呼/媛/逸尘/老伯/华/硕/安柔/泡泡),"_v3" 后缀是 cosyvoice V3 模型系列。

## 阿里云 TTS 模型对照

| 模型 ID | 系列 | 特点 | 项目是否启用 |
|---------|------|------|-------------|
| `cosyvoice-v3-flash` | CosyVoice | 中文专精,支持方言和情感 instruct,**降速是模型级**(非后处理) | ✅ |
| `cosyvoice-v2` | CosyVoice | 中文 V2,质量好但慢 | ❌(备用) |
| `qwen3-tts-instruct-flash` | Qwen-TTS | 多语言,支持自然语言 instruct("语速较慢") | ✅(.env 默认) |
| `qwen3-tts-flash` | Qwen-TTS | 多语言快速版 | ✅(备用) |

## 当前默认音色: Cherry

- **模型:** `qwen3-tts-instruct-flash`
- **音色名:** Cherry
- **性别:** 女声
- **支持语言:** 中文(普通话)、英文、粤语等

要换音色:

```bash
# .env
DASHSCOPE_VOICE=longanhuan_v3   # 或 voice_01(代码会映射)

# 或者直接传 ID(只对 cosyvoice 有效)
DASHSCOPE_VOICE=longyichen_v3  # 龙逸尘阳光男声
```

## 切换整个 vendor 到阿里云(全量替换 Edge TTS)

编辑 `server/src/config/models.json`:

```diff
   "tts": {
-    "defaultVendor": "edge",
+    "defaultVendor": "bailian",
     "defaultModel": "qwen3-tts-instruct-flash",
     "defaultVoice": "Cherry"
   }
```

然后 `pm2 restart server` 即可,所有新生成的音频都会走阿里云(消耗 dashscope 余额)。

## 完整 voice 列表

完整 48 个 Qwen-TTS 音色已抓取并存放在独立文档:**[`docs/qwen-tts-voices-full.md`](qwen-tts-voices-full.md)**。

| 类别 | 数量 | 代表 |
|------|------|------|
| 标准中文 | ~20 | 芊悦(Cherry,默认)、苏瑶、晨煦、四月、凯、安德雷、阿闻 |
| 中文方言 | 10 | 上海-阿珍、北京-晓东、南京-老李、陕西-秦川、闽南-阿杰、天津-李彼得、四川-晴儿/程川、粤语-阿强/阿清 |
| 角色/特色 | ~10 | 萌宝(小萝莉)、十三(小暴躁)、沧明子(老者)、徐大爷(烟嗓)、沙小弥(小大人)、燕铮莺(江湖)、田叔(说书) |
| 欧美外语 | 8 | 詹妮弗/艾登(美语)、莱恩(德语)、埃米尔安(法语)、博德加(西班牙)、索尼莎(拉美)、多尔切(意)、素熙(韩)、阿列克(俄) |
| 其他外语 | 2 | 小野杏(日)、拉迪奥·戈尔(葡,足球解说) |

**CosyVoice 完整音色列表待后续从 https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list 抓取补全**(同样的 playwright 流程,见 `scripts/scrape-alicloud-qwen-tts.js` 和 `scripts/parse-qwen-tts-dom.js`)。

### 已知 / 项目支持(从代码汇总)

| 音色 | 系列 | 性别 | 描述 |
|------|------|------|------|
| `Cherry` | Qwen-TTS | 女 | Qwen-TTS 默认,中文/英文 |
| `longanhuan_v3` | CosyVoice | 女 | 元气女声,支持 Instruct |
| `longanyang` | CosyVoice | 男 | 阳光男声,支持 Instruct |
| `longhuhu_v3` | CosyVoice | 女童 | 飞天泡泡音,支持 Instruct |
| `longyuan_v3` | CosyVoice | 女 | 温暖治愈 |
| `longyichen_v3` | CosyVoice | 男 | 阳光活力,支持 Instruct |
| `longlaobo_v3` | CosyVoice | 男 | 沧桑老伯 |
| `longhua_v3` | CosyVoice | 女 | 元气甜美 |
| `longshuo_v3` | CosyVoice | 男 | 清朗男声 |
| `longanrou_v3` | CosyVoice | 女 | 温柔闺蜜,支持 Instruct |
| `longpaopao_v3` | CosyVoice | 女童 | 飞天泡泡音,支持 Instruct |

> 注:CosyVoice V3 系列里更多音色(龙小白/龙大叔/龙小美等)代码里没引用,需要时直接换 `.env` 的 `DASHSCOPE_VOICE` 即可(API 不校验)。

## 语速控制差异(对比 Edge TTS)

| 实现 | 等价于播放器减速? | 听感自然度 |
|------|-------------------|----------|
| **Edge TTS `--rate=-22%`** | **是**(后处理拉伸) | 一般 |
| **Qwen-TTS Instruct "语速较慢"** | **否**(模型级慢生成) | **更好**(模型重新设计停顿和韵律) |

结论:
- Edge TTS 路径下,所有 voiceParams.speed 都被忽略(强制 1.0)。用户想减速用播放器 UI 倍速按钮(详情见 commit dd1fea03)。
- 阿里云路径下,preserve speed 参数,通过 instruct("语速较慢")传给模型,听感更好。

## 常见问题

**Q: 阿里云音色比 Edge TTS 贵多少?**

A: 阿里云按字符计费,cosyvoice-v3-flash 价格约 ¥0.00003/字,4000 字章节音频约 ¥0.12。qwen-tts 类似价。Edge TTS 免费。

**Q: 怎么测试某个音色?**

```bash
# 1. 在 .env 改 DASHSCOPE_VOICE=longyichen_v3
# 2. 调用 /api/tts/generate 走默认 vendor=bailian 路径
# 3. 或在 models.json 把 defaultVendor 改成 bailian
```

**Q: 音色 ID 拼错了会怎样?**

A: 阿里云不会本地验证,直接发 HTTP 请求,服务端返回 400 或用默认音色(不会报错)。

## CosyVoice 指令使用指南(重要)

> 来源:阿里云官方文档 https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list,2025-07-12 摘录。
> 本项目用的是 `cosyvoice-v3-flash`(默认)和 `qwen3-tts-instruct-flash`,下面的指令规则适用。

### 支持的 4 个模型

| 模型 | 价格层 | 推荐场景 |
|------|--------|----------|
| `cosyvoice-v3.5-plus` | 高质量 | 重点音频,情感/语速精细控制 |
| `cosyvoice-v3.5-flash` | 快速 | 日常大批量 |
| `cosyvoice-v3-plus` | 老款 | 兼容已有集成 |
| `cosyvoice-v3-flash` | 快速 | **项目当前默认** |

### 不同模型对指令的格式要求

| 模型 | 声音复刻 / 设计音色 | 系统音色 |
|------|--------------------|----------|
| cosyvoice-v3.5-plus | 可输入任意指令(自由描述) | ❌ v3.5 不支持系统音色 |
| cosyvoice-v3.5-flash | 可输入任意指令 | ❌ v3.5 不支持系统音色 |
| cosyvoice-v3-plus | ❌ 不支持指令控制 | 指令必须固定格式(见 CosyVoice 音色列表) |
| cosyvoice-v3-flash | 可输入任意指令 | 指令必须固定格式 |

使用方式:通过 `instruction` 参数指定指令内容。

### 指令支持的语言

| 模型 | 声音复刻 | 系统音色 |
|------|---------|----------|
| v3.5-plus / v3.5-flash | 中 / 英 / 法 / 德 / 日 / 韩 / 俄 / 葡 / 泰 / 印尼 / 越南 | ❌ 不支持 |
| v3-plus | 中 / 英 / 法 / 德 / 日 / 韩 / 俄 | 固定格式 |
| v3-flash | 中 / 英 / 法 / 德 / 日 / 韩 / 俄 | 中文 |

### 指令长度限制

**不超过 100 字符**(按以下规则计数):
- 汉字(简体 / 繁体 / 日文汉字 / 韩文汉字)**按 2 个字符**
- 其他字符(标点 / 字母 / 数字 / 日韩假名 / 谚文等)按 1 个字符

```example
"温柔知性的女性,30 岁左右,语调平和,适合有声书朗读"
  温柔=2 + 知性=2 + 的=1 + 女性=2 + ,=1 + 30=2 + 岁=1 + 左右=2 + ... ≈ 70 字符 ✅
```

### 适用场景

- 有声书和广播剧配音
- 广告和宣传片配音
- 游戏角色和动画配音
- 情感化的智能语音助手
- 纪录片和新闻播报

### 如何编写高质量的声音描述

#### 5 个核心原则

1. **具体而非模糊** — 用"低沉 / 清脆 / 语速偏快"等具体特征,避免"好听 / 普通"
2. **多维而非单一** — 组合"性别 + 年龄 + 情感 + 用途"等维度,只写"女声"太宽泛
3. **客观而非主观** — 用"音调偏高,带有活力"代替"我最喜欢的声音"
4. **原创而非模仿** — 描述声音特质,**不要**要求模仿特定人物(涉版权风险)
5. **简洁而非冗余** — 每个词都有明确作用,避免重复修饰

#### 7 个推荐描述维度

| 维度 | 可选值 |
|------|--------|
| 性别 | 男性 / 女性 / 中性 |
| 年龄 | 儿童(5-12) / 青少年(13-18) / 青年(19-35) / 中年(36-55) / 老年(55+) |
| 音调 | 高音 / 中音 / 低音 / 偏高 / 偏低 |
| 语速 | 快速 / 中速 / 缓慢 / 偏快 / 偏慢 |
| 情感 | 开朗 / 沉稳 / 温柔 / 严肃 / 活泼 / 冷静 / 治愈 |
| 特点 | 有磁性 / 清脆 / 沙哑 / 圆润 / 甜美 / 浑厚 / 有力 |
| 用途 | 新闻播报 / 广告配音 / 有声书 / 动画角色 / 语音助手 / 纪录片 |

#### 描述示例(从官方复制,微调措辞)

1. **标准播音风格**:吐字清晰精准,字正腔圆
2. **年轻活泼女性**:语速较快,带有明显的上扬语调,适合介绍时尚产品
3. **沉稳中年男性**:语速缓慢,音色低沉有磁性,适合朗读新闻或纪录片解说
4. **温柔知性女性**:30 岁左右,语调平和,适合有声书朗读
5. **可爱儿童**:大约 8 岁女孩,说话略带稚气,适合动画角色配音

### 项目内当前用法的指令格式

代码 `server/src/modules/tts/aliyun.provider.ts:103-105` 给 Qwen-TTS Instruct 用的指令格式:
```ts
if (params.speed !== 1) instructions.push(`语速${params.speed > 1 ? '较快' : '较慢'}`);
if (params.pitch !== 0) instructions.push(`音调${params.pitch > 0 ? '较高' : '较低'}`);
```

例如 speed=0.78 → `"语速较慢"`(符合 v3-flash 的指令规则,因为 speed 描述在系统音色固定格式内)。

### 注意事项

- **字数限制 100 字符很严**,所以"语速较慢"比"语速稍微放缓一点"更好(后者汉字太多可能超限)
- **优先用声音特征描述(性别 + 年龄 + 音调)**,避免纯情绪词("治愈的"),后者难以稳定生成
- **不要混用语言**,指令要全中文(系统音色)或全英文/全日文(复刻音色)
- **自定义音色的指令自由度更高**,可以实验长 prompt,但要测听感

### 🔑 方言指令控制（2026-07 实测验证）

`cosyvoice-v3-flash` + `longanhuan_v3`（主力音色）支持 `instruction` 字段控制方言。**旧代码曾禁用**（注释 "#tts-cosyvoice-428: 不接受 instruction"），但新版已修复。

| 类型 | 代表音色 | 方式 |
|------|---------|------|
| 系统音色 | `longshange_v3` | 原生支持,无需指令 |
| 系统音色 | `longanhuan_v3` | `instruction` 字段指定方言 |
| 声音复刻 | 任意 | `instruction` 写 "请用 XX 话表达。" |
| 声音设计 | v3.5 系 | ❌ 暂不支持方言 |

格式是**单数 `instruction` 字符串**(不是 `instructions` 数组):

```json
{ "input": { "voice": "longanhuan_v3", "instruction": "请用河南话表达。" } }
```

项目内全链路(commit `ed0f9532`):
```
用户选 zh-HEN → pickTtsVendor() → voice=longanhuan_v3, dialectInstruction="请用河南话表达。"
→ processTtsTask → VoiceParams → aliyun.provider.ts → CosyVoice API → 方言输出
```

## Qwen-TTS 音色清单(完整,官方页面抓取)

> 数据来源:[阿里云 Qwen-TTS 音色列表](https://help.aliyun.com/zh/model-studio/qwen-tts-voice-list),2026-07 用 playwright 渲染抓取。共 48 个音色。

| 音色名 | 描述 | 性别 |
|--------|------|------|
| `芊悦` | 阳光积极、亲切自然小姐姐 | 女 |
| `苏瑶` | 温柔小姐姐 | 女 |
| `晨煦` | 标准普通话，带部分北方口音。阳光、温暖、活力、朝气 | 男 |
| `千雪` | 二次元虚拟女友 | 女 |
| `茉兔` | 撒娇搞怪，逗你开心 | 女 |
| `十三` | 拽拽的、可爱的小暴躁 | 女 |
| `月白` | 率性帅气的月白 | 男 |
| `四月` | 知性与温柔的碰撞 | 女 |
| `凯` | 耳朵的一场SPA | 男 |
| `不吃鱼` | 不会翘舌音的设计师 | 男 |
| `萌宝` | 喝酒不打醉拳的小萝莉 | 女 |
| `詹妮弗` | 品牌级、电影质感般美语女声 | 女 |
| `甜茶` | 节奏拉满，戏感炸裂，真实与张力共舞 | 男 |
| `卡捷琳娜` | 御姐音色，韵律回味十足 | 女 |
| `艾登` | 精通厨艺的美语大男孩 | 男 |
| `沧明子` | 沉稳睿智的老者，沧桑如松却心明如镜 | 男 |
| `乖小妹` | 温顺如春水，乖巧如初雪 | 女 |
| `沙小弥` | 聪明伶俐的小大人，童真未泯却早慧如禅 | 男 |
| `燕铮莺` | 声音洪亮，吐字清晰，人物鲜活，听得人热血沸腾；金戈铁马入梦来，字正腔圆间尽显千面人声的江湖 | 女 |
| `田叔` | 一口独特的沙哑烟嗓，一开口便道尽了千军万马与江湖豪情 | 男 |
| `萌小姬` | “萌属性”爆棚的小萝莉 | 女 |
| `阿闻` | 平直的基线语调，字正腔圆的咬字发音，这就是最专业的新闻主持人 | 男 |
| `墨讲师` | 既保持学科严谨性，又通过叙事技巧将复杂知识转化为可消化的认知模块 | 女 |
| `徐大爷` | 被岁月和旱烟浸泡过的质朴嗓音，不疾不徐地摇开了满村的奇闻异事 | 男 |
| `邻家妹妹` | 糯米糍一样又软又黏的嗓音，那一声声拉长了的“哥哥”，甜得能把人的骨头都叫酥了 | 女 |
| `小婉` | 温和舒缓的声线，助你更快地进入睡眠，晚安，好梦 | 女 |
| `顽屁小孩` | 调皮捣蛋却充满童真的他来了，这是你记忆中的小新吗 | 男 |
| `少女阿月` | 平时是甜到发腻的迷糊少女音，但在喊出“代表月亮消灭你”时，瞬间充满不容置疑的爱与正义 | 女 |
| `博德加` | 热情的西班牙大叔 | 男 |
| `索尼莎` | 热情开朗的拉美大姐 | 女 |
| `阿列克` | 一开口，是战斗民族的冷，也是毛呢大衣下的暖 | 男 |
| `多尔切` | 慵懒的意大利大叔 | 男 |
| `素熙` | 温柔开朗，情绪丰富的韩国欧尼 | 女 |
| `小野杏` | 鬼灵精怪的青梅竹马 | 女 |
| `莱恩` | 理性是底色，叛逆藏在细节里——穿西装也听后朋克的德国青年 | 男 |
| `埃米尔安` | 浪漫的法国大哥哥 | 男 |
| `安德雷` | 声音磁性，自然舒服、沉稳男生 | 男 |
| `拉迪奥·戈尔` | 足球诗人Rádio Gol！今天我要用名字为你们解说足球 | 男 |
| `上海-阿珍` | 风风火火的沪上阿姐 | 女 |
| `北京-晓东` | 北京胡同里长大的少年 | 男 |
| `南京-老李` | 耐心的瑜伽老师 | 男 |
| `陕西-秦川` | 面宽话短，心实声沉——老陕的味道 | 男 |
| `闽南-阿杰` | 诙谐直爽、市井活泼的台湾哥仔形象 | 男 |
| `天津-李彼得` | 天津相声，专业捧哏 | 男 |
| `四川-晴儿` | 甜到你心里的川妹子 | 女 |
| `四川-程川` | 一个跳脱市井的四川成都男子 | 男 |
| `粤语-阿强` | 幽默风趣的阿强，在线陪聊 | 男 |
| `粤语-阿清` | 甜美的港妹闺蜜 | 女 |

### 外语音色(按语言)

| 音色名 | 描述 | 性别 |
|--------|------|------|
| `詹妮弗` | 品牌级、电影质感般美语女声 | 女 |
| `艾登` | 精通厨艺的美语大男孩 | 男 |
| `博德加` | 热情的西班牙大叔 | 男 |
| `索尼莎` | 热情开朗的拉美大姐 | 女 |
| `多尔切` | 慵懒的意大利大叔 | 男 |
| `素熙` | 温柔开朗，情绪丰富的韩国欧尼 | 女 |
| `莱恩` | 理性是底色，叛逆藏在细节里——穿西装也听后朋克的德国青年 | 男 |
| `埃米尔安` | 浪漫的法国大哥哥 | 男 |

### 中文方言/地区音色

| 音色名 | 描述 | 性别 |
|--------|------|------|
| `上海-阿珍` | 风风火火的沪上阿姐 | 女 |
| `北京-晓东` | 北京胡同里长大的少年 | 男 |
| `南京-老李` | 耐心的瑜伽老师 | 男 |
| `陕西-秦川` | 面宽话短，心实声沉——老陕的味道 | 男 |
| `闽南-阿杰` | 诙谐直爽、市井活泼的台湾哥仔形象 | 男 |
| `天津-李彼得` | 天津相声，专业捧哏 | 男 |
| `四川-晴儿` | 甜到你心里的川妹子 | 女 |
| `四川-程川` | 一个跳脱市井的四川成都男子 | 男 |
| `粤语-阿强` | 幽默风趣的阿强，在线陪聊 | 男 |
| `粤语-阿清` | 甜美的港妹闺蜜 | 女 |

### 角色/特色音色

| 音色名 | 描述 | 性别 |
|--------|------|------|
| `不吃鱼` | 不会翘舌音的设计师 | 男 |
| `萌宝` | 喝酒不打醉拳的小萝莉 | 女 |
| `沧明子` | 沉稳睿智的老者，沧桑如松却心明如镜 | 男 |
| `沙小弥` | 聪明伶俐的小大人，童真未泯却早慧如禅 | 男 |
| `萌小姬` | “萌属性”爆棚的小萝莉 | 女 |
| `顽屁小孩` | 调皮捣蛋却充满童真的他来了，这是你记忆中的小新吗 | 男 |
| `博德加` | 热情的西班牙大叔 | 男 |
| `多尔切` | 慵懒的意大利大叔 | 男 |
| `上海-阿珍` | 风风火火的沪上阿姐 | 女 |
| `北京-晓东` | 北京胡同里长大的少年 | 男 |
| `南京-老李` | 耐心的瑜伽老师 | 男 |
| `闽南-阿杰` | 诙谐直爽、市井活泼的台湾哥仔形象 | 男 |

### 选型速查

| 场景 | 推荐音色 |
|------|---------|
| **有声书/广播剧(温柔女)** | 芊悦(Cherry,默认)、苏瑶、四月 |
| **有声书(磁性男)** | 凯、晨煦(带北方口音)、安德雷 |
| **新闻播报** | 阿闻(最专业主持人)、晨煦 |
| **儿童/童趣** | 萌宝(小萝莉)、十三(拽拽小暴躁)、顽屁小孩(调皮捣蛋)、沙小弥(小大人) |
| **品牌级朗读** | 詹妮弗(电影质感美语女声)、御姐系卡捷琳娜 |
| **戏感配音** | 甜茶(节奏张力) |
| **老者/沉稳** | 沧明子(沧桑睿智)、徐大爷(沙哑烟嗓) |
| **方言版本** | 上海-阿珍、北京-晓东、南京-老李、陕西-秦川、闽南-阿杰、天津-李彼得、四川-晴儿/程川、粤语-阿强/阿清 |
| **欧美外语** | 詹妮弗/艾登(美)、莱恩(德)、埃米尔安(法)、博德加(西班牙,热情大叔)、拉迪奥·戈尔(葡,足球解说) |
| **东亚/俄** | 素熙(韩)、小野杏(日)、阿列克(俄,战斗民族冷) |