davinci-resolve-mcp 2.50.0 → 2.52.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 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.52.0
+
+`edit_engine` tighten now carries audio. Previously `execute_tighten`
+assembled a video-only variant — a speech-driven dead-air cut came out
+silent, with nothing in the preview or readback to warn you (issue #67).
+
+- **Fixed** `plan_tighten` mirrors every kept video range onto its linked
+  audio track(s) with identical source frames, so the assembled variant
+  stays frame-locked and audible. Audio targets the item's detected linked
+  audio tracks (same `GetLinkedItems` matching `execute_swap` uses), falling
+  back to audio track 1 where a single linked A/V clip's audio lives.
+- **Added** `include_audio` parameter to `plan_tighten` (default `true`).
+  Pass `include_audio=false` for the prior video-only assembly.
+- **Added** an `audio_accounting` block to the `execute_tighten` confirm
+  preview and readback (planned vs. actual audio/video item counts), so a
+  silent variant can no longer ship unnoticed. Old video-only plans
+  re-executed against this build still work and are now loudly flagged as
+  silent.
+
+## 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

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.50.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.52.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).
 
@@ -714,11 +722,15 @@ clip-count readback plus `brain_edits` rationale rows.
   `execute_selects(plan_id)` creates a NEW selects timeline from the plan's
   per-shot source ranges — additive; nothing existing is touched.
 - `plan_tighten(timeline_name?, target_ratio?, min_pause_seconds?,
-  handle_seconds?)` — dead-air lifts from transcript-gap evidence for each
-  timeline item (items without transcripts are reported in `skipped`, never
-  silently trimmed). `execute_tighten(plan_id)` assembles a tightened
-  VARIANT timeline from the plan's keep ranges — true partial trims; the
-  original timeline is never mutated.
+  handle_seconds?, include_audio?)` — dead-air lifts from transcript-gap
+  evidence for each timeline item (items without transcripts are reported in
+  `skipped`, never silently trimmed). `execute_tighten(plan_id)` assembles a
+  tightened VARIANT timeline from the plan's keep ranges — true partial
+  trims; the original timeline is never mutated. v2.52.0+: kept ranges mirror
+  onto each item's linked audio track(s) so the variant is audible (a
+  speech-driven cut was previously silent — #67); pass
+  `include_audio=false` for a video-only assembly, and the
+  `execute_tighten` readback carries an `audio_accounting` block.
 - `plan_swap(timeline_start_frame | item_name, kind="visual"|"text",
   limit?)` — alternates for one timeline item via the similarity index,
   filtered to shots long enough to fill the slot exactly.

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.50.0"
+VERSION = "2.52.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.50.0",
+  "version": "2.52.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.50.0"
+VERSION = "2.52.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.50.0"
+VERSION = "2.52.0"
 
 import base64
 import os
@@ -16592,6 +16592,15 @@ def _edit_engine_collect_items(tl, *, track_index: Optional[int] = None) -> List
                         pass
             except Exception:
                 pass
+            # Linked audio track indices so the planner can mirror kept ranges
+            # onto sound (see #67 — tighten variants were coming out silent).
+            try:
+                audio_indices, _audio_note = _edit_engine_linked_audio_tracks(
+                    tl, item, row["timeline_start_frame"], row["timeline_end_frame"]
+                )
+                row["audio_track_indices"] = audio_indices
+            except Exception:
+                row["audio_track_indices"] = []
             rows.append(row)
     return rows
 
@@ -16732,10 +16741,13 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
     - execute_selects(plan_id, confirm_token?) — creates a NEW selects timeline
       from the plan's clip in/out ranges. Nothing existing is touched.
     - plan_tighten(timeline_name?, target_ratio?, min_pause_seconds?,
-      handle_seconds?) — dead-air lifts from transcript-gap evidence for the
-      current (or named) timeline.
-    - execute_tighten(plan_id, confirm_token?) — duplicates the timeline and
-      applies the lifts (ripple) to the DUPLICATE, never the original.
+      handle_seconds?, include_audio?) — dead-air lifts from transcript-gap
+      evidence for the current (or named) timeline. Kept ranges mirror onto the
+      items' linked audio tracks by default so the variant is audible; pass
+      include_audio=false for a video-only (silent) assembly.
+    - execute_tighten(plan_id, confirm_token?) — assembles a tightened VARIANT
+      timeline from the plan's keep ranges (video + mirrored audio), never
+      mutating the original. Readback includes an audio_accounting block.
     - plan_swap(track_index?, timeline_start_frame | item_name, kind?, limit?)
       — alternates for one timeline item via the similarity index.
     - execute_swap(plan_id, alternate_index, confirm_token?) — replaces the
@@ -16807,6 +16819,7 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             target_ratio=p.get("target_ratio") or p.get("targetRatio"),
             min_pause_seconds=float(p.get("min_pause_seconds") or p.get("minPauseSeconds") or _edit_engine_mod.DEFAULT_MIN_PAUSE_SECONDS),
             handle_seconds=float(p.get("handle_seconds") or p.get("handleSeconds") or _edit_engine_mod.DEFAULT_HANDLE_SECONDS),
+            include_audio=str(p.get("include_audio", p.get("includeAudio", True))).strip().lower() not in {"false", "0", "no", "none", "off"},
         )
 
     if action == "plan_swap":
@@ -16951,6 +16964,8 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         keep_ranges = plan.get("keep_ranges") or []
         if not keep_ranges:
             return _err("plan has no keep_ranges — re-plan with this version")
+        audio_keep_ranges = sum(1 for r in keep_ranges if str(r.get("track_type", "video")).lower() == "audio")
+        video_keep_ranges = len(keep_ranges) - audio_keep_ranges
         if "confirm_token" not in p and "confirmToken" not in p and _confirm_token_required():
             return _issue_confirm_token(
                 action="edit_engine.execute_tighten", params=p,
@@ -16963,6 +16978,13 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                     "timeline_name": plan.get("timeline_name"),
                     "lift_count": len(lifts),
                     "keep_range_count": len(keep_ranges),
+                    "video_keep_range_count": video_keep_ranges,
+                    "audio_keep_range_count": audio_keep_ranges,
+                    "audio_note": (
+                        f"Variant carries audio ({audio_keep_ranges} audio ranges mirror the video cuts)."
+                        if audio_keep_ranges
+                        else "WARNING: variant is VIDEO-ONLY (silent) — plan has no audio ranges."
+                    ),
                     "estimated_removed_seconds": sum(l.get("duration_seconds") or 0 for l in lifts),
                 },
             )
@@ -17039,6 +17061,23 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                     else None
                 ),
                 "structural_diff": structural_diff,
+                "audio_accounting": {
+                    "planned_audio_ranges": audio_keep_ranges,
+                    "planned_video_ranges": video_keep_ranges,
+                    "variant_audio_items": sum(
+                        1 for it in (variant.get("items") or [])
+                        if (it.get("range") or {}).get("media_type") == 2
+                    ),
+                    "variant_video_items": sum(
+                        1 for it in (variant.get("items") or [])
+                        if (it.get("range") or {}).get("media_type") == 1
+                    ),
+                    "note": (
+                        "Variant carries audio mirrored from the video cuts."
+                        if audio_keep_ranges
+                        else "Variant is VIDEO-ONLY (silent) — re-plan with include_audio=True for sound."
+                    ),
+                },
             },
             "plan_id": plan.get("plan_id"),
         }

package/src/utils/edit_engine.py

@@ -348,13 +348,23 @@ def plan_tighten(
     target_ratio: Optional[float] = None,
     min_pause_seconds: float = DEFAULT_MIN_PAUSE_SECONDS,
     handle_seconds: float = DEFAULT_HANDLE_SECONDS,
+    include_audio: bool = True,
 ) -> Dict[str, Any]:
     """Propose dead-air lifts for a timeline.
 
     `items` rows come from the server (Resolve read): each needs
     {timeline_start_frame, timeline_end_frame, source_start_frame,
-     media_ref (clip id / path / hash), item_name?}. Lifts are returned in
-    timeline frames, latest-first ready.
+     media_ref (clip id / path / hash), item_name?}. Optionally each row may
+    carry {audio_track_indices: [int, ...]} naming the audio tracks that hold
+    the item's linked audio. Lifts are returned in timeline frames, latest-first
+    ready.
+
+    When ``include_audio`` (the default), each kept video range is mirrored onto
+    matching audio range(s) so the assembled variant carries sound — a
+    speech-driven cut would otherwise come out silent (see #67). Audio is
+    mirrored to the item's detected ``audio_track_indices``; absent that, it
+    falls back to audio track 1, which is where a single linked A/V clip's audio
+    lives.
     """
     if not items:
         return {"success": False, "error": "No timeline items supplied"}
@@ -475,6 +485,11 @@ def plan_tighten(
             cursor = max(cursor, lift_end_sec)
         if spec["src_end_sec"] - cursor > 0.05:
             segments.append((cursor, spec["src_end_sec"]))
+        audio_indices: List[int] = []
+        if include_audio:
+            audio_indices = [int(i) for i in (item.get("audio_track_indices") or []) if int(i) > 0]
+            if not audio_indices:
+                audio_indices = [1]
         for seg_start, seg_end in segments:
             start_frame = int(round(seg_start * clip_fps))
             end_frame = max(start_frame + 1, int(round(seg_end * clip_fps)) - 1)
@@ -485,23 +500,40 @@ def plan_tighten(
                 "track_type": "video",
                 "track_index": int(item.get("track_index") or 1),
             })
+            # Mirror each kept video range onto its linked audio track(s) with
+            # identical source frames so the variant stays frame-locked and
+            # audible. mediaType 2 pulls the same media-pool item's audio.
+            for audio_index in audio_indices:
+                keep_ranges.append({
+                    "clip_id": spec["resolve_clip_id"],
+                    "start_frame": start_frame,
+                    "end_frame": end_frame,
+                    "track_type": "audio",
+                    "media_type": 2,
+                    "track_index": audio_index,
+                })
 
     removed_frames = sum(l["timeline_end_frame"] - l["timeline_start_frame"] for l in lifts)
+    audio_keep_range_count = sum(1 for r in keep_ranges if r.get("track_type") == "audio")
+    video_keep_range_count = len(keep_ranges) - audio_keep_range_count
     plan = save_plan(project_root, {
         "kind": "tighten",
         "timeline_name": timeline_name,
         "timeline_fps": fps,
         "lifts": lifts,
         "keep_ranges": keep_ranges,
+        "include_audio": bool(include_audio),
         "skipped": skipped,
         "summary": (
             f"{len(lifts)} dead-air lifts, ~{round(removed_frames / fps, 1)}s removed "
-            f"from '{timeline_name}' (assembled as a tightened variant)"
+            f"from '{timeline_name}' (assembled as a tightened variant"
+            f"{', video + audio' if include_audio else ', video only'})"
         ),
         "settings": {
             "target_ratio": target_ratio,
             "min_pause_seconds": min_pause_seconds,
             "handle_seconds": handle_seconds,
+            "include_audio": bool(include_audio),
         },
     })
     return {
@@ -514,11 +546,20 @@ def plan_tighten(
         "estimated_removed_seconds": round(removed_frames / fps, 2),
         "lifts": lifts,
         "keep_range_count": len(keep_ranges),
+        "video_keep_range_count": video_keep_range_count,
+        "audio_keep_range_count": audio_keep_range_count,
+        "include_audio": bool(include_audio),
         "skipped": skipped,
         "note": (
             "Dry-run plan. Execute with edit_engine(action='execute_tighten', "
             "params={plan_id}) — a tightened VARIANT timeline is assembled from "
-            "the keep ranges; the original timeline is never mutated."
+            "the keep ranges; the original timeline is never mutated. "
+            + (
+                f"Audio is mirrored onto matching tracks ({audio_keep_range_count} "
+                "audio ranges) so the variant is audible."
+                if include_audio
+                else "include_audio=False: the variant will be VIDEO-ONLY (silent)."
+            )
         ),
     }
 

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": {