# Edge TTS 支持的语言 / 音色清单

> 自动生成自 edge-tts 7.2.8 (--list-voices)。共 **316 个音色**,覆盖 **74 种语言**。

**项目当前使用:** `zh-CN-XiaoxiaoNeural`(中文温柔女声,在 `server/src/config/models.json` 的 `tts.defaultVoice` 配置)。

**特性:** Edge TTS 是 Microsoft Edge 浏览器的"大声朗读"引擎,基于 Azure 神经网络,**完全免费**、**免 API Key**、单次最长 ~3000 字符、中文安全 1000 字。

## 中文方言(项目最常用)

| Locale | 方言 | 音色数 | 常用音色 |
|--------|------|--------|---------|
| zh-CN | 普通话(中国大陆) | 6 | XiaoxiaoNeural, XiaoyiNeural, YunjianNeural, YunxiNeural... |
| zh-HK | 粤语(香港) | 3 | HiuGaaiNeural, HiuMaanNeural, WanLungNeural |
| zh-TW | 国语(台湾) | 3 | HsiaoChenNeural, HsiaoYuNeural, YunJheNeural |
| zh-CN-sichuan | 四川话 | 0 |  |
| zh-CN-liaoning | 东北话 | 0 |  |
| zh-CN-shaanxi | 陕西方言 | 0 |  |

### 全部中文音色(14 个)

| ShortName | 性别 | 风格 |
|-----------|------|------|
| `zh-CN-XiaoxiaoNeural` | Female | Warm |
| `zh-CN-XiaoyiNeural` | Female | Lively |
| `zh-CN-YunjianNeural` | Male | Novel |
| `zh-CN-YunxiaNeural` | Male | Cute |
| `zh-CN-YunxiNeural` | Male | Lively, Sunshine |
| `zh-CN-YunyangNeural` | Male | Professional, Reliable |
| `zh-HK-HiuGaaiNeural` | Female | Friendly, Positive |
| `zh-HK-HiuMaanNeural` | Female | Friendly, Positive |
| `zh-HK-WanLungNeural` | Male | Friendly, Positive |
| `zh-TW-HsiaoChenNeural` | Female | Friendly, Positive |
| `zh-TW-HsiaoYuNeural` | Female | Friendly, Positive |
| `zh-TW-YunJheNeural` | Male | Friendly, Positive |

## 全部 74 种语言汇总

按字母排序,展示每个 Locale 的音色数:

