davinci-resolve-mcp 4.16.0 → 4.17.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 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 v4.17.0 — Power windows for Resolve 21
+
+### Added
+
+- **`drx generate` takes `resolveVersion`** (#328, thanks @hpaul). A major
+  number (`21`) or a version string (`"21.0.4"`). From 21 on, circle and
+  linear power windows are written the way Resolve 21 exports them: corrector
+  type 0x10004 (65540) with the full parameter set, `REF_WIDTH` 288 and an
+  identity transform matrix, and 0x10004 added to the node's corrector-type
+  list. Resolve 21 loads the older corrector-type-4 form into the Window
+  palette but renders an empty mask, which also hides the node's grade.
+  The default is unchanged, so output for Resolve 19/20 is byte-for-byte
+  what it was. Gradient and polygon/curve windows are not rewritten. The
+  format follows justhung69/resolve-mcp (MIT), pixel-verified there on free
+  21.0.4.5.
+- The node's corrector-type list is now varint encoded, because 65540 does
+  not fit in one byte. Every type id below 128 encodes to the same byte as
+  before.
+
+### Validation
+
+- Advanced Node suite on Node 20 with a fresh `npm ci`, PR merged on
+  `main`: 1,214 tests, 1,153 passed, 0 failed, 61 skipped (8 new for the
+  Resolve 21 window layout). PR CI green on Python 3.10/3.11 and Node 20/22.
+- Not live-validated on Resolve 21: the maintainer's box runs Studio
+  19.1.3.7. The window layout is checked against Resolve 21 fixtures only.
+
 ## What's New in v4.16.0 — Calls name their timeline, and failures say so
 
 Eight reports from a Studio 21.1 / Windows deployment (#320–#327) and the

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.16.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.17.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-37%20(390%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-4.16.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.17.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-37%20(390%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v4.16.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v4.17.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/install.py

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

package/resolve-advanced/server/tools/drx.mjs

@@ -258,6 +258,15 @@ const generateSchema = z.object({
         "(<pTrackVer>), for graph.apply_grade_from_drx with source='timeline'; a clip-target file applied to " +
         'the timeline is refused (DRX_NO_TIMELINE_GRADE).'
     ),
+  resolveVersion: z
+    .union([z.number().int().min(1), z.string()])
+    .optional()
+    .describe(
+      "Resolve version the file is for, as a major number (21) or a version string ('21.0.4'). From 21 on, " +
+        'circle and linear power windows are written in the Resolve 21 form (corrector type 0x10004, full parameter ' +
+        'set), which renders on Resolve 21; the older form loads there but renders an empty mask. Default: the ' +
+        'Resolve 19 form. Not live-verified here; the format comes from justhung69/resolve-mcp.'
+    ),
   outputPath: z.string().optional().describe('If set, write the .drx here'),
 });
 
@@ -692,7 +701,11 @@ export const drxTool = {
     if (action === 'generate') {
       const p = generateSchema.parse(args);
       const warnings = [];
-      const metadata = { ...(p.metadata || {}), ...(p.target ? { target: p.target } : {}) };
+      const metadata = {
+        ...(p.metadata || {}),
+        ...(p.target ? { target: p.target } : {}),
+        ...(p.resolveVersion !== undefined ? { resolveVersion: p.resolveVersion } : {}),
+      };
       const out = await drxGenerator().generateDRX(normalizeGradeParams(p.gradeParams, warnings), metadata);
       const content = typeof out === 'string' ? out : out?.content || out?.drxContent;
       const warn = warnings.length ? { warnings } : {};

package/resolve-advanced/vendor/drx-codec/drx-generator.js

@@ -222,6 +222,7 @@ const PARAM_IDS = {
  * Corrector Type IDs from shared library
  */
 const CORRECTOR_TYPES = drxParams.CORRECTOR_TYPES;
+const POWER_WINDOW_IDS = drxParams.POWER_WINDOWS;
 
 /**
  * Presence marker IDs from shared library
@@ -547,7 +548,7 @@ function buildHSLCurveParams(colorParams) {
  * @param {Object} options - Additional options (label, enabled, correctorTypes)
  */
 function createNode(nodeId, xPos, yPos, colorParams = null, options = {}) {
-  const { label = '', enabled = true, nodeIndex = nodeId } = options;
+  const { label = '', enabled = true, nodeIndex = nodeId, resolveVersion } = options;
 
   // Build node header with fields in order: F1, F2, F4, F5, F6, F7?, F8
   // Native Resolve analysis shows: id(F1), index(F2), pos(F4,F5), label?(F6), F8=44
@@ -749,9 +750,11 @@ function createNode(nodeId, xPos, yPos, colorParams = null, options = {}) {
     }
   }
   if (colorParams) {
-    const win = buildWindowParams(colorParams.window);
+    const win = buildWindowParams(colorParams.window, { resolveVersion });
     if (win.transform.length > 0) {
-      correctorBlocks.push(buildCorrectorBlock(CORRECTOR_TYPES.POWER_WINDOW, win.transform));
+      correctorBlocks.push(buildCorrectorBlock(win.transformType, win.transform));
+      // Resolve 21 also lists its window type in the node's corrector-type list.
+      if (win.transformType !== CORRECTOR_TYPES.POWER_WINDOW && presenceTypes.length > 0) presenceTypes.push(win.transformType);
     }
     if (win.softMask.length > 0) {
       // Linear-window softness mask (0x0870xxxx) lives under corrector type 3 in live data.
@@ -881,7 +884,7 @@ function createNode(nodeId, xPos, yPos, colorParams = null, options = {}) {
 
   // Add compact presence list as F2 (raw byte array of type IDs)
   if (presenceTypes.length > 0) {
-    const presenceBytes = Buffer.from(presenceTypes);
+    const presenceBytes = Buffer.concat(presenceTypes.map(encodeVarint)); // varints: the R21 window type is > 127
     f9Parts.push(protoBytes(2, presenceBytes));
     debugLog('[DRX] Added F2 presence list:', presenceTypes);
   }
@@ -1636,6 +1639,7 @@ function generateProtobuf(gradeParams, options = {}) {
     width = 1920,
     height = 1080,
     label = '',
+    resolveVersion,
   } = options;
 
   const timestamp = generateTimestamp();
@@ -1667,6 +1671,7 @@ function generateProtobuf(gradeParams, options = {}) {
       const node = createNode(nodeId, xPos, yPos, nodeConfig.params, {
         label: nodeConfig.label || `Node ${nodeId}`,
         enabled: nodeConfig.enabled !== false,
+        resolveVersion,
       });
       containerParts.push(node);
     });
@@ -1686,6 +1691,7 @@ function generateProtobuf(gradeParams, options = {}) {
     }
     const node = createNode(1, 500, 300, gradeParams, {
       label: label,
+      resolveVersion,
     });
     containerParts.push(node);
     // firstNodeId and lastNodeId both stay 1
@@ -1752,6 +1758,7 @@ async function generateMultiNodeDRX(nodes, connections, metadata = {}) {
     baseNodeId: passedBaseNodeId,
     firstNodeId: passedFirstNodeId,
     lastNodeId: passedLastNodeId,
+    resolveVersion,
   } = metadata;
 
   const timestamp = generateTimestamp();
@@ -1806,6 +1813,7 @@ async function generateMultiNodeDRX(nodes, connections, metadata = {}) {
         enabled: nodeConfig.enabled !== false,
         nodeIndex: nodeIndex, // Pass separate index for F2 field
         clipVersionId,
+        resolveVersion,
       }
     );
     containerParts.push(node);
@@ -1975,13 +1983,14 @@ async function generateDRX(gradeParams, metadata = {}) {
     sourceTC = '00:00:00:00',
     recordTC = '01:00:00:00',
     target = 'clip',
+    resolveVersion,
   } = metadata;
   if (target !== 'clip' && target !== 'timeline') {
     throw new Error(`target must be 'clip' or 'timeline', got ${JSON.stringify(target)}`);
   }
 
   // Generate the body (pass label for single-node mode)
-  const body = await generateDRXBody(gradeParams, { width, height, label });
+  const body = await generateDRXBody(gradeParams, { width, height, label, resolveVersion });
   const bodyHex = body.toString('hex');
 
   // Generate UUIDs
@@ -2803,8 +2812,8 @@ function buildLumaQualifierParams(lumaParams) {
  * @param {number} [windowParams.soft4=0] - Softness 4 (linear only)
  * @returns {Array} - Parameter entries for window corrector
  */
-function buildWindowParams(windowParams) {
-  const groups = { transform: [], softMask: [], gradient: [], shape: [] };
+function buildWindowParams(windowParams, { resolveVersion } = {}) {
+  const groups = { transform: [], transformType: CORRECTOR_TYPES.POWER_WINDOW, softMask: [], gradient: [], shape: [] };
   const paramEntries = groups.transform;
   const { POWER_WINDOWS } = drxParams;
 
@@ -2940,12 +2949,78 @@ function buildWindowParams(windowParams) {
     paramEntries.push(createParameterEntry(POWER_WINDOWS.SOFT_REF, w.soft1 * 16));
   }
 
+  if (isResolve21(resolveVersion) && !isVertexShape && paramEntries.length > 0) {
+    groups.transform = toResolve21WindowTransform(paramEntries);
+    groups.transformType = CORRECTOR_TYPE_WINDOW_R21;
+  }
+
   if (paramEntries.length > 0 || groups.softMask.length > 0) {
     debugLog('[DRX] Window params built:', paramEntries.length, '+', groups.softMask.length, isLinear ? '(linear: ct4 + ct3 mask)' : '(circle: ct4)');
   }
   return groups;
 }
 
+// Resolve 21 stores a circle/linear window transform as corrector type 0x10004 with the full
+// parameter set, not as corrector type 4 holding only the non-neutral parameters. The type 4
+// form loads into the Window palette on Resolve 21 but renders an empty mask, which also hides
+// the grade of the node. Order and neutral values follow what Resolve 21.0.4 exports for a
+// fresh circle window, as measured and pixel-verified by justhung69 in
+// https://github.com/justhung69/resolve-mcp (server/drx_r21.py, MIT, (c) 2026 Bùi Xuân Hưng).
+const CORRECTOR_TYPE_WINDOW_R21 = 0x10004;
+const R21_WINDOW_ORDER = [
+  [POWER_WINDOW_IDS.ROTATE, 0],
+  [POWER_WINDOW_IDS.ASPECT, 0],
+  [POWER_WINDOW_IDS.SOFT_REF, 0],
+  [POWER_WINDOW_IDS.SIZE, 1],
+  [POWER_WINDOW_IDS.PAN, 0],
+  [POWER_WINDOW_IDS.TILT, 0],
+];
+
+/** True when `resolveVersion` (a major number such as 21, or a string such as "21.0.4") is Resolve 21 or later. */
+function isResolve21(resolveVersion) {
+  return Number.parseInt(resolveVersion, 10) >= 21;
+}
+
+/** Read the parameter id out of an F3 parameter entry built by createParameterEntry. */
+function parameterEntryId(entry) {
+  let i = 1; // skip the F3 tag
+  while (entry[i++] & 0x80); // skip the entry length
+  i++; // skip the F1 tag
+  let id = 0;
+  let shift = 0;
+  let byte;
+  do {
+    byte = entry[i++];
+    id += (byte & 0x7f) * 2 ** shift;
+    shift += 7;
+  } while (byte & 0x80);
+  return id;
+}
+
+function toResolve21WindowTransform(entries) {
+  const byId = new Map(entries.map((entry) => [parameterEntryId(entry), entry]));
+  const take = (id) => {
+    const entry = byId.get(id);
+    byId.delete(id);
+    return entry;
+  };
+  const out = R21_WINDOW_ORDER.map(([id, neutral]) => take(id) || createParameterEntry(id, neutral));
+  take(POWER_WINDOW_IDS.WINDOW_TYPE);
+  const identity = [1, 0, 0, 0, 1, 0, 0, 0, 1];
+  const matrix = protoBytes(3, Buffer.concat([
+    protoVarint(1, POWER_WINDOW_IDS.TRACKING_BLOB),
+    protoBytes(2, protoBytes(10, Buffer.concat(identity.map((v, i) => protoFloat32(i + 1, v))))),
+  ]));
+  out.push(
+    createVarintParameterEntry(POWER_WINDOW_IDS.WINDOW_TYPE, 2),
+    createParameterEntry(POWER_WINDOW_IDS.REF_WIDTH, 288),
+    createParameterEntry(POWER_WINDOW_IDS.UNK_0E, 0),
+    createParameterEntry(POWER_WINDOW_IDS.UNK_0F, 0),
+    take(POWER_WINDOW_IDS.TRACKING_BLOB) || matrix,
+  );
+  return out.concat([...byId.values()]); // e.g. opacity, kept after the measured set
+}
+
 /**
  * Check if any secondary correction tools are used (qualifier, window, HDR wheels)
  * Used to determine if we need to add those corrector blocks

package/src/granular/common.py

@@ -92,7 +92,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.16.0"
+VERSION = "4.17.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 377-tool granular server instead
 """
 
-VERSION = "4.16.0"
+VERSION = "4.17.0"
 
 import base64
 import os