davinci-resolve-mcp 2.136.1 → 2.138.0

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 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.138.0 — wipes join the conform
+
+### Added
+
+- **Wipe transitions authored offline** (`transitions[].type: 'wipe'`;
+  EDL `W`-codes route to it automatically through
+  `assemble_from_interchange`). Harvested from a live 19.1.3.7 EDL W-code
+  import (E61): Resolve stores a wipe as the same Cross Dissolve element
+  whose FieldsBlob zlib payload zeroes the style-id field the dissolve
+  fills — and its own importer maps EVERY W-code (W001/W002/W005 measured
+  identical) to one soft-edge wipe style, so a single style is full parity
+  with the host importer. Render-proven both directions: the live wipe's
+  midpoint splits spatially (157.2/206.3 left/right vs the dissolve's
+  uniform 181.6), the element survives the .drt round-trip bit-exact, and
+  the offline-authored wipe through the full EDL → assemble → import →
+  render route reproduces the split (158.1/205.0). Audio wipes refuse
+  (junctions cross-fade).
+
+## What's New in v2.137.0 — the sweep reaches the database tier
+
+### Fixed
+
+- **Fairlight DB row selection** (adapted the v2.133 container-pin lesson to
+  the vendor layer): `readFromDatabase` took the FIRST `Sm2Sequence` row — in
+  any project holding a compound clip that can be a compound's embedded
+  sequence with no `FLStudioModelBA`, so bus reads failed while the model sat
+  in the next row (measured live). Worse, `applyTemplate` wrote its new blob
+  into EVERY blob-bearing sequence row, clobbering compound `SeqRef` links
+  project-wide. Reads now pick the model-bearing row; writes scope to exactly
+  that `Sm2Sequence_id` and refuse ambiguous multi-timeline projects without
+  an explicit target. `read_buses_from_db` also stops dumping the ~430KB
+  decompressed model into the tool response.
+- **`provenance.cdl_diff` silently identity-defaulted array-shaped CDLs**:
+  `[r,g,b]` slope/offset/power (the common interchange form) read as unity
+  through the `{r,g,b}` accessor, so two different grades diffed as
+  saturation-only (measured). Both shapes are accepted now; unrecognizable
+  shapes refuse loudly.
+- **Node-floor enforcement**: the advanced server refuses to start below
+  Node 20.9 with the exact fix named (measured live: a client config's node
+  resolved to an nvm v18, where pure-JS tools limp and better-sqlite3 dies
+  with a cryptic ABI mismatch). `install.py` now writes an absolute,
+  version-checked node path into client configs, and the better-sqlite3
+  loader distinguishes "not installed" from "built for a different Node".
+- **Windows UTF-8, rounds two and three** — adapted from
+  [PR #175](https://github.com/samuelgursky/davinci-resolve-mcp/pull/175) and
+  [PR #176](https://github.com/samuelgursky/davinci-resolve-mcp/pull/176) by
+  @Chosen-3: the six unencoded call sites in `src/` (brain-edits registry,
+  page lock) and `install.py`'s client-config `read_json`/`write_json`. The
+  UTF-8 discipline guard now covers `src/` and `install.py` too.
+
+### Verified through the MCP tool layer (E60)
+
+`project_read` (introspect/report/audit/timeline_clips), `offline_ref.list_in_project`,
+`color_trace.plan` (6/6 exact-name matches), and both fairlight bus readers,
+all against a live scratch project database.
+
 ## What's New in v2.136.1 — the changelog catches up
 
 ### Fixed

package/README.md

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

package/README.zh-CN.md

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

package/bin/davinci-resolve-advanced-mcp.mjs

@@ -13,6 +13,27 @@
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import path from 'node:path';
 
+// Node floor (package.json engines: >=20.9), enforced at STARTUP rather than
+// discovered per-feature: under an old Node the pure-JS tools limp along
+// while native-dep paths (better-sqlite3: project_read, fairlight DB actions,
+// offline_ref live linking) die with a cryptic NODE_MODULE_VERSION mismatch —
+// measured live under nvm's v18.20.8, which is exactly what a bare "node"
+// command in an MCP registration resolves to on a machine whose shell
+// default lags. Silent degradation is this repo's least favorite failure
+// mode; refuse loudly with the fix instead.
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (major < 20 || (major === 20 && minor < 9)) {
+  process.stderr.write(
+    `[davinci-resolve-advanced-mcp] Node ${process.versions.node} is below the ` +
+    `supported floor (>=20.9). This process was started by: ${process.execPath}\n` +
+    `Fix: point the MCP registration's command at a Node >=20.9 binary ` +
+    `(e.g. the absolute path from \`nvm which 20\`), or update the default ` +
+    `node on PATH. Re-running install.py also rewrites client configs with ` +
+    `an absolute, version-checked node path.\n`,
+  );
+  process.exit(1);
+}
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const serverEntry = path.resolve(__dirname, '..', 'resolve-advanced', 'server', 'index.mjs');
 

package/docs/guides/native-drt-authoring.md

@@ -42,6 +42,7 @@ window. `render.verify_output` covers the container-level checks.
 | Media cuts, multi-source | `media: [{mediaFilePath, spec, cuts}]` | v2.106–2.107 |
 | Multi-track video (V2+ stacking) | `cuts[].track` (video-only above V1) | v2.112 |
 | Cross-dissolves | `transitions: [{track, atFrame, durationFrames}]` | v2.111 |
+| Wipes (EDL `W`-codes) | `transitions[].type: 'wipe'` (single soft-edge style — host-importer parity) | v2.138 |
 | Audio cross-fades | `transitions[].trackType: 'audio'` | v2.116 |
 | Constant retimes, forward | `cuts[].speed` (e.g. `0.5`) | v2.113 |
 | Constant retimes, reverse | `cuts[].reverse` | v2.114 |

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.136.1"
+VERSION = "2.138.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
@@ -1091,7 +1091,7 @@ def read_json(path):
     existing settings (issue #71: Zed's settings.json ships with comments).
     """
     try:
-        with open(path, "r") as f:
+        with open(path, "r", encoding="utf-8") as f:
             raw = f.read()
     except FileNotFoundError:
         return {}
@@ -1120,7 +1120,7 @@ def write_json(path, data):
         backup = path.with_suffix(path.suffix + ".backup")
         shutil.copy2(path, backup)
 
-    with open(path, "w") as f:
+    with open(path, "w", encoding="utf-8") as f:
         json.dump(data, f, indent=2)
         f.write("\n")
 
@@ -1183,12 +1183,61 @@ def build_advanced_entry(server_path, python_path=None):
     """
     project_dir = Path(server_path).resolve().parents[1]  # .../src/server.py -> repo root
     advanced_bin = project_dir / "bin" / "davinci-resolve-advanced-mcp.mjs"
-    entry = {"command": "node", "args": [str(advanced_bin)]}
+    entry = {"command": resolve_node_command(), "args": [str(advanced_bin)]}
     if python_path:
         entry["env"] = {"AAF_PROBE_PYTHON": str(python_path)}
     return entry
 
 
+# Node floor for the advanced server (package.json engines). Below it the
+# pure-JS tools limp along while native-dep paths (better-sqlite3) die with a
+# cryptic NODE_MODULE_VERSION mismatch — measured live when a client config's
+# bare "node" resolved to an nvm v18 that a GUI app had on PATH.
+NODE_MIN = (20, 9)
+
+
+def _node_version(cmd):
+    try:
+        out = subprocess.run([cmd, "--version"], capture_output=True, text=True,
+                             encoding="utf-8", timeout=10, check=False).stdout.strip()
+        parts = out.lstrip("v").split(".")
+        return (int(parts[0]), int(parts[1]))
+    except Exception:
+        return None
+
+
+def resolve_node_command():
+    """Absolute path to a Node >= the floor, or bare "node" as a last resort.
+
+    A bare "node" in a client config resolves against WHATEVER PATH the
+    launching GUI app has — which on this machine meant an nvm v18 while the
+    repo floor is 20.9. Pin the binary at install time instead: prefer the
+    node on the installer's PATH if it meets the floor, else the newest
+    nvm-managed node that does.
+    """
+    on_path = shutil.which("node")
+    if on_path:
+        ver = _node_version(on_path)
+        if ver and ver >= NODE_MIN:
+            return str(Path(on_path).resolve())
+    nvm_dir = Path.home() / ".nvm" / "versions" / "node"
+    if nvm_dir.is_dir():
+        candidates = []
+        for d in nvm_dir.iterdir():
+            node_bin = d / "bin" / "node"
+            if node_bin.exists():
+                ver = _node_version(str(node_bin))
+                if ver and ver >= NODE_MIN:
+                    candidates.append((ver, str(node_bin)))
+        if candidates:
+            return max(candidates)[1]
+    print(
+        f"  {yellow('Node:')} no Node >= {NODE_MIN[0]}.{NODE_MIN[1]} found; writing a bare 'node' command. "
+        "The advanced server will refuse to start under an older Node and name this fix."
+    )
+    return "node"
+
+
 def generate_manual_config(python_path, server_path, api_path, lib_path):
     """Generate config snippets for manual setup."""
     entry = build_server_entry(python_path, server_path, api_path, lib_path)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.136.1",
+  "version": "2.138.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/server/author-interchange.mjs

@@ -425,7 +425,12 @@ export function eventsToAssembleSpec(events, opts = {}) {
       });
       continue;
     }
-    transitions.push({ track: c.track, atFrame: c.atFrame, durationFrames: c.durationFrames });
+    // EDL W-codes author as a WIPE (Resolve's own EDL importer maps every
+    // W-code to its single soft-edge wipe style — W001/W002/W005 measured
+    // identical — so one style is host-importer parity; render-verified
+    // spatial split at the midpoint). Everything else is a dissolve.
+    const kind = /^W/i.test(String(c.type || '')) ? 'wipe' : 'dissolve';
+    transitions.push({ track: c.track, atFrame: c.atFrame, durationFrames: c.durationFrames, ...(kind === 'wipe' ? { type: 'wipe' } : {}) });
   }
   // Audio cross-fades, same geometry rules (render-verified on 19.1.3.7 via
   // the harvested cross-fade template: the highpass RMS ramps, not steps).

