davinci-resolve-mcp 2.105.0 → 2.106.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.106.0
+
+**Media clips in native DRT authoring — cut real footage into an importable,
+RENDERING timeline.** The deepest silent-failure class this repo has hit, run
+to ground and shipped, live-verified at every step on Studio 19.1.3.7.
+
+### The discovery chain
+
+Adding media cuts to drt.assemble surfaced three buried traps in sequence.
+First: repointing the bundled media template at a new file left the pool
+entry's compressed identity blobs describing the ORIGINAL capture source —
+and when that file still exists on the machine, Resolve silently links IT
+(observed: authored timelines linked a client clip while every visible field
+said the right path). Second: after teaching the Clip identity blobs the new
+path (their layout: dir, filename, ctime-format mtime string, codec tag,
+uuid, mtime-in-MICROSECONDS — a field first misread as file size), imports
+read back perfectly and still failed to render: "Full resolution media not
+found". Third: the render engine validates the pool entry's DEEP descriptors
+(Radiometry, keyed-dict FieldsBlobs, stream data) that offline code cannot
+synthesize. Structural readback cannot see any of this — only rendering can.
+
+### The architecture that works
+
+- **`media_pool.capture_media_template(media_path)`** (live, once per file):
+  builds a disposable project around the file, lets Resolve describe it
+  natively, caches the pool media element + MediaRef id under
+  ~/.config/davinci-resolve-mcp/media-templates/, and switches your project
+  back.
+- **`drt.assemble` grows media support**: `media: {mediaFilePath, spec,
+  cuts: [{startFrame, durationFrames, srcIn}]}` cuts ONE source into N
+  placements (new cut-media vendor primitive: donor clip cloned with fresh
+  DbIds and per-cut geometry on video + audio tracks; placement guards refuse
+  cuts before the timeline origin and reads past the media's end). At build
+  time the cached native element is TRANSPLANTED and MediaRefs rewired —
+  rendered output then matches a natively built timeline exactly (YAVG
+  125.6/123.2 across cuts vs 123.2 native control). Without a cache the
+  result carries mediaDescriptor: 'repoint-fallback' and a warning naming
+  the capture action.
+- **Version-matched templates**: a Resolve-21 template stamped down to 19
+  imports and reads back perfectly — and renders BLACK (the stamp clears the
+  gate, not the blob semantics). Both template generations now ship ('21'
+  original, '19' captured from 19.1.3.7); drt.assemble picks by
+  targetAppVersion.
+
+### Fixed
+
+- `render.verify_output` never verifies a job whose JobStatus is not
+  Complete (a Failed job's stub passed the duration-ratio check during this
+  hunt).
+- The repoint fallback's Clip identity blobs are now written with the
+  measured field semantics (mtime-µs, ctime string, dropped stale fields).
+
+All of it is an api_truth entry: imported media renders only with NATIVE
+pool descriptors; render-verify authored timelines, because structural
+readback cannot see this class.
+
 ## What's New in v2.105.0
 
 **Native-schema DRT authoring — the parked "project, not a lap" — shipped.**

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.105.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.106.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.105.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.106.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.105.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.106.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.105.0"
+VERSION = "2.106.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.105.0",
+  "version": "2.106.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

@@ -198,7 +198,14 @@ export const drtTool = {
       // assembled + stamped to the host's ProjectVersion imports with every
       // element intact.
       const { assembleTimeline } = drp();
-      const { buffer, timelineName, startFrame } = await assembleTimeline(p.spec);
+      // The template GENERATION must match the target host: a Resolve-21
+      // template stamped down imports on 19 but renders BLACK (measured) —
+      // the stamp clears the gate, not the blob semantics.
+      const spec = { ...p.spec };
+      if (spec.templateVersion === undefined && p.targetAppVersion !== undefined) {
+        spec.templateVersion = parseFloat(p.targetAppVersion) >= 21 ? 21 : 19;
+      }
+      const { buffer, timelineName, startFrame, mediaDescriptor } = await assembleTimeline(spec);
       let outBuf = buffer;
       let stamped = null;
       if (p.targetAppVersion !== undefined) {
@@ -216,6 +223,17 @@ export const drtTool = {
         timelineName,
         startFrame,
         stamped,
+        templateVersion: spec.templateVersion ?? 21,
+        mediaDescriptor: mediaDescriptor ?? 'none',
+        ...(mediaDescriptor === 'repoint-fallback'
+          ? {
+              warning:
+                'No native media template cached for this file — the archive imports and reads back ' +
+                'correctly but its media may not RENDER (black frames / "Full resolution media not ' +
+                'found"). Run media_pool.capture_media_template(media_path) once with Resolve open, ' +
+                'then re-assemble for a render-verified transplant.',
+            }
+          : {}),
         note:
           'Import with timeline.import_timeline_checked — the imported timeline is named after the FILE. ' +
           'On a host older than Resolve 21, pass targetAppVersion or the version gate refuses the archive.',

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

@@ -21,18 +21,59 @@
  * @module drp-format/assemble-timeline
  */
 
-const { createEmptyProject } = require('./author-project');
+const { createEmptyProject, addMediaClip, DEFAULT_START_FRAME } = require('./author-project');
+const { loadMediaTemplate, transplantMediaElement } = require('./media-template-cache');
+const JSZip = require('jszip');
+const { cutSourceIntoClips } = require('./cut-media');
 const { placeFusionTitle } = require('./place-fusion-title');
 const { placeGenerator } = require('./place-generator');
 const { placeTransition } = require('./place-transition');
 
 async function assembleTimeline(spec = {}) {
-  const { timelineName, elements = [], transitions = [] } = spec;
+  const { timelineName, elements = [], transitions = [], media, templateVersion } = spec;
   if (!Array.isArray(elements)) throw new TypeError('assembleTimeline: elements must be an array');
   if (!Array.isArray(transitions)) throw new TypeError('assembleTimeline: transitions must be an array');
 
-  const { buffer: base, timelineName: tlName, startFrame } = await createEmptyProject({ timelineName });
-  let buffer = base;
+  let base;
+  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');
+    }
+    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) => {
+        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`,
+          );
+        }
+        if (mediaSpec && Number.isFinite(mediaSpec.frameCount) && Number.isFinite(mediaSpec.fps)) {
+          // srcIn/duration are TIMELINE frames (24fps template); the media's
+          // extent converts: frameCount / mediaFps × 24.
+          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)`,
+            );
+          }
+        }
+      });
+      const cutRes = await cutSourceIntoClips(base.buffer, { cuts });
+      base.buffer = cutRes.buffer;
+    }
+  } else {
+    base = await createEmptyProject({ timelineName, templateVersion });
+  }
+  const { buffer: baseBuffer, timelineName: tlName, startFrame } = base;
+  let buffer = baseBuffer;
 
   for (const [i, el] of elements.entries()) {
     if (!el || typeof el !== 'object') throw new TypeError(`assembleTimeline: elements[${i}] must be an object`);
@@ -59,7 +100,32 @@ async function assembleTimeline(spec = {}) {
     }));
   }
 
