Stage Assemble

stage-assemble

How to execute a validated project/plan.json into one finished file. By the time you are here the plan passed ovs plan validate and the user approved it at gate B. Walk it; do not re-plan. The producers are ovs edit, ovs draft, ovs video/ovs image, ovs speak, and the assembler is ovs edit (or the equivalent MCP tools).

Step 1 — Produce each segment (delegate by source)

Iterate segments in order. For each, produce its produced_path according to source, then write that path + status:"done" back into the segment so a resume never re-produces it:

• edit → stage-edit: ovs edit trim the input_id to [in_sec, out_sec] → project/cuts/<id>.mp4.
• compose → stage-compose: build a small visual-only manifest-owned composition for spec.kind (title card, lower-third, stat card, captions) under project/compositions/<id>/ → run ovs draft project/compositions/<id> --out project/parts/<id>.mp4 --quality draft --report project/reports/<id>-compose-report.json. This keeps compose segments on the same manifest/source/check/video-QA path as standalone COMPOSE while still letting the assembler own narration and loudness.
• generate → stage-generate (+ stage-consistency for recurring characters): only AFTER gate C. ovs video/ovs image → project/assets/<id>.mp4. For operation:"edit", pass the exact original reference video and obey top-level references plus edit_strategy; never widen it into regeneration. A failed/unknown paid attempt is not an automatic retry. Preserve completed siblings and require a new output path for any later authorized attempt.
• provided → use spec.asset_id as-is (probe it first; conform aspect/fps if needed).

Billable generate segments must not run before gate C has confirmed the count from cost_estimate. Produce cheap/free segments (edit, compose, provided) freely.

Step 2 — Assemble in ffmpeg tiers (the default path)

Assemble deterministically, bottom-up. This tiered order is the default; it is predictable and cheap, and keeps each clip's real audio intact:

1. Primary track — ovs edit concat the primary-layer produced_paths in order → project/render/primary.mp4. Conform aspect/fps on the way in if sources differ; read the returned conformance report and verify it still matches the approved canvas.
2. Overlays / bg — Do not place a full-frame opaque composed video over source footage: it erases the base. Use genuinely transparent or bounded overlays, or amend the plan to make it a primary beat. Do not bypass the opaque-overlay refusal with resizing tricks. for each overlay/bg segment, ovs edit overlay its part onto the primary over the window of the segment named in over (title cards, lower-thirds, logos). Composed layers are VISUAL-ONLY — they must not carry their own narration audio. This includes a compose segment that IS the primary track (a full-video composition): render it SILENT — do not put a narration <audio> in its index.html. The assembler owns narration (tier 3), so a composition that bakes it in would mean narration is added TWICE (the "two voices" defect).
3. Narration — added EXACTLY ONCE, here. If active, require the Gate-B-signed tracks.narration.synthesis profile. Run ovs narration fit for each timed line before ovs speak; shorten over-budget text in the plan without changing the approved meaning. Synthesize with the exact signed voice/model/format/speed, probe the result, rerun measured fit, and write each line's produced_path. If measured timing misses, revise once using the suggested unit budget rather than repeatedly billing or forcing speed. Add all produced lines in ONE ovs edit mix call at their start_sec. The default existing-audio rejection catches compose segments that accidentally baked narration; re-render those SILENT. Read voicedRatio, interiorGaps, maxOverlapSec and status: the last line reaching the end does not mean the whole track carries speech. Fix unintended dead air and collisions, and disclose any intentional silent tail at Gate D. Preserve a generated talking head's built-in lip-synced audio instead of adding a second voice.
4. Music — add tracks.music ducked under narration by the planned amount.
5. Captions — turn tracks.captions.lines ({text, start_sec, target_sec}) into a .srt, then ovs edit burnsubs. Avoid duplicating caption text already visibly present in that scene. Captions are DATA in the plan — burned ONLY here at assemble — so a later typo fix reuses the clean pre-caption primary/generated source and burns the revised file once. Never burn onto the already-captioned output and never regenerate an unchanged provider clip. If burnsubs fails because the runtime ffmpeg lacks subtitle filter support, stop and report that blocker; do not hand-write a fallback ffmpeg graph, PNG subtitle overlay, or drawtext pipeline.
6. Loudness — run ovs edit normalize-loudness project/render/draft.mp4 --out project/render/video.mp4. It normalizes to the video-craft §7 targets (~−14 LUFS integrated, true-peak ≤ ~−1 dBTP) and returns measured loudness; use ovs edit loudness only for diagnosis without writing an output.

Apply the plan's style_kit for cohesion: composed layers (titles/captions/cards) use its palette + fonts. A single lut graded across all clips is what unifies tonally mixed sources — until a grade op is available, keep mixed sources close at capture/trim and lean on the shared palette + consistent captions for cohesion rather than promising a uniform grade.

Output project/render/video.mp4 as the deliverable; project/render/draft.mp4 is the pre-normalized intermediate.

Director judgment (end-to-end assembly)

The craft of making mixed sources feel like one video, on top of the shared craft (video-craft). The seams between footage / generated / composed are where multi-source assembly falls apart — engineer continuity across them:

• One look across every source. Apply the style_kit so a cut from real footage → a generated shot → a composed card does not read as three videos: one type system + palette on every composed layer, one caption style throughout, matched aspect / fps, tonal proximity (a shared LUT is the unifier when available; video-craft §4).
• Audio is the through-line that hides the visual seam. One narration voice; a continuous music bed UNDER the cuts (do not restart it per segment); duck consistently (video-craft §7). The ear's continuity carries the eye across a source change — a reveal may drop music, but the bed bridges the cut.
• Rhythm over a mixed cut. Alternate motion vs. static and source types for momentum — do not stack three composed cards or three talking-head shots in a row (that is the repetition / slideshow smell, video-craft §3, §12). Vary holds.
• Cut on a content change, not just plan order. A hard cut on a beat / word change is invisible and professional; a crossfade signals a gentle topic shift (video-craft §5).
• Don't bury the hero. On a source_led piece, composed lower-thirds and captions FRAME the footage — they never cover its subject / face (video-craft §6).
• Apply the editing cut craft ACROSS the seams. The cut mechanics live in stage-edit → "Cut craft" (best sub-window, ≤ 4 transitions, L/J-cut sound bridges, handles / no freeze-frame, adjacent-diversity, a reason per cut) — apply them at every junction between sources, since the footage → generated → composed seams are exactly where a mixed cut betrays itself.