davinci-resolve-mcp 2.67.0 → 2.68.0

package/src/utils/resolve_connection.py

@@ -9,6 +9,11 @@ import os
 
 from .platform import get_platform, get_resolve_paths, setup_environment
 
+try:  # optional: absent in minimal installs, and never required for Studio
+    from . import resolve_bridge_client as bridge_client
+except Exception:  # pragma: no cover - defensive
+    bridge_client = None
+
 logger = logging.getLogger("davinci-resolve-mcp.connection")
 
 DEFAULT_RESOLVE_SCRIPT_TIMEOUT = 5.0
@@ -33,7 +38,30 @@ def _network_timeout():
 
 
 def connect_resolve(dvr_script):
-    """Create a Resolve handle, optionally targeting an explicit network host."""
+    """Create a Resolve handle. Three modes, tried in order of directness.
+
+    1. **Bridge** (opt-in, `DAVINCI_RESOLVE_BRIDGE=1`) — a proxy over the
+       authenticated loopback bridge running inside Resolve. This is the only
+       mode that works on the **free edition**, whose external scripting API
+       refuses foreign processes. Tried first when enabled, because if a user has
+       asked for it, silently using a different transport would hide a broken
+       bridge.
+    2. **Network** (`RESOLVE_SCRIPT_HOST`) — Studio's remote scripting.
+    3. **Local** — Studio's local scripting. The default.
+
+    `dvr_script` may be None in bridge mode: the bridge does not need Blackmagic's
+    module at all, which is precisely why it reaches editions the module cannot.
+    """
+    if bridge_client is not None and bridge_client.bridge_enabled():
+        try:
+            return bridge_client.connect()
+        except bridge_client.BridgeUnavailable as exc:
+            # Explicitly requested and unavailable: say so instead of quietly
+            # falling through to a transport the user did not ask for.
+            logger.error("in-app bridge requested but unavailable: %s", exc)
+            raise
+    if dvr_script is None:
+        return None
     host = os.environ.get("RESOLVE_SCRIPT_HOST")
     if host:
         return dvr_script.scriptapp("Resolve", host, _network_timeout())

package/src/utils/silence_ripple.py

@@ -9,13 +9,50 @@ Settings map to the Resolve dialog:
   - 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)
