VoiceMaster#

目标#

为短视频文案生成可直接交付的 AI 配音结果。优先输出单个 mp3 文件；无法本地合并时，返回分段下载卡片并明确片段顺序。使用 SenseAudio 官方接口文档：

• https://senseaudio.cn/docs/api-key
• https://senseaudio.cn/docs/text_to_speech_api
• https://senseaudio.cn/docs/voice_api

先检查环境变量 SENSEAUDIO_API_KEY。如果已经存在，直接使用；如果不存在，再提示用户提供 API Key 或先在终端设置环境变量。不要把密钥写进 SKILL.md、脚本源码或提交记录。

内置音色映射#

始终优先使用用户显式指定的 voice_id。未指定时，根据文案语气、角色设定和平台风格，从下表选择最贴近的音色，并在同一项目内保持角色映射稳定。

在当前 SenseAudio key 权限有限时，仅默认使用已确认可用的以下音色：

• child_0001_b：可爱萌娃，平稳
• male_0004_a：儒雅道长，平稳
• male_0018_a：沙哑青年，深情

不要默认选择未确认授权的 VIP / SVIP 音色。若接口返回 403 no access to the specified voice，优先回退到 child_0001_b，而不是重复尝试未授权音色。

yaml

VOICE_MAP:
  温柔女声: child_0001_b
  知性旁白: male_0004_a
  新闻主播: male_0004_a
  热血男声: male_0018_a
  沉稳纪录片: male_0004_a
  青春活力: child_0001_b
  电商促销: child_0001_b
  儿童陪伴: child_0001_b
  悬疑低语: male_0018_a
  治愈故事: child_0001_b
  儒雅道长: male_0004_a
  沙哑青年: male_0018_a
  可爱萌娃-平稳: child_0001_b

多角色文案处理规则：

1. 识别 角色名:、 旁白:、 主持人: 等显式说话人标记。
2. 为每个角色建立一次性 role -> voice_id 映射，后续所有分段复用同一映射。
3. 若当前 key 可使用的音色有限，允许多个角色共用同一音色，优先保证生成成功，不强行制造音色差异。
4. SenseAudio 单次请求只能使用一个 voice_id，所以多角色脚本不能整段一次性提交。
5. 多角色脚本必须先按角色台词切分为多个子片段，每个子片段只允许一个说话人。
6. 每个角色子片段分别调用一次 TTS，生成多个小段音频后再按原始顺序拼接。
7. 如果没有按角色逐段请求，而是把混合台词整段提交，那么最终听感会接近“全员同一音色”，这不算多角色配音成功。

输入整理#

在执行前整理以下信息：

1. 文案全文。
2. 目标风格，例如温柔、新闻感、励志、悬疑、剧情口播、带货。
3. 角色数量与角色关系。
4. 语速 speed。未指定时按风格估算，但必须限制在 0.5 到 2.0。
5. 音高 pitch。未指定时使用 0。
6. 输出文件名和输出文件路径。未指定时使用 voicemaster-output.mp3。

默认参数：

yaml

format: mp3
sample_rate: 44100
speed: 1.0
pitch: 0

对话草稿流程#

如果用户给的是完整、可直接配音的剧本，按现有流程直接整理角色、分段和音色即可。

如果用户提供的是以下任一输入形态，不要直接开始 TTS，先生成一版可编辑的对话草稿：

1. 只有主题、场景、人物关系或情绪方向。
2. 只有零散设定，没有明确的角色台词格式。
3. 用户明确表示“你先帮我写一版”“先出个对话”“先整理成剧本”。
4. 输入里角色边界、说话人、段落结构不清楚，无法直接安全切分成 TTS 片段。

执行顺序：

1. 先根据用户主题生成一版短视频可用的对话草稿，默认补齐角色名、台词顺序、必要旁白和基础节奏。
2. 输出草稿后，明确询问用户是否需要修改；不要在用户确认前直接生成音频。
3. 如果用户提出修改意见，就继续按意见改草稿，并再次等待确认。
4. 只有当用户明确表示“不需要修改”“就这样”“开始生成”“生成吧”等确认含义时，才进入配音阶段。
5. 进入配音阶段后，把最终确认版草稿视为正式剧本，再执行角色映射、分段、TTS 和拼接。

草稿要求：

