davinci-resolve-mcp 2.170.0 → 2.172.0

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 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.172.0 — E117: colour QC knows which writers are colour-blind
+
+### Fixed
+
+- **`verify_roundtrip` no longer fails a colour compare against a re-export
+  that cannot carry colour.** Measured on 19.1.3.7: Resolve's OTIO writer
+  emits a Solid Color as a `Clip` with a null `media_reference` and empty
+  `Resolve_OTIO` metadata — no colour anywhere (its FCP7 XML writer echoes
+  the colour as `input_1`). Pass `exportedFormat` (otio|edl|xml|drt): a
+  colour-blind export reports `generatorColourNotInExport` (like
+  `markersNotInExport`) instead of `generator-colour` failures; an XML
+  export keeps the strict compare. Without the format the compare stays
+  strict. Resolve's OTIO export is a permanent fixture.
+
+### Measured (filed in api-limitations)
+
+- `EXPORT_OTIO` writes generators as media-less clips named after the
+  generator with no parameters; `Cross Dissolve` transitions carry a
+  `transitionCustomCurvesKeyframes` 0→1 curve in `Resolve_OTIO` metadata.
+
+## What's New in v2.171.0 — E114: audio-lane `-1` edges take their own lane's junctions
+
+### Fixed
+
+- **XMEML audio cross-fades lost 12 source frames on the incoming clip.**
+  Resolve's FCP7 writer emits an audio cross-fade as a transitionitem on the
+  audio track with `-1` clip edges exactly like video (measured on 19.1.3.7
+  from the E109 AAF conform; its OTIO writer emits the same cross-fade as a
+  `Custom_Transition` with 12/12 offsets). The E108 audio walk attached the
+  transition but never computed that lane's junction list, so the incoming
+  clip's `<in>` (the source at the OVERLAP start) lost its junction offset and
+  `verify_roundtrip` failed the AAF → conform → import → XML loop with a
+  12-frame audio `source-frames` drift. Each lane now resolves against its
+  own transitionitems; the loop verifies `pass: true` through both writers.
+- **v2.170.0's `kind` classifier was wrong for generators and subtitles.**
+  Measured on 19.1.3.7 (E115): a Solid Color generator and a subtitle item
+  return no MediaPoolItem and `None` from GetProperty() — exactly like a
+  transition — so the "no media, empty properties" rule labelled both
+  `transition`. The discriminator is now GEOMETRY: a transition straddles a
+  cut (one neighbour ends inside its span, another starts inside it), a
+  generator owns its span, subtitle tracks report `subtitle`, and known
+  transition names short-circuit. Verified against Resolve's own enumeration
+  of the E107 fades timeline (generator, dissolve, clip, dissolve, clip,
+  dissolve, generator).
+- **v2.170.0 also shipped with two red Python tests** — an item-shape
+  assertion in the `get_items` selector test that did not expect the new
+  `kind` field. The expectation is updated.
+
 ## What's New in v2.170.0 — E113: `get_items` knows a transition from a clip
 
 ### Added

package/README.md

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

package/docs/reference/api-limitations.md

@@ -89,7 +89,7 @@ equivalent, blocking full automation.
 ### Transition create / copy / clone
 
 - **Object:** `Timeline / TimelineItem`
