脚本与语音
语音是视频的时钟。动画的每一个节拍都锚定在旁白的单词上(在 build.py 中为 T[clip] + w(clip, "word")),因此脚本及其片段先于动画产生,更改一个句子只需重新生成一个片段及之后的所有时间。在这些技能所源自的制作流程中,更换整个 TTS 引擎后,无需任何手动编辑即可重新同步已完成视频的时间线,这正是因为上述设计。先制作动画再适配语音意味着每次修改都需要手动拉伸音频或拖拽节拍。
仅写入 <video_dir>/audio/(以及 BRIEF.md 中的脚本章节)。每个句子必须在 TRUTH.md 中有依据,并遵守 CLAIMS.md;如果您需要的句子没有来源,请请求验证或删除。
脚本调用方式,详见 docs/contracts.md:
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
S="$PVS_HOME/skills/script-and-voice/scripts"
"$PVS_HOME/bin/pvs-py" "$S/check_script.py" <video_dir> # 检查 lines.tsv
"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir> [--only N3,N4] [--provider say] [--force] [--restore]
"$PVS_HOME/bin/pvs-py" "$S/pronounce_check.py" <video_dir> [--only N3] # ASR 是否识别了品牌词?
"$PVS_HOME/bin/pvs-py" "$S/make_sfx.py" <video_dir> [--list] # sfx.tsv,或列出音效库
1. 脚本是时刻表
产品录制是参考,而非时间线:真实的加载等待和屏幕变化不应出现在视频中。将脚本编写为多个时刻,每个时刻包含屏幕上发生的内容、句子(或静默)及其持续时间。一个时刻的持续时间等于其动作和句子中较长者。压缩真实等待时间:四十秒的加载约改为两秒的思考状态。
将表格添加到 BRIEF.md 的 ## Script 下方,按章节顺序排列:
| 时刻 | 屏幕内容 | 台词编号 | 文本(或静默) | 保持时长 |
|---|---|---|---|---|
| 开场 | 产品名称,背景为失焦的应用 | N1 | 这是 Acme Tasks,一款为您规划日程的待办事项列表。 | 结束后 0.8 秒 |
| 等待 | 计划正在生成 | (静默) | 2.0 秒 |
然后根据视频格式选择模板并遵循其结构:阅读 references/script-templates.md(宣传片、导览、文档页、教程、静默循环)。
如何编写台词及其理由:
- 解释重要功能,而非罗列。 在 UI 展示功能的同时,说明它对用户的作用。在这些技能所源自的制作中,26 个版本中有 9 个是因为视频仅提及功能名称而未加解释。COVERAGE.md 指出哪些功能必须在屏幕上解释:每个标记为“必须解释”的行至少需要一句解释性台词。
- 向从未见过该产品的人解释每一步骤。 角色是谁,他们请求什么,每个步骤的作用。在审核中,一段快速且未作解释的开场被拒绝。
- 每个句子一个想法,每个片段一个句子。 修改一个句子只需影响一个片段。
- 当光标触摸某元素时,在台词中说出其名称。 节拍锚定在这些单词上,因此屏幕上的名词和片段中的单词必须一致。
- 使用真实的 UI 标签,即使审核者使用其他词语。这样视频才能与用户在应用中看到的匹配。
- 将数字和时间写为单词("ten a.m.","thirty minutes later")。TTS 引擎对数字的读取不一致,且语音转文字的质量检查比较的是单词,而非数字。
- 在等待前后留出空档。 电话铃响前约三秒,使用"about a minute"而非无人能验证的精确数字。
- 以完整的句子结尾,语速稍慢。 在审核中,末尾的标语片段听起来像被截断;而包含 CLAIMS.md 定位的完整句子则不会。
- 保持视频内人称一致:第一人称作为虚构用户("First, I connect my calendar.")或第三人称描述用户。仅使用 product.yaml 中的虚构演员,并在每个视频中使用相同名称。
- 定位来源于 CLAIMS.md,而非源文档:源文档可能包含团队已禁止的短语,规则优先。
2. lines.tsv
audio/lines.tsv,制表符分隔,表头为 id\trole\tspeed\ttext,每行一个片段,按播放顺序排列,# 行为注释。完整格式及 build.py 如何读取结果:references/audio-formats.md。
- id:旁白使用
N1、N2、N7b;其他字母代表角色(A1表示客服代表,C1表示客户)。在 N7 和 N8 之间插入一行作为N7b可以保持其他所有 id 及其使用的锚点稳定。 - role:product.yaml 中
voice.roles的一个键(narrator、agent、customer,或如narrator_close的变体,见第 3 节)。语音由角色而非 id 选择。 - speed:默认为 1.0,范围 0.7 至 1.2。开场和结束行使用 0.9 至 0.96。
- text:与屏幕和字幕中的显示完全一致,使用产品名称的标准拼写。此处绝不要写入重拼;发音修正位于 product.yaml 中。
在修改已交付版本的台词前,将 lines.tsv 复制为 lines-v<N>.tsv,并将 timings.json 复制为 timings-v<N>.json,以便可以重新构建先前版本。
每次编辑后运行 check_script.py。该脚本会检查重复 id、未知角色、语速超出范围、超过 40 个单词的片段、禁用术语、never_say 短语、遗留名称以及脚本中的重拼,并对长片段、数字和破折号发出警告。在配音前修复所有错误:禁用短语一旦进入 TTS 就会耗费一次录制版本,而一旦进入渲染则会耗费一个发布版本。
3. 选角
在提议语音前请阅读 references/casting-and-pronunciation.md。简而言之:
- 优先提供逼真的语音。产品自带的默认语音和最便宜的模型在审核中被评价为“非常假”;对角色而言,最自然的可用模型值得投入。
- 在上文中试听:每个角色使用两句连续的台词,每个角色提供三到六个候选。
- 将每个选择作为封闭式问题提出,并附带推荐默认项("旁白:语音 B,温暖且从容。保留吗?")。开放的选项列表会连续数天无人回应。
- 确定每个角色的处理方式:
treatment: phone用于通话中的人,treatment: room用于录制的会议,旁白无需处理。 - 每行特有的朗读方式(更平稳、更慢、风格更少)是一个角色变体,指向同一语音但使用其他设置,因此选择在配置中,并且重新运行后仍可保留。
voice.provider: say(或 --provider say)使用免费的 macOS 语音和 whisper 获取单词时间戳。在密钥就绪前,将其用于草稿、测试和时间线工作;最终交付时使用真实语音。
4. 生成片段
"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir>
对于每一行,它仅对 TTS 重拼品牌词,将未经处理的录制版本保留在 audio/raw/ 中(先前的录制版本移至 audio/raw/prev/),修剪静音,重采样为 48 kHz 单声道,应用角色处理,归一化至 voice.clip_lufs(使用 ffmpeg loudnorm,两次通过;峰值低于 -1.5 dBTP),淡入淡出,并将该片段的条目合并到 audio/timings.json 中。
每个处理步骤的存在理由:
- 原始录制版本始终归档并作为源文件。 早期客户在完全重新渲染后从一个过时的原始文件进行了归一化;现在每个片段始终从生成它的录制版本重建。
- 尾部在最后一个单词后最多 0.6 秒处裁剪,并带有淡出。 TTS 片段可能以点击声或另一个短语的开头结束;有一次这样的点击声以音频中“奇怪的剪切”形式发布。
- 每个片段具有相同的响度。 一个角色语音在归一化前比旁白高出 6 dB。
- 未更改的行将被跳过(基于
audio/raw/cache.json中文本、语音和设置的哈希值),因此编辑一行后完整运行只会调用一次提供者。如果只更改了clip_lufs或处理方式,片段将免费从已归档的录制版本重建。--force会无论如何请求新的录制版本。
密钥由脚本从环境变量或 PVS_HOME/.env 读取,且从不打印。请勿自行读取 .env 或在聊天中询问密钥:如果密钥缺失,告知用户自行将行添加到 .env,或切换到 say。
在任何新录制版本后运行 pronounce_check.py。它会在不提示 ASR 的情况下转录每个片段,标记未被识别的品牌和演员词、被听到的遗留名称以及发音偏移的元音(第 5 节)。标记意味着需要聆听,而非重新生成:ASR 可能会误听正确说出的品牌词。
5. 发音
脚本和屏幕保留真实拼写。product.pronounce 仅更改发送给 TTS 的内容,而 tts.py 会将时间戳映射回来,因此 timings.json 在 w 中保留屏幕单词,在 say 中保留重拼({"w": "Acme", "say": "AK-mee", ...})。build.py 中的锚点使用屏幕单词。
product:
pronounce:
Acme: AK-mee # 简单重拼
Acme Tasks: {say: AK-mee Tasks, vowel: ae, confusable: ey} # 含首元音检查
当审核者说名称发音错误时,尝试在同一行上测试三四种重拼,使用元音检查进行测量,保留通过的那个,然后检查包含该单词的其他所有行:提供者在不同录制版本中可能不同。详情和元音表:references/casting-and-pronunciation.md。
6. 录制版本
- 除非用户另有说明,每行最多两个录制版本;提供者配额通常由团队共享。在运行前告知用户完整运行将消耗多少字符。
- 仅重新生成需要修改的行:
tts.py <video_dir> --only N7 --force。 - 如果新录制版本更差,使用
--only N7 --restore将其与时间戳一起换回。 - 对于语调调整("太嗨"、"听起来像半句话"),制作两三个变体(角色变体或语速变化),让审核者在上文中与前一行的内容进行比较。
- 修改一行,按顺序:复制版本文件,编辑行,运行
check_script.py,运行tts.py --only <id>,运行pronounce_check.py --only <id>,然后合成器重新构建;该片段之后的所有内容会自动调整。
7. 音效
仅使用录制的音效,来自 HyperFrames 附带的音效库(make_sfx.py --list)。合成的打字声在审核中被评价为“像吸管声,不像键盘声”,合成嗖嗖声则像“白噪声”,因此脚本拒绝使用嗖嗖声和上升音效,除非简报要求,否则旁白下方不添加音乐。这些技能所源自的制作没有背景音乐和闪避处理,也无人怀念。
- 打字:
typing_track(text, start, cps)使用从真实录音中剪切的单个按键声构建音轨,空格键使用更重的击键,并具有种子节奏,因此它是确定性的,同一段文本始终听起来相同。使其持续时间恰好等于显示文本的节拍长度(dur=),并让打出的单词与说出的单词对齐。 - 点击和爆破音:在光标按下的帧上使用
library_sfx("click", start)。 audio/sfx/CREDITS.md列出使用的每个音效库文件并附有音效库许可证。- 建议的电平:旁白 1.0,角色 1.0,点击 0.35(拖拽释放时为 0.22),打字 0.45,爆破音 0.12 到 0.3。同一音频轨道上的两个片段绝不能重叠:片段开始时间至少比前一个片段结束时间晚 0.02 秒,或将其移至另一轨道。
build.py 导入这些函数;make_sfx.py <video_dir> 配合 audio/sfx.tsv 可从命令行预构建相同的文件(格式见脚本的文档字符串)。
8. 移交给合成器
交付到 <video_dir>/audio/:lines.tsv、clips/<id>.wav、timings.json 以及带有 CREDITS.md 的 sfx/。告知合成器每个节拍应锚定到哪些单词(光标触摸的名词,打字落定的单词)以及时刻表中的等待时长。切勿手动编辑 timings.json:它会从片段重新生成,手动编辑将在下次运行时丢失。
向用户报告:已配音的行、每个片段的时长、任何发音标记及其内容、使用的语音(对任何未决定的内容提供推荐的默认选项)以及消耗的提供者字符数。