davinci-resolve-mcp 2.57.1 → 2.57.3

package/AGENTS.md

@@ -69,6 +69,10 @@ semantics.
 - Release checklist and validation rules: `docs/process/release-process.md`
 - Kernel workflow support maps: `docs/kernels/`
 - API coverage and live-test status: `docs/reference/api-coverage.md`
+- Blackmagic-facing API gaps/bugs (generated from `api_truth`):
+  `docs/reference/api-limitations.md` — when you document a new Resolve API
+  limitation, add a `submit`-tagged entry to `src/utils/api_truth.py` and
+  regenerate with `scripts/gen_api_limitations.py` (a drift guard enforces it)
 - Bundled Resolve API text: `docs/reference/resolve_scripting_api.txt`
 
 ## Key Paths

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 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.3
+
+Expanded the API-limitations catalogue with a live surface audit.
+
+- **Added** 8 newly-catalogued **missing capabilities** to
+  `docs/reference/api-limitations.md`, found by a `dir()` audit of the live
+  Resolve 21.0.0 API objects diffed against the UI feature set: timeline-item
+  trim/move/re-time (getters only, no setters), razor/blade/split, clip
+  speed/retime ratio & ramps, color node-graph editing + primary grade values,
+  Fairlight audio levels/pan/EQ/automation/FairlightFX, proxy/optimized-media
+  generation, insert/overwrite/replace/fit-to-fill edit modes, and Smart/Power
+  Bin creation. The report now lists 14 missing capabilities + 9 bugs.
+- **Verified** the four previously-doc-derived entries (per-clip audio
+  stereo↔mono, native multicam creation, transitions, cloud list/export/user)
+  against the live API surface; all confirmed absent.
+- **Changed** the generated report to carry an explicit **Scope & completeness**
+  note — it is not guaranteed exhaustive (surface audit + incident log; misses
+  parameters that exist-but-misbehave and untested capabilities).
+
+## What's New in v2.57.2
+
+Consolidated, submittable list of Resolve scripting-API limitations.
+
+- **Added** `docs/reference/api-limitations.md` — a curated, behaviorally-verified
+  catalogue of Resolve scripting-API gaps and bugs, split into **Missing
+  Capabilities** (please add) and **Bugs / Unreliable Behavior** (please fix),
+  formatted for submission to Blackmagic Design's developer feedback. First cut:
+  6 missing capabilities (Source Track Selector / insert `trackIndex`, per-clip
+  audio stereo↔mono, native multicam-clip creation, transition create/copy,
+  `GetTimelineByName`, cloud project list/export/user management) and 9
+  bugs/unreliable behaviors (enum-key silent failures in `AutoSyncAudio`,
+  `CreateSubtitlesFromAudio`, CloudProject family, and `Timeline.Export`; flaky
+  `DeleteProject`; `Composition.Paste` bridge failure; `FlowView` unreliable
+  returns; truncated `Transcription` property; automation-blocking `CreateProject`
+  modal).
+- **Added** `scripts/gen_api_limitations.py` — the report is generated from the
+  `submit`-tagged entries in the `api_truth` ledger (single source of truth, also
+  queryable at runtime via `resolve_control api_truth`), so it never drifts.
+- **Changed** the release process and CI to keep it current: a new
+  `tests.test_api_limitations_doc` drift guard (added to the publish workflow)
+  fails if the doc is stale, and `docs/process/release-process.md` now requires
+  regenerating it whenever a `submit`-tagged entry changes.
+
 ## What's New in v2.57.1
 
 Investigation outcome for community feature request #74 — no behavior change.

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.57.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.57.3-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/process/release-process.md

@@ -29,6 +29,11 @@ Every release bump must update all version surfaces:
 - README version badge
 - README current stats or latest-release summary when they changed
 - `CHANGELOG.md` latest release entry