1. 优先写成清晰的逐行对话格式，例如 旁白：...、 角色A：...、 角色B：...。
2. 单轮草稿先求结构清楚、节奏自然、便于后续分段，不追求一次写到最长。
3. 如果用户没有指定时长，默认按短视频口播场景控制在精简可配音的长度。
4. 如果用户没有指定角色数量，默认生成 2 到 3 个角色或“旁白 + 角色”结构，并在草稿里写清楚。
5. 草稿阶段可以顺带给出一句简短说明，例如“确认后我再开始生成配音”。

短视频对话草稿模板#

以下模板用于“先写草稿、再确认、后配音”的阶段。优先根据用户主题、平台风格和情绪目标，从中选择最贴近的一套，再按用户需求改写。

模板 1：旁白 + 人物冲突

适用场景：

1. 情绪故事。
2. 反转剧情。
3. 成长、遗憾、和解类短视频。

推荐结构：

1. 开场一句钩子。
2. 角色 A 抛出矛盾。
3. 角色 B 回应并升级情绪。
4. 旁白收束或反转。

草稿骨架：

text

旁白：那天以后，我才知道，有些话说晚了，就真的来不及了。
角色A：你当时为什么什么都不说？
角色B：不是我不想说，是我说了，你也不会信。
角色A：可你连试都没试过。
旁白：他们都以为自己受了委屈，却没人发现，对方也在硬撑。
角色B：如果再来一次，我不会再让你一个人扛。
旁白：有些误会，解开只要一句话；可有些人，等一句话等了一辈子。

模板 2：双人轻松聊天

适用场景：

1. 日常段子。
2. 朋友互怼。
3. 轻松种草。
4. 情侣、小剧场。

推荐结构：

1. 用一句生活化问题开场。
2. 两人来回两到三轮。
3. 结尾留包袱或结论。

草稿骨架：

text

角色A：你有没有发现，现在的人嘴上说早睡，手上却在刷到凌晨两点。
角色B：别骂了，我刚把“再看五分钟”演成了两个小时。
角色A：最离谱的是，第二天还要怪闹钟不懂事。
角色B：闹钟已经很努力了，是我的手不愿意放下手机。
角色A：所以问题到底出在哪？
角色B：出在我每次都以为，下一个视频一定不精彩。

模板 3：带货口播对话

适用场景：

1. 商品种草。
2. 直播切片。
3. 促销转化。
4. 用户痛点引导。

推荐结构：

1. 先抛用户痛点。
2. 角色提出质疑。
3. 另一角色给出解决方案。
4. 用结果感和行动指令收尾。

草稿骨架：

text

旁白：如果你也总觉得早上出门时间不够，那这段一定要看完。
角色A：我最怕的就是化妆麻烦、搭配麻烦，最后一着急全乱了。
角色B：那你就别再用一堆步骤堆时间了，先把最影响出门效率的那一步换掉。
角色A：问题是，便宜的怕不好用，好用的又怕太贵。
角色B：所以才推荐这种上手快、效果稳、价格也好接受的款，赶时间的时候特别省心。
旁白：想要省时间、少踩坑、直接提升出门效率，这种才是更适合日常复购的选择。

模板 4：知识解说对话

适用场景：

1. 冷知识。
2. 科普。
3. 职场技巧。
4. 学习方法。

推荐结构：

1. 用一个误区或问题开头。
2. 提问角色代表普通用户。
3. 解说角色给出拆解。
4. 结尾给出一句可执行建议。

草稿骨架：

text

旁白：很多人以为，做事效率低只是因为不够努力，但真相往往不是这样。
角色A：那到底卡在哪？我每天也没闲着。
角色B：问题不一定是你不努力，而是你总在用“切来切去”的方式消耗注意力。
角色A：所以我不是事太多，是一直在被打断？
角色B：对。你每切一次任务，大脑都要重新进入状态，时间就被一点点吃掉了。
旁白：如果你想先把效率提起来，先减少无意义切换，再谈更高强度的执行。

模板 5：悬念反转

适用场景：

1. 剧情号。
2. 反转短剧。
3. 都市情绪。
4. 高停留口播。

推荐结构：

1. 开头直接抛异常信息。
2. 两个角色围绕真相推进。
3. 中段制造误导。
4. 结尾用一句话反转。

草稿骨架：

text

