Video Cut

video-cut — local-first raw-footage video editor

Drop raw clips in a folder → describe the cut → get edit/final.mp4. Fully local. The editorial counterpart to our generative video skills (launch-video, Remotion, cloned-voice-pitch-pipeline). Compounds on browser-use/video-use: same two-layer reading architecture, but local ASR instead of cloud ElevenLabs Scribe.

Core principle — two-layer reading (never dump frames)

The agent reads video through two cheap layers, not by watching frames:

1. Transcript layer — transcribe_local.py runs faster_whisper with word-level timestamps (local, MPS/CPU). Packed into takes_packed.md (~tens of KB) — the primary reading artifact. This is the routing projection.
2. Visual layer (on-demand) — timeline_view.py <video> <start> <end> renders a filmstrip + waveform + word-label PNG only at decision points (ambiguous pauses, retake comparisons, cut-point checks). Never a scan — the body-grep expansion.

This is research/entities/pattern/llm-as-index-architecture.md applied to the video modality: raw frames = the substrate you never dump; transcript = the projection that routes; timeline_view = on-demand expansion. (See references/local-asr.md.)

Pipeline

Transcribe (local) → Pack → LLM reasons (proposes plain-English strategy, waits) →
EDL → Render (ffmpeg) → Self-eval (≤3 correction loops) → final.mp4

The EDL (edl.json) is the declarative cut IR — cut ranges + grade + overlays + subtitles in one file. Decouples decision (the agent) from render (ffmpeg). Full schema in references/edl-format.md.

Hard Rules (non-negotiable production correctness)

These are inherited from video-use's hard-won list. See references/hard-rules.md for the ffmpeg specifics. Summary:

1. Subtitles applied LAST in the filter chain, after every overlay.
2. Per-segment extract → lossless concat (-c copy). Never double-encode.
3. 30 ms audio fades (afade) at every cut — no audible pops.
4. Snap cuts to word boundaries — never cut inside a word; use transcript timestamps.
5. Cut padding 30–200 ms absorbs ASR drift.
6. Word-level verbatim ASR only — never phrase-mode or normalized fillers.
7. Cache transcripts per source (by content hash) — never re-transcribe unchanged input.
8. Caption output-timeline offsets — out = word.start - range.start + range_offset.
9. Output isolation — all session files go to <videos_dir>/edit/, never elsewhere.
10. Strategy approval — confirm a plain-English plan before touching the cut.

Scripts

Directory layout (created under <videos_dir>/edit/)

<videos_dir>/
├── <source clips>
└── edit/
    ├── project.md                 # session memory (Strategy / Decisions / Outstanding)
    ├── takes_packed.md            # phrase-level transcript (primary LLM input)
    ├── edl.json                   # cut decisions + grade + overlays + subtitles
    ├── transcripts/<name>.json    # cached word-level transcript
    ├── clips_graded/seg_NNN.mp4   # per-segment extracts (grade + 30ms fades)
    ├── animations/slot_<id>/      # per-overlay source + render (Remotion/HyperFrames/PIL)
    ├── master.srt                 # output-timeline subtitles
    ├── verify/                    # timeline_view PNGs + self-eval frames
    ├── preview.mp4
    └── final.mp4

Workflow

1. Inventory — ffprobe sources; transcribe_local.py each (or batch); pack_transcripts.py.
2. Pre-scan — read takes_packed.md; flag filler/false-starts/retakes.
3. Converse — shape, content type, pacing, grade, subtitle style, overlays.
4. Propose strategy — 4–8 sentences; wait for confirmation (Hard Rule 10).
5. Build EDL — author edl.json; spawn parallel overlay sub-agents if needed (Remotion etc.).
6. Render — render.py edl.json --preview first.
7. Self-eval — self_eval.py before showing the user; correct, ≤3 passes.
8. Iterate — natural-language feedback → re-render; append to project.md.

Composition map

video-cut edits; the others generate. They share the EDL as a future common IR (overlays produced by Remotion are referenced as EDL overlays[]).

Requirements

ffmpeg + ffprobe (required), faster_whisper (required, local ASR), yt-dlp (optional, for --download). Install: uv pip install -r requirements.txt. See references/local-asr.md.

Anti-patterns (from video-use, confirmed)

• Dumping frames to the model (the 45M-token mistake) — use the two-layer reading.
• Phrase-level transcription (loses sub-second gaps) — word-level verbatim only.
• Burning subtitles before overlay composition — subtitles LAST.
• Single filtergraph that re-encodes everything twice — extract→lossless-concat→one final pass.
• Hard audio cuts at boundaries — 30 ms fades.
• Editing before strategy confirmation.
• Re-transcribing cached sources.