/daniel-video-annotate
输入:一个视频文件,以及说明每个步骤原因的内容(工单、合并请求或用户消息)。输出(与输入同级):<name>-trimmed.mp4 和 <name>-explained.mp4。输入文件不会被修改。
解说视频在播放录制内容时,每次暂停会保持一帧画面持续设定的保持时间,将屏幕上某个框选控件周围的区域变暗,并在录制画面的下方或上方黑色条带中显示一句话字幕。该条带会增加视频高度,因此不会遮挡录制内容。
annotate.py 位于此文件同级目录。在以下命令中,A 代表 python3 "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/daniel-video-annotate/annotate.py"。它仅需要 ffmpeg、ffprobe 和 Python 标准库。<work> 是一个临时工作文件夹:如果有会话暂存区则使用它,否则使用 ${TMPDIR:-/tmp}/video-annotate/<name>/。
如果视频位于开发虚拟机中,请先使用 dvm get <remote path> <local dir> 将其复制到本地。
0. 选择阅读速度
保持时间是指每条字幕在屏幕上保持可读状态的时长。每次暂停的保持时间为 1.5 秒加上以阅读速度阅读其字幕所需时间,且至少 2.5 秒。若用户提供了阅读速度(以字/分钟为单位),则使用该速度;否则默认 350 字/分钟。无需询问用户。如果用户给出了固定的保持时间(秒),则每次暂停都使用该时长。
完成标志:已确定阅读速度或固定保持时间。
1. 剪除等待段
A trim <video> <name>-trimmed.mp4
该命令会找出所有画面静止 1.5 秒或更长的片段,保留每个片段的第一秒,然后剪掉其余部分。它会输出剪除的片段数量以及剪裁前后的时长。如果用户希望保留等待段,则跳过此步骤,并直接将原始视频作为 <trimmed> 使用。
后续步骤中的所有时间点均指 <trimmed> 中的时间。再次剪裁会使所有时间点偏移,因此任何新的剪裁后都需要重新执行步骤 2 至 6。
2. 了解录制内容
A sheets <trimmed> <work>/sheets
它每秒生成一张包含六帧画面的联系图,每帧上标注了精确时间。读取每一张联系图。同时阅读工单或其他来源,以获取每个步骤背后的原因。
完成标志:能够按顺序说明操作者在屏幕上做了什么、每个操作设置了哪个值、以及哪个结果证明了录制的目的。
3. 选择暂停点
每个关键选择(选择的值、按下的按钮、有目的地打开的页面)暂停一次,每个能证明目的的结果暂停一次。跳过不包含决策的导航操作。
对于每个暂停点,找到对应帧和控件框:
A frames <trimmed> <work>/frames 23.0 23.2 23.4 23.6
它会在每个时间点生成一张全尺寸 PNG 图像,文件名包含精确时间,并带有一个每 100 像素的红色网格,像素坐标标注在图像顶部和左侧边缘。
- 选择一个稳定的帧。录制中会有半渲染的帧,例如点击后某面板空白几帧。按 0.2 秒步进,直到控件及其周围区域完全绘制完成。
- 对于列表中的选择,优先选择列表已打开且光标悬停在选项上的帧。如果该帧半渲染,则使用紧随其后的、字段显示新值的帧。
- 从网格标签中读取控件框坐标,格式为
[x, y, width, height],单位为源像素。Read 工具会缩小大尺寸图像,因此在显示的图像上测量的位置是错误的;但标签始终正确。 - 控件框应仅包围字幕所描述的单个控件,并留出几个像素的边距。某个暂停点可以省略
box,此时该区域不会变暗。
完成标志:每个暂停点都有一个你已检查过帧的时间点,并且该控件框是从该帧上读取的。
4. 编写字幕
每个暂停点一句话。说明我们做了什么及原因,或者屏幕上现在显示了什么及原因。命名具体的内容:行、字段、旧值和新值。
原因来自来源。当来源未提供某步骤的原因时,仅描述可见内容,并在报告中将该字幕标记为推断。将 writing-tics 技能应用于字幕。每条字幕保持在约 180 字符以内,因为字幕条的高度取决于最长字幕。
5. 渲染
编写 <work>/spec.json,按时间顺序排列的列表:
[
{"at": 12.0, "box": [399, 569, 180, 29], "caption": "将表格中 Item 1 的尺寸从 M 改为 L,从而将 L 保存到服务器。"},
{"at": 23.6, "box": [659, 500, 192, 24], "caption": "..."}
]
at 是 <trimmed> 中的秒数。然后为每个暂停点设置 hold:
A holds <work>/spec.json [--wpm <speed>]
它会将每个暂停点的保持时间写入 spec 文件,并输出每个暂停点的保持时间和字数。如果使用固定保持时间,则自行设置每个暂停点的 hold。没有 hold 的暂停点默认保持 6 秒。
A annotate <trimmed> <work>/spec.json <name>-explained.mp4 [--position top|bottom] [--clearance <lines>]
字幕条放置在用户指定的位置。未指定时默认放在底部。
--position bottom为默认位置。视频播放器通常在其底部边缘绘制控件,因此字幕条下方预留空白区域:--clearance行数,默认 3 行,可避开小型嵌入式播放器的控件。--position top将字幕条放在录制画面之上,该区域没有播放器控件,因此无需设置 clearance。
框选控件的坐标在两种位置下均基于 <trimmed> 的坐标。
6. 检查每个暂停点
A check <name>-explained.mp4 <work>/spec.json <work>/check
它会从每个暂停点的中间位置提取一帧图像。读取每一帧。框必须准确位于控件上,字幕必须完整且在右侧不被截断,帧必须是之前选择的稳定帧。修复 spec 后重新渲染,直到每个暂停点都通过检查。
7. 报告
给出解说视频的路径、大小和时长,然后按顺序列出每条字幕及其框选的控件。说明哪些字幕是推断的。声明已对每个暂停点检查了一帧,并未观看完整播放。
限制
- 输出视频没有音频。如果输入视频包含音轨,请告知用户。
- 帧率为输入视频的平均帧率,四舍五入后限制在 5 到 30 帧/秒之间。
trim仅剪裁完全静止的画面。旋转的加载动画、进度条、闪烁的光标或时钟都会保持画面变化,因此这些等待段会被保留。一个被微小变化打断的等待段会被拆分为多个一秒钟的片段。trim仅剪裁静止片段内部的帧,并保留每次变化的第一帧。小于--noise容差(默认 0.003)的变化(例如单个小字符)会被视为静止状态而可能被剪裁。步骤 2 是检查手段:每个操作必须出现在联系图中。如果缺少某个操作,则将--noise降低至 0.001。
错误处理
| 现象 | 原因 | 修复方法 |
|---|---|---|
this ffmpeg build has no drawtext filter | ffmpeg 编译时未包含 libfreetype | 安装完整版本,例如 brew install ffmpeg |
no font file found | 已知的 macOS 或 Linux 字体路径均不存在 | 向 sheets、frames 和 annotate 传递 --font /path/to/font.ttf |
Unrecognized option 'fps_mode' | ffmpeg 版本低于 5.1 | 升级 ffmpeg |
no still stretches found, nothing written | 画面从未静止 1.5 秒 | 使用原始视频作为 <trimmed>,或降低 --min-freeze |
| 剪裁后的视频仍感觉缓慢 | 保留了带动画的等待段,或每段静止保留的一秒钟累加过多 | 将 --keep 降低至 0.5 |
| 剪裁后的视频跳跃太快难以跟上 | 每屏幕保留一秒对于此录制太短 | 将 --keep 提高至 2,--min-freeze 提高至 3 |
pause N at Ts is past the end of the video | 时间点来自原始视频而非 <trimmed> | 从 <trimmed> 的 sheets 和 frames 中重新读取时间点 |
pause N box ... is outside the frame,或框在 check 中未对准控件 | 框是在缩小的图像上测量的 | 从 frames PNG 的网格标签读取坐标 |
| 字幕在右侧被截断 | 字体比脚本假设的更宽 | 向 annotate 传递 --wrap 80 或更小的数字 |
| 播放器控件遮盖了字幕 | 字幕下方空间不足 | 将 --clearance 提高至 5,或使用 --position top |
pause N would sit at ..., past the end | 向 check 提供了剪裁后的视频 | 向 check 提供解说视频 |
其他 ffmpeg failed | 未知 | 运行 A selftest。它会剪裁并标注一个生成的片段,如果通过则表明 ffmpeg 工作正常,问题出在输入视频或 spec |
dvm get --help 因 scp 错误失败 | dvm get 将所有参数传递给 scp | 运行 dvm help |
macOS 没有 timeout 命令。一分钟 720p 视频的渲染时间仅为几秒,因此直接运行命令即可。