-- **Behavior:** There is no method to ADD or CLONE an edit transition — no AddTransition/CreateTransition/AddVideoTransition on Timeline or TimelineItem (dir(), 21.0.4.5). CORRECTION, measured on Studio 21.0.4.5 (2026-08-12): this entry previously said transitions applied in the UI are 'invisible to and unmodifiable by scripts'. BOTH HALVES WERE WRONG and are withdrawn. A transition IS a first-class timeline item: a 12-frame Cross Dissolve applied through the Edit-page right-click menu enumerates in GetItemListInTrack('video', 1) as GetName()=='Cross Dissolve', GetStart()==86426, GetDuration()==12 — centered on a cut at 86432 — with a stable GetUniqueId() and a working GetTrackTypeAndIndex(). A transition authored offline into a .drp and imported reads IDENTICALLY, so the route that created it does not matter. It is also REMOVABLE: Timeline.DeleteClips([transition], False) returns True and deletes it, leaving both adjacent clips at their original starts and durations. THE DISCRIMINATOR between a transition item and a clip item is GetProperty(): a transition returns an EMPTY dict where a video clip returns 26 transform keys; it also has no MediaPoolItem and no Fusion comp. WHAT IS GENUINELY MISSING: creation, cloning, and any type/alignment/parameter detail — the transition's kind is knowable ONLY from its name string, and there is no way to read its alignment (centered/start/end) or edit its duration. AUDIO NUANCE (measured 2026-09-01 on 19.1.3.7, E113): an audio cross-fade enumerates in GetItemListInTrack('audio', n) with an EMPTY GetName() (24 frames, centered on the cut, between the two clips) — so on audio lanes even the kind is not readable from the name. The discriminator that holds for BOTH: GetMediaPoolItem() is None AND GetProperty() is empty; a Solid Color generator has no MediaPoolItem either but DOES return transform keys. timeline.get_items reports `kind`.
+- **Behavior:** There is no method to ADD or CLONE an edit transition — no AddTransition/CreateTransition/AddVideoTransition on Timeline or TimelineItem (dir(), 21.0.4.5). CORRECTION, measured on Studio 21.0.4.5 (2026-08-12): this entry previously said transitions applied in the UI are 'invisible to and unmodifiable by scripts'. BOTH HALVES WERE WRONG and are withdrawn. A transition IS a first-class timeline item: a 12-frame Cross Dissolve applied through the Edit-page right-click menu enumerates in GetItemListInTrack('video', 1) as GetName()=='Cross Dissolve', GetStart()==86426, GetDuration()==12 — centered on a cut at 86432 — with a stable GetUniqueId() and a working GetTrackTypeAndIndex(). A transition authored offline into a .drp and imported reads IDENTICALLY, so the route that created it does not matter. It is also REMOVABLE: Timeline.DeleteClips([transition], False) returns True and deletes it, leaving both adjacent clips at their original starts and durations. THE DISCRIMINATOR between a transition item and a clip item is GetProperty(): a transition returns an EMPTY dict where a video clip returns 26 transform keys; it also has no MediaPoolItem and no Fusion comp. WHAT IS GENUINELY MISSING: creation, cloning, and any type/alignment/parameter detail — the transition's kind is knowable ONLY from its name string, and there is no way to read its alignment (centered/start/end) or edit its duration. AUDIO NUANCE (measured 2026-09-01 on 19.1.3.7, E113): an audio cross-fade enumerates in GetItemListInTrack('audio', n) with an EMPTY GetName() (24 frames, centered on the cut, between the two clips) — so on audio lanes even the kind is not readable from the name. The discriminator that holds for BOTH: GetMediaPoolItem() is None AND GetProperty() is empty — BUT a Solid Color generator AND a subtitle item read the same way (GetProperty() None, no MediaPoolItem; measured E115), so that pair only separates clips from non-clips. What separates a transition from a generator is GEOMETRY: a transition straddles a cut (one neighbour ends inside its span, another starts inside it) while a generator owns its span. timeline.get_items reports `kind` on that basis.
 - **Workaround / current handling:** Automated QC of existing transitions IS possible and is the main practical need — enumerate GetItemListInTrack, treat any item whose GetProperty() is empty and whose GetMediaPoolItem() is None as a transition, and read its name, start and duration. Removal is scriptable via Timeline.DeleteClips. To CREATE one, either apply it in the Resolve UI, or author it offline and import: the advanced server's drp place_transition writes a cross dissolve at an abutting cut ({track, atFrame, durationFrames}) and it round-trips into Resolve 21.0.4.5 reading back at the expected centered range.
 - **Tags:** missing-method, timeline, transition
 