+
+## Auto-calibrated threshold
+
+A fixed threshold is the most common way this goes wrong: -30 dB under-detects on
+quiet location audio and over-cuts a noisy room. When `threshold_db` is omitted,
+`calibrate_silence_gate` measures the file's own noise floor and places the gate
+just above it.
+
+The levels come from ffmpeg `astats`, using **`RMS through dB`** (ffmpeg's
+spelling of *trough* — the quietest analysis window) and **`RMS peak dB`** (the
+loudest). Those two bracket the file's own dynamic range, and the gate is placed
+inside that bracket.
+
+Two metrics were measured and rejected on the way here, both worth not
+rediscovering:
+
+- `volumedetect`'s **`mean_volume`** tracks `RMS level` almost exactly — it is
+  the *programme* level, not a floor. Deriving `mean_volume - 6` reads the
+  content and calls it the noise floor.
+- `astats`' **`Noise floor dB`** moves with how much of the slice is quiet, not
+  with how quiet it is. Two fixtures sharing an identical noise bed measured
+  -57.1 and -76.3 purely because one was 60% silent and the other 90%. Calibrated
+  against that, the gate lands 19 dB apart on acoustically identical material.
+  `RMS through` measured -56.06 and -56.12 on the same pair.
+
+The gate is biased above the midpoint of the trough/peak bracket because
+`silencedetect` compares instantaneous amplitude while `astats` reports windowed
+RMS: a quiet section's samples peak some way above its own RMS, and a gate at the
+exact midpoint sits near the bottom edge of the usable band.
+
+Measuring both ends also makes the failure case detectable: when trough and peak
+are not separated, no threshold distinguishes speech from room, and this says so
+and falls back to the documented default instead of inventing a number that
+finds nothing.
 """
 
 from __future__ import annotations
 
+import math
 import os
+import re
 import shutil
-from typing import List, Sequence, Tuple
+from dataclasses import dataclass
+from typing import List, Optional, Sequence, Tuple
 
 from src.utils.media_analysis import _parse_silencedetect
 
@@ -24,6 +61,67 @@ DEFAULT_MIN_STRIP_FRAMES = 10
 DEFAULT_PRE_HEAD_FRAMES = 0
 DEFAULT_POST_TAIL_FRAMES = 1
 
+#: Where in the trough→peak bracket the gate sits. Above 0.5 deliberately: see
+#: the module docstring — silencedetect compares instantaneous amplitude while
+#: astats reports windowed RMS, so a midpoint gate hugs the usable band's floor.
+GATE_BIAS = 0.6
+#: Trough and peak must differ by at least this for a gate to mean anything.
+MIN_SEPARATION_DB = 12.0
+#: True digital silence (trough = -inf) admits any gate; sit this far under peak.
+DIGITAL_SILENCE_HEADROOM_DB = 24.0
+#: Absolute band. Outside it a "calibrated" gate is not credible for dialogue.
+GATE_MIN_DB = -60.0
+GATE_MAX_DB = -24.0
+
+#: ffmpeg spells the trough "RMS through"; accept a corrected spelling too so a
+#: future ffmpeg fixing the typo does not silently drop us to the fallback.
+_ASTATS_RMS_TROUGH_RE = re.compile(r"RMS (?:through|trough) dB:\s*(-?[0-9.]+|-?inf)", re.IGNORECASE)
+_ASTATS_RMS_PEAK_RE = re.compile(r"RMS peak dB:\s*(-?[0-9.]+|-?inf)", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class NoiseCalibration:
+    """Outcome of a level measurement, with the reasoning kept visible.
+
+    **`usable` False means: do not strip this item.** The measurement happened
+    and produced no credible gate, so `gate_db` carries `DEFAULT_THRESHOLD_DB`
+    only for reporting — detection must be skipped and the item kept whole.
+
+    That is deliberately stronger than "fall back to the default". A fixed
+    threshold applied to material it does not suit is not a degraded answer, it
+    is a wrong one: a -33 dBFS programme measured against a -30 dB gate reads as
+    silent end to end, and the ripple would strip the whole clip. Keeping the
+    item whole and surfacing `reason` leaves a human able to set `threshold_db`
+    explicitly; cutting on an unvalidated gate does not.
+
+    `reason` is always populated when `usable` is False — a skip is never silent.
+    """
+
+    gate_db: float
+    basis: str  # measured_dynamics | digital_silence | fallback_default
+    usable: bool
+    quiet_rms_db: Optional[float] = None
+    loud_rms_db: Optional[float] = None
+    separation_db: Optional[float] = None
+    reason: Optional[str] = None
+
+    def as_dict(self) -> dict:
+        def finite(value: Optional[float]) -> Optional[float]:
+            if value is None or not math.isfinite(value):
+                return None
+            return round(value, 2)
+
+        return {
+            "gate_db": round(self.gate_db, 2),
+            "basis": self.basis,
+            "usable": self.usable,
+            "quiet_rms_db": finite(self.quiet_rms_db),
+            "loud_rms_db": finite(self.loud_rms_db),
+            "quiet_is_digital_silence": self.quiet_rms_db == float("-inf"),
+            "separation_db": finite(self.separation_db),
+            "reason": self.reason,
+        }
+
 
 def ffmpeg_available() -> bool:
     return shutil.which("ffmpeg") is not None
@@ -46,24 +144,26 @@ def audio_stream_count(media_path: str) -> int:
     return sum(1 for s in streams if s.get("codec_type") == "audio")
 
 
-def build_silencedetect_args(
+def build_audio_filter_args(
     media_path: str,
     start_sec: float,
     duration: float,
+    audio_filter: str,
     *,
-    threshold_db: float,
-    min_duration_sec: float,
     audio_streams: int,
 ) -> List[str]:
-    """ffmpeg argv for silence detection over a source slice.
+    """ffmpeg argv applying one audio filter 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.
+
+    Every analysis filter routes through here so the merge and the -vn skip stay
+    identical across passes. A calibration measured on stream 0 alone while
+    detection ran on the merge would place the gate against the wrong signal.
     """
