davinci-resolve-mcp 2.73.1 → 2.74.0

package/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.74.0
+
+### Added
+
+- **`drp-format/set-framerate` — relabel a `.drp` timeline frame rate in place.**
+  `setTimelineFrameRate(drpInput, targetFps)` rewrites the timeline
+  `<FrameRate>` blob(s) to a new fps while leaving every clip's integer
+  Start/Duration/In/Out and every clip-level `<MediaFrameRate>` untouched — a
+  relabel, not a retime. Use it to fix a contaminated rate tag (e.g. an export
+  step that stamped 23.976 onto a 24.000 timeline whose frames are correct).
+  Offline-only by necessity: Resolve locks a timeline's frame rate once the
+  timeline exists, so an imported `.drp` can never be relabelled through
+  Resolve itself. `readTimelineFrameRates(drpInput)` reports the current
+  rate(s) without modifying anything. Both are exported from the `drp-format`
+  index; five node:test cases cover relabel, `MediaFrameRate` isolation,
+  idempotence, and input validation.
+
+### Fixed
+
+- Corrected a garbled doc comment in `drx-parameters/index.js`.
+
+## What's New in v2.73.2
+
+Two honesty fixes in the conform path, both found by running a real 83-minute
+Avid AAF turnover end to end. Neither adds tool surface; `detect_missing_media`
+gains two additive response fields.
+
+### Fixed
+
+- **`detect_missing_media` counted an unknown item as a present one.** A timeline
+  item with no media pool item has no file path and no offline marker, so it fell
+  through to `present` — absence of information reported as presence. An AAF
+  imported with `importSourceClips=false` yields 882 such items, and the probe
+  answered `present_count: 882, missing_count: 0` while every one of them returned
+  `None` from `GetMediaPoolItem()`. The payload contradicted itself: the diagnosis
+  already said `unique_media_pool_item_count: 0`.
+
+  Those items now report under `unlinked` / `unlinked_count` and never inflate
+  `present_count`. They are deliberately **not** folded into `missing`: those rows
+  drive relink plans keyed on `media_pool_item_id`, and there is no pool item here
+  to relink. When a timeline is entirely unlinked the diagnosis says so, instead of
+  "No offline media detected" — technically true and completely misleading.
+
+- **The "Resolve created no timeline" remediation named the wrong fix.** It advised
+  converting the file to FCP7 XML / FCPXML. The far more common cause is that
+  `importSourceClips` defaults to `True`, so Resolve tries to pull in the sequence's
+  source clips and fails the entire import when those paths do not resolve — the
+  normal state of a turnover, whose paths belong to the offline editor.
+  `import_source_clips=false` lands the timeline offline and now leads the
+  remediation. Note `sourceClipsPath` does not rescue it: Resolve matches source
+  clips by the filenames recorded in the sequence, so an AAF referencing Avid MXF
+  finds nothing in a folder of differently-named finishing media.
+
 ## What's New in v2.73.1
 
 Packaging fix. The npm package shipped the AAF reader's Node half without its

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.73.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.74.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)

package/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.73.1"
+VERSION = "2.74.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.73.1",
+  "version": "2.74.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/vendor/drp-format/__tests__/set-framerate.test.js