-  return { buffer, timelineName: tlName, startFrame };
+  // 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 };
 }
 
 module.exports = { assembleTimeline };

package/resolve-advanced/vendor/drp-format/author-project.js

@@ -28,6 +28,36 @@ const DEFAULT_TIMELINE_NAME = 'Timeline 1';
 const MEDIA_TEMPLATE_DRP = path.join(__dirname, 'templates', 'media-clip-h264.drp');
 const MEDIA_TEMPLATE_SPEC = { width: 352, height: 262, frameCount: 4576, fps: 30000 / 1001 };
 const MEDIA_TEMPLATE_TL_NAME = 'MediaTemplate';
+
+// Version-matched template registry. Measured live on Studio 19.1.3.7: an
+// archive built from the Resolve-21 capture and version-STAMPED down imports
+// with every clip reading back correctly — and renders BLACK. The stamp
+// clears the import gate; the R21 blob semantics do not fully parse on 19,
+// so the render tree is empty while the structural readback is perfect (the
+// read-back-fine/render-dead class again). The only working fix is a
+// template captured from the target generation, so both generations ship:
+// '21' (original capture) and '19' (captured from Studio 19.1.3.7,
+// 2026-08-30, identical timeline geometry: start 86400, media clip
+// Start 86400 / Duration 3664 for the same 352x262 4576-frame 29.97 spec).
+const TEMPLATES = {
+  21: {
+    empty: TEMPLATE_DRP,
+    media: MEDIA_TEMPLATE_DRP,
+    mediaSpec: MEDIA_TEMPLATE_SPEC,
+  },
+  19: {
+    empty: path.join(__dirname, 'templates', 'empty-project-r19.drp'),
+    media: path.join(__dirname, 'templates', 'media-clip-r19.drp'),
+    mediaSpec: MEDIA_TEMPLATE_SPEC,
+  },
+};
+
+function templateFor(templateVersion) {
+  const key = Number(templateVersion) || 21;
+  const entry = TEMPLATES[key >= 21 ? 21 : 19];
+  if (!entry) throw new Error(`no template generation for version ${templateVersion}`);
+  return entry;
+}
 // The template timeline begins at 01:00:00:00 (24fps) — clips placed BEFORE this frame are
 // dropped by Resolve on import. Callers should place at >= startFrame.
 const DEFAULT_START_FRAME = 86400;
