davinci-resolve-mcp 2.121.0 → 2.123.0

package/docs/guides/native-drt-authoring.md

@@ -50,10 +50,13 @@ window. `render.verify_output` covers the container-level checks.
 | Custom start timecode | `spec.startFrame` / `preserveStartTimecode` | v2.117 |
 | Timeline markers | `spec.markers` (16 colors, notes, durations, customData) | v2.118 |
 | Turnover markers | EDL `* LOC:` locators + OTIO markers → authored | v2.119 |
+| TC-bearing sources (AAF route) | native clip capture (`MediaStartTime`), channel-leg merge | v2.120–2.122 |
 | Fusion titles | `elements: [{type:'title', text}]` — **21-gen hosts only** | v2.108 |
 
 `assemble_from_interchange` drives the same engine from an EDL / OTIO /
-FCP7-XML / AAF plus a `sourceMap`, and returns an honesty ledger
+FCP7-XML / AAF plus a `sourceMap` — all four formats are route-proven
+end-to-end (parse → assemble → import → measured frames and RMS) — and
+returns an honesty ledger
 (`authoredTransitions`, `droppedTransitions` with reasons, `authoredRetimes`,
 `flattenedRetimes`, `authoredAudioEvents`, `upperTrackCutsVideoOnly`).
 
@@ -98,7 +101,10 @@ Everything else stays in `droppedTransitions` with the reason.
 ## Verification checklist for a delivered .drt
 
 1. `timeline.import_timeline_checked` — expect `linked == total` for media
-   (generators legitimately count as offline).
+   (generators legitimately count as offline). For `.drt`/`.drp` it also
+   cross-checks the files items ACTUALLY link against the archive's
+   `<MediaFilePath>` set and warns on a coarse-identity cross-link
+   (`cross_link_warning`) — `linked == total` alone cannot see one.
 2. Render a probe range; check frame luma at cut boundaries, dissolve
    midpoints (expect the blend average), and retime windows.
 3. For audio: RMS per window (silence = -inf is a failed placement).

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 34 missing capabilities, 44 bugs / unreliable behaviors.
+**Totals:** 35 missing capabilities, 45 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -221,6 +221,13 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** To author a non-default start TC offline, patch MediaExtents (drt.assemble spec.startFrame does this) and keep clip Start frames >= the new origin - clips before it are silently dropped on import. For conform, assemble_from_interchange preserveStartTimecode=true anchors at the turnover's real first record frame instead of 01:00:00:00.
 - **Tags:** timecode, drt, import
 
+### Embedded source timecode lives in the clip's MediaStartTime (SECONDS); AAF duplicates audio per channel
+
+- **Object:** `Sm2TiVideoClip.MediaStartTime / AAF export`
+- **Behavior:** Two conform-ingest measurements (2026-08-30, rich Resolve 19 AAF export + its sources). (1) A source with embedded timecode is referenced by the timeline clip's <MediaStartTime> in SECONDS (01:00:00:00 -> 3600); a transplant clone keeping the template donor's 0 imports and reads back fine but the render fails with 'Full resolution media not found at 01:00:00:00'. (2) The AAF export carries one event per audio CHANNEL: every A-track event of a dual-mono clip arrives twice with identical ranges.
+- **Workaround / current handling:** capture_media_template harvests mediaStartTime and the native clip elements; drt.assemble clones the source's own captured clip per cut (render-verified: the TC-bearing source plays picture and audio, and the full AAF route renders frame-accurately). Re-capture templates for TC-bearing media. The assemble bridge merges identical audio channel legs (report.audioChannelLegsMerged) instead of refusing them as a same-track overlap.
+- **Tags:** timecode, aaf, audio, drt, silent-failure
+
 ### MediaPool.ImportMedia (current-folder destination only)
 
 - **Object:** `MediaPool`
