davinci-resolve-mcp 2.26.1 → 2.27.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 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`

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.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)

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.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.26.1",
+  "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.1"
+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()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 329-tool granular server instead
 """
 
-VERSION = "2.26.1"
+VERSION = "2.27.0"
 
 import base64
 import os
@@ -6312,6 +6312,18 @@ _MEDIA_ANALYSIS_DEFAULT_PREFS = {
     "source_trust": "auto",
     "default_depth": "standard",
     "default_sample_frames": 8,
+    # Frame-sampling mode — how many frames a clip gets for visual analysis.
+    # "ask" prompts the user to choose a standing default the first time they
+    # analyze; the choice is then saved here. Canonical modes (see
+    # media_analysis.SAMPLING_MODES): fixed (Economy), per_minute (Balanced),
+    # adaptive_capped (Thorough, recommended), adaptive (Thorough uncapped).
+    "sampling_mode_default": "ask",
+    # Tunables shared by Balanced + Thorough modes. frames_per_minute drives the
+    # Balanced target; frame_floor/frame_ceiling bound every duration/content
+    # scaled mode (the ceiling is also the Thorough per-clip cap).
+    "sampling_frames_per_minute": 4.0,
+    "sampling_frame_floor": 3,
+    "sampling_frame_ceiling": 80,
     "preferred_analysis_root": None,
     "preferred_generated_media_folder": None,
     "default_post_operation_page": "stay_put",
@@ -6580,6 +6592,29 @@ def _media_analysis_effective_preferences() -> Dict[str, Any]:
     except (TypeError, ValueError):
         sample_frames_int = 8
     effective["default_sample_frames"] = max(0, min(48, sample_frames_int))
+    # sampling_mode_default normalizes to a canonical mode, or None when unset /
+    # "ask" (None means "not yet chosen" → first-run prompt fires).
+    effective["sampling_mode_default"] = _normalize_sampling_mode_default(effective.get("sampling_mode_default"))
+
+    def _pos_number(value: Any, fallback: float) -> float:
+        try:
+            f = float(value)
+        except (TypeError, ValueError):
+            return fallback
+        return f if f > 0 else fallback
+
+    effective["sampling_frames_per_minute"] = _pos_number(
+        effective.get("sampling_frames_per_minute"), _media_analysis_module.DEFAULT_FRAMES_PER_MINUTE
+    )
+    effective["sampling_frame_floor"] = int(_pos_number(
+        effective.get("sampling_frame_floor"), _media_analysis_module.DEFAULT_FRAME_FLOOR
+    ))
+    ceiling = int(_pos_number(
+        effective.get("sampling_frame_ceiling"), _media_analysis_module.DEFAULT_FRAME_CEILING
+    ))
+    if ceiling < effective["sampling_frame_floor"]:
+        ceiling = effective["sampling_frame_floor"]
+    effective["sampling_frame_ceiling"] = ceiling
     effective["default_post_operation_page"] = _normalize_setup_choice(
         effective.get("default_post_operation_page"),
         ["stay_put", "media", "cut", "edit", "fusion", "color", "fairlight", "deliver"],
@@ -6743,6 +6778,148 @@ def _media_analysis_timed_marker_decision(p: Dict[str, Any]) -> Dict[str, Any]:
     }
 
 
+def _normalize_sampling_mode_default(value: Any) -> Optional[str]:
+    """Resolve a stored sampling_mode_default to a canonical mode, or None.
+
+    None means "not chosen yet" — covers an unset value and the "ask" sentinel,
+    both of which should trigger the first-run prompt.
+    """
+    if value is None:
+        return None
+    raw = str(value).strip().lower()
+    if raw in {"", "ask", "prompt", "ask_me", "ask_user", "none", "unset", "default"}:
+        return None
+    return _media_analysis_module.normalize_sampling_mode(value, default=None)
+
+
+def _sampling_mode_choice_from_params(p: Dict[str, Any]) -> Optional[str]:
+    """Read an explicit sampling-mode choice from analysis params.
+
+    Returns a canonical mode, the "ask" sentinel, or None when unspecified.
+    """
+    raw = _first_param(
+        p,
+        "sampling_mode",
+        "samplingMode",
+        "frame_sampling_mode",
+        "frameSamplingMode",
+        "analysis_mode",
+        "analysisMode",
+    )
+    if raw is None and isinstance(p.get("sampling"), dict):
+        raw = _first_param(p["sampling"], "mode", "sampling_mode", "samplingMode")
+    if raw is None:
+        return None
+    if str(raw).strip().lower() in {"ask", "prompt", "ask_me", "ask_user"}:
+        return "ask"
+    return _media_analysis_module.normalize_sampling_mode(raw, default=None)
+
+
+def _media_analysis_sampling_mode_prompt() -> Dict[str, Any]:
+    """First-run prompt offering the four sampling modes (Thorough recommended).
+
+    Each option saves the chosen mode as the standing default (save_sampling_default)
+    so the user is only asked once. Pass `sampling_mode` alone, without the save
+    flag, for a one-off run that doesn't change the default.
+    """
+    return {
+        "question": (
+            "How should frames be sampled for visual analysis? This sets your "
+            "default for future runs (pass sampling_mode per-call for a one-off)."
+        ),
+        "default_behavior": "Recommended: Thorough — content-aware coverage with a bounded, predictable cost.",
+        "options": [
+            {
+                "id": "fixed",
+                "label": "Economy",
+                "description": (
+                    "Flat ~8 frames per clip regardless of length. Cheapest and most "
+                    "predictable; good for proxies, triage, or known-short clips."
+                ),
+                "params": {"sampling_mode": "fixed", "save_sampling_default": True},
+            },
+            {
+                "id": "per_minute",
+                "label": "Balanced",
+                "description": (
+                    "Frames scale with duration (~4/min, bounded 3–80). Cost is linear "
+                    "in footage length and easy to predict; content-blind."
+                ),
+                "params": {"sampling_mode": "per_minute", "save_sampling_default": True},
+            },
+            {
+                "id": "adaptive_capped",
+                "label": "Thorough (recommended)",
+                "description": (
+                    "Content-aware: samples shot boundaries, representatives, and flash "
+                    "frames, bounded 3–80 per clip. Best coverage with a bounded cost."
+                ),
+                "params": {"sampling_mode": "adaptive_capped", "save_sampling_default": True},
+            },
+            {
+                "id": "adaptive",
+                "label": "Thorough (uncapped)",
+                "description": (
+                    "Content-aware with no per-clip ceiling (up to 512 frames). Use only "
+                    "when clips are known to be short or few — cost can grow fast."
+                ),
+                "params": {"sampling_mode": "adaptive", "save_sampling_default": True},
+            },
+        ],
+        "recommended": _media_analysis_module.RECOMMENDED_SAMPLING_MODE,
+    }
+
+
+def _media_analysis_sampling_mode_decision(p: Dict[str, Any]) -> Dict[str, Any]:
+    """Resolve the frame-sampling mode for an analysis run.
+
+    Resolution order:
+      1. Explicit `sampling_mode` param → one-off (persisted only if save flag set).
+      2. Saved `sampling_mode_default` preference → used silently.
+      3. Otherwise → prompt_required (first run); falls back to the recommended
+         mode so previews/automation still work, but the entry point surfaces the
+         prompt and blocks real execution.
+    """
+    choice = _sampling_mode_choice_from_params(p)
+    save_default = _media_analysis_bool(
+        _first_param(p, "save_sampling_default", "saveSamplingDefault", "set_sampling_default", "setSamplingDefault"),
+        False,
+    )
+    preferences = _read_media_analysis_preferences()
+    explicit_saved = "sampling_mode_default" in preferences
+    saved_default = _media_analysis_effective_preferences().get("sampling_mode_default")
+
+    recommended = _media_analysis_module.RECOMMENDED_SAMPLING_MODE
+    saved = None
+
+    if choice and choice != "ask":
+        mode = choice
+        source = "explicit"
+        if save_default:
+            saved = mode
+            preferences["sampling_mode_default"] = mode
+            preferences["sampling_mode_default_updated_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+            _write_media_analysis_preferences(preferences)
+            source = "saved_default"
+    elif choice == "ask":
+        mode = recommended
+        source = "prompt_required"
+    elif saved_default:
+        mode = saved_default
+        source = "saved_default" if explicit_saved else "default"
+    else:
+        mode = recommended
+        source = "prompt_required"
+
+    return {
+        "mode": mode,
+        "source": source,
+        "prompt_required": source == "prompt_required",
+        "saved_default": saved or saved_default,
+        "preferences_path": _media_analysis_preferences_path(),
+    }
+
+
 def _media_analysis_sync_marker_suggestions(detection: Dict[str, Any]) -> List[Dict[str, Any]]:
     suggestions = []
     for file_result in detection.get("files") or []:
@@ -8086,6 +8263,23 @@ def _media_analysis_apply_setup_defaults(action: str, p: Dict[str, Any]) -> Dict
                     )
                     applied["transcription_default"] = transcription_default
 
+    # Frame-sampling mode: resolve from explicit param > saved default > first-run
+    # prompt (recommended fallback). Inject mode + tunables so the analysis engine
+    # picks them up via _resolve_sampling_config; stash the decision so the entry
+    # point can surface the first-run prompt.
+    if action in {"plan", "analyze_file", "analyze_clip", "analyze_bin", "analyze_project", "analyze_timeline", "analyze_sequence", "start_batch_job"}:
+        sampling_decision = _media_analysis_sampling_mode_decision(out)
+        if not _has_any_param(out, "sampling_mode", "samplingMode", "frame_sampling_mode", "frameSamplingMode"):
+            out["sampling_mode"] = sampling_decision["mode"]
+            applied["sampling_mode"] = sampling_decision["mode"]
+        if not _has_any_param(out, "frames_per_minute", "framesPerMinute"):
+            out["frames_per_minute"] = prefs.get("sampling_frames_per_minute")
+        if not _has_any_param(out, "frame_floor", "frameFloor"):
+            out["frame_floor"] = prefs.get("sampling_frame_floor")
+        if not _has_any_param(out, "frame_ceiling", "frameCeiling"):
+            out["frame_ceiling"] = prefs.get("sampling_frame_ceiling")
+        out["_sampling_mode_decision"] = sampling_decision
+
     if action in {"plan", "analyze_file", "analyze_clip", "analyze_bin", "analyze_project", "analyze_timeline", "analyze_sequence", "start_batch_job", "publish_clip_metadata"}:
         if not _has_any_param(
             out,
@@ -9391,7 +9585,9 @@ def _setup_media_analysis_defaults() -> Dict[str, Any]:
             "source_trust": ["auto", "filename", "low", "medium", "high"],
             "default_depth": ["quick", "standard", "deep"],
             "default_post_operation_page": ["stay_put", "media", "cut", "edit", "fusion", "color", "fairlight", "deliver"],
+            "sampling_mode_default": ["ask", "fixed", "per_minute", "adaptive_capped", "adaptive"],
         },
+        "sampling_mode_labels": dict(_media_analysis_module.SAMPLING_MODE_LABELS),
     }
 
 
@@ -9512,6 +9708,24 @@ def _setup_set_media_analysis_defaults(media_defaults: Dict[str, Any], dry_run:
         "defaultsampleframes": "default_sample_frames",
         "sample_frames": "default_sample_frames",
         "sampleframes": "default_sample_frames",
+        "sampling_mode_default": "sampling_mode_default",
+        "samplingmodedefault": "sampling_mode_default",
+        "sampling_mode": "sampling_mode_default",
+        "samplingmode": "sampling_mode_default",
+        "analysis_mode": "sampling_mode_default",
+        "analysismode": "sampling_mode_default",
+        "sampling_frames_per_minute": "sampling_frames_per_minute",
+        "samplingframesperminute": "sampling_frames_per_minute",
+        "frames_per_minute": "sampling_frames_per_minute",
+        "framesperminute": "sampling_frames_per_minute",
+        "sampling_frame_floor": "sampling_frame_floor",
+        "samplingframefloor": "sampling_frame_floor",
+        "frame_floor": "sampling_frame_floor",
+        "framefloor": "sampling_frame_floor",
+        "sampling_frame_ceiling": "sampling_frame_ceiling",
+        "samplingframeceiling": "sampling_frame_ceiling",
+        "frame_ceiling": "sampling_frame_ceiling",
+        "frameceiling": "sampling_frame_ceiling",
     }
 
     requested: Dict[str, Any] = {}
@@ -9640,6 +9854,37 @@ def _setup_set_media_analysis_defaults(media_defaults: Dict[str, Any], dry_run:
             except (TypeError, ValueError):
                 return _err("default_sample_frames must be an integer between 0 and 48.")
             set_or_clear(key, raw_value, max(0, min(48, frames_int)))
+        elif key == "sampling_mode_default":
+            # "ask" clears the saved default so the first-run prompt fires again;
+            # otherwise normalize a canonical key or friendly label.
+            if _setup_text_key(raw_value) in {"ask", "prompt", "askme", "askuser"}:
+                next_preferences.pop("sampling_mode_default", None)
+                next_preferences.pop("sampling_mode_default_updated_at", None)
+                updates[key] = {"before": before.get(key), "after": None, "cleared": True}
+            else:
+                normalized = _media_analysis_module.normalize_sampling_mode(raw_value, default=None)
+                if normalized is None:
+                    return _err(
+                        "Unsupported sampling_mode_default. Use ask, fixed/economy, "
+                        "per_minute/balanced, adaptive_capped/thorough, or adaptive."
+                    )
+                set_or_clear(key, raw_value, normalized)
+        elif key == "sampling_frames_per_minute":
+            try:
+                rate = float(raw_value)
+            except (TypeError, ValueError):
+                return _err("sampling_frames_per_minute must be a positive number.")
+            if rate <= 0:
+                return _err("sampling_frames_per_minute must be greater than 0.")
+            set_or_clear(key, raw_value, rate)
+        elif key in {"sampling_frame_floor", "sampling_frame_ceiling"}:
+            try:
+                n = int(raw_value) if not isinstance(raw_value, bool) else 0
+            except (TypeError, ValueError):
+                return _err(f"{key} must be a positive integer.")
+            if n <= 0:
+                return _err(f"{key} must be a positive integer.")
+            set_or_clear(key, raw_value, n)
         elif key == "default_post_operation_page":
             normalized = _normalize_setup_choice(
                 raw_value,
@@ -9797,6 +10042,10 @@ def _setup_clear_defaults(keys: Any, dry_run: bool) -> Dict[str, Any]:
         "metadata_writeback_default": "media_analysis.metadata_writeback_default",
         "ask_before_metadata_publish": "media_analysis.ask_before_metadata_publish",
         "dry_run_first_default": "media_analysis.dry_run_first_default",
+        "sampling_mode_default": "media_analysis.sampling_mode_default",
+        "sampling_frames_per_minute": "media_analysis.sampling_frames_per_minute",
+        "sampling_frame_floor": "media_analysis.sampling_frame_floor",
+        "sampling_frame_ceiling": "media_analysis.sampling_frame_ceiling",
     }
     media_payload: Dict[str, Any] = {}
     if clear_all or "media_analysis" in normalized_keys:
@@ -9899,6 +10148,14 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
                 "media_analysis.metadata_writeback_default": {"values": [True, False], "storage": _media_analysis_preferences_path()},
                 "media_analysis.ask_before_metadata_publish": {"values": [True, False], "storage": _media_analysis_preferences_path()},
                 "media_analysis.dry_run_first_default": {"values": [True, False], "storage": _media_analysis_preferences_path()},
+                "media_analysis.sampling_mode_default": {
+                    "description": "Frame-sampling mode for visual analysis. 'ask' prompts on first analysis to set a standing default. fixed=Economy (flat frames), per_minute=Balanced (duration-scaled), adaptive_capped=Thorough (content-aware, bounded — recommended), adaptive=Thorough uncapped.",
+                    "values": ["ask", "fixed", "per_minute", "adaptive_capped", "adaptive"],
+                    "storage": _media_analysis_preferences_path(),
+                },
+                "media_analysis.sampling_frames_per_minute": {"description": "Frames per minute for Balanced mode (also seeds Thorough on short clips).", "values": "number > 0 (default 4)", "storage": _media_analysis_preferences_path()},
+                "media_analysis.sampling_frame_floor": {"description": "Minimum frames per clip for duration/content-scaled modes.", "values": "integer > 0 (default 3)", "storage": _media_analysis_preferences_path()},
+                "media_analysis.sampling_frame_ceiling": {"description": "Maximum frames per clip for Balanced + Thorough modes (the Thorough per-clip cap).", "values": "integer > 0 (default 80)", "storage": _media_analysis_preferences_path()},
                 "updates.mode": {
                     "description": "Local MCP update policy.",
                     "values": sorted(_SETUP_UPDATE_MODES),
@@ -13191,6 +13448,31 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
     """
     p = _media_analysis_apply_setup_defaults(action, dict(params or {}))
 
+    # First-run frame-sampling prompt: if the user has never chosen a sampling
+    # mode (and didn't pass one this call), ask before spending any vision
+    # tokens. Re-running with sampling_mode=<choice> saves it as the default;
+    # passing sampling_mode explicitly any time is a one-off that skips this.
+    _sampling_decision = p.get("_sampling_mode_decision") if isinstance(p, dict) else None
+    if (
+        isinstance(_sampling_decision, dict)
+        and _sampling_decision.get("prompt_required")
+        and action in {"analyze_clip", "analyze_file", "analyze_bin", "analyze_project", "analyze_sequence", "analyze_timeline", "start_batch_job"}
+    ):
+        return {
+            "success": True,
+            "status": "confirmation_required",
+            "confirmation_required": True,
+            "sampling_mode_prompt": _media_analysis_sampling_mode_prompt(),
+            "recommended_sampling_mode": _media_analysis_module.RECOMMENDED_SAMPLING_MODE,
+            "message": (
+                "Choose a frame-sampling mode for visual analysis. Re-run with "
+                "sampling_mode set to one of fixed/per_minute/adaptive_capped/adaptive "
+                "(the chosen value is saved as your default), or set it in the control "
+                "panel under Analysis Modes. Pass sampling_mode per-call any time for a one-off."
+            ),
+            "preferences_path": _media_analysis_preferences_path(),
+        }
+
     # E2 — capture original action + scope before the dispatch may rewrite
     # `action` (e.g. analyze_clip → plan). Used by _e2_wrap below to attach
     # an `escalation` block when a (scope, action) pair fails repeatedly.

package/src/utils/analysis_caps.py

@@ -18,17 +18,26 @@ deferred a "$ cost cap" axis. Token budgets are the unit of currency here.
 
 | Dimension | minimal | standard | generous | unlimited |
 |-----------|--------:|---------:|---------:|----------:|
-| response_chars                | 5,000   | 25,000    | 100,000    | None |
-| vision_tokens_per_clip        | 5,000   | 25,000    | 100,000    | None |
-| frames_per_clip               | 4       | 8         | 24         | None |
-| vision_tokens_per_job         | 50,000  | 250,000   | 1,000,000  | None |
-| vision_tokens_per_day         | 100,000 | 500,000   | 2,000,000  | None |
-| wall_clock_seconds_per_call   | 30      | 90        | 300        | None |
-| max_frame_dim_pixels          | 512     | 768       | 1280       | None |
+| response_chars                | 5,000   | 25,000     | 100,000    | None |
+| vision_tokens_per_clip        | 16,000  | 100,000    | 250,000    | None |
+| frames_per_clip               | 12      | 80         | 200        | None |
+| vision_tokens_per_job         | 60,000  | 1,000,000  | 3,000,000  | None |
+| vision_tokens_per_day         | 150,000 | 2,000,000  | 6,000,000  | None |
+| wall_clock_seconds_per_call   | 30      | 90         | 300        | None |
+| max_frame_dim_pixels          | 512     | 768        | 1280       | None |
 
 `minimal` = preview/triage mode. `standard` = realistic per-project default.
 `generous` = high-fidelity analysis on a few specific clips. `unlimited` = all
 guards off; use only when you're certain about the input size.
+
+NOTE on `frames_per_clip`: this is a *safety ceiling*, not the primary frame
+dial. How many frames a clip actually gets is chosen by the `sampling_mode`
+(Economy/Balanced/Thorough — see media_analysis.SAMPLING_MODES), which is
+duration- and content-aware. `frames_per_clip` only clips the result if the mode
+would exceed it. The standard ceiling (80) matches the default Thorough ceiling
+so the mode is never silently truncated; lower it to hard-cap cost, raise it for
+unusually long/cutty clips. (Before sampling modes existed this defaulted to 8
+and *was* the frame dial — that flat cap is what made long clips under-covered.)
 """
 
 from __future__ import annotations
@@ -74,30 +83,30 @@ CAP_PRESETS: Dict[str, Caps] = {
     PRESET_MINIMAL: Caps(
         preset=PRESET_MINIMAL,
         response_chars=5_000,
-        vision_tokens_per_clip=5_000,
-        frames_per_clip=4,
-        vision_tokens_per_job=50_000,
-        vision_tokens_per_day=100_000,
+        vision_tokens_per_clip=16_000,
+        frames_per_clip=12,
+        vision_tokens_per_job=60_000,
+        vision_tokens_per_day=150_000,
         wall_clock_seconds_per_call=30,
         max_frame_dim_pixels=512,
     ),
     PRESET_STANDARD: Caps(
         preset=PRESET_STANDARD,
         response_chars=25_000,
-        vision_tokens_per_clip=25_000,
-        frames_per_clip=8,
-        vision_tokens_per_job=250_000,
-        vision_tokens_per_day=500_000,
+        vision_tokens_per_clip=100_000,
+        frames_per_clip=80,
+        vision_tokens_per_job=1_000_000,
+        vision_tokens_per_day=2_000_000,
         wall_clock_seconds_per_call=90,
         max_frame_dim_pixels=768,
     ),
     PRESET_GENEROUS: Caps(
         preset=PRESET_GENEROUS,
         response_chars=100_000,
-        vision_tokens_per_clip=100_000,
-        frames_per_clip=24,
-        vision_tokens_per_job=1_000_000,
-        vision_tokens_per_day=2_000_000,
+        vision_tokens_per_clip=250_000,
+        frames_per_clip=200,
+        vision_tokens_per_job=3_000_000,
+        vision_tokens_per_day=6_000_000,
         wall_clock_seconds_per_call=300,
         max_frame_dim_pixels=1280,
     ),

package/src/utils/media_analysis.py

@@ -624,6 +624,103 @@ FRAME_CAPS = {
 }
 HARD_FRAME_CAP = 512
 
+# ── Frame-sampling modes ─────────────────────────────────────────────────────
+# How many frames a clip gets is governed by a `sampling_mode`. `depth` still
+# governs *which* analysis layers run; the mode governs frame coverage + cost.
+#
+#   fixed           "Economy"            — flat N frames (depth-derived / max_analysis_frames),
+#                                          independent of clip length. Most predictable cost.
+#   per_minute      "Balanced"           — N = clamp(minutes * frames_per_minute, floor, ceiling).
+#                                          Cost is linear in footage length; content-blind.
+#   adaptive_capped "Thorough"           — content-aware (per-shot boundaries + flashes), bounded
+#                                          by [floor, frame_ceiling]. Best coverage, bounded cost.
+#   adaptive        "Thorough (uncapped)" — content-aware, bounded only by the absolute HARD_FRAME_CAP.
+#                                          Use only when clips are known to be short/few.
+#
+# The math-layer default is `adaptive` so any caller that doesn't thread a
+# sampling config keeps the legacy demand-driven behaviour. The *product*
+# default (what new analysis runs use) is resolved at the preference layer in
+# server.py and recommends "adaptive_capped" (Thorough).
+SAMPLING_MODES = {"fixed", "per_minute", "adaptive", "adaptive_capped"}
+DEFAULT_SAMPLING_MODE = "adaptive"
+RECOMMENDED_SAMPLING_MODE = "adaptive_capped"
+DEFAULT_FRAMES_PER_MINUTE = 4.0
+DEFAULT_FRAME_FLOOR = 3
+DEFAULT_FRAME_CEILING = 80
+
+# Thoroughness ranking — used for cache reuse: a richer prior report satisfies a
+# cheaper mode, but switching *up* forces a re-sample.
+SAMPLING_MODE_RANK = {"fixed": 0, "per_minute": 1, "adaptive_capped": 2, "adaptive": 3}
+
+# User-facing labels (prompt + control panel).
+SAMPLING_MODE_LABELS = {
+    "fixed": "Economy",
+    "per_minute": "Balanced",
+    "adaptive_capped": "Thorough",
+    "adaptive": "Thorough (uncapped)",
+}
+
+_SAMPLING_MODE_ALIASES = {
+    "economy": "fixed", "fixed": "fixed", "flat": "fixed",
+    "balanced": "per_minute", "per_minute": "per_minute", "perminute": "per_minute",
+    "per-minute": "per_minute", "duration": "per_minute",
+    "thorough": "adaptive_capped", "adaptive_capped": "adaptive_capped",
+    "adaptive-capped": "adaptive_capped", "capped": "adaptive_capped",
+    "thorough_uncapped": "adaptive", "thorough (uncapped)": "adaptive",
+    "adaptive": "adaptive", "uncapped": "adaptive",
+}
+
+
+def normalize_sampling_mode(value: Any, default: Optional[str] = None) -> Optional[str]:
+    """Resolve a user-supplied mode string (label or key) to a canonical mode."""
+    raw = str(value or "").strip().lower().replace("_", "_")
+    return _SAMPLING_MODE_ALIASES.get(raw, default)
+
+
+def _resolve_sampling_config(params: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """Read sampling mode + tunables from analysis params, applying defaults."""
+    params = params or {}
+
+    def _first(*keys: str) -> Any:
+        for key in keys:
+            if key in params and params[key] is not None:
+                return params[key]
+        return None
+
+    mode = normalize_sampling_mode(
+        _first("sampling_mode", "samplingMode"), default=DEFAULT_SAMPLING_MODE
+    ) or DEFAULT_SAMPLING_MODE
+
+    def _pos_float(value: Any, fallback: float) -> float:
+        try:
+            f = float(value)
+        except (TypeError, ValueError):
+            return fallback
+        return f if f > 0 else fallback
+
+    rate = _pos_float(_first("frames_per_minute", "framesPerMinute"), DEFAULT_FRAMES_PER_MINUTE)
+    floor = int(_pos_float(_first("frame_floor", "frameFloor"), DEFAULT_FRAME_FLOOR))
+    ceiling = int(_pos_float(_first("frame_ceiling", "frameCeiling"), DEFAULT_FRAME_CEILING))
+    if ceiling < floor:
+        ceiling = floor
+    return {
+        "mode": mode,
+        "frames_per_minute": rate,
+        "frame_floor": floor,
+        "frame_ceiling": ceiling,
+    }
+
+
+def _clamp_int(value: Any, low: int, high: int) -> int:
+    if high < low:
+        high = low
+    v = int(value)
+    if v < low:
+        return low
+    if v > high:
+        return high
+    return v
+
 
 def slugify(value: Any, fallback: str = "untitled") -> str:
     raw = str(value or "").strip().lower()
@@ -1441,13 +1538,14 @@ def analysis_request_signature(
     depth: str,
     options: Dict[str, Any],
     frame_count: int,
+    sampling: Optional[Dict[str, Any]] = None,
 ) -> Dict[str, Any]:
     """Return the cache signature for a requested analysis profile."""
     transcription = options.get("transcription") or {}
     vision = options.get("vision") or {}
     marker_plan = options.get("marker_plan") or {}
     vision_prompt = vision.get("prompt") or DEFAULT_VISION_ANALYSIS_PROMPT
-    return {
+    signature = {
         "analysis_version": ANALYSIS_VERSION,
         "depth": depth,
         "analysis_keyframe_budget": int(frame_count or 0),
@@ -1506,6 +1604,16 @@ def analysis_request_signature(
             },
         }),
     }
+    # Recorded outside signature_hash so it doesn't bust pre-existing caches;
+    # mode changes are reconciled by thoroughness rank in _report_cache_state.
+    if sampling:
+        signature["analysis_sampling"] = {
+            "mode": sampling.get("mode"),
+            "frames_per_minute": sampling.get("frames_per_minute"),
+            "frame_floor": sampling.get("frame_floor"),
+            "frame_ceiling": sampling.get("frame_ceiling"),
+        }
+    return signature
 
 
 def _timestamp_from_analyzed_at(value: Any) -> Optional[float]:
@@ -1659,6 +1767,7 @@ def build_plan(
     }
     gaps = _required_capability_gaps(depth, options, caps)
     frame_count = _bounded_frame_count(depth, params.get("max_analysis_frames"))
+    sampling_config = _resolve_sampling_config(params)
     transcription_enabled = _coerce_bool((options.get("transcription") or {}).get("enabled"), default=DEFAULT_TRANSCRIPTION_ENABLED)
     notes = [
         "Plans describe analysis before execution.",
@@ -1721,11 +1830,12 @@ def build_plan(
     clip_plans = []
     for record in records:
         artifacts = _artifact_paths(root["project_root"], record, depth, options)
-        request_signature = analysis_request_signature(record, depth, options, frame_count)
+        request_signature = analysis_request_signature(record, depth, options, frame_count, sampling=sampling_config)
         existing: Optional[Dict[str, Any]] = None
         clip_plan = {
             "record": record,
             "analysis_keyframe_budget": frame_count,
+            "sampling": sampling_config,
             "analysis_signature": request_signature,
             "cache_status": "not_checked",
             "artifacts": artifacts,
@@ -1853,6 +1963,8 @@ def build_plan(
         "estimated_seconds": per_clip_seconds * len(records),
         "estimated_seconds_after_reuse": per_clip_seconds * max(0, len(records) - reusable_count),
         "analysis_keyframe_budget_per_clip": frame_count,
+        "sampling": sampling_config,
+        "sampling_mode": sampling_config.get("mode"),
         "reuse_existing": reuse_existing,
         "force_refresh": force_refresh,
         "reuse_policy": reuse_policy,
@@ -2414,24 +2526,19 @@ def _cut_boundary_analysis(
     }
 
 
-def _compute_demand_driven_budget(
-    requested_budget: int,
-    cut_analysis: Optional[Dict[str, Any]],
+def _demand_frame_count(
+    cut_analysis: Dict[str, Any],
     duration_seconds: Optional[float],
 ) -> int:
-    """Compute the effective frame-sampling budget driven by analysis demand.
+    """Frames the content *demands* so vision can populate the per-shot schema.
 
-    Demand sources (so vision can populate the V2 per-shot schema):
+    Demand sources:
       - Per shot: 1 representative (midpoint) + 2 boundary frames + duration-scaled extras
         (+1 for shots >5s, +1 for shots >15s, +1 per additional 15s beyond 30s)
       - Per flash_candidate: 1 mid-frame for vision adjudication (preserve all)
       - Per cut_point: a small buffer for cuts not covered by shot boundaries
-
-    Safety ceiling: HARD_FRAME_CAP capped by duration so a 10s clip cannot request 500 frames.
+      - Clip-level: first_usable, last_usable, midpoint
     """
-    if not isinstance(cut_analysis, dict):
-        return min(max(int(requested_budget or 0), 0), HARD_FRAME_CAP)
-
     per_shot_demand = 0
     for shot in cut_analysis.get("shot_ranges") or []:
         if not isinstance(shot, dict):
@@ -2458,13 +2565,84 @@ def _compute_demand_driven_budget(
     # Clip-level frames (first_usable, last_usable, midpoint)
     clip_buffer = 4
 
-    demand = per_shot_demand + flash_count + cut_buffer + clip_buffer
+    return per_shot_demand + flash_count + cut_buffer + clip_buffer
+
+
+def _compute_demand_driven_budget(
+    requested_budget: int,
+    cut_analysis: Optional[Dict[str, Any]],
+    duration_seconds: Optional[float],
+    sampling: Optional[Dict[str, Any]] = None,
+) -> int:
+    """Resolve the effective frame-sampling budget for the active sampling mode.
+
+    Modes (see SAMPLING_MODES):
+      - fixed:           flat `requested_budget`, duration-independent.
+      - per_minute:      clamp(minutes * frames_per_minute, floor, ceiling); content-blind.
+      - adaptive_capped: content demand (see _demand_frame_count), clamped to [floor, ceiling].
+      - adaptive:        content demand, clamped only by a generous duration-scaled HARD_FRAME_CAP
+                         (legacy behaviour; the default when no sampling config is threaded).
+
+    `requested_budget` (depth-derived / max_analysis_frames) acts as a floor for the
+    adaptive modes so an explicit request is never undercut.
+    """
+    sampling = sampling or {}
+    mode = normalize_sampling_mode(sampling.get("mode"), default=DEFAULT_SAMPLING_MODE) or DEFAULT_SAMPLING_MODE
+    rate = sampling.get("frames_per_minute") or DEFAULT_FRAMES_PER_MINUTE
+    floor = int(sampling.get("frame_floor") or DEFAULT_FRAME_FLOOR)
+    ceiling = int(sampling.get("frame_ceiling") or DEFAULT_FRAME_CEILING)
+    if ceiling < floor:
+        ceiling = floor
+    requested = max(int(requested_budget or 0), 0)
+    minutes = max(0.0, float(duration_seconds or 0) / 60.0)
+    per_minute_count = int(round(minutes * float(rate)))
+
+    if mode == "fixed":
+        return min(requested, HARD_FRAME_CAP)
+
+    if mode == "per_minute":
+        return _clamp_int(per_minute_count, floor, min(ceiling, HARD_FRAME_CAP))
+
+    # Adaptive modes need shot/cut analysis. Without it, fall back to a duration
+    # estimate (adaptive_capped) or the legacy requested-only budget (adaptive).
+    if not isinstance(cut_analysis, dict):
+        if mode == "adaptive_capped":
+            return _clamp_int(max(requested, per_minute_count), floor, min(ceiling, HARD_FRAME_CAP))
+        return min(max(requested, 0), HARD_FRAME_CAP)
+
+    demand = _demand_frame_count(cut_analysis, duration_seconds)
+    target = max(requested, demand, floor)
 
-    # Duration-scaled safety ceiling: clips can't request hundreds of frames per second.
-    # Floor at 64 so short clips still have headroom; ceiling at HARD_FRAME_CAP.
-    duration_cap = max(64, min(HARD_FRAME_CAP, int((duration_seconds or 0) * 2)))
+    if mode == "adaptive_capped":
+        return _clamp_int(target, floor, min(ceiling, HARD_FRAME_CAP))
 
-    return min(max(int(requested_budget or 0), demand), duration_cap)
+    # adaptive (uncapped): only the absolute hard cap, scaled by duration so a
+    # 10s clip cannot request 500 frames. Floor at 64 for short-clip headroom.
+    duration_cap = max(64, min(HARD_FRAME_CAP, int(float(duration_seconds or 0) * 2)))
+    return _clamp_int(target, floor, duration_cap)
+
+
+def _even_interval_samples(
+    duration: float,
+    count: int,
+    frame_step: float,
+) -> List[Dict[str, Any]]:
+    """Content-blind evenly-spaced samples (Economy / Balanced modes).
+
+    Returns exactly `count` frames at the midpoints of `count` equal slices of
+    [0, duration], so cost is a clean function of `count` and never inflated by
+    shot/cut demand. Used when the user has chosen a predictable, content-blind mode.
+    """
+    if count <= 0 or duration <= 0:
+        return []
+    out: List[Dict[str, Any]] = []
+    for i in range(count):
+        t = duration * (i + 0.5) / count
+        out.append({
+            "time_seconds": _clamp_sample_time(float(t), duration),
+            "selection_reason": "interval",
+        })
+    return out
 
 
 def _sample_times(
@@ -2474,21 +2652,25 @@ def _sample_times(
     *,
     fps: Optional[float] = None,
     cut_analysis: Optional[Dict[str, Any]] = None,
+    sampling: Optional[Dict[str, Any]] = None,
 ) -> List[Dict[str, Any]]:
-    """Two-pass frame allocation.
+    """Frame allocation. Content-blind for Economy/Balanced; demand-driven otherwise.
 
-    Pass 1 (reservations, always allocated — demand-driven, not budget-bounded):
-      - Per shot: shot_representative (midpoint), shot_start, shot_end boundaries,
-        duration-scaled progress samples (+1 for shots >5s, +1 for shots >15s,
-        +1 per 15s beyond 30s).
-      - Per flash_candidate: mid-frame for vision adjudication.
+    Economy (fixed) / Balanced (per_minute): exactly `budget` evenly-spaced frames
+    (see _even_interval_samples) — predictable cost, ignores shot structure.
 
-    Pass 2 (priority fill, consumes remaining budget):
-      - cut_before/cut_after pairs (for cuts not covered by shot boundaries)
-      - first_usable, last_usable, scene_change, midpoint, interval fillers
+    Thorough (adaptive / adaptive_capped) — two-pass demand-driven allocation:
+      Pass 1 (reservations, always allocated — demand-driven, not budget-bounded):
+        - Per shot: shot_representative (midpoint), shot_start, shot_end boundaries,
+          duration-scaled progress samples (+1 for shots >5s, +1 for shots >15s,
+          +1 per 15s beyond 30s).
+        - Per flash_candidate: mid-frame for vision adjudication.
+      Pass 2 (priority fill, consumes remaining budget):
+        - cut_before/cut_after pairs (for cuts not covered by shot boundaries)
+        - first_usable, last_usable, scene_change, midpoint, interval fillers
 
-    The caller passes `budget` as the soft target. Reservations always land
-    (demand-driven); priority fill is what `budget` constrains.
+      The caller passes `budget` as the soft target. Reservations always land
+      (demand-driven); priority fill is what `budget` constrains.
 
     Returns a time-sorted list of sample candidates.
     """
@@ -2498,6 +2680,12 @@ def _sample_times(
     cut_analysis = cut_analysis if isinstance(cut_analysis, dict) else {}
     frame_step = _frame_step_seconds(fps)
 
+    # Content-blind modes: even-interval sampling of exactly `budget` frames so
+    # cost stays predictable and is not inflated by per-shot reservations.
+    mode = normalize_sampling_mode((sampling or {}).get("mode"), default=DEFAULT_SAMPLING_MODE) or DEFAULT_SAMPLING_MODE
+    if mode in {"fixed", "per_minute"}:
+        return _even_interval_samples(duration, budget, frame_step)
+
     # ===================== Pass 1: Reservations =====================
     reserved: List[Dict[str, Any]] = []
 
@@ -2729,6 +2917,7 @@ def _motion_and_keyframes(
     fps: Optional[float] = None,
     cut_analysis: Optional[Dict[str, Any]] = None,
     write_frames: bool = True,
+    sampling: Optional[Dict[str, Any]] = None,
 ) -> Dict[str, Any]:
     sampled = []
     previous_raw = None
@@ -2736,8 +2925,8 @@ def _motion_and_keyframes(
     if isinstance(cut_analysis, dict):
         required_boundary_frames += len(cut_analysis.get("cut_points") or []) * 2
         required_boundary_frames += len(cut_analysis.get("flash_frame_candidates") or [])
-    effective_budget = _compute_demand_driven_budget(budget, cut_analysis, duration)
-    times = _sample_times(duration, scene_items, effective_budget, fps=fps, cut_analysis=cut_analysis)
+    effective_budget = _compute_demand_driven_budget(budget, cut_analysis, duration, sampling=sampling)
+    times = _sample_times(duration, scene_items, effective_budget, fps=fps, cut_analysis=cut_analysis, sampling=sampling)
     frames_dir = artifacts.get("frames_dir")
     for index, sample in enumerate(times, 1):
         time_seconds = float(sample.get("time_seconds") or 0.0)
@@ -2971,6 +3160,15 @@ def _report_cache_state(
     if report_budget < request_budget:
         issues.append("analysis_keyframe_budget_lower_than_requested")
 
+    # Sampling-mode reconciliation: a prior report sampled under a less-thorough
+    # mode can't satisfy a request for a more-thorough one. The reverse (richer
+    # report, cheaper request) is reused as a free upgrade.
+    report_mode = (report_signature.get("analysis_sampling") or {}).get("mode")
+    request_mode = (request_signature.get("analysis_sampling") or {}).get("mode")
+    if request_mode and report_mode and request_mode != report_mode:
+        if SAMPLING_MODE_RANK.get(request_mode, 0) > SAMPLING_MODE_RANK.get(report_mode, 0):
+            issues.append("sampling_mode_increased")
+
     report_layers = report_signature.get("layers") or {}
     request_layers = request_signature.get("layers") or {}
     report_vision = report_layers.get("vision") or {}
@@ -4747,6 +4945,7 @@ async def execute_plan_async(
                 fps=fps,
                 cut_analysis=readthrough.get("cut_analysis"),
                 write_frames=keep_frame_artifacts_for_vision or not _coerce_bool(params.get("cleanup_frames"), default=False),
+                sampling=clip_plan.get("sampling"),
             )
             if artifacts.get("motion_json"):
                 _write_json(artifacts["motion_json"], motion)