davinci-resolve-mcp 2.52.1 → 2.54.0

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 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.
+
+`safe_auto_sync_audio` / `media_pool.auto_sync_audio` no longer fail silently on
+human-readable settings (issue #70). The previous normalizer recognized
+`syncBy`/`mode` but not `method`, and it forwarded *every* unrecognized key
+(`group_id`, `primary_clip_id`, …) straight into `MediaPool.AutoSyncAudio` —
+which silently rejects the whole call when it sees a key it doesn't understand,
+returning `False` with nothing linked and no error.
+
+- **Fixed** `method` (matching the tool's own parameter naming) is now accepted
+  as an alias for the sync mode alongside `syncBy`/`sync_by`/`mode`/`syncMode`.
+- **Fixed** unrecognized settings keys are dropped instead of forwarded, so a
+  stray `group_id`/`primary_clip_id` no longer poisons the call. Dropped keys
+  are reported back in a new `ignored_settings` field on the response, so a
+  rejection is no longer invisible.
+- **Fixed** the raw `media_pool.auto_sync_audio` action now routes settings
+  through the same live `AUDIO_SYNC_*` enum resolution as the safe wrapper
+  (previously it passed strings straight through).
+
+The Media Pool inventory walk is now configurable:
+
+- **Added** `media_analysis.inventory_exclude_bins` — a comma-separated list of
+  folder names to skip entirely during the inventory walk (recursively). Empty
+  by default, so every folder is indexed unless you opt out.
+- **Added** `media_analysis.inventory_limit` — the maximum clips to index per
+  walk, configurable from the control panel and `setup`. The hard ceiling is
+  raised from 2000 to 10000.
+- Adapted from PR #69 by @rgxdev; the default was changed to exclude nothing
+  (the PR defaulted to excluding an `assets` bin, which would have silently
+  stopped indexing existing `assets` folders on upgrade).
+
 ## What's New in v2.52.1
 
 Analysis reuse no longer blocks on missing capabilities when every clip is

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.52.1-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

@@ -999,9 +999,18 @@ helpers:
 - `audio_mix_capability_report(...)`
 - `voice_isolation_capabilities(track_index?, track_type?, item_index?)`
 - `audio_mapping_report(clip_ids?)`
-- `safe_auto_sync_audio(clip_ids|selected, settings?, dry_run?)`
+- `safe_auto_sync_audio(clip_ids|selected, settings?, dry_run?)` — `settings`
+  accepts human-readable keys: `method`/`mode` (`waveform`|`timecode`),
+  `channel` (`auto`|`mix`|int), `retain_embedded_audio`, `retain_video_metadata`.
+  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.
@@ -1032,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.52.1"
+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.52.1",
+  "version": "2.54.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -4790,6 +4790,12 @@ HTML = r"""<!doctype html>
               <button type="button" class="secondary path-browse" data-browse-target="prefPreferredGeneratedMediaFolder">Browse…</button>
             </div>
           </label>
+          <label>Inventory limit
+            <input id="prefInventoryLimit" type="number" min="1" max="10000" placeholder="Default 500">
+          </label>
+          <label>Inventory exclude bins (comma separated)
+            <input id="prefInventoryExcludeBins" type="text" placeholder="None — index every folder">
+          </label>
           <label>Post-operation page
             <select id="prefPostOperationPage">
               <option value="stay_put">stay put</option>
@@ -5088,6 +5094,8 @@ HTML = r"""<!doctype html>
       prefDryRunFirstDefault: 'Prefers a preview pass before committing metadata or marker changes.',
       prefPreferredAnalysisRoot: 'Optional absolute path for analysis databases and reports. Empty uses the project analysis root.',
       prefPreferredGeneratedMediaFolder: 'Optional folder for generated sidecars or scratch outputs when a workflow needs them.',
+      prefInventoryLimit: 'Maximum number of clips to index during the Media Pool inventory walk (1–10000).',
+      prefInventoryExcludeBins: 'Comma-separated folder names to skip entirely during the inventory walk. Empty indexes every folder.',
       prefPostOperationPage: 'Resolve page to open after an operation completes, or stay put.',
       prefUpdateMode: 'Controls update checks for the MCP package.',
       prefUpdateIntervalHours: 'Minimum time between best-effort release checks.',
@@ -10233,6 +10241,8 @@ HTML = r"""<!doctype html>
       setControlChecked('prefDryRunFirstDefault', media.dry_run_first_default);
       setControlValue('prefPreferredAnalysisRoot', media.preferred_analysis_root || '');
       setControlValue('prefPreferredGeneratedMediaFolder', media.preferred_generated_media_folder || '');
+      setControlValue('prefInventoryLimit', media.inventory_limit || 500);
+      setControlValue('prefInventoryExcludeBins', media.inventory_exclude_bins || '');
       setControlValue('prefPostOperationPage', media.default_post_operation_page);
       setControlValue('prefUpdateMode', updates.mode);
       setControlValue('prefUpdateIntervalHours', updates.check_interval_hours);
@@ -10361,6 +10371,8 @@ HTML = r"""<!doctype html>
           dry_run_first_default: $('prefDryRunFirstDefault').checked,
           preferred_analysis_root: $('prefPreferredAnalysisRoot').value.trim() || 'clear',
           preferred_generated_media_folder: $('prefPreferredGeneratedMediaFolder').value.trim() || 'clear',
+          inventory_limit: parseInt($('prefInventoryLimit').value, 10) || 500,
+          inventory_exclude_bins: $('prefInventoryExcludeBins').value.trim(),
           default_post_operation_page: $('prefPostOperationPage').value,
         },
         updates: {
@@ -12013,6 +12025,7 @@ def _append_folder_media(
     records: List[Dict[str, Any]],
     warnings: List[str],
     limit: int,
+    exclude_bins: Optional[set] = None,
 ) -> bool:
     clips, clip_err = _safe_call(folder, "GetClipList")
     if clip_err:
@@ -12033,6 +12046,8 @@ def _append_folder_media(
         if len(records) >= limit:
             return True
         child_name = _safe_name(subfolder, "Unnamed")
+        if exclude_bins and child_name in exclude_bins:
+            continue
         truncated = _append_folder_media(
             subfolder,
             bin_path=f"{bin_path}/{child_name}",
@@ -12041,6 +12056,7 @@ def _append_folder_media(
             records=records,
             warnings=warnings,
             limit=limit,
+            exclude_bins=exclude_bins,
         )
         if truncated:
             return True
@@ -12256,12 +12272,13 @@ def resolve_media_inventory(
     project_root: str,
     *,
     limit: Any = 500,
+    exclude_bins: Optional[set] = None,
     recursive: bool = True,
     probe_paths: bool = True,
     reuse_cached: bool = False,
 ) -> Dict[str, Any]:
     try:
-        max_items = max(1, min(int(limit), 2000))
+        max_items = max(1, min(int(limit), 10000))
     except (TypeError, ValueError):
         max_items = 500
 
@@ -12349,6 +12366,7 @@ def resolve_media_inventory(
             records=records,
             warnings=warnings,
             limit=max_items,
+            exclude_bins=exclude_bins,
         )
         project_info = {
             "name": _safe_name(project, "Resolve Project"),
@@ -14655,6 +14673,25 @@ def _setup_defaults(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     return server_setup(action, params or {})
 
 
+def _inventory_prefs() -> Tuple[int, Optional[set]]:
+    """Return (limit, exclude_bins) for the inventory walk from media-analysis
+    preferences. ``exclude_bins`` is None when nothing is configured, so the walk
+    indexes every folder by default."""
+    try:
+        from src.server import _media_analysis_effective_preferences
+
+        prefs = _media_analysis_effective_preferences()
+    except Exception:  # noqa: BLE001 — fall back to built-in defaults
+        prefs = {}
+    try:
+        limit = max(1, min(int(prefs.get("inventory_limit", 500)), 10000))
+    except (TypeError, ValueError):
+        limit = 500
+    raw = prefs.get("inventory_exclude_bins")
+    exclude = {part.strip() for part in str(raw).split(",") if part.strip()} if raw else None
+    return limit, (exclude or None)
+
+
 class Handler(BaseHTTPRequestHandler):
     state: DashboardState
 
@@ -14838,10 +14875,12 @@ class Handler(BaseHTTPRequestHandler):
             self._json(_setup_defaults("get_defaults"))
             return
         if path == "/api/resolve/media":
+            pref_limit, exclude_bins = _inventory_prefs()
             self._json_etag(
                 resolve_media_inventory(
                     self.state.project_root,
-                    limit=(query.get("limit") or [500])[0],
+                    limit=(query.get("limit") or [pref_limit])[0],
+                    exclude_bins=exclude_bins,
                     recursive=(query.get("recursive") or ["true"])[0].lower() not in {"0", "false", "no"},
                     probe_paths=(query.get("probe") or ["1"])[0].lower() not in {"0", "false", "no"},
                     reuse_cached=(query.get("reuse") or ["0"])[0].lower() in {"1", "true", "yes"},
@@ -15429,7 +15468,8 @@ def _warm_inventory_cache(project_root: str) -> None:
     first real request builds normally.
     """
     try:
-        resolve_media_inventory(project_root)
+        pref_limit, exclude_bins = _inventory_prefs()
+        resolve_media_inventory(project_root, limit=pref_limit, exclude_bins=exclude_bins)
     except Exception:  # noqa: BLE001 — warm-up must never crash startup
         pass
 

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.52.1"
+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.52.1"
+VERSION = "2.54.0"
 
 import base64
 import os
@@ -5932,9 +5932,9 @@ def _safe_auto_sync_audio(mp, p: Dict[str, Any]):
     # until populated and can be reset to None by a mid-call reconnect. A None
     # here makes _normalize_auto_sync_settings fall back to string enum keys,
     # which AutoSyncAudio silently rejects (returns False).
-    settings = _normalize_auto_sync_settings(dict(p.get("settings") or {}), get_resolve())
+    settings, ignored_settings = _normalize_auto_sync_settings(dict(p.get("settings") or {}), get_resolve())
     if p.get("dry_run", True):
-        return _ok(would_auto_sync=True, clips=_clip_summaries(clips), missing=missing, settings=settings)
+        return _ok(would_auto_sync=True, clips=_clip_summaries(clips), missing=missing, settings=settings, ignored_settings=ignored_settings)
     # Read-back verification: AutoSyncAudio's boolean return is unreliable, so
     # capture each clip's "Synced Audio" linkage before and after and report the
     # delta. Trust `linked`/`newly_linked`, not `success`.
@@ -5969,6 +5969,7 @@ def _safe_auto_sync_audio(mp, p: Dict[str, Any]):
         "count": len(clips),
         "missing": missing,
         "settings": settings,
+        "ignored_settings": ignored_settings,
     }
 
 
@@ -5979,14 +5980,36 @@ def _resolve_audio_constant(resolve_obj, name: str, fallback):
 
 
 def _normalize_auto_sync_settings(settings: Dict[str, Any], resolve_obj=None):
+    """Translate human-readable AutoSyncAudio settings into live ``AUDIO_SYNC_*``
+    enum keys/values.
+
+    Returns ``(normalized, ignored)`` where ``ignored`` is the sorted list of
+    settings keys AutoSyncAudio does not understand (e.g. ``group_id``,
+    ``primary_clip_id``). Those are dropped rather than forwarded: passing any
+    unrecognized key makes ``MediaPool.AutoSyncAudio`` silently reject the whole
+    call (returns ``False``, nothing links). Callers surface ``ignored`` so the
+    rejection is no longer invisible. See utils/api_truth.py: MediaPool.AutoSyncAudio.
+    """
     if not settings:
-        return settings
+        return {}, []
     normalized = {}
     mode_key = _resolve_audio_constant(resolve_obj, "AUDIO_SYNC_MODE", "syncMode")
     channel_key = _resolve_audio_constant(resolve_obj, "AUDIO_SYNC_CHANNEL_NUMBER", "channelNumber")
     retain_embedded_key = _resolve_audio_constant(resolve_obj, "AUDIO_SYNC_RETAIN_EMBEDDED_AUDIO", "retainEmbeddedAudio")
     retain_metadata_key = _resolve_audio_constant(resolve_obj, "AUDIO_SYNC_RETAIN_VIDEO_METADATA", "retainVideoMetadata")
-    mode = settings.get("syncBy", settings.get("sync_by", settings.get("mode", settings.get(mode_key))))
+
+    consumed: set = set()
+
+    def _pick(*keys):
+        for key in keys:
+            if key in settings:
+                consumed.add(key)
+                return settings[key]
+        return None
+
+    # "method" is a natural alias for the sync mode (the tool advertises
+    # method="waveform"); accept it alongside syncBy/mode and a pre-resolved key.
+    mode = _pick("syncBy", "sync_by", "mode", "method", "syncMode", "sync_mode", mode_key)
     if isinstance(mode, str):
         mode_norm = mode.strip().lower()
         if mode_norm in {"waveform", "audio_waveform", "audio_sync_waveform"}:
@@ -5995,7 +6018,8 @@ def _normalize_auto_sync_settings(settings: Dict[str, Any], resolve_obj=None):
             mode = _resolve_audio_constant(resolve_obj, "AUDIO_SYNC_TIMECODE", mode)
     if mode is not None:
         normalized[mode_key] = mode
-    channel = settings.get("channelNumber", settings.get("channel_number", settings.get("channel", settings.get(channel_key))))
+
+    channel = _pick("channelNumber", "channel_number", "channel", channel_key)
     if isinstance(channel, str):
         channel_norm = channel.strip().lower()
         if channel_norm in {"auto", "automatic"}:
@@ -6004,18 +6028,192 @@ def _normalize_auto_sync_settings(settings: Dict[str, Any], resolve_obj=None):
             channel = _resolve_audio_constant(resolve_obj, "AUDIO_SYNC_CHANNEL_MIX", -2)
     if channel is not None:
         normalized[channel_key] = channel
-    for source_key, target_key in (
-        ("retainEmbeddedAudio", retain_embedded_key),
-        ("retain_embedded_audio", retain_embedded_key),
-        ("retainVideoMetadata", retain_metadata_key),
-        ("retain_video_metadata", retain_metadata_key),
-    ):
-        if source_key in settings:
-            normalized[target_key] = bool(settings[source_key])
-    for key, value in settings.items():
-        if key not in {"syncBy", "sync_by", "mode", "channelNumber", "channel_number", "channel", "retainEmbeddedAudio", "retain_embedded_audio", "retainVideoMetadata", "retain_video_metadata"}:
-            normalized.setdefault(key, value)
-    return normalized
+
+    retain_embedded = _pick("retainEmbeddedAudio", "retain_embedded_audio")
+    if retain_embedded is not None:
+        normalized[retain_embedded_key] = bool(retain_embedded)
+    retain_metadata = _pick("retainVideoMetadata", "retain_video_metadata")
+    if retain_metadata is not None:
+        normalized[retain_metadata_key] = bool(retain_metadata)
+
+    ignored = sorted(str(key) for key in settings if key not in consumed)
+    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]):
@@ -6063,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]):
@@ -7033,6 +7232,11 @@ _MEDIA_ANALYSIS_DEFAULT_PREFS = {
     "sampling_frame_ceiling": 80,
     "preferred_analysis_root": None,
     "preferred_generated_media_folder": None,
+    # Inventory walk tuning. inventory_limit caps how many clips the Media Pool
+    # walk indexes (clamped 1..10000). inventory_exclude_bins is a comma-separated
+    # list of folder names to skip entirely; empty means index every folder.
+    "inventory_limit": 500,
+    "inventory_exclude_bins": "",
     "default_post_operation_page": "stay_put",
     "marker_custom_data": "namespaced",
     "metadata_writeback_default": True,
@@ -7286,6 +7490,12 @@ def _media_analysis_effective_preferences() -> Dict[str, Any]:
     ] or list(_MEDIA_ANALYSIS_DEFAULT_PUBLISH_FIELDS)
     effective["include_confidence_scores"] = _media_analysis_bool(effective.get("include_confidence_scores"), True)
     effective["include_source_time_notes"] = _media_analysis_bool(effective.get("include_source_time_notes"), True)
