davinci-resolve-mcp 2.141.0 → 2.142.1

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 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.142.1 — the AAF leg joins the span fix
+
+### Fixed
+
+- **AAF dissolves were misaligned by half their duration**: the AAF walker
+  rewinds the incoming clip to the overlap START (the Edit Protocol
+  subtraction), so the parsed junction is the overlap's first frame — and the
+  old centered placement put half the blend before the overlap even began.
+  AAF transitions now carry `alignment: 'start'` through the same
+  render-proven span machinery as EDL (v2.142.0): span `[overlapStart,
+  overlapStart+dur)`, boundary shifted to the middle — which lands the
+  notional cut exactly at the AAF CutPoint default (centered in the overlap).
+
+## What's New in v2.142.0 — transition span fidelity, and the edge law
+
+### Changed (conform fidelity)
+
+- **Transition spans now follow the turnover's actual geometry** instead of
+  always centering: EDL dissolves/wipes span `[cut, cut+dur)` (the CMX
+  convention), OTIO transitions use their explicit in/out offsets, XMEML
+  transitionitems use their own record span, and spec-level
+  `transitions[].startFrame` overrides. Handle requirements follow the real
+  span — a start-at-cut EDL dissolve needs NO incoming handle and a
+  full-duration outgoing tail. Render-verified: the authored EDL dissolve
+  blends exactly `[cut, cut+24)` (pure outgoing through cut−1, linear blend,
+  midpoint 182), matching Resolve's own EDL importer frame-for-frame.
+
+### Measured (the edge law)
+
+- A transition's rendered span follows `<Start>`/`<Duration>`
+  (`AlignmentType` is cosmetic), **but the clip boundary must sit strictly
+  inside the span** — an edge-aligned span (Start == the boundary) renders
+  inert. That is why Resolve's own EDL importer moves the cut +dur/2 and
+  centers; the bridge now reproduces exactly that cut-reshaping. Off-center
+  spans render fine (an uneven `[cut−6, cut+18)` span blended linearly
+  across its full width).
+
 ## What's New in v2.141.0 — OTIO transitions, depth-4, and honest gaps
 
 ### Added

package/README.md

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

package/docs/guides/native-drt-authoring.md

@@ -135,10 +135,20 @@ outgoing clip through the window) — so routing an XMEML turnover through
 `assemble_from_interchange` produces transitions that render where the host
 importer's do not.
 
-**Dissolve geometry.** A transition is authored only when the predecessor
-ends exactly at the cut and both sides have handle media for the centered
-span (incoming `srcIn ≥ dur/2`; outgoing `srcIn + dur + dur/2 ≤ frameCount`).
-Everything else stays in `droppedTransitions` with the reason.
+**Dissolve geometry — spans follow the turnover, and the edge law.** A
+transition's rendered span follows `<Start>`/`<Duration>`; `AlignmentType`
+is cosmetic. The clip boundary must sit STRICTLY INSIDE the span — an
+edge-aligned span (Start == the boundary) renders inert (measured), which is
+why Resolve's own EDL importer moves the cut +dur/2 and centers. The bridge
+reproduces per-format geometry exactly: EDL dissolves span [cut, cut+dur)
+with the boundary shifted +dur/2 (CMX convention, host-importer parity —
+render-verified: blend f48→f71 on a cut at 48); OTIO uses its explicit
+in/out offsets; XMEML uses the transitionitem's own record span; spec-level
+`transitions[].startFrame` overrides. Handles follow the actual span: the
+incoming needs `srcIn ≥` the pre-cut portion, the outgoing needs tail media
+for the post-cut portion. Off-center spans render (blend measured across an
+uneven [cut-6, cut+18) span); everything unauthorable stays in
+`droppedTransitions` with the reason.
 
 ## Verification checklist for a delivered .drt
 

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.141.0"
+VERSION = "2.142.1"
 # 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.141.0",
+  "version": "2.142.1",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/server/aaf_probe.py

