samuelgursky / 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 confirmtoken, then with it to apply. `versionname`
   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.