Stage Edit

stage-edit

How to intelligently edit real user-supplied footage while keeping source and decisions auditable. Deterministic operations handle cuts, joins, captions, overlays, reframes, and audio. When the request changes pixels semantically—remove an object, alter a background, relight, or make another content-aware local change—keep the EDIT route and execute only that bounded segment as a signed ovs video --operation edit call after paid-generation approval.

Subtitle safety hard rule. Burn captions only through ovs edit burnsubs; do not hand-write ffmpeg subtitle, drawtext, or PNG-overlay fallback commands. If burnsubs fails because the runtime ffmpeg lacks subtitle filter support, stop and report the blocker instead of improvising a custom ffmpeg graph.

If the task is to FIND / SELECT / REDUCE / CLEAN rather than run a known timecode edit — remove dead air, drop fillers, pick highlights, cut a long recording down — read stage-decide first: it covers understanding the footage and producing an evidence-bearing rough cut (the deterministic auto-cuts ovs edit trim-silence / remove-fillers, plus ovs scenes / ovs quality / ovs plan rank-takes). This skill is for executing cuts you have already chosen.

Two assembly paths — pick by whether the result needs to stay re-editable:

• Plan-backed (anything the user may later adjust: narration, multi-shot, segmented edits). Author project/plan.json (the segments EDL — see stage-plan) carrying ONLY the operations the user asked for (the deltas) — everything else is the source, passed through untouched. Keep each editable concern SEPARATE in the plan: each narration line in tracks.narration.segments with its own produced_path, each caption in tracks.captions.lines as data, each segment carrying status/produced_path. Assemble with ovs edit (trim → concat → mix → burnsubs). Because plan.json holds every piece separately, a later "fix one caption / re-voice one line" is a one-entry edit + one re-render — do NOT pre-bake (e.g. one big narration file), which destroys that separability.
• One-shot deterministic (a plain trim or concat the user just wants done). Use ovs edit directly; write no plan.json.

Intelligent Edit Contract

Write project/plan.json#edit_strategy whenever OVS decides what to change rather than merely executing user-provided timecodes. Declare its mode (deterministic, semantic, or mixed), exact objectives, only the evidence signals actually used, and non-empty, non-overlapping preserve/may_change.

Declare every source/reference in top-level references with media type, reproduce/edit/guide intent and basis, roles, required state, preservation boundary, target segments, and video temporal anchors. A semantic video edit is source:"generate", media_kind:"video", operation:"edit" with its original in reference_video_paths or reference_video_urls; it remains owned by EDIT and counts as billable.

For a plan-backed follow-up, invalidate only the changed entry and its derived assembly. Preserve source probes, transcripts, inspected-frame evidence, unaffected cuts, narration, and sibling outputs. A content-identical source moved to a new path is an implementation locator change, not new creative intent.

The deterministic editing loop

1. Ingest — always probe first. For every input clip, read its metadata (duration, resolution, fps, codecs) with ovs edit probe. Never plan a cut blind; a trim past the real duration produces an empty or broken clip.
2. Plan — write an edit_decisions timeline. From the user's intent + the probe results, decide the exact segments and order, and write them to project/edit_plan.json so the plan is inspectable and re-runnable. Shape:

   {
     "segments": [
       { "input": "raw/clipA.mp4", "start": 12.0, "duration": 8.0 },
       { "input": "raw/clipB.mp4", "start": 0.0,  "duration": 5.5 }
     ],
     "subtitles": "raw/captions.srt",
     "overlay": { "media": "assets/logo.png", "x": 40, "y": 40 }
   }

   Every start/duration must be inside the probed duration of its input.
3. Execute in order.
   • ovs edit trim each segment to its own file (project/cuts/seg-1.mp4, ...).
   • ovs edit concat the cut files (in plan order) into one (project/render/edited.mp4).
   • If subtitles: ovs edit burnsubs the .srt/.ass onto the concatenated video.
   • If an overlay (logo / lower-third image / PiP): ovs edit overlay it at the planned position.
4. Publish the final file.

Read transcript and screen-grounded editing only for topic-based selection, captions, localization or narration added to existing footage. It owns evidence-first analysis, per-line speech and extracted-frame inspection.