@@ -1169,7 +1169,12 @@ def _walk_components(sequence, *, track, fps, rec, state, depth, transition=None
         try:
             if cls == "Transition":
                 duration = _length(comp)
-                pending_transition = {"type": "dissolve", "duration": duration}
+                # alignment 'start': after the rewind, the incoming clip's recIn IS the
+                # overlap start, so the transition span is [recIn, recIn+duration) — and
+                # the bridge's boundary-shift lands the notional cut at recIn+duration/2,
+                # exactly the AAF CutPoint default (centered in the overlap). The old
+                # centered-on-recIn placement put HALF the blend before the overlap began.
+                pending_transition = {"type": "dissolve", "duration": duration, "alignment": "start"}
                 # Rewind: the next component overlaps the previous one by `duration`.
                 # Clamped at this sequence's own start — a leading transition has no
                 # preceding material to overlap, and a negative record position would

package/resolve-advanced/server/author-interchange.mjs

@@ -307,14 +307,26 @@ export function eventsToAssembleSpec(events, opts = {}) {
       // be authored (abutting predecessor + handles both sides) is decided
       // after all placements are known.
       let d = Math.max(2, toTl(e.transition.duration || 0, e.fps) || 2);
-      d += d % 2; // placeTransition centers on the cut; keep it even
+      d += d % 2; // even duration keeps every alignment on whole frames
+      // Span geometry per format (E73): `pre` = frames of the span BEFORE
+      // the cut. EDL: 0 (CMX start-at-cut — matches what Resolve's own EDL
+      // importer authors, E61 harvest); OTIO: the explicit in_offset; XMEML:
+      // derived from the transitionitem's own record start; no info: centered.
+      let pre = Math.floor(d / 2);
+      if (e.transition.alignment === 'start') pre = 0;
+      else if (e.transition.inOffset != null) pre = Math.min(d, Math.max(0, toTl(e.transition.inOffset, e.fps)));
+      else if (e.transition.recStart != null) {
+        const spanStartAbs = ORIGIN + (toTl(e.transition.recStart, e.fps) - minRec);
+        pre = Math.min(d, Math.max(0, recIn - spanStartAbs));
+      }
       transitionCandidates.push({
-        atFrame: recIn, durationFrames: d, track: vTrack,
+        atFrame: recIn, durationFrames: d, track: vTrack, pre,
+        explicitSpan: e.transition.alignment != null || e.transition.inOffset != null || e.transition.recStart != null,
         index: e.index, type: e.transition.type, rawDuration: e.transition.duration,
-        source: e.source, srcIn: cut.srcIn,
+        source: e.source, srcIn: cut.srcIn, incomingCutRef: cut,
       });
     }
-    placements.push({ start: recIn, end: recOut, index: e.index, source: e.source, srcIn: cut.srcIn, durationFrames, track: vTrack });
+    placements.push({ start: recIn, end: recOut, index: e.index, source: e.source, srcIn: cut.srcIn, durationFrames, track: vTrack, cutRef: cut });
     if (!perSource.has(e.source)) perSource.set(e.source, []);
     perSource.get(e.source).push(cut);
   }
@@ -341,13 +353,17 @@ export function eventsToAssembleSpec(events, opts = {}) {
     if (e.transition) {
       let d = Math.max(2, toTl(e.transition.duration || 0, e.fps) || 2);
       d += d % 2;
+      let pre = Math.floor(d / 2);
+      if (e.transition.alignment === 'start') pre = 0;
+      else if (e.transition.inOffset != null) pre = Math.min(d, Math.max(0, toTl(e.transition.inOffset, e.fps)));
       audioTransCandidates.push({
-        atFrame: recIn, durationFrames: d, track,
+        atFrame: recIn, durationFrames: d, track, pre,
+        explicitSpan: e.transition.alignment != null || e.transition.inOffset != null,
         index: e.index, type: e.transition.type, rawDuration: e.transition.duration,
-        source: e.source, srcIn: cut.srcIn,
+        source: e.source, srcIn: cut.srcIn, incomingCutRef: cut,
       });
     }
-    audioPlacements.push({ start: recIn, end: recOut, index: e.index, track, source: e.source, srcIn: cut.srcIn, durationFrames });
+    audioPlacements.push({ start: recIn, end: recOut, index: e.index, track, source: e.source, srcIn: cut.srcIn, durationFrames, cutRef: cut });
     if (!perSource.has(e.source)) perSource.set(e.source, []);
     perSource.get(e.source).push(cut);
   }
