davinci-resolve-mcp 2.140.0 → 2.142.0

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 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.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
+
+- **OTIO `Transition` children parse and author** — they occupy no record
+  time (the AAF overlap convention), attach to the incoming clip, and route
+  through the same style table as XMEML effectids (`SMPTE_Dissolve` → plain
+  dissolve; wipe-named types → the wipe). A Gap breaks the junction.
+
+### Measured
+
+- **Depth-4 nested compounds render** (234 through four levels via the spec
+  route) — nesting depth is effectively unbounded on 19.1.3.
+- **Record gaps render clean black** (cut 122.9 / gap 16.0 / white 234) —
+  sparse turnovers assemble without synthetic filler.
+
 ## What's New in v2.140.0 — the transition style registry
 
 ### Added

package/README.md

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

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

@@ -58,7 +58,7 @@ window. `render.verify_output` covers the container-level checks.
 | Subtitles | `spec.subtitles` / `spec.subtitlesSrt` (raw SRT) | v2.128 |
 | Compound clips | survive `extract_from_drp` → `.drt` (inner containers kept, recursive) | v2.130 |
 | Compound authoring | `spec.compounds` (multiple compose; nested edits render) | v2.131–2.132 |
-| Nested compounds | `compounds[].compounds` (depth-2 and depth-3 playback render-verified) | v2.134 |
+| Nested compounds | `compounds[].compounds` (depth-2 through depth-4 playback render-verified) | v2.134–2.141 |
 | Fusion titles | `elements: [{type:'title', text}]` — **21-gen hosts only** | v2.108 |
 
 `assemble_from_interchange` drives the same engine from an EDL / OTIO /
@@ -115,6 +115,10 @@ runs in the "working" direction. The real freeze (harvested from a live EDL
 left **empty**. `cuts[].freeze: true` authors exactly that; EDL `M2 000.0`
 and zero-speed warps route to it through `assemble_from_interchange`.
 
+**Gaps are legitimate.** Cuts need not abut: record gaps between placements
+render as clean black (measured: cut 122.9 / gap 16 / white 234), so sparse
+turnovers assemble without synthetic filler.
+
 **Timeline origin.** Template timelines start at frame 86400
 (01:00:00:00 @ 24fps). Clips placed before the origin are silently dropped
 by Resolve on import — `startFrame` is timeline-absolute.
@@ -131,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.140.0"
+VERSION = "2.142.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.140.0",
+  "version": "2.142.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

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

@@ -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,
       }),
     );
@@ -152,12 +155,27 @@ export function parseOTIO(otio, opts = {}) {
       }));
     }
     let rec = 0;
+    // An OTIO Transition occupies NO record time (like an AAF transition —
+    // it overlaps its neighbours); it describes the junction between the
+    // previous and NEXT clip. Carry it to the next clip event's transition
+    // field so the bridge can author it (type strings like SMPTE_Dissolve
+    // map through the same style table as XMEML effectids).
+    let pendingTransition = null;
     for (const child of track.children || []) {
       const schema = child.OTIO_SCHEMA || '';
       const dur = (child.source_range && child.source_range.duration && child.source_range.duration.value) || 0;
       const rate = (child.source_range && child.source_range.duration && child.source_range.duration.rate) || opts.fps || 24;
       if (schema.startsWith('Gap')) {
         rec += dur;
+        pendingTransition = null; // a gap breaks the junction
+        continue;
+      }
+      if (schema.startsWith('Transition')) {
+        const inOff = (child.in_offset && child.in_offset.value) || 0;
+        const outOff = (child.out_offset && child.out_offset.value) || 0;
+        // 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')) {
@@ -191,9 +209,11 @@ export function parseOTIO(otio, opts = {}) {
             recOut: rec + dur,
             speed: Math.abs(speed),
             reverse,
+            transition: pendingTransition,
             fps: rate,
           }),
         );
+        pendingTransition = null;
         rec += dur;
       }
     }
@@ -257,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/server/tools/drt.mjs

