davinci-resolve-mcp 2.93.0 → 2.93.2

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 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.93.2
+
+Documentation and ledger correction, validated live against DaVinci Resolve
+Studio **21.0.4.5** (version read from the running instance, not assumed).
+
+- **A false "verified live" workaround for issue #74 is withdrawn, and the real
+  mechanism is documented.** `resolve-advanced/vendor/drp-format/README.md`
+  claimed that locking the video tracks below your target redirects
+  `InsertFusionTitleIntoTimeline` to that track, and called it verified live. It
+  shipped with no test, log, or evidence file, and it contradicted the
+  `api_truth` ledger entry written twelve days earlier from an explicit test
+  matrix. A third party independently reproduced the ledger's version on
+  21.0.4.5, so the two claims were re-measured on one rig, one fresh
+  3-video-track timeline per arm so no insert could fail on a collision:
+
+  | Arm | Setup | `InsertFusionTitleIntoTimeline("Text+")` |
+  |---|---|---|
+  | A | nothing locked | lands on **V1** |
+  | B | V1 locked via `Timeline.SetTrackLock` | returns **`None`** |
+  | C | V1 locked by **clicking the padlock in the UI** | returns **`None`** |
+  | D | nothing locked, source patch dragged to V2 in the UI | lands on **V2** |
+
+  B and C are identical, which kills the standing theory that a GUI lock
+  advances the selector where the API lock does not. Locking blocks the target;
+  it never re-targets. The README claim is withdrawn as false and the ledger
+  entry — previously measured on 21.0.0 — is confirmed on the newest build.
+
+- **The destination is the patch panel, not the lock state.** Arm D is the
+  finding: dragging the source patch badge onto V2 in the Edit page sends the
+  next insert to V2. The per-track badge column in the track header is the
+  auto-track-selector toggle; the source patch badge appears only on the patched
+  track, and dragging that is what re-targets. The capability exists in the
+  application and is reachable only by GUI automation — so the request to
+  Blackmagic is read/write access to the patch panel, which is smaller and
+  better defined than adding `trackIndex` to all six `Insert*IntoTimeline`
+  methods. The route is unverifiable from the API side (nothing in the scripting
+  surface confirms where the selector landed), so read the landing track back
+  with `TimelineItem.GetTrackTypeAndIndex()` and treat a wrong track as a
+  failure. Offline, `drp place_fusion_title` remains deterministic.
+
+## What's New in v2.93.1
+
+Documentation only; no behavior changed and no Resolve validation required.
+
+- **The immediate-retake blind spot is now in the media-analysis guide.** Issue
+  #125 asked for three things; the `rank_takes` caveat and the
+  `possible_swallowed_retakes` flag shipped in v2.83.0, but the documented
+  limitation never did — the guide had zero mentions of retakes, so the only way
+  to learn that word timestamps are untrustworthy around an immediate re-read was
+  to already be looking at output that flagged one. The new section states what
+  whisper does (emits a re-read sentence once, aligns it to the first take, and
+  absorbs pause-plus-second-take into a single word), names every feature that
+  inherits it, and records why silence detection cannot substitute — the
+  swallowed span measured **−12.1 dB** against adjacent speech at −16.7 dB, and a
+  silence pass recalled **3 of 17**. It is explicit that the flag is never a cut
+  point, and that no flags is weak evidence rather than proof.
+
 ## What's New in v2.93.0
 
 `source_end` is a source frame again, and the guidance v2.91.0 shipped about WAV

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.93.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.93.2-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(353%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.93.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.93.2-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(353%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v2.93.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.93.2 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/guides/media-analysis-guide.md

@@ -798,6 +798,48 @@ When analysis reveals potential issues, always alert the user:
 
 ---
 
+## Known Limitation: word timestamps lie around immediate retakes
+
+**Transcripts do not report a re-read sentence twice.** When a speaker
+immediately re-reads a line — the ordinary way people self-correct while
+recording — whisper emits the text **once**, aligns it to the **first** take, and
+absorbs "pause + entire second take" into the duration of a **single word**.
+Measured on real Chinese material: one single-character word spanning **6.06 s**,
+another **4.4 s**, where real speech runs 4–7 chars/s. Reproduced on English with
+the identical signature: the word *"lives"* carrying **2.42 s**. Issue #125.
+
+Everything downstream of the transcript inherits it:
+
+- **Retake and false-start detection never fires** for this class — the
+  transcript says the sentence was spoken cleanly, once.
+- **`rank_takes` undercounts restarts**, so a take that stumbled and recovered
+  can outscore one that did not. Its `caveat` field says so at runtime.
+- **Word-level cuts near a swallow land inside speech**, because the timestamps
+  inflate around the absorption point.
+- **`plan_transcript_tighten` is structurally blind here** — its false-start
+  heuristic only sees restarts the transcript reports.
+
+**Silence detection cannot rescue it.** The swallowed span is not silence: in the
+original measurement it was breathing and keyboard noise peaking at **−12.1 dB**,
+*louder* than the adjacent real speech at −16.7 dB. A silence-based pass recalled
+**3 of 17** ground-truth instances at any threshold.
+
+**What the analysis output gives you.** Transcript-reading results carry
+`possible_swallowed_retakes`: words whose duration exceeds an absolute bar
+(default **1.2 s**), which is language-agnostic and computed from data the
+pipeline already has. Treat it as a **flag, not a cut point** — where inside the
+stretched word the second take begins is precisely what the swallow destroyed, so
+those need a human ear or a re-transcription of the isolated window before
+anything is removed.
+
+**Read the empty case correctly.** No flags is *weak evidence, not proof*. A
+swallow smeared across several words instead of concentrated in one will not
+clear the bar, and that case is expected to exist. The bar itself is a usable
+default chosen from limited data — 17 real instances in Chinese, confirmed by a
+single genuine English swallow in synthetic material — not a tuned constant.
+
+---
+
 ## Key Principles
 
 - **The source is sacred.** Read from source files, write only to analysis sidecars unless a visual analysis workflow needs sampled frames/contact sheets in a separate analysis directory. Confirmed metadata publishing writes to Resolve's project database, not source media. `analyze_media` can opt out with `include_visuals=false`.

package/docs/reference/api-limitations.md

@@ -66,8 +66,8 @@ equivalent, blocking full automation.
 ### 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.
+- **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). RE-MEASURED on Studio 21.0.4.5 (2026-08-12, version read live), one fresh 3-video-track timeline per arm so no insert could fail on a collision: nothing locked -> lands V1; V1 locked via SetTrackLock -> returns None; V1 locked by CLICKING THE PADLOCK IN THE UI -> returns None, IDENTICAL to the API lock. That kills the recurring theory that the GUI lock advances the selector where the API lock does not — it does not, and a revision of resolve-advanced/vendor/drp-format/README.md that claimed otherwise as 'verified live' has been withdrawn as false. WHAT DOES WORK, and it is the whole mechanism: dragging the SOURCE PATCH badge onto V2 in the Edit-page patch panel sends the next insert to V2 (measured, same rig, nothing locked). The destination is the patch panel, never the lock state. In the track header the per-track badge column is the auto-track-selector toggle, while the source patch badge appears only on the patched track and dragging THAT is what re-targets. So the capability exists in the application and is reachable only by GUI automation; exposing read/write on the patch panel is a smaller, better-defined API request than adding trackIndex to all six Insert*IntoTimeline methods.
+- **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). Do NOT reach for track locking as a bypass in either form — it blocks the insert rather than re-targeting it. If a title genuinely must land on a chosen track of the OPEN timeline, the only route is GUI automation of the patch panel, and it is unverifiable from the API side: nothing in the scripting surface can confirm the selector went where you dragged it, so read the landing track back with TimelineItem.GetTrackTypeAndIndex() and treat a wrong track as a failure. For anything that can be built offline, place titles by track and frame with the advanced server's drp place_fusion_title instead. See issue #74.
 - **Reference:** [issue #74](https://github.com/samuelgursky/davinci-resolve-mcp/issues/74)
 - **Tags:** missing-method, timeline, title, generator, track
 

package/install.py

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

package/resolve-advanced/vendor/drp-format/README.md

@@ -87,10 +87,38 @@ Plus the full **DRX grade** surface (`createSimpleGrade`, curves/qualifiers/wind
 ## Live-edit recipe (the one thing that needs Resolve running)
 
 **#74 — insert a Text+/generator on a chosen track of the OPEN timeline.** The API's
-`InsertFusionTitleIntoTimeline` takes no track arg (always the lowest unlocked video track). Bypass:
-via computer-use, **lock the video tracks below your target**, then call `timeline.insert_fusion_title` —
-it lands on the chosen track. Verified live. (For export-based workflows, `place_fusion_title` does this
-offline.)
+`InsertFusionTitleIntoTimeline` takes no track arg; the insert lands on the Source/Auto Track
+Selector's current target (V1 in practice), which no API can read or set.
+
+> **Track locking does not redirect the insert — through the API *or* the UI.** An earlier
+> revision of this README claimed that locking the tracks below your target via computer-use
+> redirects the insert, and called it verified live. That claim shipped with no test or evidence
+> and is **withdrawn as false.** Measured 2026-08-12 on **Studio 21.0.4.5** (version read live,
+> not assumed), one fresh 3-video-track timeline per arm so no insert could fail on a collision:
+>
+> | Arm | Setup | `InsertFusionTitleIntoTimeline("Text+")` |
+> |---|---|---|
+> | A | nothing locked | lands on **V1** |
+> | B | V1 locked via `Timeline.SetTrackLock` | returns **None**, nothing placed |
+> | C | V1 locked by **clicking the padlock in the UI** | returns **None**, nothing placed |
+> | D | nothing locked, source patch dragged to V2 in the UI | lands on **V2** |
+>
+> B and C are identical, so the GUI-lock hypothesis is dead: locking blocks the target, it never
+> re-targets. This also reproduces issue #74 (measured on 21.0.0) on the newest build.
+>
+> **D is the real control.** The destination is the Edit-page patch panel, not the lock state.
+> Dragging the source patch onto V2 sends the insert to V2. In the header, the x-column of
+> per-track badges is the auto-track-selector toggle; the source patch badge appears only on the
+> patched track, and dragging it is what re-targets. The API can neither read nor set any of it —
+> which is exactly the gap to put in front of Blackmagic, and a far smaller ask than new
+> parameters on all six `Insert*IntoTimeline` methods.
+>
+> So a live-edit recipe does exist, but it is **GUI automation of the patch panel**, not track
+> locking. Treat it as such: it is not verifiable from the API side, since nothing in the
+> scripting surface can confirm the selector landed where you dragged it.
+
+For export-based workflows, `place_fusion_title` places a title on any track at an exact frame
+offline, with no selector involved.
 
 ---
 

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.93.0"
+VERSION = "2.93.2"
 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 353-tool granular server instead
 """
 
-VERSION = "2.93.0"
+VERSION = "2.93.2"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -560,12 +560,42 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "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).",
+                   "and MoveClips don't apply). RE-MEASURED on Studio 21.0.4.5 "
+                   "(2026-08-12, version read live), one fresh 3-video-track "
+                   "timeline per arm so no insert could fail on a collision: "
+                   "nothing locked -> lands V1; V1 locked via SetTrackLock -> "
+                   "returns None; V1 locked by CLICKING THE PADLOCK IN THE UI -> "
+                   "returns None, IDENTICAL to the API lock. That kills the "
+                   "recurring theory that the GUI lock advances the selector where "
+                   "the API lock does not — it does not, and a revision of "
+                   "resolve-advanced/vendor/drp-format/README.md that claimed "
+                   "otherwise as 'verified live' has been withdrawn as false. "
+                   "WHAT DOES WORK, and it is the whole mechanism: dragging the "
+                   "SOURCE PATCH badge onto V2 in the Edit-page patch panel sends "
+                   "the next insert to V2 (measured, same rig, nothing locked). The "
+                   "destination is the patch panel, never the lock state. In the "
+                   "track header the per-track badge column is the auto-track-selector "
+                   "toggle, while the source patch badge appears only on the patched "
+                   "track and dragging THAT is what re-targets. So the capability "
+                   "exists in the application and is reachable only by GUI "
+                   "automation; exposing read/write on the patch panel is a smaller, "
+                   "better-defined API request than adding trackIndex to all six "
+                   "Insert*IntoTimeline methods.",
         "recommended": "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.",
+                       "Do NOT reach for track locking as a bypass in either form — "
+                       "it blocks the insert rather than re-targeting it. If a title "
+                       "genuinely must land on a chosen track of the OPEN timeline, "
+                       "the only route is GUI automation of the patch panel, and it "
+                       "is unverifiable from the API side: nothing in the scripting "
+                       "surface can confirm the selector went where you dragged it, "
+                       "so read the landing track back with "
+                       "TimelineItem.GetTrackTypeAndIndex() and treat a wrong track "
+                       "as a failure. For anything that can be built offline, place "
+                       "titles by track and frame with the advanced server's "
+                       "drp place_fusion_title instead. See issue #74.",
         "tags": ["missing-method", "timeline", "title", "generator", "track"],
         "submit": "missing",
         "issue": 74,

package/src/utils/delivery_targets.py

@@ -471,33 +471,35 @@ DELIVERY_TARGETS: Dict[str, DeliveryTarget] = {
     # ── Mastering: DNxHR family ─────────────────────────────────────────────
     "dnxhr_lb_master": _dnxhr(
         "dnxhr_lb_master", "LB",
-        ("DNxHR LB", "DNxHR_LB"),
+        ("DNxHRLB", "Avid DNxHR LB 12-bit", "DNxHR LB"),
         "Low-bandwidth DNxHR. Offline/review, not finishing.",
     ),
     "dnxhr_sq_master": _dnxhr(
         "dnxhr_sq_master", "SQ",
-        ("DNxHR SQ", "DNxHR_SQ"),
+        ("DNxHRSQ", "Avid DNxHR SQ 12-bit", "DNxHR SQ"),
         "Standard-quality DNxHR. Avid-family review and distribution.",
     ),
     "dnxhr_hq_master": _dnxhr(
         "dnxhr_hq_master", "HQ",
-        ("DNxHR HQ", "DNxHR_HQ"),
+        ("DNxHRHQ", "Avid DNxHR HQ 12-bit", "DNxHR HQ"),
         "High-quality 8-bit DNxHR. Common Avid mezzanine.",
     ),
-    # Live matrix carries a bit depth in the label — plain "DNxHR HQX" does not exist.
+    # Codec IDS proved stable across 19.1.3.7 -> 21.0.4.5 while DESCRIPTIONS did not:
+    # every DNx description gained an "Avid " prefix in 21.x, and plain "DNxHR HQX"
+    # never existed. So the id leads each candidate list and descriptions follow.
     "dnxhr_hqx_master": _dnxhr(
         "dnxhr_hqx_master", "HQX 10-bit",
-        ("DNxHR HQX 10-bit", "DNxHRHQX_10", "DNxHR HQX 12-bit", "DNxHRHQX_12", "DNxHR HQX"),
+        ("DNxHRHQX_10", "Avid DNxHR HQX 10-bit", "DNxHR HQX 10-bit", "DNxHRHQX_12", "DNxHR HQX"),
         "10-bit DNxHR. The DNx tier to use for finishing and HDR.",
     ),
     "dnxhr_444_master": _dnxhr(
         "dnxhr_444_master", "444 12-bit",
-        ("DNxHR 444 12-bit", "DNxHR444_12", "DNxHR 444 10-bit", "DNxHR444_10", "DNxHR 444"),
+        ("DNxHR444_12", "Avid DNxHR 444 12-bit", "DNxHR 444 12-bit", "DNxHR444_10", "DNxHR 444"),
         "4:4:4 12-bit DNxHR. Highest DNx tier for finishing.",
     ),
     "dnxhd_1080p220_10_master": _dnxhr(
         "dnxhd_1080p220_10_master", "HD 1080p 220 10-bit",
-        ("DNxHD 1080p 220/185/175 10-bit", "DNxHD1080p220_10"),
+        ("DNxHD1080p220_10", "Avid DNxHD 1080p 220/185/175 10-bit", "DNxHD 1080p 220/185/175 10-bit"),
         "HD-era 10-bit DNxHD for Avid finishing at 1920x1080.",
         width=1920,
         height=1080,
@@ -561,7 +563,7 @@ DELIVERY_TARGETS: Dict[str, DeliveryTarget] = {
         describe="Avid-native handoff: MXF OP-Atom essence, DNxHR HQ.",
         tier="broadcast",
         format_candidates=("MXF OP-Atom", "MXF_OP_Atom", "mxf_op_atom"),
-        codec_candidates=("DNxHR HQ", "DNxHR_HQ"),
+        codec_candidates=("DNxHRHQ", "Avid DNxHR HQ 12-bit", "DNxHR HQ"),
         qc_container="mxf",
         qc_codec="dnxhd",
         audio_channels=2,