davinci-resolve-mcp 2.73.2 → 2.74.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 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

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