| Locale | 语言 | 音色数 | 主要音色 |
|--------|------|--------|---------|
| af-ZA | 南非荷兰语 Afrikaans | 2 | AdriNeural, WillemNeural |
| am-ET | 阿姆哈拉语 Amharic | 2 | AmehaNeural, MekdesNeural |
| ar-AE | 阿拉伯语 Arabic | 2 | FatimaNeural, HamdanNeural |
| ar-BH | 阿拉伯语 Arabic | 2 | AliNeural, LailaNeural |
| ar-DZ | 阿拉伯语 Arabic | 2 | AminaNeural, IsmaelNeural |
| ar-EG | 阿拉伯语 Arabic | 2 | SalmaNeural, ShakirNeural |
| ar-IQ | 阿拉伯语 Arabic | 2 | BasselNeural, RanaNeural |
| ar-JO | 阿拉伯语 Arabic | 2 | SanaNeural, TaimNeural |
| ar-KW | 阿拉伯语 Arabic | 2 | FahedNeural, NouraNeural |
| ar-LB | 阿拉伯语 Arabic | 2 | LaylaNeural, RamiNeural |
| ar-LY | 阿拉伯语 Arabic | 2 | ImanNeural, OmarNeural |
| ar-MA | 阿拉伯语 Arabic | 2 | JamalNeural, MounaNeural |
| ar-OM | 阿拉伯语 Arabic | 2 | AbdullahNeural, AyshaNeural |
| ar-QA | 阿拉伯语 Arabic | 2 | AmalNeural, MoazNeural |
| ar-SA | 阿拉伯语 Arabic | 2 | HamedNeural, ZariyahNeural |
| ar-SY | 阿拉伯语 Arabic | 2 | AmanyNeural, LaithNeural |
| ar-TN | 阿拉伯语 Arabic | 2 | HediNeural, ReemNeural |
| ar-YE | 阿拉伯语 Arabic | 2 | MaryamNeural, SalehNeural |
| az-AZ | 阿塞拜疆语 Azerbaijani | 2 | BabekNeural, BanuNeural |
| bg-BG | 保加利亚语 Bulgarian | 2 | BorislavNeural, KalinaNeural |
| bn-BD | 孟加拉语 Bengali | 2 | NabanitaNeural, PradeepNeural |
| bn-IN | 孟加拉语 Bengali | 2 | BashkarNeural, TanishaaNeural |
| bs-BA | 波斯尼亚语 Bosnian | 2 | GoranNeural, VesnaNeural |
| ca-ES | 加泰罗尼亚语 Catalan | 2 | EnricNeural, JoanaNeural |
| cs-CZ | 捷克语 Czech | 2 | AntoninNeural, VlastaNeural |
| cy-GB | 威尔士语 Welsh | 2 | AledNeural, NiaNeural |
| da-DK | 丹麦语 Danish | 2 | ChristelNeural, JeppeNeural |
| de-AT | 德语 German | 2 | IngridNeural, JonasNeural |
| de-CH | 德语 German | 2 | JanNeural, LeniNeural |
| de-DE | 德语 German | 6 | AmalaNeural, ConradNeural, FlorianMultilingualNeural... |
| el-GR | 希腊语 Greek | 2 | AthinaNeural, NestorasNeural |
| en-AU | 英语 English | 2 | NatashaNeural, WilliamMultilingualNeural |
| en-CA | 英语 English | 2 | ClaraNeural, LiamNeural |
| en-GB | 英语 English | 5 | LibbyNeural, MaisieNeural, RyanNeural... |
| en-HK | 英语 English | 2 | SamNeural, YanNeural |
| en-IE | 英语 English | 2 | ConnorNeural, EmilyNeural |
| en-IN | 英语 English | 3 | NeerjaExpressiveNeural, NeerjaNeural, PrabhatNeural |
| en-KE | 英语 English | 2 | AsiliaNeural, ChilembaNeural |
| en-NG | 英语 English | 2 | AbeoNeural, EzinneNeural |
| en-NZ | 英语 English | 2 | MitchellNeural, MollyNeural |
| en-PH | 英语 English | 2 | JamesNeural, RosaNeural |
| en-SG | 英语 English | 2 | LunaNeural, WayneNeural |
| en-TZ | 英语 English | 2 | ElimuNeural, ImaniNeural |
| en-US | 英语 English | 17 | AnaNeural, AndrewMultilingualNeural, AndrewNeural... |
| en-ZA | 英语 English | 2 | LeahNeural, LukeNeural |
| es-AR | 西班牙语 Spanish | 2 | ElenaNeural, TomasNeural |
| es-BO | 西班牙语 Spanish | 2 | MarceloNeural, SofiaNeural |
| es-CL | 西班牙语 Spanish | 2 | CatalinaNeural, LorenzoNeural |
| es-CO | 西班牙语 Spanish | 2 | GonzaloNeural, SalomeNeural |
| es-CR | 西班牙语 Spanish | 2 | JuanNeural, MariaNeural |
| es-CU | 西班牙语 Spanish | 2 | BelkysNeural, ManuelNeural |
| es-DO | 西班牙语 Spanish | 2 | EmilioNeural, RamonaNeural |
| es-EC | 西班牙语 Spanish | 2 | AndreaNeural, LuisNeural |
| es-ES | 西班牙语 Spanish | 3 | AlvaroNeural, ElviraNeural, XimenaNeural |
| es-GQ | 西班牙语 Spanish | 2 | JavierNeural, TeresaNeural |
| es-GT | 西班牙语 Spanish | 2 | AndresNeural, MartaNeural |
| es-HN | 西班牙语 Spanish | 2 | CarlosNeural, KarlaNeural |
| es-MX | 西班牙语 Spanish | 2 | DaliaNeural, JorgeNeural |
| es-NI | 西班牙语 Spanish | 2 | FedericoNeural, YolandaNeural |
| es-PA | 西班牙语 Spanish | 2 | MargaritaNeural, RobertoNeural |
| es-PE | 西班牙语 Spanish | 2 | AlexNeural, CamilaNeural |
| es-PR | 西班牙语 Spanish | 2 | KarinaNeural, VictorNeural |
| es-PY | 西班牙语 Spanish | 2 | MarioNeural, TaniaNeural |
| es-SV | 西班牙语 Spanish | 2 | LorenaNeural, RodrigoNeural |
| es-US | 西班牙语 Spanish | 2 | AlonsoNeural, PalomaNeural |
| es-UY | 西班牙语 Spanish | 2 | MateoNeural, ValentinaNeural |
| es-VE | 西班牙语 Spanish | 2 | PaolaNeural, SebastianNeural |
| et-EE | 爱沙尼亚语 Estonian | 2 | AnuNeural, KertNeural |
| fa-IR | 波斯语 Persian | 2 | DilaraNeural, FaridNeural |
| fi-FI | 芬兰语 Finnish | 2 | HarriNeural, NooraNeural |
| fil-PH | 菲律宾语 Filipino | 2 | AngeloNeural, BlessicaNeural |
| fr-BE | 法语 French | 2 | CharlineNeural, GerardNeural |
| fr-CA | 法语 French | 4 | AntoineNeural, JeanNeural, SylvieNeural... |
| fr-CH | 法语 French | 2 | ArianeNeural, FabriceNeural |
| fr-FR | 法语 French | 5 | DeniseNeural, EloiseNeural, HenriNeural... |
| ga-IE | 爱尔兰语 Irish | 2 | ColmNeural, OrlaNeural |
| gl-ES | 加利西亚语 Galician | 2 | RoiNeural, SabelaNeural |
| gu-IN | 古吉拉特语 Gujarati | 2 | DhwaniNeural, NiranjanNeural |
| he-IL | 希伯来语 Hebrew | 2 | AvriNeural, HilaNeural |
| hi-IN | 印地语 Hindi | 2 | MadhurNeural, SwaraNeural |
| hr-HR | 克罗地亚语 Croatian | 2 | GabrijelaNeural, SreckoNeural |
| hu-HU | 匈牙利语 Hungarian | 2 | NoemiNeural, TamasNeural |
| id-ID | 印度尼西亚语 Indonesian | 2 | ArdiNeural, GadisNeural |
| is-IS | 冰岛语 Icelandic | 2 | GudrunNeural, GunnarNeural |
| it-IT | 意大利语 Italian | 4 | DiegoNeural, ElsaNeural, GiuseppeMultilingualNeural... |
| ja-JP | 日语 Japanese | 2 | KeitaNeural, NanamiNeural |
| jv-ID | 爪哇语 Javanese | 2 | DimasNeural, SitiNeural |
| ka-GE | 格鲁吉亚语 Georgian | 2 | EkaNeural, GiorgiNeural |
| kk-KZ | 哈萨克语 Kazakh | 2 | AigulNeural, DauletNeural |
| km-KH | 高棉语 Khmer | 2 | PisethNeural, SreymomNeural |
| kn-IN | 卡纳达语 Kannada | 2 | GaganNeural, SapnaNeural |
| ko-KR | 韩语 Korean | 3 | HyunsuMultilingualNeural, InJoonNeural, SunHiNeural |
| lo-LA | 老挝语 Lao | 2 | ChanthavongNeural, KeomanyNeural |
| lt-LT | 立陶宛语 Lithuanian | 2 | LeonasNeural, OnaNeural |
| lv-LV | 拉脱维亚语 Latvian | 2 | EveritaNeural, NilsNeural |
| mk-MK | 马其顿语 Macedonian | 2 | AleksandarNeural, MarijaNeural |
| ml-IN | 马拉雅拉姆语 Malayalam | 2 | MidhunNeural, SobhanaNeural |
| mn-MN | 蒙古语 Mongolian | 2 | BataaNeural, YesuiNeural |
| mr-IN | 马拉地语 Marathi | 2 | AarohiNeural, ManoharNeural |
| ms-MY | 马来语 Malay | 2 | OsmanNeural, YasminNeural |
| mt-MT | 马耳他语 Maltese | 2 | GraceNeural, JosephNeural |
| my-MM | 缅甸语 Burmese | 2 | NilarNeural, ThihaNeural |
| nb-NO | 挪威语(书面) Norwegian Bokmål | 2 | FinnNeural, PernilleNeural |
| ne-NP | 尼泊尔语 Nepali | 2 | HemkalaNeural, SagarNeural |
| nl-BE | 荷兰语 Dutch | 2 | ArnaudNeural, DenaNeural |
| nl-NL | 荷兰语 Dutch | 3 | ColetteNeural, FennaNeural, MaartenNeural |
| pl-PL | 波兰语 Polish | 2 | MarekNeural, ZofiaNeural |
| ps-AF | 普什图语 Pashto | 2 | GulNawazNeural, LatifaNeural |
| pt-BR | 葡萄牙语 Portuguese | 3 | AntonioNeural, FranciscaNeural, ThalitaMultilingualNeural |
| pt-PT | 葡萄牙语 Portuguese | 2 | DuarteNeural, RaquelNeural |
| ro-RO | 罗马尼亚语 Romanian | 2 | AlinaNeural, EmilNeural |
| ru-RU | 俄语 Russian | 2 | DmitryNeural, SvetlanaNeural |
| si-LK | 僧伽罗语 Sinhala | 2 | SameeraNeural, ThiliniNeural |
| sk-SK | 斯洛伐克语 Slovak | 2 | LukasNeural, ViktoriaNeural |
| sl-SI | 斯洛文尼亚语 Slovenian | 2 | PetraNeural, RokNeural |
| so-SO | 索马里语 Somali | 2 | MuuseNeural, UbaxNeural |
| sq-AL | 阿尔巴尼亚语 Albanian | 2 | AnilaNeural, IlirNeural |
| sr-RS | 塞尔维亚语 Serbian | 2 | NicholasNeural, SophieNeural |
| su-ID | 巽他语 Sundanese | 2 | JajangNeural, TutiNeural |
| sv-SE | 瑞典语 Swedish | 2 | MattiasNeural, SofieNeural |
| sw-KE | 斯瓦希里语 Swahili | 2 | RafikiNeural, ZuriNeural |
| sw-TZ | 斯瓦希里语 Swahili | 2 | DaudiNeural, RehemaNeural |
| ta-IN | 泰米尔语 Tamil | 2 | PallaviNeural, ValluvarNeural |
| ta-LK | 泰米尔语 Tamil | 2 | KumarNeural, SaranyaNeural |
| ta-MY | 泰米尔语 Tamil | 2 | KaniNeural, SuryaNeural |
| ta-SG | 泰米尔语 Tamil | 2 | AnbuNeural, VenbaNeural |
| te-IN | 泰卢固语 Telugu | 2 | MohanNeural, ShrutiNeural |
| th-TH | 泰语 Thai | 2 | NiwatNeural, PremwadeeNeural |
| tr-TR | 土耳其语 Turkish | 2 | AhmetNeural, EmelNeural |
| uk-UA | 乌克兰语 Ukrainian | 2 | OstapNeural, PolinaNeural |
| ur-IN | 乌尔都语 Urdu | 2 | GulNeural, SalmanNeural |
| ur-PK | 乌尔都语 Urdu | 2 | AsadNeural, UzmaNeural |
| uz-UZ | 乌兹别克语 Uzbek | 2 | MadinaNeural, SardorNeural |
| vi-VN | 越南语 Vietnamese | 2 | HoaiMyNeural, NamMinhNeural |
| zh-CN | 中文 Chinese | 6 | XiaoxiaoNeural, XiaoyiNeural, YunjianNeural... |
| zh-HK | 中文 Chinese | 3 | HiuGaaiNeural, HiuMaanNeural, WanLungNeural |
| zh-TW | 中文 Chinese | 3 | HsiaoChenNeural, HsiaoYuNeural, YunJheNeural |
| zu-ZA | 祖鲁语 Zulu | 2 | ThandoNeural, ThembaNeural |

