davinci-resolve-mcp 2.26.0 → 2.27.0

package/AGENTS.md

@@ -93,7 +93,9 @@ venv/bin/python tests/test_import.py
 venv/bin/python scripts/audit_api_parity.py
 ```
 
-Python 3.10-3.12 is recommended for Resolve scripting compatibility.
+Python 3.10+ is required (the MCP SDK floor). 3.10-3.12 is the lowest-risk range
+for Resolve scripting; 3.13/3.14 are accepted and verified on Resolve Studio
+20.3.2, but older Resolve builds may fail to connect on 3.13+.
 
 ## Development Notes
 

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 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.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`
+previously hard-refused any interpreter outside 3.10–3.12, so it failed outright
+on Python 3.14. The 3.12 ceiling was based on a stale assumption that Resolve's
+scripting bridge has ABI incompatibilities on 3.13+. Verified empirically against
+DaVinci Resolve Studio 20.3.2.9: Python 3.14.4 connects and exercises the
+dict/list marshalling paths cleanly. The launcher and installer now enforce only
+the 3.10 floor (the `mcp[cli]` SDK requirement) with no upper cap. Python 3.13/3.14
+are accepted with a soft heads-up; `setup`/`doctor` surface a precise,
+connection-aware hint only when Resolve is running but the bridge returns no
+connection on 3.13+. Sub-3.10 interpreters get an actionable error instead of a
+dead end. `server.py` warns (never exits) on 3.13+. Adds 6 version-gate unit tests.
+
 ## What's New in v2.26.0
 
 **Fusion group-settings helpers** — Three new `fusion_comp` actions for

package/README.md

