# TTS 系统文档总览

> 这是项目所有 TTS 相关文档的总入口。从这里出发找到你想了解的细节。

---

## 📚 文档索引

### 🎯 核心数据(未来做"语言选择"功能必备)
| 文档 | 内容 | 行数 |
|------|------|------|
| 👉 [`alicloud-tts-lang-voice-matrix.md`](alicloud-tts-lang-voice-matrix.md) | **模型 × 语言 × 音色矩阵**(4 个 CosyVoice + Qwen-TTS 共 264 音色 × 19 标准化语言) | 146 |

### 📘 详细分文档
| 文档 | 内容 |
|------|------|
| [`tts-edge-languages.md`](tts-edge-languages.md) | Edge TTS 75 语言 / 316 音色(免费,默认 vendor) |
| [`tts-aliyun-voice.md`](tts-aliyun-voice.md) | 阿里云百炼配置 + 项目默认音色 + CosyVoice 指令使用指南 + Qwen-TTS 完整 48 音色 |
| [`qwen-tts-voices-full.md`](qwen-tts-voices-full.md) | Qwen-TTS 详细附录(独立备份) |
| [`cosyvoice-voice-design.md`](cosyvoice-voice-design.md) | **声音设计**完整指南(v3.5 / v3 / Qwen-TTS 都支持) |

---

## 🏗️ 整体架构

```
                         TTS 路由
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
   ┌────▼─────┐      ┌─────▼─────┐    ┌──────▼──────┐
   │ Edge TTS │      │ 阿里云百炼  │    │ (未来声音设计) │
   │  (默认)  │      │ (付费更好)  │    │  (用户自创)  │
   └────┬─────┘      └─────┬─────┘    └──────────────┘
        │                  │
   316 音色            264 音色
   75 语言              11 标准化语言
   free                ~¥0.00003/字
```

---

## 🚀 默认 / 决策表

| 用户场景 | 推荐 vendor | 模型 | 默认音色 |
|---------|-----------|------|---------|
| 默认(免费,够用) | edge | edge-tts | `zh-CN-XiaoxiaoNeural` |
| 中文有声书(高质量) | bailian | cosyvoice-v3-flash | `longanhuan_v3`(支持 9 种方言) |
| 多语言有声书 | bailian | qwen3-tts-instruct-flash | `Cherry`(芊悦,中英日韩) |
| 英语专业朗读 | bailian | qwen3-tts-instruct-flash | `詹妮弗`(美式电影质感) |
| 自定义独特声音 | bailian | cosyvoice-v3.5-plus | 用户描述创建 |

> **🔑 方言控制**: `longanhuan_v3` 支持通过 `instruction` 字段输出 9 种方言（东北/粤/川/鲁/豫/湘/陕/皖/闽）。
> 代码全链路已贯通: `pickTtsVendor → dialectInstruction → aliyun.provider.ts → CosyVoice API`。
> 详见 [`docs/tts-aliyun-voice.md` §方言指令控制](tts-aliyun-voice.md#-方言指令控制2026-07-实测验证)

---

## 📊 关键数据(从官方文档抓取)

| 项目 | 数量 |
|------|------|
| Edge TTS 支持的语言 | 75 |
| Edge TTS 音色 | 316 |
| 阿里云 CosyVoice 系统音色 | 216(v3-flash 88 + v3-plus 2 + v2 106 + v1 20) |
| 阿里云 Qwen-TTS 系统音色 | 48 |
| 阿里云支持的标准化语言/方言 | 19 |
| 项目实际使用的"龙"系列 CosyVoice | 10 |

---

## 🛠️ 自动化脚本

| 脚本 | 用途 |
|------|------|
| `scripts/gen-edge-tts-doc.js` | 从 edge-tts --list-voices 生成 Edge TTS 文档 |
| `scripts/scrape-alicloud-qwen-tts.js` | 用 playwright 抓阿里云 Qwen-TTS SPA 页面 |
| `scripts/parse-qwen-tts-dom.js` | DOM → Qwen-TTS markdown 表格 |
| `scripts/parse-cosyvoice-dom.py` | DOM → CosyVoice voices JSON |
| `scripts/analyze-model-lang-matrix.py` | DOM → 模型 × 语言 × 音色矩阵 JSON |
| `scripts/gen-lang-matrix-doc.js` | JSON → 矩阵 markdown 文档 |
| `scripts/gen-aliyun-tts-doc.js` | 代码 + 权威资料 → 阿里云 TTS 主文档 |
| `scripts/render-local-html.js` | playwright 渲染本地下载的 HTML |

---

## 🗺️ 用户下载的本地资料(未入 git)

在 `tts音色/` 目录(本地),由用户从阿里云官方下载:

| 文件 | 来源 |
|------|------|
| `Qwen-TTS音色列表-...html` | https://help.aliyun.com/zh/model-studio/qwen-tts-voice-list |
| `系统预置音色参数与特性列表-...html` | 系统音色完整参数表 |
| `声音设计-...html` | 声音设计指南(v3.5 / v3 / Qwen-TTS) |
| `SSML 与 LaTeX-...html` | 高级 SSML 语法(暂未读) |

> 这些文件**不入 git**(已在 .gitignore),用作脚本的输入数据源。

---

## 🗓️ 未来开发路线图

### 第一阶段:语言选择功能
- [x] 完整摸清模型×语言×音色矩阵(见 `alicloud-tts-lang-voice-matrix.md`)
- [ ] 入仓矩阵 JSON 数据
- [ ] 后端 `/api/tts/languages` 接口
- [ ] 前端"语言选择器" UI

### 第二阶段:声音设计功能
- [ ] 完成后端 `voice-design.service.ts`(基于 `cosyvoice-voice-design.md`)
- [ ] 前端"声音设计向导" 4 步流程
- [ ] 用户自定义音色列表管理

### 第三阶段:高级特性
- [ ] SSML 支持(用 `SSML 与 LaTeX.html` 内容)
- [ ] 声音复刻功能(录制 → 训练 → 复刻特定声音)
- [ ] 实时 vs 非实时双路径切换(已部分实现)

---

## 📝 关键 commit 历史

| Commit | 内容 |
|-------|------|
| `cec5ed14` | Edge TTS 语言文档 |
| `de77fb37` | CosyVoice 指令使用指南 |
| `438d49fc` | Qwen-TTS 48 音色 + 抓取脚本 |
| `506b8e4f` | 阿里云 TTS 配置 + 11 项目音色 |
| `99275640` | **模型 × 语言 × 音色矩阵** |

---

**最后更新:** 2026-07-12
**维护者:** Claude / caojunfei