davinci-resolve-mcp 2.106.0 → 2.108.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.108.0
+
+**The conform emulator, coast to coast.** An interchange file goes in; an
+importable, RENDERING native .drt comes out — one call.
+
+### Added
+
+- **`drt.assemble_from_interchange`**: EDL/OTIO/XML/AAF + a sourceMap
+  (reel → {mediaFilePath, spec}) → parse → frame-convert → multi-source
+  assemble with native-descriptor transplant → stamped .drt. The
+  events→spec bridge (`eventsToAssembleSpec`) anchors the earliest video
+  event at the timeline origin, converts nominal-base event frames to the
+  24fps template timeline (round(frames × 24 / nominalFps) — butt cuts stay
+  gapless through the conversion, verified at 29.97), groups cuts per
+  source, refuses overlapping record ranges and unmapped reels loudly, and
+  returns an honesty ledger: flattened retimes (the clip schema has no
+  per-clip speed), transitions treated as cuts, audio events skipped (cuts
+  carry their own linked A1).
+
+Live-proofed on Studio 19.1.3.7 with the full route: a three-event EDL
+cutting between two sources (with an M2 retime line) assembled, imported
+6/6 linked with exact source in-points, and rendered each event's OWN
+pixels — YAVG 125.6 / 234 / 125.5 — with a full-range render verifying at
+duration ratio 1.0 and the retime present in the ledger.
+
+### Scoped honestly
+
+Title/generator elements on a pre-21 host are NOT render-verified: the
+harvested snippets are Resolve-21 structures that import and read back
+correctly but render black on 19.1.3 (measured), and the r19 snippet
+harvest is incomplete (the generator's Sm2TiCompositionTable dependency,
+the title's per-generation comp-blob layout) — with the partial harvest,
+render jobs fail outright, which is worse. Snippet selection stays on the
+R21 structures, `drt.assemble` warns when elements target a pre-21 host,
+and the harvested r19 snippets ship in the templates directory for the
+element-transplant expedition. Media cuts render everywhere the transplant
+path covers.
+
+## What's New in v2.107.0
+
+**Multi-source media authoring.** `drt.assemble`'s media support grows from
+one source to many: `media` accepts an array of `{mediaFilePath, spec, cuts}`
+sources, each cut landing on the shared V1/A1 with its own source's
+transplanted native descriptors. New plumbing: `insertMediaElement` appends
+additional native pool elements into MpFolder's MediaVec (folder-parent id
+adopted), and `cutSourceIntoClips` accepts a per-cut `mediaRef` so each clone
+points at ITS source. Multi-source strictly requires a captured native
+template for every source (the render-verified transplant path); the refusal
+names `media_pool.capture_media_template` per missing file — a repoint
+fallback that renders black across N sources would be a trap, not a feature.
+
+Live-verified end to end on Studio 19.1.3.7 with luma fingerprints: a
+timeline interleaving cuts from two sources (testsrc + solid white) imported
+6/6 linked and rendered each cut's OWN pixels — YAVG 125.6 / 234 / 125.5
+across the three cuts, matching each source's signature exactly.
+
 ## What's New in v2.106.0
 
 **Media clips in native DRT authoring — cut real footage into an importable,

package/README.md

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

package/install.py

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

@@ -192,6 +192,103 @@ export function eventsToOTIO(events, opts = {}) {
 }
 
 /** Build a CMX3600 EDL string (cuts + M2 speed). Video events only, per EDL convention. */
