Ifly Hyper TTS (讯飞超拟人语音合成)

将文本转换为超拟人语音。适用于"把这段文案读出来"等语音合成需求。

API 文档：https://www.xfyun.cn/doc/spark/super%20smart-tts.html

核心特性

• 文本转语音：通过 WebSocket 双向流式接口合成音频
• 发音人控制：通过 --vcn 指定已授权的超拟人发音人，默认使用聆小糖
• 基础韵律控制：语速（speed）/ 音量（volume）/ 语调（pitch）
• 多属性控制：语言/方言通过选择不同发音人(VCN)实现
• 多格式输出：MP3（lame）

---

使用场景（AI调用指南）

场景一：用户说"把这段文案读出来"

用户直接提供文本，要求语音合成。默认使用系统预设参数。

触发条件：用户指令包含"读出来"、"念出来"、"语音合成"、"转语音"、"文字转语音"等关键词。

默认参数：

• 发音人：聆小糖 (x5_lingxiaotang_flow) - 女声，中文普通话，最适合作为默认主音色
• 语速：50（正常）
• 音量：50（正常）
• 语调：50（正常）
• 输出格式：MP3（lame）
• 采样率：24000Hz

# 直接合成（使用默认参数）
python3 scripts/xfei_hyper_tts.py --text "你好，欢迎使用讯飞超拟人语音合成！"

# 指定输出文件
python3 scripts/xfei_hyper_tts.py --text "欢迎收听" --output welcome.mp3

# 使用默认发音人聆小糖
python3 scripts/xfei_hyper_tts.py --text "你好" --vcn x5_lingxiaotang_flow

场景二：用户明确指定参数

用户明确指定发音人、语速、语调、音量等参数时，按用户指定参数执行。

触发条件：用户明确提到发音人名称/VCN、语速数值、语调/音量调整等。

# 指定发音人（需填写已授权的 vcn 代码，可通过 list_voices 查看）
python3 scripts/xfei_hyper_tts.py --text "你好" --vcn x5_lingfeiyi_flow

# 调整语速
python3 scripts/xfei_hyper_tts.py --text "语速稍快" --output fast.mp3 --speed 70
python3 scripts/xfei_hyper_tts.py --text "语速稍慢" --output slow.mp3 --speed 30

# 调整音量和语调
python3 scripts/xfei_hyper_tts.py --text "大声一点" --output loud.mp3 --volume 80
python3 scripts/xfei_hyper_tts.py --text "音调高低" --output pitch_test.mp3 --pitch 60

场景三：语言/方言控制

⚠️ 重要说明：讯飞超拟人API不支持 --language、--style、--emotion 参数。语言和方言通过**选择不同发音人(VCN)**来实现。

# 中文普通话（默认）
python3 scripts/xfei_hyper_tts.py --text "你好"

# 英语
python3 scripts/xfei_hyper_tts.py --text "Hello" --vcn x5_EnUs_Grant_flow

# 天津话
python3 scripts/xfei_hyper_tts.py --text "干嘛" --vcn x4_zijin_oral

# 东北话
python3 scripts/xfei_hyper_tts.py --text "嘎哈呢" --vcn x4_ziyang_oral

场景四：查看可用发音人列表

python3 scripts/xfei_hyper_tts.py --action list_voices

---

发音人说明

精选音色池（Skill 默认支持）

Skill 默认只开放以下 7 个精选发音人，避免全部暴露：

姓名	VCN	性别	语言	适用场景
聆小糖	x5_lingxiaotang_flow	女声	中文普通话	默认主音色，适合语音助手
聆飞瀚	x6_lingfeihan_pro	成年男	中文普通话	纪录片、偏正式表达场景
温暖磁性男声	x6_wennuancixingnansheng_mini	成年男	中文普通话	角色配音、客服场景
Grant	x5_EnUs_Grant_flow	男	英语美式	英文场景
Lila	x5_EnUs_Lila_flow	女	英语美式	英文场景
天津话	x4_zijin_oral	成年男	天津话	方言场景
东北话	x4_ziyang_oral	成年男	东北话	方言场景

说明：语言/方言通过选择不同发音人(VCN)来实现，而非 --language 参数。

官方默认免费发音人

以下发音人为官方提供的免费发音人，无需额外开通：

