davinci-resolve-mcp 2.26.1 → 2.27.1

package/CHANGELOG.md

@@ -2,6 +2,77 @@
 
 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.27.1
+
+**Faster control-panel startup with network source media (issue #50)** — on
+first open the control panel could sit on "connection pending" for a long time
+when Media Pool clips lived on mounted network storage, because the UI only
+treated the connection as live once the full media inventory finished loading,
+and that inventory probed every clip's file path on disk.
+
+Fixes and performance work:
+
+- **Connection state is decoupled from the media inventory.** The overview and
+  diagnostics panels now derive "connected" from the `/api/boot` handshake (which
+  returns as soon as the Resolve bridge is reachable) and show inventory loading
+  separately, so Resolve reads as live immediately while clips stream in.
+- **Parallel, cached file-existence probing.** `os.path.exists` for every clip
+  now runs in a thread pool and is memoized for a short TTL, instead of two serial
+  `stat()` calls per clip — the dominant cost on network storage.
+- **Background polls reuse the cached Media Pool walk.** The recurring poll no
+  longer re-runs the ~N serial `GetClipProperty` calls; it reuses the last walk
+  and re-applies only the local, disk-backed analysis-status overlay. A cheap
+  project-id check still catches a project switched directly in Resolve, and a
+  manual refresh always does a full walk.
+- **Resolve scripting API access is serialized.** A re-entrant lock guards every
+  scripting-API entry point, since the dashboard's threaded HTTP server could
+  previously fire concurrent (thread-unsafe) Resolve calls at startup.
+- **ETag/304 on the inventory endpoint** skips transfer and table re-render when
+  nothing changed; the last good inventory is cached client-side and painted
+  instantly on reload; and the first inventory build is warmed in a background
+  thread at server start.
+
+No public MCP tool surface changed. Adds regression tests in
+`tests/test_media_analysis.py` (path-existence probing, inventory cache reuse,
+project-switch detection, lock reentrancy).
+
+## What's New in v2.27.0
+
+**Frame-sampling modes (issue #46)** — how many frames a clip gets for visual
+analysis is now governed by a `sampling_mode`, decoupled from `depth` (which
+still controls which layers run). A fixed frame count over-sampled short clips
+and under-covered long ones; the demand-driven engine already scaled by
+duration/content, but the caps layer was flat-truncating its output back to 8
+frames — that flat cap was the real cause of long-clip under-coverage.
+
+Four clearly-tiered modes, organized so token cost is predictable per tier:
+
+- **Economy** (`fixed`) — flat N evenly-spaced, content-blind frames. Cheapest and
+  most predictable; good for proxies/triage.
+- **Balanced** (`per_minute`) — `clamp(minutes × frames_per_minute, floor, ceiling)`
+  (defaults 4/min, 3–80). Cost is linear in footage length; content-blind.
+- **Thorough** (`adaptive_capped`, recommended/default) — content-aware: samples
+  shot boundaries, representatives, and flash candidates, bounded to `[floor,
+  ceiling]`. Best coverage with a bounded cost.
+- **Thorough (uncapped)** (`adaptive`) — content-aware with no per-clip ceiling
+  (up to the 512-frame hard cap). Use only when clips are short or few.
+
+The first time you analyze without a saved default, the tool returns a
+`confirmation_required` response with a `sampling_mode_prompt`; choosing a mode
+saves it as your standing default (mirrors `timed_markers_default`). Pass
+`sampling_mode` per call any time for a one-off that doesn't change the default.
+Tunables (`frames_per_minute`, `frame_floor`, `frame_ceiling`) and the mode are
+all exposed in the control panel (Preferences → Frame sampling mode) with a live
+per-clip token-cost estimate; batch jobs honor the saved default.
+
+Analysis-caps presets were retuned so `frames_per_clip` is now a *safety ceiling*
+(minimal/standard/generous = 12/80/200), not the primary frame dial, and the
+per-clip/job/day vision-token caps were raised so the default Thorough mode isn't
+refused by the per-clip token cap. Cache reuse re-samples only when switching up
+the thoroughness rank; a richer prior report still satisfies a cheaper mode. Adds
+`tests/test_sampling_modes.py` (30 tests). Validated end-to-end on a synthetic
+multi-shot clip with real ffmpeg frame extraction.
+
 ## What's New in v2.26.1
 
 **Python 3.13 / 3.14 support (issue #45)** — `npx davinci-resolve-mcp setup`

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.26.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.27.1-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-32%20(329%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md

@@ -468,6 +468,16 @@ for existing reports. `quick` uses ffprobe metadata; `standard` adds ffmpeg
 read-through checks,
 cut-boundary analysis from full-stream scene detection, flash-frame candidates,
 motion/variance scoring, analysis keyframes, and sidecar reports.
+`depth` controls which layers run; a separate `sampling_mode` controls how many
+frames each clip gets for visual analysis (and thus token cost): `fixed`
+(Economy, flat content-blind frames), `per_minute` (Balanced, frames scale with
+duration), `adaptive_capped` (Thorough, content-aware bounded to
+`[frame_floor, frame_ceiling]` — recommended/default), or `adaptive` (Thorough
+uncapped). When no default is saved, the first analyze returns
+`confirmation_required` with a `sampling_mode_prompt`; choosing a mode saves it
+as the default. Pass `sampling_mode` per call for a one-off. The mode owns frame
+count — `analysis_caps.frames_per_clip` is a safety ceiling above it, not the
+primary dial.
 By default, planning checks the active project's analysis root and bounded
 related project-version roots for existing reports, then marks matching clips
 `skip_execution=true` when those reports already contain the requested

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

@@ -93,6 +93,33 @@ FFprobe is required. If missing:
   via host_chat_paths (finalized per clip with commit_vision, ~2-5 minutes per
   file plus host-chat read time)
 
+`depth` controls *which layers run*. How many frames each clip gets for visual
+analysis is a separate axis — the **sampling mode** — because a fixed frame count
+over-samples short clips and under-covers long ones.
+
+### 3b. Frame-sampling mode
+
+Pass `sampling_mode` on any analyze action, or set a standing default in the
+control panel (Preferences → Frame sampling mode). The mode owns frame count and
+thus token cost; `analysis_caps.frames_per_clip` is now a safety ceiling above it,
+not the primary dial.
+
+- **Economy** (`fixed`) — flat N frames (depth-derived, default 8) regardless of
+  clip length. Cheapest and most predictable; good for proxies/triage.
+- **Balanced** (`per_minute`) — `frames = clamp(minutes × frames_per_minute, floor,
+  ceiling)` (defaults 4/min, 3–80). Cost is linear in footage length; content-blind.
+- **Thorough** (`adaptive_capped`, **recommended**) — content-aware: samples shot
+  boundaries, representatives, and flash candidates, bounded to `[floor, ceiling]`
+  (3–80). Best coverage with a bounded cost.
+- **Thorough (uncapped)** (`adaptive`) — content-aware with no per-clip ceiling
+  (up to the absolute 512-frame hard cap). Use only when clips are short or few.
+
+Tunables (`frames_per_minute`, `frame_floor`, `frame_ceiling`) apply to Balanced
+and Thorough. The first time you analyze without a saved default, the tool returns
+a `confirmation_required` response with a `sampling_mode_prompt`; re-run with
+`sampling_mode=<choice>` (which saves it as your default) or pick it in the panel.
+Pass `sampling_mode` explicitly any time for a one-off that doesn't change the default.
+
 ---
 
 ## Analysis Commands

package/install.py

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