@@ -305,7 +305,7 @@ equivalent, blocking full automation.
 
 - **Object:** `Timeline`
 - **Signature:** `(filePath, EXPORT_EDL, EXPORT_NONE) -> bool`
-- **Behavior:** Resolve's CMX EDL writer (measured on Studio 19.1.3.7, E105) emits VIDEO events only — audio legs never appear; names every file source by the generic reel AX and carries the real names in `* FROM CLIP NAME:` / `* TO CLIP NAME:` comments; writes black legs as reel BL; places dissolve junctions at the CMX start-at-cut position (the overlap start, not the centered junction the timeline holds); and WRITES BL fades that its own EDL importer then drops. The FCP7 XML writer, by contrast, carries audio, writes transition-adjacent clip edges as -1 (the junction), and emits `speed` followed by `variablespeed` 0 in the same timeremap effect.
+- **Behavior:** Resolve's CMX EDL writer (measured on Studio 19.1.3.7, E105) emits VIDEO events only — audio legs never appear; names every file source by the generic reel AX and carries the real names in `* FROM CLIP NAME:` / `* TO CLIP NAME:` comments; writes black legs as reel BL; places dissolve junctions at the CMX start-at-cut position (the overlap start, not the centered junction the timeline holds); and WRITES BL fades that its own EDL importer then drops. The FCP7 XML writer, by contrast, carries audio, writes transition-adjacent clip edges as -1 (the junction), and emits `speed` followed by `variablespeed` 0 in the same timeremap effect. AUDIO cross-fades are written the same way — a transitionitem on the audio track between -1-edged clipitems (measured E114); the OTIO writer emits them as a `Custom_Transition` with symmetric offsets on the Audio track.
 - **Workaround / current handling:** For round-trip QC prefer EXPORT_OTIO (carries audio, retimes as LinearTimeWarp/FreezeFrame, exact spans). When an EDL is the required deliverable, expect no audio (editorial.verify_roundtrip reports audioNotInExport) and resolve AX reels through the clip-name comments (parseEDL does). Use EXPORT_EDL — there is no EXPORT_CMX_3600 constant, and an unknown name reaches Export as a string that returns a bare False (timeline.export_timeline_checked now refuses it loudly).
 - **Tags:** timeline, export, edl, audio, silent-failure
 
@@ -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).
+- **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).
 - **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.170.0"
+VERSION = "2.172.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.170.0",
+  "version": "2.172.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

