Metadata-Version: 2.4
Name: moviestar
Version: 0.3.0
Summary: Video editing CLI for AI agents. Load multi-camera footage, search transcripts, compose timelines and scene layouts, burn in captions, and render with FFmpeg.
Author: James Dillard
License: BSL-1.1
Keywords: video,ffmpeg,ai,agents,cli,transcript,whisper,editing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Requires-Dist: faster-whisper>=1.0
Requires-Dist: rapidfuzz>=3.0
Provides-Extra: diarize
Requires-Dist: pyannote.audio>=3.0; extra == "diarize"

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