用途:查看已渲染视频,报告屏幕上与音频中实际出现的内容。默认观察整段视频,涵盖画面、配音、音乐与音效;调用方可缩小范围以降低开销或聚焦特定片段。它是 watch-and-refine 在决定修复什么之前调用的观察原语,其他审阅与剪辑技能也可直接调用。
主要输入:video(必填,本地视频路径);ranges(可选,[开始, 结束] 时间戳列表,支持 SS、MM:SS、HH:MM:SS,默认整段);fps(帧采样率,默认按总时长自动缩放,硬上限 2 fps);max_frames(采样总帧数上限,默认 100);resolution(帧宽像素,默认 512,仅在需要看清屏幕文字时提高到 1024);include_voice、include_music、include_sfx(布尔,默认均 true,分别转写配音与对白、描述音乐起伏与相对配音增益、记录音效与转场音);focus(可选自由文本,指定关注点,如“看片尾卡”“判断鼓点落点上的剪辑时机”)。三个音频开关全为 false 时仅跑画面,并在清单中注明。
工作流:校验视频存在且可读,用 ffprobe 探测时长;解析范围,空则用 [0, 时长],拒绝超出时长的范围;解析 fps,调用方有值则用,否则按已解析范围总时长自动缩放,钳制在 2 fps;按范围时长比例分配 max_frames 预算;用 ffmpeg 按解析后的 fps 与分辨率抽帧到 frames/;任一音频开关为真时,将解析范围内音频提取为工作 WAV,include_voice=true 时跑转写,若没有 Whisper 后端则降级为仅画面并在清单中标记警告;生成 observation.md,逐条以时间戳为键,引用该窗口内可见的帧路径与同窗口的转写行、音乐/音效说明,若设置了 focus 则每条以该关注点的观察开头;写 manifest.json 记录解析后的输入与输出路径。
输出:observation.md(时间戳键控的观察报告,无结论、无好坏评判)、frames/*.jpg(报告中引用的采样帧)、transcript.json(仅在 include_voice=true 且有 Whisper 后端时,带词级时间戳)、manifest.json(解析后的输入与输出路径)。
质量检查:帧数不超过 max_frames;每个范围至少产出一帧,除非该范围短于 1/fps;include_voice=true 时转写覆盖已解析范围;manifest.json 中所有路径均指向真实文件;报告不含建议,只描述观察到的事实。
失败模式:视频缺失或不可读;ranges 某项超出文件时长;include_voice=true 但未配置 Whisper 后端(降级为仅画面并在清单中标记警告);max_frames 预算过紧导致无法为每个范围至少分到一帧(会指出被跳过的范围)。
参考:references/parameters.md 提供完整参数参考、默认值与自动 fps 预算表。