## 切换音色 / 语言

### 命令行测试

```bash
# 中文女声(默认)
edge-tts --voice zh-CN-XiaoxiaoNeural --text "你好世界" --write-media out.mp3

# 粤语女声
edge-tts --voice zh-HK-HiuMaanNeural --text "你好,這是粵語測試" --write-media cantonese.mp3

# 四川话
edge-tts --voice zh-CN-sichuan-YunxiNeural --text "今天天气好巴适" --write-media sc.mp3

# 英语男声
edge-tts --voice en-US-GuyNeural --text "Hello, world." --write-media en.mp3

# 日语女声
edge-tts --voice ja-JP-NanamiNeural --text "こんにちは" --write-media ja.mp3

# 一次性列出全部语音
edge-tts --list-voices > voices.txt
```

### 项目内修改默认音色

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

```json
{
  "tts": {
    "defaultVendor": "edge",
    "defaultModel": "edge-tts",
    "defaultVoice": "zh-CN-XiaoxiaoNeural"   // ← 改这里
  }
}
```

或者环境变量覆盖(在 `server/.env`):

```bash
EDGE_TTS_VOICE=zh-HK-HiuMaanNeural
```

### API 调用时按音色生成

前端 → 后端 `/api/tts/generate` 接口传 `voiceId` 字段:

