| name | video-edit-cli |
| description | Edit, inspect, transcribe, cut, master, or package video and audio media with the headless `video-edit-cli` CLI. Use when the user asks to edit a recording, cut a video, inspect unfamiliar media, extract audio, preview a range, synchronize cameras, make a vertical clip, or produce podcast/episode deliverables. |
You are the editor; the video-edit-cli CLI is your workbench. It exposes atomic,
deterministic primitives that print one JSON result on stdout. You form the
editorial plan yourself — no command decides what to keep, remove, or highlight.
Run video-edit-cli --help (and --help on any subcommand) for the authoritative
command surface; inside this repository run it as uv run video-edit-cli ….
If video-edit-cli is not on PATH, install it first with
uv tool install video-edit-cli (Apple Silicon transcription:
uv tool install 'video-edit-cli[mlx]'); ffmpeg and ffprobe must already be
installed separately.
Invariants (hold for every task)
- Source media is immutable. Never overwrite, re-encode in place, or delete an
original. Every derived file is new and keeps its
*.provenance.json sidecar.
- Evidence before edits: never act on a range you have not inspected through
metadata, transcript, frames, waveform, or preview.
- Validate before rendering; preview before mastering when edits are material.
- Prefer the cheapest sufficient evidence:
probe and transcript first for
dialogue; targeted visual/audio inspection only where a decision needs it.
Method
- Establish the outcome. Restate what deliverable is requested and what
media exists. Done when you can name the requested outputs and every source
file involved.
- Preflight the workflow. Run
video-edit-cli doctor --workflow base, or
use transcription, vertical-captioned, or audio-restoration when those
capabilities apply.
Resolve failed dependency checks before expensive work.
- Set up a workspace. Read references/workspace.md,
announce the chosen project path, then reuse a matching project or run
video-edit-cli workspace init. Default to
<project-root>/video-edit-projects/YYYY-MM-DD-<source-id-or-slug>/edit/
unless the user specifies another location. Done when workspace.json lists
every source with its hash.
- Inspect the media.
probe every source; gather audio, proxies, frames,
filmstrips, waveforms, or range previews as decisions require. For dialogue
media read references/transcription.md and
transcribe first. Done when you know each source's duration, streams, and
content well enough to justify the plan you are about to form.
- Plan and render. Read references/edit-plan.md
before creating or modifying a plan; author the plan yourself, validate it,
and render a preview. Done when the validated plan renders and its manifest
exists.
- Review and revise. Read references/cut-review.md;
inspect every boundary of any render you produced. Done when each cut passes
or its defect is fixed or explicitly reported.
- Finish the deliverable. Done when every requested output passes technical
validation and the required visual/editorial review.
output validate does
not inspect framing or editorial quality; report those reviews separately.
Branch references (read when the condition applies)
