davinci-resolve-mcp 2.173.0 → 2.175.0

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 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.175.0 — E121: a flattened XML compound is a named hole, not a refusal
+
+### Fixed
+
+- **An XML turnover with a compound clip refused to conform.** Resolve's FCP7
+  writer flattens a compound to ONE clipitem whose `<file>` carries an
+  explicitly empty `<pathurl>` and no inner content (measured on 19.1.3.7);
+  read as a source reel, `assemble_from_interchange` refused the whole
+  turnover as an unmapped reel. The walker now tags such clipitems
+  `compound`, and the bridge drops them with a reason in
+  `unresolvedCompounds` (name, track, record span) while the rest of the cut
+  conforms — unless the sourceMap maps the compound's name to a flattened
+  media file, in which case it authors like any clip. The reason points at
+  the OTIO export, where compounds keep their inner content and flatten
+  (E120).
+- `timeline.get_items` help notes that `generator` also covers Fusion titles
+  (Text+ enumerates with no media and no properties, like a generator).
+
+## What's New in v2.174.0 — E120: compound clips in Resolve's OTIO exports flatten instead of vanishing
+
+### Fixed
+
+- **A compound clip in an OTIO turnover was silently dropped.** Resolve's
+  OTIO writer nests a compound as a `Stack` inside the track — its
+  `source_range` is the trim window into the compound, and nested compounds
+  nest Stacks recursively (measured on 19.1.3.7 from a depth-2 timeline).
+  `parseOTIO` skipped the Stack, so a 96-frame timeline parsed as 48 with no
+  error. Nested Stacks now flatten into the parent's record time through
+  their trim window (source frames trimmed at each clip's own play rate,
+  inner upper tracks landing on the next lanes), each flattened cut tagged
+  `fromCompound`, and the bridge's ledger names them
+  (`flattenedCompounds`, `flattenedCompoundEvents`). Render-verified: the
+  flattened conform of Resolve's own export is luma-identical to the
+  original compound render at every sampled frame (three picture regions
+  at 123–125, the 24-frame white insert at 234).
+
+### Measured (filed in api-limitations)
+
+- `EXPORT_FCP_7_XML` flattens a compound to a single media-less clipitem
+  named after it, with no inner content; `EXPORT_OTIO` keeps the nesting.
+
 ## What's New in v2.173.0 — E118: Resolve's own OTIO exports re-conform
 
 ### Fixed

package/README.md

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

package/docs/reference/api-limitations.md

@@ -313,7 +313,7 @@ equivalent, blocking full automation.
 
 - **Object:** `MediaPool`
 - **Signature:** `(filePath.xml) -> Timeline`
