davinci-resolve-mcp 2.103.4 → 2.103.5

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 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.103.5
+
+Two fixes that fell out of auditing the code around this week's releases — the
+same failure classes as #161 and #164, found one tier up from where each was
+originally fixed.
+
+**Cache reuse was permanently poisoned on most real installs.** The v2.103.3
+transcription fix taught batch jobs that a declined transcription is not a clip
+failure — but the cache layer had the same default-ON blindness.
+`_report_missing_layers` counted any non-success transcript as a missing layer,
+and the capability gate only screens for a missing backend, not for the stock
+configuration: Whisper installed, `allow_model_download` unset. On such a
+machine every analysis writes a declined "skipped" transcript, every cached
+report carries `missing_layers: ['transcription']`, and `find_reusable_report`
+returns `reusable: False` — forever. Every analyze call silently re-ran full
+analysis (frame extraction included) and produced the same skipped transcript
+again. An unfixable loop, reproduced end-to-end before the fix and green after.
+
+A transcript-less report is now a missing layer only when a re-run could supply
+the transcript: the cached payload shows a real attempt that failed (a timeout
+retry may succeed), or the current options would now actually run a backend
+(mock or HTTP backends, or `allow_model_download=true`). Because the check is
+recomputed per request, flipping `allow_model_download` on later correctly
+refuses reuse and finally produces the transcript.
+
+**Absolute recordFrames below the timeline start are now refused.** Issue #164
+documented that `recordFrame` counts from Resolve's global frame zero and that
+content placed before the timeline start reads back correctly while rendering
+as ~0 frames. The wrapper's `record_frame_mode='relative'` default shields
+callers — but `record_frame_mode='absolute'` passed any value straight through,
+so an absolute-mode caller with relative-style values reproduced the silent
+stub through this server's own tools. `_normalize_record_frame` (both the
+compound and granular copies) now rejects an absolute value below the
+timeline's start frame with an error naming the convention; internal
+absolute-mode flows (`ripple_insert` cursors) derive their frames from
+timeline reads and cannot trip it. The Resolve UI cannot place content there,
+so no legitimate call is lost.
+
+### Fixed
+
+- A declined transcription (no `allow_model_download` opt-in, unavailable or
+  not-implemented backend) no longer marks cached analysis reports
+  incomplete, so report reuse works on default installs again. Opting into
+  model downloads later invalidates reuse and produces the transcript.
+- `record_frame_mode='absolute'` values below the timeline start frame are
+  refused with a remediation instead of silently placing content the render
+  engine never visits (#164).
+
 ## What's New in v2.103.4
 
 **A frame-numbering trap, documented where agents will look it up.** Issue #164

package/README.md

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

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.103.4"
+VERSION = "2.103.5"
 # 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.103.4",
+  "version": "2.103.5",
   "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.103.4"
+VERSION = "2.103.5"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")
@@ -572,7 +572,22 @@ def _normalize_record_frame(ci, index, timeline_start_frame=None):
         }
 
     start = _frame_int(timeline_start_frame)
-    if start in (None, 0) or mode == "absolute":
+    if mode == "absolute":
+        # recordFrame counts from Resolve's global frame zero; a value below
+        # the timeline start renders as ~0 frames while every readback agrees
+        # (issue #164). No legitimate placement exists there — refuse.
+        if start not in (None, 0) and rf < start:
+            return None, {
+                "error": (
+                    f"clip_infos[{index}] recordFrame {rf} is before the timeline "
+                    f"start frame {start}. recordFrame is timeline-absolute, so "
+                    "content placed there reads back correctly but renders as ~0 "
+                    "frames. Use record_frame_mode='relative' (default) or pass an "
+                    f"absolute frame >= {start}."
+                )
+            }
+        return rf, None
+    if start in (None, 0):
         return rf, None
     if mode == "auto":
         return (start + rf) if rf < start else rf, None

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.103.4"
+VERSION = "2.103.5"
 
 import base64
 import os
@@ -2894,7 +2894,24 @@ def _normalize_record_frame(
         )
 
     start = _frame_int(timeline_start_frame)