@@ -41,8 +71,8 @@ const DEFAULT_START_FRAME = 86400;
  *   startFrame is the timeline origin (86400 = 01:00:00:00 @ 24fps); place clips at >= this.
  */
 async function createEmptyProject(opts = {}) {
-  const { timelineName } = opts;
-  const tmpl = await fs.promises.readFile(TEMPLATE_DRP);
+  const { timelineName, templateVersion } = opts;
+  const tmpl = await fs.promises.readFile(templateFor(templateVersion).empty);
 
   if (!timelineName || timelineName === DEFAULT_TIMELINE_NAME) {
     return { buffer: tmpl, timelineName: DEFAULT_TIMELINE_NAME, startFrame: DEFAULT_START_FRAME };
@@ -74,13 +104,13 @@ async function createEmptyProject(opts = {}) {
  * @returns {Promise<{buffer:Buffer, timelineName:string, mediaFile:string}>}
  */
 async function addMediaClip(opts = {}) {
-  const { mediaFile, spec, timelineName, durationFrames } = opts;
+  const { mediaFile, spec, timelineName, durationFrames, templateVersion } = opts;
   if (!mediaFile || !path.isAbsolute(mediaFile)) throw new Error('addMediaClip: mediaFile must be an absolute path');
   if (!spec || ['width', 'height', 'frameCount', 'fps'].some((k) => typeof spec[k] !== 'number')) {
     throw new Error('addMediaClip: spec must be { width, height, frameCount, fps } (numbers)');
   }
 
-  const tmpl = await fs.promises.readFile(MEDIA_TEMPLATE_DRP);
+  const tmpl = await fs.promises.readFile(templateFor(templateVersion).media);
   // Discover the template's current media path (the "from" for repoint).
   const zip0 = await JSZip.loadAsync(tmpl);
   let fromPath = null;
@@ -92,7 +122,7 @@ async function addMediaClip(opts = {}) {
   if (!fromPath) throw new Error('addMediaClip: could not read template media path');
 
   let { buffer } = await repointMedia(tmpl, {
-    from: fromPath, to: mediaFile, fromSpec: MEDIA_TEMPLATE_SPEC, toSpec: spec,
+    from: fromPath, to: mediaFile, fromSpec: templateFor(templateVersion).mediaSpec, toSpec: spec,
   });
 
   // Rename the timeline (lives in the Media Pool).

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

@@ -0,0 +1,85 @@
+/**
+ * cut-media — replace a timeline's single source clip with N cuts of it.
+ *
+ * The composable half of media authoring: addMediaClip yields a project whose
+ * timeline holds ONE clip of the (repointed) source on V1/A1; this clones that
+ * donor clip into a cut list — fresh DbIds, per-cut Start / Duration / source
+ * In — on both the video and audio tracks, so a real editorial cut of one
+ * source becomes an importable timeline. Source-IN semantics per splice-clips:
+ * <In> framePos is in TIMELINE frames (verified live), encoded as
+ * `frames|LE-double(frames*0.001)`.
+ *
+ * Single-source by design (the template media pool holds one media entry);
+ * multi-source needs media-pool entry synthesis and is refused honestly.
+ *
+ * @module drp-format/cut-media
+ */
+
+const {
+  loadDrpZip,
+  selectTargetSeq,
+  splitClipElements,
+  getItemsInner,
+  setItemsInner,
+  freshDbIds,
+  getTrackVec,
+  replaceTrackVec,
+} = require('./seq-surgery');
+const { clipDbId, setClipStart, setClipDuration, setClipIn } = require('./splice-clips');
+
+/**
+ * @param {Buffer|string} drpInput
+ * @param {object} opts
+ * @param {Array<{startFrame:number, durationFrames:number, srcIn?:number}>} opts.cuts
+ *   Timeline placements. startFrame is timeline-absolute (origin 86400 on the
+ *   bundled templates — clips before the origin are dropped by Resolve on
+ *   import, silently). srcIn is the source in-point in TIMELINE frames.
+ * @param {string} [opts.timelineUuid]
+ * @returns {Promise<{buffer: Buffer, cutCount: number, clipDbIds: string[]}>}
+ */
+async function cutSourceIntoClips(drpInput, opts = {}) {
+  const { cuts, timelineUuid } = opts;
+  if (!Array.isArray(cuts) || cuts.length === 0) {
+    throw new TypeError('cutSourceIntoClips: cuts must be a non-empty array');
+  }
+  cuts.forEach((cut, i) => {
+    if (!cut || !Number.isInteger(cut.startFrame) || !Number.isInteger(cut.durationFrames) || cut.durationFrames <= 0) {
+      throw new TypeError(`cutSourceIntoClips: cuts[${i}] needs integer startFrame and positive integer durationFrames`);
+    }
+    if (cut.srcIn !== undefined && (!Number.isInteger(cut.srcIn) || cut.srcIn < 0)) {
+      throw new TypeError(`cutSourceIntoClips: cuts[${i}].srcIn must be a non-negative integer`);
+    }
+  });
+
+  const zip = await loadDrpZip(drpInput);
+  const { entry, xml: seqXml } = await selectTargetSeq(zip, timelineUuid);
+  let xml = seqXml;
+  const clipDbIds = [];
+
+  for (const trackType of ['video', 'audio']) {
+    const { match, tracks } = getTrackVec(xml, trackType);
+    if (!tracks.length) continue;
+    const items = getItemsInner(tracks[0]);
+    const clips = splitClipElements(items);
+    if (!clips.length) continue; // audio-less media: nothing to cut on A1
+    const donor = clips[0];
+    const clones = cuts.map((cut) => {
+      let c = freshDbIds(donor);
+      c = setClipStart(c, cut.startFrame);
+      c = setClipDuration(c, cut.durationFrames);
+      c = setClipIn(c, cut.srcIn ?? 0);
+      return c;
+    });
+    if (trackType === 'video') {
+      for (const c of clones) clipDbIds.push(clipDbId(c));
+    }
+    tracks[0] = setItemsInner(tracks[0], clones.join(''));
+    xml = replaceTrackVec(xml, trackType, match, tracks);
+  }
+
+  zip.file(entry, xml);
+  const buffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+  return { buffer, cutCount: cuts.length, clipDbIds };
+}
+
+module.exports = { cutSourceIntoClips };

package/resolve-advanced/vendor/drp-format/index.js

@@ -156,6 +156,7 @@ module.exports = {
 
   // Build a full importable timeline from a declarative spec (titles/generators/transitions).
   assembleTimeline: require('./assemble-timeline').assembleTimeline,
+  cutSourceIntoClips: require('./cut-media').cutSourceIntoClips,
 
   // Author a project with one media clip referencing an arbitrary h264 file, from scratch [P8].
   addMediaClip: require('./author-project').addMediaClip,

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

@@ -0,0 +1,71 @@
+/**
+ * media-template-cache — native per-media descriptors, captured live once.
+ *
+ * Offline authoring cannot synthesize Resolve's media-identity descriptors:
+ * repointing a template's pool entry at a different file imports and reads
+ * back perfectly but the render engine refuses ("Full resolution media not
+ * found") or paints black — the entry's deep blobs (Radiometry, keyed-dict
+ * FieldsBlobs, stream descriptors) still describe the template's file.
+ * Measured fix (2026-08-30, Studio 19.1.3.7): TRANSPLANT the entire native
+ * media <Element> captured from a scratch project built around the target
+ * file, and rewire the timeline clips' <MediaRef> to the native id —
+ * rendered luma then matches the native control exactly.
+ *
+ * The Python server's media_pool.capture_media_template action writes these
+ * caches (one JSON per media file, keyed by sha1 of the absolute path) while
+ * Resolve is running; this module consumes them offline.
+ *
+ * @module drp-format/media-template-cache
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const CACHE_DIR = process.env.DRP_MEDIA_TEMPLATE_DIR
+  || path.join(os.homedir(), '.config', 'davinci-resolve-mcp', 'media-templates');
+
+function cachePathFor(mediaFilePath) {
+  const key = crypto.createHash('sha1').update(path.resolve(mediaFilePath)).digest('hex');
+  return path.join(CACHE_DIR, `${key}.json`);
+}
+
+/** Load the cached native descriptor for a media file, or null. */
+function loadMediaTemplate(mediaFilePath) {
+  try {
+    const raw = fs.readFileSync(cachePathFor(mediaFilePath), 'utf8');
+    const data = JSON.parse(raw);
+    if (!data.poolElement || !data.mediaRef) return null;
+    return data;
+  } catch (e) {
+    return null;
+  }
+}
+
+/** Replace the pool media <Element> holding `marker` and rewire MediaRefs. */
+function transplantMediaElement(mpXml, seqXmls, { poolElement, mediaRef }) {
+  const idx = mpXml.indexOf('<Sm2MpVideoClip');
+  if (idx < 0) throw new Error('transplant: no Sm2MpVideoClip element in MpFolder');
+  const start = mpXml.lastIndexOf('<Element>', idx);
+  let depth = 0; let end = -1; let m;
+  const re = /<\/?Element>/g;
+  re.lastIndex = start;
+  while ((m = re.exec(mpXml))) {
+    if (m[0] === '<Element>') depth += 1; else depth -= 1;
+    if (depth === 0) { end = m.index + m[0].length; break; }
+  }
+  if (end < 0) throw new Error('transplant: unbalanced Element nesting');
+  const folderId = (mpXml.slice(start, end).match(/<MpFolder>([0-9a-f-]{36})<\/MpFolder>/) || [])[1];
+  let element = poolElement;
+  if (folderId) {
+    element = element.replace(/<MpFolder>[0-9a-f-]{36}<\/MpFolder>/, `<MpFolder>${folderId}</MpFolder>`);
+  }
+  const outMp = mpXml.slice(0, start) + element + mpXml.slice(end);
+  const outSeqs = seqXmls.map((seq) =>
+    seq.replace(/<MediaRef>[0-9a-f-]{36}<\/MediaRef>/g, `<MediaRef>${mediaRef}</MediaRef>`),
+  );
+  return { mpXml: outMp, seqXmls: outSeqs };
+}
+
+module.exports = { CACHE_DIR, cachePathFor, loadMediaTemplate, transplantMediaElement };

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

@@ -191,6 +191,114 @@ function patchSpecBlobs(mpXml, toName, fromSpec, toSpec) {
  * @param {string} [opts.from] @param {string} [opts.to] @param {object} [opts.fromSpec] @param {object} [opts.toSpec]
  * @returns {Promise<{buffer:Buffer, relinked:Array, specPatched:Array<{to:string,patched:boolean}>}>}
  */
+let _fzstd = null;
+try { _fzstd = require('fzstd'); } catch (e) { /* optional; zstd Clip blobs need it */ }
+const _zlib = require('node:zlib');
+const _crypto = require('node:crypto');
+const _fs = require('node:fs');
+
+/**
+ * Rewrite the media-identity <Clip> blobs in MpFolder.xml for a repoint.
+ *
+ * The blob is [u32BE version][u32BE len][0x81][compressed protobuf] where the
+ * protobuf is FLAT: f1 dir, f2/f6 filename, f3 mtime string, f7 uuid,
+ * f13 file size bytes, f14 media frame count. Resolve links media by THIS
+ * identity in preference to the plain-text MediaFilePath — measured live
+ * 2026-08-30: a template whose Clip blob still named its capture source made
+ * ImportTimelineFromFile link that ORIGINAL file (a real client asset) while
+ * every visible field said the new path, and the relinked render came out
+ * black. relinkMedia's raw-bytes blob pass cannot see through the
+ * compression, so this decompresses (zstd via optional fzstd, zlib, or raw
+ * deflate), patches the fields, and re-emits as zlib — the decoder framing
+ * accepts either codec.
+ */
+function repointClipBlobsInXml(xml, { toDir, toName, toSpec }) {
+  let patched = 0;
+  const out = xml.replace(/<Clip>([0-9a-f]{40,})<\/Clip>/g, (whole, hex) => {
+    try {
+      const raw = Buffer.from(hex, 'hex');
+      if (raw.length < 10 || raw[8] !== 0x81) return whole;
+      const payload = raw.subarray(9);
+      let plain;
+      if (payload[0] === 0x28 && payload[1] === 0xb5 && payload[2] === 0x2f && payload[3] === 0xfd) {
+        if (!_fzstd) return whole;
+        plain = Buffer.from(_fzstd.decompress(new Uint8Array(payload)));
+      } else if (payload[0] === 0x78) {
+        plain = _zlib.inflateSync(payload);
+      } else {
+        plain = _zlib.inflateRawSync(payload);
+      }
+      // Parse flat top-level protobuf fields.
+      const fields = [];
+      let o = 0;
+      while (o < plain.length) {
+        const start = o;
+        let shift = 0; let tag = 0;
+        for (;;) { const b = plain[o++]; tag |= (b & 0x7f) << shift; if (!(b & 0x80)) break; shift += 7; }
+        const field = tag >>> 3; const wire = tag & 7;
+        if (wire === 0) { for (;;) { const b = plain[o++]; if (!(b & 0x80)) break; } }
+        else if (wire === 1) o += 8;
+        else if (wire === 5) o += 4;
+        else if (wire === 2) {
+          let len = 0; shift = 0;
+          for (;;) { const b = plain[o++]; len |= (b & 0x7f) << shift; if (!(b & 0x80)) break; shift += 7; }
+          o += len;
+        } else return whole; // unknown wire type: leave the blob alone
+        fields.push({ field, wire, bytes: plain.subarray(start, o) });
+      }
+      const varint = (v) => {
+        const bs = [];
+        let r = v;
+        while (r > 0x7f) { bs.push((r & 0x7f) | 0x80); r = Math.floor(r / 128); }
+        bs.push(r & 0x7f);
+        return Buffer.from(bs);
+      };
+      const strField = (field, str) => {
+        const body = Buffer.from(str, 'utf8');
+        return Buffer.concat([varint((field << 3) | 2), varint(body.length), body]);
+      };
+      const intField = (field, v) => Buffer.concat([varint(field << 3), varint(v)]);
+      let stat = null;
+      try { stat = _fs.statSync(`${toDir}/${toName}`); } catch (e) { /* offline authoring: file may not exist yet */ }
+      const rebuilt = fields.map((f) => {
+        if (f.field === 1) return strField(1, toDir);
+        if (f.field === 2) return strField(2, toName);
+        if (f.field === 6) return strField(6, toName);
+        if (f.field === 7) return strField(7, _crypto.randomUUID());
+        // f13 is the file's MTIME IN MICROSECONDS — verified by capturing the
+        // same file natively (Resolve wrote 1788121973071908 for an
+        // Aug-30-2026 mtime). Writing anything else here makes the render
+        // engine refuse with "Full resolution media not found" while every
+        // structural readback stays green. f14 is absent from native captures
+        // of plain mp4 media; a stale template value is dropped.
+        if (f.field === 13 && stat) return intField(13, Math.floor(stat.mtimeMs * 1000));
+        if (f.field === 14) return Buffer.alloc(0);
+        if (f.field === 3 && stat) {
+          // ctime() layout, matching Resolve's own stamps: 'Sun Aug 17 15:01:38 2025'
+          const d = stat.mtime;
+          const days = ['Sun','Mon','Tue','Wed','Thu','Fri','Sat'];
+          const months = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'];
+          const pad = (n) => String(n).padStart(2, '0');
+          const ctime = `${days[d.getDay()]} ${months[d.getMonth()]} ${String(d.getDate()).padStart(2, ' ')} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())} ${d.getFullYear()}`;
+          return strField(3, ctime);
+        }
+        return f.bytes;
+      });
+      const fresh = Buffer.concat(rebuilt);
+      const compressed = _zlib.deflateSync(fresh);
+      const head = Buffer.alloc(9);
+      head.writeUInt32BE(raw.readUInt32BE(0), 0);
+      head.writeUInt32BE(1 + compressed.length, 4);
+      head[8] = 0x81;
+      patched += 1;
+      return `<Clip>${Buffer.concat([head, compressed]).toString('hex')}</Clip>`;
+    } catch (e) {
+      return whole; // never corrupt a blob we cannot fully parse
+    }
+  });
+  return { xml: out, patched };
+}
+
 async function repointMedia(drpInput, opts = {}) {
   const mappings = opts.mappings
     || (opts.from && opts.to ? [{ from: opts.from, to: opts.to, fromSpec: opts.fromSpec, toSpec: opts.toSpec }] : []);
@@ -210,9 +318,21 @@ async function repointMedia(drpInput, opts = {}) {
     mp = res.xml;
     specPatched.push({ to: m.to, patched: res.patched });
   }
+  // 3) rewrite the compressed media-identity Clip blobs — the field Resolve
+  // actually links by (see repointClipBlobsInXml).
+  let clipBlobsPatched = 0;
+  for (const m of mappings) {
+    const res = repointClipBlobsInXml(mp, {
+      toDir: nodePath.dirname(m.to),
+      toName: nodePath.basename(m.to),
+      toSpec: m.toSpec,
+    });
+    mp = res.xml;
+    clipBlobsPatched += res.patched;
+  }
   zip.file(mpPath, mp);
   const buffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
-  return { buffer, relinked: relinked.relinked, specPatched };
+  return { buffer, relinked: relinked.relinked, specPatched, clipBlobsPatched };
 }
 
 module.exports = { relinkMedia, repointMedia };

package/resolve-advanced/vendor/drp-format/splice-clips.js

@@ -442,4 +442,8 @@ async function rippleTimeline(drpInput, opts = {}) {
   return { buffer, entry, timelineUuid: seqId, at, delta, shifted };
 }
 
-module.exports = { moveClip, deleteClip, trimClip, trimClipHead, splitClip, rippleTimeline };
+module.exports = {
+  moveClip, deleteClip, trimClip, trimClipHead, splitClip, rippleTimeline,
+  // low-level clip-XML helpers, reused by cut-media.js
+  clipDbId, clipStart, clipDuration, clipIn, setClipStart, setClipDuration, setClipIn,
+};

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.105.0"
+VERSION = "2.106.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.105.0"
+VERSION = "2.106.0"
 
 import base64
 import os
@@ -8973,6 +8973,7 @@ _MEDIA_POOL_KERNEL_ACTIONS = [
     "link_full_resolution_checked",
     "set_clip_marks",
     "get_clip_marks",
+    "capture_media_template",
     "clear_clip_marks",
     "copy_clip_annotations",
     "media_pool_boundary_report",
@@ -13795,6 +13796,126 @@ def _set_clip_marks(root, mp, p: Dict[str, Any]):
     return {"success": all(row.get("success") for row in results), "count": len(results), "missing": missing, "results": results}
 
 
+def _capture_media_template(r, pm, p: Dict[str, Any]) -> Dict[str, Any]:
+    """Capture a media file's NATIVE Resolve descriptors for offline authoring.
+
+    Offline authoring cannot synthesize the media-identity blobs Resolve's
+    render engine validates (Radiometry, keyed-dict FieldsBlobs, stream
+    descriptors): a repointed pool entry imports and reads back perfectly but
+    renders black or fails with "Full resolution media not found" (measured
+    2026-08-30, Studio 19.1.3.7). This builds a disposable project around the
+    file, lets Resolve describe it natively, and caches the pool media
+    <Element> + the timeline clips' <MediaRef> id. drt.assemble then
+    TRANSPLANTS the cached element, which renders identically to native.
+
+    Switches the current project to a scratch project during capture and
+    switches back; requires the media file to exist locally.
+    """
+    import hashlib
+    import zipfile as _zipfile
+
+    media_path = p.get("media_path") or p.get("path")
+    if not media_path or not os.path.isabs(str(media_path)):
+        return _err("capture_media_template requires media_path (absolute)")
+    media_path = os.path.abspath(str(media_path))
+    if not os.path.exists(media_path):
+        return _err(f"media file does not exist: {media_path}")
+
+    cache_dir = os.environ.get("DRP_MEDIA_TEMPLATE_DIR") or os.path.join(
+        os.path.expanduser("~"), ".config", "davinci-resolve-mcp", "media-templates"
+    )
+    os.makedirs(cache_dir, exist_ok=True)
+    cache_path = os.path.join(
+        cache_dir, hashlib.sha1(media_path.encode("utf-8")).hexdigest() + ".json"
+    )
+
+    previous = None
+    try:
+        cur = pm.GetCurrentProject()
+        previous = cur.GetName() if cur else None
+    except Exception:
+        previous = None
+
+    scratch = f"_mcp_media_tpl_{int(time.time())}"
+    proj = pm.CreateProject(scratch)
+    if not proj:
+        return _err(f"Could not create scratch project {scratch!r}")
+    drp_tmp = os.path.join(tempfile.gettempdir(), f"{scratch}.drp")
+    try:
+        mp_obj = proj.GetMediaPool()
+        clips = mp_obj.ImportMedia([media_path])
+        if not clips:
+            return _err(f"Resolve could not import {media_path}")
+        tl = mp_obj.CreateEmptyTimeline("MediaTemplate")
+        from src.utils.resolve_writes import set_current_timeline, describe_switch_failure
+        switched, detail = set_current_timeline(proj, tl)
+        if not switched:
+            return _err(describe_switch_failure(detail, "the media-template capture"))
+        if not mp_obj.AppendToTimeline([clips[0]]):
+            return _err("AppendToTimeline failed during capture")
+        if not pm.SaveProject():
+            return _err("SaveProject failed — ExportProject would snapshot an empty timeline")
+        if not pm.ExportProject(scratch, drp_tmp):
+            return _err("ExportProject failed during capture")
+
+        with _zipfile.ZipFile(drp_tmp) as zf:
+            mp_xml = zf.read("MediaPool/Master/MpFolder.xml").decode("utf-8", "replace")
+            seq_xml = ""
+            for n in zf.namelist():
+                if re.search(r"SeqContainer/.+\.xml$", n):
+                    seq_xml = zf.read(n).decode("utf-8", "replace")
+                    break
+        marker = os.path.basename(media_path)
+        idx = mp_xml.find(marker)
+        if idx < 0:
+            return _err("captured MpFolder does not name the media — capture aborted")
+        start = mp_xml.rfind("<Element>", 0, idx)
+        depth, end = 0, -1
+        for m in re.finditer(r"</?Element>", mp_xml[start:]):
+            depth += 1 if m.group(0) == "<Element>" else -1
+            if depth == 0:
+                end = start + m.end()
+                break
+        media_ref_m = re.search(r"<MediaRef>([0-9a-f-]{36})</MediaRef>", seq_xml)
+        if end < 0 or not media_ref_m:
+            return _err("could not isolate the media element / MediaRef from the capture")
+        pool_element = mp_xml[start:end]
+        media_ref = media_ref_m.group(1)
+        if media_ref not in pool_element:
+            return _err("MediaRef is not inside the captured element — schema drift; capture aborted")
+
+        stat = os.stat(media_path)
+        payload = {
+            "mediaFilePath": media_path,
+            "capturedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "resolveVersion": r.GetVersionString(),
+            "mtimeMs": stat.st_mtime * 1000.0,
+            "sizeBytes": stat.st_size,
+            "mediaRef": media_ref,
+            "poolElement": pool_element,
+        }
+        with open(cache_path, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh)
+        return _ok(
+            cache_path=cache_path,
+            media_ref=media_ref,
+            pool_element_bytes=len(pool_element),
+            resolve_version=payload["resolveVersion"],
+            note=(
+                "drt.assemble now transplants this native descriptor for this "
+                "media file; re-capture if the file is rewritten (mtime/size "
+                "recorded for staleness checks)."
+            ),
+        )
+    finally:
+        try:
+            os.unlink(drp_tmp)
+        except OSError:
+            pass
+        from src.utils.project_cleanup import delete_project_safely
+        delete_project_safely(pm, scratch, switch_to=previous)
+
+
 def _get_clip_marks(root, mp, p: Dict[str, Any]):
     """Read mark in/out for a set of media-pool clips — the read twin of set_clip_marks."""
     resolved, err = _clips_from_params(root, mp, p)
@@ -19154,6 +19275,7 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
                 code="JOB_NOT_FOUND", category="invalid_input",
             )
         result: Dict[str, Any] = {"job_id": job_id, "status": status}
+        job_status = str(status.get("JobStatus") or "")
         target_dir = job.get("TargetDir")
         filename = job.get("OutputFilename")
         warnings: List[str] = []
@@ -19290,6 +19412,14 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
                     warnings.append(
                         "JobStatus is Complete but the output file does not exist."
                     )
+        if job_status and job_status != "Complete":
+            # Spotted live: a Failed job that wrote a stub file otherwise
+            # produced verified:true — a duration ratio means nothing when
+            # Resolve itself says the job did not complete.
+            warnings.append(
+                f"JobStatus is {job_status!r}, not Complete"
+                + (f": {status.get('Error')}" if status.get("Error") else "")
+            )
         result["warnings"] = warnings
         result["verified"] = bool(
             output_path and result.get("output_exists") and not warnings
@@ -19580,6 +19710,13 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
       check_proxy_media_compatibility(clip_id, proxy_path|path, expected_codec?, expected_profile?) -> {compatible, mismatches}
       link_proxy_checked(clip_id, proxy_path|path, dry_run?, check_compatibility?, require_compatible?, expected_codec?, expected_profile?) -> {success}
       link_full_resolution_checked(clip_id, path|full_res_media_path, dry_run?) -> {success}
+      capture_media_template(media_path) -> {cache_path, media_ref}
+        Captures the file's NATIVE Resolve media descriptors into
+        ~/.config/davinci-resolve-mcp/media-templates/ via a disposable
+        project (switches projects during capture and switches back).
+        Offline drt.assemble then transplants them — the only measured way
+        authored media actually RENDERS; synthesized descriptors import and
+        read back fine but render black or 'Full resolution media not found'.
       set_clip_marks(clip_ids|selected, mark_in, mark_out, type?, dry_run?) -> {success, results}
       clear_clip_marks(clip_ids|selected, type?, dry_run?) -> {success, results}
       copy_clip_annotations(source_clip_id, target_clip_ids, include_markers?, include_flags?, include_clip_color?, dry_run?) -> {success, results}
@@ -19961,6 +20098,8 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
         return _set_clip_marks(root, mp, p)
     elif action == "get_clip_marks":
         return _get_clip_marks(root, mp, p)
+    elif action == "capture_media_template":
+        return _capture_media_template(get_resolve(), get_resolve().GetProjectManager(), p)
     elif action == "clear_clip_marks":
         return _clear_clip_marks(root, mp, p)
     elif action == "copy_clip_annotations":

package/src/utils/api_truth.py

@@ -1885,6 +1885,35 @@ API_TRUTH: List[Dict[str, Any]] = [
         "submit": "bug",
         "issue": 171,
     },
+    {
+        "symbol": "Imported media renders only with NATIVE pool descriptors (repointed entries read back fine, render never)",
+        "object": "MediaPool / render engine",
+        "reality": "An imported archive's media links by the pool entry's DEEP "
+                   "descriptors (compressed Clip identity blobs, Radiometry, "
+                   "keyed-dict FieldsBlobs, stream data), not by the visible "
+                   "MediaFilePath. A pool entry whose visible fields all name "
+                   "the right file but whose deep blobs describe another "
+                   "imports cleanly, reads back perfectly (items, names, "
+                   "source frames, linked counts), and then either renders "
+                   "BLACK or fails with 'Full resolution media not found' — "
+                   "and worse, when the stale identity matches a file that "
+                   "exists on the machine, Resolve links THAT file (observed: "
+                   "a template captured from a client clip silently linked "
+                   "the client clip). Measured by bisection on Studio "
+                   "19.1.3.7: pristine native archives render (YAVG 123), "
+                   "every synthesized/repointed variant read back identically "
+                   "and did not.",
+        "recommended": "Never synthesize pool media descriptors. Capture them "
+                       "natively once per file with "
+                       "media_pool.capture_media_template (builds a scratch "
+                       "project around the file, caches the native element), "
+                       "and author with drt.assemble, which transplants the "
+                       "cached element and rewires MediaRefs — rendered "
+                       "output then matches a natively built timeline "
+                       "exactly. Always render-verify authored timelines; "
+                       "structural readback cannot see this class.",
+        "tags": ["media-pool", "import", "render", "silent-failure", "readback"],
+    },
     {
         "symbol": "MediaPool.ImportTimelineFromFile (.drt requirements and filename naming)",
         "object": "MediaPool",