package/resolve-advanced/server/capabilities.mjs

@@ -49,6 +49,31 @@ export const hasFfprobe = () => onPath('ffprobe');
 export const hasSharp = () => nodeModuleAvailable('sharp');
 export const hasBetterSqlite3 = () => nodeModuleAvailable('better-sqlite3');
 
+/**
+ * Load better-sqlite3 or throw the RIGHT actionable error. Two distinct
+ * failures hide behind one require: the module is not installed (install it),
+ * or it IS installed but compiled against a different Node ABI — which is
+ * what a client config pointing at a different Node than the one that ran
+ * `npm install` produces (measured live: server under nvm v18, module built
+ * under v20 → cryptic NODE_MODULE_VERSION mismatch). Name the real fix.
+ */
+export function requireBetterSqlite3(featureLabel = 'This feature') {
+  try {
+    return createRequire(import.meta.url)('better-sqlite3');
+  } catch (err) {
+    const msg = String(err && err.message);
+    if (/NODE_MODULE_VERSION/.test(msg)) {
+      throw new Error(
+        `${featureLabel} needs better-sqlite3, which is installed but compiled for a DIFFERENT Node ` +
+          `than this server is running under (${process.version} at ${process.execPath}). ` +
+          `Fix: run \`npm rebuild better-sqlite3\` in resolve-advanced/ using THIS node, ` +
+          `or point the MCP registration at the node that built it.`,
+      );
+    }
+    throw new Error(`${featureLabel} needs the optional native dep 'better-sqlite3'. Install: npm i better-sqlite3`);
+  }
+}
+
 /** Throw a clear, actionable error if ffmpeg/ffprobe aren't on PATH. */
 export function requireFfmpeg() {
   if (!hasFfmpeg() || !hasFfprobe()) {

package/resolve-advanced/server/db-patch.mjs

@@ -15,6 +15,7 @@ import os from 'node:os';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
+import { requireBetterSqlite3 } from './capabilities.mjs';
 
 export const DISK_DB_ROOT = path.join(os.homedir(), 'Library/Application Support/Blackmagic Design/DaVinci Resolve/Resolve Disk Database/Resolve Projects');
 
@@ -91,11 +92,7 @@ export async function responsiveRoots(roots = DB_ROOTS, deadlineMs = 3000) {
 }
 
 export function loadSqlite() {
-  try {
-    return require('better-sqlite3');
-  } catch {
-    throw new Error("Project.db patching needs the optional native dep 'better-sqlite3'. Install: npm i better-sqlite3");
-  }
+  return requireBetterSqlite3('Project.db patching');
 }
 
 /**

package/resolve-advanced/server/lineage-db.mjs

@@ -15,6 +15,7 @@ import crypto from 'node:crypto';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
+import { requireBetterSqlite3 } from './capabilities.mjs';
 const V = '../vendor/conform-qc';
 const parse = require(`${V}/parse/index.js`);
 const resolveTarget = require(`${V}/oracle/resolve.js`);
@@ -22,11 +23,7 @@ const resolveTarget = require(`${V}/oracle/resolve.js`);
 const TICKS_PER_SEC = 254016000000;
 
 function loadSqlite() {
-  try {
-    return require('better-sqlite3');
-  } catch {
-    throw new Error("lineage store needs the optional native dep 'better-sqlite3'. Install: npm i better-sqlite3");
-  }
+  return requireBetterSqlite3('The lineage DB');
 }
 
 const SCHEMA = `

package/resolve-advanced/server/offline-ref-db.mjs

@@ -31,6 +31,7 @@ import os from 'node:os';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
+import { requireBetterSqlite3 } from './capabilities.mjs';
 
 const DISK_DB_ROOT = path.join(os.homedir(), 'Library/Application Support/Blackmagic Design/DaVinci Resolve/Resolve Disk Database/Resolve Projects');
 // Modern Studio installs keep the local library under "Resolve Project
@@ -38,11 +39,7 @@ const DISK_DB_ROOT = path.join(os.homedir(), 'Library/Application Support/Blackm
 const PROJECT_LIBRARY_ROOT = path.join(os.homedir(), 'Library/Application Support/Blackmagic Design/DaVinci Resolve/Resolve Project Library/Resolve Projects');
 
 function loadSqlite() {
-  try {
-    return require('better-sqlite3');
-  } catch {
-    throw new Error("offline_ref DB path needs the optional native dep 'better-sqlite3'. Install: npm i better-sqlite3");
-  }
+  return requireBetterSqlite3('The live offline-reference DB path');
 }
 
 /** Recursively locate <projectName>/Project.db under the Resolve Disk Database. */

package/resolve-advanced/server/project-db.mjs

@@ -14,12 +14,9 @@ import crypto from 'node:crypto';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
+import { requireBetterSqlite3 } from './capabilities.mjs';
 function loadSqlite() {
-  try {
-    return require('better-sqlite3');
-  } catch {
-    throw new Error("project DB needs the optional native dep 'better-sqlite3'. Install: npm i better-sqlite3");
-  }
+  return requireBetterSqlite3('Project.db access');
 }
 
 export const ENTITY_KINDS = ['type', 'series', 'episode', 'sequence', 'group', 'deliverable'];

package/resolve-advanced/server/provenance-audit.mjs

@@ -120,13 +120,34 @@ export async function cdlExport(ref, opts = {}) {
 }
 
 /** Diff two ASC CDL objects (slope/offset/power/saturation) → per-param deltas. */
+// Accept BOTH common CDL shapes — {r,g,b} objects (this repo's internal
+// vocabulary) and [r,g,b] arrays (the common interchange form) — and REFUSE
+// anything else. The old reader indexed .r/.g/.b unconditionally, so an
+// array-shaped CDL silently decayed to identity and cdl_diff reported two
+// different grades as matching everywhere but saturation (measured, E60).
+function cdlChannels(value, grp, side) {
+  if (value == null) return { r: undefined, g: undefined, b: undefined };
+  if (Array.isArray(value)) {
+    if (value.length !== 3 || value.some((v) => typeof v !== 'number')) {
+      throw new Error(`cdlDiff: ${side}.${grp} array must be exactly [r, g, b] numbers`);
+    }
+    return { r: value[0], g: value[1], b: value[2] };
+  }
+  if (typeof value === 'object' && ['r', 'g', 'b'].every((k) => value[k] === undefined || typeof value[k] === 'number')) {
+    return value;
+  }
+  throw new Error(`cdlDiff: ${side}.${grp} must be {r,g,b} or [r,g,b] — refusing to silently treat it as identity`);
+}
+
 export function cdlDiff(a, b, opts = {}) {
   const tol = opts.tol ?? 1e-4;
   const deltas = [];
   for (const grp of ['slope', 'offset', 'power']) {
+    const ac = cdlChannels(a[grp], grp, 'a');
+    const bc = cdlChannels(b[grp], grp, 'b');
     for (const k of ['r', 'g', 'b']) {
-      const av = (a[grp] && a[grp][k]) ?? (grp === 'offset' ? 0 : 1);
-      const bv = (b[grp] && b[grp][k]) ?? (grp === 'offset' ? 0 : 1);
+      const av = ac[k] ?? (grp === 'offset' ? 0 : 1);
+      const bv = bc[k] ?? (grp === 'offset' ? 0 : 1);
       if (Math.abs(av - bv) > tol) deltas.push({ param: `${grp}.${k}`, a: +av.toFixed(5), b: +bv.toFixed(5), delta: +(bv - av).toFixed(5) });
     }
   }

package/resolve-advanced/server/reverse-clip-db.mjs

@@ -31,13 +31,10 @@ import path from 'node:path';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
+import { requireBetterSqlite3 } from './capabilities.mjs';
 
 function loadSqlite() {
-  try {
-    return require('better-sqlite3');
-  } catch {
-    throw new Error("reverse-clip DB path needs the optional native dep 'better-sqlite3'. Install: npm i better-sqlite3");
-  }
+  return requireBetterSqlite3('Reversed-clip DB repair');
 }
 function loadPg() {
   try {

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

@@ -51,7 +51,7 @@ const assembleSchema = z.object({
   spec: z
     .object({})
     .passthrough()
-    .describe("assembleTimeline spec: { timelineName?, startFrame? (timeline start frame @24, default 86400=01:00:00:00 — sets the start TIMECODE, render-verified on 19), media?: {mediaFilePath, spec:{width,height,frameCount,fps}, cuts:[{startFrame,durationFrames,srcIn?,track? (1-based video track; >1 = video-only, render-verified stacking),speed?/reverse? (constant retime, e.g. 0.5, forward or backwards; video-only; readback+render-verified on 19),freeze? (true = hold source frame srcIn for the whole cut; video-only; render-proven frozen on 19 via freezedetect),audioOnly?+track? (explicit AUDIO placement on audio track 1-8; presence suppresses the A1 mirror; render-verified on 19)}]} | [same, ...] (multi-source needs media_pool.capture_media_template run once per file), transitions?: [{track, atFrame, durationFrames?, trackType? ('video' dissolve | 'audio' cross-fade, both render-verified on 19)}], markers?: [{frame (timeline-absolute), color? (16 names), name?, note?, duration?, customData?}] (readback-verified on 19), compounds?: [{name, startFrame (parent, absolute), durationFrames, track?, cuts:[{mediaFilePath, startFrame (INNER, 0-based), durationFrames, srcIn?}], compounds?: [same, nested — frames inner-relative]}] (multiple PARALLEL compounds compose AND compounds NEST recursively — depth-2 AND depth-3 playback render-verified on 19 (the old depth-2 black was a missing SequenceSetup key, fixed); inner cuts need captured templates w/ native clips), subtitles?: [{startFrame (timeline-absolute), durationFrames, text}] + subtitlesSrt? (raw SRT, cues anchor at the origin; readback-verified on 19; angle-bracket runs read as SRT markup), elements?: [{type:'title'|'generator', track, startFrame, durationFrames?, text?, generatorName? ('Solid Color'|'SMPTE Color Bar'|'Grey Scale' render-verified on 19), ...}] }. startFrame is timeline-absolute (origin 86400)."),
+    .describe("assembleTimeline spec: { timelineName?, startFrame? (timeline start frame @24, default 86400=01:00:00:00 — sets the start TIMECODE, render-verified on 19), media?: {mediaFilePath, spec:{width,height,frameCount,fps}, cuts:[{startFrame,durationFrames,srcIn?,track? (1-based video track; >1 = video-only, render-verified stacking),speed?/reverse? (constant retime, e.g. 0.5, forward or backwards; video-only; readback+render-verified on 19),freeze? (true = hold source frame srcIn for the whole cut; video-only; render-proven frozen on 19 via freezedetect),audioOnly?+track? (explicit AUDIO placement on audio track 1-8; presence suppresses the A1 mirror; render-verified on 19)}]} | [same, ...] (multi-source needs media_pool.capture_media_template run once per file), transitions?: [{track, atFrame, durationFrames?, trackType? ('video' | 'audio' cross-fade), type? ('dissolve' default | 'wipe' — the single soft-edge wipe style Resolve's own EDL importer maps every W-code to; all render-verified on 19)}], markers?: [{frame (timeline-absolute), color? (16 names), name?, note?, duration?, customData?}] (readback-verified on 19), compounds?: [{name, startFrame (parent, absolute), durationFrames, track?, cuts:[{mediaFilePath, startFrame (INNER, 0-based), durationFrames, srcIn?}], compounds?: [same, nested — frames inner-relative]}] (multiple PARALLEL compounds compose AND compounds NEST recursively — depth-2 AND depth-3 playback render-verified on 19 (the old depth-2 black was a missing SequenceSetup key, fixed); inner cuts need captured templates w/ native clips), subtitles?: [{startFrame (timeline-absolute), durationFrames, text}] + subtitlesSrt? (raw SRT, cues anchor at the origin; readback-verified on 19; angle-bracket runs read as SRT markup), elements?: [{type:'title'|'generator', track, startFrame, durationFrames?, text?, generatorName? ('Solid Color'|'SMPTE Color Bar'|'Grey Scale' render-verified on 19), ...}] }. startFrame is timeline-absolute (origin 86400)."),
   outputPath: z.string().describe('Absolute path where the importable .drt will be written'),
   targetAppVersion: z
     .union([z.string(), z.number()])

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

@@ -53,7 +53,18 @@ export const fairlightTool = {
       const p = dbReadSchema.parse(args);
       const db = openDb(p.dbPath, false);
       try {
-        return patcher.readFromDatabase(db);
+        // Summarize: the full readFromDatabase result carries the multi-
+        // hundred-KB decompressed model + raw blobs — dumped into the tool
+        // response as JSON byte arrays (measured E60). Return the facts.
+        const m = patcher.readFromDatabase(db);
+        return {
+          busFormat: m.busFormat,
+          buses: m.buses,
+          sequenceId: m.sequenceId,
+          modelRowCount: m.modelRowCount,
+          modelBytes: m.data.length,
+          compressedBytes: m.rawBlob.length,
+        };
       } finally {
         db.close();
       }

package/resolve-advanced/vendor/drp-format/assemble-timeline.js

@@ -211,6 +211,7 @@ async function assembleTimeline(spec = {}) {
     ({ buffer } = await placeTransition(buffer, {
       track: tr.track, atFrame: tr.atFrame, durationFrames: tr.durationFrames,
       trackType: tr.trackType || 'video',
+      type: tr.type || 'dissolve',
     }));
   }
 

package/resolve-advanced/vendor/drp-format/place-transition.js

@@ -55,8 +55,21 @@ const clipDuration = (c) => { const m = c.match(/<Duration>(\d+)<\/Duration>/);
  * @returns {Promise<{buffer:Buffer, entry:string, timelineUuid:string, track:number,
  *   atFrame:number, start:number, durationFrames:number, transitionDbId:string|null}>}
  */
+// The WIPE variant (harvested from a live 19.1.3.7 EDL W-code import, E61):
+// Resolve stores a wipe as the SAME Cross Dissolve transition element whose
+// FieldsBlob zlib payload zeroes the style-id field the dissolve fills with
+// 08 c79fc3e9. EffectFiltersBA, alignment, everything else is byte-identical.
+// Render-proven: midpoint splits spatially (left 157.2 / right 206.3 on the
+// standard probe media) vs the dissolve's uniform 181.6, and the element
+// survives the .drt round-trip bit-exact. Resolve's own EDL importer maps
+// EVERY W-code (W001/W002/W005 measured identical) to this single soft-edge
+// wipe style, so one style is full parity with the host importer.
+const WIPE_FIELDS_BLOB = '00000002000000158012120000002c789c636660642016000000da0005';
+
 async function placeTransition(drpInput, opts = {}) {
-  const { track, atFrame, durationFrames = 24, trackType = 'video', timelineUuid } = opts;
+  const { track, atFrame, durationFrames = 24, trackType = 'video', type = 'dissolve', timelineUuid } = opts;
+  if (type !== 'dissolve' && type !== 'wipe') throw new Error("placeTransition: type must be 'dissolve' or 'wipe'");
+  if (type === 'wipe' && trackType === 'audio') throw new Error('placeTransition: wipes are video-only (audio junctions cross-fade)');
   if (!Number.isInteger(track) || track < 1) throw new TypeError('placeTransition: track must be a positive integer');
   if (!Number.isInteger(atFrame)) throw new TypeError('placeTransition: atFrame must be an integer');
   if (!Number.isInteger(durationFrames) || durationFrames < 2) throw new TypeError('placeTransition: durationFrames must be an integer >= 2');
@@ -78,6 +91,9 @@ async function placeTransition(drpInput, opts = {}) {
 
   let trans = fs.readFileSync(trackType === 'audio' ? AUDIO_TEMPLATE_PATH : TEMPLATE_PATH, 'utf8').trim();
   trans = freshDbIds(trans);
+  if (type === 'wipe') {
+    trans = trans.replace(/<FieldsBlob>[0-9a-fA-F]*<\/FieldsBlob>/, `<FieldsBlob>${WIPE_FIELDS_BLOB}</FieldsBlob>`);
+  }
   const start = atFrame - Math.floor(durationFrames / 2); // centered (AlignmentType 2)
   trans = trans.replace(/<Start>\d+<\/Start>/, `<Start>${start}</Start>`);
   trans = trans.replace(/<Duration>\d+<\/Duration>/, `<Duration>${durationFrames}</Duration>`);

package/resolve-advanced/vendor/fairlight/index.js

@@ -216,27 +216,46 @@ function readBusConfig(data) {
  * @returns {{ busFormat, buses, data, rawBlob, fieldsBlob, entries }}
  */
 function readFromDatabase(db) {
-  const row = db.prepare('SELECT FieldsBlob FROM Sm2Sequence WHERE FieldsBlob IS NOT NULL').get();
-  if (!row) throw new Error('No Sm2Sequence with FieldsBlob found');
-
-  const fieldsBlobBuf = Buffer.from(row.FieldsBlob);
-  const { entries } = parseFieldsBlob(fieldsBlobBuf);
+  // Iterate EVERY blob-bearing sequence row and pick one that actually
+  // carries the Fairlight model. "First row wins" is wrong the moment a
+  // project holds a COMPOUND CLIP: a compound's embedded Sm2Sequence has a
+  // FieldsBlob (SeqRef/SequenceSetup/thumbnail) but no FLStudioModelBA, and
+  // whichever row the engine returns first decided whether this function
+  // worked at all (measured: a one-timeline project with compounds reported
+  // "No FLStudioModelBA found" while the model sat in the next row).
+  const rows = db.prepare('SELECT Sm2Sequence_id, FieldsBlob FROM Sm2Sequence WHERE FieldsBlob IS NOT NULL').all();
+  if (!rows.length) throw new Error('No Sm2Sequence with FieldsBlob found');
 
   let busFormat = null;
   let rawBlob = null;
   let data = null;
-
-  for (const e of entries) {
-    if (e.key === 'FirstMainBusFormat') {
-      busFormat = e.rawValue.readUInt32BE(0);
-    }
-    if (e.key === 'FLStudioModelBA') {
-      rawBlob = e.rawValue.slice(4); // skip size prefix
-      data = decompressFLModel(rawBlob);
+  let fieldsBlobBuf = null;
+  let entries = null;
+  let sequenceId = null;
+  let modelRowCount = 0;
+
+  for (const row of rows) {
+    const buf = Buffer.from(row.FieldsBlob);
+    let parsed;
+    try {
+      parsed = parseFieldsBlob(buf);
+    } catch {
+      continue; // not a keyed FieldsBlob — not a candidate
     }
+    const model = parsed.entries.find(e => e.key === 'FLStudioModelBA');
+    if (!model) continue;
+    modelRowCount += 1;
+    if (data) continue; // keep the first model-bearing row; count the rest
+    fieldsBlobBuf = buf;
+    entries = parsed.entries;
+    sequenceId = row.Sm2Sequence_id;
+    const fmt = parsed.entries.find(e => e.key === 'FirstMainBusFormat');
+    if (fmt) busFormat = fmt.rawValue.readUInt32BE(0);
+    rawBlob = model.rawValue.slice(4); // skip size prefix
+    data = decompressFLModel(rawBlob);
   }
 
-  if (!data) throw new Error('No FLStudioModelBA found in FieldsBlob');
+  if (!data) throw new Error('No FLStudioModelBA found in any Sm2Sequence FieldsBlob');
 
   const busConfig = readBusConfig(data);
 
@@ -247,6 +266,8 @@ function readFromDatabase(db) {
     rawBlob,
     fieldsBlobBuf,
     entries,
+    sequenceId,
+    modelRowCount,
     busNameOffset: busConfig.busNameOffset,
   };
 }
@@ -269,12 +290,22 @@ function readFromDatabase(db) {
  * @returns {{ success: boolean, details: string }}
  */
 function applyTemplate(db, templateData, options = {}) {
-  // Read existing FieldsBlob
-  const row = db.prepare('SELECT FieldsBlob FROM Sm2Sequence WHERE FieldsBlob IS NOT NULL').get();
-  if (!row) throw new Error('No Sm2Sequence with FieldsBlob found');
-
-  const fieldsBlobBuf = Buffer.from(row.FieldsBlob);
-  const { entries } = parseFieldsBlob(fieldsBlobBuf);
+  // Read the MODEL-BEARING FieldsBlob and remember which row it came from —
+  // the write below must target exactly that row. The old blanket
+  // `UPDATE ... WHERE FieldsBlob IS NOT NULL` stamped one timeline's blob
+  // into EVERY sequence row: compound clips' embedded sequences (whose blob
+  // carries their SeqRef container link), other timelines, everything —
+  // cross-wiring the project. Scoped by Sm2Sequence_id instead, and refused
+  // when several timelines carry models and no target was named.
+  const model = readFromDatabase(db);
+  if (model.modelRowCount > 1 && options.sequenceId === undefined) {
+    throw new Error(
+      `applyTemplate: ${model.modelRowCount} sequences carry a Fairlight model (multi-timeline project) — ` +
+        'pass options.sequenceId (Sm2Sequence_id) to name the target, or use the timeline-scoped actions.',
+    );
+  }
+  const targetSequenceId = options.sequenceId !== undefined ? options.sequenceId : model.sequenceId;
+  const { entries } = model;
 
   let patchedData = Buffer.from(templateData);
 
@@ -313,8 +344,8 @@ function applyTemplate(db, templateData, options = {}) {
   // Encode new FieldsBlob
   const newFieldsBlob = encodeFieldsBlob(newEntries);
 
-  // Write to database
-  db.prepare('UPDATE Sm2Sequence SET FieldsBlob = ? WHERE FieldsBlob IS NOT NULL').run(newFieldsBlob);
+  // Write to database — ONLY the row the model came from.
+  db.prepare('UPDATE Sm2Sequence SET FieldsBlob = ? WHERE Sm2Sequence_id = ?').run(newFieldsBlob, targetSequenceId);
 
   return {
     success: true,

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.136.1"
+VERSION = "2.138.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 353-tool granular server instead
 """
 
-VERSION = "2.136.1"
+VERSION = "2.138.0"
 
 import base64
 import os

package/src/utils/brain_edits.py

@@ -348,7 +348,7 @@ def update_brain_edits_registry(
     payload: Dict[str, Any]
     if os.path.isfile(path):
         try:
-            with open(path, "r") as fh:
+            with open(path, "r", encoding="utf-8") as fh:
                 payload = json.load(fh)
         except (OSError, json.JSONDecodeError):
             payload = {"entries": []}
@@ -368,7 +368,7 @@ def update_brain_edits_registry(
     payload["updated_at"] = _now_iso()
 
     tmp_path = path + ".tmp"
-    with open(tmp_path, "w") as fh:
+    with open(tmp_path, "w", encoding="utf-8") as fh:
         json.dump(payload, fh, indent=2, default=str)
     os.replace(tmp_path, path)
     return {"success": True, "registry_path": path, "entry_count": len(entries)}
@@ -379,7 +379,7 @@ def read_brain_edits_registry(project_root: str) -> Dict[str, Any]:
     if not os.path.isfile(path):
         return {"entries": [], "registry_path": path}
     try:
-        with open(path, "r") as fh:
+        with open(path, "r", encoding="utf-8") as fh:
             payload = json.load(fh)
     except (OSError, json.JSONDecodeError):
         return {"entries": [], "registry_path": path}

package/src/utils/page_lock.py

@@ -49,7 +49,7 @@ def page_lock():
     try:
         if _depth == 1 and _HAS_FCNTL:
             try:
-                _fh = open(_LOCKFILE, "w")
+                _fh = open(_LOCKFILE, "w", encoding="utf-8")
                 fcntl.flock(_fh, fcntl.LOCK_EX)
             except OSError:
                 # Advisory lock is best-effort; never block real work on it.