davinci-resolve-mcp 2.61.0 → 2.62.0

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/background_jobs.py

@@ -0,0 +1,108 @@
+"""In-process registry for long DaVinci Resolve operations run off-thread.
+
+Some Resolve calls (transcription, subtitle generation, scene-cut and Dolby
+analysis, timeline export/import) block for minutes — longer than an MCP
+client's tool-window timeout. start_job runs such a call on a daemon thread and
+returns a short id immediately; the caller polls job_status until the job
+reports "done" (with its result) or "error" (with the message).
+
+The worker runs fn inside resolve_busy.long_resolve_op(label) so another
+Resolve-touching tool call meets the advisory "busy" answer instead of colliding
+on the single-threaded scripting bridge (job_status / list_jobs are
+connection-free and never contend). Serialization comes from that preflight, not
+from the bridge itself; the busy record tracks a single owner, so two jobs
+started in quick succession have a brief window before the first's record shows.
+
+Finished jobs are pruned once older than MAX_JOB_AGE_SECONDS on any access, so
+the registry cannot grow without bound.
+"""
+from __future__ import annotations
+
+import threading
+import time
+import uuid
+from typing import Any, Callable, Dict, List, Optional
+
+from src.utils.resolve_busy import long_resolve_op
+
+# A finished job is dropped from the registry this long after it ended.
+MAX_JOB_AGE_SECONDS = 60 * 60
+
+_lock = threading.Lock()
+_jobs: Dict[str, Dict[str, Any]] = {}
+
+
+def _prune_locked(now: float) -> None:
+    stale = [
+        job_id
+        for job_id, job in _jobs.items()
+        if job["status"] != "running"
+        and job["ended_at"] is not None
+        and now - job["ended_at"] > MAX_JOB_AGE_SECONDS
+    ]
+    for job_id in stale:
+        del _jobs[job_id]
+
+
+def _run(job_id: str, label: str, fn: Callable[[], Any]) -> None:
+    try:
+        with long_resolve_op(label):
+            result = fn()
+    except Exception as exc:
+        with _lock:
+            job = _jobs.get(job_id)
+            if job is not None:
+                job["status"] = "error"
+                job["error"] = f"{type(exc).__name__}: {exc}"
+                job["ended_at"] = time.time()
+        return
+    with _lock:
+        job = _jobs.get(job_id)
+        if job is not None:
+            job["status"] = "done"
+            job["result"] = result
+            job["ended_at"] = time.time()
+
+
+def start_job(label: str, fn: Callable[[], Any]) -> str:
+    """Run fn on a daemon thread; return a short job id immediately."""
+    now = time.time()
+    with _lock:
+        _prune_locked(now)
+        job_id = uuid.uuid4().hex[:8]
+        while job_id in _jobs:
+            job_id = uuid.uuid4().hex[:8]
+        _jobs[job_id] = {
+            "id": job_id,
+            "label": str(label),
+            "status": "running",
+            "result": None,
+            "error": None,
+            "started_at": now,
+            "ended_at": None,
+        }
+    threading.Thread(
+        target=_run,
+        args=(job_id, str(label), fn),
+        name=f"bgjob-{job_id}",
+        daemon=True,
+    ).start()
+    return job_id
+
+
+def job_status(job_id: str) -> Optional[Dict[str, Any]]:
+    """Snapshot of one job, or None when the id is unknown."""
+    with _lock:
+        _prune_locked(time.time())
+        job = _jobs.get(job_id)
+        return dict(job) if job is not None else None
+
+
+def list_jobs() -> List[Dict[str, Any]]:
+    """Compact status of every known job."""
+    with _lock:
+        _prune_locked(time.time())
+        return [
+            {k: job[k] for k in ("id", "label", "status", "started_at", "ended_at")}
+            for job in _jobs.values()
+        ]

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,