davinci-resolve-mcp 2.57.4 → 2.57.5

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 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.57.5
+
+Fixes a silent data-loss bug on Reel Name writes (issue #77) and bundles the
+community-contributed API-limitation entries from PR #76 (issue #75).
+
+- **Fixed** (#77) `set_clip_property` / `set_metadata` reporting `success: true`
+  when writing the `Reel Name` clip property even though Resolve silently
+  dropped the value. Resolve gates `Reel Name` behind the project setting
+  *General Options > Assist using reel names from the:* — when that derives reel
+  names automatically, scripted writes are ignored but still return `True`. On a
+  batch ingest this meant hundreds of clips believed to have reel names assigned
+  when none actually stuck. The server now reads the value back after writing
+  known-unreliable keys and refuses to report success on mismatch, surfacing the
+  project-setting gate as a `hint`. Wired into `set_clip_property`,
+  `set_metadata` (both forms), and the bulk `normalize_metadata` path. Adds an
+  `api_truth` bug entry (report now lists 18 missing + 11 bugs) and 10 unit
+  tests.
+- **Added** (PR #76, thanks @swayll) four `submit: missing` API-limitation
+  entries verified on Resolve 21.0.0: per-subtitle text/timing editing, subtitle
+  track styling/presets, speech-recognition engine selection + SRT import, and
+  Media Pool folder rename. These document the API ceiling behind the subtitle
+  feature request in #75 — direct subtitle text editing and SRT round-trip are
+  not exposed by the Blackmagic scripting API.
+
+### Validation
+
+- Offline: full unit suite green; new `tests/test_reel_name_writeback.py` (10
+  tests) plus the api_truth/limitations drift guards. Live Resolve validation of
+  the Reel Name read-back is recommended but not performed here — forcing the
+  gate would require writing reel names into a live project's media metadata.
+
 ## What's New in v2.57.4
 
 Live mutating verification of the catalogued API gaps.

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.57.4-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.57.5-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(341%20full)-blue.svg)](#server-modes)

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.0
 
-**Totals:** 14 missing capabilities, 10 bugs / unreliable behaviors.
+**Totals:** 18 missing capabilities, 11 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -141,6 +141,34 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** Create Smart/Power Bins in the Resolve UI; only regular bins are scriptable.
 - **Tags:** missing-method, media-pool, bins
 
+### Per-subtitle text content and timing editing
+
+- **Object:** `TimelineItem (subtitle track)`
+- **Behavior:** TimelineItem on a subtitle track exposes only 21 standard transform/composite properties (Pan, Tilt, ZoomX, Opacity, Crop, etc.). There are no methods to get or set subtitle text (GetText/SetText), start time, end time, or duration for individual subtitle items. Subtitles created via CreateSubtitlesFromAudio or imported via the Resolve UI cannot have their content or timing read or modified programmatically. Verified via dir() and GetProperty() on Resolve 21.0.0.48.
+- **Workaround / current handling:** No workaround exists — subtitle text and timing are completely inaccessible from the scripting API. Must be edited in the Resolve UI.
+- **Tags:** missing-method, subtitle, text, timing
+
+### Subtitle track styling and presets
+
+- **Object:** `TimelineItem / Timeline / Project`
+- **Behavior:** There is no API method to set or query subtitle font family, font size, text color, background color, outline, shadow, position, alignment, or to apply/query subtitle style presets. TimelineItem.GetProperty() on subtitle items returns only transform/composite keys. Timeline.GetSetting() and Project.GetSetting() return None for all probed subtitle-style keys (e.g. 'subtitleFontName', 'subtitleFontSize', 'subtitleTextColor', 'subtitleBackgroundColor', 'subtitlePosition', 'subtitleAlignment', 'subtitlePreset', 'subtitleStyle'). Verified via dir(), GetProperty(), and GetSetting() on Resolve 21.0.0.48.
+- **Workaround / current handling:** No workaround exists — subtitle styling is UI-only. Burn-in overlays via Fusion titles are a visual alternative but do not produce proper subtitle tracks.
+- **Tags:** missing-method, subtitle, style, preset
+
+### Speech recognition engine selection and SRT import
+
+- **Object:** `Timeline`
+- **Behavior:** Timeline.CreateSubtitlesFromAudio(autoCaptionSettings) always uses the built-in Resolve speech recognition engine. There is no API parameter to select an alternative provider (e.g. whisper-cli, Google Speech, AWS Transcribe). The language selection via resolve.AUTO_CAPTION_LANGUAGE_* is the only customization; the engine itself cannot be changed. Furthermore, there is no API method to import an SRT file into a subtitle track programmatically — File -> Import -> Subtitle is UI-only.
+- **Workaround / current handling:** No workaround exists for provider selection or SRT import. External transcripts must be converted to SRT and imported through the Resolve UI.
+- **Tags:** missing-method, subtitle, transcription, speech-recognition, asr
+
+### Media Pool folder rename
+
+- **Object:** `MediaPool`
+- **Behavior:** MediaPool exposes AddSubFolder(name), DeleteSubFolders([names]), and MoveFolders([names], targetFolder) but no RenameSubFolder(oldName, newName) method. Folders can be created, deleted, and moved, but their names cannot be changed through the API. Verified via dir() on Resolve 21.0.0.
+- **Workaround / current handling:** Delete and recreate the folder with the desired name, or rename in the Resolve UI.
+- **Tags:** missing-method, media-pool, folder
+
 ## Bugs / Unreliable Behavior (please fix)
 
 Methods that exist but misbehave — silent failures, unreliable return
@@ -220,3 +248,12 @@ values, or automation-hostile modal prompts.
 - **Behavior:** The Python bridge returns a callable for ANY attribute name, so hasattr(obj, 'TotallyMadeUpMethod') is always True and getattr never raises. This makes capability detection by hasattr impossible — verified on 21.0.0 (hasattr reported SetStart, Razor, AddNode, GenerateProxy, AddSmartBin etc. as present though none exist). Only dir() lists the real methods.
 - **Workaround / current handling:** Never probe method existence with hasattr/getattr; test membership against dir(obj) instead. Calling a fabricated method typically returns None/False with no error.
 - **Tags:** bridge, introspection, silent-failure
+
+### MediaPoolItem.SetClipProperty('Reel Name', ...)
+
+- **Object:** `MediaPoolItem`
+- **Signature:** `(propertyName, propertyValue) -> bool`
+- **Behavior:** Setting the 'Reel Name' clip property returns True but the value is silently dropped on read-back when the project is configured to derive reel names automatically (General Options > 'Assist using reel names from the:' set to source clip file / embedding / filename pattern). The same True-but-unpersisted behavior occurs via SetMetadata('Reel Name', ...). Other clip properties on the same clip (e.g. 'Comments') write and persist normally, so this is field-specific, not a bridge/permission failure. Verified on Resolve 21.0.0; reported as issue #77.
+- **Workaround / current handling:** After writing 'Reel Name', read it back with GetClipProperty('Reel Name') and refuse to report success on mismatch; surface the project-setting gate to the caller (server._verify_clip_property_writeback).
+- **Reference:** [issue #77](https://github.com/samuelgursky/davinci-resolve-mcp/issues/77)
+- **Tags:** unreliable-return, silent-failure, metadata, reel-name

package/install.py

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

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.57.4"
+VERSION = "2.57.5"
 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 341-tool granular server instead
 """
 
-VERSION = "2.57.4"
+VERSION = "2.57.5"
 
 import base64
 import os
@@ -6559,6 +6559,78 @@ def _safe_clip_call(clip, method_name: str, *args):
         return None, str(exc)
 
 
+# Clip-property keys whose SetClipProperty/SetMetadata write returns True but is
+# silently dropped by Resolve under common project configurations (issue #77).
+# For these we read the value back and refuse to report success unless it stuck.
+_WRITEBACK_VERIFY_KEYS = frozenset({"Reel Name"})
+
+# Per-key hint explaining the most common cause of a non-persisting write.
+_WRITEBACK_VERIFY_HINTS = {
+    "Reel Name": (
+        "Reel Name is commonly gated by the project setting "
+        "'General Options > Assist using reel names from the:'. When that is "
+        "set to derive reel names from the source clip / embedding / filename "
+        "pattern, Resolve ignores scripted writes to 'Reel Name' (the call "
+        "still returns True). Set that option to blank/manual, or assign reel "
+        "names in the Resolve UI; the scripting API cannot override the gate."
+    ),
+}
+
+
+def _normalize_clip_property_value(value):
+    """Coerce a clip-property value to a comparable, trimmed string."""
+    if value is None:
+        return ""
+    return str(value).strip()
+
+
+def _verify_clip_property_writeback(clip, key, value):
+    """Confirm a just-written, known-unreliable clip property actually persisted.
+
+    Returns a structured failure dict when Resolve accepted the write (returned
+    True) but the value did not stick on read-back; returns ``None`` when the
+    write verified, the key is not in the watch list, or we cannot read it back
+    (in which case we don't override the original success). See issue #77.
+    """
+    if key not in _WRITEBACK_VERIFY_KEYS:
+        return None
+    actual, err = _safe_clip_call(clip, "GetClipProperty", key)
+    if err is not None:
+        return None  # can't read back — don't contradict the reported result
+    if isinstance(actual, dict):  # GetClipProperty('') style dict, just in case
+        actual = actual.get(key)
+    if _normalize_clip_property_value(actual) == _normalize_clip_property_value(value):
+        return None
+    return {
+        "success": False,
+        "verified": False,
+        "key": key,
+        "requested": value,
+        "actual": actual,
+        "error": (
+            f"Resolve reported success writing {key!r} but the value did not "
+            f"persist (read-back returned {actual!r})."
+        ),
+        "hint": _WRITEBACK_VERIFY_HINTS.get(key),
+    }
+
+
+def _verify_writeback(clip, written):
+    """Verify a batch of just-written {key: value} pairs.
+
+    Returns the first silent-revert failure dict, else ``None``. Only keys in
+    ``_WRITEBACK_VERIFY_KEYS`` are checked, so ordinary writes pay nothing.
+    """
+    if not isinstance(written, dict):
+        return None
+    for key, value in written.items():
+        if key in _WRITEBACK_VERIFY_KEYS:
+            fail = _verify_clip_property_writeback(clip, key, value)
+            if fail:
+                return fail
+    return None
+
+
 def _media_pool_item_summary(clip):
     if not clip:
         return None
@@ -10213,7 +10285,17 @@ def _normalize_metadata(root, mp, p: Dict[str, Any]):
         third_party_ok = True
         for key, value in third_party.items():
             third_party_ok = bool(clip.SetThirdPartyMetadata(key, value)) and third_party_ok
-        results.append({"clip_id": clip_id, "success": ok and third_party_ok})
+        row = {"clip_id": clip_id, "success": ok and third_party_ok}
+        if ok and metadata:
+            silent = _verify_writeback(clip, metadata)
+            if silent:
+                row["success"] = False
+                row["verified"] = False
+                row["unpersisted"] = {silent["key"]: silent["actual"]}
+                row["error"] = silent["error"]
+                if silent.get("hint"):
+                    row["hint"] = silent["hint"]
+        results.append(row)
     return {"success": all(row.get("success") for row in results), "count": len(results), "missing": missing, "results": results}
 
 
@@ -15696,8 +15778,18 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         return {"metadata": _ser(clip.GetMetadata(p.get("key", "")))}
     elif action == "set_metadata":
         if "metadata" in p:
-            return {"success": bool(clip.SetMetadata(p["metadata"]))}
-        return {"success": bool(clip.SetMetadata(p["key"], p["value"]))}
+            ok = bool(clip.SetMetadata(p["metadata"]))
+            if ok:
+                silent = _verify_writeback(clip, p["metadata"])
+                if silent:
+                    return silent
+            return {"success": ok}
+        ok = bool(clip.SetMetadata(p["key"], p["value"]))
+        if ok:
+            silent = _verify_clip_property_writeback(clip, p["key"], p["value"])
+            if silent:
+                return silent
+        return {"success": ok}
     elif action == "get_third_party_metadata":
         return {"metadata": _ser(clip.GetThirdPartyMetadata(p.get("key", "")))}
     elif action == "set_third_party_metadata":
@@ -15707,7 +15799,12 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     elif action == "get_clip_property":
         return {"properties": _ser(clip.GetClipProperty(p.get("key", "")))}
     elif action == "set_clip_property":
-        return {"success": bool(clip.SetClipProperty(p["key"], p["value"]))}
+        ok = bool(clip.SetClipProperty(p["key"], p["value"]))
+        if ok:
+            silent = _verify_clip_property_writeback(clip, p["key"], p["value"])
+            if silent:
+                return silent
+        return {"success": ok}
     elif action == "get_clip_color":
         return {"color": clip.GetClipColor()}
     elif action == "set_clip_color":

package/src/utils/api_truth.py

@@ -366,6 +366,79 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["missing-method", "media-pool", "bins"],
         "submit": "missing",
     },
+    {
+        "symbol": "Per-subtitle text content and timing editing",
+        "object": "TimelineItem (subtitle track)",
+        "reality": "TimelineItem on a subtitle track exposes only 21 standard "
+                   "transform/composite properties (Pan, Tilt, ZoomX, Opacity, "
+                   "Crop, etc.). There are no methods to get or set subtitle "
+                   "text (GetText/SetText), start time, end time, or duration "
+                   "for individual subtitle items. Subtitles created via "
+                   "CreateSubtitlesFromAudio or imported via the Resolve UI "
+                   "cannot have their content or timing read or modified "
+                   "programmatically. Verified via dir() and GetProperty() on "
+                   "Resolve 21.0.0.48.",
+        "recommended": "No workaround exists — subtitle text and timing are "
+                       "completely inaccessible from the scripting API. Must "
+                       "be edited in the Resolve UI.",
+        "tags": ["missing-method", "subtitle", "text", "timing"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Subtitle track styling and presets",
+        "object": "TimelineItem / Timeline / Project",
+        "reality": "There is no API method to set or query subtitle font "
+                   "family, font size, text color, background color, outline, "
+                   "shadow, position, alignment, or to apply/query subtitle "
+                   "style presets. TimelineItem.GetProperty() on subtitle "
+                   "items returns only transform/composite keys. "
+                   "Timeline.GetSetting() and Project.GetSetting() return "
+                   "None for all probed subtitle-style keys (e.g. "
+                   "'subtitleFontName', 'subtitleFontSize', "
+                   "'subtitleTextColor', 'subtitleBackgroundColor', "
+                   "'subtitlePosition', 'subtitleAlignment', "
+                   "'subtitlePreset', 'subtitleStyle'). Verified via dir(), "
+                   "GetProperty(), and GetSetting() on Resolve 21.0.0.48.",
+        "recommended": "No workaround exists — subtitle styling is UI-only. "
+                       "Burn-in overlays via Fusion titles are a visual "
+                       "alternative but do not produce proper subtitle tracks.",
+        "tags": ["missing-method", "subtitle", "style", "preset"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Speech recognition engine selection and SRT import",
+        "object": "Timeline",
+        "reality": "Timeline.CreateSubtitlesFromAudio(autoCaptionSettings) "
+                   "always uses the built-in Resolve speech recognition "
+                   "engine. There is no API parameter to select an alternative "
+                   "provider (e.g. whisper-cli, Google Speech, AWS Transcribe). "
+                   "The language selection via resolve.AUTO_CAPTION_LANGUAGE_* "
+                   "is the only customization; the engine itself cannot be "
+                   "changed. Furthermore, there is no API method to import an "
+                   "SRT file into a subtitle track programmatically — "
+                   "File -> Import -> Subtitle is UI-only.",
+        "recommended": "No workaround exists for provider selection or SRT "
+                       "import. External transcripts must be converted to SRT "
+                       "and imported through the Resolve UI.",
+        "tags": ["missing-method", "subtitle", "transcription",
+                 "speech-recognition", "asr"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Media Pool folder rename",
+        "object": "MediaPool",
+        "reality": "MediaPool exposes AddSubFolder(name), "
+                   "DeleteSubFolders([names]), and "
+                   "MoveFolders([names], targetFolder) but no "
+                   "RenameSubFolder(oldName, newName) method. Folders can be "
+                   "created, deleted, and moved, but their names cannot be "
+                   "changed through the API. Verified via dir() on Resolve "
+                   "21.0.0.",
+        "recommended": "Delete and recreate the folder with the desired name, "
+                       "or rename in the Resolve UI.",
+        "tags": ["missing-method", "media-pool", "folder"],
+        "submit": "missing",
+    },
     {
         "symbol": "hasattr() / getattr() on Resolve API objects (attribute fabrication)",
         "object": "(all Resolve scripting objects)",
@@ -391,6 +464,29 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "run while serving over stdio.",
         "tags": ["runtime", "stdio", "subprocess"],
     },
+    {
+        "symbol": "MediaPoolItem.SetClipProperty('Reel Name', ...)",
+        "object": "MediaPoolItem",
+        "signature": "(propertyName, propertyValue) -> bool",
+        "reality": "Setting the 'Reel Name' clip property returns True but the "
+                   "value is silently dropped on read-back when the project is "
+                   "configured to derive reel names automatically "
+                   "(General Options > 'Assist using reel names from the:' set "
+                   "to source clip file / embedding / filename pattern). The "
+                   "same True-but-unpersisted behavior occurs via "
+                   "SetMetadata('Reel Name', ...). Other clip properties on the "
+                   "same clip (e.g. 'Comments') write and persist normally, so "
+                   "this is field-specific, not a bridge/permission failure. "
+                   "Verified on Resolve 21.0.0; reported as issue #77.",
+        "recommended": "After writing 'Reel Name', read it back with "
+                       "GetClipProperty('Reel Name') and refuse to report "
+                       "success on mismatch; surface the project-setting gate to "
+                       "the caller (server._verify_clip_property_writeback).",
+        "tags": ["unreliable-return", "silent-failure", "metadata", "reel-name"],
+        "submit": "bug",
+        "issue": 77,
+        "mitigation": ["_verify_clip_property_writeback", "_verify_writeback"],
+    },
 ]