@@ -0,0 +1,62 @@
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const JSZip = require('jszip');
+const { setTimelineFrameRate, readTimelineFrameRates } = require('../set-framerate');
+
+// A real Resolve export with one media clip — carries a timeline <FrameRate> blob
+// and a clip-level <MediaFrameRate> that a relabel must NOT touch.
+const TEMPLATE = path.join(__dirname, '..', 'templates', 'media-clip-h264.drp');
+
+async function countTag(buf, tag) {
+  const zip = await JSZip.loadAsync(buf);
+  let n = 0;
+  for (const name of Object.keys(zip.files)) {
+    if (!name.endsWith('.xml')) continue;
+    const xml = await zip.files[name].async('string');
+    n += (xml.match(new RegExp(`<${tag}>[0-9a-fA-F]{32}</${tag}>`, 'g')) || []).length;
+  }
+  return n;
+}
+
+test('readTimelineFrameRates reports the template timeline rate', async () => {
+  const rates = await readTimelineFrameRates(TEMPLATE);
+  assert.ok(rates.length > 0, 'expected at least one timeline FrameRate blob');
+  for (const r of rates) {
+    assert.ok(Number.isFinite(r.fps) && r.fps > 0, `decoded fps should be positive, got ${r.fps}`);
+  }
+});
+
+test('setTimelineFrameRate relabels every timeline FrameRate blob', async () => {
+  const before = await readTimelineFrameRates(TEMPLATE);
+  const target = Math.abs(before[0].fps - 25) < 1e-6 ? 24 : 25;
+
+  const { buffer, changes, timelineFrameRates } = await setTimelineFrameRate(TEMPLATE, target);
+  assert.ok(changes.length > 0, 'a real rate change must be recorded');
+  assert.deepStrictEqual(timelineFrameRates, before.map(r => r.fps));
+
+  const after = await readTimelineFrameRates(buffer);
+  assert.strictEqual(after.length, before.length, 'blob count must not change');
+  for (const r of after) assert.ok(Math.abs(r.fps - target) < 1e-6, `expected ${target}, got ${r.fps}`);
+});
+
+test('relabel leaves clip-level MediaFrameRate blobs untouched', async () => {
+  const original = fs.readFileSync(TEMPLATE);
+  const mediaBefore = await countTag(original, 'MediaFrameRate');
+  const { buffer } = await setTimelineFrameRate(original, 30);
+  const mediaAfter = await countTag(buffer, 'MediaFrameRate');
+  assert.strictEqual(mediaAfter, mediaBefore, 'MediaFrameRate must be left alone');
+});
+
+test('relabel is idempotent: same target twice yields no recorded change the second time', async () => {
+  const first = await setTimelineFrameRate(TEMPLATE, 25);
+  const second = await setTimelineFrameRate(first.buffer, 25);
+  assert.strictEqual(second.changes.length, 0, 'second pass at same fps records no change');
+});
+
+test('rejects invalid targets', async () => {
+  await assert.rejects(() => setTimelineFrameRate(TEMPLATE, 0), /positive finite number/);
+  await assert.rejects(() => setTimelineFrameRate(TEMPLATE, NaN), /positive finite number/);
+  await assert.rejects(() => setTimelineFrameRate(TEMPLATE, 'fast'), /positive finite number/);
+});

package/resolve-advanced/vendor/drp-format/index.js

