Resolve Conform

Resolve Conform / Interchange

Bridges online-editing / finishing craft to this repo's tools.

• Craft / finishing — the global online-editor skill (conform, relink, finishing philosophy in Resolve and Flame). Use for how a finishing editor thinks, not tool mechanics.
• Live tool mechanics — docs/kernels/timeline-conform-interchange-kernel.md (the timeline conform/interchange boundary).
• Offline conform engine — resolve-advanced/README.md → conform, color_trace, offline_ref, editorial, drt, project_db.

No Resolve? The work does not have to stop

timeline author_offline writes an importable timeline (drt / otio / edl) from a file-path clip plan without any connection, and every not-connected error now carries an offline_alternative block pointing at it.

Say plainly what happened: the live operation failed and a file was written — the timeline is not in a project until someone imports it. Read the warnings back too. media_tc_origin_assumed is the one that matters: OTIO source frames are timecode-absolute, and an event without media_start_tc_frame imports as an empty timeline with no error at all.

Default to drt (Resolve-native, project version 17 / Resolve 21.0 — older builds need drt downgrade). Pick otio when the plan carries retimes; a .drt flattens them.

Two servers

What this build cannot do (check before you offer it)

The scripting API changes per patch release, so "Resolve 21" is not a usable label. Read resolve_control get_version → build.unavailable_on_this_build before offering a gated surface; check_version_support asks about one named symbol. Gated on the relink/media side this domain leans on:

An empty unavailable_on_this_build means nothing recorded is missing, not that everything exists — most of the API has never been version-bisected. A symbol with no gate returns unknown, which means probe it. Probe with name in dir(obj), never bare hasattr: on a Resolve object hasattr returns True for every name, real or invented, so it can only say yes.

The offline conform / drt / project_db routes are not gated this way — they operate on files, so a missing live surface is a reason to reach for them, not a dead end.

Live conform essentials

• Inspect before touching: probe_timeline_structure, detect_gaps_overlaps, source_range_report, conform_boundary_report.
• Interchange: export_timeline_checked / import_timeline_checked (temp-guarded). drt is the only lossless project-native round-trip; EDL/FCPXML drop Resolve-specific relationships.
• XML import via the scripting API goes offline (missing-media/generators abort the import). Use import_timeline_checked with media sanitize (FCP7/FCPXML) so the API imports with links intact, then exact-path relink. A running MCP server must be restarted to pick up the sanitize fix.
• Missing media: detect_missing_media → build_relink_plan (read-only, bounded; skips broad scans when the source volume is unmounted) → execute only via media_pool.safe_relink with approved paths.

Offline conform engine (conform actions)

The offline engine QCs a conform with frame-oracle math, not filename matching — it catches a clip that relinked to the wrong-but-similarly-named source. It also does:

• Reverse/retimed subclip repair — reversed source_start = masterFrames − 1 − endoffset (live-validated); DB-level repair.
• Sequence lineage store + diff — hashed timeline snapshots, diff, rollback.
• Per-cut frame QC — oracle-frame vs reference-render compare (scale-corrected; red/yellow/cyan verdicts), the standard finishing QC. Each cut is judged at the first frame CLEAR of its transition windows (inside one the reference is a blend, or black for a fade); Resolve's own FCP7 export ingests with -1 edges resolved to junctions and its absent pproTicksIn tolerated (<in> is the source frame).
• Reference-render compare — build a REF_OFFLINE verdict when a burn-in-free reference exists.

Carrying grades across a re-conform

Native ColorTrace keys on timecode/name/order inside one project and gives up on renames, reorders, retimes and stringouts. The MCP path is two calls:

1. Advanced server, no Resolve needed — color_trace plan with sourceProjectName/sourceTimeline (graded) and targetProjectName/targetTimeline (the new cut), plus emitDir under the system temp dir. Projects in a Postgres / network / cloud library have no Project.db to open: export each with project_manager safe_project_export (allow_non_mcp_name: true, works without loading the project) and pass sourceDrp / targetDrp instead. It matches on media identity (pool id / file path / reel / file name + source-range overlap — a stringout's graded sections resolve by overlap) and only falls back to names. Read summary.byMethod, ambiguous, and each match's confidence; it writes a lossless .drx per graded match and returns planPath.
2. Live server — open the target project and timeline, then timeline_item_color apply_trace_plan with plan_path and dry_run: true to get the resolution table (every entry is apply or skip + reason). Re-call without dry_run for a confirm_token, then with it to apply. version_name adds a local version per clip first so the previous grade survives; the timeline is archived to the Archive bin before anything is replaced.

Say plainly what did not resolve: live_item_not_found, ambiguous_live_item and below_min_confidence entries are reported, never guessed. For a single look, the resolve-color skill's drx grade_transfer is the lighter tool. For "what changed between cuts," use editorial.turnover_changelist (see resolve-edit).

Offline-reference clips

Offline-ref clips have no scripting API but do live inside .drp/.drt as <OfflineClip> entries — patch via offline_ref (plain-XML/DB path), not the live server.

Gotchas that bite

• .drt version. For DaVinci Resolve 19.1.3, set DbPrjVer 17 → 16 when authoring a .drt or the import can fail.
• project_db patches require the project CLOSED in Resolve plus iConfirmProjectClosed:true; every write auto-backs-up and read-back verifies. Resolve caches open projects in memory — after patching, fully QUIT and relaunch Resolve or the change is invisible.
• AAF is an honest refuse in editorial.parse_interchange, not a silent empty result.
• Optional native deps gate some actions (better-sqlite3 for lineage/reverse/DB, sharp/ffmpeg for frame compare) — call the advanced capabilities tool.

Source-media safety (AGENTS.md)

Relink plans are read-only until you execute them; never relink, replace, or create derivatives of source media without explicit approval. Preserve the chain from camera original to final delivery.