姓名	VCN	性别	语言
聆小璇	x5_lingxiaoxuan_flow	成年女	中文普通话
聆飞逸	x5_lingfeiyi_flow	成年男	中文普通话
聆小玥	x5_lingxiaoyue_flow	成年女	中文普通话
聆玉昭	x5_lingyuzhao_flow	成年女	中文普通话
聆玉言	x5_lingyuyan_flow	成年女	中文普通话

其余发音人（x6_pro/x6_mini 等系列）需在控制台单独开通授权后才可使用。完整发音人列表见官方文档。

---

输入输出规范

输入参数

参数	说明	默认值
--text	要合成的文本内容（与 --text_file 二选一）	-
--text_file	文本文件路径（与 --text 二选一）	-
--output	输出文件路径	output.mp3
--vcn	发音人 VCN 代码	x5_lingxiaotang_flow（聆小糖）
--speed	语速 0-100（0=半速，50=正常，100=双倍）	50
--volume	音量 0-100（0=静音，50=正常，100=双倍）	50
--pitch	语调 0-100（0=低，50=正常，100=高）	50
--encoding	音频格式：lame(MP3)	lame
--sample_rate	采样率：8000 / 16000 / 24000	24000
--role	⚠️ 角色（部分发音人支持，可能返回10163）	-

响应格式

合成成功：

{
  "success": true,
  "output_path": "/absolute/path/to/output.mp3",
  "encoding": "lame",
  "vcn": "x5_lingxiaotang_flow",
  "voice_name": "聆小糖",
  "text_length": 20,
  "total_size_bytes": 45312,
  "total_size_kb": 44.25,
  "frames": 12,
  "parameters_used": {
    "speed": 50,
    "volume": 50,
    "pitch": 50,
    "sample_rate": 24000
  }
}

---

工作流（Workflow）

1. 接收用户输入：解析文本和参数
2. 参数优先级：用户指定参数 > 系统默认参数（聆小糖、语速50、音量50、语调50、MP3）
3. 输入校验：检查文本长度（最大 64KB）和参数范围
4. 鉴权构建：使用 HMAC-SHA256 签名构建 WebSocket 认证 URL
5. 建立连接：连接到讯飞超拟人 TTS WebSocket 端点
6. 发送请求：传输文本和语音参数
7. 接收音频：收集 Base64 编码的音频帧直至 status=2
8. 保存文件：解码并写入输出文件
9. 返回结果：JSON 格式返回文件路径、大小、编码等信息

---

常见问题 (FAQ) ❓

Q1：超拟人语音合成和传统语音合成的区别是什么？🤔

答： 在传统语音合成的基础上，超拟人语音合成进一步提升了语音的自然度和表现力～ 🌟 它能精准模拟人类的副语言现象，如呼吸、叹气、语速变化等，使得语音不仅流畅自然，更富有情感和生命力！✨ 简单来说，就是让AI的声音更像真人说话那样有感情～ 🎤

---

Q2：超拟人语音合成支持合成什么格式的音频？🎵

答： 支持合成以下格式的音频哦～ 🎶

格式	encoding 参数值	文件扩展名
MP3	lame	.mp3
PCM	raw	.pcm
Speex	speex / speex-wb	.spx
Opus	opus / opus-wb / opus-swb	.opus

💡 小提示：如果需要处理这些音频格式，可以使用 FFmpeg、Audibility 等音频工具～

---

Q3：如何查看合成音频的隐性标识？🔍

答： 只需要将 implicit_watermark 参数设置为 true 就可以啦～

当音频编码设置为 lame（MP3） 时，查看MP3的元数据信息，会发现这样的标识：

Metadata: {"AIGC":{
  "Label":"1",
  "ContentProducer":"001191340000711771143J00000",
  "ProduceID":"ase00018773@dx19c4b750907b867772",  ← 这是本次请求对应的 sid 哦～
  "ContentPropagator":"001191340000711771143J00000",
  "PropagateID":"%!s(MISSING)"
}}

📌 注意：除了 ProduceID 是本次请求对应的 sid，其他字段都是固定的～

---

错误处理

调用失败时，请参照以下表格进行处理哦～ 🔧

