DubbingX TTS 配音

要解决什么问题

给游戏、短剧或互动叙事配角色台词时，往往需要同一角色音色一致，还要按场景切换情绪、语速和语种。手工对接 DubbingX 智声云配 API 时，你要自己处理认证、查音色、提交异步任务、轮询状态再下载文件——流程分散，批量台词更难维护。

本技能把上述步骤收成 {SKILL_DIR}/scripts/ 下的一组脚本，用 CLI 参数对接 DubbingX，适合在 Agent 工作流里按角色批量出音。

技能如何工作

认证：在环境变量 DUBBINGX_API_KEY 中配置 Key（或在命令行传 --api-key），Key 在 DubbingX 客户端生成。

选音色：运行 list_voices.py，用 --grade（premium / ordinary / custom）、--gender、--age-group、--keyword 筛音色，确认每个角色的 voiceId。

单条试听（可选）：generate_tts.py 提交台词，支持 --text 中的停顿标签与段内音素标注；--emotion 对全情绪音色使用「类型-风格-档位」（见 emotion-map.md）；还可调 --language、--audio-speed、--audio-pitch、--format。返回 task_id 后，用 query_tts.py 查状态并下载。

批量配音：准备 JSON 配置后跑批量脚本，得到 task_map.json，再用 query_tts.py --task-map 集中下载。

任务状态：Completed 自动落盘；Generating / Ready 需等待；Failed 会给出错误信息。

适用边界与注意点

• API 为异步模型，提交后通常需几秒内轮询，脚本侧已按此设计。
• 全情绪（premium）音色情绪控制最细；V4 模型还支持 emotionCustom，可用自然语言描述情绪。
• 文本停顿用专用标签控制，单次最长约 20 秒。
• 情绪字符串格式与档位规则以 references/emotion-map.md 为准，避免与平台文档不一致。