davinci-resolve-mcp 2.75.0 → 2.76.0

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 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.76.0
+
+Three AAF conform-fidelity fixes found by placing a full 83-minute Avid turnover and
+cross-checking it against Resolve's own native import of the same file.
+
+### Fixed
+
+- **AAF transitions did not subtract from record advancement.** In the AAF Edit
+  Protocol a Transition does not occupy record time, it *overlaps* its neighbours:
+  `sequence length == sum(components) − sum(transitions)`. The walker annotated the
+  clip after a dissolve but never rewound the record position, so **every later event
+  on that track was late by the cumulative transition time** — silent, track-local,
+  and invisible on any timeline without a dissolve. On a real turnover a single
+  59-frame dissolve put 651 subsequent V1 events 59 frames past Resolve's native
+  import of the same AAF (probe 566/2586/2652 vs native 507/2527/2593); the fixed
+  probe reproduces the native positions exactly. The independent cross-check: each
+  layer's walked length used to overshoot its own DECLARED length by exactly that
+  layer's transition sum (V1 +59, V6 +77, dissolve-free layers +0) — with the
+  subtraction, walked equals declared on every layer. A leading transition clamps at
+  the sequence start rather than producing a negative record position.
+
+### Added
+
+- **Sequence start timecode.** `list_sequences` and `parse_interchange` now report
+  `startTimecode`, `startFrame`, `startTimecodeFps` and `startTimecodeDrop` per AAF
+  sequence. A conform that places events without it builds at Resolve's default
+  01:00:00:00 while the AAF starts at 00:59:50:00 — every clip ten seconds out, and
+  only visible against a linked picture reference. Avid writes one timecode slot *per
+  common rate* (a real turnover carried seven — 86160@24, 89750@25, 107592@30-drop,
+  107700@30, 215400@60, all naming the same instant), so the slot matching the
+  editorial edit rate is chosen and the rate the frame number is expressed in is always
+  reported. An AAF with no timecode slot emits explicit nulls, never a guessed start.
+- **Per-clip geometry** — the Avid transform parameters behind Resolve's "Use sizing
+  information" import option. Clips wrapped in `PaintResize_v2`, `SpatialAdapter` or
+  `FlipHoriz_2` carry a `geometry` list in application order (innermost first: 84 of
+  the fixture's clips nest a SpatialAdapter inside a PaintResize, so a single field
+  would have dropped a stage). Scale is emitted as a percent — proven, not assumed,
+  because 212 of 285 resize groups sit at exactly 100 — and the source/framing
+  rectangles yield the unit-free `reformatScaleX/Y` (0.744792 on the fixture: a 2.39:1
+  source letterboxed into a 16:9 framing). Parameters whose units the fixture does
+  *not* pin down — position, crop, and the absolute rectangle unit — pass through raw
+  under Avid's own names rather than being reinterpreted into a normalized field that
+  might ship an inversion, the lesson from `SpeedRatio` being stored as the inverse of
+  play rate. Animated parameters are named in `varying` and carry no single value.
+
+### Documentation
+
+- `api_truth`: **`TimelineItem.GetSourceStartFrame` reads one frame off on some
+  items** while `GetLeftOffset` is exact on the same items — so a conform that
+  verifies placement with `GetSourceStartFrame` reports phantom off-by-one drift on
+  correctly placed clips, and would hide a real one-frame error just as easily.
+  `docs/reference/api-limitations.md` regenerated.
+- The two timeline kernels no longer describe AAF as an honest refuse; it has parsed
+  via pyaaf2 since v2.73.x.
+
+### Validation
+
+- 2391 Python unit tests, 505 Node advanced tests (40 in the AAF suite, up from 26).
+- All release static checks and drift guards green.
+- Verified offline against a real 878-event multi-layer Avid picture turnover.
+- No Resolve scripting behavior changed — `aaf_probe.py` never touches the Resolve
+  API — so no live Resolve validation was required.
+
 ## What's New in v2.75.0
 
 The offline AAF reader now recovers retime ratios instead of only flagging them.

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.75.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.76.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/docs/kernels/timeline-conform-interchange-kernel.md

