moviestar 0.2.1

Video editing CLI for AI agents. Load multi-camera footage, search transcripts, compose timelines, route audio, and extract clips 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, 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, and export the synced result.

What's in v0.2

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.
• 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.

Output:

• moviestar export — render the 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.2 — multi-source editing, multicam audio routing, and clip extraction. Load one camera or many, compose a timeline across them, route audio, and extract standalone clips. The roadmap of what's next lives with the project.