Filmstrip Contact Sheet Creator
← Project Index Filmstrip Contact Sheet Creator

Filmstrip Contact Sheet Creator

An MCP tool (also a plain CLI) that turns an MP4 into a printable contact-sheet / filmstrip PDF -; so a moving clip can be inspected, shared, or handed to a model as one static document.

Exploring Started: May 2026 Updated: May 2026
Repo →

Overview

Feed it a video, get back a single PDF: frames sampled at a chosen rate (or by motion), optionally cropped, laid out in a captioned grid. Each cell is labelled with its frame number and timestamp, so a clip becomes something you can skim on paper or attach to a note. It runs as an MCP server for Claude clients and as a standalone command-line script for everything else.

The reason it exists is mostly about tokens: handing a model the whole video burns context, but a contact sheet lets it see the whole clip at a glance and only ask for full-res detail where it matters. The pre-processing happens locally.

How It Works

OpenCV reads the video; the script picks frames by one of three modes, builds thumbnails, and ReportLab lays them into a PDF with Pillow handling the image work. Two looks are available: a clean white contact sheet, or a black filmstrip with sprocket-hole borders.

Frame selection is the interesting part. Beyond a fixed rate (--fps) or every Nth frame (--every), there's a motion-aware mode that measures how much each frame differs from the last and spends the frame budget where the picture actually changes -; so a clip that sits still then bursts into action doesn't waste half the sheet on near-identical stills. The first page even gets a motion sparkline with ticks marking which frames were sampled.

For cropping, --crop-preview writes an annotated reference frame with a coordinate grid and your box drawn on top, so you can dial in the numbers before committing to a full render.

# motion-aware: ~30 frames, concentrated where the action is
python filmstrip.py clip.mp4 -o clip.pdf --motion --motion-target 30 --cols 5

# preview where a crop box lands BEFORE committing
python filmstrip.py clip.mp4 --crop 120,60,720,480 --crop-preview

The MCP layer wraps the same code in three tools -; probe_video, make_crop_preview, and make_filmstrip -; called in-process (no subprocess overhead) so errors come back as structured dicts the model can react to. It's a stdio server, the standard local-MCP transport.

Current Status

End-to-end working: CLI and MCP both produce PDFs, motion sampling and crop preview behave, and there's a demo PDF and preview image in the repo. Still in the exploring bucket -; it does what it set out to do, but it's early and gets poked at when a real use case shows up.

  • Three selection modes (rate, step, motion) all functional.
  • Two output styles: contact sheet and sprocket-hole filmstrip.
  • Crop preview and interactive crop both supported (interactive needs a GUI build of OpenCV).