davinci-resolve-mcp 2.142.1 → 2.144.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 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.144.0 — turnover clip markers ride the items
+
+### Added
+
+- **OTIO clip markers and FCP7-XMEML clipitem `<marker>`s route to ITEM
+  markers** on their cuts through `assemble_from_interchange` (frames
+  clip-relative, colors mapped, notes preserved; markers on trimmed-away
+  material drop rather than refuse). Track-level markers still author as
+  timeline markers. Built on v2.143's `Sm2TiItemLockableBlob` authoring —
+  the only .drt carrier for clip markers, since Resolve's own exporter
+  drops them.
+
+## What's New in v2.143.0 — item markers, and two refinements
+
+### Added
+
+- **Item-level markers (clip locators) authored offline** — `cuts[].markers`
+  (frames item-relative), on video AND explicit-audio items. Found by a raw
+  byte-hunt in a live Project.db: item markers ride an
+  `Sm2TiItemLockableBlob` in `project.xml`'s LocableBlobSet — the same wire
+  codec as timeline markers with the clip's DbId as owner. The kicker, filed
+  as a new Resolve bug in api-limitations: **Resolve's own EXPORT_DRT drops
+  item-marker blobs entirely** (even after SaveProject), while
+  `ImportTimelineFromFile` accepts an authored one — this authoring path is
+  the only way a .drt carries clip markers. Live-verified readback on video
+  and A3 audio items through the tool layer.
+- **AAF `CutPoint` honored** — when an AAF transition names where the
+  notional cut sits within the overlap, the boundary shift lands there
+  (clamped strictly inside the span per the edge law) instead of centering.
+
+### Changed
+
+- **`fade-to-color` demoted from the transition style set** — on the
+  dissolve skeleton it is duration/direction-erratic (a 24f junction
+  rendered a ~77 plateau; a 48f one rendered a single black frame then a
+  hard cut), and its real parameter blob is unharvestable while the XMEML
+  importer stays inert. Turnover Fade-To-Colors now map to `dip`, which is
+  duration-stable (clean symmetric valley measured at both 24f and 48f).
+
 ## What's New in v2.142.1 — the AAF leg joins the span fix
 
 ### Fixed

package/README.md

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

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

@@ -53,6 +53,7 @@ window. `render.verify_output` covers the container-level checks.
 | Built-in generators | `elements: [{type:'generator', generatorName}]` | v2.110 |
 | Custom start timecode | `spec.startFrame` / `preserveStartTimecode` | v2.117 |
 | Timeline markers | `spec.markers` (16 colors, notes, durations, customData) | v2.118 |
+| Item markers (clip locators) | `cuts[].markers` (frames item-relative; video + audio items) | v2.143 |
 | Turnover markers | EDL `* LOC:` locators + OTIO markers → authored | v2.119 |
 | TC-bearing sources (AAF route) | native clip capture (`MediaStartTime`), channel-leg merge | v2.120–2.122 |
 | Subtitles | `spec.subtitles` / `spec.subtitlesSrt` (raw SRT) | v2.128 |

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 35 missing capabilities, 46 bugs / unreliable behaviors.
+**Totals:** 35 missing capabilities, 47 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -671,3 +671,11 @@ values, or automation-hostile modal prompts.
 - **Behavior:** Video <transitionitem>s imported from an FCP7 XMEML land as real Sm2TiTransition elements that READ BACK through the item APIs but render INERT: the outgoing clip plays through the transition window and hard-cuts at its end. Measured on Studio 19.1.3.7 with both a plain Cross Dissolve and a Dip to Color Dissolve (midpoint frames byte-matched the outgoing clip; no blend, no dip). The same transition elements authored offline with a correct FieldsBlob render perfectly, and EDL-imported dissolves/wipes also render — the defect is specific to the XMEML import path's element construction.
 - **Workaround / current handling:** Do not trust an XMEML-imported timeline's transitions without a render probe at a junction midpoint. To conform an XMEML turnover with working transitions, route it through drt.assemble_from_interchange (format 'xml'), which authors render-verified dissolves, wipes, and the dissolve-family styles from the same <transitionitem> data.
 - **Tags:** timeline, import, xmeml, transition, readback, silent-failure