@@ -533,6 +540,13 @@ values, or automation-hostile modal prompts.
 - **Reference:** [issue #171](https://github.com/samuelgursky/davinci-resolve-mcp/issues/171)
 - **Tags:** timeline, import, silent-failure, unreliable-return
 
+### Timeline import MERGES pool media by a coarse identity - similar files can silently cross-link
+
+- **Object:** `ImportTimelineFromFile / media pool`
+- **Behavior:** When a .drt import lands in a project that already holds a media entry whose pool identity blob matches the incoming one, Resolve MERGES them and every clip relinks to the EXISTING media - silently. The identity is coarse: two different files (5.6MB vs 93KB, different names, mtimes 1s apart) had identity blobs byte-identical except internal uuids, and the second file's clips all played the first file's picture (readback showed the wrong clip NAME; measured E33/E34 on 19.1.3.7). Importing the same archive into a FRESH project materialized both files correctly - the merge only bites across imports.
+- **Workaround / current handling:** After importing an authored timeline into a non-empty project, verify per-item file paths (or render probe frames) before trusting the conform - linked==total cannot see a cross-link. Files generated in the same second are the risk class; distinct mtimes distinguish them.
+- **Tags:** import, media-pool, silent-failure, drt
+
 ### Audio tracks cannot be grown in an imported timeline; Fairlight strips live in the pool Sm2Sequence.FieldsBlob
 
 - **Object:** `Sm2TiTrack (audio) / FLStudioModelBA`

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.121.0"
+VERSION = "2.123.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.121.0",
+  "version": "2.123.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/vendor/drp-format/cut-media.js

@@ -78,12 +78,14 @@ async function cutSourceIntoClips(drpInput, opts = {}) {
     // mirror clones AUDIO even for plain video cuts, so the donor must be
     // chosen per track type, never per cut flavor (a video element in an
     // audio track aborts the whole import, measured E31e).
-    // NATIVE-DONOR PATH (live verification PENDING — a stuck Resolve modal
-    // ended the E31 session before any import of this path could be
-    // measured cleanly; only caches that carry videoClipElement /
-    // audioClipElement reach it, so ordinary captures keep the proven donor
-    // path). Donor clones from splitClipElements come <Element>-wrapped and
-    // Items concatenation depends on the wrapper.
+    // NATIVE-DONOR PATH — RENDER-VERIFIED on 19.1.3.7 (E36): a TC-bearing
+    // .mov source (embedded 01:00:00:00) renders picture AND audio through a
+    // cloned native clip, and the full AAF route (two sources, V2 stacking,
+    // merged audio legs) renders every window frame-accurately. Only caches
+    // that carry videoClipElement/audioClipElement reach this; ordinary
+    // captures keep the proven donor path. Donor clones from
+    // splitClipElements come <Element>-wrapped and Items concatenation
+    // depends on the wrapper.
     const native = kind === 'audio' ? cut.donorClipAudio : cut.donorClipVideo;
     let c = freshDbIds(native ? native.trim() : donor);
     c = setClipStart(c, cut.startFrame);

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.121.0"
+VERSION = "2.123.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.121.0"
+VERSION = "2.123.0"
 
 import base64
 import os
@@ -6966,6 +6966,49 @@ def _export_timeline_checked(tl, p: Dict[str, Any]):
     return _run_maybe_background("timeline.export_timeline_checked", p, _work)
 
 
+def _drt_expected_media_paths(path: str):
+    """Unique <MediaFilePath> values referenced by a .drt/.drp's timeline clips.
+
+    Feeds the cross-link check: Resolve merges pool media by a COARSE identity
+    across imports, so a clip can silently relink to a DIFFERENT pre-existing
+    file (measured: item readback even shows the wrong clip name). The archive
+    is the ground truth for which files the timeline meant.
+    """
+    import zipfile as _zf
+    paths = set()
+    try:
+        with _zf.ZipFile(path) as zf:
+            for n in zf.namelist():
+                if re.search(r"SeqContainer/.+\.xml$", n) or re.search(r"/SeqContainer\d*\.xml$", n):
+                    xml = zf.read(n).decode("utf-8", "replace")
+                    for m in re.finditer(r"<MediaFilePath>([^<]+)</MediaFilePath>", xml):
+                        paths.add(m.group(1))
+    except Exception:
+        return None
+    return paths or None
+
+
+def _timeline_cross_link_check(tl, expected_paths):
+    """Compare the media files a timeline ACTUALLY links against the expected set."""
+    actual = set()
+    for track_type in ("video", "audio"):
+        try:
+            count = int(tl.GetTrackCount(track_type) or 0)
+        except Exception:
+            count = 0
+        for i in range(1, count + 1):
+            for item in (tl.GetItemListInTrack(track_type, i) or []):
+                try:
+                    mpi = item.GetMediaPoolItem()
+                    fp = mpi.GetClipProperty("File Path") if mpi else None
+                    if fp:
+                        actual.add(str(fp))
+                except Exception:
+                    pass
+    missing = sorted(x for x in expected_paths if x not in actual)
+    return {"expected": sorted(expected_paths), "actual": sorted(actual), "missing": missing}
+
+
 def _timeline_media_coverage(tl) -> Dict[str, Any]:
     """Count how many timeline items are linked to a Media Pool Item vs. offline.
 
@@ -7427,6 +7470,20 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
             out["relink"] = relink_result
         if binary_relink_note:
             out["note"] = binary_relink_note
+        if ext in {".drt", ".drp"}:
+            expected_paths = _drt_expected_media_paths(path)
+            if expected_paths:
+                xcheck = _timeline_cross_link_check(imported, expected_paths)
+                if xcheck["missing"]:
+                    out["cross_link_warning"] = (
+                        "Media files this timeline references are NOT among the files its "
+                        f"items actually link to: {', '.join(xcheck['missing'])}. Resolve "
+                        "merges pool media by a coarse identity across imports, so clips "
+                        "can silently relink to a DIFFERENT pre-existing file (item names "
+                        "follow the wrong file too). Import into a fresh project, or "
+                        "render-probe before trusting this conform."
+                    )
+                    out["cross_link_check"] = xcheck
         if media["total"] and media["offline"]:
             msg = f"{media['offline']} of {media['total']} timeline items are offline (no linked media)."
             if is_binary:

package/src/utils/api_truth.py

@@ -1936,6 +1936,55 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["timecode", "drt", "import"],
         "submit": "missing",
     },
+    {
+        "symbol": "Timeline import MERGES pool media by a coarse identity - similar files can silently cross-link",
+        "object": "ImportTimelineFromFile / media pool",
+        "reality": "When a .drt import lands in a project that already "
+                   "holds a media entry whose pool identity blob matches "
+                   "the incoming one, Resolve MERGES them and every clip "
+                   "relinks to the EXISTING media - silently. The identity "
+                   "is coarse: two different files (5.6MB vs 93KB, "
+                   "different names, mtimes 1s apart) had identity blobs "
+                   "byte-identical except internal uuids, and the second "
+                   "file's clips all played the first file's picture "
+                   "(readback showed the wrong clip NAME; measured E33/E34 "
+                   "on 19.1.3.7). Importing the same archive into a FRESH "
+                   "project materialized both files correctly - the merge "
+                   "only bites across imports.",
+        "recommended": "After importing an authored timeline into a "
+                       "non-empty project, verify per-item file paths (or "
+                       "render probe frames) before trusting the conform - "
+                       "linked==total cannot see a cross-link. Files "
+                       "generated in the same second are the risk class; "
+                       "distinct mtimes distinguish them.",
+        "tags": ["import", "media-pool", "silent-failure", "drt"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "Embedded source timecode lives in the clip's MediaStartTime (SECONDS); AAF duplicates audio per channel",
+        "object": "Sm2TiVideoClip.MediaStartTime / AAF export",
+        "reality": "Two conform-ingest measurements (2026-08-30, rich "
+                   "Resolve 19 AAF export + its sources). (1) A source with "
+                   "embedded timecode is referenced by the timeline clip's "
+                   "<MediaStartTime> in SECONDS (01:00:00:00 -> 3600); a "
+                   "transplant clone keeping the template donor's 0 imports "
+                   "and reads back fine but the render fails with 'Full "
+                   "resolution media not found at 01:00:00:00'. (2) The AAF "
+                   "export carries one event per audio CHANNEL: every "
+                   "A-track event of a dual-mono clip arrives twice with "
+                   "identical ranges.",
+        "recommended": "capture_media_template harvests mediaStartTime and "
+                       "the native clip elements; drt.assemble clones the "
+                       "source's own captured clip per cut (render-verified: "
+                       "the TC-bearing source plays picture and audio, and "
+                       "the full AAF route renders frame-accurately). "
+                       "Re-capture templates for TC-bearing media. The "
+                       "assemble bridge merges identical audio channel legs "
+                       "(report.audioChannelLegsMerged) instead of refusing "
+                       "them as a same-track overlap.",
+        "tags": ["timecode", "aaf", "audio", "drt", "silent-failure"],
+        "submit": "missing",
+    },
     {
         "symbol": "Audio tracks cannot be grown in an imported timeline; Fairlight strips live in the pool Sm2Sequence.FieldsBlob",
         "object": "Sm2TiTrack (audio) / FLStudioModelBA",