旁白：所有人都以为，是她做错了。
角色A：证据都摆在这了，你还想怎么解释？
角色B：你看到的，只是别人想让你看到的。
角色A：如果不是你，那你为什么一直不说？
角色B：因为我一开口，他们就会知道，真正该怕的人不是我。
旁白：那天门一打开，大家才明白，原来从头到尾被算计的人，根本不是她。

模板 6：旁白 + 单角色自述

适用场景：

1. 情感独白。
2. 成长感悟。
3. 女性向/男性向口播。
4. 治愈系表达。

推荐结构：

1. 旁白给情绪背景。
2. 主角色连续两到三段自述。
3. 结尾落到态度变化或金句。

草稿骨架：

text

旁白：后来我慢慢发现，人最难放过的，往往不是别人，而是自己。
角色A：以前我总想把所有事情都做到最好，生怕别人失望。
角色A：可时间久了我才明白，你越是拼命讨好所有人，就越容易把自己弄丢。
角色A：现在的我，不是不认真了，只是终于学会了，把力气用在值得的人和事上。
旁白：成熟不是突然看开，而是一次次失望之后，终于学会把心收回来。

模板使用规则

1. 先选结构最接近用户目标的一套，再替换人物、场景、行业词和情绪词。
2. 如果用户只给一个主题，先用模板快速产出草稿，再问用户是否要往“更搞笑”“更催泪”“更带货”“更强反转”等方向修改。
3. 如果用户要求更短，优先删减旁白和重复解释，不先删核心冲突句。
4. 如果用户要求更像短视频爆款，优先强化第一句钩子和最后一句落点。
5. 草稿模板只是起点，不要机械照抄；生成时必须结合用户主题做定制化改写。

建议语速：

• 温柔叙事、治愈、情感类： 0.88 到 0.98
• 新闻播报、知识解说： 0.98 到 1.08
• 励志混剪、节奏短视频： 1.05 到 1.18
• 直播带货、促销叫卖： 1.12 到 1.25

若可用音色受限，默认采取以下补偿策略：

• 资讯、纪录片、旁白：优先 male_0004_a，语速 0.92 到 1.0
• 情绪故事、深情文案、悬疑口播：优先 male_0018_a，语速 0.88 到 0.98
• 带货、轻松内容、儿童感场景：优先 child_0001_b，语速 0.96 到 1.08
• 通用兜底： child_0001_b
• 不对用户隐瞒音色降级：在结果里明确说明“当前 key 仅可使用已授权音色”

分段策略#

当文本超过 500 字时，必须自动进行逻辑分段请求，避免超时。

执行规则：

1. 按段落、场景切换、说话人切换、完整句号优先切分。
2. 将每段控制在 180 到 450 字之间，避免把一句话拆开。
3. 为每段保留原始顺序编号，从 01 开始。
4. 多角色场景中，不要把同一轮对话拆到不同片段。
5. 全部片段生成完成后，优先使用 helper.py concat 合并为一个 mp3。
6. 如果一个片段内部仍然包含多个角色行，继续细分到“单片段单角色”再调用 TTS。

API 请求模板#

API 地址固定为：

text

https://api.senseaudio.cn/v1/t2a_v2

优先使用 jq 构造 JSON，避免转义错误。默认走非流式模式，便于直接拿到 hex 音频并落盘。

重要：先按最小请求体调用官方接口，不要一开始就附带全部可选字段。若接口返回 400 input content type is not supported，优先怀疑请求体结构与官方当前协议不一致，而不是继续切换音色。

请求模板：

bash

jq -n \
  --arg text "$TEXT" \
  --arg voice_id "$VOICE_ID" \
  --arg model "SenseAudio-TTS-1.0" \
  '{
    model: $model,
    text: $text,
    stream: false,
    voice_setting: {
      voice_id: $voice_id
    }
  }' |
curl -sS "https://api.senseaudio.cn/v1/t2a_v2" \
  -H "Authorization: Bearer $SENSEAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @-

最小请求体跑通后，再逐步增加以下可选字段，每次只增加一类：

1. voice_setting.speed
2. voice_setting.pitch
3. audio_setting.format
4. audio_setting.sample_rate
5. audio_setting.bitrate
6. audio_setting.channel

多片段请求时，额外在本地维护上下文元数据即可，不要求额外提交给官方接口。保持每段 model、 voice_setting、 audio_setting 一致。

