davinci-resolve-mcp 2.72.1 → 2.73.0

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 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.73.0
+
+The offline AAF reader could not read a multi-layer Avid timeline, and said so
+in the worst possible way: `ok: true` with an empty event list, indistinguishable
+from an empty timeline. Any caller gating on a successful parse would proceed to
+conform nothing.
+
+### Fixed
+
+- **AAF: multi-layer timelines returned zero events while reporting success.**
+  Avid exports a multi-layer video timeline as a `NestedScope` segment, which the
+  offline reader never traversed — `NestedScope` carries `.slots`, not
+  `.components`, so the whole timeline fell through the walker's lone-`SourceClip`
+  fallback and emitted nothing. Two further drops sat on the same path and had to
+  be fixed with it: `OperationGroup.segments` holds a nested `Sequence` rather than
+  a direct `SourceClip`, so effect-wrapped clips — the majority of any real
+  turnover — were dropped even once `NestedScope` was traversed; and source-name
+  resolution stopped one mob hop short of the MasterMob, because Avid routes
+  timeline clips through an unnamed intermediate `CompositionMob`, resolving most
+  clips to `UNKNOWN`. `Selector` segments are now followed (via the AAF `Selected`
+  property — pyaaf2 does not expose it as an attribute), and non-editorial slots
+  are skipped by media kind rather than segment class, so `Pulldown`-wrapped
+  timecode tracks no longer leak through as editorial.
+
+  Verified against a real 83-minute Avid picture turnover: **0 → 878 events**
+  across 5 layers, **0 `UNKNOWN` sources** (779 distinct camera rolls), no
+  unhandled component classes, ~1.5 s.
+
+### Added
+
+- AAF probe and `listAafSequences` now report an `unhandled` map (component class
+  → count) per sequence. A structural miss is visible instead of masquerading as
+  an empty timeline.
+
+### Known limitations, stated deliberately
+
+- **Motion Control retimes are flagged, not quantified.** They carry
+  `effect: "Motion Control"` with `speed: 100`, because the ratio is not
+  recoverable offline. A consumer reading `speed` alone will treat them as full
+  speed. Pre-existing behaviour, preserved on purpose — flag over fabricate.
+- **Effect-only layers correctly produce no events.** Layers that wrap
+  `ScopeReference` (subtitle burns, blends, mattes) apply to what shows through
+  from below and reference no media of their own. OTIO reports such layers as
+  tracks of gaps, so its track count can exceed the number of layers with media;
+  "6 layers" is not "6 layers with media". Events were not fabricated to make the
+  counts match.
+- **Only `NestedScope` layers are numbered `V1..Vn`.** Non-nested slots keep the
+  flat `V`/`A` label, a deliberate scope limit that keeps the blast radius off
+  simple AAFs — notably `editorial.mjs`'s `track === 'A'` audio-follows-video
+  heuristic, which reads that label.
+
 ## What's New in v2.72.1
 
 Documentation only. The API coverage page stated its method counts in four

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.72.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.73.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-34%20(341%20full)-blue.svg)](#server-modes)

package/install.py

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

package/resolve-advanced/README.md

@@ -173,6 +173,25 @@ status + install hints):
 Missing features fail with a clear, actionable message rather than crashing; the server logs a one-line
 "needs setup" summary to stderr at startup.
 
+> **Pinning the AAF interpreter.** `aaf_probe.py` runs under `AAF_PROBE_PYTHON`, falling back to
+> `PYTHON` and then plain `python3` on PATH. `install.py` sets that pin **only inside the `mcpServers`
+> JSON entry it writes**, so a host that spawns this advanced server some other way must pin it itself —
+> otherwise the reader resolves a `python3` without `pyaaf2` and honest-refuses every AAF.
+
+### AAF multi-layer reading — what it does and does not tell you
+Avid exports a multi-layer video timeline as a `NestedScope` segment holding one nested `Sequence` per
+layer; those layers are traversed and numbered `V1..Vn`. Each parsed sequence also carries an
+`unhandled` map (component class → count) so a structural miss is visible rather than arriving as a
+plausible-looking short event list. Three limits are deliberate:
+
+- **Motion Control retimes are flagged, not quantified** — `effect: "Motion Control"` with `speed: 100`,
+  because the ratio is not recoverable offline. Reading `speed` alone reports them as full speed.
+- **Effect-only layers produce no events.** A layer wrapping `ScopeReference` (subtitle burns, blends,
+  mattes) applies to what shows through from below and references no media of its own. OTIO materializes
+  such layers as tracks of gaps, so its track count can exceed the number of layers with media.
+- **Only `NestedScope` layers are numbered.** Non-nested slots keep the flat `V`/`A` label, which is what
+  `editorial.mjs`'s `track === 'A'` audio-follows-video heuristic reads.
+
 ## Provenance & license
 Vendored libraries are clean offline format-interop and deterministic compute code: no secrets, no
 external service coupling, no network calls, no LLM dependency. Where a feature can take a second

package/resolve-advanced/server/aaf.mjs

@@ -94,11 +94,21 @@ export async function parseAAF(contentOrPath) {
 
 /**
  * Enumerate the sequences inside an AAF for the picker.
+ *
+ * `unhandled` is carried through deliberately: a structural miss in the probe
+ * (a component class it cannot walk) otherwise looks identical to a genuinely
+ * empty timeline, and the caller would gate on a successful parse and conform
+ * nothing. A NestedScope — Avid's multi-layer video stack — used to land in
+ * exactly that hole: eventCount 0 alongside ok:true. Absent means clean.
  * @param {string} contentOrPath absolute .aaf path
- * @returns {Promise<Array<{id:string,name:string,eventCount:number}>>}
+ * @returns {Promise<Array<{id:string,name:string,eventCount:number,unhandled?:Object}>>}
  */
 export async function listAafSequences(contentOrPath) {
   const aafPath = resolveAafPath(contentOrPath);
   const { sequences } = await runProbe(aafPath);
-  return (sequences || []).map((s) => ({ id: String(s.id), name: String(s.name), eventCount: Number(s.eventCount || 0) }));
+  return (sequences || []).map((s) => {
+    const out = { id: String(s.id), name: String(s.name), eventCount: Number(s.eventCount || 0) };
+    if (s.unhandled && Object.keys(s.unhandled).length) out.unhandled = s.unhandled;
+    return out;
+  });
 }

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.72.1"
+VERSION = "2.73.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 341-tool granular server instead
 """
 
-VERSION = "2.72.1"
+VERSION = "2.73.0"
 
 import base64
 import os