davinci-resolve-mcp 2.103.3 → 2.103.4

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 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.103.4
+
+**A frame-numbering trap, documented where agents will look it up.** Issue #164
+by @jonathandahl-cmyk arrived as a detailed report that `AppendToTimeline`'s
+`trackIndex`/`recordFrame` corrupt a timeline — every readback correct, render
+produces a ~6KB stub. Their own same-day correction found the real cause, and it
+is simpler and nastier: **`recordFrame` is timeline-absolute.** It counts from
+Resolve's global frame zero, so `recordFrame=0` on a default `01:00:00:00`
+timeline places the clip at frame 0 — an hour before the timeline's own start at
+86400. The items genuinely exist and are internally consistent, so
+`AppendToTimeline` returns them, every `Get*` reads back the expected values,
+and the render engine — which only walks the timeline's own start→end range —
+reports `JobStatus: Complete` at 100% while writing a near-empty stub.
+
+The assumption was easy to make because Resolve uses both conventions side by
+side: marker `frameId`s *are* timeline-relative (frame 0 == first frame), while
+`recordFrame` and `TimelineItem.GetStart()`/`GetEnd()` are absolute.
+
+This server's own callers were never exposed: `media_pool.append_to_timeline`
+has defaulted to `record_frame_mode="relative"` — adding `GetStartFrame()` for
+you — since v2.17.1, which live-validated the exact arithmetic (relative 12 →
+86412; absolute preserved 86484). What was missing was the catalog entry: the
+API-truth table had five `AppendToTimeline` entries (the half-open `endFrame`
+bound, occupied-span null-ids, mixed-fps duration floors…) but never the
+absolute origin, which fails more silently than any of them. It now records the
+convention, the render-lies-too behavior, why the wrapper default exists, and
+that `JobStatus: Complete` is not proof a render produced frames.
+
+### Changed
+
+- `src/utils/api_truth.py` gains
+  `MediaPool.AppendToTimeline clipInfo recordFrame (timeline-absolute origin)`
+  (#164). Internal entry — an undocumented convention, not a Resolve defect —
+  so the Blackmagic-facing limitations report is unchanged.
+
 ## What's New in v2.103.3
 
 **A batch transcription fix that would have failed every clip.** Issue #160 by

package/README.md

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

package/install.py

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

package/src/granular/common.py

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

package/src/utils/api_truth.py

@@ -1853,6 +1853,44 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "when mirroring keep-ranges into clipInfos.",
         "tags": ["timeline", "edit", "off-by-one", "readback"],
     },
+    {
+        "symbol": "MediaPool.AppendToTimeline clipInfo recordFrame (timeline-absolute origin)",
+        "object": "MediaPool",
+        "signature": "([{mediaPoolItem, startFrame, endFrame, recordFrame, "
+                     "trackIndex, mediaType}]) -> [TimelineItem]",
+        "reality": "clipInfo recordFrame is TIMELINE-ABSOLUTE: it counts from "
+                   "Resolve's global frame zero, not from the timeline's own "
+                   "GetStartFrame(). A timeline with the default 01:00:00:00 "
+                   "start begins at frame 86400, so recordFrame=0 places the "
+                   "item about an hour BEFORE the timeline starts. Nothing "
+                   "reports the mistake, because the items are real and "
+                   "self-consistent: AppendToTimeline returns them, "
+                   "GetName/GetSourceStartFrame/GetSourceEndFrame all read back "
+                   "the expected values, and the bin count is right. Only a "
+                   "render exposes it — the engine walks the timeline's own "
+                   "start->end range, so the job reports JobStatus Complete at "
+                   "100% in under 2s and writes a ~6KB stub for a 405s "
+                   "timeline. The trap is that the two frame conventions sit "
+                   "side by side: marker frameIds ARE timeline-relative "
+                   "(frame 0 == first frame), while recordFrame and "
+                   "TimelineItem.GetStart/GetEnd are absolute. Distinct from "
+                   "the null-id entry below, which is a recordFrame landing in "
+                   "an OCCUPIED span rather than before the start. Verified on "
+                   "Studio 20.3.2.9 (v2.17.1 probe: relative record_frame 12 "
+                   "landed at 86400 + 12 = 86412, absolute preserved 86484) and "
+                   "independently on Studio 21.0.4.5 (issue #164).",
+        "recommended": "Offset every recordFrame by timeline.GetStartFrame(). "
+                       "This server already does it: "
+                       "media_pool.append_to_timeline defaults to "
+                       "record_frame_mode='relative' and adds the start frame, "
+                       "so pass record_frame_mode='absolute' only for raw "
+                       "Resolve frame numbers. When driving the API directly, "
+                       "never treat JobStatus Complete as proof a render "
+                       "worked — check the output file's duration, not just "
+                       "that the job finished.",
+        "tags": ["timeline", "edit", "render", "silent-failure", "media-pool"],
+        "issue": 164,
+    },
     {
         "symbol": "Timeline.DeleteClips (requires the Edit page; flaky first attempt)",
         "object": "Timeline",