davinci-resolve-mcp 2.73.2 → 2.75.0

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 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.75.0
+
+The offline AAF reader now recovers retime ratios instead of only flagging them.
+
+### Added
+
+- **Motion Control speed recovery.** OperationGroup parameters are read: a
+  constant `SpeedRatio` emits `speedRatio` (play rate) and corrects `speed`, so
+  consumers reading only `speed` are no longer told 100 for a 175% clip. Variable
+  timewarps (multi-point speed maps) report `speedVarying: true` rather than a
+  fabricated number — the reader's honest-refuse contract extends to speeds.
+  Note the stored AAF rational is RECORD/SOURCE (Edit Protocol output-over-input),
+  the inverse of play rate; the reader emits play rate, verified against the
+  length identity (sourceLen = recordLen / |ratio|) and Avid's own speed maps.
+
+### Fixed
+
+- **Motion Control events inflated `recOut`.** Record advancement used the inner
+  source clip's length instead of the OperationGroup's declared record length, so
+  fast-motion clips claimed more record time than they occupy (and slow motion
+  claimed less). On a real 83-minute turnover this produced 40 spurious record
+  overlaps; with the declared length driving advancement, one remains — a
+  two-input blend genuinely sharing its record span.
+
+## 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

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.73.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.75.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.2"
+VERSION = "2.75.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.2",
+  "version": "2.75.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/server/aaf_probe.py

@@ -19,6 +19,16 @@ trusting, so the Node server shells out to this helper, which uses the pure-Pyth
 Normalized event shape mirrors resolve-advanced/server/editorial.mjs `evt()`:
     { index, track, source, srcIn, srcOut, recIn, recOut, speed, reverse, transition, fps }
 
+Retime (motion-effect) events additionally carry `"effect"` and, when the ratio is
+recoverable from the OperationGroup's parameters (see _retime_fields):
+  * constant ratio  → `"speedRatio"`: play-rate float (1.75 = 175%), `"speed"`:
+                      round(playRate*100), `"reverse"`: true for backwards play.
+  * variable speed  → `"speedVarying": true` and speed stays 100 — a timewarp has
+                      no single honest number, so none is fabricated.
+  * unrecoverable   → the flag alone, speed stays 100 (unchanged old contract).
+For retimes, srcIn/srcOut are the SOURCE-side range while recIn/recOut span the
+OperationGroup's DECLARED (record) length — they differ by the ratio.
+
 Honest-refuse discipline (no fake parses):
   * exit 3  → pyaaf2 not installed        (stderr: AAF_PROBE_NO_PYAAF2)
   * exit 4  → file unreadable / not an AAF (stderr: AAF_PROBE_UNREADABLE: <detail>)
@@ -40,6 +50,8 @@ Segment model (Avid Media Composer picture turnovers):
   * Sequence     — ordered `.components`, laid end to end.
   * OperationGroup — effect wrapper. Its `.segments` are the effect INPUTS, and the
                    primary input is usually a nested Sequence (not a bare SourceClip).
+                   Its `.parameters` carry the retime ratio for motion effects, and
+                   its own declared length is the RECORD duration of the effect.
   * Selector     — an enabled/disabled layer variant; the live one is `Selected`.
   * ScopeReference — "show the NestedScope layer beneath me": real record time, no
                    clip of this layer's own. Treated as a gap, like Filler.
@@ -224,6 +236,123 @@ def _operation_name(comp):
         return ""
 
 