+/**
+ * eventsToAssembleSpec — normalized interchange events → drt.assemble media spec.
+ *
+ * The coast-to-coast bridge: parseInterchange's events (EDL/AAF/OTIO/XML)
+ * become an importable, RENDERING native .drt via assembleTimeline's
+ * transplant path. Frame math: event frames are NOMINAL-base at the event's
+ * fps (v2.104.6 convention, measured against Resolve); the assemble template
+ * 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).
+ *
+ * @param {Array} events - normalized events (parseInterchange shape)
+ * @param {object} opts
+ * @param {Object<string,{mediaFilePath:string, spec:object}>} opts.sourceMap -
+ *   event.source (reel) → media file + spec. Every VIDEO event's source must
+ *   be mapped; unmapped reels refuse with the reel names listed.
+ * @param {string} [opts.timelineName]
+ * @returns {{spec: object, report: object}}
+ */
+export function eventsToAssembleSpec(events, opts = {}) {
+  const { sourceMap, timelineName } = opts;
+  if (!Array.isArray(events) || !events.length) {
+    throw new TypeError('eventsToAssembleSpec: events must be a non-empty array');
+  }
+  if (!sourceMap || typeof sourceMap !== 'object') {
+    throw new TypeError('eventsToAssembleSpec: sourceMap {reel: {mediaFilePath, spec}} is required');
+  }
+  const ORIGIN = 86400;
+  const vids = events.filter((e) => e.track !== 'A' && e.recIn != null && e.recOut != null);
+  const audioSkipped = events.length - vids.length;
+  if (!vids.length) throw new Error('eventsToAssembleSpec: no video events with record ranges');
+
+  const unmapped = [...new Set(vids.map((e) => e.source).filter((srcName) => !sourceMap[srcName]))];
+  if (unmapped.length) {
+    throw new Error(
+      `eventsToAssembleSpec: unmapped source reel(s): ${unmapped.join(', ')} — ` +
+      'every video event needs a sourceMap entry {mediaFilePath, spec}',
+    );
+  }
+
+  const toTl = (frames, fps) => Math.round((frames * 24) / Math.round(fps || 24));
+  const flattenedRetimes = [];
+  const droppedTransitions = [];
+  const perSource = new Map();
+  const placements = [];
+
+  const minRec = Math.min(...vids.map((e) => toTl(e.recIn, e.fps)));
+  for (const e of vids) {
+    const recIn = ORIGIN + (toTl(e.recIn, e.fps) - minRec);
+    const recOut = ORIGIN + (toTl(e.recOut, e.fps) - minRec);
+    const durationFrames = recOut - recIn;
+    if (durationFrames <= 0) continue;
+    if ((e.speed ?? 100) !== 100 || e.reverse) {
+      flattenedRetimes.push({ index: e.index, source: e.source, speed: e.speed, reverse: !!e.reverse });
+    }
+    if (e.transition) {
+      droppedTransitions.push({ index: e.index, type: e.transition.type, duration: e.transition.duration });
+    }
+    const cut = { startFrame: recIn, durationFrames, srcIn: toTl(e.srcIn ?? 0, e.fps) };
+    placements.push({ start: recIn, end: recOut, index: e.index });
+    if (!perSource.has(e.source)) perSource.set(e.source, []);
+    perSource.get(e.source).push(cut);
+  }
+
+  placements.sort((a, b) => a.start - b.start);
+  for (let i = 1; i < placements.length; i += 1) {
+    if (placements[i].start < placements[i - 1].end) {
+      throw new Error(
+        `eventsToAssembleSpec: events ${placements[i - 1].index} and ${placements[i].index} ` +
+        'overlap on the record track after frame conversion — a single V1 cannot hold both. ' +
+        'Resolve the overlap upstream (transitions count as cuts at their boundary here).',
+      );
+    }
+  }
+
+  const media = [...perSource.entries()].map(([reel, cuts]) => ({
+    mediaFilePath: sourceMap[reel].mediaFilePath,
+    spec: sourceMap[reel].spec,
+    cuts,
+  }));
+
+  return {
+    spec: { timelineName, media },
+    report: {
+      videoEvents: vids.length,
+      sources: media.length,
+      audioEventsSkipped: audioSkipped,
+      flattenedRetimes,
+      droppedTransitions,
+      origin: ORIGIN,
+    },
+  };
+}
+
 export function eventsToEDL(events, opts = {}) {
   const fps = opts.fps || events.find((e) => e.fps)?.fps || 24;
   const vids = events.filter((e) => e.track !== 'A').sort((a, b) => (a.recIn ?? 0) - (b.recIn ?? 0));

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

@@ -29,11 +29,24 @@ const authorSchema = z.object({
   outputPath: z.string().describe('Absolute path where the .drt will be written'),
 });
 const validateSchema = z.object({ drtPath: z.string().describe('Absolute path to a .drt file') });
+const assembleFromInterchangeSchema = z.object({
+  format: z.enum(['edl', 'otio', 'xml', 'aaf']).describe('Interchange format of the input'),
+  path: z.string().optional().describe('Path to the interchange file (aaf REQUIRES a path)'),
+  content: z.string().optional().describe('Inline interchange text (edl/otio/xml)'),
+  fps: z.number().optional().describe('Event frame rate for parsing (default 24; use e.g. 29.97 for NTSC EDLs)'),
+  sourceMap: z
+    .record(z.object({ mediaFilePath: z.string(), spec: z.object({}).passthrough() }))
+    .describe('reel/source name → {mediaFilePath, spec:{width,height,frameCount,fps}}; every video event must map'),
+  timelineName: z.string().optional(),
+  outputPath: z.string().describe('Where the importable .drt is written'),
+  targetAppVersion: z.union([z.string(), z.number()]).optional()
+    .describe("Host Resolve version, e.g. '19.1' for pre-21"),
+});
 const assembleSchema = z.object({
   spec: z
     .object({})
     .passthrough()
-    .describe("assembleTimeline spec: { timelineName?, 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?, ...}], 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()])
@@ -135,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 (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, 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).',
   async handler({ action, args }) {
     if (action === 'parse') {
       const p = parseSchema.parse(requirePathArg(args, 'drtPath', 'parse'));
@@ -190,6 +203,52 @@ export const drtTool = {
       await fs.writeFile(p.outputPath, outBuf);
       return { outputPath: p.outputPath, bytes: outBuf.length, seqContainersInjected: injected, projectFolder };
     }
+    if (action === 'assemble_from_interchange') {
+      // Coast-to-coast conform: interchange in, importable RENDERING .drt out.
+      const p = assembleFromInterchangeSchema.parse(args);
+      const { parseInterchange } = await import('../editorial.mjs');
+      const { eventsToAssembleSpec } = await import('../author-interchange.mjs');
+      let content = p.content;
+      if (p.format === 'aaf') {
+        if (!p.path) return { error: 'aaf input requires path' };
+        content = p.path;
+      } else if (!content) {
+        if (!p.path) return { error: 'provide content or path' };
+        content = await fs.readFile(p.path, 'utf8');
+      }
+      const events = parseInterchange(p.format, content, { fps: p.fps ?? 24 });
+      if (!events || !events.length) return { error: 'no events parsed from the interchange input' };
+      const { spec, report } = eventsToAssembleSpec(events, {
+        sourceMap: p.sourceMap, timelineName: p.timelineName,
+      });
+      if (p.targetAppVersion !== undefined) {
+        spec.templateVersion = parseFloat(p.targetAppVersion) >= 21 ? 21 : 19;
+      }
+      const { assembleTimeline } = drp();
+      const { buffer, timelineName, mediaDescriptor } = await assembleTimeline(spec);
+      let outBuf = buffer;
+      let stamped = null;
+      if (p.targetAppVersion !== undefined) {
+        const targetPV = resolveTargetProjectVersion({ targetAppVersion: p.targetAppVersion });
+        const appVer = `${p.targetAppVersion}${'.0'.repeat(Math.max(0, 4 - String(p.targetAppVersion).split('.').length))}`;
+        const zip = await JSZip.loadAsync(buffer);
+        const { out } = await applyVersionStamps(zip, targetPV, appVer);
+        outBuf = await out.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+        stamped = { targetProjectVersion: targetPV };
+      }
+      await fs.writeFile(p.outputPath, outBuf);
+      return {
+        outputPath: p.outputPath,
+        bytes: outBuf.length,
+        timelineName,
+        mediaDescriptor,
+        stamped,
+        conform: report,
+        note:
+          'Import with timeline.import_timeline_checked (timeline is named after the FILE). ' +
+          'Retimes are flattened and transitions become cuts — see `conform` for the ledger.',
+      };
+    }
     if (action === 'assemble') {
       const p = assembleSchema.parse(args);
       // Native-schema authoring: template-spliced real Resolve structures
@@ -225,6 +284,14 @@ export const drtTool = {
         stamped,
         templateVersion: spec.templateVersion ?? 21,
         mediaDescriptor: mediaDescriptor ?? 'none',
+        ...((spec.elements || []).length && (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.',
+            }
+          : {}),
         ...(mediaDescriptor === 'repoint-fallback'
           ? {
               warning:

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

@@ -22,7 +22,7 @@
  */
 
 const { createEmptyProject, addMediaClip, DEFAULT_START_FRAME } = require('./author-project');
-const { loadMediaTemplate, transplantMediaElement } = require('./media-template-cache');
+const { loadMediaTemplate, transplantMediaElement, insertMediaElement } = require('./media-template-cache');
 const JSZip = require('jszip');
 const { cutSourceIntoClips } = require('./cut-media');
 const { placeFusionTitle } = require('./place-fusion-title');
@@ -35,24 +35,31 @@ async function assembleTimeline(spec = {}) {
   if (!Array.isArray(transitions)) throw new TypeError('assembleTimeline: transitions must be an array');
 
   let base;
+  let mediaDescriptorState = 'none';
   if (media) {
-    // Media authoring: ONE source file, cut into N placements — the template
-    // media pool holds one media entry, so multi-source is refused honestly
-    // rather than half-built.
-    if (Array.isArray(media)) {
-      throw new TypeError('assembleTimeline: media must be a single {mediaFilePath, spec, cuts} object — multi-source authoring is not supported yet');
+    // Media authoring: cut one or MORE sources into placements. Every source
+    // carries {mediaFilePath, spec, cuts}. Multi-source requires a native
+    // media template CAPTURED for every source (capture-once transplant is
+    // the only measured way authored media renders); single-source may fall
+    // back to descriptor repoint, which imports but usually will not render.
+    const sources = Array.isArray(media) ? media : [media];
+    if (!sources.length) throw new TypeError('assembleTimeline: media must not be empty');
+    const caches = sources.map((src) => loadMediaTemplate(src.mediaFilePath));
+    if (sources.length > 1) {
+      const missing = sources.filter((src, i) => !caches[i]).map((src) => src.mediaFilePath);
+      if (missing.length) {
+        throw new Error(
+          'assembleTimeline: multi-source authoring requires a captured native media template for EVERY source — ' +
+          `missing for: ${missing.join(', ')}. Run media_pool.capture_media_template(path) with Resolve open for each.`,
+        );
+      }
     }
-    const { mediaFilePath, spec: mediaSpec, cuts } = media;
-    base = await addMediaClip({ mediaFile: mediaFilePath, spec: mediaSpec, timelineName, templateVersion });
-    base.startFrame = DEFAULT_START_FRAME;
-    if (Array.isArray(cuts) && cuts.length) {
-      // Placement guards, loudly: clips before the timeline origin are
-      // DROPPED by Resolve on import with no error, and a source range past
-      // the media's end reads back as a truncated clip.
-      cuts.forEach((cut, i) => {
+    const validateCuts = (src, label) => {
+      const mediaSpec = src.spec;
+      (src.cuts || []).forEach((cut, i) => {
         if (cut.startFrame < DEFAULT_START_FRAME) {
           throw new RangeError(
-            `assembleTimeline: media.cuts[${i}].startFrame ${cut.startFrame} is before the timeline origin ${DEFAULT_START_FRAME} — Resolve silently drops it on import`,
+            `assembleTimeline: ${label}.cuts[${i}].startFrame ${cut.startFrame} is before the timeline origin ${DEFAULT_START_FRAME} — Resolve silently drops it on import`,
           );
         }
         if (mediaSpec && Number.isFinite(mediaSpec.frameCount) && Number.isFinite(mediaSpec.fps)) {
@@ -61,12 +68,55 @@ async function assembleTimeline(spec = {}) {
           const maxTimelineFrames = Math.floor((mediaSpec.frameCount / mediaSpec.fps) * 24);
           if ((cut.srcIn ?? 0) + cut.durationFrames > maxTimelineFrames) {
             throw new RangeError(
-              `assembleTimeline: media.cuts[${i}] reads past the media's end — (srcIn ?? 0) + durationFrames exceeds ${maxTimelineFrames} timeline frames (media ${mediaSpec.frameCount} frames @ ${mediaSpec.fps} fps on the 24fps template timeline)`,
+              `assembleTimeline: ${label}.cuts[${i}] reads past the media's end — (srcIn ?? 0) + durationFrames exceeds ${maxTimelineFrames} timeline frames (media ${mediaSpec.frameCount} frames @ ${mediaSpec.fps} fps on the 24fps template timeline)`,
             );
           }
         }
       });
-      const cutRes = await cutSourceIntoClips(base.buffer, { cuts });
+    };
+    sources.forEach((src, i) => validateCuts(src, sources.length > 1 ? `media[${i}]` : 'media'));
+
+    base = await addMediaClip({
+      mediaFile: sources[0].mediaFilePath, spec: sources[0].spec, timelineName, templateVersion,
+    });
+    base.startFrame = DEFAULT_START_FRAME;
+
+    // Transplant/insert native pool elements BEFORE cutting, so each cut can
+    // reference its source's MediaRef.
+    let zip = await JSZip.loadAsync(base.buffer);
+    const mpPath = 'MediaPool/Master/MpFolder.xml';
+    let mpXml = await zip.file(mpPath).async('string');
+    const seqNames = Object.keys(zip.files).filter((n) => /SeqContainer\/.+\.xml$/.test(n) || /\/SeqContainer\d*\.xml$/.test(n));
+    const seqXmls = [];
+    for (const n of seqNames) seqXmls.push(await zip.file(n).async('string'));
+    const mediaRefs = [];
+    if (caches[0]) {
+      const res = transplantMediaElement(mpXml, seqXmls, caches[0]);
+      mpXml = res.mpXml;
+      for (let i = 0; i < seqNames.length; i += 1) seqXmls[i] = res.seqXmls[i];
+      mediaRefs[0] = caches[0].mediaRef;
+      mediaDescriptorState = 'native-transplant';
+    } else {
+      mediaRefs[0] = null; // donor already points at the repointed entry
+      mediaDescriptorState = 'repoint-fallback';
+    }
+    for (let i = 1; i < sources.length; i += 1) {
+      mpXml = insertMediaElement(mpXml, caches[i].poolElement);
+      mediaRefs[i] = caches[i].mediaRef;
+    }
+    zip.file(mpPath, mpXml);
+    seqNames.forEach((n, i) => zip.file(n, seqXmls[i]));
+    base.buffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+
+    const allCuts = [];
+    sources.forEach((src, i) => {
+      (src.cuts || []).forEach((cut) => {
+        allCuts.push(mediaRefs[i] ? { ...cut, mediaRef: mediaRefs[i] } : { ...cut });
+      });
+    });
+    allCuts.sort((a, b) => a.startFrame - b.startFrame);
+    if (allCuts.length) {
+      const cutRes = await cutSourceIntoClips(base.buffer, { cuts: allCuts });
       base.buffer = cutRes.buffer;
     }
   } else {
@@ -81,12 +131,12 @@ async function assembleTimeline(spec = {}) {
       ({ buffer } = await placeFusionTitle(buffer, {
         trackIndex: el.track, startFrame: el.startFrame, durationFrames: el.durationFrames,
         text: el.text, font: el.font, style: el.style, size: el.size, color: el.color,
-        vJustify: el.vJustify, hJustify: el.hJustify, name: el.name,
+        vJustify: el.vJustify, hJustify: el.hJustify, name: el.name, templateVersion,
       }));
     } else if (el.type === 'generator') {
       ({ buffer } = await placeGenerator(buffer, {
         generatorName: el.generatorName, trackIndex: el.track,
-        startFrame: el.startFrame, durationFrames: el.durationFrames,
+        startFrame: el.startFrame, durationFrames: el.durationFrames, templateVersion,
       }));
     } else {
       throw new Error(`assembleTimeline: elements[${i}] unknown type "${el.type}" (title|generator)`);
@@ -100,32 +150,7 @@ async function assembleTimeline(spec = {}) {
     }));
   }
 
-  // Native-descriptor transplant: when a live-captured media template exists
-  // for this file, swap the pool media element and rewire MediaRefs — the
-  // only measured way an authored timeline's media actually RENDERS (the
-  // repoint fallback imports and reads back fine but the render engine
-  // refuses or paints black; see media-template-cache).
-  let mediaDescriptor = 'none';
-  if (media && media.mediaFilePath) {
-    const cached = loadMediaTemplate(media.mediaFilePath);
-    if (cached) {
-      const zip = await JSZip.loadAsync(buffer);
-      const mpPath = 'MediaPool/Master/MpFolder.xml';
-      const seqNames = Object.keys(zip.files).filter((n) => /SeqContainer\/.+\.xml$/.test(n) || /\/SeqContainer\d*\.xml$/.test(n));
-      const mpXml = await zip.file(mpPath).async('string');
-      const seqXmls = [];
-      for (const n of seqNames) seqXmls.push(await zip.file(n).async('string'));
-      const res = transplantMediaElement(mpXml, seqXmls, cached);
-      zip.file(mpPath, res.mpXml);
-      seqNames.forEach((n, i) => zip.file(n, res.seqXmls[i]));
-      buffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
-      mediaDescriptor = 'native-transplant';
-    } else {
-      mediaDescriptor = 'repoint-fallback';
-    }
-  }
-
-  return { buffer, timelineName: tlName, startFrame, mediaDescriptor };
+  return { buffer, timelineName: tlName, startFrame, mediaDescriptor: mediaDescriptorState };
 }
 
 module.exports = { assembleTimeline };

package/resolve-advanced/vendor/drp-format/cut-media.js

@@ -49,6 +49,9 @@ async function cutSourceIntoClips(drpInput, opts = {}) {
     if (cut.srcIn !== undefined && (!Number.isInteger(cut.srcIn) || cut.srcIn < 0)) {
       throw new TypeError(`cutSourceIntoClips: cuts[${i}].srcIn must be a non-negative integer`);
     }
+    if (cut.mediaRef !== undefined && !/^[0-9a-f-]{36}$/.test(cut.mediaRef)) {
+      throw new TypeError(`cutSourceIntoClips: cuts[${i}].mediaRef must be a uuid`);
+    }
   });
 
   const zip = await loadDrpZip(drpInput);
@@ -68,6 +71,11 @@ async function cutSourceIntoClips(drpInput, opts = {}) {
       c = setClipStart(c, cut.startFrame);
       c = setClipDuration(c, cut.durationFrames);
       c = setClipIn(c, cut.srcIn ?? 0);
+      if (cut.mediaRef) {
+        // Multi-source: point this cut at ITS source's transplanted pool
+        // element instead of the donor's.
+        c = c.replace(/<MediaRef>[0-9a-f-]{36}<\/MediaRef>/, `<MediaRef>${cut.mediaRef}</MediaRef>`);
+      }
       return c;
     });
     if (trackType === 'video') {

package/resolve-advanced/vendor/drp-format/media-template-cache.js

@@ -68,4 +68,16 @@ function transplantMediaElement(mpXml, seqXmls, { poolElement, mediaRef }) {
   return { mpXml: outMp, seqXmls: outSeqs };
 }
 
-module.exports = { CACHE_DIR, cachePathFor, loadMediaTemplate, transplantMediaElement };
+/** Insert an ADDITIONAL native media <Element> into MpFolder's MediaVec. */
+function insertMediaElement(mpXml, poolElement) {
+  const close = mpXml.indexOf('</MediaVec>');
+  if (close < 0) throw new Error('insertMediaElement: no MediaVec in MpFolder');
+  const folderId = (mpXml.match(/<Sm2MpVideoClip[^>]*>[\s\S]*?<MpFolder>([0-9a-f-]{36})<\/MpFolder>/) || [])[1];
+  let element = poolElement;
+  if (folderId) {
+    element = element.replace(/<MpFolder>[0-9a-f-]{36}<\/MpFolder>/, `<MpFolder>${folderId}</MpFolder>`);
+  }
+  return mpXml.slice(0, close) + element + mpXml.slice(close);
+}
+
+module.exports = { CACHE_DIR, cachePathFor, loadMediaTemplate, transplantMediaElement, insertMediaElement };

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

@@ -37,6 +37,22 @@ const {
 } = require('./seq-surgery');
 
 const TEMPLATE_PATH = path.join(__dirname, 'templates', 'fusion-title.xml');
+// Snippets are generation-bound like the project templates: an R21-harvested
+// clip imports on 19 and renders BLACK (measured 2026-08-30). r19 variant
+// 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;
+}
 
 /**
  * Place a Fusion Title clip onto a chosen video track of a timeline in a .drp.
@@ -72,6 +88,7 @@ async function placeFusionTitle(drpInput, opts = {}) {
     color,
     timelineUuid,
     titleClipXml,
+    templateVersion,
   } = opts;
 
   if (!Number.isInteger(startFrame)) throw new TypeError('placeFusionTitle: startFrame (int) is required');
@@ -82,7 +99,7 @@ async function placeFusionTitle(drpInput, opts = {}) {
   let xml = seqXml;
 
   // Prepare the title clip (clone + rewrite identity/timing).
-  let clip = titleClipXml || fs.readFileSync(TEMPLATE_PATH, 'utf8');
+  let clip = titleClipXml || fs.readFileSync(snippetPathFor(templateVersion), 'utf8');
   clip = clip.trim();
   if (!/PrettyType>\s*Fusion Title/.test(clip)) {
     throw new Error('placeFusionTitle: template is not a Fusion Title clip');

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

@@ -28,6 +28,21 @@ const {
 } = require('./seq-surgery');
 
 const TEMPLATE_PATH = path.join(__dirname, 'templates', 'generator-solid-color.xml');
+const TEMPLATE_PATH_R19 = path.join(__dirname, 'templates', 'generator-solid-color-r19.xml');
+// 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;
+}
 
 /**
  * Place a built-in generator on a chosen video track.
@@ -43,7 +58,7 @@ const TEMPLATE_PATH = path.join(__dirname, 'templates', 'generator-solid-color.x
  *   generatorName:string, videoTrackCount:number, createdTracks:number}>}
  */
 async function placeGenerator(drpInput, opts = {}) {
-  const { generatorName = 'Solid Color', trackIndex = 2, startFrame, durationFrames = 120, timelineUuid } = opts;
+  const { generatorName = 'Solid Color', trackIndex = 2, startFrame, durationFrames = 120, timelineUuid, templateVersion } = opts;
   if (!Number.isInteger(startFrame)) throw new TypeError('placeGenerator: startFrame (int) is required');
   if (!Number.isInteger(trackIndex) || trackIndex < 1) throw new TypeError('placeGenerator: trackIndex must be a positive integer');
   if (/[<>]/.test(generatorName)) throw new Error('placeGenerator: generatorName must not contain < or >');
@@ -51,7 +66,7 @@ async function placeGenerator(drpInput, opts = {}) {
   const zip = await loadDrpZip(drpInput);
   const { entry, xml: seqXml, seqId } = await selectTargetSeq(zip, timelineUuid);
 
-  let gen = fs.readFileSync(TEMPLATE_PATH, 'utf8').trim();
+  let gen = fs.readFileSync(snippetPathFor(templateVersion), 'utf8').trim();
   gen = freshDbIds(gen);
   gen = gen.replace(/<PrettyType>[\s\S]*?<\/PrettyType>/, `<PrettyType>${escapeXml(generatorName)}</PrettyType>`);
   gen = gen.replace(/<Name>[\s\S]*?<\/Name>/, `<Name>${escapeXml(generatorName)}</Name>`);

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

@@ -0,0 +1,54 @@
+<Sm2TiVideoClip DbId="8c729549-aded-4c80-b143-c1fce23c5712">
+       <FieldsBlob>0000000200000027800a120a0e2205546578742b4a05546578742b200112100000000000000005ffffffffffffffff</FieldsBlob>
+       <PrettyType>Fusion Title</PrettyType>
+       <Name>Fusion Title</Name>
+       <Start>86400</Start>
+       <Duration>120</Duration>
+       <LinkedItemSync/>
+       <WasDisbanded>false</WasDisbanded>
+       <MarkersBA/>
+       <UiMemento>0</UiMemento>
+       <Flags>0</Flags>
+       <PriorityIndex>0</PriorityIndex>
+       <EffectFiltersBA/>
+       <ImportExportMetadataBA/>
+       <RenderTextEnabled>true</RenderTextEnabled>
+       <RenderTextGanged>true</RenderTextGanged>
+       <RenderTextPrefixed>true</RenderTextPrefixed>
+       <CompositionTable>
+        <Sm2TiCompositionTable DbId="fda722ba-c81f-4fa2-ae79-9f33b26a6bb1">
+         <FieldsBlob>000000010000000100000016004c006100730074004d006f006400540069006d0065000000040000000000002254b6</FieldsBlob>
+         <DbSavedTime>2309245</DbSavedTime>
+         <CompositionBA>000006b1789c75547f6c1445145e31d4585142a28d4222eb69c51ff763f7eedabb2bb4a6f67ab686daa3bd1e840acddcec6cbbedeece6677b677a536863420d5c81f448931261543c4a0a04453153585a860b531284ab46862556c4a358809218d4a9cd9dd6b8fa89bdbcbbc37efbd79effbbe598ee3aee138ee5afa967390c39ccde91ca1d612fa3a5bcb3881eba24ec0691c72c2e8b3926ba0b11a67d07f8b53688642573ac773e2428a4453087d99cd7165a906ac19d8528882757e906fb04d13e924a36888afe5053fdf867409996d40ef668e41e612c5043fe4e71f52710ea8ffb5e315694e527fc4cf37291be8829836f2f369150ce400eceb302440500b96bc63da093211f66c19a8168dcd22d3625dd5f2be24c82a3a5468371656fb110db72505f36222280623414110623e5a03f423a9d526864d2cb76a1352a50cc6aa6726150be45454ea5a8f61df558e7a56b855962d448a0058b6c6d21666708f685015c372067726b608d6928000c793696c49afafcf34763910f832a840eef7b1b8940934b490953691ec1a8c0467d1ac532000244abf0b6adac4850167d50e81d383e867a9f4975550decd662bb15834896460ab647127927496ad06a3d875b7f7e07c4736c3a8d3491641824dab883babc11ab64d944406e96103283a893bfdbb34b935b06dc2227b033af4e07194612b92376591b02276ed3a304a4f6aa12a3015a0b24691f9af46ffb711863956b1e9b5629224b22095aaa2772f0a88f9db8166a8c85a74a66c55a5c043c5d396d78a57340d488f7b740b7019e9f479333400d883ac1adf16d648a8c3a2ea0c5940b391da6d9b56df40a805f72bc80a39714c1d211416a02c08301046220c44e3914820511dad0e88f1980c130921918b89a1585c4e54e5c46820160d4b816804c881845c950b54272242541644291783a1388c851355d14400488806c1b810a0299100146588c211581513c3a194cd462ac2e3482d854d0d1097098a345d84a31e3fd4561893623056fac4998228da0c26f7fa3a26458c0e972ff15cadd4887366876e51c891e41ce87e1f1a7566791f86948af359b7cca04304bb78cd94350888c3e5822e525877db6ed470afe2593e57830652d5861e04fbdc00ddb9d30b0a6beed6b1893662537ac4d672c82ca17e71ab9e560086554abf2b29cd30916595941be20ed06f6e61eae93dc77b3f1496edbc7ccfdd336d5f0687cfbd719aef2ceb2c9f3dfae6d9570e1d3b327ce7e9c3fb2ed47dbcf5dea5abcbeb3e19affb76bc7279ee7aedc05ddb0bd3bf37dd706e9bb8ab2dbf7bdb99b28b2f4f6e3ef8e98a0bef4f4e3d7c5f2c3b29cf275f58f3e375aba64efe31bfeed2b1b53fe8ab6bef18bae9a3fcf21dcf066e3e31b6a7977ff0833978cbedafcf6eac8fd4ece6275e9d9b782b37b29fbff81820cfbc5673eaa5bd475b0f9f3cf1cecacd8faefafa2f587872c36cf4c6bf376daffcaee9d2f13ae3b315fbbee832767db56ee7955b9f5a3356c88f8c2f9d4e9f3f04464641e56d736f0f6f7a4e786ffe9b2bfed1ba1d4bb68e9e7af167f079fcf1113cb3e57cd9ee2315fba77fab1fffa5efa75fcb0eeac9e0e8c804ff67c5da5cf8ddb364eff7cf57cc3cf1003f76e6f23fb8ff3f78</CompositionBA>
+         <ActiveCompositionIdx>0</ActiveCompositionIdx>
+        </Sm2TiCompositionTable>
+       </CompositionTable>
+       <In/>
+       <MixedFrameRateAlignment>0</MixedFrameRateAlignment>
+       <MediaStartTime>0</MediaStartTime>
+       <MediaFilePath/>
+       <MediaReelNumber/>
+       <MediaFrameRate>00000000000038400000000000000000</MediaFrameRate>
+       <MediaTimemapBA>024013d55555555555</MediaTimemapBA>
+       <LastChangedTime>0</LastChangedTime>
+       <LastRenderedTime>0</LastRenderedTime>
+       <IsMarkedForCaching>false</IsMarkedForCaching>
+       <IsForceConformed>true</IsForceConformed>
+       <MatchConflictState>0</MatchConflictState>
+       <UseOppositeSrcForLeftEye>false</UseOppositeSrcForLeftEye>
+       <UseOppositeSrcForRightEye>false</UseOppositeSrcForRightEye>
+       <RenderCacheBA/>
+       <CurrentSelectorIdx>962869300</CurrentSelectorIdx>
+       <IsPreConformed>false</IsPreConformed>
+       <PreConformMediaExtents>00000100000030c20000010000003042</PreConformMediaExtents>
+       <MediaMetadata/>
+       <Thumbnail>
+        <BtThumnail DbId="ac0024f2-2407-47f8-9789-eafdbd585ae2">
+         <FieldsBlob/>
+         <ImgWidth>-1</ImgWidth>
+         <ImgHeight>-1</ImgHeight>
+         <Buffer/>
+        </BtThumnail>
+       </Thumbnail>
+       <ThumbnailDirtyFlag>true</ThumbnailDirtyFlag>
+      </Sm2TiVideoClip>

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

@@ -0,0 +1,19 @@
+<Sm2TiGenerator DbId="9d9cd9a6-f64f-49b9-a661-18f4f9c51781">
+       <FieldsBlob/>
+       <PrettyType>Solid Color</PrettyType>
+       <Name>Solid Color</Name>
+       <Start>86520</Start>
+       <Duration>120</Duration>
+       <LinkedItemSync/>
+       <WasDisbanded>false</WasDisbanded>
+       <MarkersBA/>
+       <UiMemento>0</UiMemento>
+       <Flags>0</Flags>
+       <PriorityIndex>0</PriorityIndex>
+       <EffectFiltersBA/>
+       <ImportExportMetadataBA/>
+       <RenderTextEnabled>true</RenderTextEnabled>
+       <RenderTextGanged>true</RenderTextGanged>
+       <RenderTextPrefixed>true</RenderTextPrefixed>
+       <In/>
+      </Sm2TiGenerator>

package/src/granular/common.py

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