video-timeline

name	video-timeline
description	Generate a folder of low-resolution frame snapshots at evenly spaced timestamps so Claude (or you) can "see" a video without ingesting the full file. Use when the user says "give me a visual timeline", "let me see this video", "show me frames from this", "white balance check", "what does this video look like", or any request where Claude needs visual context about a video. Output is a folder of small JPEGs plus a timeline.md index.
disable-model-invocation	false
allowed-tools	Bash(ffmpeg *), Bash(ffprobe *), Bash(test *), Bash(mkdir *), Bash(ls *), Bash(basename *), Bash(dirname *), Bash(awk *), Bash(printf *), Read, Write

Video Timeline

Drop a folder of evenly-spaced, low-res frames from a video so they can be opened (by Claude or by the user) without processing the whole file. Cheap visual context for white-balance checks, scene scrubbing, editorial review.

Procedure

1. Inputs

Ask if not provided:

• Video — path to a video file (required).
• Frame count — default 12.
• Width — default 480 px.
• Output dir — default:
  • if invoked inside an index project, <project>/video_timeline/<video-basename>/
  • else, sibling to the source: <dir>/video_timeline/<basename>/

2. Get duration

DURATION=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$VIDEO")

Compute even-spaced timestamps. To keep the first and last frames meaningful (not the very edge), pad 5% in from each end:

N=12
PAD=$(awk -v d="$DURATION" 'BEGIN { printf "%.3f", d*0.05 }')
USABLE=$(awk -v d="$DURATION" -v p="$PAD" 'BEGIN { printf "%.3f", d - 2*p }')
STEP=$(awk -v u="$USABLE" -v n="$N" 'BEGIN { printf "%.3f", u/(n-1) }')

3. Loop seek-and-grab

-ss before -i is fast (keyframe seek) but can land on the nearest keyframe; -ss after -i is accurate but slower. Default to fast seek, since we only want a representative frame, not a precise one.

mkdir -p "$OUT_DIR"
for ((i=0; i<N; i++)); do
  T=$(awk -v p="$PAD" -v s="$STEP" -v i="$i" 'BEGIN { printf "%.3f", p + i*s }')
  HMS=$(awk -v t="$T" 'BEGIN { h=int(t/3600); m=int((t%3600)/60); s=t-h*3600-m*60; printf "%02d-%02d-%06.3f", h, m, s }')
  IDX=$(printf "%04d" $((i+1)))
  ffmpeg -hide_banner -loglevel error -y -ss "$T" -i "$VIDEO" \
    -frames:v 1 -vf "scale=$WIDTH:-1" -q:v 5 \
    "$OUT_DIR/frame_${IDX}_${HMS}.jpg"
done

4. Write timeline.md

A small index Claude can read in a single tool call:

# Video Timeline: <basename>

- Source: `<absolute path>`
- Duration: <H:MM:SS>
- Frames: 12 @ 480px wide

| # | Timestamp | File |
|---|-----------|------|
| 1 | 00:00:01.234 | frame_0001_00-00-01.234.jpg |
| 2 | 00:00:11.567 | frame_0002_00-00-11.567.jpg |
| ... |

5. Report + offer follow-ups

Print the output dir path and frame count. Offer:

• Open the folder in a file manager.
• A vision-pass critique — Claude reads the frames and comments on white balance, exposure, framing consistency.
• Pair with wb-preview if a white-balance issue is spotted.