-- **Behavior:** Resolve's FCP7 XML importer HONOURS a generatoritem's `fillcolor` parameter (measured on Studio 19.1.3.7, E110): a Premiere-shaped Color Matte (effectid Color, category Matte) and a Solid Color generatoritem, both with <red>/<green>/<blue>/<alpha> 0..255 values, imported as Solid Color items and rendered Y81 U90 V240 (red) and Y41 U240 V110 (blue) — exact BT.601 limited-range values for a 640x360 timeline. EXPORT_FCP_7_XML writes the fillcolor back (same 0..255 channels). EXPORT_DRT carries the colour as a 55-byte <EffectFiltersBA> on the Sm2TiGenerator: 8-byte header (version 2, length 47), a fixed 20-byte prefix, a flag byte, then big-endian uint16 A R G B (0xffff = full) plus a pad word, then a second, black colour record; only the ARGB words differed between the red and blue captures. The default generator has an EMPTY EffectFiltersBA. The same importer does NOT carry a TRANSITION's parameters: a `Dip to Color Dissolve` transitionitem with a white and with a red `color` parameter imported as `Dip To Color Dissolve` elements whose 37-byte EffectFiltersBA were byte-identical (defaults), and the transition rendered inert (luma flat through its window, the E66 law) — the dip colour stays GUI-only on 19.1.3.7 (measured, E111). The writer emits a Solid Color's colour as the FxPlug parameter `input_1` (effectid FxPlugWrapper:C18E8B62_…), not `fillcolor` — an authored EffectFiltersBA colour came back exactly (white, 128/64/191; E112). The OTIO writer CANNOT: EXPORT_OTIO emits a Solid Color as a Clip.2 named 'Solid Color' with a NULL media_reference, metadata {"Resolve_OTIO": {}} and a parameterless Transform effect — no colour anywhere (measured E117) — so only an XML re-export witnesses a generator colour (editorial.verify_roundtrip exportedFormat → generatorColourNotInExport). Such an OTIO export DOES re-conform through drt.assemble_from_interchange (E118): the media-less generator clips walk as black legs and the clip→generator fade renders 124→16 — black, the colour having been lost by the writer.
+- **Behavior:** Resolve's FCP7 XML importer HONOURS a generatoritem's `fillcolor` parameter (measured on Studio 19.1.3.7, E110): a Premiere-shaped Color Matte (effectid Color, category Matte) and a Solid Color generatoritem, both with <red>/<green>/<blue>/<alpha> 0..255 values, imported as Solid Color items and rendered Y81 U90 V240 (red) and Y41 U240 V110 (blue) — exact BT.601 limited-range values for a 640x360 timeline. EXPORT_FCP_7_XML writes the fillcolor back (same 0..255 channels). EXPORT_DRT carries the colour as a 55-byte <EffectFiltersBA> on the Sm2TiGenerator: 8-byte header (version 2, length 47), a fixed 20-byte prefix, a flag byte, then big-endian uint16 A R G B (0xffff = full) plus a pad word, then a second, black colour record; only the ARGB words differed between the red and blue captures. The default generator has an EMPTY EffectFiltersBA. The same importer does NOT carry a TRANSITION's parameters: a `Dip to Color Dissolve` transitionitem with a white and with a red `color` parameter imported as `Dip To Color Dissolve` elements whose 37-byte EffectFiltersBA were byte-identical (defaults), and the transition rendered inert (luma flat through its window, the E66 law) — the dip colour stays GUI-only on 19.1.3.7 (measured, E111). The writer emits a Solid Color's colour as the FxPlug parameter `input_1` (effectid FxPlugWrapper:C18E8B62_…), not `fillcolor` — an authored EffectFiltersBA colour came back exactly (white, 128/64/191; E112). The OTIO writer CANNOT: EXPORT_OTIO emits a Solid Color as a Clip.2 named 'Solid Color' with a NULL media_reference, metadata {"Resolve_OTIO": {}} and a parameterless Transform effect — no colour anywhere (measured E117) — so only an XML re-export witnesses a generator colour (editorial.verify_roundtrip exportedFormat → generatorColourNotInExport). Such an OTIO export DOES re-conform through drt.assemble_from_interchange (E118): the media-less generator clips walk as black legs and the clip→generator fade renders 124→16 — black, the colour having been lost by the writer. COMPOUND CLIPS: EXPORT_OTIO nests a compound as a Stack.1 inside the track (its source_range = the trim window into the compound; nested compounds nest Stacks recursively — measured E120 on a depth-2 timeline), while EXPORT_FCP_7_XML flattens the compound to a single media-less clipitem named after it (no inner content). editorial.parse_interchange flattens the OTIO Stacks into record time (fromCompound on each cut).
 - **Workaround / current handling:** Author fade-to-white / colour mattes by placing a Solid Color generator with that blob (drp-format placeGenerator `color`, drt.assemble elements[].color) — or carry an XMEML generatoritem fillcolor through editorial.parse_interchange; the bridge authors the coloured leg.
 - **Tags:** xml, import, generator, colour, export, drt
 

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.173.0"
+VERSION = "2.175.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.173.0",
+  "version": "2.175.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

