---
name: frame-grab
description: Extract stills from any video — at intervals, evenly-spaced, at scene changes, or just I-frames. Optional sprite-sheet output (one big PNG with N frames in a grid). Pure ffmpeg, no ML deps. Distinct from gif-board (folder → contact sheet) — frame-grab is one video → many frames. Use when the user asks for thumbnails, screenshots from a video, every-Nth-second frames, scene-change detection, sprite sheet, key-frame extraction, or stills for OCR / clip-search / cover-art workflows.
---


# frame-grab

One video → many stills. Four modes.

## Every N seconds

```bash
python3 ~/.claude/skills/frame-grab/scripts/grab.py --input movie.mp4 --mode interval --every 2
# → movie_frames/  (frame_00-00-00.jpg, frame_00-00-02.jpg, ...)
```

## Evenly-spaced N frames

```bash
python3 ~/.claude/skills/frame-grab/scripts/grab.py --input movie.mp4 --mode count --count 12
# pulls 12 frames evenly across the entire video — great for video thumbnails
```

## Scene changes

```bash
python3 ~/.claude/skills/frame-grab/scripts/grab.py --input movie.mp4 --mode scenes --threshold 0.4
# uses ffmpeg's `select='gt(scene,0.4)'` — one frame per detected cut
```

## Keyframes (I-frames only)

```bash
python3 ~/.claude/skills/frame-grab/scripts/grab.py --input movie.mp4 --mode keyframes
# only I-frames — fast, every encoded keyframe
```

## Sprite sheet

```bash
python3 ~/.claude/skills/frame-grab/scripts/grab.py --input movie.mp4 \
  --mode count --count 25 --sprite --cols 5
# → movie_frames.png — 5x5 grid sprite sheet
```

## Flags

- `--input` — video file
- `--output` — output folder (default `<video>_frames`) or sprite path
- `--mode` — `interval` | `count` | `scenes` | `keyframes`
- `--every` — seconds between frames (interval mode)
- `--count` — total frames (count mode)
- `--threshold` — scene-change threshold 0.0–1.0 (default 0.3, lower = more frames)
- `--width` — resize width in px (default: source width)
- `--quality` — JPEG quality 1–31, lower = higher quality (default 3)
- `--format` — `jpg` (default) or `png`
- `--sprite` — combine into one sprite-sheet image
- `--cols` — sprite columns (default 4)

## Pairs well with

- `clip-search` — extract frames first, then CLIP-search a folder
- `screenshot-text` — extract frames, then OCR each
- `cover-art` — pick a frame and use it as cover-art source
- `palette-rip` — extract frames, then palette-rip the folder