davinci-resolve-mcp 4.16.0 → 4.17.1

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 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.1 — Media analysis decodes each file once
+
+### Changed
+
+- **The readthrough pass of media analysis runs ffmpeg once instead of four
+  times** (#329, thanks @Dev-next-gen). Loudness, scene scoring, black frames
+  and silence each used to be a separate ffmpeg run, and each run decoded the
+  whole file: `-af` alone does not drop the video stream from a null output,
+  so the audio passes decoded every video frame too. The four filters now
+  share one run through `split`/`asplit`. On a 1080p H.264 file the
+  readthrough took 8.1 s instead of 22.1 s, and CPU time fell from 84.8 s to
+  30.5 s; ProRes and HEVC dropped by about the same share. The results are
+  the same as before. The parsers are unchanged.
+- The four measurements now share one exit code and one timeout. The single
+  run gets four times the old per-pass timeout, the budget of the four runs it
+  replaces. If that run times out, all four report `success: false`, where
+  before the other three could still succeed.
+
+### Validation
+
+- Python suite with the PR merged on `main`: 4,291 tests. The only failures
+  are the 4 `source_media_guard` path checks that always fail in a scratch
+  worktree. The new test compares the single run against the four separate
+  runs with the real ffmpeg on an A/V file, a video-only file and an
+  audio-only file.
+- No Resolve behaviour changed; this is ffmpeg only.
+
+## 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.1-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.1-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.1 版 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.1"
 # 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.1",
   "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.1"
 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.1"
 
 import base64
 import os

package/src/utils/media_analysis.py

@@ -2781,7 +2781,13 @@ def _media_duration_seconds(record: Dict[str, Any], technical: Dict[str, Any]) -
     return None
 
 
-def _ffmpeg_stderr_filter(path: str, video_filter: Optional[str] = None, audio_filter: Optional[str] = None, frames: Optional[int] = None) -> Tuple[int, str]:
+def _ffmpeg_stderr_filter(
+    path: str,
+    video_filter: Optional[str] = None,
+    audio_filter: Optional[str] = None,
+    frames: Optional[int] = None,
+    timeout: int = COMMAND_TIMEOUT_SECONDS,
+) -> Tuple[int, str]:
     args = ["ffmpeg", "-hide_banner", "-nostats", "-i", path]
     if video_filter:
         args.extend(["-vf", video_filter])
@@ -2790,7 +2796,7 @@ def _ffmpeg_stderr_filter(path: str, video_filter: Optional[str] = None, audio_f
     if frames is not None:
         args.extend(["-frames:v", str(frames)])
     args.extend(["-f", "null", "-"])
-    code, _, stderr = _run_command(args)
+    code, _, stderr = _run_command(args, timeout=timeout)
     return code, stderr
 
 
@@ -2934,25 +2940,45 @@ def _parse_idet(stderr: str) -> Dict[str, Any]:
     }
 
 
+# The four whole-file measurements `_readthrough_analysis` makes. They used to be four
+# ffmpeg runs, and every run decoded the whole file: `-af` alone does not drop the video
+# stream from a null output, so the loudness and silence passes decoded every frame just
+# as the scene and black passes did, and each video pass decoded the audio too. One run
+# with `split`/`asplit` decodes each stream once and feeds all four filters. Each parser
+# below matches only its own filter's lines, so sharing one stderr changes no result.
+# A missing stream behaves as it did per pass: ffmpeg skips the -vf or -af it cannot
+# use, exits 0, and that filter's parser finds nothing.
+_SCENE_SCORE_FILTER = "select='gt(scene,0)',metadata=print:key=lavfi.scene_score,showinfo"
+_BLACKDETECT_FILTER = "blackdetect=d=0.5:pix_th=0.10"
+_LOUDNESS_FILTER = "ebur128=peak=true"
+_SILENCEDETECT_FILTER = "silencedetect=noise=-50dB:d=1"
+_READTHROUGH_VIDEO_FILTER = f"split[scene][black];[scene]{_SCENE_SCORE_FILTER},nullsink;[black]{_BLACKDETECT_FILTER}"
+_READTHROUGH_AUDIO_FILTER = f"asplit[loud][silence];[loud]{_LOUDNESS_FILTER},anullsink;[silence]{_SILENCEDETECT_FILTER}"
+
+
 def _readthrough_analysis(path: str) -> Dict[str, Any]:
     result: Dict[str, Any] = {"success": True}
 
-    loud_code, loud_stderr = _ffmpeg_stderr_filter(path, audio_filter="ebur128=peak=true")
+    # The one run carries the timeout budget of the four it replaces, so a file whose
+    # slowest pass (scene scoring) finished in time before still finishes in time.
+    code, stderr = _ffmpeg_stderr_filter(
+        path,
+        video_filter=_READTHROUGH_VIDEO_FILTER,
+        audio_filter=_READTHROUGH_AUDIO_FILTER,
+        timeout=COMMAND_TIMEOUT_SECONDS * 4,
+    )
+
     result["loudness"] = {
-        "success": loud_code == 0,
-        "metrics": _parse_loudness(loud_stderr),
+        "success": code == 0,
+        "metrics": _parse_loudness(stderr),
     }
 
-    # Adaptive scene detection. One ffmpeg pass dumps a (pts_time, scene_score) pair
+    # Adaptive scene detection. The scene branch dumps a (pts_time, scene_score) pair
     # for every frame whose scene score is > 0 (i.e. every non-first frame); we then
     # compute a content-aware threshold from that distribution and keep peaks above it.
     # Replaces the legacy hardcoded ``gt(scene,0.3)``, which was too coarse on
     # high-motion content (missed real cuts) and too sensitive on locked-off content.
-    scene_code, scene_stderr = _ffmpeg_stderr_filter(
-        path,
-        video_filter="select='gt(scene,0)',metadata=print:key=lavfi.scene_score,showinfo",
-    )
-    scene_score_pairs = _parse_scene_score_pairs(scene_stderr)
+    scene_score_pairs = _parse_scene_score_pairs(stderr)
     scene_threshold, scene_threshold_stats = _adaptive_scene_threshold(scene_score_pairs)
     adaptive_scene_items = [
         {"time_seconds": pts, "score": score}
@@ -2960,22 +2986,20 @@ def _readthrough_analysis(path: str) -> Dict[str, Any]:
         if score is not None and score > scene_threshold
     ]
     result["scenes"] = {
-        "success": scene_code == 0,
+        "success": code == 0,
         "items": adaptive_scene_items,
         "threshold": scene_threshold,
         "threshold_stats": scene_threshold_stats,
     }
 
-    black_code, black_stderr = _ffmpeg_stderr_filter(path, video_filter="blackdetect=d=0.5:pix_th=0.10")
     result["black_frames"] = {
-        "success": black_code == 0,
-        "items": _parse_blackdetect(black_stderr),
+        "success": code == 0,
+        "items": _parse_blackdetect(stderr),
     }
 
-    silence_code, silence_stderr = _ffmpeg_stderr_filter(path, audio_filter="silencedetect=noise=-50dB:d=1")
     result["silence"] = {
-        "success": silence_code == 0,
-        "items": _parse_silencedetect(silence_stderr),
+        "success": code == 0,
+        "items": _parse_silencedetect(stderr),
     }
 
     idet_code, idet_stderr = _ffmpeg_stderr_filter(path, video_filter="idet", frames=500)