@@ -281,6 +281,21 @@ export function eventsToAssembleSpec(events, opts = {}) {
   // the fade dissolves around it, measured E91); audio BL legs are silence,
   // which an empty track already is.
   const isBL = (srcName) => /^(BL|BLACK)$/i.test(String(srcName || '').trim());
+  // FLATTENED COMPOUNDS (E121): an XML clipitem that is a compound carries no
+  // inner content, so nothing can be authored for it unless the sourceMap
+  // points its name at a flattened media file. Unmapped ones are DROPPED
+  // with a reason — a hole in the conform the ledger names — rather than
+  // refusing the whole turnover as an unmapped reel.
+  const unresolvedCompounds = [];
+  for (const list of [vids, auds]) {
+    for (let i = list.length - 1; i >= 0; i -= 1) {
+      const e = list[i];
+      if (e.compound && !sourceMap[e.source]) {
+        unresolvedCompounds.push({ name: e.compound, track: e.track, recIn: e.recIn, recOut: e.recOut, reason: 'XML compound clipitem carries no inner content — re-export as OTIO (nested Stacks flatten) or map the compound name to a flattened media file in sourceMap' });
+        list.splice(i, 1);
+      }
+    }
+  }
   const unmapped = [...new Set([...vids, ...auds].map((e) => e.source).filter((srcName) => !isBL(srcName) && !sourceMap[srcName]))];
   if (unmapped.length) {
     throw new Error(
@@ -708,6 +723,11 @@ export function eventsToAssembleSpec(events, opts = {}) {
       audioEventsSkipped: audioSkipped,
       authoredMarkers: markers.length,
       audioChannelLegsMerged,
+      // Compound clips flattened out of nested OTIO Stacks (E120): named so
+      // the ledger says which compounds became flat cuts.
+      flattenedCompounds: [...new Set(events.filter((e) => e.fromCompound).map((e) => e.fromCompound))],
+      flattenedCompoundEvents: events.filter((e) => e.fromCompound).length,
+      unresolvedCompounds,
       authoredAudioEvents: audioPlacements.length,
       audioRetimesSkipped,
       ...(elements.length || audioBlackLegsSkipped ? {

package/resolve-advanced/server/editorial.mjs

@@ -52,6 +52,8 @@ function evt(o) {
     ...(o.name !== undefined ? { name: o.name } : {}),
     ...(o.color !== undefined ? { color: o.color } : {}),
     ...(o.generatorName !== undefined ? { generatorName: o.generatorName } : {}),
+    ...(o.fromCompound !== undefined ? { fromCompound: o.fromCompound } : {}),
+    ...(o.compound !== undefined ? { compound: o.compound } : {}),
     source: o.source || 'UNKNOWN',
     srcIn: o.srcIn ?? null,
     srcOut: o.srcOut ?? null,
@@ -179,6 +181,10 @@ export function parseOTIO(otio, opts = {}) {
         name: mk.name || undefined, color: mk.color || undefined, fps: mrRate,
       }));
     }
+    // Walk one track's children into `sink`. Recursive: a nested Stack (a
+    // compound clip) walks its inner tracks with a private cursor and is
+    // flattened into the parent's record time (E120).
+    const walkChildren = (children, kind, sink) => {
     let rec = 0;
     // An OTIO Transition occupies NO record time (like an AAF transition —
     // it overlaps its neighbours); it describes the junction between the
@@ -193,7 +199,7 @@ export function parseOTIO(otio, opts = {}) {
     // empty track renders black anyway, so the growth is render-neutral.
     let atBlack = true;
     const lastRate = () => opts.fps || 24;
-    for (const child of track.children || []) {
+    for (const child of 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;
@@ -201,7 +207,7 @@ export function parseOTIO(otio, opts = {}) {
         if (pendingTransition) {
           // Transition then Gap = fade-out into black: attach it to a
           // synthetic BL leg at the junction (the bridge grows it forward).
-          events.push(evt({
+          sink.push(evt({
             index: idx++, track: kind, source: 'BL',
             recIn: rec, recOut: rec, transition: pendingTransition, fps: lastRate(),
           }));
@@ -213,6 +219,50 @@ export function parseOTIO(otio, opts = {}) {
         atBlack = true;
         continue;
       }
+      if (schema.startsWith('Stack')) {
+        // NESTED STACK = a compound clip (E120, measured against Resolve's
+        // OTIO writer: a compound exports as a Stack inside the track with
+        // its own source_range = the trim window into the compound, nested
+        // recursively). It was silently DROPPED. Flatten it: walk each inner
+        // track of this kind with a private cursor, then translate its
+        // events into the parent's record time through the trim window,
+        // trimming source frames at the clip's own play rate. Inner tracks
+        // beyond the first land on the next lanes up (V2, V3 …).
+        const sr = child.source_range || {};
+        const winStart = (sr.start_time && sr.start_time.value) || 0;
+        const winDur = (sr.duration && sr.duration.value) || 0;
+        const wantAudio = /^A/.test(kind);
+        const innerTracks = (child.children || []).filter((t) => String(t.OTIO_SCHEMA || '').startsWith('Track') && ((t.kind === 'Audio') === wantAudio));
+        const baseLetter = kind.replace(/\d+$/, '');
+        const baseNum = parseInt(kind.replace(/\D/g, '') || '1', 10);
+        let first = true;
+        innerTracks.forEach((it, i) => {
+          const label = baseNum + i === 1 ? baseLetter : `${baseLetter}${baseNum + i}`;
+          const tmp = [];
+          walkChildren(it.children || [], label, tmp);
+          for (const e of tmp) {
+            if (e.track === 'MARKER') continue;
+            const a = e.recIn - winStart, b = e.recOut - winStart;
+            const a2 = Math.max(0, a), b2 = Math.min(winDur, b);
+            if (b2 <= a2) continue;
+            const k = ((e.speed ?? 100) / 100) * (e.reverse ? -1 : 1);
+            const flat = {
+              ...e, index: idx++, recIn: rec + a2, recOut: rec + b2,
+              srcIn: e.srcIn != null ? e.srcIn + (a2 - a) * k : e.srcIn,
+              srcOut: e.srcOut != null ? e.srcOut - (b - b2) * k : e.srcOut,
+              fromCompound: child.name || 'compound',
+            };
+            // A transition pending INTO the compound attaches to its first flattened cut.
+            if (first && pendingTransition && !flat.transition) flat.transition = pendingTransition;
+            first = false;
+            sink.push(flat);
+          }
+        });
+        pendingTransition = null;
+        atBlack = false;
+        rec += winDur;
+        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;
@@ -225,7 +275,7 @@ export function parseOTIO(otio, opts = {}) {
         if (pendingTransition && atBlack) {
           // Gap (or track start) then Transition then Clip = fade-IN from
           // black — the CMX zero-length-BL form, grown by the bridge.
-          events.push(evt({
+          sink.push(evt({
             index: idx++, track: kind, source: 'BL',
             recIn: rec, recOut: rec, fps: rate,
           }));
@@ -276,7 +326,7 @@ export function parseOTIO(otio, opts = {}) {
           const mrStart = (mk.marked_range && mk.marked_range.start_time && mk.marked_range.start_time.value) || 0;
           itemMarkers.push({ frame: mrStart - startVal, name: mk.name || undefined, color: mk.color || undefined });
         }
-        events.push(
+        sink.push(
           evt({
             index: idx++,
             track: kind,
@@ -300,11 +350,13 @@ export function parseOTIO(otio, opts = {}) {
     }
     if (pendingTransition) {
       // Transition as the LAST child = fade-out to the end of the track.
-      events.push(evt({
+      sink.push(evt({
         index: idx++, track: kind, source: 'BL',
         recIn: rec, recOut: rec, transition: pendingTransition, fps: lastRate(),
       }));
     }
+    };
+    walkChildren(track.children || [], kind, events);
   }
   return events;
 }
@@ -407,7 +459,12 @@ export function parseXMEMLEvents(xml, opts = {}) {
         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: Number.isFinite(inF) ? inF + inAdj : inF, srcOut: Number.isFinite(outF) ? outF + inAdj : outF, recIn: start, recOut: end, speed, reverse, itemMarkers: itemMarkers.length ? itemMarkers : undefined, color: it.__genColor || undefined, fps: seqRate }));
+        // Resolve's FCP7 writer flattens a COMPOUND CLIP to one clipitem whose
+        // <file> carries an explicitly EMPTY <pathurl> and no inner content
+        // (measured E120/E121). Tag it so the bridge can drop it with a
+        // reason instead of refusing the whole turnover as an unmapped reel.
+        const isCompound = !!(it.file && typeof it.file.pathurl === 'string' && it.file.pathurl.trim() === '' && !it.__genColor && name !== 'BL');
+        events.push(evt({ index: idx++, track, source: name, srcIn: Number.isFinite(inF) ? inF + inAdj : inF, srcOut: Number.isFinite(outF) ? outF + inAdj : outF, recIn: start, recOut: end, speed, reverse, itemMarkers: itemMarkers.length ? itemMarkers : undefined, color: it.__genColor || undefined, compound: isCompound ? name : undefined, fps: seqRate }));
       }
     }
   };

package/resolve-advanced/server/tools/editorial.mjs

@@ -86,7 +86,7 @@ const markerSchema = z.object({
 export const editorialTool = {
   name: 'editorial',
   description:
-    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively — incl. Resolve-written OTIO generator clips (a Solid Color is a Clip with a NULL media_reference; it walks as a BL leg with generatorName, and an OTIO GeneratorReference carries its colour) so Resolve\'s own OTIO exports re-conform, Resolve-written FCP7 -1 junction edges (paired in record order) + Solid Color / Color Matte generators carrying their `fillcolor` (BL legs with `color` → fade-to-white and colour mattes author, E110), XMEML audio-track transitionitems as audio cross-fades on numbered lanes A/A2/…, and CMX FROM/TO CLIP NAME comments over the generic AX reel — + AAF via pyaaf2 (flat sound/picture slots number A/A2/… and V/V2/… in slot order so separate beds keep their lanes; NestedScope layers keep layer numbering) + PRPROJ via gunzip+XML → normalized events incl. span-explicit transitions, BL fade legs, and freezes as zero-speed events (OTIO FreezeFrame, XMEML timeremap 0, PrProj in==out, AAF 0% motion effects); for AAF/PRPROJ pass the file PATH as content; AAF also returns per-sequence startTimecode/startFrame — build the timeline at THAT start, not the Resolve 01:00:00:00 default — and per-clip `geometry` for Avid transform effects), list_sequences (ONE offline picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}], plus startTimecode/startFrame for AAF), convert_to_interchange (author OTIO/EDL/DRT Resolve CAN import from events or a parsed source; the EDL target writes CMX transition pairs incl. BL fades — the .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions survive and per-clip effects/color do not. SPEED/REVERSE survive on the otio (LinearTimeWarp) and edl (M2) targets ONLY — this FLAT drt target flattens every retime to 100% forward and returns `flattened`/`flattenedCount` naming each event that lost one (`flattened` is always present on `drt`, empty when there were none); for a .drt that AUTHORS retimes/dissolves/multi-track/audio, use drt.assemble_from_interchange), turnover_changelist (diff old vs new → moved/retimed/trimmed/replaced/new/gone PLUS the junction diff: transition_added/transition_dropped/transition_changed with fade in/out or dissolve, outgoing/incoming, span and duration/type/pre-roll deltas — zero-length CMX carrier lines and the BL legs that carry fades fold into the junction diff instead of reading as gone/new sources; events pair by closest record position, consumed once, so a source cut twice at two speeds compares instance to instance; + timing flags incl. transition_dropped and dropped_split_audio on any A-track), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base; BL-aware — black legs need no source, fades no black-side handles, and a fade-out tail requirement lands on the picture source), marker_roundtrip (markers with provenance tags), verify_roundtrip (input events vs re-export events -> pass/mismatches + fitted per-source TC offsets + marker compare w/ markersNotInExport honesty flag; FADE-AWARE: BL/Solid-Color legs merge out as blackSegments and fade-window boundary reshapes are excused into fadeReshapedBoundaries instead of failing; RETIME-AWARE: speed/reverse compare pairwise — EXPORT_OTIO carries an authored Sm2TimeMap back as LinearTimeWarp (measured), so a flattened/lost retime fails as drift geometry alone cannot catch; AUDIO-AWARE: declared audio events compare (a video-only export such as EXPORT_EDL flags audioNotInExport instead of failing) (channel legs deduped, mismatches tagged trackType audio) while the mirrored-A1 export of a video-only turnover stays informational; COLOUR-AWARE: an input generator leg carrying a fillcolor (fade-to-white, colour matte) must come back on the same track over its span with the same colour — Resolve\'s FCP7 writer emits it — else generator-colour fails (generatorColours reports the compare) — pass exportedFormat: an OTIO/EDL re-export cannot carry colour (measured) and reports generatorColourNotInExport instead of failing; the conform QC loop-closer). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
+    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively — incl. Resolve-written OTIO generator clips (a Solid Color is a Clip with a NULL media_reference; it walks as a BL leg with generatorName, and an OTIO GeneratorReference carries its colour) and nested OTIO Stacks (compound clips — Resolve\'s writer nests them with a trim window) FLATTEN into record time with fromCompound on each cut, so Resolve\'s own OTIO exports re-conform (its FCP7 XML writer flattens a compound to ONE media-less clipitem instead — tagged `compound`, which the bridge drops with a reason in unresolvedCompounds unless the sourceMap maps the compound name to a flattened media file), Resolve-written FCP7 -1 junction edges (paired in record order) + Solid Color / Color Matte generators carrying their `fillcolor` (BL legs with `color` → fade-to-white and colour mattes author, E110), XMEML audio-track transitionitems as audio cross-fades on numbered lanes A/A2/…, and CMX FROM/TO CLIP NAME comments over the generic AX reel — + AAF via pyaaf2 (flat sound/picture slots number A/A2/… and V/V2/… in slot order so separate beds keep their lanes; NestedScope layers keep layer numbering) + PRPROJ via gunzip+XML → normalized events incl. span-explicit transitions, BL fade legs, and freezes as zero-speed events (OTIO FreezeFrame, XMEML timeremap 0, PrProj in==out, AAF 0% motion effects); for AAF/PRPROJ pass the file PATH as content; AAF also returns per-sequence startTimecode/startFrame — build the timeline at THAT start, not the Resolve 01:00:00:00 default — and per-clip `geometry` for Avid transform effects), list_sequences (ONE offline picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}], plus startTimecode/startFrame for AAF), convert_to_interchange (author OTIO/EDL/DRT Resolve CAN import from events or a parsed source; the EDL target writes CMX transition pairs incl. BL fades — the .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions survive and per-clip effects/color do not. SPEED/REVERSE survive on the otio (LinearTimeWarp) and edl (M2) targets ONLY — this FLAT drt target flattens every retime to 100% forward and returns `flattened`/`flattenedCount` naming each event that lost one (`flattened` is always present on `drt`, empty when there were none); for a .drt that AUTHORS retimes/dissolves/multi-track/audio, use drt.assemble_from_interchange), turnover_changelist (diff old vs new → moved/retimed/trimmed/replaced/new/gone PLUS the junction diff: transition_added/transition_dropped/transition_changed with fade in/out or dissolve, outgoing/incoming, span and duration/type/pre-roll deltas — zero-length CMX carrier lines and the BL legs that carry fades fold into the junction diff instead of reading as gone/new sources; events pair by closest record position, consumed once, so a source cut twice at two speeds compares instance to instance; + timing flags incl. transition_dropped and dropped_split_audio on any A-track), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base; BL-aware — black legs need no source, fades no black-side handles, and a fade-out tail requirement lands on the picture source), marker_roundtrip (markers with provenance tags), verify_roundtrip (input events vs re-export events -> pass/mismatches + fitted per-source TC offsets + marker compare w/ markersNotInExport honesty flag; FADE-AWARE: BL/Solid-Color legs merge out as blackSegments and fade-window boundary reshapes are excused into fadeReshapedBoundaries instead of failing; RETIME-AWARE: speed/reverse compare pairwise — EXPORT_OTIO carries an authored Sm2TimeMap back as LinearTimeWarp (measured), so a flattened/lost retime fails as drift geometry alone cannot catch; AUDIO-AWARE: declared audio events compare (a video-only export such as EXPORT_EDL flags audioNotInExport instead of failing) (channel legs deduped, mismatches tagged trackType audio) while the mirrored-A1 export of a video-only turnover stays informational; COLOUR-AWARE: an input generator leg carrying a fillcolor (fade-to-white, colour matte) must come back on the same track over its span with the same colour — Resolve\'s FCP7 writer emits it — else generator-colour fails (generatorColours reports the compare) — pass exportedFormat: an OTIO/EDL re-export cannot carry colour (measured) and reports generatorColourNotInExport instead of failing; the conform QC loop-closer). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
   async handler({ action, args }) {
     if (action === 'parse_interchange') {
       const p = parseSchema.parse(args);

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.173.0"
+VERSION = "2.175.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.173.0"
+VERSION = "2.175.0"
 
 import base64
 import os
@@ -26250,7 +26250,7 @@ _ACTION_HELP: Dict[str, Dict[str, Dict[str, Any]]] = {
     },
     "timeline": {
         "get_items": {
-            "summary": "List items on one track as a summary (name/id/start/end/duration/kind). Transitions ARE items — a video Cross Dissolve by name, an AUDIO cross-fade with an EMPTY name — and generators/subtitles look identical to them by media-pool item and properties (all None), so `kind` (clip | transition | generator | subtitle) is decided by geometry: a transition straddles a cut.",
+            "summary": "List items on one track as a summary (name/id/start/end/duration/kind). Transitions ARE items — a video Cross Dissolve by name, an AUDIO cross-fade with an EMPTY name — and generators/subtitles look identical to them by media-pool item and properties (all None), so `kind` (clip | transition | generator | subtitle) is decided by geometry: a transition straddles a cut; `generator` also covers Fusion titles (Text+), which enumerate the same way.",
             "params": "track_type (video|audio|subtitle), index|track_index (1-based)",
             "returns": "{items: [{name, id, start, end, duration, kind}]}",
             "example": 'timeline(action="get_items", params={"track_type": "video", "index": 1})',

package/src/utils/api_truth.py

@@ -2851,7 +2851,15 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "re-conform through drt.assemble_from_interchange (E118): the "
                    "media-less generator clips walk as black legs and the "
                    "clip→generator fade renders 124→16 — black, the colour "
-                   "having been lost by the writer.",
+                   "having been lost by the writer. COMPOUND CLIPS: EXPORT_OTIO "
+                   "nests a compound as a Stack.1 inside the track (its "
+                   "source_range = the trim window into the compound; nested "
+                   "compounds nest Stacks recursively — measured E120 on a "
+                   "depth-2 timeline), while EXPORT_FCP_7_XML flattens the "
+                   "compound to a single media-less clipitem named after it "
+                   "(no inner content). editorial.parse_interchange flattens "
+                   "the OTIO Stacks into record time (fromCompound on each "
+                   "cut).",
         "recommended": "Author fade-to-white / colour mattes by placing a "
                        "Solid Color generator with that blob "
                        "(drp-format placeGenerator `color`, drt.assemble "