moviestar 0.3.0

Video editing CLI for AI agents. Load multi-camera footage, search transcripts, compose timelines and scene layouts, burn in captions, and render with FFmpeg.

moviestar

Video editing CLI for AI agents. Give your coding agent the ability to edit video.

Your agent loads one or many videos, fuzzy-searches the transcript, composes a timeline across multiple cameras, routes which source's audio plays, lays sources out on a canvas, burns in captions with spoken-word highlighting, and renders with FFmpeg — or extracts any number of standalone clips in one pass. All output is structured JSON. Source files are never modified — edits are described in a declarative spec and applied at render time.

Quick start

Make sure FFmpeg is on PATH (brew install ffmpeg on Mac), create a Python 3.10+ venv, then paste this into Claude Code, Cursor, or any coding agent:

Create a Python 3.10+ virtual environment, then:

pip install moviestar
moviestar --help

Read the --help output — it's your operational briefing.

Then load the video at ~/Downloads/podcast.mp4. Find the moment where
the host says "the bottom line, here's what I think." Trim to just
that sentence with --snap-to-words so the cuts don't land mid-word.
Export the result to ~/Desktop/clip.mp4 and tell me how long it is.

The agent will work through load → find → trim → export, returning structured JSON at every step. No GUI, no timeline, no manual scrubbing.

For a multi-camera recording, the agent can load cam1.mp4 cam2.mp4 screenshare.mp4, concat ranges from each into one timeline, pick whose mic plays with --audio-from, choose a global layout with --layout, or use scenes set for layout changes over time. Then captions generate burns word-highlighted captions from the transcript into the final render.

What's in MovieStar

Browse:

• moviestar load — index one or more videos, transcribe with local Whisper. --as <name> names sources; --add appends to an existing project.
• moviestar skim — fast browse: thumbnails + transcript over a range (--text-only for transcript alone).
• moviestar inspect — dense thumbnails on demand at a configurable interval.
• moviestar watch — extract an MP4 segment for multimodal model analysis.
• moviestar status — current project state at a glance.
• moviestar history — step-by-step edit lineage for a source.

Edit (multi-source):

• moviestar trim — append a trim to a source's edit spec (result-time semantics; stacks compose).
• moviestar cut — remove a range from the middle of a source's result.
• moviestar concat — stitch ranges from one or more sources into a single composition. --audio-from <source> routes which source's audio plays across the cut; --canvas, --layout, --slot, and --framing build canvas-aware visual compositions.
• moviestar layouts — inspect preset layout regions and sample images before choosing a layout.
• moviestar scenes set / moviestar scenes list — author and read ordered scene-layout compositions where each scene can use its own preset layout, slots, source ranges, framing, and audio route.
• moviestar undo — pop the last operation (or the last concat).
• moviestar spec — show the current spec (or --edit to replace, --reset to clear).
• moviestar find — fuzzy-search the transcript across every source; --context returns the surrounding timestamped segments.

Every source-specific command takes --source <id>, required only when a project has more than one source.

Captions and text overlays:

• moviestar captions generate — compile the transcript into caption overlays, following each scene's audio routing. --highlight spoken-word colors the word being spoken, timed from the transcript's word timing.
• moviestar captions import — import .srt / .vtt caption files as overlays (cue timing is result-time; line breaks preserved).
• moviestar overlays add — one timed text overlay: title, lower third, label, or creative emphasis text. Position presets or normalized --x/--y, --z-index stacking, style presets plus a CSS-like subset (--css "font-size: 72px; color: white; -moviestar-stroke: 4px black; transform: rotate(-8deg)").
• moviestar overlays dump / moviestar overlays set — round-trip the complete overlay state as editable JSON: fix caption text, shift timing, restyle, then atomically replace after validation.
• Overlays render on every verification surface — screenshot, inspect, watch, and export all burn them in, with fonts bundled so renders are identical across machines.

Output:

• moviestar export — render the composition, scene composition, layout composition, or a single source's edit to MP4, moviestar-clips/export.mp4 by default.
• moviestar clip — extract one standalone clip to its own MP4 (source-time, leaves the edit spec untouched).
• moviestar batch — extract many standalone clips from a JSON recipe in one atomic, frame-exact pass.
• moviestar clean — preview or delete generated media artifacts.
• moviestar screenshot — single frame at a timecode (project-aware: --at is in result-time).

Always-available:

• moviestar probe — ffprobe metadata as JSON.
• --dry-run on every expensive command (load, inspect, watch, export, clip, batch, concat, spec --edit).

Run moviestar --help for the full command list.

Why moviestar

Video editing tools are built for humans with GUIs. Agents don't have hands on a timeline or eyes on a canvas. moviestar is the hands; the agent is the brain.

• Verbose by default. Every command returns rich structured JSON — agents can discard what they don't need, but can't invent data the CLI didn't provide.
• Deterministic. Same input + same parameters = same output. No randomness, no hidden model calls.
• Result-time semantics. A second trim narrows the current result, not the original source. find matches resolve to both source-time and result-time so screenshots and exports compose cleanly.
• Multi-source native. Load many cameras into one workspace, compose a timeline across them, and route audio per-composition — the same structured CLI the single-source flow uses.
• Non-destructive. Source files are never modified.

Full design and product principles in the project docs.

Requirements

• Python 3.10+
• FFmpeg on PATH (brew install ffmpeg / apt install ffmpeg)

The package weighs ~210MB on install — faster-whisper ships local transcription out of the box (no API keys, no cloud round-trip). Diarization is opt-in: pip install moviestar[diarize].

Status

v0.3 ships the visual-composition arc: output canvases (vertical/square/landscape), preset layouts, ordered scene compositions, and burned-in captions with spoken-word highlighting. The roadmap of what's next lives with the project.