maestro: Skill for Claude Code

Video Frame Extractor

Extract frames from video recordings using ffmpeg so the agent can visually inspect what happened. UI glitches, layout shifts, and animation bugs happen in milliseconds — too fast for a human to screenshot but trivial for an LLM to spot once the frames are laid out.

How It Works

1. User provides a video path (and optionally a second video for comparison)
2. You run ffmpeg to extract frames into a temp directory
3. Frames are named with timestamps so the agent can navigate the timeline
4. The agent reads the frames and identifies what's going on

You are a frame extraction tool. Extract frames, organize them, and let the main agent do the analysis. Do not interpret what you see in the frames — just deliver them.

Quick Reference

Basic extraction (whole video)

# Create output directory
OUTPUT_DIR=$(mktemp -d)/frames
mkdir -p "$OUTPUT_DIR"

# Extract at 5 fps (good balance between coverage and file count)
ffmpeg -i "<video_path>" -vf "fps=5" -frame_pts 1 "$OUTPUT_DIR/frame_%04d.png" -y 2>&1

# Rename frames with actual timestamps
# fps=5 means each frame is 0.2s apart
for f in "$OUTPUT_DIR"/frame_*.png; do
  num=$(echo "$f" | grep -o '[0-9]\{4\}' | tail -1)
  # Frame numbers start at 1, convert to seconds
  sec=$(echo "scale=2; ($num - 1) * 0.2" | bc)
  mv "$f" "$OUTPUT_DIR/sec_${sec}s.png"
done

echo "Frames extracted to: $OUTPUT_DIR"

Custom time range

# Extract frames between specific timestamps
# -ss = start time, -to = end time
ffmpeg -i "<video_path>" -ss <start> -to <end> -vf "fps=5" -frame_pts 1 "$OUTPUT_DIR/frame_%04d.png" -y 2>&1

Higher FPS for fast animations

# Use 10-15 fps when analyzing rapid transitions or animations
ffmpeg -i "<video_path>" -vf "fps=15" -frame_pts 1 "$OUTPUT_DIR/frame_%04d.png" -y 2>&1

Two-video side-by-side comparison

# Extract frames from both videos
OUTPUT_A=$(mktemp -d)/video_a
OUTPUT_B=$(mktemp -d)/video_b
mkdir -p "$OUTPUT_A" "$OUTPUT_B"

ffmpeg -i "<video_a_path>" -vf "fps=5" -frame_pts 1 "$OUTPUT_A/frame_%04d.png" -y 2>&1
ffmpeg -i "<video_b_path>" -vf "fps=5" -frame_pts 1 "$OUTPUT_B/frame_%04d.png" -y 2>&1

# Create side-by-side composites
COMPARE_DIR=$(mktemp -d)/comparison
mkdir -p "$COMPARE_DIR"

# Get the lesser frame count to avoid mismatches
COUNT_A=$(ls "$OUTPUT_A"/frame_*.png 2>/dev/null | wc -l | tr -d ' ')
COUNT_B=$(ls "$OUTPUT_B"/frame_*.png 2>/dev/null | wc -l | tr -d ' ')
COUNT=$(( COUNT_A < COUNT_B ? COUNT_A : COUNT_B ))

for i in $(seq -f "%04g" 1 $COUNT); do
  sec=$(echo "scale=2; ($i - 1) * 0.2" | bc)
  ffmpeg -i "$OUTPUT_A/frame_${i}.png" -i "$OUTPUT_B/frame_${i}.png" \
    -filter_complex "[0]pad=iw+10:ih[left];[left][1]hstack" \
    "$COMPARE_DIR/compare_sec_${sec}s.png" -y 2>/dev/null
done

echo "Comparison frames: $COMPARE_DIR"
echo "Video A frames: $OUTPUT_A"
echo "Video B frames: $OUTPUT_B"