-    detect = f"silencedetect=noise={threshold_db}dB:d={min_duration_sec}"
     args = [
         "ffmpeg", "-hide_banner", "-nostats",
         "-ss", str(start_sec),
@@ -73,13 +173,161 @@ def build_silencedetect_args(
     ]
     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}"]
+        args += ["-filter_complex", f"{inputs}amerge=inputs={audio_streams},{audio_filter}"]
     else:
-        args += ["-af", detect]
+        args += ["-af", audio_filter]
     args += ["-f", "null", "-"]
     return args
 
 
+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."""
+    return build_audio_filter_args(
+        media_path,
+        start_sec,
+        duration,
+        f"silencedetect=noise={threshold_db}dB:d={min_duration_sec}",
+        audio_streams=audio_streams,
+    )
+
+
+def _parse_astats_levels(stderr: str) -> Tuple[Optional[float], Optional[float]]:
+    """(quiet_rms_db, loud_rms_db) from an astats summary; -inf is preserved.
+
+    -inf is a real measurement, not a parse failure: it means true digital
+    silence is present. Collapsing it to None would discard that.
+    """
+
+    def grab(pattern: "re.Pattern[str]") -> Optional[float]:
+        matches = pattern.findall(stderr)
+        if not matches:
+            return None
+        raw = matches[-1].strip().lower()  # the Overall block prints last
+        if raw.endswith("inf"):
+            return float("-inf") if raw.startswith("-") else float("inf")
+        try:
+            return float(raw)
+        except ValueError:
+            return None
+
+    return grab(_ASTATS_RMS_TROUGH_RE), grab(_ASTATS_RMS_PEAK_RE)
+
+
+def _gate_from_levels(quiet_rms_db: Optional[float], loud_rms_db: Optional[float]) -> NoiseCalibration:
+    """Pure level→gate policy, split out so it is testable without ffmpeg."""
+
+    def fallback(reason: str) -> NoiseCalibration:
+        return NoiseCalibration(
+            gate_db=DEFAULT_THRESHOLD_DB,
+            basis="fallback_default",
+            usable=False,
+            quiet_rms_db=quiet_rms_db,
+            loud_rms_db=loud_rms_db,
+            reason=reason,
+        )
+
+    if quiet_rms_db is None or loud_rms_db is None:
+        return fallback("astats reported no usable levels for this slice")
+    if not math.isfinite(loud_rms_db):
+        return fallback("the slice carries no programme audio to calibrate against")
+
+    if quiet_rms_db == float("-inf"):
+        # True digital silence: any gate between -inf and the programme works.
+        gate = min(max(loud_rms_db - DIGITAL_SILENCE_HEADROOM_DB, GATE_MIN_DB), GATE_MAX_DB)
+        return NoiseCalibration(
+            gate_db=gate,
+            basis="digital_silence",
+            usable=True,
+            quiet_rms_db=quiet_rms_db,
+            loud_rms_db=loud_rms_db,
+            separation_db=float("inf"),
+            reason="the slice contains true digital silence; the gate sits well under programme level",
+        )
+
+    separation = loud_rms_db - quiet_rms_db
+    if separation < MIN_SEPARATION_DB:
+        return NoiseCalibration(
+            gate_db=DEFAULT_THRESHOLD_DB,
+            basis="fallback_default",
+            usable=False,
+            quiet_rms_db=quiet_rms_db,
+            loud_rms_db=loud_rms_db,
+            separation_db=separation,
+            reason=(
+                f"quietest ({quiet_rms_db:.1f} dB) and loudest ({loud_rms_db:.1f} dB) windows are "
+                f"only {separation:.1f} dB apart; no threshold separates speech from room here, "
+                "so the default is used unchanged"
+            ),
+        )
+
+    gate = quiet_rms_db + GATE_BIAS * separation
+    gate = min(max(gate, GATE_MIN_DB), GATE_MAX_DB)
+    return NoiseCalibration(
+        gate_db=gate,
+        basis="measured_dynamics",
+        usable=True,
+        quiet_rms_db=quiet_rms_db,
+        loud_rms_db=loud_rms_db,
+        separation_db=separation,
+    )
+
+
+def calibrate_silence_gate(
+    media_path: str,
+    start_sec: float,
+    end_sec: float,
+    *,
+    audio_streams: Optional[int] = None,
+) -> NoiseCalibration:
+    """Measure this slice's noise floor and place a silence gate just above it.
+
+    Falls back to `DEFAULT_THRESHOLD_DB` — always with a stated reason — when the
+    file cannot be measured or the floor is not separated from the programme.
+    """
+    if not media_path or not os.path.isfile(media_path):
+        return NoiseCalibration(
+            gate_db=DEFAULT_THRESHOLD_DB, basis="fallback_default", usable=False,
+            reason="media file is not readable",
+        )
+    if end_sec <= start_sec:
+        return NoiseCalibration(
+            gate_db=DEFAULT_THRESHOLD_DB, basis="fallback_default", usable=False,
+            reason="empty source range",
+        )
+    from src.utils.media_analysis import _run_command
+
+    streams = audio_stream_count(media_path) if audio_streams is None else audio_streams
+    if streams == 0:
+        return NoiseCalibration(
+            gate_db=DEFAULT_THRESHOLD_DB, basis="fallback_default", usable=False,
+            reason="no audio streams",
+        )
+    args = build_audio_filter_args(
+        media_path, start_sec, end_sec - start_sec, "astats", audio_streams=streams
+    )
+    code, _, stderr = _run_command(args)
+    if code != 0 and streams > 1:
+        # Same amerge fallback as detection: mismatched sample rates are refused.
+        args = build_audio_filter_args(
+            media_path, start_sec, end_sec - start_sec, "astats", audio_streams=1
+        )
+        code, _, stderr = _run_command(args)
+    if code != 0:
+        return NoiseCalibration(
+            gate_db=DEFAULT_THRESHOLD_DB, basis="fallback_default", usable=False,
+            reason="ffmpeg astats failed on this slice",
+        )
+    return _gate_from_levels(*_parse_astats_levels(stderr))
+
+
 def detect_silence_in_range(
     media_path: str,
     start_sec: float,

package/src/utils/strata_analyzers.py

@@ -33,6 +33,13 @@ try:  # numpy is present in most installs but is not a hard requirement.
 except ImportError:  # pragma: no cover - exercised on minimal installs
     _np = None
 
+#: Compute helpers below take numpy arrays as arguments and are only reachable
+#: through entry points that call `_require("numpy")`. Declared so the contract
+#: is greppable instead of living in one comment two hundred lines down.
+_OPTIONAL_DEPENDENCY_CONTRACT = (
+    "numpy: every analyzer entry point gates on _require('numpy'); compute helpers assume it"
+)
+
 PROSODY_SOURCE = "prosody_v1"
 PROSODY_VERSION = "1.0.0"
 BEATGRID_SOURCE = "beatgrid_v1"

package/src/utils/strata_faces.py

@@ -57,6 +57,12 @@ _BROW = {"left": 105, "right": 334}
 _FACE_BOX = {"top": 10, "bottom": 152}
 
 EAR_BLINK_THRESHOLD = 0.21
+#: Every entry point checks `capabilities()["available"]` or raises up front,
+#: so helpers below assume cv2/mediapipe are present.
+_OPTIONAL_DEPENDENCY_CONTRACT = (
+    "opencv-python + mediapipe: run_face_strata refuses via capabilities() before any helper runs"
+)
+
 EAR_MIN_CLOSED_FRAMES = 1
 EAR_MAX_CLOSED_SECONDS = 0.5  # longer than this is eyes-closed, not a blink