@@ -101,7 +101,8 @@ files and the project DB.
   grades across a re-conform (pairs with the color kernel's `drx grade_transfer`).
 - **`offline_ref`** — offline-reference clips have **no scripting API** but live
   inside `.drp`/`.drt` as `<OfflineClip>` entries; patch them here.
-- **`editorial`** — `parse_interchange` (EDL/OTIO/XMEML; **AAF = honest refuse**),
+- **`editorial`** — `parse_interchange` (EDL/OTIO/XMEML natively; **AAF via pyaaf2**,
+  multi-layer Avid turnovers included — honest refuse only when pyaaf2 is absent),
   `turnover_changelist` (moved/retimed/replaced/new/gone with timing guards),
   `conform_manifest`, `marker_roundtrip`.
 - **`drt` / `project_db`** — timeline file authoring and DB patching.

package/docs/kernels/timeline-edit-kernel.md

@@ -186,7 +186,8 @@ The kernel above restructures a *running* timeline. The companion advanced serve
 (`davinci-resolve-advanced`, see `resolve-advanced/README.md`) authors/diffs
 timelines and reasons over editorial interchange with **no Resolve running**:
 
-- **`editorial`** — `parse_interchange` (EDL/OTIO/XMEML; **AAF = honest refuse**),
+- **`editorial`** — `parse_interchange` (EDL/OTIO/XMEML natively; **AAF via pyaaf2**,
+  multi-layer Avid turnovers included — honest refuse only when pyaaf2 is absent),
   `turnover_changelist` (moved/retimed/replaced/new/gone between two cuts, with
   timing silent-lie guards), `conform_manifest`, `marker_roundtrip`.
 - **`drt`** — `.drt` timeline file authoring + structural diff.

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 25 missing capabilities, 24 bugs / unreliable behaviors.
+**Totals:** 25 missing capabilities, 25 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -334,6 +334,14 @@ values, or automation-hostile modal prompts.
 - **Workaround / current handling:** CloseProject(current) to discard the untitled project without a prompt, then CreateProject; restore with LoadProject afterward.
 - **Tags:** project, modal, silent-failure
 
+### TimelineItem.GetSourceStartFrame
+
+- **Object:** `TimelineItem`
+- **Signature:** `() -> int`
+- **Behavior:** Reads back one frame off on some items. Measured while verifying a constructed timeline against the clipInfos it was built from: for 4/4 items GetLeftOffset returned exactly the startFrame that was sent, while GetSourceStartFrame disagreed by 1 on some of the same items. The two are supposed to describe the same edit point, so a conform that verifies placement with GetSourceStartFrame reports phantom off-by-one drift on correctly placed clips — and would hide a real one-frame error just as easily.
+- **Workaround / current handling:** Verify source-side placement with GetLeftOffset, which is exact. Treat GetSourceStartFrame as approximate, and never diff it against a sent startFrame to decide whether a clip landed right.
+- **Tags:** off-by-one, unreliable-return, timeline, conform, verify
+
 ### hasattr() / getattr() on Resolve API objects (attribute fabrication)
 
 - **Object:** `(all Resolve scripting objects)`

package/install.py

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

package/resolve-advanced/server/aaf.mjs

@@ -78,18 +78,56 @@ export function resolveAafPath(contentOrPath) {
   return path.resolve(p);
 }
 
+/**
+ * Per-sequence summary WITHOUT its events — the picker row, plus the sequence-level facts
+ * a conform needs before it places anything.
+ *
+ * `startTimecode`/`startFrame` are carried deliberately: an AAF that starts at 00:59:50:00
+ * built against Resolve's default 01:00:00:00 start puts every clip ten seconds out, and
+ * the misalignment only shows up against a linked picture reference. They are null (not
+ * absent) when the AAF has no timecode slot — an explicit "no start timecode here" rather
+ * than a guess. `startFrame` is expressed at `startTimecodeFps`.
+ */
+function sequenceSummary(s) {
+  const out = {
+    id: String(s.id),
+    name: String(s.name),
+    eventCount: Number(s.eventCount || 0),
+    startTimecode: s.startTimecode ?? null,
+    startFrame: s.startFrame ?? null,
+    startTimecodeFps: s.startTimecodeFps ?? null,
+    startTimecodeDrop: s.startTimecodeDrop ?? null,
+  };
+  if (s.unhandled && Object.keys(s.unhandled).length) out.unhandled = s.unhandled;
+  return out;
+}
+
 /**
  * Parse an AAF into a FLAT normalized-event list (mirrors parseEDL/parseOTIO/parseXMEML output),
- * concatenating every top-level sequence. Use listAafSequences() when you need per-sequence split.
+ * concatenating every top-level sequence. Use listAafSequences() when you need per-sequence split,
+ * or parseAafDocument() when you also need the sequence-level start timecode.
  * @param {string} contentOrPath absolute .aaf path
  * @returns {Promise<Array>} normalized events
  */
 export async function parseAAF(contentOrPath) {
+  return (await parseAafDocument(contentOrPath)).events;
+}
+
+/**
+ * Parse an AAF into flat events PLUS the per-sequence summaries they came from.
+ *
+ * parseAAF() flattens every sequence into one event list, which drops the sequence-level
+ * start timecode with it — so a caller that needs to know where the timeline starts had
+ * to re-run the probe. This returns both from a single probe run.
+ * @param {string} contentOrPath absolute .aaf path
+ * @returns {Promise<{events: Array, sequences: Array}>}
+ */
+export async function parseAafDocument(contentOrPath) {
   const aafPath = resolveAafPath(contentOrPath);
   const { sequences } = await runProbe(aafPath);
   const events = [];
   for (const seq of sequences || []) for (const ev of seq.events || []) events.push(ev);
-  return events;
+  return { events, sequences: (sequences || []).map(sequenceSummary) };
 }
 
 /**
@@ -101,14 +139,10 @@ export async function parseAAF(contentOrPath) {
  * 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,unhandled?:Object}>>}
+ * @returns {Promise<Array<{id:string,name:string,eventCount:number,startTimecode:?string,startFrame:?number,unhandled?:Object}>>}
  */
 export async function listAafSequences(contentOrPath) {
   const aafPath = resolveAafPath(contentOrPath);
   const { sequences } = await runProbe(aafPath);
-  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;
-  });
+  return (sequences || []).map(sequenceSummary);
 }

