---
name: finalcut
description: Conform an approved edit into Final Cut Pro — emit a clean, correct FCPXML that opens the cut as an editable 4K timeline so TJ can do final touches (stabilization, end cards, graphics, color, an extra L-cut). Use when TJ says "finalcut", "/finalcut", "make the XML", "make the FCPXML", "get this into Final Cut", "conform this", or after an /edit cut is approved and he wants to finish it in FCP. Handles BOTH landscape (full/flagship) AND vertical (reel) cuts. Pure emit — it does NOT make creative cut decisions (that's /edit) or write copy/thumbnails (that's /distribute), and it stops at the XML (no finishing/export hand-holding).
---

You are conforming an approved edit into Final Cut Pro. The job: emit a **clean, correct FCPXML** that opens the cut as an editable timeline, relinking the original 4K, with the rendered mix riding as reference audio. That's it — TJ finishes in FCP himself.

This is the **middle of the trio**: `/edit` (make the cut) → **`/finalcut` (conform to FCP)** → `/distribute` (package + post). Pipeline layout (restructured 2026-06-22, was `vision-experiment/`): the macro `Entrepreneurship Projects/YouTube TJSMind/` holds `pipeline/` (engine, incl. the emitters `emit_film_fcpxml.py` [single-source landscape], `emit_cinematic_fcpxml.py` [multi-source cinematic — segments], and `wrap_fcpxml.py` [wrap a finished render as one clip — vertical reels / overlay-only]) and `projects/<name>/` as siblings. Inputs per cut now live IN the project: the EDL in `projects/<name>/edl/<tag>_edl.json` + the rendered mp4 in `projects/<name>/render/` (from `/edit`). [Path-only update; deeper `/finalcut` rework deferred per TJ — one thing at a time.]

