drama-voice-assign

name	drama-voice-assign
description	火火短剧 · 音色分配 Agent 技能规范

火火 · 短剧音色分配

本技能服务于短剧工作台「分配音色」步骤：从当前项目 audio 配置对应 provider 的音色库（MiniMax、阿里等）为分集角色挑选 voice_id，供 TTS 试听与分镜配音使用。

流水线位置

方向	说明
上游	角色场景提取产出的本集 cast（character_id）
本步产出	各角色 音色 ID（写入 voice_id 字段）
下游	分镜 TTS / 试听

核心目标

• 为每个有台词 / 有画外音的本集角色分配唯一一个 voice_id
• 与项目已有分配保持一致；同角色跨集音色不变
• 同集内主要角色音色辨识度高，群演音色中性不抢戏

输出契约（与 apply_cast_voice_mapping 工具对齐）

对每个需分配的角色，调用一次 apply_cast_voice_mapping：

参数	含义
character_id	cast 行 ID（来自 pull_cast_voice_state）
voice_id	必填，来自 list_tts_voice_catalog 返回的音色 ID 字符串
reason	可选，一句话分配理由（便于用户审计）

说明：

• 工具不接收单独的展示名字段；展示名由系统根据 provider + voice_id 解析
• list_tts_voice_catalog 返回的 provider 以本集 audio 配置为准，不要假设一定是 MiniMax
• 旁白 / 画外音若使用独立音色，同样对对应 cast 行调用 apply_cast_voice_mapping

匹配维度

1. 性别：男角男声、女角女声；非人类角色按设定或旁白处理
2. 年龄段：少年 / 青年 / 中年 / 老年音色分层
3. 性格气质：
   • 活泼 → 明亮、语速略快
   • 沉稳 → 偏低、节奏稳
   • 温柔 → 柔和、气声少
   • 威严 → 浑厚、咬字清晰
4. 戏份：主角选辨识度高音色；龙套用中性、不易抢戏音色

推荐工具流

1. list_tts_voice_catalog — 拉取当前 provider 可用音色表
2. pull_cast_voice_state — 本集 / 项目角色与已有 voice_id
3. 按匹配维度逐角分析，列出候选音色
4. apply_cast_voice_mapping — 逐角写入（每个有台词角色至少一次）
5. 向用户汇总：角色名 → voice_id → 简要理由

同集饱和度避雷

• 同集中主要出场角色音色避免过于接近（避免 4 个中年男声都是低沉款）
• 主角与最常对戏的对手音色要形成辨识反差（一个偏高一个偏低，或一个快语速一个稳）
• 群演 / 路人优先复用同一中性音色，不必每人一色
• 若音色库存量紧张，至少让主角 + 1–2 个关键配角形成可识别差异

改主意 / 重分配策略

• 用户对某角色指定具体音色 → 优先满足，写入 voice_id 即视为用户指定，后续不再覆盖
• 用户未指定但已有 voice_id → 默认沿用，除非同集中存在音色冲突需要替换
• 跨集一致性：同一 character_id 的 voice_id 在所有集保持一致
• 重分配时输出旧 → 新对照，便于用户回滚

输出前自检清单

• 本集所有有台词的角色都已调用 apply_cast_voice_mapping，无遗漏
• 同一 character_id 在所有集中 voice_id 一致
• 主要角色之间音色差异明显（音高 / 音色 / 节奏 任一维度）
• 群演音色保持中性、可复用
• 使用的 voice_id 均来自本次 list_tts_voice_catalog 返回值
• 给用户的汇总包含「角色 → voice_id → 理由」

示例：性格 → voice_id → 理由

角色	性格 / 戏份	选型方向	简要理由
江言	19 岁女主、活泼、机灵	青年女声 / 明亮偏甜	与沉稳男主形成反差
傅深	30 岁男主、外冷内热	青年男声 / 中低频 / 节奏稳	与女主音高、节奏拉开
旁白	全集第三人称叙事	中性沉稳男声	与所有对白角色区隔

反例（不要这样做）

反例	问题	改法
给主角和 3 个反派都选同一款低沉男声	主配音色糊在一起	主角保留该音色，反派选不同频段
同一 character_id 跨集换不同 voice_id	跨集不一致	复用 pull_cast_voice_state 中已有值
群演每人一色	增加辨识负担	统一为 1 个中性音色
手写 voice_id 字符串而不调 apply_cast_voice_mapping	未落库	必须调用 apply_cast_voice_mapping
假设只有 MiniMax 音色	provider 可能为 ali 等	以 list_tts_voice_catalog 实际返回为准