davinci-resolve-mcp 2.62.2 → 2.63.0

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 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.63.0
+
+Waveform silence ripple for the edit engine (PR #91, by @EliteSystemsAI),
+adopted with follow-up hardening and live-validated in Resolve Studio.
+
+### Added
+
+- **`plan_silence_ripple` / `execute_silence_ripple`** — waveform-driven dead-air
+  removal that mirrors Resolve's *Ripple Delete Silence* dialog (ffmpeg
+  `silencedetect` → keep-range variant assembly). Tunable `threshold_db`,
+  `min_strip_frames`, `pre_head_frames`, and `post_tail_frames`. Original
+  timeline is never mutated; execution is confirm-gated like `execute_tighten`.
+  New module: `src/utils/silence_ripple.py`; tests in
+  `tests/test_silence_ripple.py` and `tests/test_edit_engine.py`.
+
+### Fixed (hardening on the PR before release)
+
+- **Skipped items ride along whole** — timeline items without a readable media
+  file path now emit a full-range keep (video + mirrored audio) so the
+  assembled variant never silently loses content; only items with no media
+  reference at all are omitted, and the `skipped` reason says so explicitly.
+- **All audio streams are merged before detection** — production MXF often
+  carries one mono PCM stream per channel, and ffmpeg's default stream
+  selection could land on a dead scratch channel, reading entire takes as
+  silence. Detection now merges every audio stream (silence only when ALL
+  channels are silent — Resolve's dialog semantics), with a single-stream
+  fallback if `amerge` refuses the graph. Found by live validation on 5-stream
+  interview masters.
+- **No pointless video decode** — silence detection runs with `-vn`, so 4K
+  ProRes sources no longer decode picture just to scan audio.
+- **Clear failure modes** — a missing ffmpeg binary now reports itself instead
+  of "no silence regions found", and a plan whose keep ranges are empty
+  (source quieter than `threshold_db` throughout) carries an explicit warning
+  and is refused at execution.
+
+## What's New in v2.62.3
+
+A single grading fix (PR #90, by @Mldphotohraphie), extended and hardened. No
+new tool surface.
+
+### Fixed
+
+- **`graph set_lut` now applies LUTs/DCTLs installed by the `dctl` tool** —
+  the `dctl` tool installs into Resolve's per-user LUT directory, but
+  `Graph.SetLUT()` resolves LUT paths (relative names *and* absolute paths)
+  only against the master (system) LUT directory. A freshly installed LUT could
+  therefore never be applied, and `set_lut` always returned
+  `{"success": false}`. Verified live on Resolve Studio 19.1.3.7: `SetLUT` fails
+  for a user-dir LUT even after `RefreshLUTList()` and even via an absolute
+  user-dir path, so relocation into the master dir is genuinely required. (The
+  originating report, PR #90, observed the same on Studio 21.0.2.) On a `SetLUT`
+  failure the server now locates the LUT, stages it under a namespaced
+  `MCP/` subfolder of the master LUT dir (avoiding basename collisions with
+  stock/vendor LUTs), calls `RefreshLUTList()`, and retries. No behavior change
+  when `SetLUT` already succeeds. Applied to both `graph set_lut` (`src/server.py`)
+  and the granular `graph_set_lut` (`src/granular/graph.py`) via a shared
+  `src/utils/lut_paths.py` helper, with offline coverage in
+  `tests/test_lut_paths.py`.
+
 ## What's New in v2.62.2
 
 A single cross-platform launcher fix. No new tool surface; default behavior is

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.62.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.63.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

@@ -820,6 +820,15 @@ clip-count readback plus `brain_edits` rationale rows.
   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_silence_ripple(timeline_name?, track_index?, threshold_db?,
+  min_strip_frames?, pre_head_frames?, post_tail_frames?, include_audio?)` —
+  waveform silence strips via ffmpeg `silencedetect`, mirroring Resolve's
+  *Clip → Audio Operations → Ripple Delete Silence* (defaults: −30 dB,
+  10-frame minimum strip, 0 pre-head, 1 post-tail frame). Items without
+  readable file paths ride along whole (reported in `skipped`), so the
+  variant never silently loses content. `execute_silence_ripple(plan_id)`
+  assembles a tightened VARIANT timeline from keep ranges — same safety model
+  as `execute_tighten` (original untouched, confirm token, audio mirroring).
 - `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.62.2"
+VERSION = "2.63.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.62.2",
+  "version": "2.63.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.62.2"
+VERSION = "2.63.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/granular/graph.py

@@ -1,6 +1,7 @@
 """Color page graph, LUT, and color-group tools."""
 
 from src.granular.common import *  # noqa: F401,F403
+from src.utils.lut_paths import ensure_lut_in_master
 
 resolve = ResolveProxy()
 
@@ -39,8 +40,25 @@ def graph_set_lut(node_index: int, lut_path: str, item_index: int = 0, track_typ
     graph = item.GetNodeGraph()
     if not graph:
         return {"error": "No node graph available"}
-    result = graph.SetLUT(node_index, lut_path)
-    return {"success": bool(result)}
+    ok = bool(graph.SetLUT(node_index, lut_path))
+    if not ok:
+        # SetLUT resolves LUTs only against the master LUT dir, not the per-user
+        # dir dctl installs to. Relocate into the master dir and retry.
+        relocated = ensure_lut_in_master(lut_path)
+        if relocated:
+            try:
+                project = resolve.GetProjectManager().GetCurrentProject()
+                if project:
+                    project.RefreshLUTList()
+            except Exception:
+                pass
+            ok = bool(graph.SetLUT(node_index, relocated))
+            if ok:
+                return {"success": True, "resolved_lut": relocated,
+                        "note": "LUT staged under the master LUT dir "
+                                "(MCP/ subfolder) and applied; SetLUT does "
+                                "not resolve the user LUT dir."}
+    return {"success": ok}
 
 
 @mcp.tool()

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.62.2"
+VERSION = "2.63.0"
 
 import base64
 import os
@@ -97,6 +97,7 @@ from src.utils.media_analysis_jobs import (
     run_batch_job_slice as run_media_analysis_batch_job_slice,
 )
 from src.utils.platform import get_resolve_paths, get_resolve_plugin_paths
+from src.utils.lut_paths import master_lut_dir, ensure_lut_in_master
 from src.utils import fuse_templates, dctl_templates, script_templates
 from src.utils.timeline_title_text import (
     candidate_title_property_keys as _candidate_title_property_keys,
@@ -1044,6 +1045,7 @@ _TOKEN_GATED_DESTRUCTIVE_ACTIONS = frozenset({
     # Phase E edit-engine loops: plan → confirm → execute.
     ("edit_engine", "execute_selects"),
     ("edit_engine", "execute_tighten"),
+    ("edit_engine", "execute_silence_ripple"),
     ("edit_engine", "execute_swap"),
     ("graph", "apply_grade_from_drx"),
     ("graph", "reset_all_grades"),
@@ -18419,6 +18421,13 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
       block and a compact structural_diff (counts + a small sample); the full
       per-item diff is persisted in the plan record (get_plan → execution_summary)
       and returned inline only when include_details=true.
+    - plan_silence_ripple(timeline_name?, track_index?, threshold_db?,
+      min_strip_frames?, pre_head_frames?, post_tail_frames?, include_audio?)
+      — waveform silence strips via ffmpeg silencedetect (Resolve's Ripple Delete
+      Silence parity). Items without readable file paths ride along whole
+      (reported in skipped).
+    - execute_silence_ripple(plan_id, confirm_token?, include_details?) —
+      same variant assembly as execute_tighten; original timeline untouched.
     - 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
@@ -18493,6 +18502,26 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             include_audio=str(p.get("include_audio", p.get("includeAudio", True))).strip().lower() not in {"false", "0", "no", "none", "off"},
         )
 
+    if action == "plan_silence_ripple":
+        _r, proj, project_root, err = _project_context(need_resolve=True)
+        if err:
+            return err
+        tl = (_find_timeline_by_name(proj, p.get("timeline_name") or p.get("timelineName"))[0] if (p.get("timeline_name") or p.get("timelineName")) else proj.GetCurrentTimeline())
+        if not tl:
+            return _err("Timeline not found")
+        items = _edit_engine_collect_items(tl, track_index=p.get("track_index") or p.get("trackIndex"))
+        return _edit_engine_mod.plan_silence_ripple(
+            project_root,
+            items=items,
+            timeline_name=tl.GetName(),
+            timeline_fps=_edit_engine_timeline_fps(tl),
+            threshold_db=float(p.get("threshold_db") if p.get("threshold_db") is not None else p.get("thresholdDb") if p.get("thresholdDb") is not None else _edit_engine_mod.DEFAULT_SILENCE_THRESHOLD_DB),
+            min_strip_frames=float(p.get("min_strip_frames") if p.get("min_strip_frames") is not None else p.get("minStripFrames") if p.get("minStripFrames") is not None else _edit_engine_mod.DEFAULT_SILENCE_MIN_STRIP_FRAMES),
+            pre_head_frames=float(p.get("pre_head_frames") if p.get("pre_head_frames") is not None else p.get("preHeadFrames") if p.get("preHeadFrames") is not None else _edit_engine_mod.DEFAULT_SILENCE_PRE_HEAD_FRAMES),
+            post_tail_frames=float(p.get("post_tail_frames") if p.get("post_tail_frames") is not None else p.get("postTailFrames") if p.get("postTailFrames") is not None else _edit_engine_mod.DEFAULT_SILENCE_POST_TAIL_FRAMES),
+            include_audio=str(p.get("include_audio", p.get("includeAudio", True))).strip().lower() not in {"false", "0", "no", "none", "off"},
+        )
+
     if action == "plan_swap":
         _r, proj, project_root, err = _project_context(need_resolve=True)
         if err:
@@ -18768,6 +18797,141 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             "plan_id": plan.get("plan_id"),
         }
 
+    if action == "execute_silence_ripple":
+        _r, proj, project_root, err = _project_context(need_resolve=True)
+        if err:
+            return err
+        plan = _edit_engine_mod.load_plan(project_root, str(p.get("plan_id") or p.get("planId") or ""))
+        if not plan or plan.get("_corrupt"):
+            return _err("plan not found (or failed its fingerprint check) — re-plan")
+        if plan.get("kind") != "silence_ripple":
+            return _err(f"plan {plan.get('plan_id')} is a {plan.get('kind')} plan")
+        lifts = plan.get("lifts") or []
+        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
+        settings = plan.get("settings") or {}
+        if "confirm_token" not in p and "confirmToken" not in p and _confirm_token_required():
+            return _issue_confirm_token(
+                action="edit_engine.execute_silence_ripple", params=p,
+                preview={
+                    "operation": "edit_engine.execute_silence_ripple",
+                    "warning": (
+                        "Assembles a silence-ripple VARIANT timeline from waveform "
+                        "keep ranges; the original timeline is not modified."
+                    ),
+                    "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,
+                    "settings": settings,
+                    "estimated_removed_seconds": sum(l.get("duration_seconds") or 0 for l in lifts),
+                },
+            )
+        blocked = _consume_confirm_token(action="edit_engine.execute_silence_ripple", params=p)
+        if blocked:
+            return blocked
+        source_tl, _src_index = _find_timeline_by_name(proj, plan.get("timeline_name"))
+        if not source_tl:
+            return _err(f"Timeline '{plan.get('timeline_name')}' not found")
+        before = _edit_engine_capture(source_tl)
+        variant_name = f"{plan.get('timeline_name')} — silence ripple {time.strftime('%H%M%S')}"
+        variant = _timeline_create_variant_from_ranges(proj, source_tl, {
+            "ranges": keep_ranges,
+            "name": variant_name,
+        })
+        if not variant.get("success"):
+            return {"success": False, "error": f"variant assembly failed: {variant.get('error')}", "variant": variant}
+        new_tl, _new_index = _find_timeline_by_name(proj, variant.get("name") or variant_name)
+        after = _edit_engine_capture(new_tl) if new_tl else {}
+        structural_diff = None
+        if new_tl is not None:
+            try:
+                structural_diff = _timeline_versioning.compare_usage_snapshots(
+                    _timeline_versioning.capture_timeline_clip_usage(source_tl),
+                    _timeline_versioning.capture_timeline_clip_usage(new_tl),
+                )
+            except Exception as diff_exc:
+                structural_diff = {"error": f"{type(diff_exc).__name__}: {diff_exc}"}
+        run_id = _analysis_runs.current_run_id()
+        try:
+            _brain_edits.log_brain_edit(
+                project_root=project_root,
+                analysis_run_id=run_id or "edit-engine",
+                edit_type="edit_engine.silence_ripple_result",
+                tool_name="edit_engine",
+                action_name="execute_silence_ripple",
+                timeline_before=plan.get("timeline_name"),
+                timeline_after=variant.get("name") or variant_name,
+                target_metric=_brain_edits.METRIC_DURATION_SECONDS,
+                metric_direction="decrease",
+                before_value=before.get("duration_seconds"),
+                after_value=after.get("duration_seconds"),
+                rationale=plan.get("summary"),
+                params={"plan_id": plan.get("plan_id"), "settings": settings},
+                result_summary={"keep_ranges": len(keep_ranges), "lifts": len(lifts)},
+            )
+        except Exception:
+            pass
+        include_details = _media_analysis_bool(
+            p.get("include_details", p.get("includeDetails")), False
+        )
+        _edit_engine_mod.mark_plan_executed(project_root, plan["plan_id"], {
+            "variant_timeline": variant.get("name") or variant_name,
+            "keep_ranges": len(keep_ranges),
+            "lifts": len(lifts),
+            "before": before,
+            "after": after,
+            "structural_diff": structural_diff,
+            "settings": settings,
+        })
+        return {
+            "success": True,
+            "original_timeline": plan.get("timeline_name"),
+            "variant_timeline": variant.get("name") or variant_name,
+            "lifts_applied": len(lifts),
+            "keep_ranges": len(keep_ranges),
+            "settings": settings,
+            "lift_rationales": [
+                {"lift": [l["timeline_start_frame"], l["timeline_end_frame"]], "rationale": l.get("rationale")}
+                for l in lifts
+            ],
+            "readback": {
+                "before": before,
+                "after": after,
+                "removed_seconds": (
+                    round(before["duration_seconds"] - after["duration_seconds"], 2)
+                    if before.get("duration_seconds") is not None and after.get("duration_seconds") is not None
+                    else None
+                ),
+                "structural_diff": (
+                    structural_diff if include_details
+                    else _compact_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"),
+        }
+
     if action == "execute_swap":
         _r, proj, project_root, err = _project_context(need_resolve=True)
         if err:
@@ -18929,6 +19093,8 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         "execute_selects",
         "plan_tighten",
         "execute_tighten",
+        "plan_silence_ripple",
+        "execute_silence_ripple",
         "plan_swap",
         "execute_swap",
         "list_plans",
@@ -22070,7 +22236,27 @@ def graph(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
     elif action == "get_lut":
         return {"lut": g.GetLUT(p["node_index"])}
     elif action == "set_lut":
-        return {"success": bool(g.SetLUT(p["node_index"], p["lut_path"]))}
+        node_index = p["node_index"]
+        lut_path = p["lut_path"]
+        ok = bool(g.SetLUT(node_index, lut_path))
+        if not ok:
+            # Resolve resolves LUTs for SetLUT only against the master LUT dir,
+            # not the per-user dir that dctl install writes to. Relocate and retry.
+            relocated = _ensure_lut_in_master(lut_path)
+            if relocated:
+                try:
+                    _, proj, _lut_err = _check()
+                    if proj:
+                        proj.RefreshLUTList()
+                except Exception:
+                    pass
+                ok = bool(g.SetLUT(node_index, relocated))
+                if ok:
+                    return {"success": True, "resolved_lut": relocated,
+                            "note": "LUT staged under the master LUT dir "
+                                    "(MCP/ subfolder) and applied; SetLUT does "
+                                    "not resolve the user LUT dir."}
+        return {"success": ok}
     elif action == "get_node_cache":
         return {"cache": g.GetNodeCacheMode(p["node_index"])}
     elif action == "set_node_cache":
@@ -23771,6 +23957,13 @@ def _dctl_dir(category: str = "lut") -> str:
                      "Valid: lut, aces_idt, aces_odt")
 
 
+# LUT relocation for Graph.SetLUT lives in src.utils.lut_paths so server.py and
+# src/granular/graph.py share one implementation (see the module docstring for
+# the live-verified behavior). Thin aliases keep the existing call sites stable.
+_master_lut_dir = master_lut_dir
+_ensure_lut_in_master = ensure_lut_in_master
+
+
 def _validate_dctl_name(name: str) -> Optional[Dict[str, Any]]:
     if not name or not _DCTL_NAME_RE.match(name):
         return _err(f"Invalid DCTL name '{name}'. "

package/src/utils/destructive_hook.py

@@ -70,6 +70,7 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
     "edit_engine": frozenset({
         "execute_selects",
         "execute_tighten",
+        "execute_silence_ripple",
         "execute_swap",
     }),
     "timeline": frozenset({

package/src/utils/edit_engine.py

@@ -31,10 +31,15 @@ import uuid
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 
 from src.utils import analysis_memory, analysis_store, timeline_brain_db
+from src.utils import silence_ripple as _silence_ripple_mod
 
 PLAN_DIR_NAME = "edit_plans"
 DEFAULT_HANDLE_SECONDS = 0.25
 DEFAULT_MIN_PAUSE_SECONDS = 1.5
+DEFAULT_SILENCE_THRESHOLD_DB = _silence_ripple_mod.DEFAULT_THRESHOLD_DB
+DEFAULT_SILENCE_MIN_STRIP_FRAMES = _silence_ripple_mod.DEFAULT_MIN_STRIP_FRAMES
+DEFAULT_SILENCE_PRE_HEAD_FRAMES = _silence_ripple_mod.DEFAULT_PRE_HEAD_FRAMES
+DEFAULT_SILENCE_POST_TAIL_FRAMES = _silence_ripple_mod.DEFAULT_POST_TAIL_FRAMES
 
 _SELECT_RANK = {"high": 3, "medium": 2, "low": 1}
 
@@ -593,6 +598,255 @@ def plan_tighten(
     }
 
 
+# ── E2b: waveform silence ripple (Resolve UI parity) ─────────────────────────
+
+
+def _resolve_media_path(conn, item: Dict[str, Any]) -> Optional[str]:
+    path = item.get("media_path") or item.get("file_path")
+    if path and os.path.isfile(str(path)):
+        return str(path)
+    clip_uuid = analysis_store.resolve_clip_uuid(conn, item.get("media_ref"))
+    if not clip_uuid:
+        clip_uuid = analysis_store.resolve_clip_uuid(conn, item.get("media_path"))
+    if not clip_uuid:
+        return None
+    row = conn.execute("SELECT file_path FROM clips WHERE clip_uuid = ?", (clip_uuid,)).fetchone()
+    if not row or not row["file_path"]:
+        return None
+    fp = str(row["file_path"])
+    return fp if os.path.isfile(fp) else None
+
+
+def plan_silence_ripple(
+    project_root: str,
+    *,
+    items: Sequence[Dict[str, Any]],
+    timeline_name: str,
+    timeline_fps: float,
+    threshold_db: float = DEFAULT_SILENCE_THRESHOLD_DB,
+    min_strip_frames: float = DEFAULT_SILENCE_MIN_STRIP_FRAMES,
+    pre_head_frames: float = DEFAULT_SILENCE_PRE_HEAD_FRAMES,
+    post_tail_frames: float = DEFAULT_SILENCE_POST_TAIL_FRAMES,
+    include_audio: bool = True,
+) -> Dict[str, Any]:
+    """Propose silence strips from waveform detection (ffmpeg silencedetect).
+
+    Mirrors Resolve's *Clip → Audio Operations → Ripple Delete Silence*.
+    Each timeline item is analyzed over its source trim; detected silences
+    become lifts assembled into a tightened VARIANT via keep_ranges.
+    """
+    if not items:
+        return {"success": False, "error": "No timeline items supplied"}
+    fps = float(timeline_fps) if timeline_fps and float(timeline_fps) > 0 else 24.0
+    min_strip_sec = _silence_ripple_mod.frames_to_seconds(min_strip_frames, fps)
+    pre_head_sec = _silence_ripple_mod.frames_to_seconds(pre_head_frames, fps)
+    post_tail_sec = _silence_ripple_mod.frames_to_seconds(post_tail_frames, fps)
+    conn = timeline_brain_db.connect(project_root)
+
+    lifts: List[Dict[str, Any]] = []
+    skipped: List[Dict[str, Any]] = []
+    item_specs: List[Dict[str, Any]] = []
+    timeline_total_frames = 0
+
+    for item_index, item in enumerate(items):
+        try:
+            tl_start = int(item["timeline_start_frame"])
+            tl_end = int(item["timeline_end_frame"])
+            src_start_frame = int(item.get("source_start_frame") or 0)
+        except (KeyError, TypeError, ValueError):
+            skipped.append({"item": item.get("item_name"), "reason": "missing frame fields"})
+            continue
+        timeline_total_frames += max(0, tl_end - tl_start)
+
+        clip_uuid = analysis_store.resolve_clip_uuid(conn, item.get("media_ref"))
+        if not clip_uuid:
+            clip_uuid = analysis_store.resolve_clip_uuid(conn, item.get("media_path"))
+        clip_row = None
+        clip_fps = fps
+        resolve_clip_id = None
+        if clip_uuid:
+            clip_row = conn.execute("SELECT * FROM clips WHERE clip_uuid = ?", (clip_uuid,)).fetchone()
+            if clip_row:
+                clip_fps = _clip_fps(dict(clip_row))
+                resolve_clip_id = dict(clip_row).get("resolve_clip_id")
+        resolve_clip_id = resolve_clip_id or item.get("media_ref")
+        if not resolve_clip_id:
+            skipped.append({
+                "item": item.get("item_name"),
+                "reason": "no media reference — OMITTED from the assembled variant",
+            })
+            continue
+
+        src_start_sec = src_start_frame / clip_fps
+        src_end_sec = src_start_sec + (tl_end - tl_start) / fps
+        spec = {
+            "item_index": item_index,
+            "item": item,
+            "clip_uuid": clip_uuid,
+            "clip_fps": clip_fps,
+            "resolve_clip_id": resolve_clip_id,
+            "src_start_sec": src_start_sec,
+            "src_end_sec": src_end_sec,
+            # Default: ride along whole. Overwritten below when waveform
+            # evidence is available for this item.
+            "keep_segments": [(src_start_sec, src_end_sec)],
+            "strip_regions": [],
+        }
+
+        media_path = _resolve_media_path(conn, item)
+        if not media_path:
+            skipped.append({
+                "item": item.get("item_name"),
+                "reason": "no readable media file path — kept whole in variant",
+            })
+            item_specs.append(spec)
+            continue
+        if not _silence_ripple_mod.ffmpeg_available():
+            return {
+                "success": False,
+                "error": (
+                    "ffmpeg not found on PATH — waveform silence detection "
+                    "requires ffmpeg (see media_analysis capabilities)"
+                ),
+            }
+
+        strip_regions, keep_segments = _silence_ripple_mod.plan_item_silence_strips(
+            media_path,
+            src_start_sec,
+            src_end_sec,
+            threshold_db=float(threshold_db),
+            min_strip_sec=min_strip_sec,
+            pre_head_sec=pre_head_sec,
+            post_tail_sec=post_tail_sec,
+        )
+        spec["keep_segments"] = keep_segments
+        spec["strip_regions"] = strip_regions
+        item_specs.append(spec)
+
+        for strip_start, strip_end in strip_regions:
+            lift_start = tl_start + int(round((strip_start - src_start_sec) * fps))
+            lift_end = tl_start + int(round((strip_end - src_start_sec) * fps))
+            if lift_end <= lift_start:
+                continue
+            lifts.append({
+                "kind": "silence",
+                "action": "ripple_delete",
+                "timeline_start_frame": lift_start,
+                "timeline_end_frame": lift_end,
+                "duration_seconds": round((lift_end - lift_start) / fps, 3),
+                "item_name": item.get("item_name"),
+                "item_index": item_index,
+                "source_lift_seconds": [round(strip_start, 3), round(strip_end, 3)],
+                "rationale": (
+                    f"Waveform silence {round(strip_start, 2)}s–{round(strip_end, 2)}s "
+                    f"(threshold {threshold_db} dB, min {min_strip_frames} frames)."
+                ),
+                "evidence": {
+                    "basis": "ffmpeg_silencedetect",
+                    "threshold_db": threshold_db,
+                    "source_gap_seconds": [round(strip_start, 3), round(strip_end, 3)],
+                },
+            })
+
+    skipped = _dedupe_skipped(skipped)
+    if not lifts:
+        return {
+            "success": False,
+            "error": "No silence regions found above threshold",
+            "skipped": skipped,
+            "note": (
+                f"threshold_db={threshold_db}, min_strip_frames={min_strip_frames}; "
+                "items without readable file paths carry no waveform evidence "
+                "(kept whole — see skipped)."
+            ),
+        }
+
+    lifts.sort(key=lambda l: -l["timeline_start_frame"])
+
+    keep_ranges: List[Dict[str, Any]] = []
+    for spec in item_specs:
+        item = spec["item"]
+        clip_fps = spec["clip_fps"]
+        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 spec.get("keep_segments") or []:
+            start_frame = int(round(seg_start * clip_fps))
+            end_frame = max(start_frame + 1, int(round(seg_end * clip_fps)))
+            keep_ranges.append({
+                "clip_id": spec["resolve_clip_id"],
+                "start_frame": start_frame,
+                "end_frame": end_frame,
+                "track_type": "video",
+                "track_index": int(item.get("track_index") or 1),
+            })
+            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": "silence_ripple",
+        "timeline_name": timeline_name,
+        "timeline_fps": fps,
+        "lifts": lifts,
+        "keep_ranges": keep_ranges,
+        "include_audio": bool(include_audio),
+        "skipped": skipped,
+        "summary": (
+            f"{len(lifts)} silence strips, ~{round(removed_frames / fps, 1)}s removed "
+            f"from '{timeline_name}' (waveform ripple-delete variant"
+            f"{', video + audio' if include_audio else ', video only'})"
+        ),
+        "settings": {
+            "threshold_db": threshold_db,
+            "min_strip_frames": min_strip_frames,
+            "pre_head_frames": pre_head_frames,
+            "post_tail_frames": post_tail_frames,
+            "include_audio": bool(include_audio),
+        },
+    })
+    result = {
+        "success": True,
+        "status": "plan_ready",
+        "plan_id": plan["plan_id"],
+        "kind": "silence_ripple",
+        "timeline_name": timeline_name,
+        "lift_count": len(lifts),
+        "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_silence_ripple', "
+            "params={plan_id}) — a tightened VARIANT timeline is assembled from "
+            "waveform silence detection; the original timeline is never mutated. "
+            "Tune threshold_db / min_strip_frames to match Resolve's "
+            "Ripple Delete Silence dialog."
+        ),
+    }
+    if video_keep_range_count == 0:
+        result["warning"] = (
+            "Plan removes ALL planned content (no keep ranges survived) — "
+            "the source audio may be quieter than threshold_db throughout. "
+            "Check the threshold before executing; execution will refuse this plan."
+        )
+    return result
+
+
 # ── E3: swap alternates ──────────────────────────────────────────────────────
 
 

package/src/utils/lut_paths.py

@@ -0,0 +1,81 @@
+"""Master LUT directory resolution for Graph.SetLUT().
+
+Resolve's Graph.SetLUT() resolves relative LUT names -- and even absolute
+paths -- ONLY against the master (system) LUT root, NOT the per-user LUT dir
+that the dctl tool installs into. Verified live on Resolve Studio 19.1.3.7:
+SetLUT succeeds for a LUT in the master dir (by relative or subfolder path) and
+returns False for the same file in the user dir, even after RefreshLUTList and
+even via an absolute user-dir path. (The originating report, PR #90, observed
+the same behavior on Studio 21.0.2.) These helpers relocate a user-dir LUT into
+a namespaced subfolder of the master dir so SetLUT can resolve it.
+"""
+
+import os
+import platform
+import shutil
+from typing import List, Optional
+
+from src.utils.platform import get_resolve_plugin_paths
+
+# Subfolder under the master LUT root where relocated LUTs are staged. SetLUT
+# resolves relative paths against the master root, so a subfolder path like
+# "MCP/Foo.cube" works AND avoids clobbering stock/vendor LUTs that share a
+# basename (e.g. InstantC.cube). Verified live on Resolve Studio 19.1.3.7.
+MASTER_LUT_RELOCATE_SUBDIR = "MCP"
+
+
+def master_lut_dir() -> str:
+    """Return Resolve's master (system) LUT directory for this platform."""
+    plat = platform.system().lower()
+    if plat == "windows":
+        programdata = os.environ.get("PROGRAMDATA", r"C:\ProgramData")
+        return os.path.join(programdata, "Blackmagic Design",
+                            "DaVinci Resolve", "Support", "LUT")
+    if plat == "linux":
+        for cand in ("/opt/resolve/LUT", "/home/resolve/LUT"):
+            if os.path.isdir(cand):
+                return cand
+        return "/opt/resolve/LUT"
+    # darwin / default
+    return "/Library/Application Support/Blackmagic Design/DaVinci Resolve/LUT"
+
+
+def _user_lut_dir() -> Optional[str]:
+    """Return the per-user LUT dir (where dctl install writes), or None."""
+    try:
+        return get_resolve_plugin_paths()["dctl_dir"]
+    except Exception:
+        return None
+
+
+def ensure_lut_in_master(lut_path: str) -> Optional[str]:
+    """Make a LUT resolvable by Graph.SetLUT().
+
+    Locates the file named by lut_path (absolute, user LUT dir, or already in
+    the master dir), copies it into a namespaced subfolder of the master LUT
+    dir when needed, and returns the master-relative path (forward slashes, as
+    GetLUT reports) to hand back to SetLUT. Returns None if the source cannot
+    be found or the master dir is not writable.
+    """
+    master = master_lut_dir()
+    base = os.path.basename(lut_path)
+    candidates: List[str] = []
+    if os.path.isabs(lut_path):
+        candidates.append(lut_path)
+    else:
+        user_dir = _user_lut_dir()
+        if user_dir:
+            candidates.append(os.path.join(user_dir, lut_path))
+        candidates.append(os.path.join(master, lut_path))
+    src = next((c for c in candidates if os.path.isfile(c)), None)
+    if not src:
+        return None
+    dst_dir = os.path.join(master, MASTER_LUT_RELOCATE_SUBDIR)
+    dst = os.path.join(dst_dir, base)
+    if os.path.abspath(src) != os.path.abspath(dst):
+        try:
+            os.makedirs(dst_dir, exist_ok=True)
+            shutil.copy2(src, dst)
+        except Exception:
+            return None
+    return f"{MASTER_LUT_RELOCATE_SUBDIR}/{base}"

package/src/utils/silence_ripple.py

@@ -0,0 +1,202 @@
+"""Waveform silence detection for ripple-delete planning.
+
+Resolve exposes **Clip → Audio Operations → Ripple Delete Silence** in the UI
+but not via scripting. This module approximates that workflow using ffmpeg
+``silencedetect`` plus the edit-engine keep-range assembler (variant timeline).
+
+Settings map to the Resolve dialog:
+  - threshold_db     → Threshold (dB)
+  - min_strip_frames → Minimum strip length (frames)
+  - pre_head_frames  → Pre-head (frames kept before silence)
+  - post_tail_frames → Post-tail (frames kept after silence ends)
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from typing import List, Sequence, Tuple
+
+from src.utils.media_analysis import _parse_silencedetect
+
+DEFAULT_THRESHOLD_DB = -30.0
+DEFAULT_MIN_STRIP_FRAMES = 10
+DEFAULT_PRE_HEAD_FRAMES = 0
+DEFAULT_POST_TAIL_FRAMES = 1
+
+
+def ffmpeg_available() -> bool:
+    return shutil.which("ffmpeg") is not None
+
+
+def frames_to_seconds(frames: float, fps: float) -> float:
+    if fps <= 0:
+        fps = 24.0
+    return float(frames) / fps
+
+
+def audio_stream_count(media_path: str) -> int:
+    """Number of audio streams in the file (0 when ffprobe fails)."""
+    from src.utils.media_analysis import _ffprobe
+
+    probe = _ffprobe(media_path)
+    if not probe.get("success"):
+        return 0
+    streams = (probe.get("raw") or {}).get("streams") or []
+    return sum(1 for s in streams if s.get("codec_type") == "audio")
+
+
+def build_silencedetect_args(
+    media_path: str,
+    start_sec: float,
+    duration: float,
+    *,
+    threshold_db: float,
+    min_duration_sec: float,
+    audio_streams: int,
+) -> List[str]:
+    """ffmpeg argv for silence detection over a source slice.
+
+    Multi-stream sources (e.g. production MXF with one mono stream per
+    channel) are merged first: silencedetect's default joint mode then only
+    triggers when EVERY channel is silent — matching Resolve's dialog, and
+    immune to a dead scratch channel reading as all-silence. -vn skips the
+    (potentially 4K) video decode entirely.
+    """
+    detect = f"silencedetect=noise={threshold_db}dB:d={min_duration_sec}"
+    args = [
+        "ffmpeg", "-hide_banner", "-nostats",
+        "-ss", str(start_sec),
+        "-i", media_path,
+        "-t", str(duration),
+        "-vn",
+    ]
+    if audio_streams > 1:
+        inputs = "".join(f"[0:a:{i}]" for i in range(audio_streams))
+        args += ["-filter_complex", f"{inputs}amerge=inputs={audio_streams},{detect}"]
+    else:
+        args += ["-af", detect]
+    args += ["-f", "null", "-"]
+    return args
+
+
+def detect_silence_in_range(
+    media_path: str,
+    start_sec: float,
+    end_sec: float,
+    *,
+    threshold_db: float = DEFAULT_THRESHOLD_DB,
+    min_duration_sec: float,
+) -> List[Tuple[float, float]]:
+    """Return absolute-file silence intervals within [start_sec, end_sec).
+
+    Uses ffmpeg silencedetect on the trimmed slice (all audio streams merged).
+    Timestamps are converted back to absolute source-file seconds.
+    """
+    if not media_path or not os.path.isfile(media_path):
+        return []
+    if end_sec <= start_sec:
+        return []
+    duration = end_sec - start_sec
+    from src.utils.media_analysis import _run_command
+
+    streams = audio_stream_count(media_path)
+    if streams == 0:
+        return []
+    args = build_silencedetect_args(
+        media_path, start_sec, duration,
+        threshold_db=threshold_db, min_duration_sec=min_duration_sec,
+        audio_streams=streams,
+    )
+    code, _, stderr = _run_command(args)
+    if code != 0 and streams > 1:
+        # amerge can refuse mismatched sample rates — fall back to the
+        # default single-stream selection rather than dropping evidence.
+        args = build_silencedetect_args(
+            media_path, start_sec, duration,
+            threshold_db=threshold_db, min_duration_sec=min_duration_sec,
+            audio_streams=1,
+        )
+        code, _, stderr = _run_command(args)
+    if code != 0:
+        return []
+    parsed = _parse_silencedetect(stderr)
+    out: List[Tuple[float, float]] = []
+    for row in parsed:
+        rel_start = row.get("start")
+        rel_end = row.get("end")
+        if rel_start is None:
+            continue
+        abs_start = start_sec + float(rel_start)
+        abs_end = start_sec + float(rel_end) if rel_end is not None else end_sec
+        abs_end = min(abs_end, end_sec)
+        if abs_end - abs_start >= min_duration_sec * 0.9:
+            out.append((abs_start, abs_end))
+    return out
+
+
+def apply_silence_handles(
+    silences: Sequence[Tuple[float, float]],
+    *,
+    pre_head_sec: float,
+    post_tail_sec: float,
+    range_start: float,
+    range_end: float,
+) -> List[Tuple[float, float]]:
+    """Expand/shrink silence regions per Resolve pre-head / post-tail handles."""
+    strip: List[Tuple[float, float]] = []
+    for s, e in silences:
+        s = max(range_start, s + pre_head_sec)
+        e = min(range_end, e - post_tail_sec)
+        if e > s + 0.001:
+            strip.append((s, e))
+    return strip
+
+
+def silence_to_keep_segments(
+    range_start: float,
+    range_end: float,
+    strip_regions: Sequence[Tuple[float, float]],
+    *,
+    min_keep_sec: float = 0.05,
+) -> List[Tuple[float, float]]:
+    """Complement of strip regions → speech/keep segments in source time."""
+    segments: List[Tuple[float, float]] = []
+    cursor = range_start
+    for s, e in sorted(strip_regions):
+        s, e = max(s, range_start), min(e, range_end)
+        if s - cursor >= min_keep_sec:
+            segments.append((cursor, s))
+        cursor = max(cursor, e)
+    if range_end - cursor >= min_keep_sec:
+        segments.append((cursor, range_end))
+    return segments
+
+
+def plan_item_silence_strips(
+    media_path: str,
+    src_start_sec: float,
+    src_end_sec: float,
+    *,
+    threshold_db: float,
+    min_strip_sec: float,
+    pre_head_sec: float,
+    post_tail_sec: float,
+) -> Tuple[List[Tuple[float, float]], List[Tuple[float, float]]]:
+    """Detect silences and return (strip_regions, keep_segments) in source seconds."""
+    raw = detect_silence_in_range(
+        media_path,
+        src_start_sec,
+        src_end_sec,
+        threshold_db=threshold_db,
+        min_duration_sec=min_strip_sec,
+    )
+    strip = apply_silence_handles(
+        raw,
+        pre_head_sec=pre_head_sec,
+        post_tail_sec=post_tail_sec,
+        range_start=src_start_sec,
+        range_end=src_end_sec,
+    )
+    keep = silence_to_keep_segments(src_start_sec, src_end_sec, strip)
+    return strip, keep