浏览器演示视频
你将视频作为代码编写脚本,因此录制是可重复的:只需更改语音或一个固定标签,即可自动重新录制,无需手动重新录制。整个流程如下:
script.cjs ──tts.cjs──▶ audio/*.wav + durations.json
│ │
└──────────record.cjs◀───────────┘ Chrome + overlay, CDP screencast → takes/<target>/frames + timeline.json
│
post.py ──▶ MP4 (cuts removed, narration + click sounds, −16 LUFS, chapters)
│
review.py ──▶ contact sheets + loudness/chapter check → you inspect, then deliver
引擎:此技能的 scripts/ 目录。每个视频项目存储在:~/Movies/Demos/<slug>/(切勿使用 /tmp,因为它会被清空),包含 video.config.cjs、script.cjs、audio/ 和 takes/。可运行示例:examples/hello-orders/(一个嵌入宿主 shell 中的小型页面;用于检查你的设置)。在首次录制前,请阅读 references/lessons.md。
要求:Chrome、Node(带 Playwright,record.cjs 会自动找到它,也可以在配置中设置 playwright)、ffmpeg/ffprobe、Python 3,以及用于 Polly 的 AWS CLI。
1. 确定视频(在任何代码编写之前)
确认并提供一个用户可以反馈的大纲:
- 受众。 内部视频涵盖角色、权限、控制项和已知限制,并以“注意事项”章节结尾。面向领导和客户的视频仅涵盖结果和成功路径。
- 端到端流程, 按章节划分,以及目标时长。约 10–12 分钟适合内部深度探讨。
- 录制位置(决定)。 操作过程会点击真实按钮并写入真实状态,因此绝不能在真实、共享的数据上运行。建议使用副本、测试工作区或包含真实数据的开发环境,以及在这些录制之间重置环境的方法。如果创建副本会写入生产数据,则需要明确同意。
- 身份(决定)。 如果流程需要两个人(创建者和审核者),要么让一位真实队友登录第二个窗口,要么由一个人扮演两个角色,并在屏幕上说明。切勿创建用户或处理密码;如果需要测试账号,由用户创建。
- 语音(决定)。 默认使用 Polly 生成式“Amy”(en-GB),它在真实观众中表现良好。在生成所有内容之前,为每个候选语音提供一个约 30 秒的样本:
aws polly synthesize-speech --profile <dev profile> --region eu-west-2 --engine generative --voice-id Amy --output-format mp3 --text "<包含产品术语的段落>" sample-Amy.mp3使用非生产 AWS 账户。macOSsay可以离线工作,但听起来很合成。用户自己的声音是最自然的选择。 - 取景。 仅产品本身在画面中:没有主机侧面板、列表或横幅。在配置的
setup钩子中进行设置。
2. 设置项目
P=~/Movies/Demos/<slug>; K=~/.claude/skills/browser-demo-video
mkdir -p "$P" && cp $K/templates/video.config.cjs $K/templates/script.cjs "$P"/
在 video.config.cjs 中,填写:一次性环境的 url,如果产品运行在 iframe 中则填写 frame、ready、setup(取景)、theme(产品强调色和页脚)、voice,以及 helpers.waitLoaded(产品的加载完成信号)。
在编写步骤之前先映射 UI。打开它,列出稳定的选择器(id、角色、data-*、可见文本),并注意缓慢的加载。优先使用基于显示文本构建的选择器(tr:has-text("-1,250.00") [data-resolve]),而不是生成的键。
3. 编写场景脚本
每个步骤具有 { id, chapter?, pre?, say?, act?, gap? }。h API 的文档位于 templates/script.cjs 的顶部。
- 旁白驱动计时。
act在片段播放时运行,h.at(0.6)将第二个操作与文字对齐。每个say保持为一到两个口头句子。 - 按口语习惯书写数字(例如“百分之九十七”、“九月十四日”)。
- 如果存在,使用真实用户的真实决策,以便屏幕上的数字与团队所知一致。
- 在每个章节前放置章节卡片(
h.card), 并添加带有 3–6 个单词标签的环。仅在需要说明要点时才使用note(),例如安全属性、注意事项或“在实际使用中……”。 - 将每个缓慢的加载包裹在
h.cut(() => h.waitLoaded(), '加载中…')中。 后期制作中会删除该跨度。 - 在屏幕和旁白中说明每一个简化操作。 例如,一个人扮演两个角色:显示控制项阻止了它,显示设置被更改“仅用于本次录制”,然后解释实际使用中会发生什么。
- 指向下载内容;不要点击它们(参见 lessons)。
4. 生成配音
node $K/scripts/tts.cjs "$P"。仅重新生成更改的行。Claude 无法收听结果,因此请指出风险词汇(首字母缩写、名称)并请用户检查。对于 macOS say,将首字母缩写拼写为字母(“S A P”)。
5. 试运行,然后登录,然后录制
- 试运行。 如果存在本地构建,则将
TARGET=preview指向previewUrl。否则在一次性环境中运行短片段:ONLY='^(c1|load0|where1)$' node $K/scripts/record.cjs "$P" record。使用 Read 工具检查几帧(takes/prod/frames/*.jpg,出错时查看failure.png),并使用 ffprobe 检查帧是否为 1920×1080。之后重置环境。 - 登录。 使用
run_in_background运行node $K/scripts/record.cjs "$P" login。用户在打开的窗口中登录,然后关闭它。如果他们说完成了但窗口仍然打开,则运行pkill -INT -f "record.cjs.* login"。 - 完整录制。 重置环境,然后使用
run_in_background运行node $K/scripts/record.cjs "$P" record。在开始之前,告知用户录制时长约为旁白长度加上三分之一,并且会打开一个可见的 Chrome 窗口,他们切勿点击。等待完成通知;不要通过睡眠轮询。检查日志中每个步骤是否为ok,并且没有FAILED或CRASHED行。
6. 组装和审查
python3 $K/scripts/post.py "$P/takes/prod" "$P/takes/prod/walkthrough.mp4" # run_in_background;对于 10 分钟的视频约需 10 分钟
python3 $K/scripts/review.py "$P/takes/prod" "$P/takes/prod/walkthrough.mp4" "$P/review" # 可选:step_id:0.8 采样
阅读每个 review/s*.jpg 版面。查找被裁剪或重叠的标签、位于错误元素上的环、未被切除的加载状态以及残留的覆盖层。响度应约为 -16 LUFS,章节数量应与脚本匹配。在脚本中修复问题,重置环境,然后重新录制。重新录制成本低廉。
7. 交付和清理
- 交付。 将视频复制到
$P/<slug>.mp4并用open打开。如果存在先前版本,则保留重命名的副本(例如old-<voice>-<slug>.mp4),而不是覆盖。 - 报告。 提供时长、分辨率、章节、语音、录制位置、展示的每个简化操作、你无法验证的内容(音频)以及遗留的任何视觉瑕疵。
- 清理前征求意见。 在移除一次性副本或环境之前,以及在删除
takes/(帧占用数 GB)之前,征得用户的同意。保留script.cjs、配置和audio/,以便将来可以重新录制视频。 - 记录。 如果该工作属于某个工单或笔记文件,请在其中记录视频的位置,并注明副本删除处于待处理状态。仅提交该文件。