video-cut

What this does

Takes an agent-authored clip plan (which source ranges to keep, in order) and:

1. Validates + enriches it into clip_plan_validated.json (clip ids, source/output times, total duration, overlap checks). Boundaries are then snapped to natural pauses (SNAP_CLIP_LINE_END) and nudged clear of the original footage's hard cuts (SCENE_CUT_SNAP, see below).
2. Concatenates those source ranges into a single edited_source.mp4.
3. (Orchestrated path — default) Stops here; the agent writes narration.json against the output timeline (0 .. total seconds). Invoked by recap.py with --no-narration-map.
4. (Legacy single-pass path) When invoked directly without --no-narration-map: maps narration written in original-video time onto the cut output timeline → narration_mapped.json.

It is stateless: given the same inputs it reproduces the same outputs. Caching is just "reuse edited_source.mp4 if it is newer than clip_plan.json".

Input contract

work_dir/clip_plan.json — a JSON array, or {"clips": [...]}. Each clip:

{"start": 12.0, "end": 28.5, "reason": "inciting incident"}