@@ -412,16 +428,21 @@ export function eventsToAssembleSpec(events, opts = {}) {
       droppedTransitions.push({ index: c.index, type: c.type, duration: c.rawDuration, reason: 'no abutting predecessor at the cut' });
       continue;
     }
-    const half = c.durationFrames / 2;
-    const bHandle = c.srcIn >= half;
+    // Handle math follows the actual span: `pre` frames before the cut need
+    // incoming pre-roll (srcIn >= pre); `post` frames after need outgoing
+    // tail media. A start-at-cut EDL dissolve needs NO incoming handle and a
+    // FULL-duration outgoing tail.
+    const pre = c.pre ?? c.durationFrames / 2;
+    const post = c.durationFrames - pre;
+    const bHandle = c.srcIn >= pre;
     const aSpec = sourceMap[prev.source] && sourceMap[prev.source].spec;
     const aFrames = aSpec && Number(aSpec.frameCount);
-    const aHandle = Number.isFinite(aFrames) ? prev.srcIn + prev.durationFrames + half <= aFrames : false;
+    const aHandle = Number.isFinite(aFrames) ? prev.srcIn + prev.durationFrames + post <= aFrames : false;
     if (!bHandle || !aHandle) {
       droppedTransitions.push({
         index: c.index, type: c.type, duration: c.rawDuration,
-        reason: `insufficient handles for a centered ${c.durationFrames}f dissolve` +
-          `${bHandle ? '' : ' (incoming srcIn < half)'}${aHandle ? '' : ' (outgoing tail media < half)'}`,
+        reason: `insufficient handles for a ${c.durationFrames}f dissolve spanning [cut-${pre}, cut+${post})` +
+          `${bHandle ? '' : ` (incoming srcIn < ${pre})`}${aHandle ? '' : ` (outgoing tail media < ${post})`}`,
       });
       continue;
     }
@@ -438,7 +459,28 @@ export function eventsToAssembleSpec(events, opts = {}) {
     else if (/additive/i.test(raw)) kind = 'additive';
     else if (/fade to color/i.test(raw)) kind = 'fade-to-color';
     else if (/smooth cut/i.test(raw)) kind = 'smooth-cut';
-    transitions.push({ track: c.track, atFrame: c.atFrame, durationFrames: c.durationFrames, ...(kind === 'dissolve' ? {} : { type: kind }) });
+    // EDGE LAW (E73, measured): the clip boundary must sit STRICTLY INSIDE
+    // the transition span — an edge-aligned span (Start == boundary) renders
+    // INERT. Resolve's own EDL importer solves the CMX start-at-cut case by
+    // MOVING the cut half the duration and centering; reproduce exactly that:
+    // extend the outgoing clip, trim the incoming head (source stays
+    // aligned), and keep the RENDERED span [cut-pre, cut-pre+d) unchanged.
+    let atFrame = c.atFrame;
+    const spanStartAbs = c.atFrame - pre;
+    if (c.explicitSpan && (pre === 0 || pre === c.durationFrames)) {
+      const shift = (pre === 0 ? 1 : -1) * (c.durationFrames / 2);
+      prev.cutRef.durationFrames += shift;
+      c.incomingCutRef.startFrame += shift;
+      c.incomingCutRef.srcIn += shift;
+      c.incomingCutRef.durationFrames -= shift;
+      prev.end += shift;
+      atFrame += shift;
+    }
+    transitions.push({
+      track: c.track, atFrame, durationFrames: c.durationFrames,
+      ...(kind === 'dissolve' ? {} : { type: kind }),
+      ...(c.explicitSpan ? { startFrame: spanStartAbs } : {}),
+    });
   }
   // Audio cross-fades, same geometry rules (render-verified on 19.1.3.7 via
   // the harvested cross-fade template: the highpass RMS ramps, not steps).