@@ -51,7 +51,7 @@ const assembleSchema = z.object({
   spec: z
     .object({})
     .passthrough()
-    .describe("assembleTimeline spec: { timelineName?, startFrame? (timeline start frame @24, default 86400=01:00:00:00 — sets the start TIMECODE, render-verified on 19), media?: {mediaFilePath, spec:{width,height,frameCount,fps}, cuts:[{startFrame,durationFrames,srcIn?,track? (1-based video track; >1 = video-only, render-verified stacking),speed?/reverse? (constant retime, e.g. 0.5, forward or backwards; video-only; readback+render-verified on 19),freeze? (true = hold source frame srcIn for the whole cut; video-only; render-proven frozen on 19 via freezedetect),ramp? ([{durationFrames,speed},...] >=2 LINEAR segments from the cut head, srcIn honored; video-only; render-proven cadence on 19 — eased/curved ramps are NOT authorable, an interp!=0 keyframe crashes Resolve on import (measured)),audioOnly?+track? (explicit AUDIO placement on audio track 1-8; presence suppresses the A1 mirror; render-verified on 19)}]} | [same, ...] (multi-source needs media_pool.capture_media_template run once per file), transitions?: [{track, atFrame, durationFrames?, trackType? ('video' | 'audio' cross-fade), type? ('dissolve' default | 'wipe' | 'dip' | 'additive' | 'fade-to-color' | 'smooth-cut' | 'non-additive' — all render-verified on 19 w/ midpoint fingerprints; XMEML/EDL transition codes route automatically, and NOTE Resolve's own XMEML importer writes transitions that render INERT, so this route beats it)}], markers?: [{frame (timeline-absolute), color? (16 names), name?, note?, duration?, customData?}] (readback-verified on 19), compounds?: [{name, startFrame (parent, absolute), durationFrames, track?, cuts:[{mediaFilePath, startFrame (INNER, 0-based), durationFrames, srcIn?}], compounds?: [same, nested — frames inner-relative]}] (multiple PARALLEL compounds compose AND compounds NEST recursively — depth-2 AND depth-3 playback render-verified on 19 (the old depth-2 black was a missing SequenceSetup key, fixed); inner cuts need captured templates w/ native clips), subtitles?: [{startFrame (timeline-absolute), durationFrames, text}] + subtitlesSrt? (raw SRT, cues anchor at the origin; readback-verified on 19; angle-bracket runs read as SRT markup), elements?: [{type:'title'|'generator', track, startFrame, durationFrames?, text?, generatorName? ('Solid Color'|'SMPTE Color Bar'|'Grey Scale' render-verified on 19), ...}] }. startFrame is timeline-absolute (origin 86400)."),
+    .describe("assembleTimeline spec: { timelineName?, startFrame? (timeline start frame @24, default 86400=01:00:00:00 — sets the start TIMECODE, render-verified on 19), media?: {mediaFilePath, spec:{width,height,frameCount,fps}, cuts:[{startFrame,durationFrames,srcIn?,track? (1-based video track; >1 = video-only, render-verified stacking),speed?/reverse? (constant retime, e.g. 0.5, forward or backwards; video-only; readback+render-verified on 19),freeze? (true = hold source frame srcIn for the whole cut; video-only; render-proven frozen on 19 via freezedetect),ramp? ([{durationFrames,speed},...] >=2 LINEAR segments from the cut head, srcIn honored; video-only; render-proven cadence on 19 — eased/curved ramps are NOT authorable, an interp!=0 keyframe crashes Resolve on import (measured)),audioOnly?+track? (explicit AUDIO placement on audio track 1-8; presence suppresses the A1 mirror; render-verified on 19)}]} | [same, ...] (multi-source needs media_pool.capture_media_template run once per file), transitions?: [{track, atFrame, durationFrames?, trackType? ('video' | 'audio' cross-fade), type? ('dissolve' default | 'wipe' | 'dip' | 'additive' | 'fade-to-color' | 'smooth-cut' | 'non-additive' — all render-verified on 19 w/ midpoint fingerprints; XMEML/EDL transition codes route automatically, and NOTE Resolve's own XMEML importer writes transitions that render INERT, so this route beats it)}], markers?: [{frame (timeline-absolute), color? (16 names), name?, note?, duration?, customData?}] (readback-verified on 19), compounds?: [{name, startFrame (parent, absolute), durationFrames, track?, cuts:[{mediaFilePath, startFrame (INNER, 0-based), durationFrames, srcIn?}], compounds?: [same, nested — frames inner-relative]}] (multiple PARALLEL compounds compose AND compounds NEST recursively — depth-2 through depth-4 playback render-verified on 19 (the old depth-2 black was a missing SequenceSetup key, fixed); inner cuts need captured templates w/ native clips), subtitles?: [{startFrame (timeline-absolute), durationFrames, text}] + subtitlesSrt? (raw SRT, cues anchor at the origin; readback-verified on 19; angle-bracket runs read as SRT markup), elements?: [{type:'title'|'generator', track, startFrame, durationFrames?, text?, generatorName? ('Solid Color'|'SMPTE Color Bar'|'Grey Scale' render-verified on 19), ...}] }. 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

@@ -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.140.0"
+VERSION = "2.142.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.140.0"
+VERSION = "2.142.0"
 
 import base64
 import os