davinci-resolve-mcp 2.138.0 → 2.139.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 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.139.0 — speed ramps, and the easing crash law
+
+### Added
+
+- **Variable-speed ramps authored offline** (`cuts[].ramp:
+  [{durationFrames, speed}, …]` — two or more linear segments from the cut
+  head, `srcIn` honored). No harvest was needed: the engine honors
+  intermediate keyframes in the same seconds-domain keyed `Sm2TimeMap` the
+  constant retimes use. E63/E64 proof on 19.1.3.7: a 50%→100% knee read back
+  the exact source window AND rendered the predicted frame cadence (11/23
+  doubled frames in the half-speed window, none at full speed; the 2×
+  segment moved at 4.3× the 0.5× segment's per-frame motion), with `srcIn`
+  landing on the right source frame by luma.
+
+### Measured and closed
+
+- **Eased ramps are a crasher, not a boundary.** A keyframe with
+  `interp = 2` crashed Resolve outright on import (E65 — app death, headless
+  recovery per doctrine). The builders hardcode `interp = 0`, the test suite
+  asserts it, and the guide records the law: linear segments are the
+  authorable envelope on 19.1.3.
+
 ## What's New in v2.138.0 — wipes join the conform
 
 ### Added

package/README.md

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

package/docs/guides/native-drt-authoring.md

@@ -47,6 +47,7 @@ window. `render.verify_output` covers the container-level checks.
 | Constant retimes, forward | `cuts[].speed` (e.g. `0.5`) | v2.113 |
 | Constant retimes, reverse | `cuts[].reverse` | v2.114 |
 | Freeze frames | `cuts[].freeze` (holds source frame `srcIn`) | v2.134 |
+| Speed ramps | `cuts[].ramp: [{durationFrames, speed}, …]` (linear segments only) | v2.139 |
 | Audio placements, A1–A8 | `cuts[].audioOnly + track` | v2.115 |
 | Built-in generators | `elements: [{type:'generator', generatorName}]` | v2.110 |
 | Custom start timecode | `spec.startFrame` / `preserveStartTimecode` | v2.117 |
@@ -96,6 +97,14 @@ the clip's `<In>`/`<Duration>` window into it in record-domain frames.
 Reverse is the same map with the Y endpoints swapped, and `In` then measures
 from the source end.
 
+**Ramps are just more keyframes — but easing is a crasher.** The engine
+honors intermediate keyframes in the same seconds-domain map (E63/E64:
+a synthesized 50%→100% knee read back AND rendered with the exact predicted
+frame cadence, srcIn baked into the first keyframe's Y, clip `In` at the cut
+head). `cuts[].ramp` authors piecewise-constant segments. The keyframes'
+`interp` field must stay **0**: an `interp=2` keyframe crashed Resolve
+19.1.3 outright on import (app death, E65) — eased ramps are not authorable.
+
 **Freezes are a third shape, not a flat retime.** A flat line in the retime's
 frame domain reads back frozen but *renders moving* — the one divergence that
 runs in the "working" direction. The real freeze (harvested from a live EDL

package/install.py

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

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

@@ -51,7 +51,7 @@ const assembleSchema = z.object({
   spec: z
     .object({})
     .passthrough()
-    .describe("assembleTimeline spec: { timelineName?, startFrame? (timeline start frame @24, default 86400=01:00:00:00 — sets the start TIMECODE, render-verified on 19), media?: {mediaFilePath, spec:{width,height,frameCount,fps}, cuts:[{startFrame,durationFrames,srcIn?,track? (1-based video track; >1 = video-only, render-verified stacking),speed?/reverse? (constant retime, e.g. 0.5, forward or backwards; video-only; readback+render-verified on 19),freeze? (true = hold source frame srcIn for the whole cut; video-only; render-proven frozen on 19 via freezedetect),audioOnly?+track? (explicit AUDIO placement on audio track 1-8; presence suppresses the A1 mirror; render-verified on 19)}]} | [same, ...] (multi-source needs media_pool.capture_media_template run once per file), transitions?: [{track, atFrame, durationFrames?, trackType? ('video' | 'audio' cross-fade), type? ('dissolve' default | 'wipe' — the single soft-edge wipe style Resolve's own EDL importer maps every W-code to; all render-verified on 19)}], markers?: [{frame (timeline-absolute), color? (16 names), name?, note?, duration?, customData?}] (readback-verified on 19), compounds?: [{name, startFrame (parent, absolute), durationFrames, track?, cuts:[{mediaFilePath, startFrame (INNER, 0-based), durationFrames, srcIn?}], compounds?: [same, nested — frames inner-relative]}] (multiple PARALLEL compounds compose AND compounds NEST recursively — depth-2 AND depth-3 playback render-verified on 19 (the old depth-2 black was a missing SequenceSetup key, fixed); inner cuts need captured templates w/ native clips), subtitles?: [{startFrame (timeline-absolute), durationFrames, text}] + subtitlesSrt? (raw SRT, cues anchor at the origin; readback-verified on 19; angle-bracket runs read as SRT markup), elements?: [{type:'title'|'generator', track, startFrame, durationFrames?, text?, generatorName? ('Solid Color'|'SMPTE Color Bar'|'Grey Scale' render-verified on 19), ...}] }. startFrame is timeline-absolute (origin 86400)."),
+    .describe("assembleTimeline spec: { timelineName?, startFrame? (timeline start frame @24, default 86400=01:00:00:00 — sets the start TIMECODE, render-verified on 19), media?: {mediaFilePath, spec:{width,height,frameCount,fps}, cuts:[{startFrame,durationFrames,srcIn?,track? (1-based video track; >1 = video-only, render-verified stacking),speed?/reverse? (constant retime, e.g. 0.5, forward or backwards; video-only; readback+render-verified on 19),freeze? (true = hold source frame srcIn for the whole cut; video-only; render-proven frozen on 19 via freezedetect),ramp? ([{durationFrames,speed},...] >=2 LINEAR segments from the cut head, srcIn honored; video-only; render-proven cadence on 19 — eased/curved ramps are NOT authorable, an interp!=0 keyframe crashes Resolve on import (measured)),audioOnly?+track? (explicit AUDIO placement on audio track 1-8; presence suppresses the A1 mirror; render-verified on 19)}]} | [same, ...] (multi-source needs media_pool.capture_media_template run once per file), transitions?: [{track, atFrame, durationFrames?, trackType? ('video' | 'audio' cross-fade), type? ('dissolve' default | 'wipe' — the single soft-edge wipe style Resolve's own EDL importer maps every W-code to; all render-verified on 19)}], markers?: [{frame (timeline-absolute), color? (16 names), name?, note?, duration?, customData?}] (readback-verified on 19), compounds?: [{name, startFrame (parent, absolute), durationFrames, track?, cuts:[{mediaFilePath, startFrame (INNER, 0-based), durationFrames, srcIn?}], compounds?: [same, nested — frames inner-relative]}] (multiple PARALLEL compounds compose AND compounds NEST recursively — depth-2 AND depth-3 playback render-verified on 19 (the old depth-2 black was a missing SequenceSetup key, fixed); inner cuts need captured templates w/ native clips), subtitles?: [{startFrame (timeline-absolute), durationFrames, text}] + subtitlesSrt? (raw SRT, cues anchor at the origin; readback-verified on 19; angle-bracket runs read as SRT markup), elements?: [{type:'title'|'generator', track, startFrame, durationFrames?, text?, generatorName? ('Solid Color'|'SMPTE Color Bar'|'Grey Scale' render-verified on 19), ...}] }. startFrame is timeline-absolute (origin 86400)."),
   outputPath: z.string().describe('Absolute path where the importable .drt will be written'),
   targetAppVersion: z
     .union([z.string(), z.number()])

package/resolve-advanced/vendor/drp-format/assemble-timeline.js

@@ -25,7 +25,7 @@ const { createEmptyProject, addMediaClip, DEFAULT_START_FRAME } = require('./aut
 const { loadMediaTemplate, transplantMediaElement, insertMediaElement } = require('./media-template-cache');
 const JSZip = require('jszip');
 const { cutSourceIntoClips } = require('./cut-media');
-const { buildConstantSpeedTimemapKeyed, buildFreezeTimemapKeyed } = require('./media-timemap');
+const { buildConstantSpeedTimemapKeyed, buildFreezeTimemapKeyed, buildRampTimemapKeyed } = require('./media-timemap');
 const { encodeTimelineMarkersBlob } = require('./timeline-markers-blob');
 const { placeSubtitles, parseSrt } = require('./place-subtitles');
 const { placeCompound } = require('./place-compound');
@@ -78,7 +78,9 @@ async function assembleTimeline(spec = {}) {
           // srcIn/duration are TIMELINE frames (24fps template); the media's
           // extent converts: frameCount / mediaFps × 24.
           const maxTimelineFrames = Math.floor((mediaSpec.frameCount / mediaSpec.fps) * 24);
-          if ((cut.srcIn ?? 0) + cut.durationFrames > maxTimelineFrames) {
+          // Ramps consume sum(duration × speed) source, not durationFrames —
+          // the ramp builder enforces its own source-extent bound.
+          if (!Array.isArray(cut.ramp) && (cut.srcIn ?? 0) + cut.durationFrames > maxTimelineFrames) {
             throw new RangeError(
               `assembleTimeline: ${label}.cuts[${i}] reads past the media's end — (srcIn ?? 0) + durationFrames exceeds ${maxTimelineFrames} timeline frames (media ${mediaSpec.frameCount} frames @ ${mediaSpec.fps} fps on the 24fps template timeline)`,
             );
@@ -137,7 +139,26 @@ async function assembleTimeline(spec = {}) {
         // captured before clip elements were harvested.
         if (caches[i] && caches[i].videoClipElement) out.donorClipVideo = caches[i].videoClipElement;
         if (caches[i] && caches[i].audioClipElement) out.donorClipAudio = caches[i].audioClipElement;
-        if (cut.freeze || cut.speed === 0) {
+        if (Array.isArray(cut.ramp)) {
+          // VARIABLE-SPEED RAMP (E63, render-verified): piecewise-constant
+          // segments as one multi-keyframe Sm2TimeMap. Record domain starts
+          // at the cut head (In stays 0); srcIn bakes into the map's first
+          // keyframe. Video-only, like every retime.
+          if (cut.freeze || cut.reverse || (cut.speed !== undefined && cut.speed !== 1)) {
+            throw new RangeError('assembleTimeline: cut.ramp cannot combine with speed/reverse/freeze');
+          }
+          const fpsR = Math.round(src.spec.fps || 24);
+          const total = cut.ramp.reduce((s, seg) => s + (seg && seg.durationFrames || 0), 0);
+          if (total !== cut.durationFrames) {
+            throw new RangeError(`assembleTimeline: ramp segments sum to ${total} frames but the cut is ${cut.durationFrames}`);
+          }
+          out.timemap = buildRampTimemapKeyed({
+            segments: cut.ramp, srcIn: cut.srcIn ?? 0,
+            sourceFrames: src.spec.frameCount, fps: fpsR, uniqueId: randomUUID(),
+          }).toString('hex');
+          out.srcIn = 0; // record-domain In is the cut head; the map carries srcIn
+          delete out.ramp;
+        } else if (cut.freeze || cut.speed === 0) {
           // FREEZE frame (r19 keyed map harvested from a live EDL M2 000.0
           // import, E55; render-proven frozen). Holds source frame srcIn for
           // the whole cut. The frozen clip's <In> stays EMPTY; the position

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

@@ -304,10 +304,62 @@ function buildFreezeTimemapKeyed({ freezeFrame, sourceFrames, fps = 24, uniqueId
   ] });
 }
 
+/**
+ * VARIABLE-SPEED RAMP — piecewise-constant speed segments as a multi-keyframe
+ * r19 keyed Sm2TimeMap. E63 (2026-08-31): the engine honors intermediate
+ * keyframes with the SAME seconds-domain conventions as the constant maps —
+ * a synthesized 3-keyframe 50%→100% ramp read back source 0..36 over 48
+ * record frames AND rendered with exactly the predicted cadence (11/23
+ * doubled frames in the 50% window, 0/24 at 100%). Record domain starts at
+ * the cut head (clip In stays 0); srcIn bakes into the first keyframe's Y.
+ *
+ * @param {Array<{durationFrames:number, speed:number}>} segments - record-domain
+ *   pieces, in order from the cut head; speeds are source/record multipliers.
+ */
+function buildRampTimemapKeyed({ segments, srcIn = 0, sourceFrames, fps = 24, uniqueId }) {
+  if (!Array.isArray(segments) || segments.length < 2) throw new TypeError('buildRampTimemapKeyed: segments must be an array of >= 2 {durationFrames, speed} pieces (use speed/freeze for a single one)');
+  if (!Number.isInteger(sourceFrames) || sourceFrames < 1) throw new TypeError('buildRampTimemapKeyed: sourceFrames must be a positive integer');
+  if (!Number.isInteger(srcIn) || srcIn < 0) throw new TypeError('buildRampTimemapKeyed: srcIn must be a non-negative integer');
+  const kf = (X, Y) => encodeKeyedDict({ hdr: 1, entries: [
+    { key: 'interp', type: 0x02, subType: 0, value: 0 },
+    { key: 'YOut', type: T_DOUBLE, subType: 0, value: 0 },
+    { key: 'YIn', type: T_DOUBLE, subType: 0, value: 0 },
+    { key: 'Y', type: T_DOUBLE, subType: 0, value: Y },
+    { key: 'XOut', type: T_DOUBLE, subType: 0, value: 0 },
+    { key: 'XIn', type: T_DOUBLE, subType: 0, value: 0 },
+    { key: 'X', type: T_DOUBLE, subType: 0, value: X },
+  ] }).toString('hex');
+  let x = 0;
+  let y = srcIn / fps;
+  const points = [[x, y]];
+  for (const [i, seg] of segments.entries()) {
+    if (!Number.isInteger(seg.durationFrames) || seg.durationFrames < 1) throw new TypeError(`buildRampTimemapKeyed: segments[${i}].durationFrames must be a positive integer`);
+    if (!(seg.speed > 0)) throw new RangeError(`buildRampTimemapKeyed: segments[${i}].speed must be > 0 (freeze/reverse segments are not authorable in a ramp)`);
+    x += seg.durationFrames / fps;
+    y += (seg.durationFrames * seg.speed) / fps;
+    points.push([x, y]);
+  }
+  const sourceEnd = y * fps;
+  if (sourceEnd > sourceFrames) {
+    throw new RangeError(`buildRampTimemapKeyed: ramp consumes source frame ${Math.ceil(sourceEnd)} but the media has ${sourceFrames}`);
+  }
+  const entries = points.map(([X, Y], i) => ({ key: String(i), type: T_BYTES, subType: 0, value: kf(X, Y) })).reverse();
+  const keyframes = encodeKeyedDict({ hdr: 1, entries }).toString('hex');
+  const [XMax, YMax] = points[points.length - 1];
+  return encodeKeyedDict({ hdr: 1, entries: [
+    { key: 'YMax', type: T_DOUBLE, subType: 0, value: YMax },
+    { key: 'XMax', type: T_DOUBLE, subType: 0, value: XMax },
+    { key: 'UniqueId', type: T_STRING, subType: 0, value: uniqueId },
+    { key: 'LastValidYOffset', type: T_DOUBLE, subType: 0, value: (sourceFrames - 1) / fps },
+    { key: 'KeyframesBA', type: T_BYTES, subType: 0, value: keyframes },
+    { key: 'DbType', type: T_STRING, subType: 0, value: 'Sm2TimeMap' },
+  ] });
+}
+
 module.exports = {
   decodeTimemap, encodeTimemap, encodeRetimedTimemap,
   identityTimemap, buildConstantSpeedTimemap, buildConstantSpeedTimemapKeyed,
-  buildFreezeTimemapKeyed,
+  buildFreezeTimemapKeyed, buildRampTimemapKeyed,
   buildTimemap, decodeProtobuf,
   TYPE_LINEAR,
 };

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.138.0"
+VERSION = "2.139.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.138.0"
+VERSION = "2.139.0"
 
 import base64
 import os