pr-explainer-film
一部默认静音、时长约30秒、分为五个段落的影片。其结构是关键:观众先是感到代码差异难以阅读,然后收到用通俗语言给出的答案,接着看到证明,最后知道要输入什么命令。
| 时间 | 段落 | 目的 |
|---|---|---|
| 0-2秒 | 钩子 | 点明变更的规模("修改了15个文件。") |
| 2-8秒 | 差异模糊 | 真实的代码块快速滚过;计数器跳动增加 |
| 8-13秒 | 通俗解释 | 一句话标题加上三个简短要点 |
| 13-23秒 | 四个能力点 | 每个能力点都与其背后的真实代码行并列展示 |
| 23-30秒 | 结尾 | 逐个字符打出安装命令,然后显示URL |
输入
在开始制作前收集这些信息。只询问缺失的部分。
- 变更来源:一个GitHub PR或发布(
gh pr diff,gh pr view --json title,body,files),或者本地工作树(git diff加上未跟踪的文件)。只读操作;绝不修改仓库。 - 目标受众:那些不会阅读代码差异的人(客户、团队成员、关注者)。这决定了总结和能力点中的词汇选择。
- 行动号召(CTA):确切的安装命令和/或URL。逐字使用。如果产品只有一个权威命令,则只显示该命令,不显示任何其他工具的名称。
- 品牌:配色方案、Logo(你自己的文件)、字体。模板中的默认值为中性深色风格。
工作流程
- 阅读变更。 获取包含添加/删除计数的文件列表以及真实的代码块。用一个非工程师能理解的句子描述这个变更;如果做不到,说明你尚未理解这个变更。
- 选择内容(参见
references/content-rules.md):钩子数字、用于差异模糊效果的5-8个代码块、3个总结要点、恰好4个能力点、CTA。 - 创建项目框架。
npx --yes hyperframes init <dir> --non-interactive --example=blank,然后将template/index.html和template/film.config.js复制覆盖到生成的文件上。如果有你自己的Logo,放在assets/logo.png。 - 填充
film.config.js。 所有措辞、代码片段和数字都放在这里。仅在需要修改:root中的品牌变量、时间或布局时才编辑index.html。 - 验证:
npx --yes hyperframes lint然后npx --yes hyperframes check。修复所有错误。已知可接受的警告:nested_structure_needs_subcomposition(影片有意采用单个文件以便于重新定制品牌)。 - 查看效果。
npx --yes hyperframes snapshot --at 1,4,6,8.3,11,14,17,19.5,22,26,29然后打开snapshots/contact-sheet-*.jpg。对照下面的列表检查;修复问题并重新生成快照,直到一切正常。 - 渲染。
npx --yes hyperframes render --quality high --workers 2 --output final.mp4。使用ffprobe确认文件为1920x1080分辨率、H.264编码,时长在28-34秒之间。 - 再次查看从MP4中提取的4-6帧图片(
ffmpeg -ss T -i final.mp4 -frames:v 1 f.png),而不仅仅依赖快照。
确保格式有效的规则
- 代码差异必须是真实的。 从实际代码差异中复制真实行。绝不虚构代码或计数。从
git diff --shortstat加上新文件的wc -l计算计数。 - 故意难以阅读。 滚动加速(
power2.in)并带有模糊效果。不要减慢速度让人们能够阅读;"信息太多难以阅读"这个卡片会为此带来回报。 - 先解释,后证明。 总结在任何能力点之前出现。每个能力点标题是一个2-4个字的益处;描述是一句没有行话的句子;代码片段是1-5行真实代码,关键行高亮显示。
- 恰好四个能力点,每个一个想法,每个约2.6秒。宁可删除较弱的点,也不要缩小文字。
- 交替背景。 差异和能力点使用深色背景,总结使用一个浅色场景。背景变化标志着"现在变简单了"。
- 以命令结尾。 逐个字符打出真实命令,然后显示URL。没有第二个CTA。
- 文案整洁。 在代码片段中出现之前,移除命名了竞争对手或无关工具的代码注释。绝不显示除CTA中那个之外的任何CLI。
- 使用自己的资产。 使用你自己的Logo、机器已有的字体,不适用任何库存或第三方媒体。音乐为可选;如果使用,只使用已获商业使用许可的音轨(通过
media-use解决),并确保在没有声音时影片也能完全看懂。 - 确定性。 构图中不使用
Math.random、Date.now或网络调用;从动画进度值驱动打字文本和计数器,以便精确跳转。
帧检查清单(第6步和第8步)
- 钩子数字和措辞匹配真实变更。
- 差异窗口在其框架内剪辑;文件头和绿色/红色行在静止时可读,移动时模糊。
- 计数器停在真实数字上。
- 总结幻灯片在淡出前显示所有三个要点。
- 每个能力点都有标题、句子和代码片段同时可见,无内容被截断。
- 最终帧显示完整的命令和URL,拼写完全正确。
交付物
交付 final.mp4 和项目文件夹(index.html,film.config.js,assets/,meta.json)。报告文件路径、时长以及任何被接受的验证警告。使用相同命令可重新渲染该文件夹;如需为下一个发布重新定制品牌或重用,只需编辑 film.config.js。
详见 references/content-rules.md 了解尺寸和措辞限制。