davinci-resolve-mcp 2.194.0 → 2.196.0

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 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.196.0 — E144: Resolve's own retimes decode; a flat map is a freeze
+
+### Fixed
+
+- **Resolve's own retimes decode.** Every retime Resolve 19.1.3.7 makes
+  itself — an XMEML import, a UI speed change, an EDL `M2` freeze, a speed
+  ramp — writes `KeyframesBA` in the keyed-dict form (keyframes
+  `{interp,YOut,YIn,Y,XOut,XIn,X}` under keys `0`, `1`, …), which the DRP
+  time-map reader rejected ("unsupported wire type 7"), so E140 called them
+  unknown. The reader now decodes both forms; keyframe 0 at X=0 is the
+  origin and its Y the source second the map starts on (4.0 s on a real ramp
+  harvest). Verbatim harvest blobs: a 50% constant reads 50, a ramp reads
+  its two segments (0.5 then 2.0) with the right source window, both freezes
+  read the second they hold.
+- **A source window is the map, evaluated.** A DRT event's `srcIn`/`srcOut`
+  now come from evaluating the piecewise-linear map at `In` and `In +
+  duration` (origin included), which makes ramps, reverses and rebased maps
+  come out right without special cases.
+- **A flat map over the 60000 sentinel is a freeze even with a source-in.**
+  The E66 harvest (an XMEML import of a plain 100% clip) came back with a
+  flat map at Y=0 and `In` 24, and its render is static at the source's frame
+  0: inter-frame change 0.02 against 0.42 in the source. Resolve's XMEML
+  importer froze the clip silently; the event now says frozen at frame 0 and
+  keeps the ignored `In` as `recordDomainIn`. (The first draft of this fix
+  called that map a harmless identity because it fit the prose; the render
+  said otherwise.)
+
+### Measured (filed in api-limitations)
+
+- The keyed-dict keyframe form on Resolve-made retimes, and the freeze
+  law with a present `<In>`.
+
+## What's New in v2.195.0 — E143: a retimed DRT clip's source-in is record-domain
+
+### Fixed
+
+- **A retimed DRT clip's source-in is record-domain.** On a keyed
+  `Sm2TimeMap` Resolve's `<In>` indexes the source stretched by 1/speed (the
+  DRP library measured this live and writes `In = srcIn / speed` for exactly
+  that reason), so the first source frame a retimed clip shows is `In × speed`,
+  not `In`. E140 read `In` as a source frame, wrong by `(1/speed − 1) × In`:
+  10,537 frames on a real 80% clip. The DRT event now carries `srcIn = In ×
+  speed` (reverse: measured from the source tail), `srcOut` following at that
+  speed, and the raw value as `recordDomainIn`.
+- **Which meant a wrong "match".** Against the Premiere pix-lock, the hand
+  conform's four 80% layers had read as unchanged because its `In` values
+  equalled Premiere's source frames numerically — the very mistake: typing a
+  source frame straight into `In` of an 80% clip shows a frame 20% of `In`
+  earlier. Read correctly: the bridge-authored timeline (`In` 52682) matches
+  Premiere frame for frame on all four layers, and the hand conform (`In`
+  42145) shows source 33715 — 8,430 frames early — which the changelist now
+  reports as four trims. The media volume was offline in this session, so the
+  render witness for those four layers is owed; the law itself stands on the
+  DRP library's live measurement.
+
+### Measured (filed in api-limitations)
+
+- The record-domain `<In>` law on retimed clips, with both real timelines as
+  witnesses.
+
 ## What's New in v2.194.0 — E142: a cut re-aligned inside a dissolve is the same picture
 
 ### Added

package/README.md

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

package/docs/reference/api-limitations.md

@@ -305,7 +305,7 @@ equivalent, blocking full automation.
 
 - **Object:** `Timeline`
 - **Signature:** `(filePath, EXPORT_DRT) -> bool`
-- **Behavior:** Measured on a Studio 19.1.3.7 export of a 229-clip reel (E139). A SeqContainer clip (Sm2TiVideoClip / Sm2TiAudioClip) carries its record window as <Start> and <Duration> (frames, absolute), its SOURCE in-point as <In> (frames) — written EMPTY (<In/>) on every audio clip and on generator tails — <MediaFilePath>, <MediaStartTime> (seconds), <MediaFrameRate> as a 16-hex blob = one little-endian IEEE double + 8 pad bytes (24.0 = 0000000000003840…), and <MediaTimemapBA>: tag byte 0x02 + one double (the media length in seconds) on a 100% clip, a keyed Sm2TimeMap opening 00000001… on a retimed clip and on generators — its KeyframesBA is the protobuf point form (NOT the keyed-dict form a 19.1.3.7 XMEML retime import writes) and decodes with the DRP library's decodeTimemap: the keyframe slope is the speed (0.79999 on all four retimed clips of a real reel = Premiere's 80 for the same cuts, srcOut = In + round(Duration × 0.8) matching Premiere's frame for frame), XMax 60000 with a zero slope is the freeze sentinel (a Black Video generator), a negative slope is a reverse (a reversed tail leader). An Sm2TiTransition sits in the same <Items> list as the clips with <Start>/<Duration> (its span), <PrettyType> (Cross Dissolve), <AlignmentType> and <Position>: type 2 centres the span on the cut, type 3 ends it at the cut (11/11 witnessed against the clip edges; the one-sided 8-frame fade-in is type 3 / Position 1). The container carries NO frame rate, start or resolution — they live in the pool folder's embedded Sm2Sequence: <FrameRate> (LE double blob), <MediaExtents> = two LE doubles, record start SECONDS then duration SECONDS (7192.0 → frame 172608 = 01:59:52:00 at 24), <Resolution> = two big-endian uint64, width then height.
+- **Behavior:** Measured on a Studio 19.1.3.7 export of a 229-clip reel (E139). A SeqContainer clip (Sm2TiVideoClip / Sm2TiAudioClip) carries its record window as <Start> and <Duration> (frames, absolute), its SOURCE in-point as <In> (frames) — written EMPTY (<In/>) on every audio clip and on generator tails — <MediaFilePath>, <MediaStartTime> (seconds), <MediaFrameRate> as a 16-hex blob = one little-endian IEEE double + 8 pad bytes (24.0 = 0000000000003840…), and <MediaTimemapBA>: tag byte 0x02 + one double (the media length in seconds) on a 100% clip, a keyed Sm2TimeMap opening 00000001… on a retimed clip and on generators — its KeyframesBA is the protobuf point form on that hand-conformed export, while every retime Resolve 19.1.3.7 MAKES itself (XMEML import, UI speed change, EDL M2 freeze, speed ramp) writes the KEYED-DICT form (E144: keyframes {interp,YOut,YIn,Y,XOut,XIn,X} under keys '0','1',…; keyframe 0 at X=0 is the origin and its Y the source second the map starts on — 4.0 on a real ramp); both decode with the DRP library's decodeTimemap: the keyframe slope is the speed (0.79999 on all four retimed clips of a real reel = Premiere's 80 for the same cuts, srcOut = In + round(Duration × 0.8) matching Premiere's frame for frame), XMax 60000 with a zero slope is the freeze sentinel — a FREEZE at the source second the flat map holds, even when <In> is present: an XMEML import of a 100% clip came back with that flat map at Y=0 and In 24, and its render is static at the source's frame 0 (E144, inter-frame change 0.02 vs 0.42 in the source) — Resolve's XMEML importer froze the clip silently; a negative slope is a reverse (a reversed tail leader). On a retimed clip <In> is RECORD-domain (E143): the map spans the whole source stretched by 1/speed and the clip windows into that, so the first source frame shown is In × speed — two timelines of the same reel carried the same 80% map with In 52682 (bridge-authored: source 42145, Premiere's frame) and In 42145 (hand conform: source 33716, 8,429 frames early). An Sm2TiTransition sits in the same <Items> list as the clips with <Start>/<Duration> (its span), <PrettyType> (Cross Dissolve), <AlignmentType> and <Position>: type 2 centres the span on the cut, type 3 ends it at the cut (11/11 witnessed against the clip edges; the one-sided 8-frame fade-in is type 3 / Position 1). The container carries NO frame rate, start or resolution — they live in the pool folder's embedded Sm2Sequence: <FrameRate> (LE double blob), <MediaExtents> = two LE doubles, record start SECONDS then duration SECONDS (7192.0 → frame 172608 = 01:59:52:00 at 24), <Resolution> = two big-endian uint64, width then height.
 - **Workaround / current handling:** Read record timing from Start/Duration, source in from In (null when empty — do not fake 0 silently), fps and start from the pool sequence (frames = round(seconds × fps)); decode a keyed timemap to its speed (E140) and report a map the decoder cannot read as speed null rather than 100%. The parser exposes these and editorial.parse_interchange {format:'drt', content: PATH} walks one timeline into normalized events so two timeline versions diff through turnover_changelist (v19 vs v20 of a real reel: identical, 229 of 229 retained).
 - **Tags:** timeline, export, drt, interchange
 

