Metadata-Version: 2.4
Name: moviestar
Version: 0.1.0
Summary: Video editing CLI for AI agents. Load videos, fuzzy-search transcripts, trim, and export 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 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.
