davinci-resolve-mcp 2.61.0 → 2.61.1

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 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.61.1
+
+The strata cleanup batch deferred from the v2.61.0 review — behavior-neutral
+consolidation and hot-path efficiency. No new actions or parameters.
+
+### Changed
+
+- **One clip resolver** — `strata.resolve_clip()` replaces the four drifting
+  per-module wrappers, and rides the pre-v9 auto-ingest fallback hoisted out
+  of deep_vision into `analysis_store.resolve_clip_uuid_ingesting()`: a clip
+  ref that resolves for `deepen` now resolves identically for every strata
+  action, including on older analysis roots.
+- **One float32 codec** — `pack_curve`/`unpack_curve` delegate to
+  `embeddings.pack_vector`/`unpack_vector` instead of duplicating the BLOB
+  convention.
+- **Decode once** — `strata_run` decodes the media file a single time when
+  several audio analyzers run (prosody + beat_grid previously each ran a full
+  ffmpeg decode); the shared `_audio_context` preamble also collapses their
+  duplicated require/resolve/decode blocks.
+- **Registry-derived capabilities** — `ANALYZERS` carries run function plus
+  requires/writes metadata; `capabilities()` derives from it, so adding an
+  analyzer is one entry.
+- **Query-layer caching** — word-find hits clustering in one clip unpack each
+  curve blob once, and `timeline_strata` resolves + bundles a source clip
+  reused across many placements once.
+- **Sargable event windows (schema v15)** — windowed `read_events` bounds its
+  span-overlap lower edge by the track's `MAX(duration_seconds)` (a b-tree
+  descent via the new `ix_events_clip_track_span` index) so
+  `ix_events_clip_track` range-seeks instead of scanning the track.
+- `backfill_words` iterates report blobs lazily with a transcription
+  prefilter instead of loading every blob into memory; `detect_breaths`
+  drops its unreachable non-numpy fallbacks.
+
+### Validation
+
+- Full offline suite: 1,431 tests green (13 new covering the shared resolver
+  + pre-v9 fallback, codec identity, decode-once, per-clip caching, long-span
+  window overlap, and the index range-seek query plan). No Resolve behavior
+  changed; live test not required.
+
 ## What's New in v2.61.0
 
 Perception strata — a timecoded track model over every analyzed clip, plus the

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.61.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.61.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.61.0"
+VERSION = "2.61.1"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

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

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.61.0"
+VERSION = "2.61.1"
 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 341-tool granular server instead
 """
 
-VERSION = "2.61.0"
+VERSION = "2.61.1"
 
 import base64
 import os

package/src/utils/analysis_store.py

@@ -200,6 +200,45 @@ def resolve_clip_uuid(conn: sqlite3.Connection, ref: Any) -> Optional[str]:
     return None
 
 
+def resolve_clip_uuid_ingesting(
+    project_root: str, conn: sqlite3.Connection, clip_ref: Any
+) -> Optional[str]:
+    """resolve_clip_uuid plus the pre-v9 fallback: when the DB has no rows
+    for the ref, walk clips/*/analysis.json for a matching report and ingest
+    it. Shared by deep_vision and the strata layers so a clip that resolves
+    for one resolves for all."""
+    clip_uuid = resolve_clip_uuid(conn, clip_ref)
+    if clip_uuid:
+        return clip_uuid
+    ma = _ma()
+    clips_root = os.path.join(project_root, "clips")
+    candidate = str(clip_ref or "")
+    if not os.path.isdir(clips_root):
+        return None
+    for entry in sorted(os.listdir(clips_root)):
+        report_path = os.path.join(clips_root, entry, "analysis.json")
+        if not os.path.isfile(report_path):
+            continue
+        try:
+            with open(report_path, "r", encoding="utf-8") as handle:
+                report = json.load(handle)
+        except (OSError, json.JSONDecodeError):
+            continue
+        clip_block = report.get("clip") or {}
+        if candidate not in (
+            entry,
+            str(clip_block.get("clip_id") or ""),
+            str(clip_block.get("media_id") or ""),
+            ma.normalize_path(clip_block.get("file_path") or ""),
+        ):
+            continue
+        ingest = ingest_report(project_root, report, clip_dir=os.path.join(clips_root, entry))
+        if ingest.get("success"):
+            return str(ingest["clip_uuid"])
+        return None
+    return None
+
+
 # ── ingest ────────────────────────────────────────────────────────────────────
 
 

package/src/utils/deep_vision.py

@@ -123,37 +123,8 @@ def _now() -> str:
 def _clip_context(project_root: str, clip_ref: Any) -> Tuple[Optional[Dict[str, Any]], Optional[str]]:
     """Resolve a clip to (context, error). Auto-ingests the JSON report when
     the DB has no rows yet (pre-v9 analysis roots)."""
-    ma = _ma()
     conn = timeline_brain_db.connect(project_root)
-    clip_uuid = analysis_store.resolve_clip_uuid(conn, clip_ref)
-    if not clip_uuid:
-        # Pre-v9 report? Find the analysis.json by walking clips/ and ingest it.
-        clips_root = os.path.join(project_root, "clips")
-        candidate = str(clip_ref or "")
-        if os.path.isdir(clips_root):
-            for entry in sorted(os.listdir(clips_root)):
-                report_path = os.path.join(clips_root, entry, "analysis.json")
-                if not os.path.isfile(report_path):
-                    continue
-                try:
-                    with open(report_path, "r", encoding="utf-8") as handle:
-                        report = json.load(handle)
-                except (OSError, json.JSONDecodeError):
-                    continue
-                clip_block = report.get("clip") or {}
-                if candidate not in (
-                    entry,
-                    str(clip_block.get("clip_id") or ""),
-                    str(clip_block.get("media_id") or ""),
-                    ma.normalize_path(clip_block.get("file_path") or ""),
-                ):
-                    continue
-                ingest = analysis_store.ingest_report(
-                    project_root, report, clip_dir=os.path.join(clips_root, entry)
-                )
-                if ingest.get("success"):
-                    clip_uuid = ingest["clip_uuid"]
-                break
+    clip_uuid = analysis_store.resolve_clip_uuid_ingesting(project_root, conn, clip_ref)
     if not clip_uuid:
         return None, f"No analyzed clip found for {clip_ref!r} (run db_ingest if this is an older analysis root)"
     clip_row = conn.execute("SELECT * FROM clips WHERE clip_uuid = ?", (clip_uuid,)).fetchone()

package/src/utils/strata.py

@@ -21,12 +21,14 @@ from __future__ import annotations
 import json
 import logging
 import math
+import os
 import sqlite3
 import time
-from array import array
 from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
 
 from src.utils import timeline_brain_db
+from src.utils.embeddings import pack_vector as _pack_vector
+from src.utils.embeddings import unpack_vector as _unpack_vector
 
 logger = logging.getLogger("resolve-mcp.strata")
 
@@ -60,20 +62,67 @@ def _dumps(value: Any) -> str:
     return json.dumps(value, sort_keys=True, default=str)
 
 
-# ── float32 blob convention (shared with embeddings.vector) ──────────────────
+# ── clip resolution — the ONE resolver for every strata surface ──────────────
+
+
+def resolve_clip(
+    project_root: str,
+    clip_ref: Any,
+    *,
+    require_media: bool = False,
+) -> Tuple[Optional[sqlite3.Connection], Optional[Dict[str, Any]], Optional[Dict[str, Any]]]:
+    """Resolve a clip ref to ``(conn, clip, error)`` — exactly one of
+    ``clip``/``error`` is set (conn is always usable when clip is set).
+
+    ``clip`` carries {clip_uuid, clip_name, file_path, duration_seconds, fps}.
+    Uses the same pre-v9 auto-ingest fallback as deep_vision, so a ref that
+    resolves for deepen resolves identically for every strata action. With
+    ``require_media=True`` the clip's media file must exist on disk.
+    """
+    from src.utils import analysis_store
+
+    conn = timeline_brain_db.connect(project_root)
+    clip_uuid = analysis_store.resolve_clip_uuid_ingesting(project_root, conn, clip_ref)
+    if not clip_uuid:
+        return conn, None, {
+            "success": False,
+            "error": f"Unknown clip ref: {clip_ref!r} (older analysis root? run db_ingest first)",
+        }
+    row = conn.execute(
+        "SELECT clip_uuid, clip_name, file_path, duration_seconds, fps FROM clips WHERE clip_uuid = ?",
+        (clip_uuid,),
+    ).fetchone()
+    if row is None:
+        return conn, None, {"success": False, "error": f"No clips row for {clip_uuid}"}
+    clip = {
+        "clip_uuid": clip_uuid,
+        "clip_name": row["clip_name"],
+        "file_path": row["file_path"],
+        "duration_seconds": row["duration_seconds"],
+        "fps": row["fps"],
+    }
+    if require_media:
+        file_path = clip["file_path"]
+        if not file_path or not os.path.isfile(file_path):
+            return conn, None, {
+                "success": False,
+                "error": f"Media file not accessible for clip {clip['clip_name']!r}: {file_path!r}",
+                "clip_uuid": clip_uuid,
+            }
+    return conn, clip, None
+
+
+# ── float32 blob convention — ONE codec, shared with embeddings.vector ───────
 
 
 def pack_curve(values: Sequence[float]) -> bytes:
     """Encode a float sequence as a little-endian float32 BLOB."""
-    arr = array("f", (float(v) for v in values))
-    return arr.tobytes()
+    return _pack_vector([float(v) for v in values])
 
 
 def unpack_curve(blob: bytes) -> List[float]:
     """Decode a float32 BLOB back to a list of floats."""
-    arr = array("f")
-    arr.frombytes(blob)
-    return list(arr)
+    return _unpack_vector(blob)
 
 
 def curve_stats(values: Sequence[float]) -> Dict[str, Any]:
@@ -230,9 +279,23 @@ def read_events(
     # inside it — a 3 s pause that began before the window is still a pause.
     # Point events (no duration) use the half-open [start, end) convention.
     if start_seconds is not None:
-        sql += " AND (time_seconds >= ? OR time_seconds + COALESCE(duration_seconds, 0) > ?)"
-        args.append(float(start_seconds))
-        args.append(float(start_seconds))
+        start = float(start_seconds)
+        # A bare OR on the overlap test is non-sargable (ix_events_clip_track
+        # could never range-seek on time_seconds). Bound the lower edge by the
+        # track's longest span instead: no overlapping event can start earlier
+        # than start - MAX(duration). The MAX probe is a single b-tree descent
+        # via ix_events_clip_track_span (v15).
+        span_sql = "SELECT MAX(duration_seconds) FROM events WHERE clip_uuid = ?"
+        span_args: List[Any] = [clip_uuid]
+        if track:
+            span_sql += " AND track = ?"
+            span_args.append(track)
+        max_span = conn.execute(span_sql, span_args).fetchone()[0] or 0.0
+        sql += (
+            " AND time_seconds >= ?"
+            " AND (time_seconds >= ? OR time_seconds + COALESCE(duration_seconds, 0) > ?)"
+        )
+        args.extend([start - float(max_span), start, start])
     if end_seconds is not None:
         sql += " AND time_seconds < ?"
         args.append(float(end_seconds))
@@ -476,13 +539,19 @@ def backfill_transcript_words(project_root: str) -> Dict[str, Any]:
     re-running any analysis. Idempotent.
     """
     conn = timeline_brain_db.connect(project_root)
-    rows = conn.execute("SELECT clip_uuid, report_json FROM analysis_reports").fetchall()
-    clips_seen = 0
+    clips_seen = int(conn.execute("SELECT COUNT(*) FROM analysis_reports").fetchone()[0])
     clips_with_words = 0
     words_written = 0
     with timeline_brain_db.transaction(project_root) as txn:
-        for row in rows:
-            clips_seen += 1
+        # Lazy cursor + substring prefilter: never hold every multi-MB report
+        # blob in memory at once, and skip parsing reports that cannot carry
+        # words. Reads and writes share the cached connection but touch
+        # different tables, so interleaving is safe.
+        cursor = txn.execute(
+            "SELECT clip_uuid, report_json FROM analysis_reports "
+            "WHERE report_json LIKE '%\"transcription\"%'"
+        )
+        for row in cursor:
             try:
                 report = json.loads(row["report_json"])
             except (TypeError, ValueError):
@@ -507,14 +576,12 @@ def backfill_transcript_words(project_root: str) -> Dict[str, Any]:
 
 def strata_status(project_root: str, clip_ref: Any = None) -> Dict[str, Any]:
     """Project-level (or per-clip) strata inventory."""
-    from src.utils import analysis_store
-
     conn = timeline_brain_db.connect(project_root)
     if clip_ref is not None:
-        clip_uuid = analysis_store.resolve_clip_uuid(conn, clip_ref)
-        if not clip_uuid:
-            return {"success": False, "error": f"Unknown clip ref: {clip_ref!r}"}
-        return {"success": True, "clip_uuid": clip_uuid, **list_tracks(conn, clip_uuid)}
+        conn, clip, err = resolve_clip(project_root, clip_ref)
+        if err:
+            return err
+        return {"success": True, "clip_uuid": clip["clip_uuid"], **list_tracks(conn, clip["clip_uuid"])}
 
     def _count(sql: str) -> int:
         return int(conn.execute(sql).fetchone()[0])

package/src/utils/strata_analyzers.py

@@ -17,10 +17,8 @@ and DB writes.
 
 from __future__ import annotations
 
-import json
 import logging
 import math
-import os
 import shutil
 import subprocess
 from typing import Any, Dict, List, Optional, Sequence, Tuple
@@ -71,33 +69,30 @@ def _ensure_tool_path() -> None:
 
 
 def capabilities() -> Dict[str, Any]:
-    """What the local analyzers can run on this machine."""
+    """What the local analyzers can run on this machine.
+
+    Derived from the ANALYZERS registry — adding an analyzer there is the
+    single edit; this report and run_analyzers' default set follow.
+    """
     _ensure_tool_path()
     ffmpeg = shutil.which("ffmpeg")
+    have = {"ffmpeg": bool(ffmpeg), "numpy": _np is not None}
+    analyzers: Dict[str, Any] = {}
+    for name, spec in ANALYZERS.items():
+        probe = spec.get("capability")
+        if probe is not None:
+            analyzers[name] = probe()
+            continue
+        requires = spec["requires"]
+        analyzers[name] = {
+            "available": all(have.get(req, False) for req in requires),
+            "requires": list(requires),
+            "writes": spec["writes"],
+        }
     return {
         "ffmpeg": {"available": bool(ffmpeg), "path": ffmpeg},
         "numpy": {"available": _np is not None},
-        "analyzers": {
-            "prosody": {
-                "available": bool(ffmpeg) and _np is not None,
-                "requires": ["ffmpeg", "numpy"],
-                "writes": {
-                    "curves": ["pitch", "vocal_energy", "speech_rate"],
-                    "events": ["pause", "breath", "hesitation"],
-                },
-            },
-            "beat_grid": {
-                "available": bool(ffmpeg) and _np is not None,
-                "requires": ["ffmpeg", "numpy"],
-                "writes": {"events": ["beat", "downbeat"]},
-            },
-            "motion_energy": {
-                "available": bool(ffmpeg),
-                "requires": ["ffmpeg"],
-                "writes": {"curves": ["motion_energy"]},
-            },
-            "face": _face_capability(),
-        },
+        "analyzers": analyzers,
     }
 
 
@@ -126,36 +121,10 @@ def _require(*needs: str) -> Optional[Dict[str, Any]]:
 
 
 def _clip_row(project_root: str, clip_ref: Any) -> Tuple[Optional[Dict[str, Any]], Optional[Dict[str, Any]]]:
-    """Resolve a clip ref to {clip_uuid, file_path, duration_seconds, fps}."""
-    from src.utils import analysis_store
-
-    conn = timeline_brain_db.connect(project_root)
-    clip_uuid = analysis_store.resolve_clip_uuid(conn, clip_ref)
-    if not clip_uuid:
-        return None, {
-            "success": False,
-            "error": f"Unknown clip ref: {clip_ref!r} (older analysis root? run db_ingest first)",
-        }
-    row = conn.execute("SELECT * FROM clips WHERE clip_uuid = ?", (clip_uuid,)).fetchone()
-    if row is None:
-        return None, {"success": False, "error": f"No clips row for {clip_uuid}"}
-    file_path = row["file_path"]
-    if not file_path or not os.path.isfile(file_path):
-        return None, {
-            "success": False,
-            "error": f"Media file not accessible for clip {row['clip_name']!r}: {file_path!r}",
-            "clip_uuid": clip_uuid,
-        }
-    return (
-        {
-            "clip_uuid": clip_uuid,
-            "clip_name": row["clip_name"],
-            "file_path": file_path,
-            "duration_seconds": row["duration_seconds"],
-            "fps": row["fps"],
-        },
-        None,
-    )
+    """Resolve a clip ref to {clip_uuid, file_path, duration_seconds, fps};
+    analyzers read the media file, so it must exist."""
+    _conn, clip, err = strata.resolve_clip(project_root, clip_ref, require_media=True)
+    return clip, err
 
 
 # ── decoding ─────────────────────────────────────────────────────────────────
@@ -179,6 +148,40 @@ def decode_audio(path: str, sample_rate: int = AUDIO_SAMPLE_RATE, timeout: int =
     return _np.frombuffer(proc.stdout, dtype=_np.float32)
 
 
+def _audio_context(
+    project_root: str,
+    clip_ref: Any,
+    *,
+    clip: Optional[Dict[str, Any]] = None,
+    samples: "Any" = None,
+) -> Tuple[Optional[Dict[str, Any]], "Any", Optional[Dict[str, Any]]]:
+    """The shared audio-analyzer preamble: deps → clip row → decoded samples.
+
+    Returns (clip, samples, error). Pass a previously resolved ``clip`` and
+    decoded ``samples`` to skip the ffmpeg decode — run_analyzers uses this
+    so prosody and beat_grid share one decode of the same media file.
+    """
+    missing = _require("ffmpeg", "numpy")
+    if missing:
+        return None, None, missing
+    if clip is None:
+        clip, err = _clip_row(project_root, clip_ref)
+        if err:
+            return None, None, err
+    if samples is None:
+        try:
+            samples = decode_audio(clip["file_path"])
+        except (RuntimeError, subprocess.TimeoutExpired) as exc:
+            return None, None, {"success": False, "error": str(exc), "clip_uuid": clip["clip_uuid"]}
+    if samples.size == 0:
+        return None, None, {
+            "success": False,
+            "error": "clip has no decodable audio",
+            "clip_uuid": clip["clip_uuid"],
+        }
+    return clip, samples, None
+
+
 # ── prosody: pure compute ────────────────────────────────────────────────────
 
 
@@ -326,7 +329,9 @@ def detect_breaths(
     """
     if not len(energy):
         return []
-    arr = _np.asarray(energy, dtype=_np.float64) if _np is not None else None
+    # numpy assumed: every caller sits behind _require("numpy"), matching the
+    # sibling compute functions in this module.
+    arr = _np.asarray(energy, dtype=_np.float64)
     breaths: List[Dict[str, Any]] = []
     for pause in pauses:
         start = float(pause["time_seconds"])
@@ -335,9 +340,9 @@ def detect_breaths(
         hi = min(int((start + dur) * curve_rate), len(energy))
         if hi - lo < 3:
             continue
-        seg = arr[lo:hi] if arr is not None else energy[lo:hi]
-        floor = float(_np.percentile(seg, 20)) if arr is not None else min(seg)
-        peak_idx = int(_np.argmax(seg)) if arr is not None else max(range(len(seg)), key=lambda i: seg[i])
+        seg = arr[lo:hi]
+        floor = float(_np.percentile(seg, 20))
+        peak_idx = int(_np.argmax(seg))
         peak = float(seg[peak_idx])
         # Bump: clearly above the gap floor, clearly below speech (~1.0 scale).
         if peak >= floor + 0.05 and peak <= 0.5:
@@ -354,29 +359,26 @@ def detect_breaths(
 # ── prosody: runner ──────────────────────────────────────────────────────────
 
 
-def run_prosody(project_root: str, clip_ref: Any) -> Dict[str, Any]:
+def run_prosody(
+    project_root: str,
+    clip_ref: Any,
+    *,
+    clip: Optional[Dict[str, Any]] = None,
+    samples: "Any" = None,
+) -> Dict[str, Any]:
     """Compute + persist prosody strata for one clip.
 
     Writes curves pitch / vocal_energy / speech_rate and events pause /
     breath / hesitation. Requires the clip's media file, ffmpeg, numpy, and
-    (for word-derived tracks) transcript_words rows.
+    (for word-derived tracks) transcript_words rows. ``clip``/``samples``
+    accept a pre-resolved row and pre-decoded audio (see _audio_context).
     """
-    missing = _require("ffmpeg", "numpy")
-    if missing:
-        return missing
-    clip, err = _clip_row(project_root, clip_ref)
+    clip, samples, err = _audio_context(project_root, clip_ref, clip=clip, samples=samples)
     if err:
         return err
     conn = timeline_brain_db.connect(project_root)
     words = strata.read_words(conn, clip["clip_uuid"])
 
-    try:
-        samples = decode_audio(clip["file_path"])
-    except (RuntimeError, subprocess.TimeoutExpired) as exc:
-        return {"success": False, "error": str(exc), "clip_uuid": clip["clip_uuid"]}
-    if samples.size == 0:
-        return {"success": False, "error": "clip has no decodable audio", "clip_uuid": clip["clip_uuid"]}
-
     duration = clip["duration_seconds"] or (samples.size / AUDIO_SAMPLE_RATE)
     energy = compute_energy_curve(samples)
     pitch = compute_pitch_curve(samples, energy=energy)
@@ -447,7 +449,6 @@ def compute_beat_grid(
     Downbeats are a phase-of-strongest-onset estimate every 4 beats —
     explicitly low-confidence (no meter detection).
     """
-    hop = int(sample_rate * HOP_SECONDS)
     win = int(sample_rate * FRAME_SECONDS)
     frames, _, _ = _frame_signal(samples, sample_rate)
     if frames.shape[0] < 16:
@@ -500,20 +501,20 @@ def compute_beat_grid(
     }
 
 
-def run_beat_grid(project_root: str, clip_ref: Any) -> Dict[str, Any]:
-    """Compute + persist the musical beat grid for one clip."""
-    missing = _require("ffmpeg", "numpy")
-    if missing:
-        return missing
-    clip, err = _clip_row(project_root, clip_ref)
+def run_beat_grid(
+    project_root: str,
+    clip_ref: Any,
+    *,
+    clip: Optional[Dict[str, Any]] = None,
+    samples: "Any" = None,
+) -> Dict[str, Any]:
+    """Compute + persist the musical beat grid for one clip.
+
+    ``clip``/``samples`` accept a pre-resolved row and pre-decoded audio
+    (see _audio_context)."""
+    clip, samples, err = _audio_context(project_root, clip_ref, clip=clip, samples=samples)
     if err:
         return err
-    try:
-        samples = decode_audio(clip["file_path"])
-    except (RuntimeError, subprocess.TimeoutExpired) as exc:
-        return {"success": False, "error": str(exc), "clip_uuid": clip["clip_uuid"]}
-    if samples.size == 0:
-        return {"success": False, "error": "clip has no decodable audio", "clip_uuid": clip["clip_uuid"]}
 
     grid = compute_beat_grid(samples)
     beat_events = [
@@ -641,11 +642,36 @@ def _run_face(project_root: str, clip_ref: Any) -> Dict[str, Any]:
     return strata_faces.run_face_strata(project_root, clip_ref)
 
 
-ANALYZERS = {
-    "prosody": run_prosody,
-    "beat_grid": run_beat_grid,
-    "motion_energy": run_motion_energy,
-    "face": _run_face,
+# The single analyzer registry: run function + dependency/track metadata.
+# capabilities() and run_analyzers' default set derive from it, so a new
+# analyzer is one entry here (or a "capability" probe for stacks that
+# self-describe, like face). "audio" marks analyzers that consume the shared
+# mono PCM decode.
+ANALYZERS: Dict[str, Dict[str, Any]] = {
+    "prosody": {
+        "run": run_prosody,
+        "requires": ("ffmpeg", "numpy"),
+        "writes": {
+            "curves": ["pitch", "vocal_energy", "speech_rate"],
+            "events": ["pause", "breath", "hesitation"],
+        },
+        "audio": True,
+    },
+    "beat_grid": {
+        "run": run_beat_grid,
+        "requires": ("ffmpeg", "numpy"),
+        "writes": {"events": ["beat", "downbeat"]},
+        "audio": True,
+    },
+    "motion_energy": {
+        "run": run_motion_energy,
+        "requires": ("ffmpeg",),
+        "writes": {"curves": ["motion_energy"]},
+    },
+    "face": {
+        "run": _run_face,
+        "capability": _face_capability,
+    },
 }
 
 
@@ -658,7 +684,8 @@ def run_analyzers(
 
     Explicitly-requested analyzers run (and fail loudly if deps are
     missing); the default set runs only what this machine can run, and
-    names what it skipped.
+    names what it skipped. When several audio analyzers run, the media
+    file is decoded once and the samples are shared.
     """
     caps = capabilities()["analyzers"]
     if analyzers:
@@ -674,7 +701,24 @@ def run_analyzers(
             "error": f"Unknown analyzer(s): {', '.join(unknown)}",
             "available": sorted(ANALYZERS),
         }
-    results = {name: ANALYZERS[name](project_root, clip_ref) for name in names}
+
+    audio_names = [n for n in names if ANALYZERS[n].get("audio")]
+    shared_clip: Optional[Dict[str, Any]] = None
+    shared_samples: "Any" = None
+    shared_err: Optional[Dict[str, Any]] = None
+    if len(audio_names) > 1:
+        shared_clip, shared_samples, shared_err = _audio_context(project_root, clip_ref)
+
+    results: Dict[str, Any] = {}
+    for name in names:
+        if name in audio_names and shared_err is not None:
+            results[name] = shared_err
+        elif name in audio_names and shared_clip is not None:
+            results[name] = ANALYZERS[name]["run"](
+                project_root, clip_ref, clip=shared_clip, samples=shared_samples
+            )
+        else:
+            results[name] = ANALYZERS[name]["run"](project_root, clip_ref)
     out: Dict[str, Any] = {
         "success": all(r.get("success") for r in results.values()),
         "results": results,

package/src/utils/strata_queries.py

@@ -27,16 +27,8 @@ def _norm_word(word: str) -> str:
 
 
 def _resolve(project_root: str, clip_ref: Any) -> Tuple[Optional[str], Optional[Dict[str, Any]]]:
-    from src.utils import analysis_store
-
-    conn = timeline_brain_db.connect(project_root)
-    clip_uuid = analysis_store.resolve_clip_uuid(conn, clip_ref)
-    if not clip_uuid:
-        return None, {
-            "success": False,
-            "error": f"Unknown clip ref: {clip_ref!r} (older analysis root? run db_ingest first)",
-        }
-    return clip_uuid, None
+    _conn, clip, err = strata.resolve_clip(project_root, clip_ref)
+    return (clip["clip_uuid"] if clip else None), err
 
 
 def _finite(values: Sequence[float]) -> List[float]:
@@ -204,28 +196,45 @@ def _clip_bundle(
     end: Optional[float],
     *,
     include_curve_values: bool = False,
+    cache: Optional[Dict[str, Dict[str, Any]]] = None,
 ) -> Dict[str, Any]:
-    """Everything the strata know about one clip window, joined."""
+    """Everything the strata know about one clip window, joined.
+
+    ``cache`` (keyed by clip_uuid) memoizes the window-independent reads —
+    the clips row, present-track lists, and full curve blobs — so callers
+    building many bundles for the same clip (word-find hits cluster by clip)
+    unpack each curve once. Windowed reads stay per call.
+    """
+    memo = cache.setdefault(clip_uuid, {}) if cache is not None else {}
     bundle: Dict[str, Any] = {"clip_uuid": clip_uuid}
-    row = conn.execute(
-        "SELECT clip_name, duration_seconds, fps FROM clips WHERE clip_uuid = ?", (clip_uuid,)
-    ).fetchone()
+    if "row" not in memo:
+        memo["row"] = conn.execute(
+            "SELECT clip_name, duration_seconds, fps FROM clips WHERE clip_uuid = ?", (clip_uuid,)
+        ).fetchone()
+    row = memo["row"]
     if row:
         bundle["clip_name"] = row["clip_name"]
         bundle["fps"] = row["fps"]
 
     bundle["words"] = strata.read_words(conn, clip_uuid, start_seconds=start, end_seconds=end)
 
+    if "event_tracks" not in memo:
+        memo["event_tracks"] = _present_tracks(conn, clip_uuid, "events", _EVENT_TRACK_ORDER)
     events: Dict[str, List[Dict[str, Any]]] = {}
-    for track in _present_tracks(conn, clip_uuid, "events", _EVENT_TRACK_ORDER):
+    for track in memo["event_tracks"]:
         hits = strata.read_events(conn, clip_uuid, track, start_seconds=start, end_seconds=end)
         if hits:
             events[track] = hits
     bundle["events"] = events
 
+    if "curve_tracks" not in memo:
+        memo["curve_tracks"] = _present_tracks(conn, clip_uuid, "curves", _CURVE_TRACK_ORDER)
+    loaded_curves = memo.setdefault("curves_by_track", {})
     curves: Dict[str, Any] = {}
-    for track in _present_tracks(conn, clip_uuid, "curves", _CURVE_TRACK_ORDER):
-        curve = strata.read_curve(conn, clip_uuid, track)
+    for track in memo["curve_tracks"]:
+        if track not in loaded_curves:
+            loaded_curves[track] = strata.read_curve(conn, clip_uuid, track)
+        curve = loaded_curves[track]
         if curve is None:
             continue
         lo = start if start is not None else 0.0
@@ -303,6 +312,7 @@ def strata_query(
         sql += " ORDER BY w.clip_uuid, w.start_seconds LIMIT ?"
         args.append(int(limit))
         hits = []
+        bundle_cache: Dict[str, Dict[str, Any]] = {}
         for row in conn.execute(sql, args).fetchall():
             t = row["start_seconds"]
             hit: Dict[str, Any] = {
@@ -318,6 +328,7 @@ def strata_query(
                     max(0.0, t - context_seconds),
                     t + context_seconds,
                     include_curve_values=include_curve_values,
+                    cache=bundle_cache,
                 )
             hits.append(hit)
         return {"success": True, "mode": "word_find", "match": match_word, "hits": hits}
@@ -405,10 +416,17 @@ def timeline_strata(
 
     placements = []
     unresolved = []
+    # A source clip reused across many cuts resolves and bundles once: the
+    # whole-clip bundle (start=end=None) is identical for every placement.
+    resolve_memo: Dict[str, Optional[str]] = {}
+    bundle_memo: Dict[str, Dict[str, Any]] = {}
     for row in conn.execute(sql, args).fetchall():
-        clip_uuid = analysis_store.resolve_clip_uuid(conn, row["media_pool_item_id"])
+        media_id = row["media_pool_item_id"]
+        if media_id not in resolve_memo:
+            resolve_memo[media_id] = analysis_store.resolve_clip_uuid(conn, media_id)
+        clip_uuid = resolve_memo[media_id]
         placement = {
-            "media_pool_item_id": row["media_pool_item_id"],
+            "media_pool_item_id": media_id,
             "track_type": row["track_type"],
             "track_index": row["track_index"],
             "record_in_frame": row["in_frame"],
@@ -421,11 +439,13 @@ def timeline_strata(
                 placement["record_in_seconds"] = round((row["in_frame"] - start_frame) / fps, 3)
                 placement["record_out_seconds"] = round((row["out_frame"] - start_frame) / fps, 3)
         if clip_uuid:
-            placement["strata"] = _clip_bundle(
-                conn, clip_uuid, None, None, include_curve_values=include_curve_values
-            )
+            if clip_uuid not in bundle_memo:
+                bundle_memo[clip_uuid] = _clip_bundle(
+                    conn, clip_uuid, None, None, include_curve_values=include_curve_values
+                )
+            placement["strata"] = bundle_memo[clip_uuid]
         else:
-            unresolved.append(row["media_pool_item_id"])
+            unresolved.append(media_id)
         placements.append(placement)
 
     return {

package/src/utils/strata_story.py

@@ -84,16 +84,10 @@ def _beat_uuid() -> str:
 
 
 def _resolve(project_root: str, clip_ref: Any):
-    from src.utils import analysis_store
-
-    conn = timeline_brain_db.connect(project_root)
-    clip_uuid = analysis_store.resolve_clip_uuid(conn, clip_ref)
-    if not clip_uuid:
-        return None, None, {
-            "success": False,
-            "error": f"Unknown clip ref: {clip_ref!r} (older analysis root? run db_ingest first)",
-        }
-    return conn, clip_uuid, None
+    conn, clip, err = strata.resolve_clip(project_root, clip_ref)
+    if err:
+        return None, None, err
+    return conn, clip["clip_uuid"], None
 
 
 def plan_story_beats(project_root: str, clip_ref: Any) -> Dict[str, Any]:

package/src/utils/timeline_brain_db.py

@@ -29,7 +29,7 @@ from typing import Callable, Dict, Iterator, Optional, Tuple
 
 logger = logging.getLogger("resolve-mcp.timeline-brain-db")
 
-SCHEMA_VERSION = 14
+SCHEMA_VERSION = 15
 DB_FILENAME = "timeline_brain.sqlite"
 SOUL_DIRNAME = "_soul"
 
@@ -924,6 +924,23 @@ def _migrate_v14_timeline_version_timebase(conn: sqlite3.Connection) -> None:
         conn.execute("ALTER TABLE timeline_versions ADD COLUMN start_frame INTEGER")
 
 
+@register_migration(15)
+def _migrate_v15_events_span_index(conn: sqlite3.Connection) -> None:
+    """Index (clip_uuid, track, duration_seconds) on events.
+
+    strata.read_events bounds its windowed lower edge by the track's longest
+    span (the sargable form of span-overlap); this index makes that
+    MAX(duration_seconds) probe a single b-tree descent instead of a track
+    scan.
+    """
+    conn.executescript(
+        """
+        CREATE INDEX IF NOT EXISTS ix_events_clip_track_span
+            ON events(clip_uuid, track, duration_seconds);
+        """
+    )
+
+
 def latest_version(conn: sqlite3.Connection, timeline_name: str) -> Optional[int]:
     """Return the highest archived version number for `timeline_name`, or None."""
     row = conn.execute(