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. Every command hands back structured JSON an agent can act on.

Install Quickstart Command reference Public docs Install the agent skill

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

check FFmpeg capabilities

$ moviestar doctor

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 plan, not a change to your file

Commands don't touch your source file. Each edit is saved as a step in a plan you can undo, inspect with spec, and re-run 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.

Scene composition

Shape and animate the canvas.

Use scenes geometry to resize and place a slot, make it a circle, rounded rectangle, or rectangle, add a border, or bounce it across the canvas. Camera motion is separate: the target → preview → apply flow lets an agent point at important content and inspect the exact crop before saving a zoom.

Every verification surface uses the same resolved plan. Check a project frame with screenshot, or run screenshot --file on the rendered MP4 to inspect the artifact itself.

shape and place an inset

$ moviestar scenes geometry demo:inset --size small --at bottom-right --shape circle --border "4px white"

capture a zoom target

$ moviestar scenes motion target --at 0:42 --slot main

verify the rendered artifact

$ moviestar screenshot --file final.mp4 --at 0:42

Reference

Command reference

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

Whatever the command, the reply is a JSON envelope in the same shape: what it did, the data an agent needs, and a hint on the next step. Here’s what load hands back.

what a command hands back

{
  "status": "loaded",
  "project_dir": "/videos/talk/moviestar",
  "sources": [
    {
      "id": "src_0",
      "path": "/videos/talk/talk.mp4",
      "duration": "0:04:12.000",
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "transcript": {
        "model": "base",
        "word_count": 812,
        "duration": 252
      }
    }
  ],
  "hint": "Run 'moviestar skim' to browse frames and transcript. Narrow with --from/--to."
}

Prepare & perceive

Check the environment, load footage, and understand what is in it.

doctor: Check FFmpeg readiness and feature support.
probe: Inspect a media file's metadata and audio loudness.
models: Pre-download local Whisper transcription models.
load: Load one or more videos into a project workspace.
retranscribe: Re-run transcription without discarding edits or frames.
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.
activity: Measure visual change and candidate active or idle ranges.
storyboard: Contact sheet: one composite image sampling the whole video.

Find & rough cut

Address moments by words or time, then build a reversible timeline.

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.
concat: Stitch ranges from one or more sources into one composition.
history: Show the step-by-step lineage of one source's edits.
undo: Revert the last edit operation.
spec: Show, replace, or reset the current edit spec (JSON).

Compose & finish

Arrange scenes, shape the frame, add captions, and mix the soundtrack.

layouts: List and preview layout presets for an output canvas.
scenes: Author layouts, geometry, camera motion, and pacing over time.
captions: Generate or import caption overlays for burn-in.
overlays: Author timed titles, labels, and styled text.
audio: Mix source audio, voiceover, and music on the final timeline.
fonts: Add or list fonts for captions and overlays.

Verify, render & share

Check the result, produce files, and close the feedback loop.

screenshot: Capture a frame from the project or any exported file.
watch: Extract a video segment from the loaded project as MP4.
export: Render the current edit spec to a final MP4.
clip: Extract one independent clip from a source to its own MP4.
batch: Extract many standalone clips from one JSON recipe.
clean: Clean generated output artifacts.
feedback: Create or send guided product feedback with optional follow-up.
subscribe: Sign up for release updates via confirmation email.

Product feedback

Tell us what the editing loop taught you.

Run MovieStar feedback to start with a guided report. It asks for the context needed to triage quickly, with optional debugging, positive-feedback, idea, wild-idea, and follow-up email prompts.

Leave an email in the report and we’ll send a note when that feedback has been addressed. It is stored separately and does not subscribe you to general updates. For those, an agent can run moviestar subscribe EMAIL; the human activates the subscription from a confirmation email.

MovieStar never automatically includes project files, paths, logs, account identifiers, or command history.

create a guided report

$ moviestar feedback > feedback.md

submit the completed report

$ moviestar feedback --file feedback.md

or send a quick note

$ moviestar feedback --quick "trim was confusing"

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