davinci-resolve-mcp 2.168.0 → 2.169.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 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.169.0 — E112: round-trip QC is colour-aware
+
+`verify_roundtrip` merged every generator leg out of the compare as "black",
+so a fade-to-white that came back black — or a colour matte that lost its
+colour — passed QC on geometry alone.
+
+### Added
+
+- **`verify_roundtrip` compares generator colours.** An input leg carrying a
+  fill colour must come back on the same track over its span with the same
+  colour (±1/255), else `generator-colour` fails; `generatorColours` reports
+  the compare. Black-only turnovers compare nothing and stay silent.
+
+### Fixed
+
+- **Resolve's own re-export of an authored colour reads back.** The FCP7
+  writer emits a Solid Color's colour as the FxPlug parameter `input_1`
+  (not Premiere's `fillcolor`); the walker now reads any RGB-valued
+  generator parameter. Live loop closed on 19.1.3.7: the E110 fade-to-white
+  turnover conformed, imported, rendered, re-exported, and verified
+  `pass: true` with both colours (white, and 128/64/191) compared — the
+  writer echoing the authored `EffectFiltersBA` is a second witness to the
+  blob layout. A black-for-white export fails as `generator-colour`.
+
+### Measured (filed in api-limitations)
+
+- The XML importer ignores a `Dip to Color Dissolve`'s colour parameter:
+  white and red imported as byte-identical default blobs and rendered inert.
+  The dip colour stays GUI-only on 19.1.3.7 (E111).
+
 ## What's New in v2.168.0 — E110: Solid Color has a colour — fade-to-white and colour mattes author
 
 The one thing the black-leg machinery could not do was be anything but

package/README.md

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

package/docs/reference/api-limitations.md

@@ -313,7 +313,7 @@ equivalent, blocking full automation.
 
 - **Object:** `MediaPool`
 - **Signature:** `(filePath.xml) -> Timeline`
-- **Behavior:** Resolve's FCP7 XML importer HONOURS a generatoritem's `fillcolor` parameter (measured on Studio 19.1.3.7, E110): a Premiere-shaped Color Matte (effectid Color, category Matte) and a Solid Color generatoritem, both with <red>/<green>/<blue>/<alpha> 0..255 values, imported as Solid Color items and rendered Y81 U90 V240 (red) and Y41 U240 V110 (blue) — exact BT.601 limited-range values for a 640x360 timeline. EXPORT_FCP_7_XML writes the fillcolor back (same 0..255 channels). EXPORT_DRT carries the colour as a 55-byte <EffectFiltersBA> on the Sm2TiGenerator: 8-byte header (version 2, length 47), a fixed 20-byte prefix, a flag byte, then big-endian uint16 A R G B (0xffff = full) plus a pad word, then a second, black colour record; only the ARGB words differed between the red and blue captures. The default generator has an EMPTY EffectFiltersBA.
+- **Behavior:** Resolve's FCP7 XML importer HONOURS a generatoritem's `fillcolor` parameter (measured on Studio 19.1.3.7, E110): a Premiere-shaped Color Matte (effectid Color, category Matte) and a Solid Color generatoritem, both with <red>/<green>/<blue>/<alpha> 0..255 values, imported as Solid Color items and rendered Y81 U90 V240 (red) and Y41 U240 V110 (blue) — exact BT.601 limited-range values for a 640x360 timeline. EXPORT_FCP_7_XML writes the fillcolor back (same 0..255 channels). EXPORT_DRT carries the colour as a 55-byte <EffectFiltersBA> on the Sm2TiGenerator: 8-byte header (version 2, length 47), a fixed 20-byte prefix, a flag byte, then big-endian uint16 A R G B (0xffff = full) plus a pad word, then a second, black colour record; only the ARGB words differed between the red and blue captures. The default generator has an EMPTY EffectFiltersBA. The same importer does NOT carry a TRANSITION's parameters: a `Dip to Color Dissolve` transitionitem with a white and with a red `color` parameter imported as `Dip To Color Dissolve` elements whose 37-byte EffectFiltersBA were byte-identical (defaults), and the transition rendered inert (luma flat through its window, the E66 law) — the dip colour stays GUI-only on 19.1.3.7 (measured, E111). The writer emits a Solid Color's colour as the FxPlug parameter `input_1` (effectid FxPlugWrapper:C18E8B62_…), not `fillcolor` — an authored EffectFiltersBA colour came back exactly (white, 128/64/191; E112).
 - **Workaround / current handling:** Author fade-to-white / colour mattes by placing a Solid Color generator with that blob (drp-format placeGenerator `color`, drt.assemble elements[].color) — or carry an XMEML generatoritem fillcolor through editorial.parse_interchange; the bridge authors the coloured leg.
 - **Tags:** xml, import, generator, colour, export, drt
 

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.168.0"
+VERSION = "2.169.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.168.0",
+  "version": "2.169.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

@@ -905,7 +905,7 @@ export function verifyRoundtrip(inputEvents, exportedEvents, opts = {}) {
     if (!v.length) return [];
     const off = anchorOfSide(evts);
     return v
-      .map((e) => ({ track: canonTrack(e.track), source: mapSource(canonSource(e.source)), recIn: e.recIn - off, recOut: e.recOut - off, srcIn: e.srcIn ?? 0, speed: e.speed ?? 100, reverse: Boolean(e.reverse) }))
+      .map((e) => ({ track: canonTrack(e.track), source: mapSource(canonSource(e.source)), recIn: e.recIn - off, recOut: e.recOut - off, srcIn: e.srcIn ?? 0, speed: e.speed ?? 100, reverse: Boolean(e.reverse), color: e.color && typeof e.color === 'object' ? { r: Number(e.color.r) || 0, g: Number(e.color.g) || 0, b: Number(e.color.b) || 0 } : null }))
       .sort((a, b) => a.track.localeCompare(b.track) || a.recIn - b.recIn);
   };
   // FADES (E94): BL legs on the input side and the Solid Color generators a
@@ -975,6 +975,30 @@ export function verifyRoundtrip(inputEvents, exportedEvents, opts = {}) {
 
   const a0 = norm(inputEvents);
   const b0 = norm(exportedEvents);
+  // GENERATOR COLOUR (E112): a black leg is only "black" by default — an
+  // XMEML fillcolor rides on it (fade-to-white, colour mattes; E110), and
+  // Resolve's FCP7 writer emits the colour back. Black legs still merge out
+  // of the pairwise geometry compare (their extents follow the picture), but
+  // every input leg that CARRIES a colour must find an exported leg on the
+  // same track overlapping its span with the same colour — a white fade that
+  // came back black is a conform error geometry alone cannot see.
+  const generatorColours = { compared: 0, mismatches: [] };
+  const colourKey = (c) => (c ? [c.r, c.g, c.b].map((v) => Math.round(v * 255)).join(',') : '0,0,0');
+  const colourTol = 1 / 255 + 1e-9;
+  const sameColour = (x, y) => ['r', 'g', 'b'].every((k) => Math.abs((x ? x[k] : 0) - (y ? y[k] : 0)) <= colourTol);
+  {
+    const inLegs = a0.filter((e) => isBlackSeg(e) && e.color);
+    const exLegs = b0.filter((e) => isBlackSeg(e));
+    for (const leg of inLegs) {
+      const partner = exLegs.find((x) => x.track === leg.track && x.recIn < leg.recOut && x.recOut > leg.recIn);
+      generatorColours.compared += 1;
+      if (!partner) {
+        generatorColours.mismatches.push({ kind: 'generator-colour', track: leg.track, record: [leg.recIn, leg.recOut], input: colourKey(leg.color), exported: null });
+      } else if (!sameColour(leg.color, partner.color)) {
+        generatorColours.mismatches.push({ kind: 'generator-colour', track: leg.track, record: [leg.recIn, leg.recOut], input: colourKey(leg.color), exported: colourKey(partner.color) });
+      }
+    }
+  }
   const a = a0.filter((e) => !isBlackSeg(e));
   const b = b0.filter((e) => !isBlackSeg(e));
   const blackSegments = { input: a0.length - a.length, exported: b0.length - b.length };
@@ -1042,8 +1066,10 @@ export function verifyRoundtrip(inputEvents, exportedEvents, opts = {}) {
     }
     mismatches.push(...markers.mismatches);
   }
+  mismatches.push(...generatorColours.mismatches);
   return {
     pass: mismatches.length === 0, pairs: n, srcOffsets, mismatches, markers,
+    ...(generatorColours.compared ? { generatorColours } : {}),
     ...(markersNotInExport ? { markersNotInExport } : {}),
     ...(blackSegments.input || blackSegments.exported ? { blackSegments } : {}),
     ...(fadeReshapedBoundaries.length ? { fadeReshapedBoundaries } : {}),

package/resolve-advanced/server/editorial.mjs

@@ -297,8 +297,10 @@ export function parseOTIO(otio, opts = {}) {
 function xmemlFillColor(g) {
   const params = g && g.effect && g.effect.parameter ? (Array.isArray(g.effect.parameter) ? g.effect.parameter : [g.effect.parameter]) : [];
   for (const pm of params) {
-    const pid = String(pm.parameterid || pm.name || '').trim().toLowerCase();
-    if (pid !== 'fillcolor' || !pm.value || typeof pm.value !== 'object') continue;
+    // Premiere writes the matte colour as `fillcolor`; Resolve's OWN writer
+    // emits a Solid Color's colour as the FxPlug input parameter `input_1`
+    // (measured E112) — any RGB-valued generator parameter is the colour.
+    if (!pm.value || typeof pm.value !== 'object' || pm.value.red == null || pm.value.green == null || pm.value.blue == null) continue;
     const ch = (k) => { const v = Number(pm.value[k]); return Number.isFinite(v) ? Math.max(0, Math.min(255, v)) / 255 : 0; };
     const c = { r: ch('red'), g: ch('green'), b: ch('blue'), a: pm.value.alpha != null ? ch('alpha') : 1 };
     if (c.r === 0 && c.g === 0 && c.b === 0) return null; // black = the default leg

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

@@ -86,7 +86,7 @@ const markerSchema = z.object({
 export const editorialTool = {
   name: 'editorial',
   description:
-    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively — incl. Resolve-written FCP7 -1 junction edges (paired in record order) + Solid Color / Color Matte generators carrying their `fillcolor` (BL legs with `color` → fade-to-white and colour mattes author, E110), XMEML audio-track transitionitems as audio cross-fades on numbered lanes A/A2/…, and CMX FROM/TO CLIP NAME comments over the generic AX reel — + AAF via pyaaf2 (flat sound/picture slots number A/A2/… and V/V2/… in slot order so separate beds keep their lanes; NestedScope layers keep layer numbering) + PRPROJ via gunzip+XML → normalized events incl. span-explicit transitions, BL fade legs, and freezes as zero-speed events (OTIO FreezeFrame, XMEML timeremap 0, PrProj in==out, AAF 0% motion effects); for AAF/PRPROJ pass the file PATH as content; AAF also returns per-sequence startTimecode/startFrame — build the timeline at THAT start, not the Resolve 01:00:00:00 default — and per-clip `geometry` for Avid transform effects), list_sequences (ONE offline picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}], plus startTimecode/startFrame for AAF), convert_to_interchange (author OTIO/EDL/DRT Resolve CAN import from events or a parsed source; the EDL target writes CMX transition pairs incl. BL fades — the .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions survive and per-clip effects/color do not. SPEED/REVERSE survive on the otio (LinearTimeWarp) and edl (M2) targets ONLY — this FLAT drt target flattens every retime to 100% forward and returns `flattened`/`flattenedCount` naming each event that lost one (`flattened` is always present on `drt`, empty when there were none); for a .drt that AUTHORS retimes/dissolves/multi-track/audio, use drt.assemble_from_interchange), turnover_changelist (diff old vs new → moved/retimed/trimmed/replaced/new/gone PLUS the junction diff: transition_added/transition_dropped/transition_changed with fade in/out or dissolve, outgoing/incoming, span and duration/type/pre-roll deltas — zero-length CMX carrier lines and the BL legs that carry fades fold into the junction diff instead of reading as gone/new sources; events pair by closest record position, consumed once, so a source cut twice at two speeds compares instance to instance; + timing flags incl. transition_dropped and dropped_split_audio on any A-track), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base; BL-aware — black legs need no source, fades no black-side handles, and a fade-out tail requirement lands on the picture source), marker_roundtrip (markers with provenance tags), verify_roundtrip (input events vs re-export events -> pass/mismatches + fitted per-source TC offsets + marker compare w/ markersNotInExport honesty flag; FADE-AWARE: BL/Solid-Color legs merge out as blackSegments and fade-window boundary reshapes are excused into fadeReshapedBoundaries instead of failing; RETIME-AWARE: speed/reverse compare pairwise — EXPORT_OTIO carries an authored Sm2TimeMap back as LinearTimeWarp (measured), so a flattened/lost retime fails as drift geometry alone cannot catch; AUDIO-AWARE: declared audio events compare (a video-only export such as EXPORT_EDL flags audioNotInExport instead of failing) (channel legs deduped, mismatches tagged trackType audio) while the mirrored-A1 export of a video-only turnover stays informational; the conform QC loop-closer). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
+    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively — incl. Resolve-written FCP7 -1 junction edges (paired in record order) + Solid Color / Color Matte generators carrying their `fillcolor` (BL legs with `color` → fade-to-white and colour mattes author, E110), XMEML audio-track transitionitems as audio cross-fades on numbered lanes A/A2/…, and CMX FROM/TO CLIP NAME comments over the generic AX reel — + AAF via pyaaf2 (flat sound/picture slots number A/A2/… and V/V2/… in slot order so separate beds keep their lanes; NestedScope layers keep layer numbering) + PRPROJ via gunzip+XML → normalized events incl. span-explicit transitions, BL fade legs, and freezes as zero-speed events (OTIO FreezeFrame, XMEML timeremap 0, PrProj in==out, AAF 0% motion effects); for AAF/PRPROJ pass the file PATH as content; AAF also returns per-sequence startTimecode/startFrame — build the timeline at THAT start, not the Resolve 01:00:00:00 default — and per-clip `geometry` for Avid transform effects), list_sequences (ONE offline picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}], plus startTimecode/startFrame for AAF), convert_to_interchange (author OTIO/EDL/DRT Resolve CAN import from events or a parsed source; the EDL target writes CMX transition pairs incl. BL fades — the .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions survive and per-clip effects/color do not. SPEED/REVERSE survive on the otio (LinearTimeWarp) and edl (M2) targets ONLY — this FLAT drt target flattens every retime to 100% forward and returns `flattened`/`flattenedCount` naming each event that lost one (`flattened` is always present on `drt`, empty when there were none); for a .drt that AUTHORS retimes/dissolves/multi-track/audio, use drt.assemble_from_interchange), turnover_changelist (diff old vs new → moved/retimed/trimmed/replaced/new/gone PLUS the junction diff: transition_added/transition_dropped/transition_changed with fade in/out or dissolve, outgoing/incoming, span and duration/type/pre-roll deltas — zero-length CMX carrier lines and the BL legs that carry fades fold into the junction diff instead of reading as gone/new sources; events pair by closest record position, consumed once, so a source cut twice at two speeds compares instance to instance; + timing flags incl. transition_dropped and dropped_split_audio on any A-track), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base; BL-aware — black legs need no source, fades no black-side handles, and a fade-out tail requirement lands on the picture source), marker_roundtrip (markers with provenance tags), verify_roundtrip (input events vs re-export events -> pass/mismatches + fitted per-source TC offsets + marker compare w/ markersNotInExport honesty flag; FADE-AWARE: BL/Solid-Color legs merge out as blackSegments and fade-window boundary reshapes are excused into fadeReshapedBoundaries instead of failing; RETIME-AWARE: speed/reverse compare pairwise — EXPORT_OTIO carries an authored Sm2TimeMap back as LinearTimeWarp (measured), so a flattened/lost retime fails as drift geometry alone cannot catch; AUDIO-AWARE: declared audio events compare (a video-only export such as EXPORT_EDL flags audioNotInExport instead of failing) (channel legs deduped, mismatches tagged trackType audio) while the mirrored-A1 export of a video-only turnover stays informational; COLOUR-AWARE: an input generator leg carrying a fillcolor (fade-to-white, colour matte) must come back on the same track over its span with the same colour — Resolve\'s FCP7 writer emits it — else generator-colour fails (generatorColours reports the compare); the conform QC loop-closer). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
   async handler({ action, args }) {
     if (action === 'parse_interchange') {
       const p = parseSchema.parse(args);

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.168.0"
+VERSION = "2.169.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.168.0"
+VERSION = "2.169.0"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -2813,7 +2813,18 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "A R G B (0xffff = full) plus a pad word, then a second, "
                    "black colour record; only the ARGB words differed between "
                    "the red and blue captures. The default generator has an "
-                   "EMPTY EffectFiltersBA.",
+                   "EMPTY EffectFiltersBA. The same importer does NOT carry a "
+                   "TRANSITION's parameters: a `Dip to Color Dissolve` "
+                   "transitionitem with a white and with a red `color` "
+                   "parameter imported as `Dip To Color Dissolve` elements "
+                   "whose 37-byte EffectFiltersBA were byte-identical "
+                   "(defaults), and the transition rendered inert (luma flat "
+                   "through its window, the E66 law) — the dip colour stays "
+                   "GUI-only on 19.1.3.7 (measured, E111). The writer emits "
+                   "a Solid Color's colour as the FxPlug parameter `input_1` "
+                   "(effectid FxPlugWrapper:C18E8B62_…), not `fillcolor` — an "
+                   "authored EffectFiltersBA colour came back exactly (white, "
+                   "128/64/191; E112).",
         "recommended": "Author fade-to-white / colour mattes by placing a "
                        "Solid Color generator with that blob "
                        "(drp-format placeGenerator `color`, drt.assemble "