feat(conform): the conform emulator — interchange in, rendering .drt out

drt.assemble_from_interchange: EDL/OTIO/XML/AAF + a sourceMap → parse →
frame-convert → multi-source assemble with native-descriptor transplant
→ stamped importable .drt, one call. eventsToAssembleSpec anchors the
earliest video event at the timeline origin, converts nominal-base
event frames to the 24fps template timeline (butt cuts stay gapless
through the conversion, verified at 29.97), groups cuts per source,
refuses overlaps and unmapped reels loudly, and ships an honesty
ledger: flattened retimes, transitions-as-cuts, skipped audio events.

Full-route live proof on Studio 19.1.3.7: a three-event EDL cutting
between two sources (with an M2 retime) assembled, imported 6/6 linked
with exact source in-points, rendered each event's OWN pixels (YAVG
125.6 / 234 / 125.5), full-range render at duration ratio 1.0, retime
in the ledger.

Scoped honestly: elements on pre-21 hosts are not render-verified — the
R21 snippets render black on 19 and the r19 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 R21,
drt.assemble warns on pre-21 element use, and the harvested r19
snippets ship for the element-transplant expedition.

Author: samuelgursky

CHANGELOG.md

@@ -2,6 +2,44 @@
 
 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

README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.107.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)

README.zh-CN.md

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

install.py

@@ -37,7 +37,7 @@
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.107.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-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.107.0",
+  "version": "2.108.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package.json

@@ -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));

resolve-advanced/server/author-interchange.mjs

@@ -29,6 +29,19 @@ 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({})
@@ -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: