davinci-resolve-mcp 2.53.0 → 2.54.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 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.54.0
+
+Hardens the rest of the enum-keyed settings APIs against the same silent-failure
+class fixed for `AutoSyncAudio` in v2.53.0 (issue #70). Several Resolve methods
+key their settings dict by `resolve.<CONST>` enum attributes and silently reject
+the whole call when handed plain string keys — returning `False`/`None` with
+nothing applied and no error.
+
+- **Fixed** `CreateSubtitlesFromAudio` (both `timeline_ai.create_subtitles` and
+  `timeline.subtitle_generation_probe`) now resolves human-readable
+  `autoCaptionSettings` — `language`, `preset`, `line_break`, `chars_per_line`,
+  `gap` — into live `SUBTITLE_*`/`AUTO_CAPTION_*` enum keys/values. Unknown keys
+  and unresolvable values are dropped and reported in `ignored_settings` instead
+  of poisoning the call, and generation is read-back verified against the
+  timeline's subtitle track count (the boolean return is unreliable).
+- **Fixed** the `ProjectManager` CloudProject family (`create`/`load`/
+  `import_project`/`restore`) resolves `{cloudSettings}` into live
+  `CLOUD_SETTING_*`/`CLOUD_SYNC_*` enums (`project_name`, `media_path`,
+  `is_collab`, `sync_mode`, `is_camera_access`), dropping unknown keys into
+  `ignored_settings`.
+- **Changed** the string→enum resolution is now a shared `_resolve_enum_settings`
+  primitive driven by per-field specs, so the next enum-keyed API gets the same
+  treatment without re-implementing it.
+- **Added** `api_truth` entries for `Timeline.CreateSubtitlesFromAudio` and the
+  CloudProject family, documenting the silent-rejection + unreliable-return
+  behavior alongside the existing `AutoSyncAudio` entry.
+
 ## What's New in v2.53.0
 
 Two improvements to audio sync reliability and inventory control.

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.53.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.54.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-34%20(341%20full)-blue.svg)](#server-modes)
@@ -163,3 +163,8 @@ Samuel Gursky (samgursky@gmail.com)
 - Blackmagic Design for DaVinci Resolve and its scripting API
 - The Model Context Protocol team for enabling AI assistant integration
 - Anthropic for Claude Code, used extensively in development and testing
+
+### Community contributions
+
+- [@rgxdev](https://github.com/rgxdev) — configurable Media Pool inventory walk
+  (exclude bins + inventory limit), [#69](https://github.com/samuelgursky/davinci-resolve-mcp/pull/69) (v2.53.0)

package/docs/SKILL.md

@@ -1005,7 +1005,12 @@ helpers:
   Unrecognized keys are dropped and echoed back in `ignored_settings` rather than
   silently failing the call.
 - `transcription_capabilities(clip_ids?|selected?)`
-- `subtitle_generation_probe(settings?, allow_generate?)`
+- `subtitle_generation_probe(settings?, allow_generate?)` — `settings` accepts
+  human-readable keys resolved to live `SUBTITLE_*`/`AUTO_CAPTION_*` enums:
+  `language` (e.g. `english`, `korean`), `preset` (`default`|`teletext`|`netflix`),
+  `line_break` (`single`|`double`), `chars_per_line` (1–60), `gap` (0–10).
+  Unrecognized keys/values are dropped and echoed in `ignored_settings`; generation
+  is read-back verified against the subtitle track count.
 - `fairlight_boundary_report`
 
 **`timeline_markers`** — Markers and playhead on the current timeline.
@@ -1036,7 +1041,9 @@ file to disk.
 
 **`timeline_ai`** — AI/ML analysis on the current timeline.
 
-Key actions: `create_subtitles(settings?)`, `detect_scene_cuts`,
+Key actions: `create_subtitles(settings?)` (human-readable settings resolved to
+`SUBTITLE_*`/`AUTO_CAPTION_*` enums + read-back verified — see
+`subtitle_generation_probe`), `detect_scene_cuts`,
 `grab_still`, `grab_all_stills(source?)`, `analyze_dolby_vision`
 
 ---

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.53.0"
+VERSION = "2.54.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.53.0",
+  "version": "2.54.0",
   "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.53.0"
+VERSION = "2.54.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 341-tool granular server instead
 """
 
-VERSION = "2.53.0"
+VERSION = "2.54.0"
 
 import base64
 import os
@@ -6040,6 +6040,182 @@ def _normalize_auto_sync_settings(settings: Dict[str, Any], resolve_obj=None):
     return normalized, ignored
 
 
+def _resolve_enum_settings(resolve_obj, settings, field_specs):
+    """Resolve a human-readable settings dict into the live enum-keyed dict that
+    enum-keyed Resolve APIs require.
+
+    Several Resolve methods (``MediaPool.AutoSyncAudio``,
+    ``Timeline.CreateSubtitlesFromAudio``, the ``ProjectManager`` CloudProject
+    family) key their settings dict by ``resolve.<CONST>`` enum attributes — and
+    for many fields expect ``resolve.<CONST>`` enum *values* too. They silently
+    reject the WHOLE call when handed a plain string key (returning False/None
+    with nothing applied), so unrecognized keys must be dropped, not forwarded.
+    See utils/api_truth.py for the catalogued symbols.
+
+    ``field_specs`` is an iterable of dicts, one per supported field:
+      ``aliases``   human keys accepted for this field (case-insensitive)
+      ``key_const`` name of the ``resolve`` enum attribute used as the dict key
+      ``key_fallback`` key used when the live handle can't resolve ``key_const``
+                    (defaults to ``key_const``); keeps offline behavior readable
+      ``values``    optional ``{lowercased_str: enum_const_name}`` value map
+      ``coerce``    optional ``"int"`` | ``"bool"`` cast for plain values
+      ``bounds``    optional ``(min, max)`` clamp applied after int coercion
+
+    Returns ``(normalized, ignored)``. ``ignored`` lists input keys that no spec
+    claimed AND recognized keys whose value could not be resolved (sorted) — so a
+    field that silently fails to apply is reported rather than hidden.
+    """
+    if not settings:
+        return {}, []
+    normalized = {}
+    consumed = set()
+    lower = {str(k).strip().lower(): k for k in settings}
+
+    for spec in field_specs:
+        src_key = next((lower[a.lower()] for a in spec["aliases"] if a.lower() in lower), None)
+        if src_key is None:
+            continue
+        raw = settings[src_key]
+        key = _resolve_audio_constant(resolve_obj, spec["key_const"], spec.get("key_fallback", spec["key_const"]))
+        values_map = spec.get("values")
+        if values_map is not None and isinstance(raw, str):
+            const_name = values_map.get(raw.strip().lower())
+            if const_name is None:
+                continue  # unknown enum value — leave src_key unconsumed -> ignored
+            value = _resolve_audio_constant(resolve_obj, const_name, raw)
+        elif spec.get("coerce") == "int":
+            try:
+                value = int(raw) if not isinstance(raw, bool) else int(raw)
+            except (TypeError, ValueError):
+                continue
+            lo, hi = spec.get("bounds", (None, None))
+            if lo is not None:
+                value = max(lo, value)
+            if hi is not None:
+                value = min(hi, value)
+        elif spec.get("coerce") == "bool":
+            value = bool(raw)
+        else:
+            value = raw
+        normalized[key] = value
+        consumed.add(src_key)
+
+    ignored = sorted(str(key) for key in settings if key not in consumed)
+    return normalized, ignored
+
+
+# Timeline.CreateSubtitlesFromAudio({autoCaptionSettings}) — enum-keyed exactly
+# like AutoSyncAudio (docs/reference/resolve_scripting_api.txt lines 733-771).
+_AUTO_CAPTION_LANGUAGES = {
+    "auto": "AUTO_CAPTION_AUTO",
+    "danish": "AUTO_CAPTION_DANISH",
+    "dutch": "AUTO_CAPTION_DUTCH",
+    "english": "AUTO_CAPTION_ENGLISH",
+    "french": "AUTO_CAPTION_FRENCH",
+    "german": "AUTO_CAPTION_GERMAN",
+    "italian": "AUTO_CAPTION_ITALIAN",
+    "japanese": "AUTO_CAPTION_JAPANESE",
+    "korean": "AUTO_CAPTION_KOREAN",
+    "mandarin_simplified": "AUTO_CAPTION_MANDARIN_SIMPLIFIED",
+    "mandarin_traditional": "AUTO_CAPTION_MANDARIN_TRADITIONAL",
+    "norwegian": "AUTO_CAPTION_NORWEGIAN",
+    "portuguese": "AUTO_CAPTION_PORTUGUESE",
+    "russian": "AUTO_CAPTION_RUSSIAN",
+    "spanish": "AUTO_CAPTION_SPANISH",
+    "swedish": "AUTO_CAPTION_SWEDISH",
+}
+_AUTO_CAPTION_PRESETS = {
+    "default": "AUTO_CAPTION_SUBTITLE_DEFAULT",
+    "subtitle_default": "AUTO_CAPTION_SUBTITLE_DEFAULT",
+    "teletext": "AUTO_CAPTION_TELETEXT",
+    "netflix": "AUTO_CAPTION_NETFLIX",
+}
+_AUTO_CAPTION_LINE_BREAKS = {
+    "single": "AUTO_CAPTION_LINE_SINGLE",
+    "double": "AUTO_CAPTION_LINE_DOUBLE",
+}
+_AUTO_CAPTION_FIELD_SPECS = (
+    {"aliases": ["language", "lang", "SUBTITLE_LANGUAGE"], "key_const": "SUBTITLE_LANGUAGE", "key_fallback": "language", "values": _AUTO_CAPTION_LANGUAGES},
+    {"aliases": ["preset", "caption_preset", "SUBTITLE_CAPTION_PRESET"], "key_const": "SUBTITLE_CAPTION_PRESET", "key_fallback": "captionPreset", "values": _AUTO_CAPTION_PRESETS},
+    {"aliases": ["line_break", "linebreak", "SUBTITLE_LINE_BREAK"], "key_const": "SUBTITLE_LINE_BREAK", "key_fallback": "lineBreak", "values": _AUTO_CAPTION_LINE_BREAKS},
+    {"aliases": ["chars_per_line", "charsperline", "SUBTITLE_CHARS_PER_LINE"], "key_const": "SUBTITLE_CHARS_PER_LINE", "key_fallback": "charsPerLine", "coerce": "int", "bounds": (1, 60)},
+    {"aliases": ["gap", "SUBTITLE_GAP"], "key_const": "SUBTITLE_GAP", "key_fallback": "gap", "coerce": "int", "bounds": (0, 10)},
+)
+
+
+def _normalize_auto_caption_settings(settings, resolve_obj=None):
+    """Translate human-readable subtitle settings (e.g. ``{"language": "korean"}``)
+    into live ``SUBTITLE_*``/``AUTO_CAPTION_*`` enum keys/values for
+    ``CreateSubtitlesFromAudio``. Returns ``(normalized, ignored)``."""
+    return _resolve_enum_settings(resolve_obj, dict(settings or {}), _AUTO_CAPTION_FIELD_SPECS)
+
+
+# ProjectManager CloudProject family — {cloudSettings} is keyed by
+# resolve.CLOUD_SETTING_* constants with resolve.CLOUD_SYNC_* sync-mode values
+# (docs/reference/resolve_scripting_api.txt lines 588-603). Same silent-rejection
+# failure mode as AutoSyncAudio when handed plain string keys.
+_CLOUD_SYNC_MODES = {
+    "none": "CLOUD_SYNC_NONE",
+    "proxy_only": "CLOUD_SYNC_PROXY_ONLY",
+    "proxy": "CLOUD_SYNC_PROXY_ONLY",
+    "proxy_and_orig": "CLOUD_SYNC_PROXY_AND_ORIG",
+    "proxy_and_original": "CLOUD_SYNC_PROXY_AND_ORIG",
+}
+_CLOUD_SETTINGS_FIELD_SPECS = (
+    {"aliases": ["project_name", "name", "CLOUD_SETTING_PROJECT_NAME"], "key_const": "CLOUD_SETTING_PROJECT_NAME", "key_fallback": "projectName"},
+    {"aliases": ["project_media_path", "media_path", "CLOUD_SETTING_PROJECT_MEDIA_PATH"], "key_const": "CLOUD_SETTING_PROJECT_MEDIA_PATH", "key_fallback": "projectMediaPath"},
+    {"aliases": ["is_collab", "collab", "CLOUD_SETTING_IS_COLLAB"], "key_const": "CLOUD_SETTING_IS_COLLAB", "key_fallback": "isCollab", "coerce": "bool"},
+    {"aliases": ["sync_mode", "syncmode", "CLOUD_SETTING_SYNC_MODE"], "key_const": "CLOUD_SETTING_SYNC_MODE", "key_fallback": "syncMode", "values": _CLOUD_SYNC_MODES},
+    {"aliases": ["is_camera_access", "camera_access", "CLOUD_SETTING_IS_CAMERA_ACCESS"], "key_const": "CLOUD_SETTING_IS_CAMERA_ACCESS", "key_fallback": "isCameraAccess", "coerce": "bool"},
+)
+
+
+def _normalize_cloud_settings(settings, resolve_obj=None):
+    """Translate human-readable cloud-project settings (e.g.
+    ``{"project_name": "X", "sync_mode": "proxy_only"}``) into live
+    ``CLOUD_SETTING_*``/``CLOUD_SYNC_*`` enum keys/values. Returns
+    ``(normalized, ignored)``."""
+    return _resolve_enum_settings(resolve_obj, dict(settings or {}), _CLOUD_SETTINGS_FIELD_SPECS)
+
+
+def _safe_create_subtitles(tl, p: Dict[str, Any]):
+    """CreateSubtitlesFromAudio with enum-resolved settings + readback.
+
+    The raw boolean is unreliable (like AutoSyncAudio), so we verify by reading
+    the timeline's subtitle track count before/after and report the real delta.
+    """
+    settings, ignored = _normalize_auto_caption_settings(p.get("settings"), get_resolve())
+    if p.get("dry_run", False):
+        return _ok(would_create_subtitles=True, settings=settings, ignored_settings=ignored)
+
+    def _subtitle_track_count():
+        try:
+            return int(tl.GetTrackCount("subtitle") or 0)
+        except Exception:
+            return 0
+
+    res = verify_by_readback(
+        mutate=lambda: tl.CreateSubtitlesFromAudio(settings),
+        observe=_subtitle_track_count,
+        snapshot=_subtitle_track_count,
+        compare=lambda before, after: {
+            "verified": bool((after or 0) > (before or 0)),
+            "subtitle_tracks_before": before,
+            "subtitle_tracks_after": after,
+        },
+        label="create_subtitles_from_audio",
+        intent={"settings_keys": sorted(settings.keys()) if settings else []},
+    )
+    return {
+        "success": res["success_raw"],
+        "verified": res["verified"],
+        "subtitle_tracks_before": res.get("subtitle_tracks_before"),
+        "subtitle_tracks_after": res.get("subtitle_tracks_after"),
+        "settings": settings,
+        "ignored_settings": ignored,
+    }
+
+
 def _transcription_capabilities(mp, p: Dict[str, Any]):
     root = mp.GetRootFolder()
     clips = []
@@ -6085,13 +6261,14 @@ def _transcription_capabilities(mp, p: Dict[str, Any]):
 
 
 def _subtitle_generation_probe(tl, p: Dict[str, Any]):
-    settings = dict(p.get("settings") or {})
+    settings, ignored = _normalize_auto_caption_settings(p.get("settings"), get_resolve())
     if not p.get("allow_generate", False):
-        return _ok(would_generate=True, settings=settings, note="Pass allow_generate=True to call CreateSubtitlesFromAudio.")
+        return _ok(would_generate=True, settings=settings, ignored_settings=ignored,
+                   note="Pass allow_generate=True to call CreateSubtitlesFromAudio.")
     if not _has_method(tl, "CreateSubtitlesFromAudio"):
         return _err("CreateSubtitlesFromAudio unavailable")
     with long_resolve_op("timeline.create_subtitles_from_audio"):
-        return {"success": bool(tl.CreateSubtitlesFromAudio(settings)), "settings": settings}
+        return _safe_create_subtitles(tl, p)
 
 
 def _fairlight_boundary_report(proj, mp, tl, p: Dict[str, Any]):
@@ -13711,16 +13888,21 @@ def project_manager_cloud(action: str, params: Optional[Dict[str, Any]] = None)
         return _err("Could not connect to DaVinci Resolve. It was not running and auto-launch failed. Check that Resolve Studio is installed.")
     pm = r.GetProjectManager()
 
+    # cloudSettings is enum-keyed (CLOUD_SETTING_*/CLOUD_SYNC_*); resolve string
+    # keys against the live handle so human-readable settings aren't silently
+    # rejected. Unrecognized keys are dropped and reported in ignored_settings.
+    settings, ignored = _normalize_cloud_settings(p.get("settings"), r)
+
     if action == "create":
-        proj = pm.CreateCloudProject(p["settings"])
-        return _ok(name=proj.GetName()) if proj else _err("Failed to create cloud project")
+        proj = pm.CreateCloudProject(settings)
+        return _ok(name=proj.GetName(), ignored_settings=ignored) if proj else _err("Failed to create cloud project")
     elif action == "load":
-        proj = pm.LoadCloudProject(p["settings"])
-        return _ok(name=proj.GetName()) if proj else _err("Failed to load cloud project")
+        proj = pm.LoadCloudProject(settings)
+        return _ok(name=proj.GetName(), ignored_settings=ignored) if proj else _err("Failed to load cloud project")
     elif action == "import_project":
-        return {"success": bool(pm.ImportCloudProject(p["path"], p["settings"]))}
+        return {"success": bool(pm.ImportCloudProject(p["path"], settings)), "ignored_settings": ignored}
     elif action == "restore":
-        return {"success": bool(pm.RestoreCloudProject(p["folder_path"], p["settings"]))}
+        return {"success": bool(pm.RestoreCloudProject(p["folder_path"], settings)), "ignored_settings": ignored}
     return _unknown(action, ["create","load","import_project","restore"])
 
 
@@ -18118,7 +18300,7 @@ def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
 
     if action == "create_subtitles":
         with long_resolve_op("timeline_ai.create_subtitles"):
-            return {"success": bool(tl.CreateSubtitlesFromAudio(p.get("settings", {})))}
+            return _safe_create_subtitles(tl, p)
     elif action == "detect_scene_cuts":
         with long_resolve_op("timeline_ai.detect_scene_cuts"):
             return {"success": bool(tl.DetectSceneCuts())}

package/src/utils/api_truth.py

@@ -29,6 +29,35 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "'Synced Audio' property (see verify_by_readback).",
         "tags": ["unreliable-return", "silent-failure", "audio", "enum"],
     },
+    {
+        "symbol": "Timeline.CreateSubtitlesFromAudio",
+        "object": "Timeline",
+        "signature": "(autoCaptionSettings) -> bool",
+        "reality": "Same failure mode as AutoSyncAudio: the autoCaptionSettings "
+                   "dict is keyed by resolve.SUBTITLE_* enum constants with "
+                   "resolve.AUTO_CAPTION_* enum values, so plain string keys like "
+                   "{'language': 'korean'} are silently rejected (returns False, "
+                   "no subtitle track created). The boolean is also unreliable.",
+        "recommended": "Resolve the SUBTITLE_*/AUTO_CAPTION_* constants via the "
+                       "live resolve handle (server._normalize_auto_caption_settings) "
+                       "and verify by reading the timeline's subtitle track count "
+                       "before/after (server._safe_create_subtitles).",
+        "tags": ["unreliable-return", "silent-failure", "subtitle", "enum"],
+    },
+    {
+        "symbol": "ProjectManager CloudProject family (Create/Load/Import/RestoreCloudProject)",
+        "object": "ProjectManager",
+        "signature": "(..., cloudSettings) -> Project | bool",
+        "reality": "All four take an enum-keyed {cloudSettings} dict "
+                   "(resolve.CLOUD_SETTING_* keys, resolve.CLOUD_SYNC_* sync-mode "
+                   "values). Plain string keys are silently rejected, so a settings "
+                   "dict built from human-readable keys yields no project / False.",
+        "recommended": "Resolve the CLOUD_SETTING_*/CLOUD_SYNC_* constants via the "
+                       "live resolve handle (server._normalize_cloud_settings) "
+                       "before calling, and treat the bool return from "
+                       "Import/RestoreCloudProject as advisory.",
+        "tags": ["silent-failure", "project", "cloud", "enum"],
+    },
     {
         "symbol": "Composition.Paste",
         "object": "Fusion Composition",