davinci-resolve-mcp 2.148.0 → 2.149.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 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.149.0 — subtitle render truth: ExportSubtitle lies on 19.x
+
+### Measured (new Resolve bug, filed in api-limitations)
+
+- **`SetRenderSettings` subtitle keys are accepted-and-inert on 19.x**: with
+  authored subtitle cues readback-verified and the track enabled,
+  `ExportSubtitle: true` + every `SubtitleFormat` mode (`BurnIn`,
+  `SeparateFile`, `EmbeddedCaptions`) returns True — and the renders carry no
+  burned-in pixels, no sidecar file, and no caption stream. The keys are
+  documented in the Resolve 21 API reference. Quirk: `ExportSubtitle` alone
+  returns False; the pair returns True.
+
+### Added
+
+- **`render.set_settings` warns on pre-21 hosts** when the subtitle-delivery
+  keys are set, naming the measured inertness and the verification steps —
+  the accepted-then-ignored warning pattern that already covers
+  `AddFrameHandles` under `UseFullExtents`.
+
 ## What's New in v2.148.0 — the audio ceiling doubles: A1–A16
 
 ### Changed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.148.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.149.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.148.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.149.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.148.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.149.0 版 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:** 35 missing capabilities, 48 bugs / unreliable behaviors.
+**Totals:** 35 missing capabilities, 49 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -687,3 +687,11 @@ values, or automation-hostile modal prompts.
 - **Behavior:** Timeline markers present and readable through the marker API do not appear in the exported .otio at all — the OTIO Marker schema exists and Resolve's importer reads it, but the exporter writes none (measured on Studio 19.1.3.7: two markers read back at frames 12/72; the export carried zero). Any marker-fidelity QC built on an OTIO re-export silently sees an unmarked timeline.
 - **Workaround / current handling:** Do not use EXPORT_OTIO to carry or verify markers. editorial.verify_roundtrip reports this case as `markersNotInExport` (honesty flag, not a failure); read markers through the marker API for fidelity checks, and author them offline via drt.assemble spec.markers when a .drt must carry them.
 - **Tags:** timeline, export, otio, markers, silent-failure
+
+### Project.SetRenderSettings ExportSubtitle/SubtitleFormat (inert on 19.x)
+
+- **Object:** `Project`
+- **Signature:** `({'ExportSubtitle': bool, 'SubtitleFormat': str}) -> bool`
+- **Behavior:** On Studio 19.1.3.7 the subtitle-delivery keys documented in the Resolve 21 API reference are accepted and fully inert: SetRenderSettings returns True for all three SubtitleFormat modes ('BurnIn', 'SeparateFile', 'EmbeddedCaptions'), and the renders carry no burned-in pixels (frame-extract verified), no sidecar subtitle file, and no embedded caption track (stream-probe verified) — with the subtitle cues readback-verified on the timeline and the subtitle track enabled. Quirk: ExportSubtitle alone returns False; the pair returns True. All three outputs are stream-identical to a no-subtitle render.
+- **Workaround / current handling:** Do not trust a True return for subtitle delivery on a pre-21 host — verify the output (extract a frame for burn-in, list the target directory for a sidecar, ffprobe streams for embedded captions). On 19.x subtitle export requires the UI render page. render.set_settings warns when these keys are set on a pre-21 host.
+- **Tags:** render, subtitle, burn-in, silent-failure, version-gated

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.148.0"
+VERSION = "2.149.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.148.0",
+  "version": "2.149.0",
   "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.148.0"
+VERSION = "2.149.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.148.0"
+VERSION = "2.149.0"
 
 import base64
 import os
@@ -18730,7 +18730,7 @@ def _render_preset_pin(proj, preset_name: str):
     return {"preset": preset_name, "loaded": True}, None
 
 
