davinci-resolve-mcp 2.49.0 → 2.51.0

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 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.51.0
+
+CLAP audio embeddings — the final phase of the post-program improvements.
+Detection-based like every other backend (never auto-installed); local
+compute, so nothing touches the caps ledger.
+
+- **Added** audio embedding backend detection: CLAP via `transformers`
+  (laion/clap-htsat-unfused, preferred) or the `laion_clap` package, plus
+  torch + ffmpeg. `capabilities` gains an `audio` block with install
+  guidance and a `clap_audio` Tools-page entry.
+- **Added** `build_embeddings(kinds=["audio"])`: one CLAP window per shot
+  (center-cropped to ~10 s, piped from the source media as raw PCM —
+  read-only on source media, no temp files) plus a clip-level mean vector,
+  stored as `embedding_kind="audio"` rows. Idempotent via content hashes;
+  offline media is reported in `skipped_missing_media`; a missing backend
+  is a graceful skip with install guidance.
+- **Added** `find_similar(kind="audio")`: shot/clip queries over the audio
+  vectors, and free-text queries ("engine revving") via the CLAP text
+  encoder.
+
+## What's New in v2.50.0
+
+The last JSON-fed readers now source from the DB-canonical analysis store
+(consistency/perf hygiene — the JSON export is lockstep with the DB, so this
+is shape-preserving by construction).
+
+- **Changed** `summarize_reports` aggregates from the DB (blob + human
+  overlay) when every report dir on disk is covered by an ingested clip row;
+  pre-v9 roots and MIXED roots (some clips not ingested) fall back WHOLESALE
+  to the JSON walk — a partial DB view would silently under-report. The
+  summary gains a `"source": "db"|"json"` key for observability; the F1
+  provenance map (source_reports / missing_reports) is unchanged.
+- **Changed** `build_analysis_index` sources local reports from the DB
+  instead of re-parsing every `analysis.json`; job-linked EXTERNAL report
+  paths (their rows live under another project's DB) and pre-v9 dirs keep
+  the JSON read. The FTS schema and the query surface are identical; the
+  result gains `report_sources` counts.
+- **Added** DB-vs-JSON parity tests (semantic equality with normalized
+  ordering) plus wholesale-fallback regressions for mixed and pre-v9 roots;
+  live-validated on the sample analysis root (summary, index counts, and
+  FTS query results identical on both paths).
+
 ## What's New in v2.49.0
 
 Cross-shot relationships (spec §4 — pattern recognition only): the shot

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.49.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.51.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-34%20(341%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md

@@ -547,15 +547,23 @@ no editorial suggestions): `same_setup_as` / `alt_take_of` (symmetric) and
 vendor tokens, so nothing here touches the caps ledger. Backends are
 detected, never installed (capabilities lists them with install guidance):
 text = ollama serving `nomic-embed-text` or sentence-transformers; visual =
-open_clip (ViT-B-32, needs torch).
-- `build_embeddings(kinds=["text","visual"]?, clip_id?)` — idempotent;
-  embeds clip summaries, shot descriptions (+ deep field groups), transcript
-  segments, and sampled frames (per-shot visual vector = mean of its
-  frames'). Only re-embeds entities whose content changed.
-- `find_similar(text=… | clip_id=… | clip_id+shot_index, kind="text"|"visual",
-  entity_types?, limit?)` — brute-force cosine over the project's vectors.
-  Free-text visual queries use the CLIP text encoder ("cracked windshield"
-  finds the frame). Results carry scores plus clip/shot/segment context.
+open_clip (ViT-B-32, needs torch); audio (v2.51.0+) = CLAP via
+`transformers` (laion/clap-htsat-unfused, preferred) or the `laion_clap`
+package — needs torch + ffmpeg.
+- `build_embeddings(kinds=["text","visual","audio"]?, clip_id?)` —
+  idempotent; embeds clip summaries, shot descriptions (+ deep field
+  groups), transcript segments, and sampled frames (per-shot visual vector
+  = mean of its frames'). `kinds=["audio"]` embeds one CLAP window per shot
+  (center-cropped to ~10s, piped from the source media as raw PCM —
+  read-only, no temp files) plus a clip-level mean vector; clips whose
+  media is offline are reported in `skipped_missing_media`. Only re-embeds
+  entities whose content changed.
+- `find_similar(text=… | clip_id=… | clip_id+shot_index,
+  kind="text"|"visual"|"audio", entity_types?, limit?)` — brute-force
+  cosine over the project's vectors. Free-text visual queries use the CLIP
+  text encoder ("cracked windshield" finds the frame); free-text audio
+  queries use the CLAP text encoder ("engine revving" finds the shot).
+  Results carry scores plus clip/shot/segment context.
 The panel search box gains a `Semantic` toggle when a text backend is
 detected. Vectors live in the per-project DB (schema v10).
 

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.49.0"
+VERSION = "2.51.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.49.0",
+  "version": "2.51.0",
   "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.49.0"
+VERSION = "2.51.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 341-tool granular server instead
 """
 
-VERSION = "2.49.0"
+VERSION = "2.51.0"
 
 import base64
 import os

package/src/utils/embeddings.py

@@ -1,12 +1,15 @@
 """Embeddings + similarity search (Phase C of the analysis program).
 
 Text vectors over clip/shot summaries and transcript segments, CLIP image
-vectors over sampled frames. Backends are detected, never installed (the
-whisper pattern):
+vectors over sampled frames, CLAP audio vectors over per-shot audio windows.
+Backends are detected, never installed (the whisper pattern):
 
 - text: ollama serving ``nomic-embed-text`` (preferred — works on Apple
   Silicon via Metal), or ``sentence_transformers`` when installed.
 - visual: ``open_clip_torch`` (ViT-B-32) when installed alongside torch.
+- audio: ``transformers`` ClapModel (laion/clap-htsat-unfused; preferred) or
+  ``laion_clap`` when installed alongside torch; needs ffmpeg. Audio windows
+  are piped from the source media as raw PCM — read-only, no temp files.
 
 Vectors live in the per-project DB (schema v10 ``embeddings`` table) as
 float32 BLOBs, one row per (entity, kind, model). Similarity is brute-force
@@ -37,12 +40,17 @@ OLLAMA_TEXT_MODEL = os.environ.get("DAVINCI_RESOLVE_MCP_EMBED_MODEL", "nomic-emb
 SENTENCE_TRANSFORMERS_MODEL = "all-MiniLM-L6-v2"
 OPEN_CLIP_MODEL = ("ViT-B-32", "laion2b_s34b_b79k")
 
+CLAP_HF_MODEL = "laion/clap-htsat-unfused"
+CLAP_SAMPLE_RATE = 48000
+AUDIO_WINDOW_SECONDS = 10.0  # CLAP works on ~10s windows; longer shots are center-cropped
+
 _PROBE_TIMEOUT_SECONDS = 2.0
 _EMBED_TIMEOUT_SECONDS = 120.0
 
 # Lazy singletons for heavyweight local models.
 _ST_MODEL = None
 _CLIP_STATE: Optional[Tuple[Any, Any, Any]] = None  # (model, preprocess, torch)
+_CLAP_STATE: Optional[Tuple[str, Any]] = None  # (backend, state)
 
 
 def _now() -> str:
@@ -140,6 +148,26 @@ def detect_embedding_capabilities() -> Dict[str, Any]:
             else "pip install torch open_clip_torch"
         )
 
+    transformers_available = importlib.util.find_spec("transformers") is not None
+    laion_clap_available = importlib.util.find_spec("laion_clap") is not None
+    ffmpeg_available = bool(shutil.which("ffmpeg"))
+    audio_backends: List[str] = []
+    if torch_available and ffmpeg_available:
+        if transformers_available:
+            audio_backends.append("transformers_clap")
+        if laion_clap_available:
+            audio_backends.append("laion_clap")
+    if not audio_backends:
+        if not ffmpeg_available:
+            guidance["audio"] = "Install ffmpeg (audio windows are extracted with it)."
+        else:
+            guidance["audio"] = (
+                "pip install transformers (CLAP via laion/clap-htsat-unfused), "
+                "or pip install laion_clap"
+                if torch_available
+                else "pip install torch transformers"
+            )
+
     return {
         "success": True,
         "no_auto_install": True,
@@ -156,6 +184,12 @@ def detect_embedding_capabilities() -> Dict[str, Any]:
             "backends": ["open_clip"] if visual_available else [],
             "model": "-".join(OPEN_CLIP_MODEL) if visual_available else None,
         },
+        "audio": {
+            "available": bool(audio_backends),
+            "backends": audio_backends,
+            "model": CLAP_HF_MODEL if audio_backends else None,
+            "ffmpeg": ffmpeg_available,
+        },
         "install_guidance": guidance,
     }
 
@@ -279,6 +313,148 @@ def embed_text_for_visual_query(text: str) -> Dict[str, Any]:
         return {"success": False, "error": f"{type(exc).__name__}: {exc}"}
 
 
+# ── audio (CLAP) ─────────────────────────────────────────────────────────────
+
+
+def _clap_state() -> Tuple[str, Any]:
+    """Lazy-load the preferred CLAP backend: transformers (HF-cached, kept
+    current) over the laion_clap package."""
+    global _CLAP_STATE
+    if _CLAP_STATE is None:
+        caps = detect_embedding_capabilities()["audio"]
+        backends = caps["backends"]
+        if "transformers_clap" in backends:
+            from transformers import ClapModel, ClapProcessor
+
+            model = ClapModel.from_pretrained(CLAP_HF_MODEL)
+            model.eval()
+            processor = ClapProcessor.from_pretrained(CLAP_HF_MODEL)
+            _CLAP_STATE = ("transformers_clap", (model, processor))
+        elif "laion_clap" in backends:
+            import laion_clap
+
+            module = laion_clap.CLAP_Module(enable_fusion=False)
+            module.load_ckpt()  # default pretrained checkpoint
+            _CLAP_STATE = ("laion_clap", module)
+        else:
+            raise RuntimeError("No audio-embedding backend available")
+    return _CLAP_STATE
+
+
+def _extract_audio_window(file_path: str, start_seconds: float, duration_seconds: float):
+    """Mono 48 kHz float32 samples piped straight from ffmpeg — read-only on
+    the source media, no temp files. Returns None when the window is empty
+    (e.g. video-only media)."""
+    import subprocess
+
+    import numpy as np
+
+    command = [
+        "ffmpeg", "-v", "error",
+        "-ss", f"{max(0.0, float(start_seconds)):.3f}",
+        "-t", f"{max(0.1, float(duration_seconds)):.3f}",
+        "-i", file_path,
+        "-vn", "-ac", "1", "-ar", str(CLAP_SAMPLE_RATE),
+        "-f", "f32le", "-",
+    ]
+    try:
+        proc = subprocess.run(command, capture_output=True, timeout=120, check=False)
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if proc.returncode != 0 or not proc.stdout:
+        return None
+    samples = np.frombuffer(proc.stdout, dtype=np.float32)
+    return samples if samples.size else None
+
+
+def _clap_audio_vectors(waveforms: List[Any]) -> Tuple[List[List[float]], str]:
+    backend, state = _clap_state()
+    if backend == "transformers_clap":
+        import torch
+
+        model, processor = state
+        inputs = processor(audios=waveforms, sampling_rate=CLAP_SAMPLE_RATE, return_tensors="pt", padding=True)
+        with torch.no_grad():
+            features = model.get_audio_features(**inputs)
+            features = features / features.norm(dim=-1, keepdim=True)
+        return [[float(x) for x in row.tolist()] for row in features], f"transformers_clap:{CLAP_HF_MODEL}"
+    import numpy as np
+
+    module = state
+    vectors = module.get_audio_embedding_from_data(x=np.stack(waveforms), use_tensor=False)
+    return [[float(x) for x in row] for row in vectors], "laion_clap:default"
+
+
+def embed_audio_windows(file_path: str, windows: List[Tuple[float, float]]) -> Dict[str, Any]:
+    """Embed (start_seconds, end_seconds) windows of one media file with CLAP.
+
+    Windows longer than AUDIO_WINDOW_SECONDS are center-cropped. Vector slots
+    are None for windows with no decodable audio.
+    """
+    caps = detect_embedding_capabilities()
+    if not caps["audio"]["available"]:
+        return {
+            "success": False,
+            "error": "No audio-embedding backend available",
+            "install_guidance": caps["install_guidance"].get("audio"),
+        }
+    if not os.path.isfile(file_path):
+        return {"success": False, "error": f"media not found: {file_path}"}
+    waveforms: List[Any] = []
+    slots: List[Optional[int]] = []
+    for start, end in windows:
+        duration = max(0.1, float(end) - float(start))
+        if duration > AUDIO_WINDOW_SECONDS:
+            start = float(start) + (duration - AUDIO_WINDOW_SECONDS) / 2.0
+            duration = AUDIO_WINDOW_SECONDS
+        samples = _extract_audio_window(file_path, float(start), duration)
+        if samples is None:
+            slots.append(None)
+            continue
+        slots.append(len(waveforms))
+        waveforms.append(samples)
+    if not waveforms:
+        return {"success": True, "vectors": [None] * len(windows), "model": None,
+                "note": "no decodable audio in any window"}
+    try:
+        vectors, model = _clap_audio_vectors(waveforms)
+    except Exception as exc:  # noqa: BLE001 — backend failures surface as data
+        return {"success": False, "error": f"{type(exc).__name__}: {exc}"}
+    return {
+        "success": True,
+        "vectors": [vectors[slot] if slot is not None else None for slot in slots],
+        "model": model,
+    }
+
+
+def embed_text_for_audio_query(text: str) -> Dict[str, Any]:
+    """CLAP text encoder — lets a free-text query ('engine revving') search
+    audio vectors."""
+    caps = detect_embedding_capabilities()
+    if not caps["audio"]["available"]:
+        return {
+            "success": False,
+            "error": "No audio-embedding backend available",
+            "install_guidance": caps["install_guidance"].get("audio"),
+        }
+    try:
+        backend, state = _clap_state()
+        if backend == "transformers_clap":
+            import torch
+
+            model, processor = state
+            inputs = processor(text=[str(text)], return_tensors="pt", padding=True)
+            with torch.no_grad():
+                features = model.get_text_features(**inputs)
+                features = features / features.norm(dim=-1, keepdim=True)
+            return {"success": True, "vector": [float(x) for x in features[0].tolist()],
+                    "model": f"transformers_clap:{CLAP_HF_MODEL}"}
+        vectors = state.get_text_embedding([str(text), ""], use_tensor=False)
+        return {"success": True, "vector": [float(x) for x in vectors[0]], "model": "laion_clap:default"}
+    except Exception as exc:  # noqa: BLE001
+        return {"success": False, "error": f"{type(exc).__name__}: {exc}"}
+
+
 # ── content builders ─────────────────────────────────────────────────────────
 
 
@@ -497,6 +673,78 @@ def build_embeddings(
         else:
             result["visual"] = {"success": True, "embedded": 0, "note": "all up to date"}
 
+    if "audio" in kinds:
+        caps = detect_embedding_capabilities()
+        if not caps["audio"]["available"]:
+            result["audio"] = {
+                "success": False,
+                "skipped": True,
+                "error": "No audio-embedding backend available",
+                "install_guidance": caps["install_guidance"].get("audio"),
+            }
+            result["success"] = False
+            return result
+        existing = _existing_rows(conn, "audio")
+        embedded_count = 0
+        missing_media: List[str] = []
+        audio_model: Optional[str] = None
+        for clip in conn.execute(f"SELECT * FROM clips{where}", args).fetchall():
+            clip = dict(clip)
+            file_path = str(clip.get("file_path") or "")
+            if not file_path or not os.path.isfile(file_path):
+                missing_media.append(str(clip.get("clip_name") or clip["clip_uuid"]))
+                continue
+            shots = [dict(s) for s in conn.execute(
+                "SELECT shot_uuid, time_seconds_start, time_seconds_end FROM shots "
+                "WHERE clip_uuid = ? ORDER BY shot_index",
+                (clip["clip_uuid"],),
+            ).fetchall()]
+            windows: List[Tuple[float, float]] = []
+            window_meta: List[Tuple[str, str, str]] = []
+            for shot in shots:
+                start, end = shot.get("time_seconds_start"), shot.get("time_seconds_end")
+                if start is None or end is None or float(end) - float(start) < 0.2:
+                    continue
+                h = _content_hash(f"{file_path}|{start}|{end}")
+                if existing.get(("shot", str(shot["shot_uuid"]))) == h:
+                    continue
+                windows.append((float(start), float(end)))
+                window_meta.append(("shot", str(shot["shot_uuid"]), h))
+            if not windows:
+                continue
+            embedded = embed_audio_windows(file_path, windows)
+            if not embedded.get("success"):
+                result["audio"] = embedded
+                result["success"] = False
+                return result
+            if not embedded.get("model"):
+                continue  # no decodable audio in this clip (e.g. video-only)
+            audio_model = str(embedded["model"])
+            items: List[Tuple[str, str, str, List[float]]] = []
+            clip_vectors: List[List[float]] = []
+            for m, vector in zip(window_meta, embedded["vectors"]):
+                if vector is None:
+                    continue
+                items.append((m[0], m[1], m[2], vector))
+                clip_vectors.append(vector)
+            # Clip-level audio vector = mean of its shot windows' (the
+            # per-shot-visual pattern).
+            if clip_vectors:
+                dim = len(clip_vectors[0])
+                mean = [sum(v[i] for v in clip_vectors) / len(clip_vectors) for i in range(dim)]
+                items.append((
+                    "clip", str(clip["clip_uuid"]),
+                    _content_hash(f"{file_path}|clip|{len(clip_vectors)}"), mean,
+                ))
+            embedded_count += _store_vectors(project_root, "audio", audio_model, items)
+        result["audio"] = {
+            "success": True,
+            "embedded": embedded_count,
+            "model": audio_model,
+            **({"skipped_missing_media": missing_media} if missing_media else {}),
+            **({"note": "all up to date"} if not embedded_count and not missing_media else {}),
+        }
+
     result["wall_clock_ms"] = int((time.time() - started) * 1000)
     counts = conn.execute(
         "SELECT embedding_kind, COUNT(*) AS n FROM embeddings GROUP BY embedding_kind"
@@ -569,8 +817,8 @@ def find_similar(
 
     conn = timeline_brain_db.connect(project_root)
     kind = (kind or "text").strip().lower()
-    if kind not in ("text", "visual"):
-        return {"success": False, "error": f"kind must be 'text' or 'visual', got {kind!r}"}
+    if kind not in ("text", "visual", "audio"):
+        return {"success": False, "error": f"kind must be 'text', 'visual', or 'audio', got {kind!r}"}
 
     exclude: Optional[Tuple[str, str]] = None
     query_vector: Optional[List[float]] = None
@@ -583,6 +831,12 @@ def find_similar(
                 return embedded
             query_vector = embedded["vectors"][0]
             query_model = str(embedded["model"])
+        elif kind == "audio":
+            encoded = embed_text_for_audio_query(str(text))
+            if not encoded.get("success"):
+                return encoded
+            query_vector = encoded["vector"]
+            query_model = str(encoded["model"])
         else:
             encoded = embed_text_for_visual_query(str(text))
             if not encoded.get("success"):

package/src/utils/media_analysis.py

@@ -1458,6 +1458,20 @@ TOOL_INSTALL: Dict[str, Dict[str, Any]] = {
         "verify": "python -c \"import open_clip\"",
         "notes": "Needs torch. Model weights (~350 MB) download on first use.",
     },
+    "clap_audio": {
+        "label": "CLAP (audio embeddings)",
+        "bundle": "embeddings",
+        "required_for": ["audio similarity (find_similar kind=audio)"],
+        "commands": {
+            "all": "pip install transformers",
+        },
+        "verify": "python -c \"import transformers\"",
+        "notes": (
+            "Needs torch + ffmpeg. Uses laion/clap-htsat-unfused (~600 MB, "
+            "downloads on first use); the laion_clap package works as an "
+            "alternative backend."
+        ),
+    },
     "whisper_cpp": {
         "label": "whisper.cpp",
         "bundle": "transcription",
@@ -1650,6 +1664,11 @@ def detect_capabilities(env: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
                 bool(embedding_caps.get("visual", {}).get("available")),
                 {"python_module": "open_clip"},
             ),
+            "clap_audio": _tool_entry(
+                "clap_audio",
+                bool(embedding_caps.get("audio", {}).get("available")),
+                {"backends": embedding_caps.get("audio", {}).get("backends", [])},
+            ),
         },
         "embeddings": embedding_caps,
         "transcription": {
@@ -5994,20 +6013,68 @@ def load_report(project_root: str, report_path: Optional[str] = None, clip_dir:
     return {"success": True, "path": path, "report": payload}
 
 
-def summarize_reports(project_root: str) -> Dict[str, Any]:
-    root = normalize_path(project_root)
+def _collect_reports_for_summary(root: str) -> Tuple[List[Dict[str, Any]], List[str], str]:
+    """(reports, report_paths, source) for summarize_reports.
+
+    DB-first: when every report dir on disk is covered by an ingested clip
+    row, reports come from the DB-canonical store (blob + human overlay —
+    identical content to the lockstep JSON export). Pre-v9 roots and MIXED
+    roots (some clips not ingested) fall back WHOLESALE to the JSON walk —
+    a partial DB view would silently under-report.
+    """
     clips_root = os.path.join(root, "clips")
-    reports: List[Dict[str, Any]] = []
-    report_paths: List[str] = []
+    disk_paths: List[str] = []
     if os.path.isdir(clips_root):
         for dirpath, _, filenames in os.walk(clips_root):
             if "analysis.json" in filenames:
-                report_path = os.path.join(dirpath, "analysis.json")
+                disk_paths.append(os.path.join(dirpath, "analysis.json"))
+    disk_paths.sort()
+
+    try:
+        from src.utils import analysis_store, timeline_brain_db
+
+        conn = timeline_brain_db.connect(root)
+        db_dirs = {
+            str(r["clip_dir"]): str(r["clip_uuid"])
+            for r in conn.execute(
+                "SELECT clip_dir, clip_uuid FROM clips WHERE clip_dir IS NOT NULL"
+            ).fetchall()
+        }
+    except Exception:  # noqa: BLE001 — no DB (pre-v9) → JSON
+        db_dirs = {}
+    if disk_paths and db_dirs:
+        dir_names = [os.path.basename(os.path.dirname(p)) for p in disk_paths]
+        if all(name in db_dirs for name in dir_names):
+            from src.utils import analysis_store
+
+            reports: List[Dict[str, Any]] = []
+            complete = True
+            for path, name in zip(disk_paths, dir_names):
                 try:
-                    reports.append(_read_json(report_path))
-                    report_paths.append(report_path)
-                except (OSError, json.JSONDecodeError):
-                    continue
+                    report = analysis_store.export_report(root, db_dirs[name])
+                except Exception:  # noqa: BLE001
+                    report = None
+                if not isinstance(report, dict):
+                    complete = False
+                    break
+                reports.append(report)
+            if complete:
+                return reports, disk_paths, "db"
+
+    reports = []
+    report_paths: List[str] = []
+    for path in disk_paths:
+        try:
+            reports.append(_read_json(path))
+            report_paths.append(path)
+        except (OSError, json.JSONDecodeError):
+            continue
+    return reports, report_paths, "json"
+
+
+def summarize_reports(project_root: str) -> Dict[str, Any]:
+    root = normalize_path(project_root)
+    reports, report_paths, reports_source = _collect_reports_for_summary(root)
     warnings = []
     motion_counts: Dict[str, int] = {}
     tags: Dict[str, int] = {}
@@ -6047,6 +6114,7 @@ def summarize_reports(project_root: str) -> Dict[str, Any]:
     summary = {
         "success": True,
         "project_root": root,
+        "source": reports_source,  # "db" (canonical store) | "json" (walk fallback)
         "clip_reports": len(reports),
         "motion_distribution": motion_counts,
         "technical_warning_count": len(warnings),
@@ -7202,9 +7270,42 @@ def build_analysis_index(project_root: str, *, index_path: Optional[Any] = None)
         conn.execute("INSERT INTO index_metadata (key, value) VALUES (?, ?)", ("fts_enabled", "1" if fts_enabled else "0"))
         conn.execute("INSERT INTO index_metadata (key, value) VALUES (?, ?)", ("image_blob_policy", "excluded"))
 
+        # DB-first sourcing: local reports whose clip dir is ingested come from
+        # the DB-canonical store (blob + human overlay — identical content to
+        # the lockstep JSON export) instead of re-parsing every analysis.json.
+        # Pre-v9 dirs and job-linked EXTERNAL report paths (their rows live
+        # under another project's DB) keep the JSON read. The index schema and
+        # the query surface are unchanged either way.
+        clips_root_prefix = os.path.realpath(os.path.join(root, "clips")) + os.sep
+        try:
+            from src.utils import timeline_brain_db as _brain_db
+
+            _db_dirs = {
+                str(r["clip_dir"]): str(r["clip_uuid"])
+                for r in _brain_db.connect(root).execute(
+                    "SELECT clip_dir, clip_uuid FROM clips WHERE clip_dir IS NOT NULL"
+                ).fetchall()
+            }
+        except Exception:  # noqa: BLE001 — no DB (pre-v9) → JSON for everything
+            _db_dirs = {}
+        report_sources = {"db": 0, "json": 0}
         for report_path in sorted(_iter_analysis_report_files(root)):
             try:
-                report = _read_json(report_path)
+                report = None
+                if _db_dirs and os.path.realpath(report_path).startswith(clips_root_prefix):
+                    clip_uuid = _db_dirs.get(os.path.basename(os.path.dirname(report_path)))
+                    if clip_uuid:
+                        try:
+                            from src.utils import analysis_store as _analysis_store
+
+                            report = _analysis_store.export_report(root, clip_uuid)
+                        except Exception:  # noqa: BLE001 — fall back per-report
+                            report = None
+                if isinstance(report, dict):
+                    report_sources["db"] += 1
+                else:
+                    report = _read_json(report_path)
+                    report_sources["json"] += 1
                 row_counts = _insert_analysis_report_into_index(conn, report_path, report, fts_enabled=fts_enabled)
                 counts["clips"] += 1
                 for key, value in row_counts.items():
@@ -7244,6 +7345,7 @@ def build_analysis_index(project_root: str, *, index_path: Optional[Any] = None)
         "image_blob_policy": "excluded",
         "fts_enabled": bool(counts["clips"]) and _sqlite_table_exists(db_path, "clips_fts"),
         "counts": counts,
+        "report_sources": report_sources,  # how many reports came from the DB vs JSON
         "failed_report_count": len(failed_reports),
         "failed_reports": failed_reports[:50],
         "size_bytes": os.path.getsize(db_path) if os.path.isfile(db_path) else 0,