```json
{
  "text": "你好世界",
  "voiceId": "zh-CN-YunxiNeural"
}
```

## 前端统一音色 ID → 实际 Edge TTS 音色映射

前端用 10 个统一 ID(`voice_01`~`voice_10`)展示,后端 `edge-tts.provider.ts:51-62` 的 `EDGE_VOICE_MAP` 把它们映射到实际 Edge 音色:

| 前端 ID | 实际 Edge 音色 | 描述 |
|---------|----------------|------|
| voice_01 | `zh-CN-XiaoxiaoNeural` | 温柔女声 |
| voice_02 | `zh-CN-YunxiNeural` | 磁性男声 |
| voice_03 | `zh-CN-XiaoyiNeural` | 活泼女声 |
| voice_04 | `zh-CN-YunyangNeural` | 知性女声(新闻) |
| voice_05 | `zh-CN-YunjianNeural` | 阳光男声 |
| voice_06 | `zh-CN-YunyangNeural` | 沧桑男声 |
| voice_07 | `zh-CN-XiaoxiaoNeural` | 甜美女声 |
| voice_08 | `zh-CN-YunxiNeural` | 清朗男声 |
| voice_09 | `zh-CN-XiaoyiNeural` | 亲切女声 |
| voice_10 | `zh-CN-XiaoshuangNeural` | 稚嫩童声 |