+
+### Timeline.Export EXPORT_DRT (drops timeline-item markers)
+
+- **Object:** `Timeline`
+- **Signature:** `(filePath, EXPORT_DRT) -> bool`
+- **Behavior:** Item-level markers (clip locators) are not serialized into the exported .drt at all. They live in the project database as Sm2TiItemLockableBlob rows (same wire codec as timeline markers, BlobOwner = the item's DbId — located by byte search in a live Project.db), and readback via TimelineItem.GetMarkers is fine, but the export omits the blobs even after SaveProject — measured on Studio 19.1.3.7. Asymmetrically, ImportTimelineFromFile ACCEPTS an authored Sm2TiItemLockableBlob and the markers read back perfectly.
+- **Workaround / current handling:** Do not rely on .drt archives to carry clip markers. To deliver item markers in a .drt, author them offline (drt.assemble cuts[].markers writes the accepted blob); to preserve markers from a live timeline, read them via the marker API and re-author.
+- **Tags:** timeline, export, drt, markers, silent-failure

package/install.py

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

package/resolve-advanced/server/aaf_probe.py

@@ -1175,6 +1175,15 @@ def _walk_components(sequence, *, track, fps, rec, state, depth, transition=None
                 # 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"}
+                # CutPoint (optional): where the notional cut sits WITHIN the
+                # overlap. The bridge shifts the reshaped clip boundary there
+                # instead of the centered default, preserving Avid's intent.
+                try:
+                    cut_point = comp["CutPoint"].value
+                    if cut_point is not None:
+                        pending_transition["cutPoint"] = int(cut_point)
+                except (KeyError, AttributeError, TypeError, ValueError):
+                    pass
                 # 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

@@ -10,6 +10,14 @@
  */
 import { drt } from './libs.mjs';
 
+const COLOR_MAP = {
+  blue: 'Blue', cyan: 'Cyan', green: 'Green', yellow: 'Yellow', red: 'Red',
+  pink: 'Pink', purple: 'Purple', magenta: 'Fuchsia', fuchsia: 'Fuchsia',
+  rose: 'Rose', lavender: 'Lavender', sky: 'Sky', mint: 'Mint',
+  lemon: 'Lemon', sand: 'Sand', cocoa: 'Cocoa', cream: 'Cream',
+  orange: 'Sand', white: 'Cream', black: 'Cocoa',
+};
+
 const pad = (n, w = 2) => String(Math.max(0, Math.floor(n))).padStart(w, '0');
 
 /** frames → CMX timecode at fps (non-drop). */
@@ -284,6 +292,21 @@ export function eventsToAssembleSpec(events, opts = {}) {
     if (durationFrames <= 0) continue;
     const vTrack = trackNum(e.track);
     const cut = { startFrame: recIn, durationFrames, srcIn: toTl(e.srcIn ?? 0, e.fps), ...(vTrack > 1 ? { track: vTrack } : {}) };
+    // CLIP markers from the turnover (OTIO clip markers, XMEML clipitem
+    // <marker>s) become ITEM markers on the cut (frames clip-relative,
+    // nominal→timeline converted; anything landing outside the cut is
+    // dropped rather than refused — a marker on trimmed-away material).
+    if (Array.isArray(e.itemMarkers) && e.itemMarkers.length) {
+      const ims = e.itemMarkers
+        .map((m) => ({
+          frame: Math.round(toTl(m.frame ?? 0, e.fps)),
+          color: COLOR_MAP[String(m.color || '').toLowerCase()] || 'Blue',
+          ...(m.name ? { name: m.name } : {}),
+          ...(m.note ? { note: m.note } : {}),
+        }))
+        .filter((m) => m.frame >= 0 && m.frame < durationFrames);
+      if (ims.length) cut.markers = ims;
+    }
     if ((e.speed ?? 100) !== 100 || e.reverse) {
       const spd = Math.abs(e.speed ?? 100);
       if (!(spd > 0)) {
@@ -323,7 +346,7 @@ export function eventsToAssembleSpec(events, opts = {}) {
         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, incomingCutRef: cut,
+        source: e.source, srcIn: cut.srcIn, incomingCutRef: cut, cutPoint: e.transition.cutPoint,
       });
     }
     placements.push({ start: recIn, end: recOut, index: e.index, source: e.source, srcIn: cut.srcIn, durationFrames, track: vTrack, cutRef: cut });
@@ -360,7 +383,7 @@ export function eventsToAssembleSpec(events, opts = {}) {
         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, incomingCutRef: cut,
+        source: e.source, srcIn: cut.srcIn, incomingCutRef: cut, cutPoint: e.transition.cutPoint,
       });
     }
     audioPlacements.push({ start: recIn, end: recOut, index: e.index, track, source: e.source, srcIn: cut.srcIn, durationFrames, cutRef: cut });
@@ -457,7 +480,7 @@ export function eventsToAssembleSpec(events, opts = {}) {
     else if (/dip to color/i.test(raw)) kind = 'dip';
     else if (/non-additive/i.test(raw)) kind = 'non-additive';
     else if (/additive/i.test(raw)) kind = 'additive';
-    else if (/fade to color/i.test(raw)) kind = 'fade-to-color';
+    else if (/fade to color/i.test(raw)) kind = 'dip'; // fade-to-color is erratic on the skeleton (measured); dip is the verified fade-to-black-and-back
     else if (/smooth cut/i.test(raw)) kind = 'smooth-cut';
     // EDGE LAW (E73, measured): the clip boundary must sit STRICTLY INSIDE
     // the transition span — an edge-aligned span (Start == boundary) renders
@@ -468,7 +491,11 @@ export function eventsToAssembleSpec(events, opts = {}) {
     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);
+      // AAF CutPoint: the notional cut's offset within the overlap — shift
+      // the reshaped boundary there when given (clamped strictly inside the
+      // span, the edge law), else center.
+      const cp = Number.isInteger(c.cutPoint) ? Math.min(c.durationFrames - 1, Math.max(1, c.cutPoint)) : c.durationFrames / 2;
+      const shift = (pre === 0 ? 1 : -1) * cp;
       prev.cutRef.durationFrames += shift;
       c.incomingCutRef.startFrame += shift;
       c.incomingCutRef.srcIn += shift;
@@ -507,7 +534,11 @@ export function eventsToAssembleSpec(events, opts = {}) {
     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);
+      // AAF CutPoint: the notional cut's offset within the overlap — shift
+      // the reshaped boundary there when given (clamped strictly inside the
+      // span, the edge law), else center.
+      const cp = Number.isInteger(c.cutPoint) ? Math.min(c.durationFrames - 1, Math.max(1, c.cutPoint)) : c.durationFrames / 2;
+      const shift = (pre === 0 ? 1 : -1) * cp;
       prev.cutRef.durationFrames += shift;
       c.incomingCutRef.startFrame += shift;
       c.incomingCutRef.srcIn += shift;
@@ -524,13 +555,6 @@ export function eventsToAssembleSpec(events, opts = {}) {
   // Turnover markers (EDL * LOC: locators, OTIO Marker objects) → authored
   // timeline markers. Interchange colors map to the measured Resolve names;
   // unknown colors fall back to Blue. Frames are timeline-absolute like cuts.
-  const COLOR_MAP = {
-    blue: 'Blue', cyan: 'Cyan', green: 'Green', yellow: 'Yellow', red: 'Red',
-    pink: 'Pink', purple: 'Purple', magenta: 'Fuchsia', fuchsia: 'Fuchsia',
-    rose: 'Rose', lavender: 'Lavender', sky: 'Sky', mint: 'Mint',
-    lemon: 'Lemon', sand: 'Sand', cocoa: 'Cocoa', cream: 'Cream',
-    orange: 'Sand', white: 'Cream', black: 'Cocoa',
-  };
   const markers = markerEvents
     .map((e) => ({
       frame: ORIGIN + (toTl(e.recIn, e.fps) - minRec),

package/resolve-advanced/server/editorial.mjs

@@ -59,6 +59,7 @@ function evt(o) {
     speed: o.speed ?? 100,
     reverse: o.reverse ?? false,
     transition: o.transition || null,
+    ...(o.itemMarkers !== undefined ? { itemMarkers: o.itemMarkers } : {}),
     fps: o.fps ?? null,
   };
 }
@@ -190,13 +191,14 @@ export function parseOTIO(otio, opts = {}) {
           }
         }
         const src = (child.media_reference && (child.media_reference.target_url || child.media_reference.name)) || child.name || 'UNKNOWN';
+        // CLIP markers belong to the ITEM, not the sequence — carried as
+        // itemMarkers (frames CLIP-relative) so the bridge authors them as
+        // Sm2TiItemLockableBlobs (E80). Track-level markers above remain
+        // timeline markers.
+        const itemMarkers = [];
         for (const mk of child.markers || []) {
           const mrStart = (mk.marked_range && mk.marked_range.start_time && mk.marked_range.start_time.value) || 0;
-          events.push(evt({
-            index: idx++, track: 'MARKER', source: '',
-            recIn: rec + (mrStart - startVal), recOut: null,
-            name: mk.name || undefined, color: mk.color || undefined, fps: rate,
-          }));
+          itemMarkers.push({ frame: mrStart - startVal, name: mk.name || undefined, color: mk.color || undefined });
         }
         events.push(
           evt({
@@ -210,6 +212,7 @@ export function parseOTIO(otio, opts = {}) {
             speed: Math.abs(speed),
             reverse,
             transition: pendingTransition,
+            itemMarkers: itemMarkers.length ? itemMarkers : undefined,
             fps: rate,
           }),
         );
@@ -252,7 +255,13 @@ export function parseXMEMLEvents(xml, opts = {}) {
         }
       }
       if (Number.isFinite(start) && Number.isFinite(end)) {
-        events.push(evt({ index: idx++, track, source: name, srcIn: inF, srcOut: outF, recIn: start, recOut: end, speed, reverse, fps: seqRate }));
+        // FCP7 clipitem <marker> children are CLIP markers (frames relative
+        // to the clip's own <in>) — routed to item markers like OTIO's (E81).
+        const mks = it.marker ? (Array.isArray(it.marker) ? it.marker : [it.marker]) : [];
+        const itemMarkers = mks
+          .filter((mk) => Number.isFinite(Number(mk.in)))
+          .map((mk) => ({ frame: Number(mk.in) - inF, name: mk.name != null ? String(mk.name) : undefined, note: mk.comment != null ? String(mk.comment) : undefined }));
+        events.push(evt({ index: idx++, track, source: name, srcIn: inF, srcOut: outF, recIn: start, recOut: end, speed, reverse, itemMarkers: itemMarkers.length ? itemMarkers : undefined, fps: seqRate }));
       }
     }
   };

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 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)."),
+    .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),markers? (ITEM markers/clip locators: [{frame ITEM-relative, color?, name?, note?, duration?, customData?}] — readback-verified on 19; NOTE Resolve's own EXPORT_DRT drops item markers, this authoring path is the only .drt carrier)}]} | [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' | '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

@@ -209,6 +209,51 @@ async function assembleTimeline(spec = {}) {
   const { buffer: baseBuffer, timelineName: tlName, startFrame } = base;
   let buffer = baseBuffer;
 
+  // ITEM-level markers (clip locators): cuts[].markers, frames ITEM-relative.
+  // They live in project.xml's LocableBlobSet as Sm2TiItemLockableBlob —
+  // same wire codec as timeline markers, BlobOwner = the CLIP's DbId
+  // (measured E78 via a live DB byte-hunt: the .drt EXPORTER drops these
+  // blobs entirely, but the IMPORTER accepts an authored one — frames,
+  // colors, notes, durations and customData all read back through the
+  // marker API). Placed right after cuts, while the parent container is
+  // still the only one (compounds haven't run).
+  {
+    const itemMarkerCuts = [];
+    (Array.isArray(media) ? media : media ? [media] : []).forEach((src) => {
+      (src.cuts || []).forEach((cut) => {
+        if (Array.isArray(cut.markers) && cut.markers.length) itemMarkerCuts.push(cut);
+      });
+    });
+    if (itemMarkerCuts.length) {
+      const { getTrackVec } = require('./seq-surgery');
+      const zipIM = await JSZip.loadAsync(buffer);
+      const seqName = Object.keys(zipIM.files).find((n) => !zipIM.files[n].dir && /SeqContainer\/.+\.xml$/.test(n));
+      const seqXml = await zipIM.file(seqName).async('string');
+      let pj = await zipIM.file('project.xml').async('string');
+      if (!/<LocableBlobSet>[\s\S]*?<\/LocableBlobSet>/.test(pj)) throw new Error('assembleTimeline: project.xml has no LocableBlobSet for item markers');
+      for (const cut of itemMarkerCuts) {
+        for (const m of cut.markers) {
+          if (!Number.isInteger(m.frame) || m.frame < 0 || m.frame >= cut.durationFrames) {
+            throw new RangeError(`assembleTimeline: item marker frame ${m.frame} outside the cut (frames are ITEM-relative, [0, ${cut.durationFrames}))`);
+          }
+        }
+        const kind = cut.audioOnly ? 'audio' : 'video';
+        const { tracks } = getTrackVec(seqXml, kind);
+        const trackXml = tracks[(cut.track ?? 1) - 1];
+        if (!trackXml) throw new Error(`assembleTimeline: item markers — track ${cut.track ?? 1} not found`);
+        const tag = cut.audioOnly ? 'Sm2TiAudioClip' : 'Sm2TiVideoClip';
+        const re = new RegExp(`<${tag} DbId="([^"]+)">(?:(?!<\\/${tag}>)[\\s\\S])*?<Start>${cut.startFrame}<\\/Start>`);
+        const hit = trackXml.match(re);
+        if (!hit) throw new Error(`assembleTimeline: item markers — no ${kind} clip starting at ${cut.startFrame} on track ${cut.track ?? 1}`);
+        const blob = encodeTimelineMarkersBlob(cut.markers);
+        const el = `<Element>\n     <Sm2TiItemLockableBlob DbId="${randomUUID()}">\n      <FieldsBlob>${blob.toString('hex')}</FieldsBlob>\n      <BlobOwner>${hit[1]}</BlobOwner>\n      <DbSavedTime>0</DbSavedTime>\n     </Sm2TiItemLockableBlob>\n    </Element>\n   `;
+        pj = pj.replace('</LocableBlobSet>', `${el}</LocableBlobSet>`);
+      }
+      zipIM.file('project.xml', pj);
+      buffer = await zipIM.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+    }
+  }
+
   for (const [i, el] of elements.entries()) {
     if (!el || typeof el !== 'object') throw new TypeError(`assembleTimeline: elements[${i}] must be an object`);
     if (el.type === 'title') {

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

@@ -75,10 +75,15 @@ const WIPE_FIELDS_BLOB = '00000002000000158012120000002c789c636660642016000000da
 // renders INERT — so authoring through this path beats the host importer.
 // Unknown PrettyTypes are refused, not probed: unvetted strings are exactly
 // the class that crashed the app elsewhere (interp!=0, dangling ids).
+// 'Fade To Color' is deliberately ABSENT: on the dissolve skeleton its
+// behavior is duration/direction-erratic (24f rendered a ~77 plateau, 48f a
+// single black frame then a hard cut — measured E68/E75; its real params
+// live in an EffectFiltersBA no importer path can harvest, the XMEML
+// importer being inert). Dip is the verified equivalent (fade to black and
+// back, clean symmetric valley at 24f AND 48f).
 const STYLE_PRETTY_TYPES = {
   dip: 'Dip To Color Dissolve',
   additive: 'Additive Dissolve',
-  'fade-to-color': 'Fade To Color',
   'smooth-cut': 'Smooth Cut',
   'non-additive': 'Non-Additive Dissolve',
 };

package/src/granular/common.py

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

package/src/utils/api_truth.py

@@ -2694,6 +2694,28 @@ API_TRUTH: List[Dict[str, Any]] = [
         "submit": "bug",
         "mitigation": ["drt.assemble_from_interchange"],
     },
+    {
+        "symbol": "Timeline.Export EXPORT_DRT (drops timeline-item markers)",
+        "object": "Timeline",
+        "signature": "(filePath, EXPORT_DRT) -> bool",
+        "reality": "Item-level markers (clip locators) are not serialized into "
+                   "the exported .drt at all. They live in the project database "
+                   "as Sm2TiItemLockableBlob rows (same wire codec as timeline "
+                   "markers, BlobOwner = the item's DbId — located by byte "
+                   "search in a live Project.db), and readback via "
+                   "TimelineItem.GetMarkers is fine, but the export omits the "
+                   "blobs even after SaveProject — measured on Studio 19.1.3.7. "
+                   "Asymmetrically, ImportTimelineFromFile ACCEPTS an authored "
+                   "Sm2TiItemLockableBlob and the markers read back perfectly.",
+        "recommended": "Do not rely on .drt archives to carry clip markers. To "
+                       "deliver item markers in a .drt, author them offline "
+                       "(drt.assemble cuts[].markers writes the accepted blob); "
+                       "to preserve markers from a live timeline, read them via "
+                       "the marker API and re-author.",
+        "tags": ["timeline", "export", "drt", "markers", "silent-failure"],
+        "submit": "bug",
+        "mitigation": ["drt.assemble cuts[].markers"],
+    },
 ]