+- `docs/reference/api-limitations.md` when any `submit`-tagged entry in
+  `src/utils/api_truth.py` was added or changed (a newly documented Resolve API
+  gap/bug, a closed won't-fix issue, etc.). Regenerate it — do not hand-edit:
+  `venv/bin/python scripts/gen_api_limitations.py`. The
+  `tests.test_api_limitations_doc` drift guard fails the suite if it is stale.
 - `docs/SKILL.md` when tool discovery, examples, or behavior changed
 - `docs/guides/control-panel.md` when the control panel UI changed, plus
   regenerated screenshots: start the panel against a project with analysis
@@ -48,6 +53,7 @@ Always run static checks before release:
 ```bash
 venv/bin/python tests/test_import.py
 venv/bin/python scripts/audit_api_parity.py
+venv/bin/python scripts/gen_api_limitations.py --check
 venv/bin/python -m unittest tests.test_static_undefined_names tests.test_action_list_drift tests.test_panel_docs_drift
 node bin/davinci-resolve-mcp.mjs --help
 node bin/davinci-resolve-mcp.mjs --version

package/docs/reference/api-coverage.md

@@ -57,6 +57,12 @@ a track via `MediaPool.AppendToTimeline`'s clipInfo `trackIndex` (exposed as
 in the verified `api_truth` ledger (query `resolve_control api_truth "track"`);
 see issue #74.
 
+The full catalogue of verified scripting-API gaps and bugs — curated for
+submission to Blackmagic Design's developer feedback — lives in
+[api-limitations.md](api-limitations.md). It is generated from the `submit`-tagged
+`api_truth` entries (`scripts/gen_api_limitations.py`) and kept in sync by a drift
+guard, so it never goes stale.
+
 | Class | Methods | Tools | Description |
 |-------|---------|-------|-------------|
 | Resolve | 22 | 22 | App control, pages, layout presets, render/burn-in presets, keyframe mode |

package/docs/reference/api-limitations.md

@@ -0,0 +1,208 @@
+# DaVinci Resolve Scripting API — Limitations & Feedback
+
+<!-- GENERATED FILE — do not edit by hand.
+     Source: src/utils/api_truth.py (entries tagged `submit`).
+     Regenerate: venv/bin/python scripts/gen_api_limitations.py -->
+
+This is a curated, behaviorally-verified list of DaVinci Resolve scripting
+API gaps and bugs encountered while building this MCP server, intended for
+submission to Blackmagic Design's developer feedback. Every item was
+observed against live Resolve; each entry notes the current workaround (or
+that none exists).
+
+**Verified on:** DaVinci Resolve Studio 21.0.0
+
+**Totals:** 14 missing capabilities, 9 bugs / unreliable behaviors.
+
+The authoritative source is the runtime-queryable `api_truth` ledger
+(`resolve_control api_truth "<query>"`); this document is generated from
+it and stays in sync via a drift guard.
+
+### Scope & completeness
+
+This list is **not guaranteed exhaustive.** It combines (a) issues hit
+while building this MCP server and (b) a `dir()` surface audit of the live
+Resolve API objects (ProjectManager, Project, MediaPool, MediaPoolItem,
+Timeline, TimelineItem, Graph) diffed against Resolve's UI feature set.
+That catches absent methods and documented constraints, but not subtler
+issues: parameters that exist yet misbehave, version-specific regressions,
+or capabilities we simply never exercised. New findings are added as
+`submit`-tagged `api_truth` entries and this document is regenerated.
+
+## Missing Capabilities (please add)
+
+Functionality that exists in the Resolve UI but has no scripting API
+equivalent, blocking full automation.
+
+### Timeline.GetTimelineByName
+
+- **Object:** `Project`
+- **Behavior:** Does not exist. Timelines are looked up by index.
+- **Workaround / current handling:** Iterate GetTimelineByIndex(1..GetTimelineCount()).
+- **Tags:** missing-method, timeline
+
+### Source Track Selector / destination track for Insert*IntoTimeline
+
+- **Object:** `Timeline`
+- **Behavior:** There is no API to read or set the Source/Auto Track Selector (the Edit-page patch panel that picks the destination track). InsertTitleIntoTimeline, InsertFusionTitleIntoTimeline, InsertGeneratorIntoTimeline, InsertFusionGeneratorIntoTimeline, InsertOFXGeneratorIntoTimeline and InsertFusionCompositionIntoTimeline take no trackIndex and always drop the clip on the selector's current target (V1 in practice). Locking lower video tracks does NOT redirect the insert — verified live on 21.0.0: locking V1 makes the insert FAIL rather than land on V2. Titles/generators also can't be moved afterward (no MediaPoolItem, so AppendToTimeline clipInfo and MoveClips don't apply).
+- **Workaround / current handling:** Accept the limitation for titles/generators (insert lands on V1). For clips that DO have a MediaPoolItem, target a track with MediaPool.AppendToTimeline's clipInfo 'trackIndex' instead (exposed as media_pool append_to_timeline clip_infos). See issue #74.
+- **Reference:** [issue #74](https://github.com/samuelgursky/davinci-resolve-mcp/issues/74)
+- **Tags:** missing-method, timeline, title, generator, track
+
+### Per-clip audio channel-format conversion (Stereo<->Mono)
+
+- **Object:** `MediaPoolItem / TimelineItem`
+- **Behavior:** No scripting method converts an individual clip's audio channel format. ConvertTimelineToStereo is timeline-wide, and CreateStereoClip builds a 3D *visual* stereoscopic clip, not an audio mono->stereo change. The Edit-page 'Clip Attributes > Audio' channel mapping is UI-only.
+- **Workaround / current handling:** Use the supported surface: timeline add_track with audioType (create mono/stereo tracks), get_track_sub_type (query format), convert_to_stereo (timeline-wide), and timeline_item get_source_audio_channel_mapping. Per-clip conversion is not possible. See issue #73.
+- **Reference:** [issue #73](https://github.com/samuelgursky/davinci-resolve-mcp/issues/73)
+- **Tags:** missing-method, audio, channel
+
+### Native multicam clip creation
+
+- **Object:** `MediaPool`
+- **Behavior:** There is no method to create a native multicam clip from a set of angles. Angles can be stacked onto tracks programmatically, but the multicam-clip conversion is a UI-only step.
+- **Workaround / current handling:** Prepare a stacked timeline (media_pool setup_multicam_timeline) and finish the multicam-clip conversion in the Resolve UI.
+- **Tags:** missing-method, media-pool, multicam
+
+### Transition create / copy / clone
+
+- **Object:** `Timeline / TimelineItem`
+- **Behavior:** The scripting API exposes no method to add, read, copy, or clone an edit transition (cross-dissolve, etc.). Transitions applied in the UI are invisible to and unmodifiable by scripts.
+- **Workaround / current handling:** Apply/duplicate transitions in the Resolve UI; no scripted equivalent exists.
+- **Tags:** missing-method, timeline, transition
+
+### Cloud project enumeration / export / user management
+
+- **Object:** `ProjectManager`
+- **Behavior:** Only CreateCloudProject, LoadCloudProject, ImportCloudProject and RestoreCloudProject exist. There is no GetCloudProjectList (list available cloud projects), no ExportToCloud, and no Add/RemoveUserToCloudProject — so cloud collaboration can't be fully automated.
+- **Workaround / current handling:** Drive cloud project listing, export, and collaborator management from the Resolve UI; only create/load/import/restore are scriptable.
+- **Tags:** missing-method, project, cloud
+
+### TimelineItem trim / move / re-time (no position setters)
+
+- **Object:** `TimelineItem`
+- **Behavior:** TimelineItem exposes GetStart, GetEnd, GetDuration, GetLeftOffset, GetRightOffset and GetSourceStart/EndFrame, but NO matching setters. A clip cannot be trimmed, slipped, slid, rolled, moved to another time/track, or have its duration changed once it is on the timeline. Verified via dir() on Resolve 21.0.0 (getters only).
+- **Workaround / current handling:** Do edit-point adjustments in the Resolve UI, or rebuild the timeline from MediaPool.AppendToTimeline clipInfos with the desired startFrame/endFrame/recordFrame.
+- **Tags:** missing-method, timeline, edit, trim
+
+### Razor / blade / split a timeline item
+
+- **Object:** `Timeline / TimelineItem`
+- **Behavior:** There is no method to split/cut/blade a clip at a given frame. Verified absent on Timeline and TimelineItem (dir(), 21.0.0).
+- **Workaround / current handling:** Split in the Resolve UI, or construct the cut up-front by appending two clipInfos with the desired in/out points.
+- **Tags:** missing-method, timeline, edit
+
+### Clip speed / retime ratio and speed ramps
+
+- **Object:** `TimelineItem`
+- **Behavior:** SetProperty exposes only retime *quality* (RetimeProcess, MotionEstimation) and transform/crop/composite/opacity keys — not the speed value itself. There is no way to set a clip to a given % speed, reverse it, or author a speed ramp. Verified against the documented SetProperty key list (21.0.0).
+- **Workaround / current handling:** Set clip speed/retime in the Resolve UI; no scripted equivalent exists.
+- **Tags:** missing-method, timeline, retime, speed
+
+### Color node graph editing and primary grade values
+
+- **Object:** `Graph / TimelineItem`
+- **Behavior:** The Graph object exposes node enable/label/count, LUT get/set, cache mode, ResetAllGrades, ApplyGradeFromDRX and ApplyArriCdlLut; TimelineItem adds SetCDL, CopyGrades and color versions. But you cannot add, delete, or connect nodes, and you cannot read or write primary grade values (lift/gamma/gain/offset/contrast/curves/qualifiers/power windows). Grading is limited to CDL, whole-grade DRX/LUT application and copying.
+- **Workaround / current handling:** Build node trees and dial grades in the Resolve UI or via DRX/CDL/LUT import; per-parameter grade control is not scriptable.
+- **Tags:** missing-method, color, grade, node
+
+### Fairlight audio levels / pan / EQ / automation / FairlightFX
+
+- **Object:** `TimelineItem / Timeline`
+- **Behavior:** There is no API to set clip or track volume, pan, EQ, audio automation, or to add/configure FairlightFX. SetProperty covers video transform only; the audio surface is read-only (GetSourceAudioChannelMapping, GetAudioMapping, voice isolation). Verified via dir() + SetProperty docs (21.0.0).
+- **Workaround / current handling:** Mix in the Fairlight UI; only voice-isolation state and channel-mapping reads are scriptable.
+- **Tags:** missing-method, audio, fairlight
+
+### Proxy / optimized-media generation
+
+- **Object:** `MediaPoolItem`
+- **Behavior:** Only LinkProxyMedia, UnlinkProxyMedia and LinkFullResolutionMedia exist (attach/detach EXISTING proxies). There is no method to generate proxies or optimized media. Verified via MediaPoolItem dir() (21.0.0).
+- **Workaround / current handling:** Trigger proxy/optimized-media generation from the Resolve UI; scripting can only link/unlink already-rendered proxies.
+- **Tags:** missing-method, media-pool, proxy
+
+### Insert / Overwrite / Replace / Fit-to-Fill edit modes
+
+- **Object:** `MediaPool / Timeline`
+- **Behavior:** MediaPool.AppendToTimeline (with optional recordFrame positioning) is the only programmatic placement. The standard edit modes — insert (ripple), overwrite, replace, fit-to-fill, place-on-top — have no API. Verified via dir() (21.0.0).
+- **Workaround / current handling:** Position clips with AppendToTimeline clipInfo recordFrame, or perform insert/overwrite/replace edits in the Resolve UI.
+- **Tags:** missing-method, timeline, edit
+
+### Smart Bins / Power Bins creation
+
+- **Object:** `MediaPool`
+- **Behavior:** Only AddSubFolder (a regular bin) exists. Smart Bins (rule-based) and Power Bins (cross-project) cannot be created or configured. Verified via MediaPool dir() (21.0.0).
+- **Workaround / current handling:** Create Smart/Power Bins in the Resolve UI; only regular bins are scriptable.
+- **Tags:** missing-method, media-pool, bins
+
+## Bugs / Unreliable Behavior (please fix)
+
+Methods that exist but misbehave — silent failures, unreliable return
+values, or automation-hostile modal prompts.
+
+### MediaPool.AutoSyncAudio
+
+- **Object:** `MediaPool`
+- **Signature:** `(clips, settings) -> bool`
+- **Behavior:** The boolean return does not reflect whether clips actually linked, and string enum keys in `settings` are silently rejected (the call returns False).
+- **Workaround / current handling:** Resolve the AUDIO_SYNC_* enum constants via the live resolve handle, and verify by reading each clip's 'Synced Audio' property (see verify_by_readback).
+- **Tags:** unreliable-return, silent-failure, audio, enum
+
+### Timeline.CreateSubtitlesFromAudio
+
+- **Object:** `Timeline`
+- **Signature:** `(autoCaptionSettings) -> bool`
+- **Behavior:** 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.
+- **Workaround / current handling:** 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
+
+### ProjectManager CloudProject family (Create/Load/Import/RestoreCloudProject)
+
+- **Object:** `ProjectManager`
+- **Signature:** `(..., cloudSettings) -> Project | bool`
+- **Behavior:** 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.
+- **Workaround / current handling:** 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
+
+### Timeline.Export
+
+- **Object:** `Timeline`
+- **Signature:** `(fileName, exportType, exportSubtype) -> bool`
+- **Behavior:** exportType/exportSubtype must be resolve.EXPORT_* enum *values* resolved from the live handle. A JSON/MCP caller cannot pass a live enum, and a plain string ('fcpxml', or even the constant name 'EXPORT_FCPXML_1_10') is silently rejected with no file written.
+- **Workaround / current handling:** Map a friendly format/subtype to the EXPORT_* constant and resolve it against the live handle (server._timeline_export_spec) before calling; verify the output file exists afterward.
+- **Tags:** silent-failure, timeline, export, enum
+
+### ProjectManager.DeleteProject
+
+- **Object:** `ProjectManager`
+- **Signature:** `(projectName) -> bool`
+- **Behavior:** Returns False (no deletion) when the target project is, or recently was, the current project, and is flaky on the first attempt — so a single bool() call leaves the project undeleted with no useful error.
+- **Workaround / current handling:** Load/close away from the target first, then retry; use src/utils/project_cleanup.py:delete_project_safely.
+- **Tags:** unreliable-return, project, flaky
+
+### Composition.Paste
+
+- **Object:** `Fusion Composition`
+- **Behavior:** Passing tool.SaveSettings()'s in-memory table to Paste() / LoadSettings() fails across the Python bridge with an OrderedDict/null-argument error and creates no node, while reporting nothing useful.
+- **Workaround / current handling:** Duplicate via AddTool(RegID) + SaveSettings(path)/LoadSettings(path) through a temp .setting FILE, which round-trips reliably. Identify the new node by name diff.
+- **Tags:** fusion, bridge, silent-failure
+
+### FlowView.SetPos / FlowView.GetPosTable
+
+- **Object:** `Fusion FlowView (comp.CurrentFrame.FlowView)`
+- **Behavior:** Node positions are read/written through the FlowView, not the tool. SetPos returns nothing reliable; GetPosTable returns a 1-indexed table (or dict/tuple depending on bridge).
+- **Workaround / current handling:** Use comp.CurrentFrame.FlowView.SetPos(tool, x, y); confirm with GetPosTable and a liberal position parser.
+- **Tags:** fusion, unreliable-return
+
+### MediaPoolItem.GetClipProperty('Transcription')
+
+- **Object:** `MediaPoolItem`
+- **Behavior:** Returns a PREVIEW of the transcription that ends in an ellipsis when the full transcript is longer than the property exposes.
+- **Workaround / current handling:** Treat a trailing ellipsis as truncation (see media_pool_item get_transcription's `truncated` flag).
+- **Tags:** transcription, truncation
+
+### ProjectManager.CreateProject (with a dirty Untitled project)
+
+- **Object:** `ProjectManager`
+- **Behavior:** Returns None and pops a modal 'Save Current Project' dialog when the current unsaved/Untitled project blocks the switch. SaveProject() on an Untitled project re-triggers the same modal.
+- **Workaround / current handling:** CloseProject(current) to discard the untitled project without a prompt, then CreateProject; restore with LoadProject afterward.
+- **Tags:** project, modal, silent-failure

package/install.py

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

package/scripts/gen_api_limitations.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Generate the Blackmagic-facing DaVinci Resolve API limitations report.
+
+The single source of truth is the ``submit``-tagged entries in
+``src/utils/api_truth.py`` (see ``submittable_limitations``). This script renders
+them into ``docs/reference/api-limitations.md`` — a curated, behaviorally-verified
+list that can be submitted to Blackmagic Design's developer feedback, split into
+capabilities they should *add* and behaviors they should *fix*.
+
+The output is deterministic (no timestamps) so ``tests.test_api_limitations_doc``
+can assert the committed file matches. Regenerate after editing any ``submit``
+entry:
+
+    venv/bin/python scripts/gen_api_limitations.py
+
+Run with ``--check`` to fail (exit 1) when the committed doc is stale.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+from src.utils.api_truth import (  # noqa: E402
+    VERIFIED_ON,
+    submittable_limitations,
+)
+
+DOC_PATH = REPO_ROOT / "docs" / "reference" / "api-limitations.md"
+ISSUE_URL = "https://github.com/samuelgursky/davinci-resolve-mcp/issues"
+
+
+def _render_entry(entry: dict) -> str:
+    lines = [f"### {entry['symbol']}", ""]
+    obj = entry.get("object")
+    if obj:
+        lines.append(f"- **Object:** `{obj}`")
+    sig = entry.get("signature")
+    if sig:
+        lines.append(f"- **Signature:** `{sig}`")
+    lines.append(f"- **Behavior:** {entry['reality']}")
+    rec = entry.get("recommended")
+    if rec:
+        lines.append(f"- **Workaround / current handling:** {rec}")
+    issue = entry.get("issue")
+    if issue is not None:
+        lines.append(f"- **Reference:** [issue #{issue}]({ISSUE_URL}/{issue})")
+    tags = entry.get("tags")
+    if tags:
+        lines.append(f"- **Tags:** {', '.join(tags)}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def render() -> str:
+    groups = submittable_limitations()
+    missing = groups["missing"]
+    bugs = groups["bug"]
+
+    out = [
+        "# DaVinci Resolve Scripting API — Limitations & Feedback",
+        "",
+        "<!-- GENERATED FILE — do not edit by hand.",
+        "     Source: src/utils/api_truth.py (entries tagged `submit`).",
+        "     Regenerate: venv/bin/python scripts/gen_api_limitations.py -->",
+        "",
+        "This is a curated, behaviorally-verified list of DaVinci Resolve scripting",
+        "API gaps and bugs encountered while building this MCP server, intended for",
+        "submission to Blackmagic Design's developer feedback. Every item was",
+        "observed against live Resolve; each entry notes the current workaround (or",
+        "that none exists).",
+        "",
+        f"**Verified on:** {VERIFIED_ON}",
+        "",
+        f"**Totals:** {len(missing)} missing capabilities, {len(bugs)} bugs / "
+        "unreliable behaviors.",
+        "",
+        "The authoritative source is the runtime-queryable `api_truth` ledger",
+        "(`resolve_control api_truth \"<query>\"`); this document is generated from",
+        "it and stays in sync via a drift guard.",
+        "",
+        "### Scope & completeness",
+        "",
+        "This list is **not guaranteed exhaustive.** It combines (a) issues hit",
+        "while building this MCP server and (b) a `dir()` surface audit of the live",
+        "Resolve API objects (ProjectManager, Project, MediaPool, MediaPoolItem,",
+        "Timeline, TimelineItem, Graph) diffed against Resolve's UI feature set.",
+        "That catches absent methods and documented constraints, but not subtler",
+        "issues: parameters that exist yet misbehave, version-specific regressions,",
+        "or capabilities we simply never exercised. New findings are added as",
+        "`submit`-tagged `api_truth` entries and this document is regenerated.",
+        "",
+        "## Missing Capabilities (please add)",
+        "",
+        "Functionality that exists in the Resolve UI but has no scripting API",
+        "equivalent, blocking full automation.",
+        "",
+    ]
+    for entry in missing:
+        out.append(_render_entry(entry))
+
+    out += [
+        "## Bugs / Unreliable Behavior (please fix)",
+        "",
+        "Methods that exist but misbehave — silent failures, unreliable return",
+        "values, or automation-hostile modal prompts.",
+        "",
+    ]
+    for entry in bugs:
+        out.append(_render_entry(entry))
+
+    return "\n".join(out).rstrip() + "\n"
+
+
+def main(argv: list[str]) -> int:
+    content = render()
+    if "--check" in argv:
+        current = DOC_PATH.read_text() if DOC_PATH.exists() else ""
+        if current != content:
+            print(
+                f"STALE: {DOC_PATH.relative_to(REPO_ROOT)} is out of date.\n"
+                "Run: venv/bin/python scripts/gen_api_limitations.py",
+                file=sys.stderr,
+            )
+            return 1
+        print(f"OK: {DOC_PATH.relative_to(REPO_ROOT)} is up to date.")
+        return 0
+    DOC_PATH.write_text(content)
+    print(f"Wrote {DOC_PATH.relative_to(REPO_ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.57.1"
+VERSION = "2.57.3"
 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.1"
+VERSION = "2.57.3"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -10,6 +10,19 @@ Each entry is a small dict. Grow it opportunistically — every readback recipe
 every fix that uncovers a surprising behavior should add an entry. Facts are
 stamped with the Resolve build they were verified on so drift is visible when a
 new version ships.
+
+Optional keys on an entry feed the Blackmagic-facing limitations report
+(``docs/reference/api-limitations.md``, generated by
+``scripts/gen_api_limitations.py``):
+
+  - ``submit``: ``"missing"`` (a capability Blackmagic should add) or ``"bug"``
+    (a behavior Blackmagic should fix). Entries without ``submit`` are internal
+    quirks/tips and stay out of the report.
+  - ``issue``: GitHub issue number (int) that drove the finding, for cross-ref.
+
+When you add or change a ``submit``-tagged entry, regenerate the report
+(``venv/bin/python scripts/gen_api_limitations.py``) or the
+``tests.test_api_limitations_doc`` drift guard fails.
 """
 from typing import Any, Dict, List, Optional
 
@@ -28,6 +41,7 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "resolve handle, and verify by reading each clip's "
                        "'Synced Audio' property (see verify_by_readback).",
         "tags": ["unreliable-return", "silent-failure", "audio", "enum"],
+        "submit": "bug",
         "mitigation": ["_normalize_auto_sync_settings", "_safe_auto_sync_audio"],
     },
     {
@@ -44,6 +58,7 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "and verify by reading the timeline's subtitle track count "
                        "before/after (server._safe_create_subtitles).",
         "tags": ["unreliable-return", "silent-failure", "subtitle", "enum"],
+        "submit": "bug",
         "mitigation": ["_normalize_auto_caption_settings", "_safe_create_subtitles"],
     },
     {
@@ -59,6 +74,7 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "before calling, and treat the bool return from "
                        "Import/RestoreCloudProject as advisory.",
         "tags": ["silent-failure", "project", "cloud", "enum"],
+        "submit": "bug",
         "mitigation": ["_normalize_cloud_settings"],
     },
     {
@@ -75,6 +91,7 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "(server._timeline_export_spec) before calling; verify the "
                        "output file exists afterward.",
         "tags": ["silent-failure", "timeline", "export", "enum"],
+        "submit": "bug",
         "mitigation": ["_timeline_export_spec", "_timeline_export_value"],
     },
     {
@@ -88,6 +105,7 @@ API_TRUTH: List[Dict[str, Any]] = [
         "recommended": "Load/close away from the target first, then retry; use "
                        "src/utils/project_cleanup.py:delete_project_safely.",
         "tags": ["unreliable-return", "project", "flaky"],
+        "submit": "bug",
     },
     {
         "symbol": "Composition.Paste",
@@ -100,6 +118,7 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "LoadSettings(path) through a temp .setting FILE, which "
                        "round-trips reliably. Identify the new node by name diff.",
         "tags": ["fusion", "bridge", "silent-failure"],
+        "submit": "bug",
     },
     {
         "symbol": "FlowView.SetPos / FlowView.GetPosTable",
@@ -110,6 +129,7 @@ API_TRUTH: List[Dict[str, Any]] = [
         "recommended": "Use comp.CurrentFrame.FlowView.SetPos(tool, x, y); confirm "
                        "with GetPosTable and a liberal position parser.",
         "tags": ["fusion", "unreliable-return"],
+        "submit": "bug",
     },
     {
         "symbol": "Timeline.GetTimelineByName",
@@ -117,6 +137,7 @@ API_TRUTH: List[Dict[str, Any]] = [
         "reality": "Does not exist. Timelines are looked up by index.",
         "recommended": "Iterate GetTimelineByIndex(1..GetTimelineCount()).",
         "tags": ["missing-method", "timeline"],
+        "submit": "missing",
     },
     {
         "symbol": "Project render methods (AddRenderJob, SetRenderSettings, ...)",
@@ -136,6 +157,7 @@ API_TRUTH: List[Dict[str, Any]] = [
         "recommended": "Treat a trailing ellipsis as truncation (see "
                        "media_pool_item get_transcription's `truncated` flag).",
         "tags": ["transcription", "truncation"],
+        "submit": "bug",
     },
     {
         "symbol": "ProjectManager.CreateProject (with a dirty Untitled project)",
@@ -147,6 +169,7 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "without a prompt, then CreateProject; restore with "
                        "LoadProject afterward.",
         "tags": ["project", "modal", "silent-failure"],
+        "submit": "bug",
     },
     {
         "symbol": "Timeline.InsertFusionCompositionIntoTimeline",
@@ -179,6 +202,163 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "instead (exposed as media_pool append_to_timeline clip_infos). "
                        "See issue #74.",
         "tags": ["missing-method", "timeline", "title", "generator", "track"],
+        "submit": "missing",
+        "issue": 74,
+    },
+    {
+        "symbol": "Per-clip audio channel-format conversion (Stereo<->Mono)",
+        "object": "MediaPoolItem / TimelineItem",
+        "reality": "No scripting method converts an individual clip's audio "
+                   "channel format. ConvertTimelineToStereo is timeline-wide, and "
+                   "CreateStereoClip builds a 3D *visual* stereoscopic clip, not an "
+                   "audio mono->stereo change. The Edit-page 'Clip Attributes > "
+                   "Audio' channel mapping is UI-only.",
+        "recommended": "Use the supported surface: timeline add_track with audioType "
+                       "(create mono/stereo tracks), get_track_sub_type (query "
+                       "format), convert_to_stereo (timeline-wide), and "
+                       "timeline_item get_source_audio_channel_mapping. Per-clip "
+                       "conversion is not possible. See issue #73.",
+        "tags": ["missing-method", "audio", "channel"],
+        "submit": "missing",
+        "issue": 73,
+    },
+    {
+        "symbol": "Native multicam clip creation",
+        "object": "MediaPool",
+        "reality": "There is no method to create a native multicam clip from a set "
+                   "of angles. Angles can be stacked onto tracks programmatically, "
+                   "but the multicam-clip conversion is a UI-only step.",
+        "recommended": "Prepare a stacked timeline (media_pool setup_multicam_timeline) "
+                       "and finish the multicam-clip conversion in the Resolve UI.",
+        "tags": ["missing-method", "media-pool", "multicam"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Transition create / copy / clone",
+        "object": "Timeline / TimelineItem",
+        "reality": "The scripting API exposes no method to add, read, copy, or "
+                   "clone an edit transition (cross-dissolve, etc.). Transitions "
+                   "applied in the UI are invisible to and unmodifiable by scripts.",
+        "recommended": "Apply/duplicate transitions in the Resolve UI; no scripted "
+                       "equivalent exists.",
+        "tags": ["missing-method", "timeline", "transition"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Cloud project enumeration / export / user management",
+        "object": "ProjectManager",
+        "reality": "Only CreateCloudProject, LoadCloudProject, ImportCloudProject "
+                   "and RestoreCloudProject exist. There is no GetCloudProjectList "
+                   "(list available cloud projects), no ExportToCloud, and no "
+                   "Add/RemoveUserToCloudProject — so cloud collaboration can't be "
+                   "fully automated.",
+        "recommended": "Drive cloud project listing, export, and collaborator "
+                       "management from the Resolve UI; only create/load/import/"
+                       "restore are scriptable.",
+        "tags": ["missing-method", "project", "cloud"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "TimelineItem trim / move / re-time (no position setters)",
+        "object": "TimelineItem",
+        "reality": "TimelineItem exposes GetStart, GetEnd, GetDuration, "
+                   "GetLeftOffset, GetRightOffset and GetSourceStart/EndFrame, but "
+                   "NO matching setters. A clip cannot be trimmed, slipped, slid, "
+                   "rolled, moved to another time/track, or have its duration "
+                   "changed once it is on the timeline. Verified via dir() on "
+                   "Resolve 21.0.0 (getters only).",
+        "recommended": "Do edit-point adjustments in the Resolve UI, or rebuild the "
+                       "timeline from MediaPool.AppendToTimeline clipInfos with the "
+                       "desired startFrame/endFrame/recordFrame.",
+        "tags": ["missing-method", "timeline", "edit", "trim"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Razor / blade / split a timeline item",
+        "object": "Timeline / TimelineItem",
+        "reality": "There is no method to split/cut/blade a clip at a given frame. "
+                   "Verified absent on Timeline and TimelineItem (dir(), 21.0.0).",
+        "recommended": "Split in the Resolve UI, or construct the cut up-front by "
+                       "appending two clipInfos with the desired in/out points.",
+        "tags": ["missing-method", "timeline", "edit"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Clip speed / retime ratio and speed ramps",
+        "object": "TimelineItem",
+        "reality": "SetProperty exposes only retime *quality* (RetimeProcess, "
+                   "MotionEstimation) and transform/crop/composite/opacity keys — "
+                   "not the speed value itself. There is no way to set a clip to a "
+                   "given % speed, reverse it, or author a speed ramp. Verified "
+                   "against the documented SetProperty key list (21.0.0).",
+        "recommended": "Set clip speed/retime in the Resolve UI; no scripted "
+                       "equivalent exists.",
+        "tags": ["missing-method", "timeline", "retime", "speed"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Color node graph editing and primary grade values",
+        "object": "Graph / TimelineItem",
+        "reality": "The Graph object exposes node enable/label/count, LUT get/set, "
+                   "cache mode, ResetAllGrades, ApplyGradeFromDRX and "
+                   "ApplyArriCdlLut; TimelineItem adds SetCDL, CopyGrades and color "
+                   "versions. But you cannot add, delete, or connect nodes, and you "
+                   "cannot read or write primary grade values (lift/gamma/gain/"
+                   "offset/contrast/curves/qualifiers/power windows). Grading is "
+                   "limited to CDL, whole-grade DRX/LUT application and copying.",
+        "recommended": "Build node trees and dial grades in the Resolve UI or via "
+                       "DRX/CDL/LUT import; per-parameter grade control is not "
+                       "scriptable.",
+        "tags": ["missing-method", "color", "grade", "node"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Fairlight audio levels / pan / EQ / automation / FairlightFX",
+        "object": "TimelineItem / Timeline",
+        "reality": "There is no API to set clip or track volume, pan, EQ, audio "
+                   "automation, or to add/configure FairlightFX. SetProperty covers "
+                   "video transform only; the audio surface is read-only "
+                   "(GetSourceAudioChannelMapping, GetAudioMapping, voice "
+                   "isolation). Verified via dir() + SetProperty docs (21.0.0).",
+        "recommended": "Mix in the Fairlight UI; only voice-isolation state and "
+                       "channel-mapping reads are scriptable.",
+        "tags": ["missing-method", "audio", "fairlight"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Proxy / optimized-media generation",
+        "object": "MediaPoolItem",
+        "reality": "Only LinkProxyMedia, UnlinkProxyMedia and "
+                   "LinkFullResolutionMedia exist (attach/detach EXISTING proxies). "
+                   "There is no method to generate proxies or optimized media. "
+                   "Verified via MediaPoolItem dir() (21.0.0).",
+        "recommended": "Trigger proxy/optimized-media generation from the Resolve "
+                       "UI; scripting can only link/unlink already-rendered proxies.",
+        "tags": ["missing-method", "media-pool", "proxy"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Insert / Overwrite / Replace / Fit-to-Fill edit modes",
+        "object": "MediaPool / Timeline",
+        "reality": "MediaPool.AppendToTimeline (with optional recordFrame "
+                   "positioning) is the only programmatic placement. The standard "
+                   "edit modes — insert (ripple), overwrite, replace, fit-to-fill, "
+                   "place-on-top — have no API. Verified via dir() (21.0.0).",
+        "recommended": "Position clips with AppendToTimeline clipInfo recordFrame, "
+                       "or perform insert/overwrite/replace edits in the Resolve UI.",
+        "tags": ["missing-method", "timeline", "edit"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Smart Bins / Power Bins creation",
+        "object": "MediaPool",
+        "reality": "Only AddSubFolder (a regular bin) exists. Smart Bins (rule-"
+                   "based) and Power Bins (cross-project) cannot be created or "
+                   "configured. Verified via MediaPool dir() (21.0.0).",
+        "recommended": "Create Smart/Power Bins in the Resolve UI; only regular "
+                       "bins are scriptable.",
+        "tags": ["missing-method", "media-pool", "bins"],
+        "submit": "missing",
     },
     {
         "symbol": "subprocess inheriting stdin under the MCP stdio server",
@@ -212,3 +392,17 @@ def lookup_api_truth(query: Optional[str] = None) -> List[Dict[str, Any]]:
         if q in hay:
             out.append(e)
     return out
+
+
+def submittable_limitations() -> Dict[str, List[Dict[str, Any]]]:
+    """Group ``submit``-tagged entries for the Blackmagic-facing report.
+
+    Returns ``{"missing": [...], "bug": [...]}`` — entries Blackmagic should add
+    vs. behaviors they should fix — preserving API_TRUTH order within each group.
+    """
+    groups: Dict[str, List[Dict[str, Any]]] = {"missing": [], "bug": []}
+    for e in API_TRUTH:
+        kind = e.get("submit")
+        if kind in groups:
+            groups[kind].append(e)
+    return groups