davinci-resolve-mcp 2.106.0 → 2.107.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 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.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.107.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.107.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.107.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.107.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.107.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

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

@@ -33,7 +33,7 @@ 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()])

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 {
@@ -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/src/granular/common.py

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