davinci-resolve-mcp 2.108.0 → 2.111.0

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 33 missing capabilities, 41 bugs / unreliable behaviors.
+**Totals:** 33 missing capabilities, 42 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -526,6 +526,13 @@ values, or automation-hostile modal prompts.
 - **Reference:** [issue #171](https://github.com/samuelgursky/davinci-resolve-mcp/issues/171)
 - **Tags:** timeline, import, silent-failure, unreliable-return
 
+### Imported Fusion comps render via byte-keyed disk cache on 19.x (offline comp edits render black)
+
+- **Object:** `Fusion / render engine`
+- **Behavior:** On Studio 19.1.3.7, a Fusion composition arriving via timeline import renders only when the machine's Fusion disk cache (CacheClip/) holds frames keyed to the comp blob's EXACT bytes. Measured by discrimination: the untouched harvested title rendered its text; the same blob after an IDENTITY recompression — byte-identical Lua, different zlib bytes, verified consistent framing — imported, read back perfectly, and rendered black; a text-patched blob (also byte-verified) rendered black the same way. The live-render fallback for imported comps does not produce frames on 19; 21-generation hosts render imported comps live (the template-splice title/generator primitives were proven there).
+- **Workaround / current handling:** Never edit an imported comp's bytes offline for a 19.x host — no valid re-encoding can hit the cache. Author media offline (renders everywhere via the native-descriptor transplant) and set title text POST-IMPORT with timeline.set_title_text, whose Fusion-comp write path is live-verified on 19.1.3. Built-in GENERATORS are exempt: Sm2TiGenerator clips carry no Fusion comp, and offline-authored Solid Color / SMPTE Color Bar / Grey Scale all render live from an imported .drt (measured YAVG 16 / 104.9 / 125.1 over a 234 white base). Render-verify any imported Fusion TITLE before delivery; structural readback cannot see this.
+- **Tags:** fusion, render, import, silent-failure
+
 ### MediaPool.ImportTimelineFromFile (.drt requirements and filename naming)
 
 - **Object:** `MediaPool`

package/install.py

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

@@ -202,9 +202,11 @@ export function eventsToOTIO(events, opts = {}) {
  * timeline runs 24fps with origin 86400, so rec/src frames convert as
  * round(frames × 24 / nominalFps). Placement anchors the EARLIEST video
  * event at the origin. Honesty ledger in the returned report: flattened
- * retimes (the template clip schema has no per-clip speed), dropped
- * transitions (treated as cuts at their boundary), and skipped audio events
- * (cuts carry linked A1 audio from their own source already).
+ * retimes (the template clip schema has no per-clip speed), authored vs
+ * dropped transitions (cross-dissolves are AUTHORED when the predecessor
+ * abuts the cut and both sides have handle media — render-verified on
+ * 19.1.3.7; otherwise dropped with the reason, as a cut at the boundary),
+ * and skipped audio events (cuts carry linked A1 audio already).
  *
  * @param {Array} events - normalized events (parseInterchange shape)
  * @param {object} opts
@@ -238,6 +240,7 @@ export function eventsToAssembleSpec(events, opts = {}) {
   const toTl = (frames, fps) => Math.round((frames * 24) / Math.round(fps || 24));
   const flattenedRetimes = [];
   const droppedTransitions = [];
+  const transitionCandidates = [];
   const perSource = new Map();
   const placements = [];
 
@@ -250,11 +253,20 @@ export function eventsToAssembleSpec(events, opts = {}) {
     if ((e.speed ?? 100) !== 100 || e.reverse) {
       flattenedRetimes.push({ index: e.index, source: e.source, speed: e.speed, reverse: !!e.reverse });
     }
+    const cut = { startFrame: recIn, durationFrames, srcIn: toTl(e.srcIn ?? 0, e.fps) };
     if (e.transition) {
-      droppedTransitions.push({ index: e.index, type: e.transition.type, duration: e.transition.duration });
+      // A dissolve INTO this event, at its record-in boundary. Whether it can
+      // be authored (abutting predecessor + handles both sides) is decided
+      // after all placements are known.
+      let d = Math.max(2, toTl(e.transition.duration || 0, e.fps) || 2);
+      d += d % 2; // placeTransition centers on the cut; keep it even
+      transitionCandidates.push({
+        atFrame: recIn, durationFrames: d,
+        index: e.index, type: e.transition.type, rawDuration: e.transition.duration,
+        source: e.source, srcIn: cut.srcIn,
+      });
     }
-    const cut = { startFrame: recIn, durationFrames, srcIn: toTl(e.srcIn ?? 0, e.fps) };
-    placements.push({ start: recIn, end: recOut, index: e.index });
+    placements.push({ start: recIn, end: recOut, index: e.index, source: e.source, srcIn: cut.srcIn, durationFrames });
     if (!perSource.has(e.source)) perSource.set(e.source, []);
     perSource.get(e.source).push(cut);
   }
@@ -276,13 +288,44 @@ export function eventsToAssembleSpec(events, opts = {}) {
     cuts,
   }));
 
+  // Author cross-dissolves where the geometry allows it (render-verified on
+  // 19.1.3.7: an offline Sm2TiTransition over transplanted cross-source media
+  // blends 124→181.6→234 at the cut — transitions carry no Fusion comp, so
+  // the byte-keyed comp-cache law does not apply). A candidate is authorable
+  // when a predecessor ends EXACTLY at its cut and both sides have handle
+  // media for the centered span; anything else stays in droppedTransitions
+  // with the reason.
+  const transitions = [];
+  for (const c of transitionCandidates) {
+    const prev = placements.find((pl) => pl.end === c.atFrame);
+    if (!prev) {
+      droppedTransitions.push({ index: c.index, type: c.type, duration: c.rawDuration, reason: 'no abutting predecessor at the cut' });
+      continue;
+    }
+    const half = c.durationFrames / 2;
+    const bHandle = c.srcIn >= half;
+    const aSpec = sourceMap[prev.source] && sourceMap[prev.source].spec;
+    const aFrames = aSpec && Number(aSpec.frameCount);
+    const aHandle = Number.isFinite(aFrames) ? prev.srcIn + prev.durationFrames + half <= aFrames : false;
+    if (!bHandle || !aHandle) {
+      droppedTransitions.push({
+        index: c.index, type: c.type, duration: c.rawDuration,
+        reason: `insufficient handles for a centered ${c.durationFrames}f dissolve` +
+          `${bHandle ? '' : ' (incoming srcIn < half)'}${aHandle ? '' : ' (outgoing tail media < half)'}`,
+      });
+      continue;
+    }
+    transitions.push({ track: 1, atFrame: c.atFrame, durationFrames: c.durationFrames });
+  }
+
   return {
-    spec: { timelineName, media },
+    spec: { timelineName, media, ...(transitions.length ? { transitions } : {}) },
     report: {
       videoEvents: vids.length,
       sources: media.length,
       audioEventsSkipped: audioSkipped,
       flattenedRetimes,
+      authoredTransitions: transitions,
       droppedTransitions,
       origin: ORIGIN,
     },

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

@@ -46,7 +46,7 @@ const assembleSchema = z.object({
   spec: z
     .object({})
     .passthrough()
-    .describe("assembleTimeline spec: { timelineName?, media?: {mediaFilePath, spec:{width,height,frameCount,fps}, cuts:[{startFrame,durationFrames,srcIn?}]} | [same, ...] (multi-source needs media_pool.capture_media_template run once per file), elements?: [{type:'title'|'generator', track, startFrame, durationFrames?, text?, ...}], transitions? }. startFrame is timeline-absolute (origin 86400)."),
+    .describe("assembleTimeline spec: { timelineName?, media?: {mediaFilePath, spec:{width,height,frameCount,fps}, cuts:[{startFrame,durationFrames,srcIn?}]} | [same, ...] (multi-source needs media_pool.capture_media_template run once per file), elements?: [{type:'title'|'generator', track, startFrame, durationFrames?, text?, generatorName? ('Solid Color'|'SMPTE Color Bar'|'Grey Scale' render-verified on 19), ...}], transitions? }. 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()])
@@ -148,7 +148,7 @@ function requirePathArg(args, key, action) {
 export const drtTool = {
   name: 'drt',
   description:
-    'DaVinci Resolve Timeline (.drt) operations — offline, no Resolve required. Actions: assemble_from_interchange (EDL/OTIO/XML/AAF + sourceMap → IMPORTABLE RENDERING native .drt in one call; retimes flatten, transitions become cuts, ledger in `conform`), assemble (spec → IMPORTABLE native-schema .drt via template-spliced real structures; pass targetAppVersion e.g. \'19.1\' for pre-21 hosts), parse, list_sequences (enumerate the timelines inside a .drp/.drt → [{id,name,eventCount,index}] to drive a "which sequence?" picker), author, validate, inject_into_drp, extract_from_drp (pull one SeqContainer out as a .drt — feed the .drt to the Python davinci-resolve MCP timeline.import_timeline_checked, or use timeline.import_from_drp to do both), downgrade (stamp <ProjectVersion> down so an OLDER Resolve will import a .drt/.drp from a newer one — pass targetAppVersion like "19.1.3" or targetProjectVersion).',
+    'DaVinci Resolve Timeline (.drt) operations — offline, no Resolve required. Actions: assemble_from_interchange (EDL/OTIO/XML/AAF + sourceMap → IMPORTABLE RENDERING native .drt in one call; retimes flatten; cross-dissolves are AUTHORED when the cut abuts with handles both sides (render-verified on 19), else dropped with reason; ledger in `conform`), assemble (spec → IMPORTABLE native-schema .drt via template-spliced real structures; pass targetAppVersion e.g. \'19.1\' for pre-21 hosts), parse, list_sequences (enumerate the timelines inside a .drp/.drt → [{id,name,eventCount,index}] to drive a "which sequence?" picker), author, validate, inject_into_drp, extract_from_drp (pull one SeqContainer out as a .drt — feed the .drt to the Python davinci-resolve MCP timeline.import_timeline_checked, or use timeline.import_from_drp to do both), downgrade (stamp <ProjectVersion> down so an OLDER Resolve will import a .drt/.drp from a newer one — pass targetAppVersion like "19.1.3" or targetProjectVersion).',
   async handler({ action, args }) {
     if (action === 'parse') {
       const p = parseSchema.parse(requirePathArg(args, 'drtPath', 'parse'));
@@ -284,12 +284,17 @@ export const drtTool = {
         stamped,
         templateVersion: spec.templateVersion ?? 21,
         mediaDescriptor: mediaDescriptor ?? 'none',
-        ...((spec.elements || []).length && (spec.templateVersion ?? 21) < 21
+        ...((spec.elements || []).some((e) => e && e.type === 'title') && (spec.templateVersion ?? 21) < 21
           ? {
               elementsWarning:
-                'title/generator elements on a pre-21 host are NOT render-verified: the harvested ' +
-                'snippets are Resolve-21 structures, which import and read back correctly but render ' +
-                'black on 19.1.3 (measured). Media cuts render; verify element output before delivery.',
+                'On a pre-21 host, imported Fusion TITLE comps render only via the machine\'s ' +
+                'Fusion disk cache, keyed to the EXACT comp bytes (measured: an identity ' +
+                'recompression rendered black) — offline-authored titles may render black and ' +
+                'offline text patching cannot work there. The working pre-21 title flow: assemble ' +
+                'without title text, then set it post-import with timeline.set_title_text (its ' +
+                'Fusion-comp path is live-verified on 19.1.3). Media cuts and built-in GENERATORS ' +
+                '(Solid Color / SMPTE Color Bar / Grey Scale — plain Sm2TiGenerator, no Fusion ' +
+                'comp) render everywhere: generator kinds render-verified on 19.1.3.',
             }
           : {}),
         ...(mediaDescriptor === 'repoint-fallback'

package/resolve-advanced/vendor/drp-format/composition-text.js

@@ -82,6 +82,15 @@ function rewriteInner(hex, transform) {
   const b = Buffer.from(hex, 'hex');
   const outer = zlib.inflateSync(b.subarray(4));
 
+  // NOTE (measured 2026-08-30, Studio 19.1.3.7): the mechanics below are
+  // generation-agnostic and byte-correct — a patched blob re-inflates with
+  // StyledText updated and consistent framing. But on 19, IMPORTED comps
+  // render only via the machine's Fusion disk cache, keyed to the EXACT
+  // compressed bytes: even an identity reframe (same Lua, different
+  // compression) rendered black, while the untouched harvest rendered its
+  // cached frames. Offline text patching therefore works on 21-generation
+  // hosts (live Fusion render) and CANNOT work on 19 imports — set text
+  // post-import with timeline.set_title_text instead.
   const marker = outer.lastIndexOf(COMPRESSED_MARKER);
   if (marker < 0) throw new Error('composition-text: composition marker not found (unexpected framing)');
   const zNull = outer.indexOf(0x00, marker);

package/resolve-advanced/vendor/drp-format/place-fusion-title.js

@@ -42,16 +42,7 @@ const TEMPLATE_PATH = path.join(__dirname, 'templates', 'fusion-title.xml');
 // harvested live from Studio 19.1.3.7.
 const TEMPLATE_PATH_R19 = path.join(__dirname, 'templates', 'fusion-title-r19.xml');
 function snippetPathFor(templateVersion) {
-  // The r19 snippets are harvested but NOT yet render-viable: the generator's
-  // separate Sm2TiCompositionTable dependency is not carried, and the title's
-  // comp-blob patching assumes the R21 layout — with them, render jobs FAIL
-  // outright (measured), which is worse than the R21 snippet's silent black.
-  // Selection stays on the R21 snippet for every generation until the element
-  // transplant (comp table + per-generation blob patch) lands; drt.assemble
-  // warns when elements target a pre-21 host.
-  void templateVersion;
-  void TEMPLATE_PATH_R19;
-  return TEMPLATE_PATH;
+  return (Number(templateVersion) || 21) >= 21 ? TEMPLATE_PATH : TEMPLATE_PATH_R19;
 }
 
 /**

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

@@ -9,7 +9,10 @@
  *
  * Clone-based: carry the bundled Solid Color template and swap PrettyType/Name/Start/
  * Duration + a fresh DbId. The same Sm2TiGenerator shape serves the other simple built-in
- * generators by changing PrettyType (verify per type before relying on it).
+ * generators by changing PrettyType — RENDER-VERIFIED on Studio 19.1.3.7 (2026-08-30):
+ * Solid Color YAVG 16 over white 234, SMPTE Color Bar 104.9, Grey Scale 125.1, all from a
+ * fully offline-authored .drt. Unlike Fusion titles, Sm2TiGenerator has no comp blob, so
+ * the byte-keyed Fusion render-cache law does NOT apply: generators render live everywhere.
  *
  * @module drp-format/place-generator
  */
@@ -32,16 +35,7 @@ const TEMPLATE_PATH_R19 = path.join(__dirname, 'templates', 'generator-solid-col
 // Generation-bound like every other harvested structure (R21 snippet renders
 // black on 19 — measured); r19 variant harvested live from 19.1.3.7.
 function snippetPathFor(templateVersion) {
-  // The r19 snippets are harvested but NOT yet render-viable: the generator's
-  // separate Sm2TiCompositionTable dependency is not carried, and the title's
-  // comp-blob patching assumes the R21 layout — with them, render jobs FAIL
-  // outright (measured), which is worse than the R21 snippet's silent black.
-  // Selection stays on the R21 snippet for every generation until the element
-  // transplant (comp table + per-generation blob patch) lands; drt.assemble
-  // warns when elements target a pre-21 host.
-  void templateVersion;
-  void TEMPLATE_PATH_R19;
-  return TEMPLATE_PATH;
+  return (Number(templateVersion) || 21) >= 21 ? TEMPLATE_PATH : TEMPLATE_PATH_R19;
 }
 
 /**

package/resolve-advanced/vendor/drp-format/templates/fusion-title-r19.xml

@@ -1,3 +1,4 @@
+<Element>
 <Sm2TiVideoClip DbId="8c729549-aded-4c80-b143-c1fce23c5712">
        <FieldsBlob>0000000200000027800a120a0e2205546578742b4a05546578742b200112100000000000000005ffffffffffffffff</FieldsBlob>
        <PrettyType>Fusion Title</PrettyType>
@@ -52,3 +53,4 @@
        </Thumbnail>
        <ThumbnailDirtyFlag>true</ThumbnailDirtyFlag>
       </Sm2TiVideoClip>
+</Element>

package/resolve-advanced/vendor/drp-format/templates/generator-solid-color-r19.xml

@@ -1,3 +1,4 @@
+<Element>
 <Sm2TiGenerator DbId="9d9cd9a6-f64f-49b9-a661-18f4f9c51781">
        <FieldsBlob/>
        <PrettyType>Solid Color</PrettyType>
@@ -17,3 +18,4 @@
        <RenderTextPrefixed>true</RenderTextPrefixed>
        <In/>
       </Sm2TiGenerator>
+</Element>

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.108.0"
+VERSION = "2.111.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.108.0"
+VERSION = "2.111.0"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -1914,6 +1914,38 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "structural readback cannot see this class.",
         "tags": ["media-pool", "import", "render", "silent-failure", "readback"],
     },
+    {
+        "symbol": "Imported Fusion comps render via byte-keyed disk cache on 19.x (offline comp edits render black)",
+        "object": "Fusion / render engine",
+        "reality": "On Studio 19.1.3.7, a Fusion composition arriving via "
+                   "timeline import renders only when the machine's Fusion "
+                   "disk cache (CacheClip/) holds frames keyed to the comp "
+                   "blob's EXACT bytes. Measured by discrimination: the "
+                   "untouched harvested title rendered its text; the same "
+                   "blob after an IDENTITY recompression — byte-identical "
+                   "Lua, different zlib bytes, verified consistent framing — "
+                   "imported, read back perfectly, and rendered black; a "
+                   "text-patched blob (also byte-verified) rendered black "
+                   "the same way. The live-render fallback for imported "
+                   "comps does not produce frames on 19; 21-generation "
+                   "hosts render imported comps live (the template-splice "
+                   "title/generator primitives were proven there).",
+        "recommended": "Never edit an imported comp's bytes offline for a "
+                       "19.x host — no valid re-encoding can hit the cache. "
+                       "Author media offline (renders everywhere via the "
+                       "native-descriptor transplant) and set title text "
+                       "POST-IMPORT with timeline.set_title_text, whose "
+                       "Fusion-comp write path is live-verified on 19.1.3. "
+                       "Built-in GENERATORS are exempt: Sm2TiGenerator "
+                       "clips carry no Fusion comp, and offline-authored "
+                       "Solid Color / SMPTE Color Bar / Grey Scale all "
+                       "render live from an imported .drt (measured YAVG "
+                       "16 / 104.9 / 125.1 over a 234 white base). "
+                       "Render-verify any imported Fusion TITLE before "
+                       "delivery; structural readback cannot see this.",
+        "tags": ["fusion", "render", "import", "silent-failure"],
+        "submit": "bug",
+    },
     {
         "symbol": "MediaPool.ImportTimelineFromFile (.drt requirements and filename naming)",
         "object": "MediaPool",