Documentation

Drive video edits from the command line.

MovieStar is a CLI built for AI agents. Load a video, find moments by what was said, make reversible edits, verify a frame, and render — and every command hands back structured JSON an agent can act on.

Install Quickstart Command reference

Install

Requires Python 3.10+ and FFmpeg on your PATH. On macOS: brew install ffmpeg.

install from PyPI

$ pip install moviestar

check it's working

$ moviestar --help

Quickstart

One clip, start to finish

Load a recording, find a line by what was said, cut a clean vertical clip, check the frame, and render. Each command appends to the spec and hands back JSON with the timecodes and the next step.

1 — load the video

$ moviestar load talk.mp4 --as src_0

2 — find the moment by transcript

$ moviestar find "this is where you get to the pain"

what it got back

{
  "command": "find",
  "query": "this is where you get to the pain",
  "matches": [
    {
      "text": "this is where you get to that pain",
      "score": 0.91,
      "source_range": {
        "from": {
          "text": "0:00:38.700",
          "seconds": 38.7
        },
        "to": {
          "text": "0:00:41.200",
          "seconds": 41.2
        }
      }
    }
  ],
  "hint": "Pipe a match into trim with --snap-to-words for clean boundaries."
}

3 — trim to the range (reversible)

$ moviestar trim --from 0:00:38.700 --to 0:00:41.200 --snap-to-words

4 — verify a single frame

$ moviestar screenshot --at 0:00:00.000

5 — render the finished clip

$ moviestar export short.mp4

Made a wrong cut? moviestar undo reverts the last operation. Want to see the whole plan? moviestar spec prints the current edit spec as JSON.

Concepts

How MovieStar thinks

Every edit is a spec

Commands don't touch your source file. Each edit appends a declarative operation to a spec — reversible with undo, inspectable with spec, and reproducible on export.

Address by words or by time

find searches the transcript and hands back exact timecodes. Feed those into trim or cut, or address any edit directly by timecode. No eyeballing the scrubber.

Structured JSON, always

Every command prints a structured envelope — timecodes, durations, and a hint on what to do next. An agent reads it and drives the whole loop itself.

Deterministic render

export renders the spec the same way every time. Same input, same result — no hidden model calls, no randomness. Preview a single frame in seconds first.

Reference

Command reference

The full surface, grouped by the edit loop. Run moviestar <command> --help for options on any of them.

Load & browse

Get a video into a project and perceive what's in it.

load: Load one or more videos into a project workspace.
status: Show sources, edits, transcripts, and overlays at a glance.
skim: Fast sample of thumbnails + transcript across a range.
inspect: Dense thumbnails + transcript for a narrow range, on demand.
storyboard: Contact sheet — one composite image sampling the whole video.
probe: Inspect a media file's metadata and audio loudness.

Find & edit

Address moments by what was said or by time, then edit the spec.

find: Fuzzy-search the project's transcript for a phrase.
trim: Trim to a timecode range. Appends to the edit spec.
cut: Remove a range from a source's result. Appends to the edit spec.
clip: Extract one independent clip from a source to its own MP4.
undo: Revert the last edit operation.
spec: Show, replace, or reset the current edit spec (JSON).
history: Show the step-by-step lineage of one source's edits.

Verify & render

Check your work at any fidelity, then commit to a full render.

screenshot: Capture a single frame at a timecode.
watch: Extract a video segment from the loaded project as MP4.
export: Render the current edit spec to a final MP4.
clean: Clean generated output artifacts.

Point your agent at a video

MovieStar runs locally and works with Claude Code and Codex. Install it, describe the edit, and let the agent drive the loop.

See it in action MovieStar on PyPI