@@ -153,6 +153,10 @@ module.exports = {
   // Author a project with one media clip referencing an arbitrary h264 file, from scratch [P8].
   addMediaClip: require('./author-project').addMediaClip,
 
+  // Relabel the timeline frame rate tag in place (not a retime — frame counts untouched).
+  setTimelineFrameRate: require('./set-framerate').setTimelineFrameRate,
+  readTimelineFrameRates: require('./set-framerate').readTimelineFrameRates,
+
   // Offline media relink — repoint media to new paths in the Media Pool blobs (no Resolve).
   relinkMedia: require('./relink-media').relinkMedia,
   // Relink + fix cached specs (resolution/frames/fps) for a differently-formatted file [P8].

package/resolve-advanced/vendor/drp-format/set-framerate.js

@@ -0,0 +1,97 @@
+/**
+ * set-framerate — **relabel** a Resolve `.drp` timeline frame rate in place.
+ *
+ * This is a *relabel*, not a retime: it rewrites the timeline `FrameRate` blob(s) to a new fps
+ * while leaving every clip's integer Start/Duration/In/Out and every `MediaFrameRate` (clip
+ * *source* rate) untouched. The frame count is identical; only the rate the timeline is
+ * interpreted at changes. Use this to fix a contaminated tag — e.g. a caption/export step that
+ * stamped 23.976 onto a 24.000 timeline whose frames are actually correct.
+ *
+ * Why offline: Resolve locks a timeline's frame rate once the timeline exists (writable only when
+ * a project has 0 timelines), so an imported `.drp` can never be relabelled *through* Resolve —
+ * only retimed.
+ *
+ * Where fps lives in a real DRP (verified against templates/media-clip-h264.drp, a Resolve export):
+ *   - timeline rate  → `<FrameRate>[double fps][double 0]</FrameRate>` in MediaPool/<folder>/MpFolder.xml
+ *   - clip source    → `<MediaFrameRate>…</MediaFrameRate>` (LEFT ALONE — different tag)
+ *   - project.xml / Gallery.xml carry no fps.
+ * The exact tag `<FrameRate>` never substring-matches `<MediaFrameRate>` (char before "FrameRate"
+ * is "a", not "<"), so a `<FrameRate>`-scoped rewrite is inherently clip-safe.
+ *
+ * @module drp-format/set-framerate
+ */
+
+const fs = require('node:fs');
+const JSZip = require('jszip');
+const { decodeRateBlob, encodeRateBlob } = require('./media-blobs');
+
+// Exact timeline FrameRate blob element. `[^]` (not `.`) so a stray newline can't break the match.
+const FRAMERATE_BLOB_RE = /<FrameRate>([0-9a-fA-F]{32})<\/FrameRate>/g;
+
+async function loadZip(drpInput) {
+  const buf = Buffer.isBuffer(drpInput) ? drpInput : await fs.promises.readFile(drpInput);
+  return JSZip.loadAsync(buf);
+}
+
+/**
+ * Relabel every timeline FrameRate blob in a `.drp` to `targetFps`.
+ *
+ * @param {string|Buffer} drpInput  Path to a `.drp` (or its Buffer).
+ * @param {number} targetFps        New timeline fps (e.g. 24, 23.976, 25).
+ * @returns {Promise<{ buffer: Buffer, changes: Array<{entry:string, from:number, to:number}>, timelineFrameRates:number[] }>}
+ * @throws if the target is not a finite positive number or no timeline FrameRate blob is found.
+ */
+async function setTimelineFrameRate(drpInput, targetFps) {
+  if (typeof targetFps !== 'number' || !Number.isFinite(targetFps) || targetFps <= 0) {
+    throw new Error(`set-framerate: targetFps must be a positive finite number, got ${targetFps}`);
+  }
+  const zip = await loadZip(drpInput);
+  const newHex = encodeRateBlob(targetFps); // [double fps][double 0], 32 hex chars
+
+  const entries = [];
+  zip.forEach((p, e) => { if (!e.dir && /\.xml$/i.test(p)) entries.push(p); });
+
+  const changes = [];
+  const seenRates = [];
+  for (const entry of entries) {
+    const xml = await zip.file(entry).async('string');
+    if (!FRAMERATE_BLOB_RE.test(xml)) continue;
+    FRAMERATE_BLOB_RE.lastIndex = 0;
+    const next = xml.replace(FRAMERATE_BLOB_RE, (_m, hex) => {
+      const from = decodeRateBlob(hex);
+      if (from != null) seenRates.push(from);
+      // Round-trip guard: only record a real change; still rewrite so the blob's
+      // trailing 8 bytes are canonicalised to zero.
+      if (from == null || Math.abs(from - targetFps) > 1e-6) {
+        changes.push({ entry, from: from ?? NaN, to: targetFps });
+      }
+      return `<FrameRate>${newHex}</FrameRate>`;
+    });
+    zip.file(entry, next);
+  }
+
+  if (seenRates.length === 0) {
+    throw new Error('set-framerate: no timeline <FrameRate> blob found — not a .drp with a timeline?');
+  }
+
+  const buffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+  return { buffer, changes, timelineFrameRates: seenRates };
+}
+
+/** Read-only: report the timeline frame rate(s) in a `.drp` without modifying it. */
+async function readTimelineFrameRates(drpInput) {
+  const zip = await loadZip(drpInput);
+  const rates = [];
+  const entries = [];
+  zip.forEach((p, e) => { if (!e.dir && /\.xml$/i.test(p)) entries.push(p); });
+  for (const entry of entries) {
+    const xml = await zip.file(entry).async('string');
+    for (const m of xml.matchAll(FRAMERATE_BLOB_RE)) {
+      const fps = decodeRateBlob(m[1]);
+      if (fps != null) rates.push({ entry, fps });
+    }
+  }
+  return rates;
+}
+
+module.exports = { setTimelineFrameRate, readTimelineFrameRates };

package/resolve-advanced/vendor/drx-parameters/index.js

@@ -10,7 +10,7 @@
  * - Protobuf encoding/decoding
  * - Validation and correction
  *
- * Used across the The project platform for consistent DRX handling.
+ * Used across the platform for consistent DRX handling.
  *
  * @module drx-parameters
  *

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.73.1"
+VERSION = "2.74.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 341-tool granular server instead
 """
 
-VERSION = "2.73.1"
+VERSION = "2.74.0"
 
 import base64
 import os
@@ -6048,9 +6048,23 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
                     imported = t
         if not imported:
             if is_binary:
+                # importSourceClips defaults to True, so Resolve tries to pull in the
+                # sequence's source clips during import — and when those paths do not
+                # resolve it fails the whole import rather than creating an offline
+                # timeline. That is the normal case for a turnover (the paths belong
+                # to the offline editor), so it is by far the most common reason a
+                # valid AAF "creates no timeline", and the flag fixes it. Naming a
+                # format conversion first sent people down a much longer road than
+                # the one-flag retry that actually works. Note sourceClipsPath does
+                # NOT rescue it: Resolve matches source clips by the filenames
+                # recorded in the sequence, so an AAF referencing Avid MXF finds
+                # nothing in a folder of differently-named finishing media.
                 remediation = (
-                    f"Resolve created no timeline from this {ext}. Verify it exports/opens in "
-                    "Resolve directly, or convert to FCP7 XML / FCPXML upstream and import that."
+                    f"Resolve created no timeline from this {ext}. Most often the source clips "
+                    "could not be resolved: retry with import_source_clips=false to land the "
+                    "timeline offline, then add the media to the media pool and relink. "
+                    "Otherwise verify it exports/opens in Resolve directly, or convert to "
+                    "FCP7 XML / FCPXML upstream and import that."
                 )
             elif sanitize:
                 remediation = None
@@ -6583,6 +6597,7 @@ def _missing_media_diagnosis(missing_rows: List[Dict[str, Any]]) -> Dict[str, An
 def _detect_missing_media_from_snapshot(snapshot: Dict[str, Any]):
     missing = []
     present = []
+    unlinked = []
     for track_type, type_payload in (snapshot.get("tracks") or {}).items():
         for track in type_payload.get("tracks", []):
             for item in track.get("items", []):
@@ -6603,13 +6618,40 @@ def _detect_missing_media_from_snapshot(snapshot: Dict[str, Any]):
                 }
                 if is_missing:
                     missing.append(row)
+                elif not file_path and not item.get("media_pool_item_id"):
+                    # No path AND no media pool item: the timeline item has nothing
+                    # behind it at all. It is not "present" — we simply know nothing
+                    # about it — and counting it as present is how an entirely
+                    # offline timeline reported full coverage (an AAF imported with
+                    # importSourceClips=false yields 882 such items and used to
+                    # report present_count 882 / missing_count 0, while every one of
+                    # them returned None from GetMediaPoolItem()).
+                    #
+                    # Kept out of `missing` deliberately: those rows drive relink
+                    # plans keyed on media_pool_item_id, and there is no pool item
+                    # here to relink. This is a third state, so it gets its own.
+                    unlinked.append(row)
                 else:
                     present.append(row)
     diagnosis = _missing_media_diagnosis(missing)
+    if unlinked and not missing:
+        # Nothing to relink, so the generic "no offline media detected" advice
+        # would send the caller away satisfied from a timeline with no media.
+        diagnosis = dict(diagnosis)
+        diagnosis["primary_cause"] = "no_media_pool_items"
+        diagnosis["recommended_next_step"] = (
+            f"{len(unlinked)} timeline items have no media pool item at all — the timeline was "
+            "imported without its source clips. Add the media to the media pool, then relink; "
+            "there is nothing here for a path-based relink to act on."
+        )
     return {
         "missing": missing,
         "present_count": len(present),
         "missing_count": len(missing),
+        # Timeline items with neither a file path nor a media pool item. Never
+        # folded into present_count — see above.
+        "unlinked": unlinked,
+        "unlinked_count": len(unlinked),
         "diagnosis": diagnosis,
     }