davinci-resolve-mcp 2.170.0 → 2.171.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 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.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.171.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.171.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.171.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
 

package/install.py

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

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/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.170.0"
+VERSION = "2.171.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.171.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 "