-    if start in (None, 0) or mode == "absolute":
+    if mode == "absolute":
+        # recordFrame counts from Resolve's global frame zero. An absolute
+        # value below the timeline's own start frame places content the render
+        # engine never visits: every readback agrees, the render reports
+        # Complete, and the output is a near-empty stub (issue #164; see the
+        # api_truth recordFrame timeline-absolute origin entry). The Resolve UI
+        # cannot place content there, so there is no legitimate case — refuse.
+        if start not in (None, 0) and rf < start:
+            return None, _err(
+                f"clip_infos[{index}] recordFrame {rf} is before the timeline start "
+                f"frame {start}. recordFrame is timeline-absolute (counted from frame "
+                "zero, not from the timeline's start), so content placed there reads "
+                "back correctly but renders as ~0 frames. Use the default "
+                "record_frame_mode='relative' with an offset from the timeline start, "
+                f"or pass an absolute frame >= {start}."
+            )
+        return rf, None
+    if start in (None, 0):
         return rf, None
     if mode == "auto":
         return (start + rf) if rf < start else rf, None

package/src/utils/api_truth.py

@@ -1884,7 +1884,9 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "media_pool.append_to_timeline defaults to "
                        "record_frame_mode='relative' and adds the start frame, "
                        "so pass record_frame_mode='absolute' only for raw "
-                       "Resolve frame numbers. When driving the API directly, "
+                       "Resolve frame numbers — and since v2.103.5 an absolute "
+                       "value below the timeline start is refused outright. "
+                       "When driving the API directly, "
                        "never treat JobStatus Complete as proof a render "
                        "worked — check the output file's duration, not just "
                        "that the job finished.",

package/src/utils/media_analysis.py

@@ -227,6 +227,30 @@ def transcription_attempt_failed(transcript: Any, *, enabled: bool) -> bool:
     return status not in TRANSCRIPTION_UNATTEMPTED_STATUSES
 
 
+def transcription_options_would_attempt(transcription: Dict[str, Any]) -> bool:
+    """True when these options would actually run a transcription backend.
+
+    Mirrors _transcribe's early-outs. The local backends (whisper_cli,
+    mlx_whisper — also what a backend of None resolves to) refuse to run
+    without allow_model_download=true, whisper_cpp is not_implemented, and
+    the resolve backend is refused by design; mock and HTTP-provider
+    backends always attempt. Used by _report_missing_layers to decide
+    whether re-running an analysis could produce a transcript a cached
+    report lacks — if it could not, the cached report is as complete as a
+    fresh run would be. Known blind spot: backend None on a machine whose
+    only configured backend is an HTTP provider reports False here; name
+    the http_* backend explicitly to get cache invalidation.
+    """
+    backend = transcription.get("backend")
+    if backend in {"mock", "local_mock"}:
+        return True
+    if isinstance(backend, str) and backend.startswith(HTTP_TRANSCRIPTION_BACKEND_PREFIX):
+        return True
+    if backend in {"whisper_cpp", "resolve"}:
+        return False
+    return _coerce_bool(transcription.get("allow_model_download"), default=False)
+
+
 def _annotate_clip_transcript_failure(clip_result: Dict[str, Any], transcript: Any) -> None:
     """Mark a clip failed when requested transcription did not complete.
 
@@ -3665,7 +3689,19 @@ def _report_missing_layers(report: Dict[str, Any], depth: str, options: Dict[str
     if _coerce_bool(transcription.get("enabled"), default=DEFAULT_TRANSCRIPTION_ENABLED):
         transcript = report.get("transcription") or {}
         if not transcript.get("success") or transcript.get("status") == "skipped":
-            missing.append("transcription")
+            # A transcript-less report is a missing layer only when a re-run
+            # could supply the transcript: either the cached payload shows a
+            # real attempt that failed (a retry may fix a timeout), or the
+            # current options would now actually run a backend. Transcription
+            # is enabled by default while allow_model_download is not, so on a
+            # stock install every report carries a declined "skipped" payload —
+            # counting that as missing made every cached report reusable=False
+            # forever, silently defeating cache reuse with full re-analysis
+            # that could never produce the transcript either.
+            if transcription_attempt_failed(
+                transcript, enabled=True
+            ) or transcription_options_would_attempt(transcription):
+                missing.append("transcription")
     vision = options.get("vision") or {}
     if _coerce_bool(vision.get("enabled"), default=False):
         visual = report.get("visual") or {}