moviestar 0.1.0

Video editing CLI for AI agents. Load videos, fuzzy-search transcripts, trim, and export with FFmpeg.

moviestar

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

Your agent loads a video, fuzzy-searches the transcript, trims to result-time ranges, snaps cuts to word boundaries, and renders with FFmpeg. 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.

What's in v0.1

Browse:

• moviestar load — index a video, transcribe with local Whisper.
• moviestar skim — fast browse: thumbnails + transcript over a range.
• 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.

Edit:

• moviestar trim — append a trim to the edit spec (result-time semantics; stacks compose).
• moviestar undo — pop the last operation.
• moviestar spec — show the current spec (or --edit to replace).
• moviestar find — fuzzy-search the transcript for a phrase.

Output:

• moviestar export — render the spec's effective timeline to MP4.
• 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, 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.
• 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.1 — first public release. Core loop is working: load → browse → edit → export. The roadmap of what's next lives with the project.