NLE Round Trip (Gate 1, option 3)

Read this when the human wants to fine-tune the cut in Final Cut Pro or DaVinci Resolve rather than describe edits in conversation. Offer it whenever feedback turns granular ("nudge that cut a few frames") — frame-level trimming is faster in an NLE than through a chat loop.

Two paths

FCPXML (below) is portable: no Resolve running, no Studio licence, works on another machine, opens in Final Cut too. It is the default.

Direct skips the export/import step entirely when Resolve Studio is open:

python3 scripts/resolve_bridge.py status
python3 scripts/resolve_bridge.py push plan/cut_plan.json --timeline reel_v1 \
    --project reel_work --width 1080 --height 1920
# ... the human edits in Resolve ...
python3 scripts/resolve_bridge.py pull --out plan/cut_plan.json \
    --base-plan plan/cut_plan.json

Pass --width/--height, and --fps when the plan is not on the 30fps mezzanine grid. A fresh Resolve project opens at 1920x1080 and 24fps, and a plan converted on the wrong rate mis-times every segment with no error. push sets the rate before creating anything — Resolve refuses to change it once a project holds a timeline — and refuses to continue on a mismatch.

Segments are zoomed to COVER the frame. normalize_clips.py --no-crop leaves the mezzanine wider than the target so render_reel.py --pan has pixels to reframe with (measured 3414x1920 on a real project), and Resolve's only scriptable mismatch behaviour is scaleToFit, which pillarboxes that into a stripe. Per-item ZoomX/ZoomY fixes it; a clip already at the target aspect is left alone.

Requires Studio — Blackmagic gates external scripting to it, and the free edition refuses a foreign process whatever the preference says. Set Preferences > General > External scripting using = Local. status reports which precondition failed rather than hanging.

--base-plan restores the clip PATHS (Resolve returns bare names) and carries music / bpm / music_start across, none of which live on a timeline.

Round-tripped a real 16-segment plan: clips, order and music preserved, worst drift 13ms — under one frame at 30fps.

Do not render in Resolve. The grade and the master belong to render_reel.py; two renderers over one timeline is how the approval gates stop meaning anything. Picture decisions round-trip. The look does not.

Hand the timeline over

python3 scripts/export_timeline.py plan/cut_plan.json --out plan/reel.fcpxml

Opens in Final Cut Pro (File > Import > XML) and DaVinci Resolve (File > Import Timeline) with every clip pre-placed at the right source timecode, phase notes as clip names, and the music on its own audio lane. Defaults to fcpxml v1.10; Resolve rejects newer versions, so pass --fcpxml-version 1.9 for Resolve 17. Verified end to end against DaVinci Resolve 21.

Times are quantized to the 30fps mezzanine grid cumulatively, so drift never reaches half a frame, whatever the cut count before it. A segment asking for frames past the end of its source has its in-point pulled back to fit, and the export names each one it moved — that shifts the cut, so refit the plan rather than letting the export paper over it:

python3 scripts/audit_plan.py plan/cut_plan.json --out work/plan_audit.png

It reports overruns before the picture is drawn. build_cut_plan.py refits automatically on a re-plan; a hand-edited plan needs the in-point or duration shortened by hand.

Then stop

The pipeline is paused while the human edits.

python3 scripts/pipeline.py gate 1 nle-wait

That snapshots the plan's mtime, and status alarms if anything touches cut_plan.json during the wait. Note it in project.md. Do not render, re-plan, or touch cut_plan.json in the meantime — their edit would be overwritten.

Tell them how to hand the result back: export fcpxml from the NLE — from Resolve choose v1.9 or v1.10; from FCP either a .fcpxml or a .fcpxmld bundle works.

Bring it back

python3 scripts/import_timeline.py plan/reel_edited.fcpxml \
    --out plan/cut_plan.json --base-plan plan/cut_plan.json

Only cuts survive the round trip — clip order, in-points, durations, music offset. NLE-side effects, transitions, titles, and retimes are ignored; the importer warns, and those warnings go to the user so they know what did not make it. Grading stays in the render step. Timeline gaps are dropped with a warning, since the renderer butts segments together.

After import: pipeline.py gate 1 reopen, re-render the preview, QC, and return to Gate 1 for a final confirm.