Look at the footage
Show an agent what the footage holds: one frame, a contact sheet across a clip, or the composed timeline - as an image, or as text-only measurements for models without vision.
fablecut_analyze_reference gives you the ears - where the cuts are, how hard each shot hits. fablecut_frame gives you the eyes. It answers with a real image (an MCP image content block), so you can judge a shot instead of inferring it from an energy value.
| call | returns |
|---|---|
{path:"/media/x.mp4", t:3.2} | that exact frame |
{path:"/media/x.mp4", frames:12} | a 4×3 contact sheet across the whole clip |
{path:"/media/x.mp4", frames:12, from:30, to:90} | a contact sheet across part of it |
{time:8.5} (no path) | the composed timeline at 8.5 s, graded, all tracks |
{path} with an absolute path | the file is read in place without copying into media/ |
{path, text:true} | text-only statistics (luma, colors, texture, saturation, motion) for non-vision agents |
Each answer leads with a text line naming the source, the timestamp(s) and (in timeline mode) the clips on screen, so you always know what you are looking at. width sets the pixel width (default 768 for one frame, 320 per contact-sheet cell); text:true returns descriptive statistics instead of an image block, for agents without vision capability - luma levels (min, p1, median, mean, p99, max, all 0–1 like fablecut_scopes), dominant colors, texture, saturation and per-cell motion; where/timeout apply to timeline mode only.
The REST endpoint /api/frame accepts src, t, frames, from, to, w, q (JPEG quality 1–31) and text=1 (statistics mode) as query parameters.
When it pays. Before choosing a clip's in point, sample a few candidate moments - the blueprint tells you a shot spans 2.1 s–4.9 s and reads energy: 88, but only a frame tells you whether that is a car jump or a pan across a landscape. Contact sheets are the cheap survey: one call shows you what a whole 3-minute clip holds, then you grab single frames where it matters. Timeline mode answers "what did I actually build?" - the same picture the user sees and export renders, grades and transitions included.
Needs ffmpeg on PATH for the source modes. Timeline mode runs in the open editor tab, else a headless browser, like fablecut_export.