> 当前 10 个统一 ID 实际只用到 6 种 Edge 音色,语音方案日后续可补充粤语、英语等跨语言音色(增加 voiceId 11~20 等)。

## 已知限制

- **文本长度:** 单次 ~3000 字符(中文约 1000 字),超出会被服务端拒绝。代码已自动按 1000 字分段拼接(`tts.service.ts` 的 `splitText`)。
- **语速控制:** `--rate` 参数是**后处理时间拉伸**,听感等同于播放器 `audio.playbackRate`(见 `docs/tts-speed-note.md` 或代码 commit dd1fea03)。
- **稳定性:** 依赖微软服务器,偶尔会限频(502/timeout),代码已加 retry + 多个 vendor fallback(`provider.registry.ts`)。
- **没商用授权:** 内部使用 OK,正式商用建议切阿里云 CosyVoice/Qwen-TTS。

## 如何更新本文档

Edge TTS 升级可能新增/删除音色,重新生成:

```bash
# 1. 服务器上导出最新列表
ssh root@8.159.134.106 "edge-tts --list-voices" > /tmp/voices.txt

# 2. 本地跑脚本生成
node deploy-package/scripts/gen-edge-tts-doc.js /tmp/voices.txt > docs/tts-edge-languages.md

# 3. 提交
git add docs/tts-edge-languages.md deploy-package/edge-voices-snapshot.txt
git commit -m "docs(tts): 更新 Edge TTS 音色清单"
```