@@ -986,10 +986,20 @@ export function verifyRoundtrip(inputEvents, exportedEvents, opts = {}) {
   const colourKey = (c) => (c ? [c.r, c.g, c.b].map((v) => Math.round(v * 255)).join(',') : '0,0,0');
   const colourTol = 1 / 255 + 1e-9;
   const sameColour = (x, y) => ['r', 'g', 'b'].every((k) => Math.abs((x ? x[k] : 0) - (y ? y[k] : 0)) <= colourTol);
+  // Which writers can WITNESS a generator colour (measured, E112/E117):
+  // Resolve's FCP7 XML export echoes it (`input_1`); its OTIO export writes
+  // a Solid Color as a Clip with a NULL media_reference and empty metadata —
+  // no colour anywhere — and an EDL/DRT re-export carries none either. A
+  // colour compare against such an export can only ever "fail", so it is
+  // reported as generatorColourNotInExport instead (like markersNotInExport).
+  const exportedFormat = String(opts.exportedFormat || '').toLowerCase();
+  const colourCapable = exportedFormat === '' || /^(xml|xmeml|fcp7|fcpxml)$/.test(exportedFormat);
+  let generatorColourNotInExport = false;
   {
     const inLegs = a0.filter((e) => isBlackSeg(e) && e.color);
+    if (inLegs.length && !colourCapable) generatorColourNotInExport = true;
     const exLegs = b0.filter((e) => isBlackSeg(e));
-    for (const leg of inLegs) {
+    for (const leg of generatorColourNotInExport ? [] : inLegs) {
       const partner = exLegs.find((x) => x.track === leg.track && x.recIn < leg.recOut && x.recOut > leg.recIn);
       generatorColours.compared += 1;
       if (!partner) {
@@ -1070,6 +1080,7 @@ export function verifyRoundtrip(inputEvents, exportedEvents, opts = {}) {
   return {
     pass: mismatches.length === 0, pairs: n, srcOffsets, mismatches, markers,
     ...(generatorColours.compared ? { generatorColours } : {}),
+    ...(generatorColourNotInExport ? { generatorColourNotInExport } : {}),
     ...(markersNotInExport ? { markersNotInExport } : {}),
     ...(blackSegments.input || blackSegments.exported ? { blackSegments } : {}),
     ...(fadeReshapedBoundaries.length ? { fadeReshapedBoundaries } : {}),

package/resolve-advanced/server/editorial.mjs

@@ -390,6 +390,18 @@ export function parseXMEMLEvents(xml, opts = {}) {
       }
     }
   };
+  // A track's transitionitems as -1-edge junctions (alignment-dependent frame
+  // plus the span), shared by video and audio lanes.
+  const trackJunctionsOf = (t) => {
+    const tlist = t.transitionitem ? (Array.isArray(t.transitionitem) ? t.transitionitem : [t.transitionitem]) : [];
+    return tlist.map((tr) => {
+      const s0 = Number(tr.start), e0 = Number(tr.end);
+      if (!Number.isFinite(s0) || !Number.isFinite(e0)) return null;
+      const al = String(tr.alignment || 'center').toLowerCase();
+      const frame = al === 'start-black' || al === 'start' ? s0 : al === 'end-black' || al === 'end' ? e0 : Math.round((s0 + e0) / 2);
+      return { frame, start: s0, end: e0 };
+    }).filter(Boolean);
+  };
   // Attach a track's <transitionitem> siblings to its walked events. Shared
   // by VIDEO and AUDIO tracks (E108): audio cross-fades used to be dropped at
   // parse because only the video walk looked at transitionitems, so an XMEML
@@ -447,14 +459,7 @@ export function parseXMEMLEvents(xml, opts = {}) {
       const label = vi === 0 ? 'V' : `V${vi + 1}`;
       const before = events.length;
       // Junctions of this track's transitionitems, for -1 edge resolution.
-      const tlist = t.transitionitem ? (Array.isArray(t.transitionitem) ? t.transitionitem : [t.transitionitem]) : [];
-      currentJunctions = tlist.map((tr) => {
-        const s0 = Number(tr.start), e0 = Number(tr.end);
-        if (!Number.isFinite(s0) || !Number.isFinite(e0)) return null;
-        const al = String(tr.alignment || 'center').toLowerCase();
-        const frame = al === 'start-black' || al === 'start' ? s0 : al === 'end-black' || al === 'end' ? e0 : Math.round((s0 + e0) / 2);
-        return { frame, start: s0, end: e0 };
-      }).filter(Boolean);
+      currentJunctions = trackJunctionsOf(t);
       // Solid Color / Color Matte generatoritems are GENERATOR legs: black by
       // default (what Resolve writes for a fade's black side), or the
       // `fillcolor` the item declares — Resolve's importer honours it and
@@ -480,6 +485,11 @@ export function parseXMEMLEvents(xml, opts = {}) {
       const label = ai === 0 ? 'A' : `A${ai + 1}`;
       const before = events.length;
       clipCursor = 0;
+      // Audio lanes carry -1 edges under their cross-fades exactly like video
+      // (Resolve's writer, measured E114: the incoming clip's <in> is the
+      // source at the overlap start and needs the junction offset) — the
+      // junction list must be THIS lane's, not the last video track's.
+      currentJunctions = trackJunctionsOf(t);
       if (t.clipitem) walk(t.clipitem, label);
       currentJunctions = [];
       attachTransitions(t, label, before);

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 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); 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 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);
@@ -158,6 +158,8 @@ export const editorialTool = {
         srcTol: z.number().optional(),
         sourceMap: z.record(z.object({ mediaFilePath: z.string() }).passthrough()).optional()
           .describe('The SAME reel→{mediaFilePath} map the assemble used — lets an EDL reel (CUTSRC) match the re-export\'s file basename (cut_src)'),
+        exportedFormat: z.string().optional()
+          .describe('Format of the re-export (otio|edl|xml|drt). Generator COLOUR can only be witnessed by an XML re-export (Resolve\'s OTIO/EDL writers carry none — measured); pass it so a colour compare against a colour-blind export reports generatorColourNotInExport instead of failing'),
       }).parse(args);
       // EDL reels vs exported basenames: derive the alias table from the
       // sourceMap that drove the assemble (the one authority linking them).
@@ -166,7 +168,7 @@ export const editorialTool = {
         const base = String(src.mediaFilePath).split('/').pop();
         if (base) sourceAliases[reel] = base;
       }
-      return verifyRoundtrip(p.input, p.exported, { recTol: p.recTol, srcTol: p.srcTol, sourceAliases });
+      return verifyRoundtrip(p.input, p.exported, { recTol: p.recTol, srcTol: p.srcTol, sourceAliases, exportedFormat: p.exportedFormat });
     }
     if (action === 'marker_roundtrip') {
       const p = markerSchema.parse(args);

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.170.0"
+VERSION = "2.172.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.170.0"
+VERSION = "2.172.0"
 
 import base64
 import os
@@ -2604,33 +2604,51 @@ def _find_timeline_item_by_id(tl, timeline_item_id) -> Optional[Any]:
     return None
 
 
-def _describe_track_item(it) -> Dict[str, Any]:
-    """One GetItemListInTrack entry → {name, id, start, end, duration, kind}.
+_TRANSITION_NAMES = {
+    "cross dissolve", "dip to color dissolve", "additive dissolve", "non-additive dissolve",
+    "smooth cut", "blur dissolve", "cross fade", "cross fade 0db", "cross fade +3db", "cross fade -3db",
+}
+
+
+def _describe_track_items(items, track_type: str):
+    """GetItemListInTrack entries → [{name, id, start, end, duration, kind}].
 
-    Transitions ARE items in that list (api_truth): a video Cross Dissolve
-    enumerates by its name, but an AUDIO cross-fade enumerates with an EMPTY
-    name (measured 2026-09-01, Studio 19.1.3.7, E113) — so the name string can
-    never be the discriminator. A transition has no MediaPoolItem and an empty
-    GetProperty() dict; a clip has both. `kind` reports that.
+    Transitions ARE items in that list (api_truth). What does NOT tell them
+    apart, measured 2026-09-01 on Studio 19.1.3.7 (E113/E115): the name (an
+    AUDIO cross-fade enumerates with an EMPTY name), GetMediaPoolItem() (a
+    Solid Color generator and a subtitle have none either) and GetProperty()
+    (generator and subtitle both return None, like a transition). What does:
+    GEOMETRY — a transition straddles a cut, so one neighbour ENDS inside its
+    span and another STARTS inside it; a generator or clip owns its span.
+    kind: clip (has a MediaPoolItem) | transition (known name, or no media and
+    straddles a cut) | generator (no media, owns its span) | subtitle (track).
     """
-    kind = "clip"
-    try:
-        has_media = it.GetMediaPoolItem() is not None
-    except Exception:
-        has_media = True  # an API surprise must not demote a clip to a transition
-    if not has_media:
+    raw = []
+    for it in items or []:
         try:
-            props = it.GetProperty()
+            has_media = it.GetMediaPoolItem() is not None
         except Exception:
-            props = None
-        if not props:
+            has_media = True  # an API surprise must not demote a clip
+        raw.append({
+            "name": it.GetName(), "id": it.GetUniqueId(), "start": it.GetStart(),
+            "end": it.GetEnd(), "duration": it.GetDuration(), "_media": has_media,
+        })
+    out = []
+    for r in raw:
+        name = str(r["name"] or "").strip().lower()
+        if track_type == "subtitle":
+            kind = "subtitle"
+        elif r["_media"]:
+            kind = "clip"
+        elif name in _TRANSITION_NAMES:
             kind = "transition"
         else:
-            kind = "generator"  # no media, but transform keys: Solid Color / titles
-    return {
-        "name": it.GetName(), "id": it.GetUniqueId(), "start": it.GetStart(),
-        "end": it.GetEnd(), "duration": it.GetDuration(), "kind": kind,
-    }
+            s0, e0 = r["start"], r["end"]
+            ends_inside = any(o is not r and o["end"] is not None and s0 < o["end"] <= e0 for o in raw)
+            starts_inside = any(o is not r and o["start"] is not None and s0 <= o["start"] < e0 for o in raw)
+            kind = "transition" if (ends_inside and starts_inside) else "generator"
+        out.append({k: v for k, v in r.items() if k != "_media"} | {"kind": kind})
+    return out
 
 
 def _get_timeline_item_for_fusion(p: Dict[str, Any]):
@@ -24444,7 +24462,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
         if err:
             return _err(err)
         items = tl.GetItemListInTrack(track_type, track_index)
-        return {"items": [_describe_track_item(it) for it in (items or [])]}
+        return {"items": _describe_track_items(items, track_type)}
     elif action == "delete_clips":
         # Find timeline items by unique IDs
         ids_set = set(p["clip_ids"])
@@ -26232,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 — so `kind` (clip | transition | generator) is the discriminator, never the name.",
+            "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.",
             "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

@@ -895,9 +895,14 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "with an EMPTY GetName() (24 frames, centered on the cut, "
                    "between the two clips) — so on audio lanes even the kind is "
                    "not readable from the name. The discriminator that holds for "
-                   "BOTH: GetMediaPoolItem() is None AND GetProperty() is empty; "
-                   "a Solid Color generator has no MediaPoolItem either but DOES "
-                   "return transform keys. timeline.get_items reports `kind`.",
+                   "BOTH: GetMediaPoolItem() is None AND GetProperty() is empty — "
+                   "BUT a Solid Color generator AND a subtitle item read the same "
+                   "way (GetProperty() None, no MediaPoolItem; measured E115), so "
+                   "that pair only separates clips from non-clips. What separates "
+                   "a transition from a generator is GEOMETRY: a transition "
+                   "straddles a cut (one neighbour ends inside its span, another "
+                   "starts inside it) while a generator owns its span. "
+                   "timeline.get_items reports `kind` on that basis.",
         "recommended": "Automated QC of existing transitions IS possible and is "
                        "the main practical need — enumerate GetItemListInTrack, "
                        "treat any item whose GetProperty() is empty and whose "
@@ -2787,7 +2792,11 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "FCP7 XML writer, by contrast, carries audio, writes "
                    "transition-adjacent clip edges as -1 (the junction), and "
                    "emits `speed` followed by `variablespeed` 0 in the same "
-                   "timeremap effect.",
+                   "timeremap effect. AUDIO cross-fades are written the same way "
+                   "— a transitionitem on the audio track between -1-edged "
+                   "clipitems (measured E114); the OTIO writer emits them as a "
+                   "`Custom_Transition` with symmetric offsets on the Audio "
+                   "track.",
         "recommended": "For round-trip QC prefer EXPORT_OTIO (carries audio, "
                        "retimes as LinearTimeWarp/FreezeFrame, exact spans). "
                        "When an EDL is the required deliverable, expect no "
@@ -2832,7 +2841,13 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "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).",
+                   "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).",
         "recommended": "Author fade-to-white / colour mattes by placing a "
                        "Solid Color generator with that blob "
                        "(drp-format placeGenerator `color`, drt.assemble "