Communitygithub.com

daniel-video-annotate

将屏幕录制转化为带有解释的解说版本:剪掉静止等待段,在每个关键操作处暂停,框出控件并添加说明文字,解释操作内容及原因。当用户调用 /daniel-video-annotate 或要求标注、解释视频时使用。

daniel-video-annotate 是什么?

该技能(/daniel-video-annotate)专为 AI 编码代理(如 Claude Code)设计,用于将屏幕录制转化为带标注的解说视频。它通过三步流程实现:首先自动剪辑掉长时间静止片段(保留每段的第一秒),然后让用户(或 AI)在关键操作点(如选择值、按下按钮、打开页面)和关键结果处设置暂停点,并为每个暂停点添加方框标注控件和一句话解释性字幕。技能支持 ffmpeg 和 Python 标准库,无需额外依赖。输出为 `<name>-trimmed.mp4`(剪辑版)和 `<name>-explained.mp4`(解说版)。字幕放置在录制画面下方的黑色条带中,不遮挡原始录制内容,且用户可调整条带位置(顶部或底部)。AI 需根据用户提供的工单、合并请求或消息来源获取每个步骤的原因,并在无法确定时标记为推断。技能还提供内置检查功能,通过逐帧验证确保方框正确对齐控件、字幕完整显示。

兼容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/dancodes/skills-agents/tree/HEAD/skills/daniel-video-annotate

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

/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 filterffmpeg 编译时未包含 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 视频的渲染时间仅为几秒,因此直接运行命令即可。

相关技能