00:00:00 OPEN SOURCE · MIT

You fly. Your agent edits.

Shotpilot is an open-source pipeline from raw drone footage to a published film: motion-smoothness analysis, aesthetic review, selects, pacing, crossfade montage, AI-generated music and YouTube publishing assets - designed to be operated by an AI coding agent, with a plain CLI underneath.

View on GitHub Watch example films
00:00:01 AGENT-FIRST

The primary operator is an AI agent. You direct.

You drop in footage, say what you want and approve decisions. The agent runs the CLI, looks at the generated contact sheets and review plots, applies the codified decision rules - and asks only when a call is genuinely yours to make.

Built for Claude Code: skills like /shot-review, /montage and /autopilot walk the agent through selection, pacing and editing. Every decision lands in a persistent manifest (output/project.json) - the source of truth across sessions.

Approving is visual, not archaeological: ./shot ui opens a local, read-only web view of the agent's work - the selects gallery with stars, tags and decision notes, the cut sequences and every source file, with the clips and the original 4K footage playable right in the browser.

And everything also works by hand: ./shot is a normal command-line tool with --json output, native batching and honest exit codes. No agent required.

claude code - shotpilot

you › review the new footage

agent › Scanning 14 files from the card… ./shot scan input/DJI_0284.MP4 … --json

agent › DJI_0301 is smooth throughout. The lake crossing at 00:42–01:18 is the strongest range - golden light, clean horizon. Cutting a select, ★★★. ./shot select DJI_0301.MP4 42 78 --label lake --stars 3

you › isn’t the ridge shot too slow?

agent › 1.4 %/s on screen - slow. A ×2.5 variant keeps the drift readable without feeling rushed. ./shot speed output/selects/DJI_0294_ridge.mp4 2.5 Kept the dusk shot at ×1 - it stays slow, that’s the mood.

shot ui - read-only web view: selects gallery with thumbnails, stars, tags and decision notes
./shot ui - the agent’s selects with stars, tags and decision notes, ready to review in a local web view
00:00:02 PIPELINE

From SD card to published film, in seven stages.

Each stage leaves auditable artifacts - review images, JSON summaries, a manifest entry - so the human, or the next agent session, can see exactly why every cut happened.

Scan

Per-frame camera transform via OpenCV feature tracking; smoothness scores the acceleration of motion, so a fast uniform flyover reads as smooth and a jerk as a spike.

./shot scan input/*.MP4

Review

Contact sheets and KEPT/CUT review plots for every file - the agent judges composition, light and subject, and recommends ranges.

./shot frames FILE 12 40 88

Select

Chosen ranges are re-encoded into uniform clips with star ratings and decision notes; batch plans resume after interruptions.

./shot select FILE 42 78 --stars 3

Pace

Screen pace measured as % of frame width per second, with speed-up recommendations. Mechanical numbers; the mood call stays with the agent.

./shot pace --selects

Montage

Sequence ordering with a variety-and-narrative lint, then crossfade splicing - with optional motion interpolation for mixed frame rates.

./shot montage --smooth

Music

AI-generated track (Stable Audio) probed for duration, loudness and energy curve, then muxed onto the render. Paid API calls sit behind explicit cost gates.

./shot music --generate

Publish

YouTube thumbnail from a hero frame, plus title and description built from your channel template.

./shot publish --frame FILE T
00:00:03 EXAMPLE

Films made end-to-end with this pipeline.

Selection, pacing, montage with crossfades and the YouTube publishing assets were all driven by the agent through the CLI.

Still from “Pieniny - Three Crowns & the Dunajec” - an aerial 4K drone shot Pieniny - Three Crowns & the Dunajec - Cinematic 4K · watch on YouTube ↗ Still from “Pruszków, WKD Komorów” - an aerial 4K drone shot Pruszków, WKD Komorów - 4K DJI Mini 3 · watch on YouTube ↗
00:00:04 CLI

One interface for humans and agents.

All commands take multiple files (native batch) and support --json: result on stdout, logs on stderr, exit ≠ 0 on error.

./shot statusproject dashboard: inputs, selects, sequence, render, music, publishing
./shot uithe same state as a read-only web UI - selects gallery, cuts, inputs, video preview
./shot scansmoothness analysis + contact sheet in one pass (mtime cache)
./shot selectcut a select from the source, with stars, notes and resumable batch plans
./shot pacescreen pace (%/s) + speed-up recommendation; finds dull stretches to trim
./shot sequencemontage order + lint for variety and narrative structure
./shot montagecrossfade splice; stream-copy drafts; --smooth interpolation
./shot musicgenerate (Stable Audio), probe, and mux a track onto the render
./shot publishYouTube thumbnail, title and description
./shot locateread-only mapping: montage timeline ↔ source shots
./shot archivemove the whole project state aside and start clean; restore reverses it

Plus sheet, frames, jitter, speed, tag, trim, smooth, config and validate - full flag semantics live in ./shot <command> --help and the README.

00:00:05 READ THIS FIRST

Young software. We’d rather you knew.

EARLY DAYS

Built iteratively with an AI agent around one person’s real workflow, not engineered as a product. Expect rough edges, missing features and breaking changes.

RESOURCE-HUNGRY

Selects and montage renders re-encode 4K with x264 (~4× real time per clip); --smooth interpolation needs ~6 GB RAM per clip on top. A full SD card keeps every core busy for a while.

BACK UP YOUR FOOTAGE

The pipeline never modifies originals - selects are copies, cleanup is archiving - but this is young software driven by an agent. Keep your own backup. Use at your own risk.

00:00:06 QUICKSTART

Three commands and a sentence.

  • Python ≥ 3.10 with a venv (the ./shot wrapper expects .venv/)
  • ffmpeg / ffprobe on PATH
  • macOS or Linux (no Windows support)
  • Optional: a Stability AI key - only for music generation. Everything else is free and offline.
# once
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

# drop footage into input/ - or point at the SD card
./shot config --input-dir /Volumes/SDCARD

# then open Claude Code in the repo and say:
“review the new footage”   → /shot-review
“edit the film”            → /montage
“autopilot”                → no questions asked + a decision report