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

Script / Library	Purpose
scripts/transcribe_local.py <video> [--model base] [--diarize]	Local faster_whisper word-level transcript → edit/transcripts/<name>.json (cached by source hash + settings)
scripts/pack_transcripts.py --edit-dir <dir>	All transcripts/*.json → edit/takes_packed.md (phrase-level; breaks on silence ≥0.5 s or speaker change)
scripts/timeline_view.py <video> <start> <end> [-o out.png]	Filmstrip + waveform + word-label PNG for one range → edit/verify/
scripts/render.py <edl.json> [-o out.mp4] [--preview]	EDL → ffmpeg: per-segment extract+grade+fades → lossless concat → overlays → subtitles (LAST)
scripts/self_eval.py <edl.json> <rendered.mp4>	Inspect render at each cut boundary; report discontinuities/pops/hidden-subs as JSON
scripts/edl.py	Shared lib: EDL load/validate, SRT generation, output-timeline offset math (imported by render/self_eval/tests)

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

Need	Skill
Overlay animations (kinetic type, UI, charts)	Remotion (PAI) / HyperFrames / PIL
Cinematic generated launch video	launch-video (broomva) — generative, Liquid Glass
AI-generated B-roll / frames	content-creation (Imagen/Veo)
Audio-only cleanup	AudioEditor (PAI)
Narrated pitch from text + cloned voice	cloned-voice-pitch-pipeline (OmniVoice → Remotion)
Local word-level ASR backbone	faster_whisper (this skill)

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.