@@ -1,12 +1,12 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.26.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.27.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-32%20(329%20full)-blue.svg)](#server-modes)
 [![Tested](https://img.shields.io/badge/Live%20Tested-98.5%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--3.12-green.svg)](https://www.python.org/downloads/)
+[![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)
 
 A Model Context Protocol (MCP) server that lets AI assistants control DaVinci Resolve Studio through the official Scripting API. It provides full API coverage plus guarded workflow helpers for editing, media pool organization, render setup, review markers, grading, Fusion, Fairlight, project lifecycle tasks, extension authoring, and source-safe media analysis.
@@ -133,7 +133,7 @@ Extension authoring references live in [docs/authoring](docs/authoring/). Resolv
 ## Requirements
 
 - DaVinci Resolve Studio 18.5+ on macOS, Windows, or Linux. The free edition does not support external scripting.
-- Python 3.10-3.12 recommended. Python 3.13+ may have ABI incompatibilities with Resolve's scripting library.
+- Python 3.10+ (3.10-3.12 is the lowest-risk range). Python 3.13/3.14 also work on recent Resolve builds (verified on Studio 20.3.2); older builds may fail to connect on 3.13+, in which case use 3.10-3.12.
 - Resolve external scripting set to **Local**.
 
 Resolve 19.1.3 remains the compatibility baseline. Resolve 20.x scripting calls are additive, version-guarded, and live-tested on 20.3.2. Resolve 21 beta APIs are intentionally deferred until stable.

package/bin/davinci-resolve-mcp.mjs

@@ -11,6 +11,16 @@ const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)),
 const VERSION = readPackageVersion();
 const MANAGED_MARKER = ".davinci-resolve-mcp-managed.json";
 
+// The only hard Python floor is the MCP SDK: mcp[cli] requires 3.10+.
+// We do NOT cap the upper bound. Resolve's scripting bridge (fusionscript)
+// loads cleanly into newer interpreters on recent builds — Python 3.14 is
+// verified working against Resolve Studio 20.3.2. Older Resolve builds may
+// fail to connect on 3.13+, but the version number is a poor proxy for that;
+// the connection check in `setup`/`doctor` is the real signal, so we proceed
+// with a soft heads-up rather than refusing to run.
+const PY_MIN_MINOR = 10;
+const PY_ABI_RISK_MINOR = 13;
+
 const SYNC_ITEMS = [
   "bin",
   "src",
@@ -54,7 +64,8 @@ Examples:
 
 Environment:
   DAVINCI_RESOLVE_MCP_INSTALL_ROOT   Override the managed install directory.
-  DAVINCI_RESOLVE_MCP_PYTHON         Python executable to use.
+  DAVINCI_RESOLVE_MCP_PYTHON         Python executable to use (3.10+). Set this to
+                                     pin a specific interpreter, e.g. python3.12.
   PYTHON                             Fallback Python executable to use.
 `;
 }
@@ -193,17 +204,24 @@ function pythonCandidates() {
   if (explicit) {
     candidates.push(explicit);
   }
+  // Prefer the lowest-ABI-risk interpreters first, then newer ones, then the
+  // generic launchers. All 3.10+ are accepted; ordering just picks the safest
+  // when several are installed.
   if (process.platform === "win32" && commandExists("py")) {
     candidates.push(
       { command: "py", args: ["-3.12"] },
       { command: "py", args: ["-3.11"] },
-      { command: "py", args: ["-3.10"] }
+      { command: "py", args: ["-3.10"] },
+      { command: "py", args: ["-3.13"] },
+      { command: "py", args: ["-3.14"] }
     );
   }
   candidates.push(
     { command: "python3.12", args: [] },
     { command: "python3.11", args: [] },
     { command: "python3.10", args: [] },
+    { command: "python3.13", args: [] },
+    { command: "python3.14", args: [] },
     { command: "python3", args: [] },
     { command: "python", args: [] }
   );
@@ -224,8 +242,9 @@ function checkPython(candidate) {
   }
   try {
     const info = JSON.parse(result.stdout.trim());
-    const supported = info.major === 3 && info.minor >= 10 && info.minor <= 12;
-    return { ...candidate, ...info, supported };
+    const supported = info.major === 3 && info.minor >= PY_MIN_MINOR;
+    const abiRisk = info.major === 3 && info.minor >= PY_ABI_RISK_MINOR;
+    return { ...candidate, ...info, supported, abiRisk };
   } catch {
     return null;
   }
@@ -244,8 +263,40 @@ function findSupportedPython() {
     }
   }
 
-  const suffix = checked.length ? ` Found: ${checked.join(", ")}.` : "";
-  throw new Error(`Python 3.10-3.12 is required for Resolve scripting compatibility.${suffix}`);
+  throw new Error(unsupportedPythonMessage(checked));
+}
+
+// Print the 3.13+ heads-up for run modes that never invoke install.py
+// (server/control-panel/batch). setup/doctor stay quiet here because
+// install.py emits a richer, connection-aware note of its own.
+function maybeWarnAbiRisk(info) {
+  if (info && info.abiRisk) {
+    console.warn(abiRiskNote(info));
+  }
+}
+
+function abiRiskNote(info) {
+  return (
+    `Note: using Python ${info.major}.${info.minor}.${info.micro}. ` +
+    `This is verified working on recent Resolve builds (Studio 20.3.2). ` +
+    `If Resolve fails to connect (scriptapp("Resolve") returns None), install ` +
+    `Python 3.10-3.12 and pin it with DAVINCI_RESOLVE_MCP_PYTHON=/path/to/python3.12.`
+  );
+}
+
+function unsupportedPythonMessage(checked) {
+  const found = checked.length ? ` Found: ${checked.join(", ")}.` : "";
+  const lines = [
+    `Python 3.${PY_MIN_MINOR} or newer is required (the MCP SDK needs Python 3.${PY_MIN_MINOR}+).${found}`,
+    "",
+    "How to fix:",
+    "  - Install Python 3.12 (the lowest-risk version for Resolve), e.g.:",
+    "      macOS:   brew install python@3.12   (or: pyenv install 3.12)",
+    "      Linux:   pyenv install 3.12          (or your distro's python3.12 package)",
+    "      Windows: install Python 3.12 from python.org",
+    `  - Point the launcher at it:  DAVINCI_RESOLVE_MCP_PYTHON=/path/to/python3.12 npx ${APP_NAME} setup`,
+  ];
+  return lines.join("\n");
 }
 
 function venvPython(root) {
@@ -258,7 +309,10 @@ function venvPython(root) {
   }
   const info = checkPython({ command: executable, args: [] });
   if (!info || !info.supported) {
-    throw new Error(`Managed venv Python must be 3.10-3.12. Re-run setup to recreate it: ${executable}`);
+    throw new Error(
+      `Managed venv Python must be 3.${PY_MIN_MINOR} or newer. ` +
+        `Re-run setup to recreate it: ${executable}`
+    );
   }
   return info;
 }
@@ -326,6 +380,7 @@ function commandDoctor(args) {
 function commandServer(args) {
   const root = syncManagedInstall(installRoot());
   const python = venvPython(root) || findSupportedPython();
+  maybeWarnAbiRisk(python);
   const serverScript = path.join(root, "src", "server.py");
   const [command, ...commandArgs] = pythonCommandLine(python, [serverScript, ...args]);
   run(command, commandArgs, { cwd: root });
@@ -334,6 +389,7 @@ function commandServer(args) {
 function commandControlPanel(args) {
   const root = syncManagedInstall(installRoot());
   const python = venvPython(root) || findSupportedPython();
+  maybeWarnAbiRisk(python);
   const [command, ...commandArgs] = pythonCommandLine(python, ["-m", "src.control_panel", ...args]);
   run(command, commandArgs, { cwd: root });
 }
@@ -341,6 +397,7 @@ function commandControlPanel(args) {
 function commandBatch(args) {
   const root = syncManagedInstall(installRoot());
   const python = venvPython(root) || findSupportedPython();
+  maybeWarnAbiRisk(python);
   const [command, ...commandArgs] = pythonCommandLine(python, ["-m", "src.batch_cli", ...args]);
   run(command, commandArgs, { cwd: root });
 }

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
@@ -1247,9 +1257,13 @@ timeline item returns `False` in Resolve. Use `get_node_graph` without a
 if the Gallery panel is open in the Resolve UI on the Color page. Instruct the
 user to open it via Workspace menu if export fails.
 
-**Python version** — Resolve's scripting library works best with Python 3.10–3.12.
-Python 3.13+ may cause `scriptapp("Resolve")` to return `None` due to ABI
-incompatibilities.
+**Python version** — the only hard requirement is Python **3.10+** (the MCP SDK
+floor). There is no upper cap: 3.13/3.14 are accepted, and Python 3.14 is verified
+working against Resolve Studio 20.3.2. On *older* Resolve builds the scripting
+bridge may still fail to load on 3.13+ (`scriptapp("Resolve")` returns `None`);
+`setup`/`doctor` warn on 3.13+ and their connection check surfaces a real failure.
+If that happens, recreate the venv with Python 3.10–3.12 (the lowest-risk range).
+The running server only warns on 3.13+ rather than exiting.
 
 **Resolve version guards** — Resolve 20-specific actions return a clear
 `requires DaVinci Resolve 20.x+` error when called against older builds. Resolve

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/docs/install.md

@@ -5,9 +5,18 @@ This guide covers Resolve requirements, the universal installer, supported MCP c
 ## Requirements
 
 - **DaVinci Resolve Studio** 18.5+ (macOS, Windows, or Linux) — the free edition does not support external scripting
-- **Python 3.10–3.12** recommended (3.13+ may have ABI incompatibilities with Resolve's scripting library)
+- **Python 3.10+** (the MCP SDK requires 3.10). **3.10–3.12 is the lowest-risk
+  choice**; 3.13/3.14 also work on recent Resolve builds — see below
 - DaVinci Resolve running with **Preferences > General > "External scripting using"** set to **Local**
 
+> **Python 3.13 / 3.14:** these are **allowed** — setup will use them and warn.
+> Python 3.14 is verified working against DaVinci Resolve Studio 20.3.2. On
+> *older* Resolve builds the scripting bridge may fail to load on 3.13+
+> (`scriptapp("Resolve")` returns `None`); setup's connection check will tell you
+> if that happens. If it does, install a 3.10–3.12 interpreter
+> (`brew install python@3.12`, `pyenv install 3.12`, or python.org on Windows) and
+> point the launcher at it with `DAVINCI_RESOLVE_MCP_PYTHON=/path/to/python3.12`.
+
 Validated live coverage is based on **DaVinci Resolve 19.1.3 Studio** for the original API surface, plus **DaVinci Resolve 20.3.2 Studio** for the Resolve 20.0-20.2.2 scripting additions. Resolve 21 beta APIs are intentionally deferred until a stable release.
 
 ## Quick Start

package/install.py

@@ -35,9 +35,14 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.26.0"
+VERSION = "2.27.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
+# may fail to connect on 3.13+, but the connection check is the real signal,
+# so we proceed with a heads-up rather than refusing to run.
 SUPPORTED_PYTHON_MIN = (3, 10)
-SUPPORTED_PYTHON_MAX = (3, 12)
+PYTHON_ABI_RISK_MIN = (3, 13)
 
 # ─── Colors (disabled on Windows cmd without ANSI support) ────────────────────
 
@@ -77,7 +82,12 @@ def platform_name():
 
 def is_supported_python_version(version):
     major, minor = version[:2]
-    return major == 3 and SUPPORTED_PYTHON_MIN[1] <= minor <= SUPPORTED_PYTHON_MAX[1]
+    return major == 3 and minor >= SUPPORTED_PYTHON_MIN[1]
+
+
+def is_abi_risk_python_version(version):
+    major, minor = version[:2]
+    return major == 3 and minor >= PYTHON_ABI_RISK_MIN[1]
 
 
 def format_python_version(version):
@@ -85,9 +95,38 @@ def format_python_version(version):
 
 
 def python_requirement_text():
+    return f"Python {SUPPORTED_PYTHON_MIN[0]}.{SUPPORTED_PYTHON_MIN[1]} or newer"
+
+
+_ABI_NOTE_PRINTED = False
+
+
+def print_abi_risk_note_once(version, label="Python"):
+    """Emit the 3.13+ heads-up at most once per installer run."""
+    global _ABI_NOTE_PRINTED
+    if _ABI_NOTE_PRINTED:
+        return
+    _ABI_NOTE_PRINTED = True
+    print(f"  {yellow(label + ':')} {python_abi_risk_note(version)}")
+
+
+def python_abi_risk_note(version):
+    return (
+        f"Using Python {format_python_version(version)}. Verified working on recent "
+        f"Resolve builds (Studio 20.3.2). If Resolve fails to connect "
+        f"(scriptapp(\"Resolve\") returns None), install Python 3.10-3.12 and re-run "
+        f"with it, e.g.: python3.12 install.py"
+    )
+
+
+def python_fix_hint():
     return (
-        f"Python {SUPPORTED_PYTHON_MIN[0]}.{SUPPORTED_PYTHON_MIN[1]}-"
-        f"{SUPPORTED_PYTHON_MAX[0]}.{SUPPORTED_PYTHON_MAX[1]}"
+        "  How to fix:\n"
+        "    - Install Python 3.12 (the lowest-risk version for Resolve), e.g.:\n"
+        "        macOS:   brew install python@3.12   (or: pyenv install 3.12)\n"
+        "        Linux:   pyenv install 3.12          (or your distro's python3.12 package)\n"
+        "        Windows: install Python 3.12 from python.org\n"
+        "    - Re-run with that interpreter, e.g.:  python3.12 install.py"
     )
 
 
@@ -120,10 +159,13 @@ def require_supported_python(python_path, label="Python"):
     if not is_supported_python_version(version):
         print(
             f"  {red(label + ':')} {python_requirement_text()} is required "
-            f"for Resolve scripting compatibility; found {format_python_version(version)} "
+            f"(the MCP SDK needs 3.10+); found {format_python_version(version)} "
             f"at {python_path}"
         )
+        print(python_fix_hint())
         sys.exit(1)
+    if is_abi_risk_python_version(version):
+        print_abi_risk_note_once(version, label)
     return version
 
 
@@ -132,10 +174,13 @@ def require_current_python(label="Python"):
     if not is_supported_python_version(version):
         print(
             f"  {red(label + ':')} {python_requirement_text()} is required "
-            f"for Resolve scripting compatibility; current interpreter is "
+            f"(the MCP SDK needs 3.10+); current interpreter is "
             f"{format_python_version(version)} at {sys.executable}"
         )
+        print(python_fix_hint())
         sys.exit(1)
+    if is_abi_risk_python_version(version):
+        print_abi_risk_note_once(version, label)
     return version
 
 # ─── Resolve Path Detection ──────────────────────────────────────────────────
@@ -1411,14 +1456,34 @@ def main():
 
     if api_path:
         success, message = verify_resolve_connection(python_path, api_path, lib_path)
+        try:
+            py_abi_risk = is_abi_risk_python_version(_version_for_python(python_path))
+        except Exception:
+            py_abi_risk = False
         if success:
             if "not running" in message.lower():
                 print(f"  API:       {green('Module loads OK')}")
-                print(f"  Resolve:   {yellow('Not running')} — start Resolve to use MCP tools")
+                # If Resolve IS running but the bridge still reported no connection
+                # on a 3.13+ interpreter, that is the ABI-mismatch signature.
+                if resolve_running and py_abi_risk:
+                    print(
+                        f"  Resolve:   {yellow('Running, but the scripting bridge returned no connection')}"
+                    )
+                    print(
+                        f"             This can happen on Python 3.13+ with older Resolve builds. "
+                        f"If MCP tools fail, recreate the venv with Python 3.10-3.12."
+                    )
+                else:
+                    print(f"  Resolve:   {yellow('Not running')} — start Resolve to use MCP tools")
             else:
                 print(f"  Connected: {green(message)}")
         else:
             print(f"  Verify:    {yellow(message)}")
+            if py_abi_risk:
+                print(
+                    f"             On Python 3.13+ this may be an ABI mismatch with Resolve's "
+                    f"scripting library — try Python 3.10-3.12 if it persists."
+                )
     else:
         print(f"  {yellow('Skipped')} — Resolve API path not detected")
 

package/package.json

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

package/src/analysis_dashboard.py

@@ -4272,6 +4272,21 @@ HTML = r"""<!doctype html>
             </select>
           </label>
           <label>Default sample frames <input id="prefFrames" type="number" min="0" max="48" value="8"></label>
+          <label>Frame sampling mode
+            <select id="prefSamplingMode" onchange="updateSamplingModeHint()">
+              <option value="ask">ask · choose on first analysis</option>
+              <option value="fixed">Economy · flat frames, cheapest &amp; most predictable</option>
+              <option value="per_minute">Balanced · frames scale with duration (linear cost)</option>
+              <option value="adaptive_capped">Thorough · content-aware, bounded cost (recommended)</option>
+              <option value="adaptive">Thorough (uncapped) · content-aware, up to 512 frames</option>
+            </select>
+          </label>
+          <small class="pref-hint" id="samplingModeHint" style="display:block;margin:-4px 0 8px;opacity:0.75;"></small>
+          <div class="pref-inline-row" style="display:flex;gap:10px;flex-wrap:wrap;">
+            <label>Frames / minute <input id="prefSamplingRate" type="number" min="0.1" step="0.5" value="4" oninput="updateSamplingModeHint()"></label>
+            <label>Frame floor <input id="prefSamplingFloor" type="number" min="1" value="3" oninput="updateSamplingModeHint()"></label>
+            <label>Frame ceiling <input id="prefSamplingCeiling" type="number" min="1" value="80" oninput="updateSamplingModeHint()"></label>
+          </div>
           <label>Persistence
             <select id="prefAnalysisPersistence">
               <option value="session_only">session only</option>
@@ -4755,6 +4770,10 @@ HTML = r"""<!doctype html>
       prefVisionDefault: 'Controls whether visual frame analysis is used by default when an operation supports it.',
       prefTranscriptionDefault: 'Sets the default answer for transcript generation on audio-bearing clips.',
       prefSlateDetectionDefault: 'Controls whether slate detection should run or ask before adding slate-informed context.',
+      prefSamplingMode: 'Chooses how many frames each clip gets for visual analysis: Economy (flat), Balanced (scales with duration), or Thorough (content-aware, bounded). Drives both coverage and token cost.',
+      prefSamplingRate: 'Frames sampled per minute in Balanced mode (also seeds Thorough on short clips).',
+      prefSamplingFloor: 'Minimum frames per clip for duration/content-scaled modes.',
+      prefSamplingCeiling: 'Maximum frames per clip for Balanced and Thorough modes (the Thorough per-clip cap).',
       prefAnalysisPersistence: 'Chooses whether analysis artifacts stay session-only or keep reusable reports and frames.',
       prefAnalysisSummaryStyle: 'Tunes the language of generated summaries for editorial, QC, producer, or full-detail review.',
       prefReportFormat: 'Chooses compact readable reports, full reports, or machine-readable output for downstream agents.',
@@ -9088,6 +9107,12 @@ HTML = r"""<!doctype html>
       setControlValue('prefSourceTrust', media.source_trust || 'auto');
       setControlValue('prefDepth', media.default_depth || 'standard');
       setControlValue('prefFrames', media.default_sample_frames ?? 8);
+      // sampling_mode_default is null when unset → show "ask".
+      setControlValue('prefSamplingMode', media.sampling_mode_default || 'ask');
+      setControlValue('prefSamplingRate', media.sampling_frames_per_minute ?? 4);
+      setControlValue('prefSamplingFloor', media.sampling_frame_floor ?? 3);
+      setControlValue('prefSamplingCeiling', media.sampling_frame_ceiling ?? 80);
+      updateSamplingModeHint();
       setControlValue('prefAnalysisPersistence', media.analysis_persistence);
       const legacySummaryMap = { assistant_editor: 'creative', producer: 'creative', qc: 'technical' };
       const summaryStyle = legacySummaryMap[media.analysis_summary_style] || media.analysis_summary_style || 'concise';
@@ -9182,6 +9207,38 @@ HTML = r"""<!doctype html>
       };
     }
 
+    // Rough per-frame vision cost for the estimate (≈768px frame at typical
+    // tokenization). The engine's pre-call refusal estimates more conservatively.
+    const SAMPLING_TOKENS_PER_FRAME = 450;
+    function _fmtTokens(frames) {
+      const k = (frames * SAMPLING_TOKENS_PER_FRAME) / 1000;
+      return k >= 1 ? `~${k.toFixed(k < 10 ? 1 : 0)}k tokens` : `~${Math.round(k * 1000)} tokens`;
+    }
+    function updateSamplingModeHint() {
+      const hintEl = document.getElementById('samplingModeHint');
+      if (!hintEl) return;
+      const mode = ($('prefSamplingMode') || {}).value || 'ask';
+      const rate = Number(($('prefSamplingRate') || {}).value) || 4;
+      const floor = Number(($('prefSamplingFloor') || {}).value) || 3;
+      const ceil = Number(($('prefSamplingCeiling') || {}).value) || 80;
+      const fixed = Number(($('prefFrames') || {}).value) || 8;
+      let msg = '';
+      if (mode === 'ask') {
+        msg = 'You will be asked to pick a mode the first time you analyze. Recommended: Thorough.';
+      } else if (mode === 'fixed') {
+        msg = `Economy — flat ${fixed} frames per clip regardless of length (${_fmtTokens(fixed)}/clip). Most predictable.`;
+      } else if (mode === 'per_minute') {
+        const oneMin = Math.max(floor, Math.min(ceil, Math.round(rate)));
+        const tenMin = Math.max(floor, Math.min(ceil, Math.round(rate * 10)));
+        msg = `Balanced — ${rate}/min, bounded ${floor}–${ceil}. ~${oneMin}f (${_fmtTokens(oneMin)}) for 1 min · ~${tenMin}f (${_fmtTokens(tenMin)}) for 10 min. Linear cost.`;
+      } else if (mode === 'adaptive_capped') {
+        msg = `Thorough — content-aware (shot boundaries + flashes), bounded ${floor}–${ceil} frames/clip (${_fmtTokens(floor)}–${_fmtTokens(ceil)}). Best coverage, bounded cost.`;
+      } else if (mode === 'adaptive') {
+        msg = `Thorough (uncapped) — content-aware, no per-clip ceiling (up to 512 frames, ${_fmtTokens(512)}). Use only for short/few clips.`;
+      }
+      hintEl.textContent = msg;
+    }
+
     function setupPreferencePayload() {
       let markerColors = {};
       try {
@@ -9197,6 +9254,10 @@ HTML = r"""<!doctype html>
           source_trust: $('prefSourceTrust').value,
           default_depth: $('prefDepth').value,
           default_sample_frames: Number($('prefFrames').value || 8),
+          sampling_mode_default: $('prefSamplingMode').value,
+          sampling_frames_per_minute: Number($('prefSamplingRate').value || 4),
+          sampling_frame_floor: Number($('prefSamplingFloor').value || 3),
+          sampling_frame_ceiling: Number($('prefSamplingCeiling').value || 80),
           analysis_persistence: $('prefAnalysisPersistence').value,
           analysis_summary_style: $('prefAnalysisSummaryStyle').value,
           report_format: $('prefReportFormat').value,
@@ -13299,6 +13360,27 @@ class Handler(BaseHTTPRequestHandler):
                 "cleanup_frames": True,
                 "reuse_project_roots": self.state.related_project_roots(),
             }
+            # Honor the saved frame-sampling mode (or an explicit per-job override)
+            # so batch runs match the user's chosen coverage/cost. Falls back to the
+            # recommended mode when the user hasn't set a default yet (batch jobs
+            # shouldn't block on the first-run prompt).
+            try:
+                from src.server import (
+                    _media_analysis_effective_preferences as _ma_eff_prefs,
+                )
+                from src.utils import media_analysis as _ma_mod
+                _ma_prefs = _ma_eff_prefs()
+                params["sampling_mode"] = (
+                    body.get("sampling_mode")
+                    or _ma_prefs.get("sampling_mode_default")
+                    or _ma_mod.RECOMMENDED_SAMPLING_MODE
+                )
+                params["frames_per_minute"] = body.get("frames_per_minute") or _ma_prefs.get("sampling_frames_per_minute")
+                params["frame_floor"] = body.get("frame_floor") or _ma_prefs.get("sampling_frame_floor")
+                params["frame_ceiling"] = body.get("frame_ceiling") or _ma_prefs.get("sampling_frame_ceiling")
+            except Exception:
+                # Best-effort; the engine still applies its own defaults.
+                pass
             with self.state.lock:
                 created = create_batch_job_from_paths(
                     project_name=self.state.project_name,

package/src/granular/common.py

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