-def _render_settings_warnings(settings: Dict[str, Any]):
+def _render_settings_warnings(settings: Dict[str, Any], version_major: Optional[int] = None):
     """Inter-key combinations Resolve accepts and then silently ignores.
 
     SetRenderSettings returns True for these, so nothing downstream would ever
@@ -18745,6 +18745,17 @@ def _render_settings_warnings(settings: Dict[str, Any]):
             "AddFrameHandles is ignored while UseFullExtents is true: Resolve renders the "
             "clip's full extents and the handle count silently does nothing. Drop one of the two."
         )
+    if ("ExportSubtitle" in settings or "SubtitleFormat" in settings) and (
+        version_major is not None and version_major < 21
+    ):
+        warnings.append(
+            "ExportSubtitle/SubtitleFormat are INERT on this Resolve generation: measured on "
+            "Studio 19.1.3.7, SetRenderSettings returns True for all three SubtitleFormat modes "
+            "and the render carries no burn-in, no sidecar file, and no embedded caption track "
+            "(cues readback-verified, subtitle track enabled). The keys are documented in the "
+            "Resolve 21 API reference. Verify the output (frame extract / sidecar check) before "
+            "claiming caption delivery; on 19.x burn-in requires the UI render page."
+        )
     return warnings
 
 
@@ -19283,6 +19294,12 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         "Same as project", or "None"). AddFrameHandles is ignored while
         UseFullExtents is true — the call still succeeds, so that pairing
         comes back in warnings rather than silently doing nothing.
+        ExportSubtitle (bool) + SubtitleFormat ("BurnIn" | "SeparateFile" |
+        "EmbeddedCaptions") are documented for Resolve 21 but measured INERT
+        on 19.x — SetRenderSettings returns True and the render carries no
+        burn-in, sidecar, or caption track — so setting them on a pre-21
+        host comes back in warnings; verify the output before claiming
+        caption delivery.
       list_presets() -> {presets}
       load_preset(name) -> {success}
       save_preset(name) -> {success}
@@ -19577,8 +19594,12 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         if ignored_settings:
             result["ignored_settings"] = ignored_settings
         # Accepted-then-ignored key combinations (21.0.4 AddFrameHandles under
-        # UseFullExtents) read as a clean success without this.
-        warnings = _render_settings_warnings(settings)
+        # UseFullExtents; 19.x ExportSubtitle) read as a clean success without this.
+        try:
+            _ver_major = int((get_resolve().GetVersion() or [0])[0])
+        except Exception:
+            _ver_major = None
+        warnings = _render_settings_warnings(settings, version_major=_ver_major)
         if warnings:
             result["warnings"] = warnings
         return result

package/src/utils/api_truth.py

@@ -2737,6 +2737,33 @@ API_TRUTH: List[Dict[str, Any]] = [
         "submit": "bug",
         "mitigation": ["editorial.verify_roundtrip markersNotInExport"],
     },
+    {
+        "symbol": "Project.SetRenderSettings ExportSubtitle/SubtitleFormat (inert on 19.x)",
+        "object": "Project",
+        "signature": "({'ExportSubtitle': bool, 'SubtitleFormat': str}) -> bool",
+        "reality": "On Studio 19.1.3.7 the subtitle-delivery keys documented "
+                   "in the Resolve 21 API reference are accepted and fully "
+                   "inert: SetRenderSettings returns True for all three "
+                   "SubtitleFormat modes ('BurnIn', 'SeparateFile', "
+                   "'EmbeddedCaptions'), and the renders carry no burned-in "
+                   "pixels (frame-extract verified), no sidecar subtitle "
+                   "file, and no embedded caption track (stream-probe "
+                   "verified) — with the subtitle cues readback-verified on "
+                   "the timeline and the subtitle track enabled. Quirk: "
+                   "ExportSubtitle alone returns False; the pair returns "
+                   "True. All three outputs are stream-identical to a "
+                   "no-subtitle render.",
+        "recommended": "Do not trust a True return for subtitle delivery on "
+                       "a pre-21 host — verify the output (extract a frame "
+                       "for burn-in, list the target directory for a "
+                       "sidecar, ffprobe streams for embedded captions). On "
+                       "19.x subtitle export requires the UI render page. "
+                       "render.set_settings warns when these keys are set on "
+                       "a pre-21 host.",
+        "tags": ["render", "subtitle", "burn-in", "silent-failure", "version-gated"],
+        "submit": "bug",
+        "mitigation": ["render.set_settings warnings"],
+    },
 ]