package/resolve-advanced/server/aaf_probe.py

@@ -11,6 +11,8 @@ trusting, so the Node server shells out to this helper, which uses the pure-Pyth
       "ok": true,
       "sequences": [
         { "id": <mob-id str>, "name": <str>, "eventCount": <int>,
+          "startTimecode": <"HH:MM:SS:FF"|null>, "startFrame": <int|null>,
+          "startTimecodeFps": <int|null>, "startTimecodeDrop": <bool|null>,
           "unhandled": { "<ComponentClass>": <int>, ... },
           "events": [ {normalized-event}, ... ] }
       ]
@@ -55,6 +57,11 @@ Segment model (Avid Media Composer picture turnovers):
   * Selector     — an enabled/disabled layer variant; the live one is `Selected`.
   * ScopeReference — "show the NestedScope layer beneath me": real record time, no
                    clip of this layer's own. Treated as a gap, like Filler.
+  * Transition   — a dissolve/wipe that OVERLAPS its neighbours. It does not occupy
+                   record time of its own; it CONSUMES it. See _walk_components.
+
+Retimes additionally carry `"effect"`/`"speedRatio"`; clips wrapped in an Avid transform
+effect carry `"geometry"` (see _geometry_fields).
 """
 
 import json
@@ -353,6 +360,148 @@ def _retime_fields(op_group):
     }
 
 
+# ── Per-clip geometry (Avid transform OperationGroups) ────────────────────────
+# The data behind Resolve's "Use sizing information" AAF import option. Census of a
+# real 878-event Avid picture turnover — the parameters that are actually present,
+# by operation:
+#
+#   PaintResize_v2 (285)  AFX_SCALE_X_U / AFX_SCALE_Y_U       percent, 100 = identity
+#                         AFX_POS_X_U / AFX_POS_Y_U           Avid position units
+#                         AFX_CROP_{LEFT,RIGHT,TOP,BOTTOM}_U  Avid crop units
+#                         AFX_FIXED_ASPECT_U                  bool (aspect locked)
+#   SpatialAdapter (90)   AFX_SPATIAL_SOURCE_{WID,HEI}_{NUM,DEN}   source rectangle
+#                         AFX_SPATIAL_FRAMING_{WID,HEI}_{NUM,DEN}  framing rectangle
+#                         AFX_SPATIAL_REFORMAT, AFX_SCALE_{X,Y}_U
+#   FlipHoriz_2 (10)      a horizontal flip; carries no geometry parameters of its own
+#
+# What the fixture PROVES, and is therefore emitted as a named field:
+#   * scale is a PERCENT — 212 of 285 PaintResize groups sit at exactly 100, i.e.
+#     identity, which pins the unit without needing a reference render.
+#   * the source and framing rectangles share ONE unit, so their RATIO is unit-free.
+#     `reformatScaleX/Y` is that ratio (a 5120/3 x 900 source into a 1200 x 900
+#     framing is the 2.39:1-into-16:9 letterbox the reference showed).
+#
+# What it does NOT prove, and is therefore passed through RAW under Avid's own
+# parameter names in `params` rather than reinterpreted into a normalized field:
+# the unit of POS_*/CROP_*, and the ABSOLUTE unit of the rectangles. This is the
+# SpeedRatio lesson applied ahead of time — that one was stored as the INVERSE of
+# play rate, and a normalized-looking field would have shipped the inversion. A
+# stored Avid number keeps its own name until its semantics are measured.
+
+_GEOMETRY_OPS = frozenset({"PaintResize_v2", "SpatialAdapter", "FlipHoriz_2"})
+
+_GEOMETRY_SCALARS = frozenset(
+    {
+        "AFX_POS_X_U",
+        "AFX_POS_Y_U",
+        "AFX_CROP_LEFT_U",
+        "AFX_CROP_RIGHT_U",
+        "AFX_CROP_TOP_U",
+        "AFX_CROP_BOTTOM_U",
+        "AFX_SPATIAL_REFORMAT",
+    }
+)
+_GEOMETRY_BOOLS = frozenset({"AFX_FIXED_ASPECT_U", "AFX_SPATIAL_LOCK_ASPECT"})
+# Rectangles arrive split across a <base>_NUM / <base>_DEN rational pair.
+_GEOMETRY_RECTS = frozenset(
+    {
+        "AFX_SPATIAL_SOURCE_WID",
+        "AFX_SPATIAL_SOURCE_HEI",
+        "AFX_SPATIAL_FRAMING_WID",
+        "AFX_SPATIAL_FRAMING_HEI",
+    }
+)
+
+
+def _param_number(param):
+    """A Parameter's ConstantValue as a float (AAFRational, int, bool all convert)."""
+    try:
+        return round(float(param.value), 6)
+    except Exception:
+        return None
+
+
+def _geometry_scalar(param):
+    """(value, is_varying) for one geometry parameter, or (None, False) if unreadable.
+
+    A VaryingValue whose control points all carry the SAME value is a constant — the
+    same rule the speed map uses. More than one distinct value is an animated
+    transform, and no single number for it would be honest.
+    """
+    if type(param).__name__ == "VaryingValue":
+        values = _pointlist_values(param)
+        if values is None:
+            return None, False
+        if len(set(values)) > 1:
+            return None, True
+        return (round(float(values[0]), 6) if values else None), False
+    return _param_number(param), False
+
+
+def _geometry_fields(op_group, op_name):
+    """Recovered geometry for one transform OperationGroup. See the census above."""
+    scale = {}
+    scalars = {}
+    bools = {}
+    rects = {}
+    varying = set()
+    for param in _op_parameters(op_group):
+        name = _param_name(param)
+        base, _, suffix = name.rpartition("_")
+        if suffix in ("NUM", "DEN") and base in _GEOMETRY_RECTS:
+            value = _param_number(param)
+            if value is not None:
+                rects.setdefault(base, {})[suffix] = value
+            continue
+        if name in ("AFX_SCALE_X_U", "AFX_SCALE_Y_U"):
+            value, is_varying = _geometry_scalar(param)
+            if is_varying:
+                varying.add(name)
+            elif value is not None:
+                scale[name] = value
+            continue
+        if name in _GEOMETRY_BOOLS:
+            value = _param_number(param)
+            if value is not None:
+                bools[name] = bool(value)
+            continue
+        if name in _GEOMETRY_SCALARS:
+            value, is_varying = _geometry_scalar(param)
+            if is_varying:
+                varying.add(name)
+            elif value is not None:
+                scalars[name] = value
+    geometry = {"effect": op_name}
+    if op_name == "FlipHoriz_2":
+        geometry["flipHorizontal"] = True
+    if "AFX_SCALE_X_U" in scale:
+        geometry["scalePercentX"] = scale["AFX_SCALE_X_U"]
+    if "AFX_SCALE_Y_U" in scale:
+        geometry["scalePercentY"] = scale["AFX_SCALE_Y_U"]
+    sizes = {}
+    for base, parts in rects.items():
+        num, den = parts.get("NUM"), parts.get("DEN")
+        if num is None or not den:
+            continue
+        sizes[base] = round(num / den, 6)
+    if sizes:
+        geometry["rect"] = dict(sorted(sizes.items()))
+        # The one unit-free quantity the rectangles yield: framing over source.
+        for axis, src, framing in (
+            ("X", "AFX_SPATIAL_SOURCE_WID", "AFX_SPATIAL_FRAMING_WID"),
+            ("Y", "AFX_SPATIAL_SOURCE_HEI", "AFX_SPATIAL_FRAMING_HEI"),
+        ):
+            if sizes.get(src) and sizes.get(framing) is not None:
+                geometry[f"reformatScale{axis}"] = round(sizes[framing] / sizes[src], 6)
+    if varying:
+        # An animated transform. Named, never reduced to one number.
+        geometry["varying"] = sorted(varying)
+    params = dict(sorted({**scalars, **bools}.items()))
+    if params:
+        geometry["params"] = params
+    return geometry
+
+
 def _walk_segment(segment, *, track, fps, rec, state, depth=0, transition=None):
     """
     Emit normalized events for ONE segment placed at record position `rec`.
@@ -417,6 +566,15 @@ def _walk_segment(segment, *, track, fps, rec, state, depth=0, transition=None):
         for inp in getattr(segment, "segments", None) or []:
             _walk_segment(inp, track=track, fps=fps, rec=rec, state=state, depth=depth + 1, transition=transition)
         op_name = _operation_name(segment)
+        if op_name in _GEOMETRY_OPS:
+            # A transform effect. Clips are commonly wrapped in MORE than one (a
+            # SpatialAdapter reformat inside a PaintResize, say), so geometry is a
+            # LIST in application order — innermost first, because this walk annotates
+            # on the way back out. Collapsing them to one field would silently drop a
+            # stage of the transform stack.
+            geometry = _geometry_fields(segment, op_name)
+            for ev in state["events"][before:]:
+                ev.setdefault("geometry", []).append(geometry)
         if op_name and ("speed" in op_name.lower() or "motion" in op_name.lower()):
             # A retime. Its ratio is recoverable from the group's PARAMETERS (see
             # _retime_fields): a constant ratio updates speed/speedRatio so
@@ -445,7 +603,25 @@ def _walk_segment(segment, *, track, fps, rec, state, depth=0, transition=None):
 
 
 def _walk_components(sequence, *, track, fps, rec, state, depth, transition=None):
-    """Lay a Sequence's components end to end. Returns the record length consumed."""
+    """Lay a Sequence's components end to end. Returns the record length consumed.
+
+    Transitions SUBTRACT. This is the dual of the declared-length rule above, and it
+    is the AAF Edit Protocol's definition rather than a heuristic: a Transition is not
+    a component that occupies record time, it is an OVERLAP of the two components
+    around it, so
+
+        sequence length == sum(component lengths) - sum(transition lengths)
+
+    and the component after a transition starts `duration` frames EARLIER than the
+    previous one ended. Annotating the following clip (which this walker already did)
+    without rewinding `rec` left every later event on that track late by the CUMULATIVE
+    transition time — silent, track-local, and invisible on any timeline without a
+    dissolve. Measured on a real Avid turnover: V1's single 59-frame dissolve put every
+    subsequent V1 cut 59 frames past Resolve's own native import of the same file, and
+    each layer's walked length overshot its DECLARED length by exactly the sum of that
+    layer's transitions (V1 +59, V6 +77, every dissolve-free layer +0). The declared
+    length is the cross-check — with the subtraction, walked == declared on every layer.
+    """
     start = rec
     pending_transition = transition
     components = getattr(sequence, "components", None)
