samuelgursky/davinci-resolve-mcp

v2.27.0

Frame-sampling modes for media analysis (issue #46) — choose how many frames each clip gets, with predictable cost per tier, plus a first-run default prompt and full control-panel exposure.

Added

• sampling_mode on all analyze actions, decoupled from depth:
  • Economy (fixed) — flat N evenly-spaced, content-blind frames. Cheapest, most predictable.
  • Balanced (per_minute) — clamp(minutes × frames_per_minute, floor, ceiling); linear cost.
  • Thorough (adaptive_capped, recommended/default) — content-aware (shot boundaries, representatives, flash candidates), bounded [floor, ceiling].
  • Thorough (uncapped) (adaptive) — content-aware up to the 512-frame hard cap.
• First-run flow: with no saved default, the first analyze returns confirmation_required + a sampling_mode_prompt; choosing a mode saves it as the standing default (mirrors timed_markers_default). sampling_mode per call is a one-off.
• Control panel: Preferences → Frame sampling mode selector + frames_per_minute / frame_floor / frame_ceiling with a live per-clip token-cost estimate. Batch jobs honor the saved default.
• tests/test_sampling_modes.py (30 tests).

Fixed

• Long clips were under-covered: the demand-driven engine already scaled by duration/content, but the caps layer flat-truncated its output back to 8 frames. frames_per_clip is now a safety ceiling, not the frame dial.

Changed

• Analysis-caps presets retuned: frames_per_clip minimal/standard/generous = 12/80/200 (was 4/8/24); per-clip/job/day vision-token caps raised so the default Thorough mode isn't refused by the per-clip cap.
• Cache reuse re-samples only when switching up the thoroughness rank; a richer prior report still satisfies a cheaper mode.

Documentation

• docs/guides/media-analysis-guide.md and docs/SKILL.md document the sampling modes, tunables, and first-run flow.

Validation

• Static checks (test_import, audit_api_parity, npm pack, node CLI) clean; 155 focused unit tests pass.
• Live-tested end-to-end on a synthetic 6-shot clip with real ffmpeg frame extraction (caught and fixed a bug where per-shot reservations overrode the Economy/Balanced budgets). No DaVinci Resolve scripting behavior changed — ffmpeg-based frame sampling and preference plumbing only.