---
name: barefootford/contact-sheet
source: https://app.decimal.ai/s/barefootford-contact-sheet@1/SKILL.md
source_sha256: 0b68b9e9139f
---

# Skill: Contact Sheet

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:

```bash
# 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>

# Explicit range
ruby lib/buttercut/contact_sheet.rb <video-path> <start> <end> --library libraries/<lib>
```

`<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.