@@ -455,8 +631,13 @@ def _walk_components(sequence, *, track, fps, rec, state, depth, transition=None
         cls = type(comp).__name__
         try:
             if cls == "Transition":
-                # A transition overlaps its neighbours; it does not advance rec itself.
-                pending_transition = {"type": "dissolve", "duration": _length(comp)}
+                duration = _length(comp)
+                pending_transition = {"type": "dissolve", "duration": duration}
+                # Rewind: the next component overlaps the previous one by `duration`.
+                # Clamped at this sequence's own start — a leading transition has no
+                # preceding material to overlap, and a negative record position would
+                # be a worse lie than the malformed AAF that produced it.
+                rec = max(start, rec - duration)
                 continue
             rec += _walk_segment(
                 comp, track=track, fps=fps, rec=rec, state=state, depth=depth, transition=pending_transition
@@ -518,6 +699,147 @@ def _media_kind_to_track(slot):
     return "A" if _slot_media_kind(slot).startswith("sound") else "V"
 
 
+# ── Sequence start timecode ───────────────────────────────────────────────────
+# A composition does NOT have one timecode slot. Avid writes several — one per common
+# timecode rate — all naming the same wall-clock start. A real turnover carried seven:
+#
+#     start 86160 @24     start 89750 @25     start 107592 @30 drop
+#     start 107700 @30    start 215400 @60    (and duplicates)
+#
+# Every one of those is 00:59:50:00. They agree on the STRING and disagree on the
+# FRAME NUMBER, so "read the first timecode slot" hands back a frame count in a rate
+# the rest of the parse never uses — a 10%-off offset that looks plausible. Pick the
+# slot whose rate matches the EDITORIAL edit rate, and always report the rate the
+# frame number is expressed in so a mismatch can't hide.
+#
+# This mattered: a consumer built its conform timeline at Resolve's default
+# 01:00:00:00 while the AAF started at 00:59:50:00, mis-aligning the linked picture
+# reference by ten seconds until it was hand-fixed.
+
+_TIMECODE_KIND = "timecode"
+
+
+def _timecode_component(segment, depth=0):
+    """The Timecode component inside a timecode slot's segment, or None.
+
+    Avid wraps it in a Pulldown (the rate conversion that makes a 30-drop view of a
+    23.976 sequence), sometimes inside a Sequence, so the slot segment's own class
+    name is not enough to find it.
+    """
+    if segment is None or depth > 8:
+        return None
+    cls = type(segment).__name__
+    if cls == "Timecode":
+        return segment
+    children = []
+    if cls == "Sequence":
+        children = list(getattr(segment, "components", None) or [])
+    elif cls == "Pulldown":
+        # pyaaf2 exposes the wrapped segment as the InputSegment PROPERTY, not an
+        # attribute — same access pattern as Selector's `Selected`.
+        for getter in (
+            lambda s: s["InputSegment"].value,
+            lambda s: s.getvalue("InputSegment"),
+            lambda s: getattr(s, "input_segment", None),
+        ):
+            try:
+                inner = getter(segment)
+            except Exception:
+                inner = None
+            if inner is not None:
+                children = [inner]
+                break
+    for child in children:
+        found = _timecode_component(child, depth + 1)
+        if found is not None:
+            return found
+    return None
+
+
+def _frames_to_timecode(frames, rate, drop):
+    """SMPTE timecode string for a frame count at an INTEGER timecode rate.
+
+    Drop-frame (`;` separator) skips two frame NUMBERS — four at the 60-family rate —
+    at the top of every minute except every tenth. It renumbers; it never drops a
+    picture frame, which is why the conversion is a renumbering pass and not a
+    rescaling of `frames`.
+    """
+    try:
+        frames = int(frames)
+        rate = int(round(float(rate)))
+    except Exception:
+        return None
+    if rate <= 0 or frames < 0:
+        return None
+    sep = ":"
+    if drop and rate % 30 == 0:
+        dropped = 2 * (rate // 30)
+        per_10min = rate * 600 - dropped * 9
+        per_min = rate * 60 - dropped
+        tens, rem = divmod(frames, per_10min)
+        frames += dropped * 9 * tens
+        if rem > dropped:
+            frames += dropped * ((rem - dropped) // per_min)
+        sep = ";"
+    total_seconds, ff = divmod(frames, rate)
+    hh, rem_seconds = divmod(total_seconds, 3600)
+    mm, ss = divmod(rem_seconds, 60)
+    return f"{hh % 24:02d}:{mm:02d}:{ss:02d}{sep}{ff:02d}"
+
+
+# Absent-timecode sequences report these as null rather than omitting them: an explicit
+# null is a readable "this AAF carries no start timecode", where a missing key is
+# indistinguishable from an older probe that never emitted one.
+_NO_START_TIMECODE = {
+    "startTimecode": None,
+    "startFrame": None,
+    "startTimecodeFps": None,
+    "startTimecodeDrop": None,
+}
+
+
+def _sequence_start_timecode(mob, edit_fps):
+    """Start-timecode fields for a composition mob. Never guesses — see _NO_START_TIMECODE.
+
+    `startFrame` is expressed at `startTimecodeFps`, which is the rate of the slot we
+    picked; it equals the editorial edit rate whenever a matching slot exists.
+    """
+    candidates = []
+    for slot in getattr(mob, "slots", []) or []:
+        if _slot_media_kind(slot) != _TIMECODE_KIND:
+            continue
+        tc = _timecode_component(getattr(slot, "segment", None))
+        if tc is None:
+            continue
+        try:
+            start = int(getattr(tc, "start", None))
+            rate = int(round(float(getattr(tc, "fps", 0) or 0)))
+        except Exception:
+            continue
+        if rate <= 0 or start < 0:
+            continue
+        try:
+            drop = bool(getattr(tc, "drop", False))
+        except Exception:
+            drop = False
+        candidates.append((start, rate, drop))
+    if not candidates:
+        return dict(_NO_START_TIMECODE)
+    wanted = int(round(edit_fps)) if edit_fps else None
+    chosen = None
+    if wanted:
+        chosen = next((c for c in candidates if c[1] == wanted), None)
+    if chosen is None:
+        chosen = candidates[0]
+    start, rate, drop = chosen
+    return {
+        "startTimecode": _frames_to_timecode(start, rate, drop),
+        "startFrame": start,
+        "startTimecodeFps": rate,
+        "startTimecodeDrop": drop,
+    }
+
+
 def probe(path):
     import aaf2
 
@@ -542,6 +864,7 @@ def probe(path):
                 name = None
             # `idx` is monotonic across the WHOLE mob, every slot and every nested layer.
             state = {"idx": 1, "events": [], "unhandled": {}}
+            edit_fps = None
             for slot in getattr(mob, "slots", []) or []:
                 seg = getattr(slot, "segment", None)
                 if seg is None:
@@ -550,18 +873,17 @@ def probe(path):
                 # metadata/sound master) — see _NON_EDITORIAL_KINDS.
                 if not _is_editorial_slot(slot):
                     continue
-                _walk_slot(
-                    seg,
-                    prefix=_media_kind_to_track(slot),
-                    fps=_fps_from_edit_rate(getattr(slot, "edit_rate", None)),
-                    state=state,
-                )
+                fps = _fps_from_edit_rate(getattr(slot, "edit_rate", None))
+                if edit_fps is None:
+                    edit_fps = fps  # picks the timecode slot to trust — see above
+                _walk_slot(seg, prefix=_media_kind_to_track(slot), fps=fps, state=state)
             events = state["events"]
             sequences.append(
                 {
                     "id": mob_id or (str(name) if name else f"seq{len(sequences) + 1}"),
                     "name": str(name) if name else f"Sequence {len(sequences) + 1}",
                     "eventCount": len(events),
+                    **_sequence_start_timecode(mob, edit_fps),
                     # Component classes we could not model, by name+count. Empty {} means
                     # a structurally complete read; non-empty means events are INCOMPLETE.
                     "unhandled": dict(sorted(state["unhandled"].items())),

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

@@ -5,6 +5,7 @@
  * Actions:
  *   parse_interchange     — EDL / OTIO / XMEML / AAF (pyaaf2) / PRPROJ (gunzip+XML) → normalized events
  *   list_sequences        — ONE picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}]
+ *                           (AAF rows also carry startTimecode/startFrame — see aaf.mjs sequenceSummary)
  *   convert_to_interchange— events (or a parsed source) → OTIO/EDL/DRT Resolve CAN import (the .prproj bridge)
  *   turnover_changelist   — diff old vs new events → moved/retimed/replaced/new/gone (+timing flags)
  *   conform_manifest      — per-event assert: source resolved, handles, retime, reverse, TC-base
@@ -13,7 +14,7 @@
 import fs from 'node:fs/promises';
 import { z } from 'zod';
 import { parseInterchange, diffChangelist, timingGuards, conformManifest, markerRoundtrip } from '../editorial.mjs';
-import { parseAAF } from '../aaf.mjs';
+import { parseAAF, parseAafDocument } from '../aaf.mjs';
 import { parsePrproj, parsePrprojDoc } from '../prproj.mjs';
 import { listSequences, detectFormat } from '../sequences.mjs';
 import { authorInterchange } from '../author-interchange.mjs';
@@ -81,14 +82,17 @@ 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 + AAF via pyaaf2 + PRPROJ via gunzip+XML → normalized events; for AAF/PRPROJ pass the file PATH as content), list_sequences (ONE offline picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}]), convert_to_interchange (author OTIO/EDL/DRT Resolve CAN import from events or a parsed source — the .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions/speed survive, per-clip effects/color do not), turnover_changelist (diff old vs new → moved/retimed/replaced/new/gone + timing flags), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base), marker_roundtrip (markers with provenance tags). 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 + AAF via pyaaf2 + PRPROJ via gunzip+XML → normalized events; 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 .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions/speed survive, per-clip effects/color do not), turnover_changelist (diff old vs new → moved/retimed/replaced/new/gone + timing flags), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base), marker_roundtrip (markers with provenance tags). 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);
       // Binary formats parse out-of-band from a PATH: AAF via pyaaf2, .prproj via gunzip+XML.
       if (p.format === 'aaf') {
-        const events = await parseAAF(p.content);
-        return { format: 'aaf', count: events.length, events };
+        // `sequences` carries the per-sequence start timecode, which the flattened event
+        // list cannot express — a conform that places events without it lands the whole
+        // timeline at the wrong start.
+        const { events, sequences } = await parseAafDocument(p.content);
+        return { format: 'aaf', count: events.length, events, sequences };
       }
       if (p.format === 'prproj') {
         const doc = parsePrprojDoc(p.content);

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.75.0"
+VERSION = "2.76.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.75.0"
+VERSION = "2.76.0"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -516,6 +516,24 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["missing-method", "timeline", "edit", "trim"],
         "submit": "missing",
     },
+    {
+        "symbol": "TimelineItem.GetSourceStartFrame",
+        "object": "TimelineItem",
+        "signature": "() -> int",
+        "reality": "Reads back one frame off on some items. Measured while verifying a "
+                   "constructed timeline against the clipInfos it was built from: for "
+                   "4/4 items GetLeftOffset returned exactly the startFrame that was "
+                   "sent, while GetSourceStartFrame disagreed by 1 on some of the same "
+                   "items. The two are supposed to describe the same edit point, so a "
+                   "conform that verifies placement with GetSourceStartFrame reports "
+                   "phantom off-by-one drift on correctly placed clips — and would hide "
+                   "a real one-frame error just as easily.",
+        "recommended": "Verify source-side placement with GetLeftOffset, which is exact. "
+                       "Treat GetSourceStartFrame as approximate, and never diff it "
+                       "against a sent startFrame to decide whether a clip landed right.",
+        "tags": ["off-by-one", "unreliable-return", "timeline", "conform", "verify"],
+        "submit": "bug",
+    },
     {
         "symbol": "Razor / blade / split a timeline item",
         "object": "Timeline / TimelineItem",