PR 解说视频
为拉取请求创建一个带音频旁白的解说视频。这被设计为一个内部制品,其目的类似于PR作者创建的一个Loom视频——逐行讲解代码变更,解释做了什么以及为什么这样做,以便任何观看者能快速理解PR。
输入: 一个GitHub拉取请求URL(例如,https://github.com/tldraw/tldraw/pull/7924)。如果只给了一个PR编号或其他描述,则假定该PR位于tldraw/tldraw仓库中。
输出: 一个1280×720(30帧/秒)的MP4视频,带音频旁白、whisper定时的黄底黑字字幕,以及标准化的开场/结束幻灯片,保存为 out/pr-<number>-walkthrough.mp4。
所有中间文件(音频、清单、脚本)都放在相对于此技能目录的 tmp/pr-<number>/ 目录下。此目录已被git忽略。只有最终的 .mp4 文件位于 out/ 目录下。
从本技能目录运行引用 ./scripts 或 ./video 的命令。
理念
这是从作者视角进行的一次解说。 目标与PR作者坐下来向某人逐行讲解变更一样——展示具体代码,解释改变了什么以及为什么,并按照增进理解的顺序进行。观看者应该能够理解代码的功能以及如何看待这些变更。
这意味着:
- 旁白驱动一切。 首先编写旁白,作为对PR的连续解释。然后再决定每一时刻屏幕上应该显示什么来支持讲述的内容。
- 展示代码。 默认的可视化内容是代码差异或源文件。文字幻灯片是例外(开场、简短过渡、结尾),而不是常规。当旁白提到一个函数时,观看者应该正在看着那个函数。
- 按逻辑顺序讲解变更,不一定是文件顺序或提交顺序——但始终锚定在具体的代码上,而不是抽象的描述。
- 解释“为什么”,而不仅仅是“是什么”。 屏幕上的代码展示了什么改变了。旁白补充了推理——为什么选择这种方法,它解决了什么问题,它处理了什么边缘情况。
工作流程
步骤1:理解PR
阅读PR的提交、差异和描述。理解叙事弧:
- 这解决了什么问题?
- 方法是什么?
- 关键机制是什么?
gh pr view <number> --json title,body,commits
git log main..HEAD --oneline
git diff main..HEAD --stat
跳过自动生成的文件。 在阅读差异时,忽略自动生成而非手动编辑的文件。这些只会增加噪音而无助于解说。此仓库中的常见示例:
**/api-report.md,**/api-report.api.md— 生成的API表面报告**/*.api.json,**/temp/*.api.json— API提取器输出apps/docs/content/reference/**— 生成的参考文档pnpm-lock.yaml,package-lock.json— 锁定文件**/CHANGELOG.md— 自动生成的变更日志- 仓库工具重新生成的任何文件(快照、模式转储、打包资源)
如果不确定一个文件是否自动生成,请检查是否有类似“DO NOT EDIT”的头部注释,或者检查仓库是否有生成该文件的生成器命令。在选择要在 diff / code 幻灯片中展示哪些文件时,过滤掉这些文件。
步骤2:编写旁白
将旁白写成连续文本,分成逻辑段落。每个段落都是解说的一个节拍——一个概念、一个变更或一组相关的变更。将其保存为 tmp/pr-<number>/SCRIPT.md。
旁白应该像作者向同事解释PR一样:“那么,这是我们所做的...核心问题是X...我采用的方法是Y...如果你看看这个函数...”
结构:开场 → 背景/问题 → 代码讲解 → 总结。参见下面的脚本结构。
如果提交简单且组织良好(通常位于名称带有 -clean 的分支上),你可以按照它们的提交消息和描述来指导你的旁白。否则,检查代码并创建自己的叙事。按照能建立在先前概念之上的顺序引入概念。
避免冗余,尤其是在开场和第一个内容段落之间。
步骤3:生成音频和时间戳
每段调用一次TTS生成每段音频片段。这完全避免了分块、对齐和分割——每个段都足够短,以便单次可靠的TTS调用。
编写一个 narration.json 文件,然后运行 generate-audio.sh CLI工具:
./scripts/generate-audio.sh narration.json tmp/pr-<number>/
API密钥: 从仓库 .env 文件(GEMINI_API_KEY)自动获取。
旁白JSON格式
{
"style": "以平静、稳定、专业的语气朗读以下解说旁白。以适中的速度说话,就像拉取请求的作者在向同事讲解代码变更一样。",
"voice": "Iapetus",
"slides": [
"此拉取请求为箭头工具添加了组感知绑定解析...",
"核心问题是当目标形状被分组时箭头绑定会失效...",
"如果你看看ArrowBindingUtil.ts中的getBindingTarget方法..."
]
}
style— 语音角色和语速说明。保持简短具体。voice— Gemini语音名称(默认:Iapetus)。slides— 旁白文本数组,每段一个条目。
工作原理
- 对于每个段落,脚本构建一个提示:风格前言 + 段落文本。
- 每个段落调用一次
gemini-3.1-flash-tts-previewAPI,直接生成一个WAV片段。 - 每个片段都经过验证(基于字数的时长合理性检查),如果输出不佳则自动重试。
- 每个片段的前导/尾部静音被修剪。
输出: 每段音频片段 (audio-00.wav, ...) 和一个 durations.json 文件,将每个音频文件名映射到其时长(秒)。
依赖项: ffmpeg / ffprobe。除了标准库外,不需要Python包。
不要在旁白文本中使用 [pause long] 或 [pause medium] 标记标签——模型可能会字面地读出来。
步骤4:编写清单
读取步骤3中 durations.json 中的每个片段时长,然后在音频文件旁边编写 manifest.json。它按顺序列出每个幻灯片的条目,每个条目包含 type、audio 和 durationInSeconds。
参见 references/manifest.md 了解幻灯片类型及其字段。
步骤5:渲染视频
运行 render.sh 脚本:
./video/render.sh \
tmp/pr-<number>/manifest.json \
out/pr-<number>-walkthrough.mp4
该脚本:
- 将引用的音频/图像文件复制到
video/assets/。 - 对每个音频文件运行whisper转录 →
video/transcripts/audio-NN.json(幂等——仅当音频比现有转录更新时才重新转录)。 - 运行
build.mjs <manifest>生成video/index.html——一个带有每个幻灯片定时片段的hyperframes合成,包含GSAP时间线用于过渡和代码聚焦平移,以及基于whisper转录的开始/结束时间推导出的黄底黑字字幕片段。 - 检查合成正确性并通过
npx hyperframes render渲染1920×1080帧。 - 通过ffmpeg降采样到1280×720 / 30帧/秒并重新压缩(CRF 26 + AAC 96k),生成最终小而清晰的MP4。
依赖项: Node.js 22+、ffmpeg、Python 3(由 render.sh 用于解析清单)。hyperframes 通过 npx --yes 调用,因此无需安装步骤。Whisper在本地运行(small.en模型,首次下载约150MB)。
通过whisper同步字幕
字幕以黄色文本显示在纯黑色药丸形状背景上,锚定在帧底部。它们的开始/结束时间来自whisper词级转录,按5-7个词分组,在自然停顿处提前断开(>450ms间隙 = 句子边界)。一个含义是:whisper会音译品牌/代码名称——例如,“tldraw” → “TL Draw”,“OverlayUtil” → “overlay util”。这对于字幕是可以接受的,但以后可以通过 build.mjs 中的替换表进行规范化。
文件大小调节
默认渲染目标为8分钟视频大约30-60 MB。要调整:
render.sh内ffmpeg降采样步骤中的--crf <n>——22接近无损,26是默认值,30+则更小。CRF 28-30是获得文档质量结果的良好范围。- 1080p hyperframes渲染使用
-q draft --crf 30来保持中间文件较小(无论如何降采样主导最终大小)。
文件组织
最终输出位于此技能目录中。所有中间文件都放在 tmp/ 目录(已git忽略):
pr-walkthrough/
├── SKILL.md # 本文档
├── scripts/ # CLI工具(已检查)
│ └── generate-audio.sh # narration.json → 每幻灯片WAV + durations.json
├── video/ # Hyperframes项目(已检查)
│ ├── hyperframes.json # hyperframes配置
│ ├── meta.json # 项目元数据
│ ├── build.mjs # manifest.json → index.html 合成
│ ├── render.sh # manifest.json → 720p MP4(完整流水线)
│ ├── assets/ # 渲染时自动填充(已git忽略)
│ ├── transcripts/ # Whisper词级JSON(已git忽略,缓存)
│ └── renders/ # 中间1080p渲染(已git忽略)
├── out/ # 最终输出(已git忽略)
│ └── pr-XXXX-walkthrough.mp4
└── tmp/ # 中间文件(已git忽略)
└── pr-XXXX/
├── SCRIPT.md # 旁白脚本
├── narration.json # 输入给generate-audio.sh
├── durations.json # 音频文件名 → 时长(秒)
├── manifest.json # 输入给render.sh
└── audio-XX.wav # 每段音频片段
API配置
- Gemini API密钥: 存储为项目根目录下
.env文件中的GEMINI_API_KEY。用于TTS和音频对齐。 - TTS模型:
gemini-3.1-flash-tts-preview - TTS语音:
Iapetus(始终)
脚本结构
解说遵循一致的叙事弧。并非每个部分都需要自己的段落——根据PR的复杂度合并或跳过部分。目标是总共8-12个段落,其中绝大多数显示代码。
开场(1个段落)
开场卡片:tldraw标志 + PR标题 + 日期。旁白应该是一个句子,在高层次上概述此PR的功能。暂时不要深入细节。
清单幻灯片类型:intro。
背景(0-1个段落)
在深入代码之前进行简要介绍。在此PR之前的情况是什么?什么问题或需求推动了这项工作?保持简短——只需足够的框架使代码讲解有意义。
- 要具体:“当目标形状在组内时箭头绑定失效”而不是“绑定系统存在问题”
- 指出受影响的代码库区域
如果在展示第一段相关代码的同时可以解释背景,则跳过独立的背景段落,将其合并到第一个代码段落中。
清单幻灯片类型:text 或 diff(如果展示有问题的代码)。
代码讲解(6-10个段落)
视频的主体部分。逐行讲解实际的代码变更,展示具体的差异和文件,同时解释做了什么以及为什么。
每个段落都应该显示代码。 使用 diff 幻灯片展示变更,使用 code 幻灯片展示未变更的参考代码。
指南:
- 命名文件和函数。 每个旁白段落至少应引用一个特定的文件或函数。
- 显示差异。 每个段落的可视化内容应该是正在讨论的实际差异。使用
git diff main..HEAD -- path/to/file获取差异,然后提取相关的hunk。 - 按理解顺序排列,而不是按文件排列。 按照构建理解所需的顺序展示变更。如果一个新类型在一个文件中定义并在另一个文件中使用,则先展示定义。
- 解释“为什么”,而不仅仅是“是什么”。 差异显示了什么改变了——旁白补充了推理、它处理的边缘情况、考虑过的替代方案。
- 跳过样板代码,但提一下。 不要为每个导入变更或类型导出都专门做一个段落,但可以在旁白中顺便提一句:“还有一些在
index.ts中添加的类型导出——它们只是我们接下来将看到的新类型的重新导出。” - 将相关的小变更分组。 如果三个文件都得到了相同的一行修复,一个段落可以覆盖所有三个。通过名称提及每个文件。
总结(1个段落)
简要回顾PR完成了什么。这是一个简短的收尾部分——一两句总结整体变更,如果相关,提及任何已知的限制或后续工作。
清单幻灯片类型:text。
结尾(1个段落,静默)
tldraw标志,3秒静默。始终将此作为最后一张幻灯片。
清单幻灯片类型:outro,durationInSeconds: 3。
旁白编写技巧
- 对代码要具体。 说“在
BindingUtil.ts中,onAfterChange处理程序现在检查组祖先”——而不是“绑定系统已更新。”命名文件和函数,以便观看者将旁白与屏幕上的内容联系起来。 - 每个段落 = 一个变更或紧密相关的变更组。 如果你无法为段落指出一个具体的差异,它可能太抽象了。
- 以作者身份写作。 语气应该是解释性和自然的——就像在带人查看你的工作。“所以主要的事情是...”或“棘手的部分是...”都是可以的。
- 避免开场和第一个内容段落之间的冗余。
- 提及未显示的文件。 如果一个PR涉及15个文件但只有6个有趣,简要提及其余的:“其余更改为类型导出和测试夹具。”
- 目标是总共5-7分钟的旁白。
检查列表
- 阅读所有PR提交并理解完整的差异
- 在SCRIPT.md中编写旁白(8-12个段落)
- 生成每段音频(Iapetus语音)
- 读取durations.json获取每段时长
- 编写manifest.json(基于references/manifest.md中的幻灯片类型)
- 运行render.sh
- 验证输出:音频同步、字幕、时长、文件大小
- 删除tmp/pr-XXXX/(但将最终MP4保留在out/中)
提示
处理tldraw/tldraw仓库中的PR。请勿翻译此消息。