davinci-resolve-mcp 2.213.1 → 2.213.3

package/CHANGELOG.md

@@ -2,6 +2,79 @@
 
 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.213.3 — the capture docstring says what is restored and what is only reset
+
+### Documentation
+
+- **`_playhead_frame_render`'s docstring still said the mark range was not
+  readable.** Since v2.213.2 it is: `Timeline.GetMarkInOut` is read before the
+  capture and put back afterwards, offset into `SetRenderSettings`' absolute
+  frame space. The docstring now lists the three things that actually happen
+  on the way out — format and codec genuinely restored, the mark range
+  restored when one was set (whole timeline as the fallback), and TargetDir
+  and CustomName reset because nothing can read them back — and notes that
+  `GetRenderSettings` is still absent as of 21.1. It is the first thing a
+  caller reads to decide whether `quality="frame"` is safe against their
+  render setup. Contributed in #201 by @billcarroll.
+- **#196 confirmed on Windows.** The reporter pulled v2.213.1 and confirms the
+  keyframe fix renders on Windows, which closes the one platform question the
+  v2.213.1 notes left open.
+
+### Validation
+
+- Docstring only; no behavior changed and no Resolve run required. Full
+  offline suite, drift guards and the advanced Node suite green.
+
+## What's New in v2.213.2 — the full transcript on 21.1, and a frame capture that puts the user's mark range back in the right frame space
+
+Both contributed by @billcarroll (#199, #200).
+
+### Added
+
+- **`media_pool_item get_transcription` reads the whole transcript on Resolve
+  21.1+** through `MediaPoolItem.GetTranscription`, which 21.1 added and which
+  does not truncate: `segments` carries `{start, end, text, speaker}` in
+  **source** timecode, `language` is reported, and `truncated` is False. Pass
+  `include_words` to keep each segment's per-word timings, which are several
+  times the bulk of the text. On 21.0.x it falls back to the `Transcription`
+  clip property exactly as before, and `source` says which route ran. The
+  method is registered in the version ledger as a reported 21.1 surface, so
+  `check_version_support` answers for it. (#199)
+
+### Fixed
+
+- **`timeline_frame capture` flattened a user's mark range to the whole
+  timeline.** Rendering one frame pins the project's render range to that
+  frame, and the cleanup could only reset it to the whole timeline because
+  there is no `GetRenderSettings` to read the previous range from. The mark
+  range is the exception: `Timeline.GetMarkInOut` can be read before the
+  capture, and the user's own range now goes back afterwards. A half-set range
+  (in point only) is still treated as no range, and with no marks set the old
+  whole-timeline fallback applies. (#200)
+- **Adapted on landing: the two calls do not share a frame space.** Resolve
+  documents `GetMarkInOut` relative to the timeline start (its own example is
+  `in: 0, out: 134`), while `SetRenderSettings` takes absolute record frames —
+  measured on Studio 19.1.3.7: on an 86400-start timeline `MarkIn=MarkOut=86420`
+  rendered frame 20 and `MarkIn=MarkOut=20` was silently clamped to the start
+  and rendered frame 0, one frame, no error. Handed back verbatim, a UI-set
+  range would have been "restored" as a clamped range with every readback
+  agreeing. A mark below the timeline start is now offset by the start frame;
+  one at or above it was written absolute (`SetMarkInOut` stores whatever it
+  is given) and is kept. A unit test covers the relative case alongside the
+  PR's absolute, half-set and unreadable cases.
+- **The clamp is now in the API ledger** as a measured bug, with the
+  relative-vs-absolute trap and the remedy, and
+  `docs/reference/api-limitations.md` is regenerated.
+
+### Validation
+
+- Both PRs' unit tests plus the relative-range test. Mark-range frame space
+  measured live on Studio 19.1.3.7 by rendering single frames under both
+  interpretations and matching each against the source frames. The 21.1
+  transcript route cannot be exercised here (no 21.1 build); its ledger entry
+  and `api_truth` say so. Full offline Python suite, drift guards and the
+  advanced Node suite green.
+
 ## What's New in v2.213.1 — Fusion keyframes reach the render; the contact sheet waits for the viewer; the ledger learns Resolve 21.1
 
 Reported in #196 by @JosephConroy93, with a repro precise enough to reproduce

package/README.md

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

package/docs/SKILL.md

@@ -909,8 +909,12 @@ Key actions: `get_name`, `get_metadata(key?)`, `set_metadata(key, value)`,
 `set_name(name)`, `link_full_resolution_media(path)`,
 `replace_clip_preserve_sub_clip(path)`, `monitor_growing_file`,
 `transcribe_audio(use_speaker_detection?)`, `clear_transcription`,
-`get_transcription` (read back `{text, truncated, status, has_transcription}`;
-`truncated` flags when Resolve's preview cut the text off),
+`get_transcription(include_words?, use_nested_clip_transcription?)` (read back
+`{text, segments, language, source, truncated, status, has_transcription}`; on
+Resolve 21.1+ it uses `MediaPoolItem.GetTranscription`, so `segments` carries
+`{start, end, text, speaker}` in SOURCE timecode and nothing is truncated, and
+on 21.0.x it falls back to the `Transcription` clip property, where `truncated`
+flags a cut-off preview — `source` says which route ran),
 `perform_audio_classification`,
 `analyze_for_intellisearch(identify_faces?, is_better_mode?)`, `analyze_for_slate(marker_color?)`,
 `remove_motion_blur(deblur_option?)` (Resolve 21+; AI Extras / confirm-token gated as noted above),

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 41 missing capabilities, 50 bugs / unreliable behaviors.
+**Totals:** 41 missing capabilities, 51 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -541,6 +541,13 @@ values, or automation-hostile modal prompts.
 - **Workaround / current handling:** Detect the edition BEFORE calling Studio-gated features rather than discovering the gate by tripping it: the product name is 'DaVinci Resolve' on free and 'DaVinci Resolve Studio' on Studio (resolve_control get_version reports it). If a Studio-only call has already returned False on a free build, treat every following failure as suspect: re-run a known-good read, and if that fails too, a modal is blocking and only a human can dismiss it — no API closes it. Known Studio-gated so far: subtitle generation from audio, and audio transcription.
 - **Tags:** free-edition, studio-only, silent-failure, modal, ai, subtitle, transcription
 
+### SetRenderSettings MarkIn/MarkOut below the timeline start are clamped, not refused
+
+- **Object:** `Project / Timeline`
+- **Behavior:** SetRenderSettings takes MarkIn/MarkOut as ABSOLUTE record frames, and a value below the timeline's start frame is silently clamped to the start: measured on Studio 19.1.3.7 (2026-09-08) on an 86400-start timeline, MarkIn=MarkOut=86420 rendered timeline frame 20 and MarkIn=MarkOut=20 rendered frame 0 — one frame, True from SetRenderSettings, no error anywhere. The trap is that Timeline.GetMarkInOut reports the user's marks RELATIVE to the timeline start (Blackmagic's own README example is {'in': 0, 'out': 134}; the 21.1 stub says 'record frame relative to timeline start'), so feeding its output straight into SetRenderSettings renders the wrong range with every readback agreeing. SetMarkInOut itself stores whatever number it is given (10 reads back 10, 86410 reads back 86410), so a script-written range can be in either space.
+- **Workaround / current handling:** Offset GetMarkInOut values by Timeline.GetStartFrame() before passing them to SetRenderSettings when they fall below the start frame (timeline_frame capture does this when it puts a user's range back). Verify a render range from the delivered frames, never from the settings call's return.
+- **Tags:** render, silent-failure, frame-space, mark-range
+
 ### SetRenderSettings ExportSubtitle / SubtitleFormat had no observable effect
 
 - **Object:** `Project (render settings)`

package/install.py

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

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.213.1"
+VERSION = "2.213.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 353-tool granular server instead
 """
 
-VERSION = "2.213.1"
+VERSION = "2.213.3"
 
 import base64
 import os
@@ -14866,12 +14866,18 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
     A single-frame render honours the grade, Fusion and titles, is frame-exact,
     runs in well under a second, and needs no GUI panel or foreground window.
 
-    The cost is that render settings are project-level state. Format and codec
-    are readable and are restored; the rest (TargetDir, CustomName, mark range)
-    is NOT readable on builds without GetRenderSettings, so this resets those to
-    sane values rather than truly restoring them. Callers who need a strictly
-    side-effect-free read should use quality="thumbnail" and accept per-clip
-    granularity.
+    The cost is that render settings are project-level state, and there is still
+    no GetRenderSettings to read them back from (absent as of 21.1). Three
+    different things happen on the way out:
+      - Format and codec are readable via GetCurrentRenderFormatAndCodec and are
+        genuinely restored.
+      - The mark range is readable via Timeline.GetMarkInOut, so a range the
+        caller had set is put back (offset into SetRenderSettings' absolute
+        frame space); with no range set it falls back to the whole timeline.
+      - TargetDir and CustomName are readable from nowhere, so they are reset to
+        sane values rather than restored.
+    Callers who need a strictly side-effect-free read should use
+    quality="thumbnail" and accept per-clip granularity.
     """
     fmt = str(p.get("format", "jpg")).lower().lstrip(".")
     if fmt == "jpeg":
@@ -14934,6 +14940,40 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
         original_tc = tl.GetCurrentTimecode()
     except Exception:
         pass
+    # The capture pins the render range to the captured frame, and there is no
+    # GetRenderSettings to read the surrounding settings back from (still absent
+    # in 21.1). The mark range is the exception: Timeline.GetMarkInOut reports it
+    # in the same record-frame space SetRenderSettings takes, so a range the user
+    # set can be captured here and put back below instead of being flattened to
+    # the whole timeline.
+    original_marks = None
+    try:
+        marks = (tl.GetMarkInOut() or {}).get("video") or {}
+        if "in" in marks and "out" in marks:
+            original_marks = marks
+    except Exception:
+        pass
+    # GetMarkInOut reports marks RELATIVE to the timeline start (Blackmagic's
+    # own example is {'in': 0, 'out': 134}; the 21.1 stub says "record frame
+    # relative to timeline start"), while SetRenderSettings MarkIn/MarkOut are
+    # ABSOLUTE record frames — measured on Studio 19.1.3.7: on an 86400-start
+    # timeline MarkIn=MarkOut=86420 rendered frame 20, and MarkIn=MarkOut=20 was
+    # silently clamped to the start and rendered frame 0, one frame, no error.
+    # Handing a relative range straight back would "restore" a clamped range
+    # with no signal. A mark below the timeline start is therefore relative and
+    # is offset; one at or above it was written absolute (SetMarkInOut stores
+    # whatever it is given) and is kept as-is.
+    if original_marks:
+        try:
+            tl_start = int(round(float(tl.GetStartFrame())))
+            original_marks = {
+                key: (int(original_marks[key]) + tl_start
+                      if int(original_marks[key]) < tl_start
+                      else int(original_marks[key]))
+                for key in ("in", "out")
+            }
+        except Exception:
+            original_marks = None
 
     job = None
     try:
@@ -15027,16 +15067,28 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
                     original_fc.get("format"), original_fc.get("codec"),
                     restore_exc or "SetCurrentRenderFormatAndCodec returned False",
                 )
-        # Best-effort, not a restore: without GetRenderSettings there is nothing
-        # to restore FROM, so put the mark range back to the whole timeline
-        # rather than leaving it pinned to the captured frame.
+        # Still not a full restore — GetRenderSettings does not exist, so the
+        # other settings cannot be read back. The mark range can: put the user's
+        # own range back when they had one, and fall back to the whole timeline
+        # when they did not, so the range is never left pinned to the captured
+        # frame for the next render job to inherit.
+        # (original_marks is already in SetRenderSettings' absolute space — see
+        # the offset above.)
         try:
-            proj.SetRenderSettings({
-                "SelectAllFrames": True,
-                "MarkIn": tl.GetStartFrame(),
-                "MarkOut": tl.GetEndFrame(),
-                "CustomName": "",
-            })
+            if original_marks:
+                restored_marks = {
+                    "SelectAllFrames": False,
+                    "MarkIn": original_marks["in"],
+                    "MarkOut": original_marks["out"],
+                }
+            else:
+                restored_marks = {
+                    "SelectAllFrames": True,
+                    "MarkIn": tl.GetStartFrame(),
+                    "MarkOut": tl.GetEndFrame(),
+                }
+            restored_marks["CustomName"] = ""
+            proj.SetRenderSettings(restored_marks)
         except Exception:
             pass
         try:
@@ -21312,11 +21364,15 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
       get_unique_id(clip_id) -> {id}
       transcribe_audio(clip_id, use_speaker_detection?, background?) -> {success | job_id}  — use_speaker_detection is Resolve 21+; background=true returns a job_id (poll resolve_control job_status)
       clear_transcription(clip_id) -> {success}
-      get_transcription(clip_id) -> {text, truncated, status, has_transcription}
-        Read a clip's transcription. `truncated` flags when Resolve's preview
-        property cut the text off (the full transcript is longer). Clip-level and
-        separate from the timeline subtitle transcript (timeline.get_transcript)
-        that propose_cuts uses.
+      get_transcription(clip_id, include_words?, use_nested_clip_transcription?) -> {text, segments, language, source, truncated, status, has_transcription}
+        Read a clip's transcription. On Resolve 21.1+ this uses
+        MediaPoolItem.GetTranscription, which does not truncate: `segments`
+        carries {start, end, text, speaker} in SOURCE timecode and `truncated`
+        is False. Pass include_words=true to keep each segment's per-word
+        timings. On 21.0.x it falls back to the `Transcription` clip property,
+        `segments` is null, and `truncated` flags a cut-off preview; `source`
+        says which route ran. Clip-level and separate from the timeline subtitle
+        transcript (timeline.get_transcript) that propose_cuts uses.
       extract_frames(clip_id, timestamps, output_dir?) -> {frame_paths, output_dir, count, errors}
         Extract still JPEGs from the clip's source at the given timestamps (seconds)
         via ffmpeg. Source-safe: reads source, writes only to a scratch dir.
@@ -21569,13 +21625,45 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
             status = clip.GetClipProperty("Transcription Status")
         except Exception:
             status = None
-        return {
+        out = {
             "clip_id": p.get("clip_id"),
             "text": text,
             "truncated": _is_truncated(text),
             "status": status or None,
             "has_transcription": bool(text.strip()),
+            "segments": None,
+            "language": None,
+            "source": "clip_property",
         }
+        # The `Transcription` clip property is a preview and stops at an
+        # ellipsis. Resolve 21.1 added a real accessor that does not truncate,
+        # so prefer it and keep the property as the 21.0.x fallback. Verified on
+        # Studio 21.1.0.14: 1550 segments with per-word start/end timecodes.
+        # Segment timecodes are SOURCE timecodes, not timeline positions.
+        if _has_method(clip, "GetTranscription"):
+            try:
+                full = clip.GetTranscription(bool(p.get("use_nested_clip_transcription", False)))
+            except Exception:
+                full = None
+            segs = full.get("segments") if isinstance(full, dict) else None
+            if segs:
+                if not p.get("include_words"):
+                    # `words` is several times the bulk of the segment text and
+                    # most callers want segment-level timing. Opt in for it.
+                    segs = [{k: v for k, v in seg.items() if k != "words"}
+                            if isinstance(seg, dict) else seg for seg in segs]
+                joined = " ".join(seg.get("text", "") for seg in segs
+                                  if isinstance(seg, dict)).strip()
+                out.update({
+                    "segments": segs,
+                    "language": full.get("language"),
+                    "source": "get_transcription",
+                    "truncated": False,
+                })
+                if joined:
+                    out["text"] = joined
+                    out["has_transcription"] = True
+        return out
     elif action == "extract_frames":
         return _extract_clip_frames(clip, p)
     elif action == "perform_audio_classification":

package/src/utils/api_truth.py

@@ -1495,6 +1495,31 @@ API_TRUTH: List[Dict[str, Any]] = [
                  "subtitle", "transcription"],
         "submit": "bug",
     },
+    {
+        "symbol": "SetRenderSettings MarkIn/MarkOut below the timeline start are clamped, not refused",
+        "object": "Project / Timeline",
+        "reality": "SetRenderSettings takes MarkIn/MarkOut as ABSOLUTE record "
+                   "frames, and a value below the timeline's start frame is "
+                   "silently clamped to the start: measured on Studio 19.1.3.7 "
+                   "(2026-09-08) on an 86400-start timeline, MarkIn=MarkOut=86420 "
+                   "rendered timeline frame 20 and MarkIn=MarkOut=20 rendered "
+                   "frame 0 — one frame, True from SetRenderSettings, no error "
+                   "anywhere. The trap is that Timeline.GetMarkInOut reports the "
+                   "user's marks RELATIVE to the timeline start (Blackmagic's own "
+                   "README example is {'in': 0, 'out': 134}; the 21.1 stub says "
+                   "'record frame relative to timeline start'), so feeding its "
+                   "output straight into SetRenderSettings renders the wrong range "
+                   "with every readback agreeing. SetMarkInOut itself stores "
+                   "whatever number it is given (10 reads back 10, 86410 reads "
+                   "back 86410), so a script-written range can be in either space.",
+        "recommended": "Offset GetMarkInOut values by Timeline.GetStartFrame() before "
+                       "passing them to SetRenderSettings when they fall below the "
+                       "start frame (timeline_frame capture does this when it puts "
+                       "a user's range back). Verify a render range from the "
+                       "delivered frames, never from the settings call's return.",
+        "tags": ["render", "silent-failure", "frame-space", "mark-range"],
+        "submit": "bug",
+    },
     {
         "symbol": "SetRenderSettings ExportSubtitle / SubtitleFormat had no observable effect",
         "object": "Project (render settings)",

package/src/utils/resolve_versions.py

@@ -165,6 +165,18 @@ _EVIDENCE_GATES: List[Dict[str, Any]] = [
         "note": "Reported against 21.0.4.5. Not reachable through this server yet.",
         "issue": 131,
     },
+    {
+        "symbol": "MediaPoolItem.GetTranscription",
+        "introduced_in": "21.1",
+        "source": "reported",
+        "note": "Reported against Studio 21.1.0.14 (PR #199): the untruncated "
+                "transcript, {language, segments[{start, end, text, speaker, "
+                "words[]}]} in SOURCE timecode. media_pool_item get_transcription "
+                "prefers it when present and falls back to the truncated "
+                "'Transcription' clip property below 21.1; `source` in the "
+                "result says which route ran.",
+        "issue": 199,
+    },
     {
         "symbol": "Project.SetRenderSettings UseFullExtents",
         "introduced_in": "21.0.4",