@@ -448,20 +490,35 @@ export function eventsToAssembleSpec(events, opts = {}) {
       droppedTransitions.push({ index: c.index, type: c.type, duration: c.rawDuration, trackType: 'audio', reason: 'no abutting predecessor at the cut' });
       continue;
     }
-    const half = c.durationFrames / 2;
-    const bHandle = c.srcIn >= half;
+    const pre = c.pre ?? c.durationFrames / 2;
+    const post = c.durationFrames - pre;
+    const bHandle = c.srcIn >= pre;
     const aSpec = sourceMap[prev.source] && sourceMap[prev.source].spec;
     const aFrames = aSpec && Number(aSpec.frameCount);
-    const aHandle = Number.isFinite(aFrames) ? prev.srcIn + prev.durationFrames + half <= aFrames : false;
+    const aHandle = Number.isFinite(aFrames) ? prev.srcIn + prev.durationFrames + post <= aFrames : false;
     if (!bHandle || !aHandle) {
       droppedTransitions.push({
         index: c.index, type: c.type, duration: c.rawDuration, trackType: 'audio',
-        reason: `insufficient handles for a centered ${c.durationFrames}f cross-fade` +
-          `${bHandle ? '' : ' (incoming srcIn < half)'}${aHandle ? '' : ' (outgoing tail media < half)'}`,
+        reason: `insufficient handles for a ${c.durationFrames}f cross-fade spanning [cut-${pre}, cut+${post})` +
+          `${bHandle ? '' : ` (incoming srcIn < ${pre})`}${aHandle ? '' : ` (outgoing tail media < ${post})`}`,
       });
       continue;
     }
-    transitions.push({ track: c.track, atFrame: c.atFrame, durationFrames: c.durationFrames, trackType: 'audio' });
+    let atFrame = c.atFrame;
+    const spanStartAbs = c.atFrame - pre;
+    if (c.explicitSpan && (pre === 0 || pre === c.durationFrames)) {
+      const shift = (pre === 0 ? 1 : -1) * (c.durationFrames / 2);
+      prev.cutRef.durationFrames += shift;
+      c.incomingCutRef.startFrame += shift;
+      c.incomingCutRef.srcIn += shift;
+      c.incomingCutRef.durationFrames -= shift;
+      prev.end += shift;
+      atFrame += shift;
+    }
+    transitions.push({
+      track: c.track, atFrame, durationFrames: c.durationFrames, trackType: 'audio',
+      ...(c.explicitSpan ? { startFrame: spanStartAbs } : {}),
+    });
   }
 
   // Turnover markers (EDL * LOC: locators, OTIO Marker objects) → authored

package/resolve-advanced/server/editorial.mjs

@@ -118,7 +118,10 @@ export function parseEDL(text, opts = {}) {
         srcOut: tcToFrames(srcOut, fps),
         recIn: tcToFrames(recIn, fps),
         recOut: tcToFrames(recOut, fps),
-        transition: transition && transition !== 'C' ? { type: transition, duration: dur || 0 } : null,
+        // CMX convention: the dissolve/wipe span STARTS at the cut (occupies
+        // the first `dur` frames of the incoming event) — matching what
+        // Resolve's own EDL importer authors (E61 harvest: Start == the cut).
+        transition: transition && transition !== 'C' ? { type: transition, duration: dur || 0, alignment: 'start' } : null,
         fps,
       }),
     );
