配音

脚本路径相对于此 SKILL.md，speak.py 从 film 文件夹运行。此步骤为可选：来自其他工具的录音或音频同样可用。将它们放在 audio/voice/<行ID>.wav，或在台词上设置 file。

用对方自己的语言与其交谈。

设置密钥（一次性）

费用由用户个人账户承担。请用户在自己的终端中运行以下命令：

python <dula-start 文件夹>/scripts/configure.py

在 Claude Code 中，用户可以输入 ! python <路径>/configure.py。

切勿在对话中询问密钥，也切勿读取或打印 ~/.dula-craft/config.env。 若要检查是否已设置密钥，请使用 configure.py --status。如果有人将密钥粘贴到对话中，请告知他们在控制台中撤销该密钥并创建一个新的。

在 config/film.json 的顶层添加 voices：

"voices": {
  "mochi": {"desc": "一个大约八岁的男孩，活泼开朗，语速快，呼吸轻盈"},
  "gran": {"desc": "一位七十岁的女性，声音温暖略带沙哑，语速慢，吐字非常清晰"}
}

台词可以包含 delivery：

{"id": "l03", "who": "mochi", "text": "真……真的？", "delivery": "惊讶又高兴，第一个字带颤抖，语气在结尾上扬"}

可选声音字段：lang 设置语言（默认使用台词的语言）；speaker 设置官方火山引擎语音 ID；reference 指向用户有权使用的参考音频。

用英文或台词的语言编写 desc 和 delivery。描述声音本身：年龄、紧张程度、气息、语速和音量。仅靠“快乐”无法改变声音。不要写成“听起来像某位演员或角色”，也不要选择模仿知名角色或真人的声音。声音同样具有形象权和版权风险。

python <此文件夹>/scripts/speak.py --dry-run   # 预览提示而不产生费用
python <此文件夹>/scripts/speak.py

每个角色的第一句台词将作为其后续台词的语音参考，因此请先试听第一句台词。如果效果不理想，修改 desc 并重新生成。修改第一句台词后，使用 --only 重新生成该角色的后续台词，使其跟随新声音。

当修改台词或声音并重新运行时，仅重新生成发生变化的部分。

python <此文件夹>/scripts/speak.py --sound "安静的老房间，远处偶尔有鸟叫" --seconds 10 --out audio/sfx/room.wav

始终提供 --seconds。 计费与时长挂钩，若不指定，片段可能持续 30 秒或更长。该参数为近似值，较短的请求往往会返回较长的片段。生成的片段通常音量较低，因此请在 film.json 中为故事音效设置 level_db（参见 film.json 参考）。

一次只生成一个音效。不要用一个提示同时生成对话、音效和音乐，否则无法分别调整音量层级，并且口型会出错。

尽可能试听。如果无法试听，请告知用户“此音频未经人工验证”。
你可以自行检查：确认时长是否合理（短句持续 5 秒可能有问题）。如果有 Whisper 等转录工具可用，将其转录文本与脚本进行对比。音量过低的单词可能会缺失，此时需要重新生成。
delivery 是一个请求，而非精确控制。停顿长度尤其不可靠，因此如果节奏不对，请缩短台词或重新生成。
相同的提示每次会得到不同的结果，因此在出错时重新生成。

症状	修复方法
`密钥被拒绝，或 Audio Generation 1.0 未启用`	检查该服务是否已启用。密钥必须来自语音控制台，Ark 密钥不适用
单词被误读	重新生成，或改写台词
各句台词听起来不像同一个人	确保第一句台词正确，然后用 `--only` 重新生成后续台词，或设置 `speaker`
台词末尾被截断	要求更慢的 `delivery`，或重新生成