SenseAudio 响应处理#

SenseAudio 非流式 TTS 的成功响应为 JSON，其中 data.audio 是 hex 编码的音频数据。处理规则如下：

1. 先检查 base_resp.status_code 是否为 0。
2. 若成功，读取 data.audio 并按十六进制解码为二进制音频文件。
3. 使用 extra_info.audio_length、 extra_info.audio_sample_rate 作为结果回执。
4. 若 data.audio 为空或 status_code 非 0，直接返回 base_resp.status_msg。

响应结构参考：

json

{
  "data": {
    "audio": "hex编码音频",
    "status": 2
  },
  "extra_info": {
    "audio_length": 3500,
    "audio_sample_rate": 44100
  },
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

返回结果处理#

1. 调用 helper.py synthesize 发送请求并把 hex 音频保存到本地。
2. 长文案分段时，将每段保存为 segment-01.mp3、 segment-02.mp3。
3. 多角色场景中，进一步保存为更细粒度的角色片段，例如 segment-01-narrator.mp3、 segment-02-youngman.mp3。
4. 全部片段完成后，调用 helper.py concat 生成最终文件。
5. 如果 ffmpeg 不可用，则保留分段文件并把路径按顺序返回给用户。
6. 如果返回里没有 data.audio，把完整原始 JSON 一并带回，便于后续比对协议变更。

示例：

bash

python helper.py synthesize ^
  --text-file segment-01.txt ^
  --voice-id male_0004_a ^
  --speed 0.96 ^
  --pitch 0 ^
  --output outputs\segment-01.mp3

bash

python helper.py concat ^
  --output outputs\final.mp3 ^
  outputs\segment-01.mp3 outputs\segment-02.mp3 outputs\segment-03.mp3

helper.py 用法#

仅在以下情况调用本地脚本：

• 需要把 SenseAudio 的 hex 音频响应落盘。
• 长文案需要本地合并多个片段。
• 需要统一输出文件名和目录结构。

命令概要：

text

python helper.py synthesize --text-file <segment.txt> --voice-id <voice_id> --output <file.mp3>
python helper.py concat --output <final.mp3> <segment1.mp3> <segment2.mp3> ...

输出要求#

完成配音后，始终给出：

1. 使用的 voice_id，以及为何匹配该风格。
2. 实际 speed 与 pitch。
3. 最终音频文件路径。
4. 如果做了分段，说明分段数量与是否已成功合并。
5. 若请求失败，返回 SenseAudio 的 status_code 与 status_msg。
6. 如果因为套餐权限限制降级到授权音色，明确写出降级原因与最终使用的 voice_id。

背景音乐建议#

配音完成后，必须根据文案情感推荐 2 到 3 种背景音乐方向，避免只给宽泛标签。按以下映射优先推荐：

• 悲伤、遗憾、追忆：钢琴氛围、弦乐极简、低速 lo-fi
• 励志、成长、逆袭：电影感激励、流行摇滚推进、企业宣传 uplift
• 温馨、治愈、亲子：木吉他轻快、暖感钢琴、轻爵士刷鼓
• 悬疑、反转、故事感：暗色脉冲、稀疏打击乐、电子氛围 tension
• 带货、促销、种草：明亮电子流行、节奏 house、funk 轻律动

输出建议时，同时说明：

1. 适合的镜头节奏。
2. 是否应低音量铺底，避免压住人声。
3. 是否需要在转场处加鼓点或上升音效。

执行原则#

1. 优先保证语气和角色一致性，再追求绝对快速度。
2. 对未明确的风格参数做合理估算，但必须在回复中写明使用了什么默认值。
3. 如果用户输入还不是正式剧本，先走“对话草稿流程”，不要抢先调用 TTS。
4. 遇到长文本时，默认启用分段，不要一次性硬请求超长文案。
5. 如果本地缺少 ffmpeg，返回按顺序编号的分段结果，并说明未执行自动合并。
6. 如果用户未提供已验证可用的 voice_id，按以下顺序优先尝试： male_0004_a、 male_0018_a、 child_0001_b。
7. 多角色配音的真实前提是“逐角色多次请求并拼接”，不是仅在文本里写出多个角色标签。
8. 只有在用户明确确认最终草稿后，才开始生成音频；确认前的工作以写稿和改稿为主。