fix(timemap): reverse and speed ramps both work; decoder reported a reverse as speed 0 — release v2.95.3

The retime api_truth entry carried an explicit warning: "UNTESTED as import
routes: reverse (negative time_scalar / reverse M2) and varying-speed maps — do
not extrapolate the constant-speed result to them." Both are now measured on
Studio 21.0.4.5 and both work; the warning is closed.

REVERSE lands through both import routes. OTIO with time_scalar -1 placed a clip
reading GetSourceStartFrame 95 -> GetSourceEndFrame 46; EDL with M2 -24.0 read
48 -> 0. So the API DOES expose direction — a reversed clip reports source start
GREATER than source end, a negative span.

VARYING-SPEED RAMPS cannot be expressed in OTIO (LinearTimeWarp is one
time_scalar, constant by construction) but can be authored offline and survive.
A Sm2TimeMap built with buildTimemap carrying 0-2s record at 0.5x and 2-4s at
2.0x was patched into a clip's MediaTimemapBA, imported, and re-exported by
Resolve with the segments UNCHANGED. Independent API-side confirmation: the clip
read source 0..120 over a 96-frame record, and 2s@0.5x (24 source frames) +
2s@2.0x (96) is exactly 120.

Two decoder bugs, both exposed by the first reversed map media-timemap.js ever
saw:

- Fixed-offset keyframe reads. Each point omits whichever of recordSec/sourceSec
  is zero (protobuf default-omission), so readDoubleLE(1)/readDoubleLE(10) threw
  "offset out of range" on every reversed map. Forward maps decoded only because
  both values happened to be non-zero.
- A hardcoded (0,0) origin. A reversed clip starts at the far end of the source
  and Resolve encodes that starting offset as a TOP-LEVEL protobuf field 2
  double. Assuming (0,0) made a reverse decode as SPEED 0 — a plausible wrong
  number, worse than a crash. It now decodes as -1.

Four tests pin the reverse shape, the omitted-value points, the negative-speed
result, and that forward maps are unaffected.

Also records a trap that cost real time: buildTimemap returns a BUFFER, and
writing it into XML without .toString('hex') embeds mojibake. The failure is
silent — the clip imports cleanly and reads 0..0, indistinguishable from the
degenerate-map signature this ledger describes for xmeml imports, so it reads as
"Resolve rejected the retime" when it is a caller bug.

Python suite 2633 passed / 1 skipped; Node suite 818, 0 fail.

Author: samuelgursky

CHANGELOG.md

@@ -2,6 +2,51 @@
 
 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.95.3
+
+Closes the retime entry's explicit `UNTESTED` warning: **reverse and
+variable-speed ramps both work**, and fixes two decoder bugs found proving it.
+
+### Measured — reverse lands through both import routes
+
+On Studio 21.0.4.5. OTIO with a negative `time_scalar` (-1) placed a clip reading
+`GetSourceStartFrame` 95 → `GetSourceEndFrame` 46; EDL with a negative `M2` rate
+(-24.0 at 24fps) read 48 → 0. **The API does expose direction** — a reversed clip
+reports source start GREATER than source end, i.e. a negative span.
+
+### Measured — variable-speed ramps survive Resolve intact
+
+They cannot be expressed in OTIO (`LinearTimeWarp` is a single `time_scalar`,
+constant by construction), but they can be authored offline. A `Sm2TimeMap` built
+with `media-timemap.buildTimemap` carrying two segments — 0–2s record at 0.5×,
+2–4s at 2.0× — was patched into a clip's `MediaTimemapBA`, imported, and
+**re-exported by Resolve with the segments unchanged**. Confirmed independently
+from the API side: the clip read source `0..120` over a 96-frame record, and
+2s@0.5× (24 source frames) + 2s@2.0× (96) is exactly 120.
+
+### Fixed — the timemap decoder reported a reverse as speed 0
+
+Two real bugs in `media-timemap.js`, both exposed by the first reversed map it
+ever saw:
+
+- **Fixed-offset keyframe reads.** Each point omits whichever of
+  `recordSec`/`sourceSec` is zero (protobuf default-omission), so
+  `readDoubleLE(1)`/`readDoubleLE(10)` threw *"offset out of range"* on every
+  reversed map. Forward maps only decoded because both values happened to be
+  non-zero.
+- **A hardcoded (0,0) origin.** A reversed clip starts at the far end of the
+  source, and Resolve encodes that starting offset as a **top-level protobuf
+  field 2** double. Assuming (0,0) made a reverse decode as **speed 0** — a
+  plausible wrong number, which is worse than a crash. It now decodes as −1.
+
+### Trap worth naming
+
+`buildTimemap` returns a **Buffer**. Writing it into the XML without
+`.toString('hex')` embeds mojibake, and the failure is silent: the clip imports
+cleanly and reads `0..0` — indistinguishable from the degenerate-map signature
+the ledger describes for xmeml imports, so it looks like Resolve rejected the
+retime when it is a caller bug. It cost real time here before being caught.
+
 ## What's New in v2.95.2
 
 Adds the live round-trip harness the offline `.drp` tier never had — the absence