@@ -170,7 +173,9 @@ export function parseOTIO(otio, opts = {}) {
       if (schema.startsWith('Transition')) {
         const inOff = (child.in_offset && child.in_offset.value) || 0;
         const outOff = (child.out_offset && child.out_offset.value) || 0;
-        pendingTransition = { type: String(child.transition_type || 'SMPTE_Dissolve'), duration: inOff + outOff };
+        // in_offset = frames BEFORE the cut, out_offset = frames after; the
+        // bridge places the span [cut - inOffset, cut + outOffset).
+        pendingTransition = { type: String(child.transition_type || 'SMPTE_Dissolve'), duration: inOff + outOff, inOffset: inOff };
         continue;
       }
       if (schema.startsWith('Clip')) {
@@ -272,7 +277,10 @@ export function parseXMEMLEvents(xml, opts = {}) {
         if (!Number.isFinite(s) || !Number.isFinite(e2)) continue;
         const effectId = (tr.effect && (tr.effect.effectid || tr.effect.name)) || 'Cross Dissolve';
         const incoming = events.slice(before).find((ev) => ev.track === label && ev.recIn > s - 1 && ev.recIn <= e2);
-        if (incoming) incoming.transition = { type: String(effectId), duration: e2 - s };
+        // recStart carries the transitionitem's EXPLICIT record span start
+        // (sequence-relative) so the bridge reproduces the editor's actual
+        // alignment instead of assuming centered.
+        if (incoming) incoming.transition = { type: String(effectId), duration: e2 - s, recStart: s };
       }
     });
     const atracks = media.audio && media.audio.track ? (Array.isArray(media.audio.track) ? media.audio.track : [media.audio.track]) : [];

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

@@ -233,6 +233,7 @@ async function assembleTimeline(spec = {}) {
       track: tr.track, atFrame: tr.atFrame, durationFrames: tr.durationFrames,
       trackType: tr.trackType || 'video',
       type: tr.type || 'dissolve',
+      spanStart: tr.startFrame,
     }));
   }
 

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

@@ -85,7 +85,7 @@ const STYLE_PRETTY_TYPES = {
 const TRANSITION_TYPES = ['dissolve', 'wipe', ...Object.keys(STYLE_PRETTY_TYPES)];
 
 async function placeTransition(drpInput, opts = {}) {
-  const { track, atFrame, durationFrames = 24, trackType = 'video', type = 'dissolve', timelineUuid } = opts;
+  const { track, atFrame, durationFrames = 24, trackType = 'video', type = 'dissolve', spanStart, timelineUuid } = opts;
   if (!TRANSITION_TYPES.includes(type)) throw new Error(`placeTransition: type must be one of ${TRANSITION_TYPES.join(', ')}`);
   if (type !== 'dissolve' && trackType === 'audio') throw new Error('placeTransition: styled transitions are video-only (audio junctions cross-fade)');
   if (!Number.isInteger(track) || track < 1) throw new TypeError('placeTransition: track must be a positive integer');
@@ -114,7 +114,19 @@ async function placeTransition(drpInput, opts = {}) {
   } else if (STYLE_PRETTY_TYPES[type]) {
     trans = trans.replace(/<PrettyType>Cross Dissolve<\/PrettyType>/, `<PrettyType>${STYLE_PRETTY_TYPES[type]}</PrettyType>`);
   }
-  const start = atFrame - Math.floor(durationFrames / 2); // centered (AlignmentType 2)
+  // Span geometry follows <Start>/<Duration>, NOT AlignmentType (the E61
+  // harvest of Resolve's own EDL import carries AlignmentType 2 with the
+  // span STARTING at the cut — the CMX convention — while our default
+  // centers it). spanStart (absolute) overrides for format parity: EDL
+  // dissolves start at the cut, OTIO splits by in/out offsets, XMEML
+  // transitionitems carry their explicit record span.
+  if (spanStart !== undefined) {
+    if (!Number.isInteger(spanStart)) throw new TypeError('placeTransition: spanStart must be an integer frame');
+    if (spanStart > atFrame || spanStart + durationFrames < atFrame) {
+      throw new RangeError(`placeTransition: span [${spanStart}, ${spanStart + durationFrames}) does not cover the cut at ${atFrame}`);
+    }
+  }
+  const start = spanStart !== undefined ? spanStart : atFrame - Math.floor(durationFrames / 2);
   trans = trans.replace(/<Start>\d+<\/Start>/, `<Start>${start}</Start>`);
   trans = trans.replace(/<Duration>\d+<\/Duration>/, `<Duration>${durationFrames}</Duration>`);
   const transitionDbId = (trans.match(/<Sm2TiTransition DbId="([^"]+)"/) || [])[1] || null;

package/src/granular/common.py

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