## What it emits (and the hard-won mechanics — don't deviate)
- **Video on the spine, frame-aligned + contiguous.** Offsets are ABSOLUTE accumulated-frame positions in `/30000s` (29.97 DF, frameDuration 1001/30000s). Do NOT chain accumulated durations as you go — rounding drifts. Compute each clip's offset from the running absolute frame total.
- **Relink the original 4K by path** (`file:///Volumes/<your footage drive>/.../footage/Cxxxx.MP4`, percent-encoded, no bookmarks). The drive MUST be mounted or FCP imports offline clips.
- **Mute camera scratch** with `srcEnable="video"` on every asset-clip — the rendered mix carries all audio.
- **STANDARD (TJ, 2026-06-23): ride SEPARATE audio stems as TWO connected lanes, not one baked mix.** Deliver `music` on `lane="-1"` (`role="music"`) and `voice` on `lane="-2"` (`role="dialogue"`) — so TJ can level/mute/trim/slide the VO independently of music in FCP without a re-render. The assembler writes the stems (`assemble_cinematic.py --audio` → `render/<cut>_voice.m4a` + `_music.m4a`; the hype reel's equivalent is music + nat-sound); the emitter detects the stems beside the render and rides both lanes, falling back to a single bounced `final mix` (`<out>_mix.m4a`) ONLY if stems are absent. Apply to EVERY conform (landscape AND reel) — make new assemblers export stems so this always holds. Reproducing the per-segment envelope/ducking natively isn't worth it — the duck is baked into the music stem, aligned to where VO sits.
- Format `r1` = 3840×2160 (land) or **1080×1920 (port)**, Rec.709.

## Landscape vs vertical — two strategies, pick by what FINISHING needs
Landscape always opens as PER-CLIP segments (never a wrap — TJ finishes per-clip: isolated stabilization + audio splices). The real choice is HOW the segments are sourced, decided by whether the footage is UNIFORM or MIXED:
- **Landscape, MIXED-format or has STILLS — DEFAULT: PRE-CUT UNIFORM SEGMENTS.** `python3 pipeline/emit_land_segments_fcpxml.py <cinematic_edl.json> <rendered_4k.mp4> <out>`. Pre-cuts EVERY shot to its own 3840×2160@29.97 segment (video cover-crop; **stills get Ken Burns motion BAKED in** — same zoompan as `assemble_cinematic.py`), contiguous actual-dur spine, mix on the `final mix` lane. **Because every segment IS the sequence format, FCP never conforms an odd source in-timeline → the entire black-clip class is structurally impossible.** Same proven technique as the vertical reel. Use for any [cinematic-review](cinematic-review) cut (multi-folder, mixed frame rate, stock, stills). Built + proven 2026-06-23 (`7Lakes_Cinematic`, 52 segments incl. 15 Ken Burns stills, passed all 7 audit checks first try). **LESSON (2026-06-23):** the relink approach (below) fought a black/format bug across ~6 imports; pre-cut segments make that class impossible — when a representation keeps producing the same class of failure, switch the representation, don't keep patching (POSTMORTEMS 2026-06-23 ×2).
- **Landscape, UNIFORM footage (single folder, all 4K@29.97) — relink originals by path.** `emit_film_fcpxml.py <edl> <rendered.mp4> <out>` (e.g. `Huacachina_flagship`). Cheaper (no segment render), keeps camera originals, but ONLY safe when every source is already the sequence format. Relinks by path → **drive MUST be mounted + sources present** (the 🇵🇪 emoji folder name percent-encodes fine). (`emit_cinematic_fcpxml.py` is the older mixed-format relink emitter with per-source `<format>` — superseded by pre-cut segments for mixed/stills cuts; use only if camera-original relink is explicitly required AND all sources are 16:9 standard-rate.)
- **⚠️ NEVER wrap a landscape cut as one clip** (`wrap_fcpxml.py` is vertical-reel / overlay-only) — it opens as one massive clip and blocks isolated stabilization/splices (2026-06-23).

- **Vertical (reel) — DEFAULT: PRE-CUT 9:16 SEGMENTS** via `python3 pipeline/emit_vert_segments_fcpxml.py <vert_edl.json> <reel_*_port.mp4> <out.fcpxml>`. Pre-crops each shot to its own 1080×1920 clip (exact render crop incl. per-shot `px`), per-clip editable (color/stabilization), and **rides separate `music` + `nat sound` lanes** (needs `assemble_hype_port.py --audio` stems beside the render). This is the default because separate audio lanes (the TJ standard) require segments, not a wrap. `7Lakes_Hype_Reel` rebuilt this way 2026-06-23.
- **Vertical — wrap the finished render** via `python3 pipeline/wrap_fcpxml.py <reel_*_port.mp4> <out.fcpxml> [name]` (single asset-clip, baked-in audio, pixel-exact, no drive mount). Use ONLY when the finishing is a simple OVERLAY (end card/title/graphic) AND separate audio lanes aren't needed — it CANNOT split music/voice. How `Huacachina_reel.fcpxml` was made (2026-06-21).

- **Vertical — ONLY if per-clip 4K editing is genuinely needed:** the 4K-relinked conform requires baking each clip's 9:16 crop (`crop=1215:2160:x:0 → 1080×1920`, `x=(3840-1215)/2*(1+px)`; the 1215×2160 slice is exactly 9:16 so `<adjust-crop mode="trim">` + `spatialConform="fill"`, honoring per-clip `px`). **CAUTION — verification gap:** FCP transform/crop UNITS can't be confirmed without opening Final Cut (no headless render of an FCPXML), so a 4K vertical conform CANNOT be self-verified. Don't ship it blind (a mis-framed FCPXML is worse than none, per below). Build it only WITH TJ watching FCP: have him import and eyeball clip 1's framing against `reel_*_port.mp4`, then adjust the transform values until it matches ([[feedback_verify_visuals_not_metadata]] — look, don't trust the math). Until that loop is done once and the unit recipe is proven, prefer the wrap-the-render default.

## Gotchas baked in
- **"Invalid edit with no respective media" on EVERY asset-clip (timeline imports EMPTY) = a SOURCE/ASSET-DECLARATION mismatch, diagnose by DIFFING a working sibling's actual MEDIA, not just the XML.** Two distinct root causes hit Koh Samui (2026-06-25), both invisible in the XML — found only by `ffprobe`-ing the referenced files vs a known-good project's files:
  - **Sony `.mov` carries a `tmcd` timecode track.** Pre-cut SEGMENTS made from `.mov` come out with TWO streams (video + `tmcd` data) → FCP rejects every segment. `-map 0:v:0 -dn` is NOT enough — the mov/mp4 MUXER auto-writes a tmcd track from the input's timecode metadata. Fix: **`-write_tmcd 0`** on the segment ffmpeg → pure single-video-stream segment. (`.MP4` sources like 7lakes didn't hit this; `.mov` does. Verify segments are single-stream: `ffprobe -show_entries stream=index`.)
  - **Sony `.mov` originals CANNOT be relinked raw** — the `tmcd` timecode stream makes FCP reject every relinked clip ("no respective media"), and declaring `hasAudio` did NOT fix it (Koh Samui flagship, 2026-06-25; `.MP4` originals with an `rtmd` data stream relinked FINE on Huacachina — `.mov` tmcd is the difference). Fix that WORKED: relink **clean video-only stream-COPIES** of each unique source — `ffmpeg -i src.mov -map 0:v:0 -c:v copy -an -dn -sn -write_tmcd 0 clean.mp4` (FAST, no re-encode), declared video-only (no `hasAudio`, no `srcEnable`), spine `start=sin` as normal. Makes the relink structurally identical to the working pre-cut segments. `koh-samui/emit_finalcut.py` does this in its `land` branch (`*_clean/` dir).
- **`srcEnable="video"`**: keep it on relinked ORIGINALS (mute camera scratch); harmless but unnecessary on video-only pre-cut segments. (Not the cause of the 2026-06-25 bug despite first appearances — the tmcd stream was.)
- **When you update a stem `.wav`, REGENERATE its `.m4a` — a stale `.m4a` silently rides OLD audio.** FCP plays the `.m4a` (AAC) version; if the emitter only converts `wav→m4a` when the m4a is *missing*, an updated `.wav` won't propagate and the FCPXML imports with the previous cut's audio (Koh Samui hybrid: new "My name is Hamid" intro in the `.wav` + preview mp4, but FCP played the old stutter open from the stale `.m4a` — looked unfixable until transcribing the `.m4a` itself). Fix in `emit_finalcut.py` `as_m4a()`: regenerate if `.m4a` missing OR `getmtime(wav) > getmtime(m4a)`. **Verify the actual `.m4a` (not the `.wav`/mp4) when audio "won't update."**
- **Connected audio stems MUST be `<asset-clip lane="-N" audioRole="...">`, NOT `<audio ref=...>`.** The `<audio>` element creates an audio *component* → FCP gives it a STRIPPED inspector (only Volume + Beat Detection/Tempo, NO Pan / Audio Enhancements / Audio Configuration). A connected `<asset-clip>` with `audioRole` is a full audio CLIP → the complete per-clip audio toolset (Koh Samui, 2026-06-25; took 3 tries — `srcEnable` and `.wav`→`.m4a` were both red herrings, the element TYPE was it). `koh-samui/emit_finalcut.py` nests two connected `<asset-clip>`s (music lane -1, voice lane -2). Audio stems as `.m4a` (AAC) is still good hygiene (FCP-standard, smaller) but was NOT the inspector fix.
- **Relinked stock must be 16:9 + a standard rate (29.97/30/59.94/60).** A non-16:9 / non-NTSC source (a 1998x1080 @23.98fps cinema stock clip) imports and decodes in the FCP BROWSER but renders BLACK on the timeline — FCP won't conform that format in-sequence. Symptom survives both a duration fix AND Create Optimized Media (it's a conform issue, not overrun or codec). Confirmed by comparing per-clip <format> entries: only the oddball was black, 2026-06-23. Fix: drop the clip, or pre-cut it to the sequence format (16:9 @29.97) first. Vet stock footage formats before adding to a cut.
- **Spine clip duration = the shot's ACTUAL length, NOT the edge-to-edge span.** Building each clip's timeline duration as `next_off - this_off` inflates it to fill the assembler's small gaps; a SHORT source (e.g. a 4.8s stock clip) then plays past its end = a BLACK clip on the timeline (looks like missing/codec, but it's an in/out overrun — confirmed by it staying black even after Create Optimized Media, 2026-06-23). Use contiguous offsets from accumulated actual durs, cap the last shot to hit `total`. Verify after emit: no clip's `sin+duration` exceeds its source length.
- **No `tcFormat` on `<asset-clip>`** — it's a SEQUENCE-level attr (DF/NDF) and is INVALID for non-NTSC source rates (a 24fps Rainbow-Mtn stock clip triggered "Encountered an unexpected value (tcFormat=DF)" warnings on the 7Lakes_Cinematic import, 2026-06-23). Keep `tcFormat="DF"` on `<sequence>` only. (The legacy `emit_film_fcpxml.py` puts it on clips too — harmless only because Huacachina was all 29.97; don't copy that into multi-rate emitters.)
- **ALL `media-rep src` must be ABSOLUTE `file://` paths.** A relative URL (`file://projects/…`) imports OFFLINE (red clip) in FCP. The video srcs come from the EDL as absolute `/Volumes/…`; the **bounced mix** path must be `os.path.abspath(...)` too — emitting it relative is exactly what made the `final mix` red on the first 7Lakes_Cinematic import (2026-06-23). Verify after emit: no `src="file://` value lacks a leading `/`.
- **Drive mounted** before emit (relink-by-path needs `/Volumes/<your footage drive>`).
- **Every looped still (`-loop 1 -i x.png`) MUST carry `-t <dur>`, and the output `-shortest`** (or `shortest=1` on the overlay). A looped still is an infinite input; without the bound ffmpeg encodes forever after the real clip ends and a background render silently stalls (2026-09-05, 30 min lost). When a render goes quiet, check `ps aux | grep ffmpeg` for the live command and CPU time — the log only records completions. (See `POSTMORTEMS.md` 2026-09-05.)
- If you ever bake audio fades while prepping a mix, **never `afade=t=out`** (silences the clip in this ffmpeg) — use `areverse,afade=t=in,areverse`. (See `POSTMORTEMS.md` 2026-06-21.)
- One mix per cut; name it `final mix` so TJ recognizes it on the timeline.

## Pre-import audit — RUN ALL OF THESE BEFORE HANDING OVER ANY FCPXML
FCPXML *rendering* can't be verified headless (FCP is the only renderer), but its *structure* CAN — so do NOT ship-and-discover one defect per import. Batch every check in one pass (this is the fix for the 2026-06-23 ~6-round-trip saga). On the emitted file + the cut:
0. **DTD-validate headless against FCP's OWN DTD** (the key upgrade, 2026-07-01 — caught the 7 Books chunk import error before TJ ever saw it):
   `cp "/Applications/Final Cut Pro.app/Contents/Frameworks/Interchange.framework/Versions/A/Resources/FCPXMLv1_14.dtd" /tmp/ && xmllint --noout --dtdvalid /tmp/FCPXMLv1_14.dtd <out.fcpxml>`
   (Pick the DTD matching the file's `version=` attr; v1_14 is current as of FCP 11. The `cp` to /tmp is REQUIRED — xmllint resolves the --dtdvalid arg as a URI, so the space in "Final Cut Pro.app" makes it fail with "Could not parse DTD"; validating from a space-free path works, 2026-07-03.) Zero output = structurally valid. This catches element-ORDER violations minidom well-formedness can't — e.g. the DTD requires clip children in a fixed order (notes/modifiers BEFORE anchored/connected items); rebuilding a clip's children in a new order imports with "invalid edit" errors even though the XML is well-formed. When editing an existing FCPXML programmatically, PRESERVE each element's original child order (see `7 Immigrant Books/edit/ripple_source.py`).
1. **Every `src="file://…"` is ABSOLUTE (leading `/`) AND the file exists** (decode the percent-encoding / emoji; `urllib.parse.unquote`).
2. **`tcFormat` appears only on `<sequence>`, never on an `<asset-clip>`.**
3. **No clip overruns its source:** for each shot `sin + spine_duration ≤ source_length`. Spine durations are ACTUAL shot lengths (contiguous), not edge-to-edge spans.
4. **Every source is 16:9 AND a standard rate (29.97/30/59.94/60).** Any non-16:9 / non-NTSC clip (cinema 1.85:1, 23.98fps, etc.) renders BLACK in the FCP timeline — drop it or pre-cut it to the sequence format first. Vet stock-footage formats on ingest, before they enter the cut.
5. **Render video length == audio length** (no end freeze): `video_dur == container_dur`.
5b. **Audio-only asset-clips MUST carry a `format` ref** (2026-07-04, 7 Books sound-design pass): both the `<asset>` and every `<asset-clip>` referencing audio-only media need `format="rN"` pointing at a `<format name="FFVideoFormatRateUndefined"/>` resource (reuse the document's existing one; create it if absent). Without it FCP resolves the clip against the sequence's VIDEO format, finds no video stream in the asset, and silently DROPS the clip with "Invalid edit with no respective media" — while the file still DTD-validates cleanly (format is `#IMPLIED`), so check 0 will NOT catch this. Also clamp clip `start+duration` a frame INSIDE the audio file's real length (round-up frame quantization past EOF triggers the same warning), and write asset durations sample-exact (`int(dur*rate)/rate` timebase) like FCP does. Reference implementation: `7 Immigrant Books/sound/emit_sound.py`.
6. **Well-formed XML** (`xml.dom.minidom.parse`).
7. **Landscape = segments (per-clip), not a wrap;** vertical reel = wrap (or pre-cut segments) — match what the finishing needs.
8. **Audio = SEPARATE lanes, NOT a single baked mix** (TJ standard 2026-06-23). Landscape/cinematic = `music` (lane -1, role music) + `voice` (lane -2, role dialogue) via `assemble_cinematic.py --audio`. Reel (no VO) = `music` (lane -1) + `nat sound` (lane -2, role effects) via `assemble_hype_port.py --audio` → `hype_music.m4a` + `hype_nat.m4a`. The segment emitters detect the stems beside the render and ride both lanes; single `final mix` is the fallback ONLY when stems are absent. If a conform ships one mix, make the assembler export stems and re-emit. (The WRAP path bakes one audio clip and CANNOT have separate lanes — so use pre-cut SEGMENTS whenever separate lanes are wanted, which is now the reel default.)
When something imports broken but a SIBLING clip works, DIFF their `<asset>`/`<format>`/`<asset-clip>` entries before re-trying any fix — that's how the black-clip root cause was finally found.

## Output + handoff (minimal — no finishing guidance, per scope)
- Write to `fcpxml/<Name>.fcpxml` (+ `<Name>_mix.m4a`). Name by cut: `Huacachina_full`, `Huacachina_flagship`, `Huacachina_reel`.
- Tell TJ **which file to import** (File → Import → XML) and which cut it is. Then stop — stabilization, end cards, color, export settings are his (or a future skill's), NOT this command's job.

## Non-negotiables
- **The cut must have passed `/video-review` first.** Don't conform a cut TJ hasn't approved through the internal review (junk frames, mid-sentence cuts, mix balance). If you derived/altered a reel here, re-run `/video-review` on it — the vertical crop + any captions are exactly what its safe-area check exists for. (`video-review`)
- **Correctness over features.** A frame-misaligned or offline-relinking FCPXML is worse than none.
- **Match the rendered cut.** The FCP timeline must open looking like the approved render — especially the vertical crop.
- **Version non-destructively — distinct named sets per cut** (`<Name>.fcpxml` + its EDL + stems, unique tags so nothing collides). Never overwrite a cut TJ might want back; a prior version should be re-emittable WITHOUT a re-render (Koh Samui's 8.7-min original was restored in ~40s of stream-copies because its EDL + stems kept distinct filenames, 2026-06-26).
- **When TJ says the audio/cut is wrong, verify the ARTIFACT FCP actually uses — don't insist it's fixed.** FCP rides the `.m4a`; transcribe THAT (not the `.wav`/mp4) when audio "won't update" (the stale-m4a intro bug). Look/listen at the thing, never the assumption. (`feedback_verify_visuals_not_metadata`)
- **Stay in your lane.** No creative re-cutting, no captions/thumbnails, no export babysitting.