Builds a contact sheet from a slice of a video clip: 16 evenly spaced frames laid out in a 4x4 grid, each annotated with its hh:mm:ss timestamp.
Prerequisite: ffmpeg with drawtext
This skill burns timestamps onto frames with ffmpeg's drawtext filter. ButterCut resolves ffmpeg from the repo's dependencies/ directory first, then PATH, and raises a clear error when it's in neither place. If a run fails with that missing-ffmpeg error, or with No such filter: 'drawtext' (some PATH builds, notably the stock Homebrew formula, omit drawtext), run the setup skill to install a suitable ffmpeg, then retry the contact sheet.
Run
When the clip belongs to a library, always pass --library so the output lands in the standard place:
# Whole clip
ruby lib/buttercut/contact_sheet.rb <video-path> --library libraries/<lib>
# From <start> to the end of the clip
ruby lib/buttercut/contact_sheet.rb <video-path> <start> --library libraries/<lib>
ruby lib/buttercut/contact_sheet.rb --library libraries/
`<start>` and `<end>` accept seconds (e.g. `12.5`) or `HH:MM:SS` / `MM:SS`.
Options: `--library DIR`, `--output PATH` (exact path; overrides `--library`).
Frame count is chosen automatically: 16 frames in a 4x4 grid for clips longer than 10 seconds, 4 frames in a 2x2 grid for clips of 10 seconds or less (avoids duplicates).
Portrait clips (iPhone, etc.) are auto-rotated using the source's container rotation metadata so timestamps land right-side-up. Variable-frame-rate sources (screen recordings, some action cams) are detected and routed through the slower seek-and-grab path automatically.
## Output location
- With `--library DIR`: saved to `<library>/contact_sheets/<clipname>_<descriptor>.jpg`.
- `<descriptor>` is `full` when covering the whole clip, otherwise `HH-MM-SS_to_HH-MM-SS` (dashes instead of colons).
- Examples: `contact_sheets/DJI_20251126164651_0278_D_full.jpg`, `contact_sheets/DJI_20251126164651_0278_D_00-00-30_to_00-01-00.jpg`.
- The `contact_sheets/` directory is created automatically if missing.
- Without `--library` (and no `--output`): saved next to the source video with the same `_<descriptor>` suffix. Fine for quick one-off testing, but library work should always pass `--library`.
## After running
Share the output path as a clickable link so the user can open it directly.