job-yang/jobyang-ai-skills/video-reader

Video Reader — 给大模型配的"看视频的眼镜"

干什么 / 边界

大模型能看图、看不了视频。本 skill 的脚本用纯代码帧差算出"哪几秒画面在动"，折叠静止段，把视频翻译成带时间戳的关键帧 + 运动时间线，由你（大模型）看图判断"第几秒发生了什么"。尤其适合排查 App 滑动/交互问题、复现 bug、分析用户操作录屏。

• 不查帧率/卡顿：截图看不出卡，查性能请走日志/Perfetto。
• 不含任何业务逻辑：它不懂"卡顿""面板""跟手"，只供帧和时间线；判断对错是你的活。
• 完整设计原理、安装方式、逐参数参考见 README.zh-CN.md，本文件只保留你触发后必须照做的契约。

四个子命令（按需要选，别只会 scan）

标准打法：长视频先 `grid` 概览 → `scan` 看运动时间线 → `zoom` 下钻可疑段。先读时间线（纯文字）再决定看哪段的帧，最省 token。

调用契约（Agent 必须照做）

脚本路径（绝对路径调用）：<SKILL_DIR>/scripts/video_frames.py

python3 <SKILL_DIR>/scripts/video_frames.py scan <视频路径>
python3 <SKILL_DIR>/scripts/video_frames.py zoom <视频路径> --start 10.0 --end 12.0 --density 8
python3 <SKILL_DIR>/scripts/video_frames.py grid <视频路径>

• stdout = 结构化 JSON（含 timeline、frames[].path、frames[].t、outdir）；stderr = 人读进度。不要解析 stderr 拿数据。
• 退出码：0=成功；2=无法打开/不是视频文件（含 PNG 改名 mp4 这类"能打开但无视频流"）；3=缺 cv2/numpy 且未放行自动安装；4=transcribe 缺 ffmpeg/whisper 或跳过转写。
• 装包闸门：首次缺 cv2/numpy（约 90MB）或缺 whisper（含 torch 约 2GB）时，未设 VIDEO_READER_YES_PIP=1 不会静默安装——脚本会打印体量预告和手动命令并 exit 3/4。需要自动装时带 VIDEO_READER_YES_PIP=1 重跑。
• 假视频防呆：文件能打开但不含可解码视频流（frame_count≤0、宽高为 0）直接 exit 2 报人话错——收到"改后缀"的文件先确认内容真是视频，别把垃圾当分析结论。
• 帧目录治理：帧默认写到随机临时目录，退出时 stderr 会打印"可删除 <dir>"提示（不自动删，防止你 Read 滞后）。已抽帧目录默认保留；--cleanup 在成功退出时才删自动临时目录（--outdir 指定的位置绝不删）。--max-frames（默认 300）限制 scan/zoom 抽帧上限，超限截断并 warn。
• 多 python 错配：脚本启动在 stderr 自报解释器路径/版本/user-site。"装了却 import 不到"99% 是装在别的 python 上，换那个解释器跑即可。
• zoom/grid 性能：scan 的运动分析是"只 seek 一次+顺序跳帧"，长视频也快；zoom/grid 是逐帧随机 seek，长视频上宽区间会慢，请收窄区间、别一次性高密度抽长片。

上传被拦怎么办（注意边界）

很多平台禁视频格式，用户传不上来。两个办法：①把文件改后缀（.txt/.bin）再上传，脚本按内容解码不认后缀；②压成 zip 上传，解压后喂给脚本。

边界：这仅适用于用户自有、有权处置的内容，且目标平台规则允许时；不要用它绕过平台合规管控。拿到文件后先用上面的"假视频防呆"确认是真视频。

看完帧怎么讲

JSON 里 frames[].path 是帧路径、.t 是秒数。Read 帧时把每张图和它的 t 绑定，产出带时间线的客观叙述："3.5s 面板开始上滑，4.5s 停在半屏——与应锚定位置不符"。用户没说预期就只复述事实，不瞎猜对错。