davinci-resolve-mcp 2.67.0 → 2.68.0

package/CHANGELOG.md

@@ -2,6 +2,123 @@
 
 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.68.0
+
+Six engines that let an agent judge its own output before shipping it — audio
+loudness, silence calibration, image QC, transcript editing, captions — plus the
+**in-app bridge**, which reaches the **free edition** of DaVinci Resolve, whose
+external scripting API refuses foreign processes entirely.
+
+### Added
+
+- **Audio delivery QC.** Delivery targets carry a named loudness contract
+  (`web`, `podcast`, `ebu_r128`, `atsc_a85`, `ott_dialogue_gated`) and project it
+  into the existing `loudness_qc` vocabulary. Dialogue-gated standards emit no
+  gradeable `integrated` figure — `loudness_qc` measures full-program, so grading
+  a dialogue-gated number against it produces a verdict that means nothing; it
+  travels as advisory metadata with the reason stated. No shipped target names a
+  standard, because a ProRes master has no inherent programme loudness.
+  `render(action='list_loudness_standards')`.
+- **Auto-calibrated silence gate.** `plan_silence_ripple` derives the threshold
+  from each clip's own dynamics instead of a fixed −30 dB. The metric is `astats`
+  **RMS trough** paired with RMS peak: `mean_volume` tracks programme level, and
+  `Noise floor dB` moved 19 dB between two fixtures sharing an identical noise
+  bed purely because one was quieter for longer. Against ground truth the fixed
+  threshold was wrong on all four fixtures. When calibration cannot be trusted
+  the item is **kept whole** rather than stripped — a fixed threshold applied to
+  material it does not suit is not a degraded answer, it is a wrong one.
+- **Image QC.** `media_analysis(action='assess_grade')` gives an agent
+  deterministic grounds to reject its own grade: tonal frame, noise
+  amplification, banding, highlight posterization and clipping growth, with
+  validated **CIEDE2000** (all 33 Sharma/Wu/Dalal reference pairs to 4 dp). A
+  clean grade costs zero tokens; vision is spent only where the numbers cannot
+  settle it. Non-display-referred working spaces are **refused, never guessed** —
+  the right transform depends on camera and project colour management, which a
+  frame cannot tell you.
+- **Word-level transcript editing.** `edit_engine(action='plan_transcript_tighten')`
+  removes fillers, false starts and over-long pauses at word boundaries with a
+  reason per cut, and `search_spoken_content` searches word timings across a
+  whole shoot to build selects. A lexical axis alongside `find_similar`'s
+  semantic-visual one.
+- **Captions.** `media_analysis(action='generate_captions')` emits SRT and WebVTT
+  under broadcast line rules, plus chapters and YouTube description text.
+- **The in-app bridge — live read and write control of the FREE edition.**
+  Opt-in with `DAVINCI_RESOLVE_BRIDGE=1`; unset changes nothing for existing
+  installs. A script launched from Workspace ▸ Scripts is handed the live
+  `resolve` object on any edition and re-exports it over an authenticated
+  loopback listener, which `connect_resolve` uses as a third transport beside
+  Local and Network. Existing call sites need no changes. This is the documented
+  in-app path, not a licence circumvention — but Blackmagic could close it, so
+  treat it as supported-until-it-is-not.
+- **`shutdown` and `reload` for the bridge.** The launcher blocks (correctly — a
+  Scripts-menu script is a child process, so a daemon thread dies the instant it
+  returns), which used to mean a stale in-Resolve copy could only be replaced by
+  quitting Resolve. `reload` re-imports the runtime from disk in place, and
+  refuses before stopping if the new sources will not compile.
+
+### Fixed
+
+- **The bridge was unreachable on the machine it exists for.** `_try_connect`
+  returned on `dvr_script is None` before calling `connect_resolve`, the function
+  that accepts None in bridge mode. Blackmagic's scripting module ships with the
+  *installer*, not the App Store build, so a free-edition-only machine has no
+  `Developer/Scripting/Modules` tree and the import fails. Verified by blocking
+  the import against a healthy live bridge: `get_resolve()` answered None.
+- **Auto-launch started the wrong Resolve, or one nobody asked for.** The macOS
+  path list contained only the installer location, so a free-only machine found
+  nothing and a machine with both always started Studio. In bridge mode it now
+  refuses outright: launching cannot create a listener that only a Scripts-menu
+  run creates.
+- **Interchange export over the bridge was degrading silently.** Resolve's API
+  constants (`EXPORT_AAF`, `AUDIO_SYNC_*`) are plain attributes and `dir()` does
+  not list them — measured on 21.0.3.7, `dir(resolve)` returns 34 names with no
+  `EXPORT_*` among them while the constants read back as real values. The proxy
+  could only call methods, so `hasattr` said False and the server fell through to
+  handing Resolve the bare string `"EXPORT_AAF"`.
+- **The proxy broke every chain longer than one call.** Every live Resolve object
+  reports `type(obj).__name__ == "PyRemoteObject"` — root 34 methods, Project 49,
+  TimelineItem 88, one class name — so caching method sets on it let the first
+  object touched define `hasattr` for everything after. Method sets are now keyed
+  on provenance, and absence is re-verified against the object itself.
+- **Bridge error codes never crossed the transport.** Every surface code was
+  flattened to `operation_failed`, so `stale_handle` (re-fetch) and
+  `ambiguous_locator` (disambiguate) arrived as one undifferentiated failure.
+
+### Validated live
+
+On **DaVinci Resolve 21.0.3.7 (App Store, free, sandboxed)**, with Blackmagic's
+scripting module blocked to reproduce a free-only machine: 34 tools, 583 declared
+actions, **165 read-shaped actions attempted, 145 clean, zero bridge-attributable
+failures**; 109 of the 112 API read methods the tools actually call exercised on
+the live object graph; a render completed to a non-empty file; AAF/DRT/EDL/FCPXML
+all written by `Timeline.Export`; 400 clips appended in 1.23 s and enumerated at
+0.81 ms/item; an evicted handle refusing with `stale_handle` rather than
+resolving to another object; and reads *and* writes continuing to work with a
+native file dialog open, because the bridge runs in its own process.
+
+`scripts/bridge_differential.py --mode differential` diffs the bridge against
+native scripting on one Studio instance. That comparison has **not** been run
+yet, so the evidenced claim is that the bridge carries the surface the tools use
+on the free edition — not that it is byte-identical to native scripting.
+
+## What's New in v2.67.1
+
+Documentation correction. No code changes — v2.67.0 already ships the correct
+behavior.
+
+### Changed
+
+- **`docs/kernels/render-deliver-kernel.md` no longer quotes a format/codec count
+  as portable.** It presented "23 formats and 99 format/codec pairs" as the
+  expected probe result; a live probe on Studio 19.1.3.7 found 20 formats and 271
+  pairs. Both mentions now carry the build they came from and point at probing
+  the machine in hand (`probe_render_matrix`, or `list_delivery_targets` with
+  `check_availability`) instead of comparing against a fixed number.
+- The kernel's boundary list now records the two traps the delivery-target work
+  verified live: codec **descriptions are not codec ids** (`H.264` vs `H264`, not
+  only the ProRes family), and some formats expose **no codecs at all** (`Wave`,
+  `GIF` on 19.1.3.7) and cannot be selected through this API.
+
 ## What's New in v2.67.0
 
 Adds **delivery targets** — named render intents that carry their own QC spec —

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.67.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.68.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)
@@ -22,7 +22,7 @@ A local browser control panel ships with the server for inspecting Resolve state
 npx davinci-resolve-mcp setup
 ```
 
-Before connecting, open DaVinci Resolve Studio and set **Preferences > General > External scripting using** to **Local**. The npm launcher installs a managed copy under your user application-data directory, then runs the universal Python installer. The installer creates a virtual environment, detects Resolve paths, and can configure Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Continue, Cline, Roo Code, OpenCode, and JetBrains IDEs.
+Before connecting, open DaVinci Resolve Studio and set **Preferences > General > External scripting using** to **Local**. (On the **free edition** that preference does not help — see [Free edition](#free-edition-in-app-bridge) below.) The npm launcher installs a managed copy under your user application-data directory, then runs the universal Python installer. The installer creates a virtual environment, detects Resolve paths, and can configure Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Continue, Cline, Roo Code, OpenCode, and JetBrains IDEs.
 
 For source installs:
 
@@ -36,6 +36,31 @@ For platform paths, client-specific config, and manual setup, see [Installation
 
 The installer and server check the latest GitHub release for MCP updates. Checks are best-effort and throttled; the server never blocks MCP startup for a prompt. The installer can prompt, snooze, ignore a release, disable checks, or apply an opt-in safe auto-update for clean git checkouts.
 
+## Free edition (in-app bridge)
+
+Blackmagic gates *external* scripting to Studio: on the free edition
+`scriptapp("Resolve")` refuses a foreign process, whatever the preference says.
+The **Workspace ▸ Scripts** menu is not gated — a script launched from it is
+handed the live `resolve` object on any edition — so the server can reach the
+free edition through a small script that runs *inside* Resolve and re-exports it
+over an authenticated loopback listener.
+
+```bash
+python scripts/install_resolve_bridge.py
+# restart Resolve, open a project, then: Workspace > Scripts > resolve_bridge
+export DAVINCI_RESOLVE_BRIDGE=1      # opt-in; unset changes nothing
+```
+
+Requires a **framework Python** (python.org). Resolve enumerates `.py` scripts
+only when it finds one — Homebrew, pyenv and conda interpreters are not
+detected, and the script silently never appears in the menu. A Lua canary is
+installed alongside so you can tell that apart from a wrong folder.
+
+Validated on free 21.0.3.7 and Studio 19.1.3.7. This is the documented in-app
+path, not a licence circumvention, but Blackmagic could close it — treat it as a
+supported-until-it-is-not tier. Loopback only, HMAC-signed requests, one-use
+nonces.
+
 ## Local Control Panel
 
 Launch the single-user local control panel from the repository root:

package/docs/SKILL.md

@@ -19,6 +19,26 @@ configured to the Resolve host IP (use `127.0.0.1` on the same machine). The
 server auto-launches Resolve if it is not running, but that first connection can
 take up to 60 seconds.
 
+**Free edition.** Both of those preferences are Studio features; on the free
+edition `scriptapp("Resolve")` refuses a foreign process regardless. A third
+transport reaches it — a script run from **Workspace ▸ Scripts** is handed the
+live `resolve` object on any edition and re-exports it over an authenticated
+loopback listener. Install with `python scripts/install_resolve_bridge.py`, start
+it from that menu, and set `DAVINCI_RESOLVE_BRIDGE=1`. Existing tool call sites
+work unchanged. Two things to know when diagnosing it:
+
+- Resolve lists `.py` scripts only when it can find a **framework Python**
+  (python.org). Homebrew/pyenv/conda are not detected and the script simply never
+  appears, with no error. The installer preflights this and ships a Lua canary,
+  which always lists, so "Python not detected" is distinguishable from "wrong
+  folder".
+- The in-Resolve runtime is a **copy taken at install time**. After changing the
+  repository, re-run the installer and then ask the running bridge to reload —
+  it re-imports from disk in place, so Resolve does not need restarting.
+
+The bridge is a documented in-app path rather than a licence circumvention, but
+Blackmagic could close it; treat it as a supported-until-it-is-not tier.
+
 Network scripting permits remote control of Resolve. Use Local mode when remote
 access is unnecessary; otherwise restrict access with host firewall and network
 controls.

package/docs/kernels/render-deliver-kernel.md

@@ -79,7 +79,17 @@ come from one definition.
   readback as version/page dependent and still validates and applies settings
   through `SetRenderSettings`.
 - Render format and codec availability is machine, OS, license, and plugin
-  dependent. The final live probe found 23 formats and 99 format/codec pairs.
+  dependent, and it varies a lot: a live probe found 23 formats / 99 pairs on one
+  build, and 20 formats / 271 pairs on Studio 19.1.3.7. Treat neither figure as
+  the expected count — probe the machine you are on
+  (`probe_render_matrix`, or `list_delivery_targets` with `check_availability`).
+- Codec **descriptions are not codec ids**. `GetRenderCodecs` returns
+  `{description: id}` and every setter wants the id, so the name shown in the
+  Deliver page is rejected — for `H.264` (`H264`) just as much as for
+  `Apple ProRes 422 HQ` (`ProRes422HQ`). `src/utils/render_ids.py` normalizes
+  either form; see `docs/reference/api-limitations.md`.
+- Some formats expose **no codecs at all** (`Wave`, `GIF` on 19.1.3.7) and then
+  reject every codec value, so they cannot be selected through this API.
 - Some settings may be accepted but not readable for coercion checks on builds
   where `GetRenderSettings` is unavailable.
 - Quick Export actual execution is intentionally gated behind
@@ -151,6 +161,8 @@ Result:
 
 The live harness created and deleted a disposable project named
 `_mcp_render_deliver_probe_1778342107`, generated synthetic media, probed 23
-formats and 99 format/codec pairs, rendered one tiny synthetic output, wrote
+formats and 99 format/codec pairs **on that build** (a later probe on Studio
+19.1.3.7 saw 20 formats / 271 pairs — the counts are not portable), rendered one
+tiny synthetic output, wrote
 JSON and Markdown reports, and removed the generated media and render output
 directories after the report was written.

package/install.py

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