README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.95.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.95.3-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(353%20full)-blue.svg)](#server-modes)

README.zh-CN.md

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

docs/reference/api-limitations.md

@@ -36,7 +36,7 @@
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.95.2"
+VERSION = "2.95.3"
 # 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

install.py

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.95.2",
+  "version": "2.95.3",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package.json

@@ -117,3 +117,59 @@ test('identityTimemap builds a [02][end,0,end,0,end] map', () => {
   assert.strictEqual(b.seconds.length, 5);
   assert.strictEqual(Math.round(b.seconds[0] * (30000 / 1001)), 4575);
 });
+
+// --- Reverse maps: the origin is NOT always (0,0) ---------------------------
+// Captured from a clip reversed via EDL M2 / OTIO negative time_scalar and
+// exported by DaVinci Resolve Studio 21.0.4.5. Two things here used to break:
+//   1. Each keyframe point omits whichever of recordSec/sourceSec is 0 —
+//      protobuf default-omission — so the old fixed-offset reader
+//      (readDoubleLE(1) / readDoubleLE(10)) threw "offset out of range".
+//   2. The starting source offset is a TOP-LEVEL field 2 double. Assuming a
+//      (0,0) origin made a reverse decode as speed 0 — a plausible wrong
+//      number rather than an error, which is the worse failure.
+const REVERSED_KEYFRAMES_BA = '800a09115655555555d517400a09095655555555d51740';
+
+function reversedMapHex() {
+  const { encodeKeyedDict } = require('../keyed-dict');
+  const T_DOUBLE = 6; const T_STRING = 10; const T_BYTES = 12;
+  return encodeKeyedDict({
+    hdr: 1,
+    entries: [
+      { key: 'YMin', type: T_DOUBLE, subType: 0, value: -1 },
+      { key: 'YMax', type: T_DOUBLE, subType: 0, value: -1 },
+      { key: 'XMax', type: T_DOUBLE, subType: 0, value: 5.958333333333334 },
+      { key: 'UniqueId', type: T_STRING, subType: 0, value: '4dbe3e42-ab1e-4b93-8118-67fdc376c962' },
+      { key: 'LastValidYOffset', type: T_DOUBLE, subType: 0, value: 5.958333333333333 },
+      { key: 'KeyframesBA', type: T_BYTES, subType: 0, value: REVERSED_KEYFRAMES_BA },
+      { key: 'DbType', type: T_STRING, subType: 0, value: 'Sm2TimeMap' },
+    ],
+  }).toString('hex');
+}
+
+test('decodeTimemap: a reversed map decodes without throwing', () => {
+  assert.doesNotThrow(() => decodeTimemap(reversedMapHex()));
+});
+
+test('decodeTimemap: a reversed map reports NEGATIVE speed, not 0', () => {
+  const d = decodeTimemap(reversedMapHex());
+  assert.equal(d.segments.length, 1);
+  assert.equal(d.segments[0].speed, -1);
+  assert.ok(d.segments[0].speed < 0, 'reverse must not decode as speed 0');
+});
+
+test('_decodeKeyframePoint: a point may omit either value (protobuf default 0)', () => {
+  // sourceSec-only and recordSec-only points both appear in one real reversed map.
+  const d = decodeTimemap(reversedMapHex());
+  assert.equal(d.recordDurationSec, 5.958333333333334);
+  assert.equal(d.sourceDurationSec, 5.958333333333333);
+});
+
+test('forward maps are unaffected by the origin fix', () => {
+  const fwd = buildTimemap({
+    keyframes: [{ recordSec: 2, sourceSec: 1 }, { recordSec: 4, sourceSec: 5 }],
+    sourceDurationSec: 6, recordDurationSec: 4, uniqueId: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
+  });
+  const d = decodeTimemap(fwd.toString('hex'));
+  assert.equal(d.variable, true);
+  assert.deepEqual(d.segments.map((s) => s.speed), [0.5, 2]);
+});

resolve-advanced/vendor/drp-format/__tests__/media-timemap.test.js

@@ -41,17 +41,69 @@ function _isKeyedForm(b) {
  * (fixed64 LE doubles). The map starts at the implicit (0,0); constant speed has one keyframe,
  * a variable-speed ramp has one keyframe per added speed point.
  */
+/**
+ * One keyframe point: an inner message of field 1 (recordSec) and field 2
+ * (sourceSec), both wire type 1 (64-bit double) — tags 0x09 and 0x11.
+ *
+ * Both are OPTIONAL. Protobuf omits a field whose value is the default (0), so
+ * a point can legitimately carry only one of the two, and fixed offsets do not
+ * work. This is not theoretical: a REVERSED clip exported by Resolve 21.0.4.5
+ * encodes its points as `0a 09 11 <double>` (sourceSec only) and
+ * `0a 09 09 <double>` (recordSec only), and the previous fixed-offset reader
+ * — `readDoubleLE(1)` / `readDoubleLE(10)` — threw
+ * "offset out of range … Received 10" on every reversed map. Forward maps only
+ * decoded because both values happened to be non-zero.
+ */
+function _decodeKeyframePoint(buf) {
+  let recordSec = 0;
+  let sourceSec = 0;
+  let i = 0;
+  while (i < buf.length) {
+    const tag = buf[i];
+    if (tag === 0x09 && i + 9 <= buf.length) { recordSec = buf.readDoubleLE(i + 1); i += 9; }
+    else if (tag === 0x11 && i + 9 <= buf.length) { sourceSec = buf.readDoubleLE(i + 1); i += 9; }
+    else break; // unknown tag or truncated — stop rather than misread
+  }
+  return { recordSec, sourceSec };
+}
+
+/**
+ * Keyframe points plus the map's ORIGIN.
+ *
+ * The origin is not always (0,0). A reversed clip starts at the far end of the
+ * source and walks backwards, and Resolve encodes that starting source offset as
+ * a TOP-LEVEL field 2 double alongside the keyframe messages. Measured on a
+ * reversed clip exported by Studio 21.0.4.5:
+ *
+ *   80 0a 09                      field 160 = 9
+ *   11 5655555555d51740           field 2   = 5.9583  <- origin sourceSec
+ *   0a 09 09 5655555555d51740     field 1   = { recordSec: 5.9583 }
+ *
+ * Reading that as an implicit (0,0) origin yields a segment from (0,0) to
+ * (5.9583, 0) — slope 0 — so a reverse decodes as "speed 0", a plausible-looking
+ * wrong answer rather than an error. With the origin it is (0, 5.9583) to
+ * (5.9583, 0): slope -1, a reverse.
+ */
 function _decodeKeyframes(hex) {
-  if (hex == null) return [];
+  if (hex == null) return { origin: { recordSec: 0, sourceSec: 0 }, keyframes: [] };
   const fields = decodeProtobuf(hex);
-  return fields
-    .filter((f) => f.field === 1 && f.wire === 2)
-    .map((f) => ({ recordSec: f.value.readDoubleLE(1), sourceSec: f.value.readDoubleLE(10) }));
+  const originField = fields.find((f) => f.field === 2 && f.wire === 1);
+  const originSource = originField
+    ? (Buffer.isBuffer(originField.value)
+      ? originField.value.readDoubleLE(0)
+      : Number(originField.value))
+    : 0;
+  return {
+    origin: { recordSec: 0, sourceSec: Number.isFinite(originSource) ? originSource : 0 },
+    keyframes: fields
+      .filter((f) => f.field === 1 && f.wire === 2)
+      .map((f) => _decodeKeyframePoint(f.value)),
+  };
 }
 
-/** Per-segment speeds from the keyframe points (slope Δsource/Δrecord); starts at (0,0). */
-function _segments(keyframes) {
-  const pts = [{ recordSec: 0, sourceSec: 0 }, ...keyframes];
+/** Per-segment speeds from the keyframe points (slope Δsource/Δrecord). */
+function _segments(keyframes, origin = { recordSec: 0, sourceSec: 0 }) {
+  const pts = [origin, ...keyframes];
   const segs = [];
   for (let i = 1; i < pts.length; i++) {
     const dr = pts[i].recordSec - pts[i - 1].recordSec;
@@ -68,8 +120,8 @@ 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 keyframes = _decodeKeyframes(get('KeyframesBA'));
-    const segments = _segments(keyframes);
+    const { origin, keyframes } = _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);
     // `segments` carries the full variable-speed ramp.

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

@@ -87,7 +87,7 @@
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.95.2"
+VERSION = "2.95.3"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

src/granular/common.py

@@ -11,7 +11,7 @@
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.95.2"
+VERSION = "2.95.3"
 
 import base64
 import os