overcast-frame-grid

name	overcast-frame-grid
description	Triage a whole clip in one VLM call — tile sampled frames into a labeled contact sheet, ask which cells show the target, then zoom in.

overcast-frame-grid

Use this skill to find roughly WHERE in a clip something appears with a single vision call, before spending per-frame calls. It's the "grid trick" from temporal-search research (frames tiled into one image; Set-of-Mark numbering over time). Pairs with overcast-pinpoint for the frame-precise follow-up. Use the broad overcast skill and overcast/reference/verbs.md for exact flags.

Workflow

overcast doctor --json
overcast case init --json
overcast grid ./clip.mp4 --count 16 --json     # -> media.grid: payload.montage + payload.cells + payload.cols
overcast see <montage-path> --prompt "Which numbered cells show <X>? Reply with cell numbers and why." --json

• If the grid record's payload.labeled is false (this ffmpeg build has no drawtext), tell see it's a <cols>-column grid numbered left-to-right, top-to-bottom (cols is in the record), so it can reference cells by position.
• Only the first count cells hold frames; the last row may be blank padding (those payload.cells[].at are null), so have see pick from 1..count and ignore blank tiles.
• Always map the chosen cell number back through payload.cells[n].at to get the real timestamp — never use a time the model typed out.

Zoom in on the winning region (narrow the window, or hand the timestamp to overcast-pinpoint):

overcast grid ./clip.mp4 --start <a> --end <b> --count 16 --json   # finer sheet around the hit
overcast see frame://<watch-record>@<t> --prompt "Is <X> here? yes/no + detail" --json
overcast note "<X> first visible" --ref <record> --at <t1-t2> --json
overcast brief --export ./grid-triage.md --json

Use --at "s1,s2,s3" instead of --count when you already have candidate timestamps to compare side by side; --start/--end to focus a window; --cols / --width to shape the sheet. Add --view (--no-open in a headless run) to also write a clickable HTML board — numbered, timestamped cells that seek the source clip — for eyeballing the sheet by hand; the montage PNG stays the input you hand to see.

Output

The cell(s) that matched, the timestamp each maps to (via payload.cells), and the grid record.id. Treat grid hits as coarse (one frame per cell) — confirm the exact moment by see-ing that frame before citing it as evidence.

Caveats

One contact sheet samples sparsely, so a brief event between cells can be missed — raise --count or re-grid a tighter --start/--end. The montage is a still, so motion/audio cues are gone; use watch/listen when those matter. Video can be local or a URL, but the see frame:// zoom-in step needs it local.