davinci-resolve-mcp 2.104.2 → 2.104.4

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 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.104.4
+
+Hardening pass over the classes the v2.104.2 batch exposed, live-verified on
+Studio 19.1.3.7.
+
+**set_title_text works on builds where SetProperty cannot.** On Studio 19.1.3
+a Text+ item rejects every title property key, so set_title_text failed while
+the item's Fusion comp accepted the same text all along. The setter now falls
+back to writing StyledText on the TextPlus tool — deliberately UNLOCKED, per
+the comp-lock render bug — and reports success only after reading the input
+back. Live-verified end to end: set via fallback, read via get_title_text,
+and a rendered frame confirms the text reaches the output (mean luma above
+black). bulk_set_title_text inherits the fallback. PR #166's discarded-return
+guard caught the fallback's bare SetInput during development — the allowlist
+entry records that the write is verified by readback, which is stronger than
+the bool Fusion doesn't return.
+
+**verify_output no longer flags deliberate short renders.** A single-frame
+capture tripped the mark-range-collapse warning, because the checker cannot
+distinguish a caller-chosen short range from a Resolve-rewritten one. Passing
+expected_frames / expected_duration_seconds matching the mark range now
+suppresses the collapse warning; an unstated short range still warns.
+
+**#171's scope measured: the internal-name override is FCP7-specific.** An
+OTIO export re-imported under a new timelineName creates a new timeline
+(measured 19.1.3.7), so the api_truth entry now says the override is an FCP7
+XML behavior, not a general import rule.
+
+**One more #167-class constant found and removed.** effect-encoder's exported
+"common double values" hex table — consumed by nothing — carried a '0.9'
+entry that decoded to 0.8. Deleted; the sweep found the remaining converters
+(editorial, media-inventory, the Python timecode helpers) already round
+correctly.
+
+## What's New in v2.104.3
+
+Documentation follow-through on the v2.104.2 batch.
+
+- The FCP7 internal-sequence-name-overrides-timelineName behavior (#171) is now
+  a submit-tagged api_truth entry, so it feeds the Blackmagic-facing
+  limitations report alongside the fix that works around it.
+- `project_db.list_subtitle_styles`'s styled:false note now states that the
+  "must be styled once in the UI" precondition covers the scripted
+  `ImportMedia(srt)` + `AppendToTimeline` route too (confirmed by the #169
+  reporter on Studio 21.0.4.5), not only tracks added empty in the UI.
+
 ## What's New in v2.104.2
 
 A contributor batch: two merged PRs, one PR converted into its fix, and four

package/README.md

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

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 33 missing capabilities, 39 bugs / unreliable behaviors.
+**Totals:** 33 missing capabilities, 40 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -517,6 +517,15 @@ values, or automation-hostile modal prompts.
 - **Reference:** [issue #77](https://github.com/samuelgursky/davinci-resolve-mcp/issues/77)
 - **Tags:** unreliable-return, silent-failure, metadata, reel-name
 
+### MediaPool.ImportTimelineFromFile (internal sequence name overrides timelineName)
+
+- **Object:** `MediaPool`
+- **Signature:** `(filePath, {timelineName, importSourceClips, ...}) -> Timeline`
+- **Behavior:** For FCP7 XML, the sequence name INSIDE the file wins over the timelineName import option. When the internal name matches an existing timeline, the call returns that EXISTING timeline — no error, no new timeline — so an export→edit→re-import loop keying uniqueness on the option 'succeeds' while operating on one timeline forever (issue #171, Studio 21.0.4.5; wrapper behavior verified on 19.1.3.7). Distinct from the documented repeated-timelineName None return: here the option is fresh and the file's name is stale.
+- **Workaround / current handling:** Rewrite the <sequence><name> inside the file to the intended name before importing — timeline.import_timeline_checked does this automatically for FCP7 XML and errors when a non-rewritable format still returns an existing timeline. Never treat a truthy return as proof of creation; check the returned timeline's id against the pre-import set.
+- **Reference:** [issue #171](https://github.com/samuelgursky/davinci-resolve-mcp/issues/171)
+- **Tags:** timeline, import, silent-failure, unreliable-return
+
 ### Timeline.DeleteClips (requires the Edit page; flaky first attempt)
 
 - **Object:** `Timeline`

package/install.py

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

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

@@ -259,7 +259,7 @@ export const projectDbTool = {
         return {
           tracks,
           note: tracks.some((t) => t.styled === false)
-            ? 'Tracks with styled:false carry no style blob (Resolve writes a NumLayers-only stub until the track is styled once in the UI); set_subtitle_style cannot patch those.'
+            ? 'Tracks with styled:false carry no style blob (Resolve writes a NumLayers-only stub until the track is styled once in the UI); set_subtitle_style cannot patch those. This covers scripted routes too: a track built by MediaPool.ImportMedia(srt) + AppendToTimeline([srtClip]) reports styled:false (confirmed on Studio 21.0.4.5, issue #169), so style once in the UI regardless of how the track was created.'
             : undefined,
         };
       } finally {

package/resolve-advanced/vendor/drp-format/effect-encoder.js

@@ -180,16 +180,10 @@ function encodeFloat(value) {
   return buffer.toString('hex');
 }
 
-/**
- * Common double values in hex for quick reference
- */
-const DOUBLE_VALUES = {
-  '1.0': '000000000000f03f',
-  '1.1': '9a9999999999f13f',
-  '0.9': '9a9999999999e93f',
-  '2.0': '0000000000000040',
-  '0.5': '000000000000e03f',
-};
+// A "common double values in hex" reference table used to sit here. It was
+// consumed by nothing, and its '0.9' entry actually decoded to 0.8 — the same
+// hand-typed-hex rot that put 30000/1001 in drt.author's 23.976 slot
+// (issue #167). Encode with encodeDouble()/writeDoubleLE; never copy hex.
 
 /**
  * Build a protobuf field with double value
@@ -636,5 +630,4 @@ module.exports = {
   // Constants
   EFFECT_PARAMS,
   WIRE_TYPES,
-  DOUBLE_VALUES,
 };

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.104.2"
+VERSION = "2.104.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.104.2"
+VERSION = "2.104.4"
 
 import base64
 import os
@@ -5745,9 +5745,41 @@ def _timeline_set_title_text(tl, p: Dict[str, Any]) -> Dict[str, Any]:
                     "attempts": attempts,
                 }
 
+    # SetProperty exposes no title keys on every build (Text+ on Studio 19.1.3
+    # rejects all of them), while the item's Fusion comp carries the same text
+    # as the TextPlus tool's StyledText input and accepts writes there — the
+    # route get_title_text already reads. Deliberately a bare, UNLOCKED
+    # SetInput: the comp-lock render bug (api_truth / v2.98.5) eats writes
+    # wrapped in Comp.Lock(), and unlocked writes are the safe ones.
+    if not bool(p.get("as_styled_xml", p.get("styled", False))):
+        try:
+            if int(item.GetFusionCompCount() or 0) > 0:
+                comp = item.GetFusionCompByIndex(1)
+                tools = comp.GetToolList(False, "TextPlus") if comp else None
+                for tool_key in (tools or {}):
+                    tool = tools[tool_key]
+                    tool.SetInput("StyledText", text)
+                    confirmed = tool.GetInput("StyledText")
+                    rec = {"mode": "fusion_comp", "property_key": "StyledText",
+                           "success": confirmed == text}
+                    if confirmed != text:
+                        rec["readback"] = _ser(confirmed)
+                    attempts.append(rec)
+                    if confirmed == text:
+                        return {
+                            "success": True,
+                            "timeline_item_id": _safe_timeline_item_id(item),
+                            "property_key": "StyledText",
+                            "mode": "fusion_comp",
+                            "attempts": attempts,
+                        }
+        except Exception as exc:
+            attempts.append({"mode": "fusion_comp", "success": False, "error": str(exc)})
+
     return {
         "success": False,
-        "error": "SetProperty did not succeed; run title_property_scan, copy a real key from `properties`, "
+        "error": "SetProperty did not succeed and the Fusion-comp StyledText fallback found no "
+        "TextPlus tool to write; run title_property_scan, copy a real key from `properties`, "
         "and pass `property_key` (see `attempts` for diagnostics).",
         "attempts": attempts,
     }
@@ -18833,7 +18865,9 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         cross-checks the job's timeline items (which read back their real
         positions): items before the timeline start and a mark range far
         smaller than the item extent both warn. Pass expected_frames or
-        expected_duration_seconds when you know what the render should hold.
+        expected_duration_seconds when you know what the render should hold —
+        a DELIBERATE short render (single-frame capture, excerpt) reads as a
+        collapse warning unless the stated expectation matches the mark range.
         Verify BEFORE deleting the job; deleted jobs carry no TargetDir.
       start(job_ids?, interactive?) -> {success}
       stop() -> {success}
@@ -18971,7 +19005,28 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
                         "zero, issue #164). The items read back as placed; the "
                         "render is a stub."
                     )
+                caller_expected_frames = None
+                if p.get("expected_frames") is not None:
+                    try:
+                        caller_expected_frames = int(p["expected_frames"])
+                    except (TypeError, ValueError):
+                        caller_expected_frames = None
+                elif p.get("expected_duration_seconds") is not None and fps:
+                    try:
+                        caller_expected_frames = int(round(float(p["expected_duration_seconds"]) * fps))
+                    except (TypeError, ValueError):
+                        caller_expected_frames = None
+                # A caller who states the render SHOULD be this short (a
+                # deliberate single-frame or excerpt render) is not a collapse
+                # victim — the warning is for ranges Resolve rewrote, which the
+                # caller by definition did not expect.
+                intentional_short_range = (
+                    caller_expected_frames is not None
+                    and mark_frames is not None
+                    and abs(caller_expected_frames - mark_frames) <= 1
+                )
                 if (extent_lo is not None and mark_frames is not None
+                        and not intentional_short_range
                         and mark_frames < (extent_hi - extent_lo) * 0.5):
                     warnings.append(
                         f"The job's mark range ({mark_frames} frame(s)) is under "

package/src/utils/api_truth.py

@@ -1853,6 +1853,32 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "when mirroring keep-ranges into clipInfos.",
         "tags": ["timeline", "edit", "off-by-one", "readback"],
     },
+    {
+        "symbol": "MediaPool.ImportTimelineFromFile (internal sequence name overrides timelineName)",
+        "object": "MediaPool",
+        "signature": "(filePath, {timelineName, importSourceClips, ...}) -> Timeline",
+        "reality": "For FCP7 XML, the sequence name INSIDE the file wins over "
+                   "the timelineName import option. When the internal name "
+                   "matches an existing timeline, the call returns that "
+                   "EXISTING timeline — no error, no new timeline — so an "
+                   "export→edit→re-import loop keying uniqueness on the option "
+                   "'succeeds' while operating on one timeline forever "
+                   "(issue #171, Studio 21.0.4.5; wrapper behavior verified on "
+                   "19.1.3.7). Distinct from the documented repeated-"
+                   "timelineName None return: here the option is fresh and the "
+                   "file's name is stale.",
+        "recommended": "Rewrite the <sequence><name> inside the file to the "
+                       "intended name before importing — "
+                       "timeline.import_timeline_checked does this "
+                       "automatically for FCP7 XML and errors when a "
+                       "non-rewritable format still returns an existing "
+                       "timeline. Never treat a truthy return as proof of "
+                       "creation; check the returned timeline's id against "
+                       "the pre-import set.",
+        "tags": ["timeline", "import", "silent-failure", "unreliable-return"],
+        "submit": "bug",
+        "issue": 171,
+    },
     {
         "symbol": "MediaPool.AppendToTimeline clipInfo recordFrame (timeline-absolute origin)",
         "object": "MediaPool",