69 lines
6.4 KiB
Markdown
Raw Permalink Normal View History

# grab
Decode frames of a video file and write them as PNGs (local render, no credits). By default the frames are merged into contact sheets: up to 12 per image, each cell labelled with its timecode (`08s10f`, zero segments dropped) and drawn as large as fits, so a handful of frames arrives as one high-resolution picture instead of a directory to open one by one (separate: true writes a PNG per frame). Grabs the asset's own pixels, unlike capture which renders the composited node. The recommended tool for understanding a video at the frame level; past ~12 frames prefer filmstrip.
| | |
| --- | --- |
| MCP tool | `grab` |
| CLI | `diffusion grab <path> [options]` |
| CLI aliases | `diffusion sample` |
## Input
| Field | Type | CLI | Description |
| --- | --- | --- | --- |
| `path` | `string`, required | `<path>` | absolute file path or URL (works with or without an open project), or a library path like `b-roll/clip.mp4` (needs an open project) |
| `times` | `Time[]` | `-t, --times <time...>` | timestamps to grab — seconds ("1.5"), frames ("45f"), or "MM:SS"; negatives count back from the end, so -1 is one second before the end and -1f one frame before it (default: [0]) |
| `count` | `integer` | `-c, --count <n>` | instead of times, grab this many frames evenly spaced across the clip (or across the start/end window) |
| `auto` | `boolean` | `-a, --auto` | scan the clip at 2fps and keep a frame each time the footage settles into a new visual state (transitions are waited out, so picks stay sharp); returns at most count frames (default cap: 30), static footage like screen recordings returns far fewer; requires WebGPU |
| `start` | `Time` | `-s, --start <time>` | with count or auto, start of the window to sample (default: 0) |
| `end` | `Time` | `-e, --end <time>` | with count or auto, end of the window to sample (default: asset duration) |
| `quality` | `"small" \| "medium" \| "large" \| "fullres"` | `-q, --quality <preset>` | frame resolution as a pixel budget, aspect ratio kept and never enlarged past the source: small (384² pixels, 512x288 for 16:9), medium (768², 1024x576), large (1536², 2048x1152), or fullres (native); default: as large as the sheet cell allows, or small with separate: true |
| `separate` | `boolean` | `-S, --separate` | write one image per position instead of merging them into contact sheets of up to 12 cells, each labelled with its timecode |
| `perSheet` | `integer` | `--per-sheet <n>` | positions per contact sheet, 1-12; fewer means a larger cell each (default: as many as fit) |
| `uncapped` | `boolean` | `--uncapped` | lift the 100-frame safety cap (grabbing many frames is slow and token-heavy) |
| `output` | `string` | `-o, --output <dir>` | absolute directory to write the PNGs into (default: a fresh directory under the system temp dir) |
## Sampling
Three ways to say which frames, mutually exclusive:
- `times`: explicit timestamps in source time. A negative value counts back from the end of the clip, so `-1` is one second before the end and `-1f` one frame before it.
- `count`: that many frames evenly spaced across the clip, or across the `start`/`end` window, at a fixed interval of `window / count`, starting at the window start.
- `auto`: a scan at 2 fps that keeps a frame each time the picture settles into a new visual state, dropping near-duplicates and waiting out transitions so picks stay sharp. Returns at most `count` frames (default cap 30); static footage such as a screen recording returns far fewer. Needs WebGPU.
`start` and `end` only apply with `count` or `auto`. An `end` past the asset's duration is clamped to it; a `start` at or past the end is an error, since the window would be empty. Like [`capture`](./capture.md), but this grabs the asset's own pixels; `capture` renders the composited node. Renders locally; no credits. Past ~12 frames, [`filmstrip`](./filmstrip.md) is the cheaper way to scan a clip.
`quality` is a pixel budget rather than a box: a frame is scaled down, aspect ratio kept, until it holds no more pixels than the preset's square (`small` is 384², so a 16:9 frame becomes 512x288; `medium` 768² gives 1024x576; `large` 1536² gives 2048x1152), and never enlarged, so `large` on 1080p footage is the native 1920x1080.
With `separate`, frames keep their own resolution and alpha, and each file is named after its timecode (e.g. `01s12f.png`). Without an `output` directory the images land in a fresh `dapi-grab-*` directory under the system temp directory, so runs never overwrite each other. Writing into the same directory twice overwrites images whose name matches; with `separate`, requested times that land on the same frame share one file.
## Timecodes
Cell labels, the `timecode` field, and the filenames all use the same stamp, which drops its zero segments: `08s10f` is 8 seconds and 10 frames, `01m05s` is 65 seconds, and the first frame is `0f`. Each segment carries its unit, so nothing is ambiguous once the empty ones are gone. (The rulers [`filmstrip`](./filmstrip.md) and [`waveform`](./waveform.md) draw stay on fixed-width `HH:MM:SS:FF`, so their ticks line up.)
## Layout
A sheet never exceeds 2576x1456, the largest image a vision model reads at full detail. Within that budget the grid is the one that draws each frame largest, frames are never enlarged past their source resolution, and the last row may be partially filled. Sheets are named after the span they cover, e.g. `0f-08s10f.png`. For 16:9 footage the cell sizes are:
| Frames | Grid | Per-frame |
|---|---|---|
| 1 | 1x1 | 2568x1444 |
| 2-4 | 2x1, 2x2 | 1280x720 |
| 5-9 | 3x2, 3x3 | 850x478 |
| 10-12 | 4x3 | 636x358 |
## Output
One JSON object with one entry per written image: a contact sheet by default, a frame with `separate`.
```ts
{ images: Array<{ timecode: string; path: string }> } // e.g. { "images": [{ "timecode": "0f-08s10f", "path": "…/0f-08s10f.png" }] }
```
A sheet's timecode is the span it covers; a frame's is its own. Sheets come in time order, and their cells in the order the times were requested in. Over MCP, up to four images of at most a megabyte each also arrive inline.
## Errors
Fails when the path can't be resolved, the asset is not a video, any of `times` is past the asset's duration, the window is empty (`start` at or past the asset's end) or `start` is not before `end`, `times` is combined with `count` or `auto`, `start`/`end` are given without `count` or `auto`, `perSheet` is outside 1 to 12 or combined with `separate`, more than 100 frames are requested without `uncapped`, or a PNG can't be written.