davinci-resolve-mcp 4.6.4 → 4.7.0

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 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 v4.7.0 — the Resolve 21.1 transcription and timeline-item type reads are complete
+
+The read-only pick from the 21.1 tracker ([#207](https://github.com/samuelgursky/davinci-resolve-mcp/issues/207)), by @legionsound in [#237](https://github.com/samuelgursky/davinci-resolve-mcp/pull/237). Granular 387 → 389; compound unchanged at 37.
+
+### Added
+
+- **Granular `get_media_pool_item_transcription(clip_id, use_nested_clip_transcription=False)`** —
+  the complete 21.1 `MediaPoolItem.GetTranscription` dictionary with timed words. The
+  compound `media_pool_item get_transcription` already preferred it on 21.1; the
+  granular server had no way to reach it.
+- **Compound `timeline_item get_type` and granular
+  `get_timeline_item_type(track_type, track_index, item_index)`** — the native
+  lowercase `TimelineItem.GetType`, addressed by position like the other 21.1 item
+  readers (`get_speed`, `get_fades`), behind the same `_requires_method(..., "21.1")`
+  guard. The granular item-properties bundle already carried `type` by id through an
+  unguarded call; this is the position-addressed twin of the compound action.
+- `CODE_FLOORS` gains `MediaPoolItem.GetTranscription` and `TimelineItem.GetType` at
+  21.1. Docs, README counts, and the generated agent-rule files are regenerated.
+
+### Validation
+
+- Live on Studio 21.1.0.14 (contributor's measurement, reported): native, compound,
+  and granular agreed exactly — one English segment with 19 timed words, and item
+  type `video` — matching the 2026-09-09 measurement. `Transcription Status` reads
+  empty while processing and `Transcribed` when done.
+  `tests/live_resolve211_read_completion.py` reproduces it.
+- Unit-tested: argument validation, the missing-method refusal below 21.1, and both
+  interfaces forwarding the native value unchanged. The 19.1.3.7 floor refusal was
+  not re-measured on landing (the open project had no timeline or clips); the guard
+  is the one the twelve v2.216.0 readers measured refusing on 19.1.3.7.
+- Not tested: nested-clip transcription, non-English or multi-speaker audio,
+  `GetType` on audio/subtitle/generator/Fusion items, builds other than 21.1.0.14.
+
 ## What's New in v4.6.4 — `ripple="false"` no longer ripples
 
 ### Fixed

package/README.md

@@ -2,10 +2,10 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.6.4-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.7.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-37%20(387%20full)-blue.svg)](#server-modes)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(389%20full)-blue.svg)](#server-modes)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#server-modes)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
@@ -133,7 +133,7 @@ The command starts a loopback-only server and opens the control panel in your br
 | Mode | Entry point | Tools | Best for |
 |------|-------------|-------|----------|
 | Compound | `src/server.py` | 37 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
-| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 387 | Power users who want one MCP tool per Resolve API method. |
+| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 389 | Power users who want one MCP tool per Resolve API method. |
 
 The compound server is recommended unless you specifically need the granular one-tool-per-method surface.
 
@@ -410,7 +410,7 @@ The default server is a local stdio process launched by your MCP client; it does
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **37** compound / **387** granular (live server) |
+| MCP Tools | **37** compound / **389** granular (live server) |
 | Advanced (offline) tools | **18** — .drp/.drt/.drx + DB authoring, no Resolve running |
 | Kernel Actions | **136** guarded workflow actions across 9 compound tools |
 | API Methods Covered | **361/361** (100%) |

package/README.zh-CN.md

@@ -2,17 +2,17 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-4.6.4-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.7.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-37%20(387%20full)-blue.svg)](#服务器模式)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(389%20full)-blue.svg)](#服务器模式)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#服务器模式)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
 [![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)
 
-> 本翻译对应 v4.6.4 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v4.7.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -88,7 +88,7 @@ venv/bin/python -m src.control_panel
 | 模式 | 入口 | 工具数 | 适合谁 |
 |------|------|--------|--------|
 | Compound（复合） | `src/server.py` | 37 | 大多数助手的默认模式。相关的 Resolve 操作按 action 参数分组，压低上下文占用。 |
-| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 387 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
+| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 389 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
 
 除非你明确需要一方法一工具的细粒度界面，否则推荐复合模式。
 
@@ -226,7 +226,7 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 | 指标 | 数值 |
 |------|------|
-| MCP 工具 | **37** 复合 / **387** 细粒度（实时服务器） |
+| MCP 工具 | **37** 复合 / **389** 细粒度（实时服务器） |
 | Advanced（离线）工具 | **18**——.drp/.drt/.drx + 数据库创作，无需 Resolve 运行 |
 | 内核 action | 9 个复合工具下 **136** 个带护栏的工作流 action |
 | API 方法覆盖 | **361/361**（100%） |

package/docs/SKILL.md

@@ -353,7 +353,7 @@ to the user as verified.
 | Mode | Entry point | Tool count | Use when |
 |---|---|---|---|
 | Compound (default) | `src/server.py` | 37 tools | Most workflows — keeps context lean |
-| Granular (full) | `src/server.py --full` | 387 tools | Power users needing one tool per API method |
+| Granular (full) | `src/server.py --full` | 389 tools | Power users needing one tool per API method |
 
 Resolve 21.1 adds [twelve read-only discovery controls](reference/resolve211-read-controls.md)
 for edition, presets, audio formats/codecs, normalization modes, speed, fades

package/docs/install.md

@@ -144,7 +144,7 @@ The MCP server comes in two modes:
 | Mode | File | Tools | Best For |
 |------|------|-------|----------|
 | **Compound** (default) | `src/server.py` | 37 | Most users — fast, clean, low context usage |
-| **Full** | `src/resolve_mcp_server.py` | 387 | Power users who want one tool per API method |
+| **Full** | `src/resolve_mcp_server.py` | 389 | Power users who want one tool per API method |
 
 The compound server's `timeline_item` tool includes dedicated actions for common workflows:
 
@@ -159,7 +159,7 @@ The compound server's `timeline_item` tool includes dedicated actions for common
 
 The installer uses the compound server by default. To use the full server:
 ```bash
-python src/server.py --full    # Launch full 387-tool server
+python src/server.py --full    # Launch full 389-tool server
 # Or point your MCP config directly at src/resolve_mcp_server.py
 ```
 

package/docs/reference/api-coverage.md

@@ -25,7 +25,7 @@ Every non-deprecated method in the bundled legacy README is represented. This
 does not claim complete coverage of the newer Resolve 21.1 typed API. The
 default compound server exposes **37 tools** that group related operations by
 action parameter, keeping LLM context windows lean. The full granular server
-provides **387 individual tools** for power users. The legacy coverage spans
+provides **389 individual tools** for power users. The legacy coverage spans
 13 API object classes. MCP-level kernel actions are tracked separately in
 [Kernel Action Coverage](../kernels/README.md).
 
@@ -44,6 +44,10 @@ way Blackmagic's MCP exposes `search_scripting_api` — and each result also say
 whether this server wraps the method, so a lookup doubles as a parity check.
 See [Querying the typed API](typed-api-search.md).
 
+The 21.1 full-transcription and native timeline-item type readers are also
+available through both interfaces. A synthetic spoken clip matched the native
+results exactly; see [Resolve 21.1 transcription and type reads](resolve211-transcription-type.md).
+
 The 34th compound tool is `timeline_versioning` (C6) — an MCP-level workflow
 tool, not a wrapper around a Resolve API method. It surfaces the
 version-on-mutate hook that auto-archives the working timeline before any

package/docs/reference/resolve211-transcription-type.md

@@ -0,0 +1,35 @@
+# Resolve 21.1 transcription and timeline-item type reads
+
+Resolve 21.1 added `MediaPoolItem.GetTranscription` and
+`TimelineItem.GetType`. The compound server already preferred the full native
+transcription over the older truncated clip-property preview. This change adds
+the missing granular transcription tool plus direct type reads in both server
+modes.
+
+## Live acceptance
+
+Tested on Resolve Studio 21.1.0.14 using a disposable project and a 14-second
+synthetic spoken-camera clip. Native `TranscribeAudio(False, False)` completed
+with status `Transcribed`. The official API, compound
+`media_pool_item.get_transcription`, and granular
+`get_media_pool_item_transcription` returned the same English transcription:
+one segment with 19 timed words. Nested-clip transcription was disabled.
+
+The clip was also placed on a timeline. Native `TimelineItem.GetType`, compound
+`timeline_item.get_type`, and granular `get_timeline_item_type` all returned the
+lowercase string `video`.
+
+The reusable harness is `tests/live_resolve211_read_completion.py`; structured
+evidence is in
+`docs/reference/evidence/resolve211-transcription-type.json`.
+
+## Scope
+
+This validates a non-nested English transcription on one video-plus-audio item
+and the `video` timeline-item type. It does not establish nested-clip behavior,
+speaker labels, other languages, audio-only items, titles, generators,
+transitions, subtitles, multicam items, or every possible native type string.
+
+## Re-run on v4.6.3, 2026-09-15
+
+Rebuilt from `main` at v4.6.3 and re-measured on Studio 21.1.0.14 in a local disposable project. Native `GetTranscription`, compound `media_pool_item get_transcription` and granular `get_media_pool_item_transcription` agreed exactly: one English segment, 19 timed words. Native `GetType`, compound `timeline_item get_type` and granular `get_timeline_item_type` all returned `video`. `Transcription Status` reads empty while transcription is still processing and `Transcribed` once it is done.

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "4.6.4"
+VERSION = "4.7.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
@@ -1543,7 +1543,7 @@ def verify_resolve_connection(python_path, api_path, lib_path):
 
 def print_banner():
     title = f"DaVinci Resolve MCP Server — Installer v{VERSION}"
-    subtitle = "37 compound · 387 full · 3 platforms"
+    subtitle = "37 compound · 389 full · 3 platforms"
     print()
     print(bold("  ╔══════════════════════════════════════════════════════╗"))
     print(bold(f"  ║{title:^54}║"))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "4.6.4",
+  "version": "4.7.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -93,7 +93,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.6.4"
+VERSION = "4.7.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/granular/resolve_211.py

@@ -57,6 +57,25 @@ def get_project_settings_presets() -> dict:
     return {"presets": proj.GetProjectSettingsPresetList()}
 
 
+@mcp.tool(annotations=READ_ONLY_TOOL)
+def get_media_pool_item_transcription(clip_id: str, use_nested_clip_transcription: bool = False) -> dict:
+    """Read the complete 21.1 transcription dictionary for one Media Pool item, including timed words."""
+    if not isinstance(clip_id, str) or not clip_id:
+        return {"error": "clip_id must be a non-empty string"}
+    if type(use_nested_clip_transcription) is not bool:
+        return {"error": "use_nested_clip_transcription must be a boolean"}
+    _, proj = get_current_project()
+    if proj is None:
+        return {"error": "No project currently open"}
+    clip = _find_clip_by_id(proj.GetMediaPool().GetRootFolder(), clip_id)
+    if clip is None:
+        return {"error": "Media Pool item not found"}
+    missing = _requires_method(clip, "GetTranscription", "21.1")
+    if missing:
+        return missing
+    return {"transcription": clip.GetTranscription(use_nested_clip_transcription)}
+
+
 @mcp.tool(annotations=READ_ONLY_TOOL)
 def get_audio_render_formats() -> dict:
     """Read GetAudioRenderFormats (documented on Resolve 21.1+)."""
@@ -129,6 +148,19 @@ def get_timeline_item_fades(track_type: str = "video", track_index: int = 1, ite
         return missing
     return {"fades": item.GetFades()}
 
+@mcp.tool(annotations=READ_ONLY_TOOL)
+def get_timeline_item_type(track_type: str = "video", track_index: int = 1, item_index: int = 0) -> dict:
+    """Read the native lowercase TimelineItem type documented on Resolve 21.1+."""
+    if track_type not in ("video", "audio") or track_index < 1 or item_index < 0:
+        return {"error": "Use video/audio, a 1-based track index and a non-negative item index"}
+    item, error = _get_timeline_item(track_type, track_index, item_index)
+    if error:
+        return error
+    missing = _requires_method(item, "GetType", "21.1")
+    if missing:
+        return missing
+    return {"type": item.GetType()}
+
 @mcp.tool(annotations=READ_ONLY_TOOL)
 def get_timeline_item_output_blanking(track_type: str = "video", track_index: int = 1, item_index: int = 0) -> dict:
     """Read GetOutputBlanking (documented on Resolve 21.1+). Pixel coordinates; clips inheriting timeline blanking return an empty dict."""

package/src/resolve_mcp_server.py

@@ -34,7 +34,7 @@ from src.utils.update_check import start_background_update_check
 if __name__ == "__main__":
     try:
         start_background_update_check(VERSION, project_dir, logger)
-        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (387 granular tools)")
+        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (389 granular tools)")
         run_fastmcp_stdio(mcp)
     except KeyboardInterrupt:
         logger.info("Server shutdown requested")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 377-tool granular server instead
 """
 
-VERSION = "4.6.4"
+VERSION = "4.7.0"
 
 import base64
 import os
@@ -26403,6 +26403,7 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
       set_fades(options, ...) -> {success} — native 21.1 FadeIn/FadeOut integer frames.
       get_speed(...) -> {speed} — documented on Resolve 21.1+.
       get_fades(...) -> {fades} — documented on Resolve 21.1+. Native frame durations.
+      get_type(...) -> {type} — native lowercase TimelineItem type documented on Resolve 21.1+.
       get_output_blanking(...) -> {blanking} — documented on Resolve 21.1+. Pixel coordinates; empty on a clip inheriting timeline blanking.
       get_use_timeline_for_output_blanking(...) -> {use_timeline} — documented on Resolve 21.1+.
       get_name(track_type?, track_index?, item_index?) -> {name}
@@ -26516,6 +26517,11 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
         if missing:
             return missing
         return {"fades": _ser(item.GetFades())}
+    if action == "get_type":
+        missing = _requires_method(item, "GetType", "21.1")
+        if missing:
+            return missing
+        return {"type": _ser(item.GetType())}
     if action == "get_output_blanking":
         missing = _requires_method(item, "GetOutputBlanking", "21.1")
         if missing:
@@ -26702,7 +26708,7 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
             return _err(f"Invalid interpolation. Must be one of: {', '.join(valid)}")
         return {"success": bool(item.SetKeyframeInterpolation(p["property"], p["frame"], p["interpolation"]))}
 
-    return _unknown(action, ["set_output_blanking","set_use_timeline_for_output_blanking","flatten_multicam","add_transition","set_speed","set_fades","get_speed","get_fades","get_output_blanking","get_use_timeline_for_output_blanking","get_name","get_property","set_property","get_duration","get_start","get_end","get_source_start_frame","get_source_end_frame","get_source_start_time","get_source_end_time","get_left_offset","get_right_offset","set_clip_enabled","get_clip_enabled","update_sidecar","get_unique_id","get_media_pool_item","get_stereo_convergence","get_stereo_left_window","get_stereo_right_window","get_linked_items","get_track_type_and_index","get_source_audio_mapping","load_burnin_preset","set_name","get_voice_isolation_state","set_voice_isolation_state","get_retime","set_retime","get_transform","set_transform","get_crop","set_crop","get_composite","set_composite","get_audio","set_audio","get_keyframes","add_keyframe","modify_keyframe","delete_keyframe","set_keyframe_interpolation"])
+    return _unknown(action, ["set_output_blanking","set_use_timeline_for_output_blanking","flatten_multicam","add_transition","set_speed","set_fades","get_speed","get_fades","get_type","get_output_blanking","get_use_timeline_for_output_blanking","get_name","get_property","set_property","get_duration","get_start","get_end","get_source_start_frame","get_source_end_frame","get_source_start_time","get_source_end_time","get_left_offset","get_right_offset","set_clip_enabled","get_clip_enabled","update_sidecar","get_unique_id","get_media_pool_item","get_stereo_convergence","get_stereo_left_window","get_stereo_right_window","get_linked_items","get_track_type_and_index","get_source_audio_mapping","load_burnin_preset","set_name","get_voice_isolation_state","set_voice_isolation_state","get_retime","set_retime","get_transform","set_transform","get_crop","set_crop","get_composite","set_composite","get_audio","set_audio","get_keyframes","add_keyframe","modify_keyframe","delete_keyframe","set_keyframe_interpolation"])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════

package/src/utils/resolve_versions.py

@@ -250,6 +250,8 @@ CODE_FLOORS: Dict[str, str] = {
     "Timeline.GetOutputBlanking": "21.1",
     "TimelineItem.GetSpeed": "21.1",
     "TimelineItem.GetFades": "21.1",
+    "MediaPoolItem.GetTranscription": "21.1",
+    "TimelineItem.GetType": "21.1",
     "TimelineItem.GetOutputBlanking": "21.1",
     "TimelineItem.GetUseTimelineForOutputBlanking": "21.1",