错误码	说明	处理建议
❌	未配置环境变量	嗨呀～还没配置讯飞API凭证呢！请设置 IFLY_APP_ID、IFLY_API_KEY、IFLY_API_SECRET 这三个环境变量哦～
10009	输入数据非法	检查一下输入的数据吧～可能包含特殊字符或非法格式呢 🤔
10010	没有授权许可或授权数已满	抱歉，当前应用没有权限或配额用完啦！请联系讯飞提交工单处理哦～
10019	session 超时	会话超时啦！检查一下数据是否发送完毕但没有关闭连接呢 🔌
10043	音频解码失败	音频解码出错了～请检查编码参数是否正确设置呢～
10114	session 超时	会话时间超过60秒啦！加快发送速度试试看哦 ⏱️
10139	参数错误	参数写错了呢～请检查一下参数是否正确吧～
10160	请求数据格式非法	请求数据格式不对哦～确保发送的是合法的JSON数据吧 📝
10161	base64 解码失败	数据编码有问题！确保发送的数据已经过base64编码啦～
10163	参数校验失败	常见原因：发音人不支持该参数哦（比如某些发音人不支持 role 参数） 💡
10200	读取数据超时	超过10秒没发送数据就会超时哦～保持流畅输入吧 ⏰
10222	数据超限	上传数据超过接口上限啦！或者检查一下SSL证书呢 🔒
10223	lb 找不到节点	服务器内部问题～请联系讯飞提交工单哦 📮
10313	appid 和 apikey 不匹配	哎呀，APP_ID 和 API_KEY 不对应呢！去讯飞控制台核对一下吧～
10317	版本非法	版本有问题！请联系讯飞技术支持处理哦 🔧
10700	引擎异常	引擎出错啦！可以提供 sid 给讯飞提交工单排查哦 🐛
11200	功能未授权	没有开通超拟人语音合成服务哦～去讯飞控制台开通一下吧！
11201	每日次数超限	今天的调用次数用完啦！可以提交应用审核提额，或联系商务购买企业版哦 💰
11502	服务配置错误	服务器配置有问题～请联系讯飞提交工单哦 📮
11503	服务内部响应数据错误	服务器内部错误～请联系讯飞提交工单哦 📮
100001~100010	调用引擎时出现错误	提供 sid 及错误信息，联系讯飞技术人员排查哦 🔧

---

配置说明

1. 安装依赖

pip install websocket-client>=1.6.0

2. 获取API凭证

访问讯飞开放平台创建应用，获取：

• APP_ID：应用ID
• API_KEY：API密钥
• API_SECRET：API密钥私钥

3. 开通服务 & 购买套餐 🎁

如果还没有开通超拟人语音合成服务，可以通过以下链接进行开通或购买哦～

链接类型	地址	说明
🌐 服务控制台	讯飞控制台 - 超拟人语音合成	开通服务、管理应用、查看用量
💳 购买套餐	讯飞购买页面	购买语音包套餐

💡 小提示：新用户可能有免费试用额度哦～先去控制台看看能不能白嫖吧！😄

4. 配置环境变量

export IFLY_APP_ID="your_app_id"
export IFLY_API_KEY="your_api_key"
export IFLY_API_SECRET="your_api_secret"

兼容说明：设置任意 IFLY_* 凭证变量（包括空值）后，仅使用该组，缺项报错；未设置标准组时，依次尝试 XFEI_*、XFYUN_*，不跨组拼接。旧前缀会在 stderr 输出一次不含凭证值的迁移提示。

---

使用提示

1. 默认发音人：未指定 --vcn 时使用聆小糖（x5_lingxiaotang_flow），女声，中文普通话
2. 精选音色池：Skill 默认只支持 7 个精选发音人（聆小糖、聆飞瀚、温暖磁性男声、Grant、Lila、天津话、东北话）
3. 语言/方言控制：通过选择不同发音人(VCN)实现，不支持 --language、--style、--emotion 参数
4. 发音人授权：非免费发音人需在控制台开通对应权限后才可使用，否则返回 10163
5. 长文本处理：超过 64KB 的文本建议拆分处理
6. 推荐格式：推荐使用 --encoding lame --sample_rate 24000（MP3 / 24kHz）
7. 购买 & 文档：开通服务请访问服务控制台，购买套餐点这里哦～ 🎁