package/install.py

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

package/resolve-advanced/server/editorial.mjs

@@ -624,7 +624,9 @@ export function parseInterchange(format, content, opts = {}) {
  * media <MediaFilePath>; <MediaTimemapBA> tag 0x02 = linear 100%, a keyed
  * Sm2TimeMap decodes to the speed (E140: constant 80% on a real reel's four
  * retimes = Premiere's 80; XMax 60000 + zero slope = freeze; negative = reverse;
- * an unreadable map stays speed null + retimeUnknown);
+ * an unreadable map stays speed null + retimeUnknown) and, on a retime, <In> is
+ * RECORD-domain — the event's srcIn is In × speed (E143), with the raw value
+ * kept as recordDomainIn;
  * Sm2TiTransition alignment 2 centres on the cut, 3 ends at it. Record
  * positions are sequence-relative (start frame subtracted), like every other
  * parser here; `startFrame` is returned beside the events.
@@ -661,16 +663,47 @@ export function drtEventsFromParsed(parsed, opts = {}) {
         // decoder could not read stays speed/srcOut null + retimeUnknown.
         const tm = c.timemap && typeof c.timemap === 'object' ? c.timemap : null;
         const kind = tm ? tm.kind : (c.timemap === 'curve' ? 'unknown' : 'linear');
-        let speed = 100, srcOut = srcIn + c.duration, unknown = false;
-        if (kind === 'freeze') { speed = 0; srcOut = srcIn; }
-        else if (kind === 'constant' || kind === 'variable') { speed = Math.round(tm.speed * 10000) / 100; srcOut = srcIn + Math.round(c.duration * tm.speed); }
+        // E143: on a keyed retime Resolve's <In> is RECORD-domain — the map
+        // spans the whole source stretched by 1/speed and the clip windows
+        // into that (measured live on 19.1.3.7; the bridge writes In =
+        // srcIn/speed for exactly this reason). The source frame the clip
+        // starts on is In × speed. Reading In as a source frame was wrong by
+        // (1/speed − 1) × In: 10,537 frames on a real 80% clip at In 52682.
+        // Reverse: the map descends from the source tail, In measures from
+        // the END — source start = sourceFrames − In×speed − duration×speed.
+        let speed = 100, srcOut = srcIn + c.duration, unknown = false, srcStart = srcIn;
+        if (kind === 'freeze') {
+          // A real freeze holds the source second in its flat map (E144); the
+          // clip's <In> is empty. Zero-speed in==out event on that frame.
+          speed = 0; srcStart = tm && tm.freezeSec != null ? Math.round(tm.freezeSec * fps) : srcIn; srcOut = srcStart;
+
+        }
+        else if (kind === 'constant' || kind === 'variable') {
+          // E143/E144: <In> is RECORD-domain — evaluate the map (piecewise
+          // linear in seconds, origin included) at In and In + duration; the
+          // source window is the min/max of the two, which also makes a
+          // reversed map (descending line) come out the right way round.
+          speed = Math.round(tm.speed * 10000) / 100;
+          const pts = tm.points && tm.points.length >= 2 ? tm.points : null;
+          const mapAt = (recFrames) => {
+            const x = recFrames / fps;
+            if (!pts) return x * tm.speed * (tm.reverse ? -1 : 1);
+            let i = 1; while (i < pts.length - 1 && x > pts[i].recordSec) i++;
+            const a = pts[i - 1], b = pts[i];
+            const slope = b.recordSec === a.recordSec ? 0 : (b.sourceSec - a.sourceSec) / (b.recordSec - a.recordSec);
+            return a.sourceSec + (x - a.recordSec) * slope;
+          };
+          const s0 = Math.round(mapAt(srcIn) * fps), s1 = Math.round(mapAt(srcIn + c.duration) * fps);
+          srcStart = Math.max(0, Math.min(s0, s1)); srcOut = Math.max(s0, s1);
+        }
         else if (kind === 'unknown') { speed = null; srcOut = null; unknown = true; }
         const ev = {
           index: index++, track: label, source: media ? base(media, c.name) : (c.name || 'BL'),
-          srcIn, srcOut, recIn: c.start - startFrame, recOut: c.start - startFrame + c.duration,
+          srcIn: srcStart, srcOut, recIn: c.start - startFrame, recOut: c.start - startFrame + c.duration,
           speed, reverse: Boolean(tm && tm.reverse), transition: null, fps,
         };
         if (media) ev.sourcePath = media;
+        if (srcStart !== srcIn && c.in != null) ev.recordDomainIn = srcIn;
         if (c.in == null) ev.srcInAbsent = true;
         if (unknown) ev.retimeUnknown = true;
         if (kind === 'variable') { ev.variableSpeed = true; ev.retimeSegments = tm.segments; }

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

@@ -90,7 +90,7 @@ const markerSchema = z.object({
 export const editorialTool = {
   name: 'editorial',
   description:
-    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively — incl. Resolve-written OTIO generator clips (a Solid Color is a Clip with a NULL media_reference; it walks as a BL leg with generatorName, and an OTIO GeneratorReference carries its colour) and nested OTIO Stacks (compound clips — Resolve\'s writer nests them with a trim window) FLATTEN into record time with fromCompound on each cut, so Resolve\'s own OTIO exports re-conform (its FCP7 XML writer flattens a compound to ONE media-less clipitem instead — tagged `compound`, which the bridge drops with a reason in unresolvedCompounds unless the sourceMap maps the compound name to a flattened media file), Resolve-written FCP7 -1 junction edges (paired in record order) + Solid Color / Color Matte generators carrying their `fillcolor` (BL legs with `color` → fade-to-white and colour mattes author, E110), XMEML audio-track transitionitems as audio cross-fades on numbered lanes A/A2/…, and CMX FROM/TO CLIP NAME comments over the generic AX reel — + AAF via pyaaf2 (flat sound/picture slots number A/A2/… and V/V2/… in slot order so separate beds keep their lanes; NestedScope layers keep layer numbering; a NESTED SEQUENCE used as a clip — a SourceClip referencing a named CompositionMob — flattens through its reference window with fromCompound, like OTIO Stacks) + PRPROJ via gunzip+XML (real Premiere 2025 files — uuid ObjectUID/ObjectURef graph, TrackGroups, ClipTrackItem→SubClip→VideoClip→MediaSource→Media chain, zeros written as absence — and the legacy ObjectID/VideoTracks shape both walk; measured on a 739-sequence turnover that used to list ZERO; a NESTED SEQUENCE used as a clip — Source = Video/AudioSequenceSource → Sequence — flattens through its in-point window with fromCompound, like OTIO Stacks and AAF nested compositions; 13,711 such events on one real reels project; real transitions live in the track\'s TransitionItems list — read alongside ClipItems, attached with their DisplayName as type, HasOutgoingClip/HasIncomingClip false = fade from/to black or silence; tracks number as lanes V/V2…/A/A2… and a flattened nested sequence\'s inner lanes first-fit above what the parent already stacks — laneShift records the shift; markers are the sequence\'s OWN, read from Premiere\'s DVAMarker JSON) → 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/DRT/DRP pass the file PATH as content; DRT/DRP walk ONE timeline (`timeline` = pool name or index; default the first timeline-kind container) into events with sequence-relative record positions + the returned startFrame/startTimecode/fps read from the pool sequence — <In> is the source in-point (EMPTY on real audio clips → srcInAbsent), a keyed MediaTimemapBA Sm2TimeMap decodes to the speed (E140: the four retimed clips of a real reel read 80 — Premiere\'s 80 for the same cuts — with srcOut following the record window at that speed; XMax 60000 + zero slope = a freeze → the zero-speed in==out event; a negative slope = reverse; a map the decoder cannot read stays speed null + retimeUnknown, never faked to 100%), Sm2TiTransition alignment 2 centres on the cut and 3 ends at it — so two Resolve timeline VERSIONS diff through turnover_changelist (E139); 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 and nestedIn — an AAF composition another composition uses as a clip is NESTED in it; offer the parent, its cuts arrive flattened), 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 → a SHAPE verdict first — identical | subset (new keeps some of old\'s cuts unchanged in place and nothing else: a patch/selects reel of the same cut, NOT N deletions; a real Premiere auto-save kept 3 of 335) | superset (the reverse) | edit — with retained/oldCuts/newCuts, `sparse` and the retainedWindows for subset/superset, a transition that vanished or appeared with the cuts it joins counting as a consequence not an edit; RELINK-AWARE (E141): sourceAliases ({from,to} | {pattern,replace}) rename old sources before pairing, a systematic rename is INFERRED from unpaired cuts sharing a record window (one-to-one, recurring or clearly the same name) and reported in sourceAliases — a real offline→online turnover paired 15 of 228 cuts until the "4K-2K" proxies aliased to the "4K" masters, then 186 — and a constant per-source source-window shift witnessed on ≥2 cuts is a TC REBASE (sourceTcOffsets), not trims; a cut moved INSIDE an unchanged dissolve span with the incoming\'s source-in and the outgoing\'s source-out sliding by the same delta is ONE junction_realigned (E142: Premiere keeps a fractional alignment, Resolve\'s conform re-centres it — 9 of 10 residual moves on a real reel were this; same picture, a consequence not an edit) and two labels of one transition family ("Cross Dissolve (Legacy)" vs "Cross Dissolve") are a relabel in transitionRelabels, so a picture-identical conform reads shape `equivalent`; then 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; a compound seen collapsed in one cut and flattened in the other reports compound_collapsed/compound_expanded once, never replaced+gone), 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; a compound clipitem fails source_resolved by NAME with the remedy — map it to a flattened file or turn over as OTIO), 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; COMPOUND-AWARE: an XML re-export that collapsed a compound to one clipitem over cuts the input flattened from that compound reports compoundsCollapsedInExport instead of count/source drift; the conform QC loop-closer). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
+    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively — incl. Resolve-written OTIO generator clips (a Solid Color is a Clip with a NULL media_reference; it walks as a BL leg with generatorName, and an OTIO GeneratorReference carries its colour) and nested OTIO Stacks (compound clips — Resolve\'s writer nests them with a trim window) FLATTEN into record time with fromCompound on each cut, so Resolve\'s own OTIO exports re-conform (its FCP7 XML writer flattens a compound to ONE media-less clipitem instead — tagged `compound`, which the bridge drops with a reason in unresolvedCompounds unless the sourceMap maps the compound name to a flattened media file), Resolve-written FCP7 -1 junction edges (paired in record order) + Solid Color / Color Matte generators carrying their `fillcolor` (BL legs with `color` → fade-to-white and colour mattes author, E110), XMEML audio-track transitionitems as audio cross-fades on numbered lanes A/A2/…, and CMX FROM/TO CLIP NAME comments over the generic AX reel — + AAF via pyaaf2 (flat sound/picture slots number A/A2/… and V/V2/… in slot order so separate beds keep their lanes; NestedScope layers keep layer numbering; a NESTED SEQUENCE used as a clip — a SourceClip referencing a named CompositionMob — flattens through its reference window with fromCompound, like OTIO Stacks) + PRPROJ via gunzip+XML (real Premiere 2025 files — uuid ObjectUID/ObjectURef graph, TrackGroups, ClipTrackItem→SubClip→VideoClip→MediaSource→Media chain, zeros written as absence — and the legacy ObjectID/VideoTracks shape both walk; measured on a 739-sequence turnover that used to list ZERO; a NESTED SEQUENCE used as a clip — Source = Video/AudioSequenceSource → Sequence — flattens through its in-point window with fromCompound, like OTIO Stacks and AAF nested compositions; 13,711 such events on one real reels project; real transitions live in the track\'s TransitionItems list — read alongside ClipItems, attached with their DisplayName as type, HasOutgoingClip/HasIncomingClip false = fade from/to black or silence; tracks number as lanes V/V2…/A/A2… and a flattened nested sequence\'s inner lanes first-fit above what the parent already stacks — laneShift records the shift; markers are the sequence\'s OWN, read from Premiere\'s DVAMarker JSON) → 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/DRT/DRP pass the file PATH as content; DRT/DRP walk ONE timeline (`timeline` = pool name or index; default the first timeline-kind container) into events with sequence-relative record positions + the returned startFrame/startTimecode/fps read from the pool sequence — <In> is the source in-point (EMPTY on real audio clips → srcInAbsent), a keyed MediaTimemapBA Sm2TimeMap decodes to the speed (E140: the four retimed clips of a real reel read 80 — Premiere\'s 80 for the same cuts — with srcOut following the record window at that speed — and on a retime <In> is RECORD-domain (E143, measured live: the map spans the whole source stretched by 1/speed and the clip windows into that), so the event\'s srcIn is In × speed with the raw value kept as recordDomainIn; a hand conform that typed the source frame straight into In of an 80% clip shows a frame 20% of In earlier than intended, and this reader now says so; XMax 60000 + zero slope = a freeze → the zero-speed in==out event; a negative slope = reverse; a map the decoder cannot read stays speed null + retimeUnknown, never faked to 100%), Sm2TiTransition alignment 2 centres on the cut and 3 ends at it — so two Resolve timeline VERSIONS diff through turnover_changelist (E139); 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 and nestedIn — an AAF composition another composition uses as a clip is NESTED in it; offer the parent, its cuts arrive flattened), 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 → a SHAPE verdict first — identical | subset (new keeps some of old\'s cuts unchanged in place and nothing else: a patch/selects reel of the same cut, NOT N deletions; a real Premiere auto-save kept 3 of 335) | superset (the reverse) | edit — with retained/oldCuts/newCuts, `sparse` and the retainedWindows for subset/superset, a transition that vanished or appeared with the cuts it joins counting as a consequence not an edit; RELINK-AWARE (E141): sourceAliases ({from,to} | {pattern,replace}) rename old sources before pairing, a systematic rename is INFERRED from unpaired cuts sharing a record window (one-to-one, recurring or clearly the same name) and reported in sourceAliases — a real offline→online turnover paired 15 of 228 cuts until the "4K-2K" proxies aliased to the "4K" masters, then 186 — and a constant per-source source-window shift witnessed on ≥2 cuts is a TC REBASE (sourceTcOffsets), not trims; a cut moved INSIDE an unchanged dissolve span with the incoming\'s source-in and the outgoing\'s source-out sliding by the same delta is ONE junction_realigned (E142: Premiere keeps a fractional alignment, Resolve\'s conform re-centres it — 9 of 10 residual moves on a real reel were this; same picture, a consequence not an edit) and two labels of one transition family ("Cross Dissolve (Legacy)" vs "Cross Dissolve") are a relabel in transitionRelabels, so a picture-identical conform reads shape `equivalent`; then 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; a compound seen collapsed in one cut and flattened in the other reports compound_collapsed/compound_expanded once, never replaced+gone), 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; a compound clipitem fails source_resolved by NAME with the remedy — map it to a flattened file or turn over as OTIO), 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; COMPOUND-AWARE: an XML re-export that collapsed a compound to one clipitem over cuts the input flattened from that compound reports compoundsCollapsedInExport instead of count/source drift; the conform QC loop-closer). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
   async handler({ action, args }) {
     if (action === 'parse_interchange') {
       const p = parseSchema.parse(args);

package/resolve-advanced/vendor/drp-format/media-timemap.js

@@ -86,6 +86,27 @@ function _decodeKeyframePoint(buf) {
  */
 function _decodeKeyframes(hex) {
   if (hex == null) return { origin: { recordSec: 0, sourceSec: 0 }, keyframes: [] };
+  // r19 KEYED-DICT form (E144): Resolve 19.1.3.7 itself writes KeyframesBA
+  // as a keyed dict of keyed-dict keyframes ({interp,YOut,YIn,Y,XOut,XIn,X}
+  // under keys '0','1',…) on every retime it makes (XMEML import, UI speed
+  // change, EDL M2 freeze) — the same shape buildConstantSpeedTimemapKeyed
+  // emits — while an EXPORT_DRT of a hand-conformed reel carried protobuf
+  // points. The reader used to throw on the keyed form ("unsupported wire
+  // type 7"), so a Resolve-made retime read as unknown. Keyframe 0 at X=0 is
+  // the origin (its Y = the source second the map starts on: 4.0 on a real
+  // ramp harvest); the rest are the points.
+  const kh = String(hex).replace(/[^0-9a-fA-F]/g, '');
+  if (kh.startsWith('00000001')) {
+    const pts = [];
+    for (const e of decodeKeyedDict(Buffer.from(kh, 'hex')).entries) {
+      const inner = decodeKeyedDict(Buffer.from(String(e.value), 'hex')).entries;
+      const get = (k) => { const f = inner.find((x) => x.key === k); return f ? Number(f.value) : 0; };
+      pts.push({ recordSec: get('X'), sourceSec: get('Y') });
+    }
+    pts.sort((a, b) => a.recordSec - b.recordSec);
+    const origin = pts.length && pts[0].recordSec === 0 ? pts.shift() : { recordSec: 0, sourceSec: 0 };
+    return { origin, keyframes: pts, keyed: true };
+  }
   const fields = decodeProtobuf(hex);
   const originField = fields.find((f) => f.field === 2 && f.wire === 1);
   const originSource = originField
@@ -120,7 +141,7 @@ function decodeTimemap(input) {
     const get = (k) => { const e = entries.find((x) => x.key === k); return e ? e.value : undefined; };
     const recordDurationSec = get('XMax');
     const sourceDurationSec = get('LastValidYOffset');
-    const { origin, keyframes } = _decodeKeyframes(get('KeyframesBA'));
+    const { origin, keyframes, keyed } = _decodeKeyframes(get('KeyframesBA'));
     const segments = _segments(keyframes, origin);
     // The EXACT speed lives in the keyframe ratios (source/record per segment); XMax and
     // LastValidYOffset are frame-quantized. `speed` is the first segment's (whole clip if 1 kf);
@@ -128,7 +149,7 @@ function decodeTimemap(input) {
     const speed = segments.length ? segments[0].speed : sourceDurationSec / recordDurationSec;
     const variable = segments.length > 1;
     return {
-      form: 'retimed', variable, speed, segments, keyframes,
+      form: 'retimed', variable, speed, segments, keyframes, origin, keyframeForm: keyed ? 'keyed' : 'protobuf',
       sourceDurationSec, recordDurationSec, entries,
     };
   }

package/resolve-advanced/vendor/drt-format/drt-parser.js

@@ -79,8 +79,17 @@ function decodeTimemapField(hex) {
   }
   if (!d || d.form !== 'retimed') return { form: 'retimed', kind: 'unknown', speed: null, reverse: false };
   const slope = d.segments && d.segments.length ? d.segments[0].speed : null;
-  const base = { form: 'retimed', recordDurationSec: d.recordDurationSec ?? null, sourceDurationSec: d.sourceDurationSec ?? null };
-  if (d.recordDurationSec === FREEZE_XMAX_SENTINEL && slope === 0) return { ...base, kind: 'freeze', speed: 0, reverse: false };
+  const points = [d.origin || { recordSec: 0, sourceSec: 0 }, ...(d.keyframes || [])];
+  const base = { form: 'retimed', recordDurationSec: d.recordDurationSec ?? null, sourceDurationSec: d.sourceDurationSec ?? null, keyframeForm: d.keyframeForm || null, points };
+  if (d.recordDurationSec === FREEZE_XMAX_SENTINEL && slope === 0) {
+    // A flat map over the 60000 sentinel is a FREEZE at the source second the
+    // map holds (Y) — with or without an <In> (E144, render-witnessed: the
+    // E66 harvest carries Y = 0 and In 24, and its render is static at the
+    // source's frame 0: inter-frame change 0.02 vs 0.42 in the source). The
+    // EDL M2 000.0 harvest holds Y = 1.0 with an empty <In>.
+    const y = points[0] ? points[0].sourceSec : 0;
+    return { ...base, kind: 'freeze', speed: 0, reverse: false, freezeSec: y };
+  }
   if (!Number.isFinite(slope) || slope === 0 || Math.abs(slope) > 100) return { ...base, kind: 'unknown', speed: null, reverse: false };
   return {
     ...base,

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.194.0"
+VERSION = "2.196.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.194.0"
+VERSION = "2.196.0"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -2744,15 +2744,31 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "0000000000003840…), and <MediaTimemapBA>: tag byte 0x02 + "
                    "one double (the media length in seconds) on a 100% clip, a "
                    "keyed Sm2TimeMap opening 00000001… on a retimed clip and on "
-                   "generators — its KeyframesBA is the protobuf point form "
-                   "(NOT the keyed-dict form a 19.1.3.7 XMEML retime import "
-                   "writes) and decodes with the DRP library's decodeTimemap: "
+                   "generators — its KeyframesBA is the protobuf point form on "
+                   "that hand-conformed export, while every retime Resolve "
+                   "19.1.3.7 MAKES itself (XMEML import, UI speed change, EDL "
+                   "M2 freeze, speed ramp) writes the KEYED-DICT form (E144: "
+                   "keyframes {interp,YOut,YIn,Y,XOut,XIn,X} under keys "
+                   "'0','1',…; keyframe 0 at X=0 is the origin and its Y the "
+                   "source second the map starts on — 4.0 on a real ramp); "
+                   "both decode with the DRP library's decodeTimemap: "
                    "the keyframe slope is the speed (0.79999 on all four "
                    "retimed clips of a real reel = Premiere's 80 for the same "
                    "cuts, srcOut = In + round(Duration × 0.8) matching "
                    "Premiere's frame for frame), XMax 60000 with a zero slope "
-                   "is the freeze sentinel (a Black Video generator), a "
-                   "negative slope is a reverse (a reversed tail leader). An "
+                   "is the freeze sentinel — a FREEZE at the source second the "
+                   "flat map holds, even when <In> is present: an XMEML import "
+                   "of a 100% clip came back with that flat map at Y=0 and In "
+                   "24, and its render is static at the source's frame 0 "
+                   "(E144, inter-frame change 0.02 vs 0.42 in the source) — "
+                   "Resolve's XMEML importer froze the clip silently; a "
+                   "negative slope is a reverse (a reversed tail leader). On a "
+                   "retimed clip <In> is RECORD-domain (E143): the map spans the "
+                   "whole source stretched by 1/speed and the clip windows into "
+                   "that, so the first source frame shown is In × speed — two "
+                   "timelines of the same reel carried the same 80% map with In "
+                   "52682 (bridge-authored: source 42145, Premiere's frame) and "
+                   "In 42145 (hand conform: source 33716, 8,429 frames early). An "
                    "Sm2TiTransition sits in the same <Items> "
                    "list as the clips with <Start>/<Duration> (its span), "
                    "<PrettyType> (Cross Dissolve), <AlignmentType> and "