+# ── Retime (Motion Control) parameter recovery ─────────────────────────────────
+# Avid stores a retime's ratio on the OperationGroup's PARAMETERS. Verified against
+# real Media Composer turnovers by cross-checking the inner SourceClip length vs the
+# group's declared record length AND the PARAM_SPEED_MAP_U control-point values:
+#   * "SpeedRatio" (AAF Edit Protocol ParameterDef, a ConstantValue rational) is the
+#     RECORD/SOURCE length ratio — i.e. the INVERSE of the play rate. A 175% fast
+#     motion is stored as 4/7 (100 record frames consume 175 source frames); reverse
+#     play is a NEGATIVE rational (-1/1 = 100% backwards). Mixed-rate pulldown
+#     wrappers appear as 1000/1001.
+#   * "PARAM_SPEED_MAP_U" (Avid, a VaryingValue) has control points whose VALUES are
+#     play-rate scalars directly (1.75 = 175%, negative = reverse). More than one
+#     distinct value means the speed VARIES across the clip.
+#   * "PARAM_SPEED_RATIO_U" (Avid, a ConstantValue) belongs to the same *_U family
+#     as the speed map, so its value is a play-rate scalar, not a SpeedRatio.
+
+# The AAF Edit Protocol parameter-definition id for SpeedRatio, so a file whose
+# dictionary lost the human name still resolves.
+_SPEED_RATIO_AUID = "72559a80-24d7-11d3-8a50-0050040ef7d2"
+
+
+def _op_parameters(op_group):
+    """An OperationGroup's Parameter objects; [] when absent or unreadable."""
+    try:
+        prop = getattr(op_group, "parameters", None)
+        if prop is None:
+            return []
+        value = getattr(prop, "value", None)
+        return list(value if value is not None else prop)
+    except Exception:
+        return []
+
+
+def _param_name(param):
+    try:
+        return str(param.name or "")
+    except Exception:
+        return ""
+
+
+def _param_is(param, name, auid=None):
+    if _param_name(param) == name:
+        return True
+    if auid:
+        try:
+            return str(param.auid).lower() == auid
+        except Exception:
+            return False
+    return False
+
+
+def _pointlist_values(varying):
+    """Control-point VALUES of a VaryingValue's point list, or None if unreadable."""
+    points = getattr(varying, "pointlist", None)
+    if points is None:
+        return None
+    inner = getattr(points, "value", None)
+    if inner is not None:
+        points = inner
+    try:
+        return [float(p.value) for p in points]
+    except Exception:
+        return None
+
+
+def _retime_fields(op_group):
+    """Extra event fields recovered from a retime OperationGroup's parameters.
+
+    Returns one of:
+      {"speedRatio": <play-rate float>, "speed": <int %>, "reverse": <bool>}
+      {"speedVarying": True}  — a variable-speed timewarp; no single honest number
+      {}                      — nothing recoverable (flag-only, speed stays 100)
+    """
+    play = None
+    speed_map = None
+    for param in _op_parameters(op_group):
+        cls = type(param).__name__
+        if cls == "VaryingValue":
+            if _param_name(param) == "PARAM_SPEED_MAP_U":
+                speed_map = param
+            continue
+        if cls != "ConstantValue":
+            continue
+        if _param_is(param, "SpeedRatio", _SPEED_RATIO_AUID):
+            try:
+                value = param.value
+                num = int(value.numerator)
+                den = int(value.denominator)
+            except Exception:
+                continue
+            if num:
+                play = den / num  # stored record/source → play rate is the inverse
+        elif _param_name(param) == "PARAM_SPEED_RATIO_U" and play is None:
+            try:
+                value = float(param.value)
+            except Exception:
+                continue
+            if value:
+                play = value  # *_U family stores the play rate directly
+    if speed_map is not None:
+        values = _pointlist_values(speed_map)
+        if values is None:
+            # A speed map we cannot read: we can neither call the speed constant
+            # nor prove it varies — recover nothing rather than guess.
+            return {}
+        if len(set(values)) > 1:
+            return {"speedVarying": True}
+        if play is None and values and values[0]:
+            play = values[0]  # a flat map's single value IS the constant play rate
+    if not play:
+        return {}
+    return {
+        "speedRatio": round(abs(play), 6),
+        "speed": int(round(abs(play) * 100)),
+        "reverse": play < 0,
+    }
+
+
 def _walk_segment(segment, *, track, fps, rec, state, depth=0, transition=None):
     """
     Emit normalized events for ONE segment placed at record position `rec`.
@@ -289,10 +418,24 @@ def _walk_segment(segment, *, track, fps, rec, state, depth=0, transition=None):
             _walk_segment(inp, track=track, fps=fps, rec=rec, state=state, depth=depth + 1, transition=transition)
         op_name = _operation_name(segment)
         if op_name and ("speed" in op_name.lower() or "motion" in op_name.lower()):
-            # We can detect that a retime is present but not reliably its ratio
-            # offline; flag it honestly rather than fake a speed number.
+            # A retime. Its ratio is recoverable from the group's PARAMETERS (see
+            # _retime_fields): a constant ratio updates speed/speedRatio so
+            # consumers reading only `speed` are no longer told 100; a variable
+            # timewarp is reported as speedVarying: true; an unreadable one keeps
+            # the old flag-only contract. A number is never fabricated.
+            extra = _retime_fields(segment)
             for ev in state["events"][before:]:
                 ev["effect"] = op_name
+                ev.update(extra)
+                # The group's DECLARED length is the RECORD duration; the inner
+                # SourceClip's length is the SOURCE-side range — under a retime
+                # they differ by the ratio, so an event whose recOut was advanced
+                # by the source length inflates (fast motion) or undershoots
+                # (slow motion) its real record span. The container declared-
+                # length rule (this file's convention for rec advancement)
+                # applies to the events too.
+                if declared > 0:
+                    ev["recOut"] = max(ev["recIn"], rec + declared)
         return declared
 
     # Unknown component — advance by its declared length, don't fake an event, and

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.2"
+VERSION = "2.75.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.2"
+VERSION = "2.75.0"
 
 import base64
 import os