+    effective["inventory_limit"] = _setup_positive_int(effective.get("inventory_limit"), 500, 1, 10000)
+    effective["inventory_exclude_bins"] = (
+        str(effective.get("inventory_exclude_bins")).strip()
+        if effective.get("inventory_exclude_bins") is not None
+        else ""
+    )
     effective["analysis_summary_style"] = _normalize_setup_choice(
         effective.get("analysis_summary_style"),
         ["full", "concise", "creative", "technical"],
@@ -10983,6 +11193,12 @@ def _setup_set_media_analysis_defaults(media_defaults: Dict[str, Any], dry_run:
         "preferredgeneratedmediafolder": "preferred_generated_media_folder",
         "generated_media_folder": "preferred_generated_media_folder",
         "generatedmediafolder": "preferred_generated_media_folder",
+        "inventory_limit": "inventory_limit",
+        "inventorylimit": "inventory_limit",
+        "inventory_exclude_bins": "inventory_exclude_bins",
+        "inventoryexcludebins": "inventory_exclude_bins",
+        "exclude_bins": "inventory_exclude_bins",
+        "excludebins": "inventory_exclude_bins",
         "default_post_operation_page": "default_post_operation_page",
         "defaultpostoperationpage": "default_post_operation_page",
         "post_operation_page": "default_post_operation_page",
@@ -11205,6 +11421,16 @@ def _setup_set_media_analysis_defaults(media_defaults: Dict[str, Any], dry_run:
             if normalized is None:
                 return _err("Unsupported marker_custom_data. Use namespaced or minimal.")
             set_or_clear(key, raw_value, normalized)
+        elif key == "inventory_limit":
+            try:
+                n = int(raw_value) if not isinstance(raw_value, bool) else 500
+            except (TypeError, ValueError):
+                return _err("inventory_limit must be an integer between 1 and 10000.")
+            set_or_clear(key, raw_value, max(1, min(10000, n)))
+        elif key == "inventory_exclude_bins":
+            # Normalize a comma-separated list of folder names; empty excludes nothing.
+            parts = [part.strip() for part in str(raw_value).split(",") if part.strip()]
+            set_or_clear(key, raw_value, ",".join(parts))
         elif key in {"preferred_analysis_root", "preferred_generated_media_folder"}:
             path = None if clear_requested(raw_value) else os.path.realpath(os.path.abspath(os.path.expanduser(str(raw_value))))
             set_or_clear(key, raw_value, path)
@@ -11449,6 +11675,8 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
                 "media_analysis.report_format": {"values": ["compact", "full", "machine_readable"], "storage": _media_analysis_preferences_path()},
                 "media_analysis.preferred_analysis_root": {"values": "absolute or expandable path", "storage": _media_analysis_preferences_path()},
                 "media_analysis.preferred_generated_media_folder": {"values": "absolute or expandable path", "storage": _media_analysis_preferences_path()},
+                "media_analysis.inventory_limit": {"description": "Maximum clips indexed during the Media Pool inventory walk.", "values": "integer 1..10000 (default 500)", "storage": _media_analysis_preferences_path()},
+                "media_analysis.inventory_exclude_bins": {"description": "Comma-separated folder names to skip entirely during the inventory walk. Empty indexes every folder.", "values": "comma-separated folder names (default none)", "storage": _media_analysis_preferences_path()},
                 "media_analysis.default_post_operation_page": {"values": ["stay_put", "media", "cut", "edit", "fusion", "color", "fairlight", "deliver"], "storage": _media_analysis_preferences_path()},
                 "media_analysis.marker_custom_data": {"values": ["namespaced", "minimal"], "storage": _media_analysis_preferences_path()},
                 "media_analysis.metadata_writeback_default": {"values": [True, False], "storage": _media_analysis_preferences_path()},
@@ -13660,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"])
 
 
@@ -14770,7 +15003,13 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
     elif action == "auto_sync_audio":
         clips = [_find_clip(root, cid) for cid in p["clip_ids"]]
         clips = [c for c in clips if c]
-        return {"success": bool(mp.AutoSyncAudio(clips, p.get("settings", {})))}
+        # Normalize string settings into live AUDIO_SYNC_* enum keys; passing raw
+        # human-readable keys makes AutoSyncAudio silently reject the call.
+        settings, ignored = _normalize_auto_sync_settings(dict(p.get("settings") or {}), get_resolve())
+        result = {"success": bool(mp.AutoSyncAudio(clips, settings))}
+        if ignored:
+            result["ignored_settings"] = ignored
+        return result
     elif action == "get_selected":
         sel = mp.GetSelectedClips()
         if not sel:
@@ -18061,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",