davinci-resolve-mcp 2.67.0 → 2.68.0

package/src/utils/delivery_targets.py

@@ -47,6 +47,40 @@ Both omissions follow the module's core rule:
 Asserting a field the render never controlled produces QC failures that say
 nothing about the deliverable — so unset fields are absent from both projections.
 
+## Loudness is a fourth projection, not a QC-spec field
+
+`deliverable_qc` asserts what the *render* pinned. Program loudness is not one of
+those things — the mix sets it, not `SetRenderSettings` — so a loudness contract
+would violate the rule above if it lived in `to_qc_spec()`. It is a separate
+projection, `to_loudness_target()`, feeding the `loudness_qc` action, whose
+target vocabulary is `{integrated, integratedTol, truePeakMax, lraMax}`.
+
+A loudness failure therefore means "the mix is wrong", never "the render settings
+are wrong", and the two never get confused in one verdict.
+
+**Dialogue-gated standards emit no gradeable `integrated` value.** `loudness_qc`
+measures full-program via ebur128; a dialogue-gated spec measures only speech.
+Grading one against the other produces a verdict that says nothing reliable, so
+the integrated number is carried in `meta` for a human or a dialogue-gated meter
+and the emitted target asserts only true peak and LRA — which *are* valid
+full-program. That is the same rule as above: assert only what is actually
+verifiable.
+
+**No per-target custom numbers yet.** A target names a standard; it cannot carry
+a bespoke integrated/tolerance pair (a show bible asking for −24 LKFS ±1 rather
+than ATSC's ±2). Free-text loudness on the authored side is already handled by
+the advanced server's `spec_from_authored`. If bespoke numbers are needed here,
+the standards table is what should grow — not five more fields on every target.
+
+## No shipped target names a loudness standard by default
+
+A ProRes master has no inherent program loudness, and even a broadcast handoff
+depends on territory (EBU vs ATSC). Guessing one would assert a number the
+deliverable never promised. `loudness_standard` is therefore unset everywhere in
+the shipped table and is named explicitly per call, per user override, or per
+project. The value here is that the *numbers* are correct and named when someone
+does ask for them, instead of being invented at the call site.
+
 ## Not every target has a QC projection
 
 Image-sequence targets render *many* files and package targets (IMF, DCP) render
@@ -104,6 +138,94 @@ TIERS = ("master", "web", "sequence", "broadcast", "package")
 VERIFIED_ON = "DaVinci Resolve Studio 19.1.3.7 (2026-07-27, 20 formats / 271 pairs)"
 
 
+# ── Loudness standards ──────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class LoudnessStandard:
+    """One named program-loudness contract, projected onto `loudness_qc`.
+
+    `integrated` / `tolerance_lu` are the integrated-loudness window;
+    `true_peak_max_dbtp` is a ceiling. `lra_max` is None for every standard
+    shipped here — none of them mandate a loudness-range cap, and asserting one
+    would invent a failure the spec never asked for. A wide LRA is surfaced as
+    advice by the projection instead.
+
+    `dialogue_gated` marks a standard whose integrated figure is measured over
+    dialogue only. Those emit no gradeable integrated value — see the module
+    docstring.
+    """
+
+    id: str
+    label: str
+    integrated: float
+    tolerance_lu: float
+    true_peak_max_dbtp: float
+    lra_max: Optional[float] = None
+    dialogue_gated: bool = False
+    source: str = ""
+
+
+#: Advisory threshold. Above this, a mix is unusually dynamic for delivery and
+#: worth a human look — but no standard here makes it a failure, so it never is.
+LRA_ADVISORY_LU = 20.0
+
+LOUDNESS_STANDARDS: Dict[str, LoudnessStandard] = {
+    standard.id: standard
+    for standard in (
+        LoudnessStandard(
+            id="web",
+            label="Web / social",
+            integrated=-16.0,
+            tolerance_lu=2.0,
+            true_peak_max_dbtp=-1.0,
+            source="Common streaming/social practice: platforms normalise around -16 LUFS, true peak <= -1 dBTP.",
+        ),
+        LoudnessStandard(
+            id="podcast",
+            label="Podcast (stereo)",
+            integrated=-16.0,
+            tolerance_lu=1.5,
+            true_peak_max_dbtp=-1.0,
+            source="Podcast stereo convention: -16 LUFS +/-1.5 LU, true peak <= -1 dBTP.",
+        ),
+        LoudnessStandard(
+            id="ebu_r128",
+            label="EBU R128 broadcast",
+            integrated=-23.0,
+            tolerance_lu=0.5,
+            true_peak_max_dbtp=-1.0,
+            source="EBU R128: -23 LUFS +/-0.5 LU, true peak <= -1 dBTP.",
+        ),
+        LoudnessStandard(
+            id="atsc_a85",
+            label="ATSC A/85 (US broadcast)",
+            integrated=-24.0,
+            tolerance_lu=2.0,
+            true_peak_max_dbtp=-2.0,
+            source="ATSC A/85: -24 LKFS +/-2 LU, true peak <= -2 dBTP.",
+        ),
+        LoudnessStandard(
+            id="ott_dialogue_gated",
+            label="OTT dialogue-gated",
+            integrated=-27.0,
+            tolerance_lu=2.0,
+            true_peak_max_dbtp=-2.0,
+            dialogue_gated=True,
+            source="OTT dialogue-gated delivery: -27 LUFS +/-2 LU over dialogue only, true peak <= -2 dBTP.",
+        ),
+    )
+}
+
+
+def normalize_loudness_standard(name: Any) -> Optional[str]:
+    """Fold a user-supplied standard name to a canonical id, or None if unknown."""
+    if not isinstance(name, str):
+        return None
+    key = name.strip().lower().replace("-", "_").replace(" ", "_")
+    return key if key in LOUDNESS_STANDARDS else None
+
+
 # ── Target model ────────────────────────────────────────────────────────────
 
 
@@ -137,6 +259,10 @@ class DeliveryTarget:
     export_audio: bool = True
     export_alpha: bool = False
 
+    # Program loudness. An id into LOUDNESS_STANDARDS, or None for "do not pin".
+    # Unset on every shipped target — see the module docstring for why.
+    loudness_standard: Optional[str] = None
+
     verified: str = ""
     source: str = ""
     notes: Tuple[str, ...] = ()
@@ -155,6 +281,13 @@ class DeliveryTarget:
     def has_qc_projection(self) -> bool:
         return bool(self.qc_codec or self.qc_audio_codec)
 
+    @property
+    def loudness(self) -> Optional[LoudnessStandard]:
+        """The named standard, or None when the target pins no loudness."""
+        if not self.loudness_standard:
+            return None
+        return LOUDNESS_STANDARDS.get(self.loudness_standard)
+
 
 # ── Shipped table ───────────────────────────────────────────────────────────
 
@@ -539,6 +672,7 @@ OVERRIDE_KEYS = frozenset(
         "qc_container",
         "qc_codec",
         "qc_audio_codec",
+        "loudness_standard",
     }
 )
 
@@ -633,6 +767,19 @@ def resolve_target(
                 patch[key] = bool(raw)
             elif key == "fps":
                 patch[key] = float(raw)
+            elif key == "loudness_standard":
+                # Validate against the table rather than accepting any string:
+                # an unrecognised standard would otherwise ride through as a
+                # target that silently emits no loudness projection at all.
+                canonical_standard = normalize_loudness_standard(raw)
+                if canonical_standard is None:
+                    logger.warning(
+                        "ignoring unknown loudness standard %r (known: %s)",
+                        raw,
+                        ", ".join(sorted(LOUDNESS_STANDARDS)),
+                    )
+                    continue
+                patch[key] = canonical_standard
             else:
                 patch[key] = str(raw)
         except (TypeError, ValueError):
@@ -666,6 +813,7 @@ def list_targets(
             "export_alpha": target.export_alpha,
             "has_qc_projection": target.has_qc_projection,
             "qc_skip_reason": target.qc_skip_reason,
+            "loudness_standard": target.loudness_standard,
             "verified": target.verified,
             "source": target.source,
             "notes": list(target.notes),
@@ -757,6 +905,83 @@ def to_qc_spec(
     return spec or None
 
 
+def to_loudness_target(target: DeliveryTarget) -> Optional[Dict[str, Any]]:
+    """Project a target onto the `loudness_qc` target vocabulary.
+
+    Returns None when the target pins no loudness — most do not, and an absent
+    contract must stay absent rather than becoming a guessed one.
+
+    Shape::
+
+        {"target": {"integrated": -23.0, "integratedTol": 0.5,
+                    "truePeakMax": -1.0},
+         "meta": {"standard": "ebu_r128", ...}}
+
+    `target` is handed straight to `loudness_qc`; `meta` is for the human-facing
+    verdict. They are separated so nothing in `meta` can ever be mistaken for a
+    gradeable assertion.
+
+    A dialogue-gated standard emits **no** `integrated` key: `loudness_qc`
+    measures full-program via ebur128, and grading a dialogue-gated number
+    against a full-program measurement produces a pass/fail that means nothing.
+    The figure travels in `meta.dialogue_gated_integrated_lufs` for a human or a
+    properly gated meter, and only true peak is asserted.
+
+    No `lraMax` is emitted: no standard here mandates one. `meta.lra_advisory_lu`
+    carries the threshold above which a mix is worth a look, as advice.
+    """
+    standard = target.loudness
+    if standard is None:
+        return None
+    if not target.export_audio:
+        return None
+
+    assertions: Dict[str, Any] = {"truePeakMax": standard.true_peak_max_dbtp}
+    meta: Dict[str, Any] = {
+        "standard": standard.id,
+        "label": standard.label,
+        "source": standard.source,
+        "dialogue_gated": standard.dialogue_gated,
+        "lra_advisory_lu": LRA_ADVISORY_LU,
+    }
+
+    if standard.dialogue_gated:
+        meta["measurement_basis"] = "dialogue_gated"
+        meta["dialogue_gated_integrated_lufs"] = standard.integrated
+        meta["dialogue_gated_tolerance_lu"] = standard.tolerance_lu
+        meta["integrated_not_asserted_reason"] = (
+            "loudness_qc measures full-program loudness; this standard is measured over "
+            "dialogue only. Verify the integrated figure with a dialogue-gated meter — a "
+            "full-program pass or fail against it would not mean anything."
+        )
+    else:
+        meta["measurement_basis"] = "full_program"
+        assertions["integrated"] = standard.integrated
+        assertions["integratedTol"] = standard.tolerance_lu
+
+    if standard.lra_max is not None:
+        assertions["lraMax"] = standard.lra_max
+
+    return {"target": assertions, "meta": meta}
+
+
+def list_loudness_standards() -> Dict[str, Dict[str, Any]]:
+    """Introspection payload so an agent names a standard instead of inventing one."""
+    return {
+        standard.id: {
+            "id": standard.id,
+            "label": standard.label,
+            "integrated_lufs": standard.integrated,
+            "tolerance_lu": standard.tolerance_lu,
+            "true_peak_max_dbtp": standard.true_peak_max_dbtp,
+            "lra_max": standard.lra_max,
+            "dialogue_gated": standard.dialogue_gated,
+            "source": standard.source,
+        }
+        for standard in sorted(LOUDNESS_STANDARDS.values(), key=lambda s: s.id)
+    }
+
+
 # ── User overrides ──────────────────────────────────────────────────────────
 
 

package/src/utils/edit_engine.py

@@ -32,6 +32,7 @@ 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
+from src.utils import transcript_edit as _transcript_edit_mod
 
 PLAN_DIR_NAME = "edit_plans"
 DEFAULT_HANDLE_SECONDS = 0.25
@@ -623,7 +624,7 @@ def plan_silence_ripple(
     items: Sequence[Dict[str, Any]],
     timeline_name: str,
     timeline_fps: float,
-    threshold_db: float = DEFAULT_SILENCE_THRESHOLD_DB,
+    threshold_db: Optional[float] = None,
     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,
@@ -710,17 +711,39 @@ def plan_silence_ripple(
                 ),
             }
 
+        # An explicit threshold is honoured as given; omitting it calibrates the
+        # gate from this slice's own dynamics. An unusable calibration means no
+        # threshold suits this material — keep the item whole rather than strip
+        # it against a gate that was never validated against the audio.
+        item_threshold = threshold_db
+        calibration = None
+        if item_threshold is None:
+            calibration = _silence_ripple_mod.calibrate_silence_gate(
+                media_path, src_start_sec, src_end_sec
+            )
+            spec["calibration"] = calibration.as_dict()
+            if not calibration.usable:
+                skipped.append({
+                    "item": item.get("item_name"),
+                    "reason": f"silence gate could not be calibrated — kept whole: {calibration.reason}",
+                    "calibration": calibration.as_dict(),
+                })
+                item_specs.append(spec)
+                continue
+            item_threshold = calibration.gate_db
+
         strip_regions, keep_segments = _silence_ripple_mod.plan_item_silence_strips(
             media_path,
             src_start_sec,
             src_end_sec,
-            threshold_db=float(threshold_db),
+            threshold_db=float(item_threshold),
             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
+        spec["threshold_db"] = float(item_threshold)
         item_specs.append(spec)
 
         for strip_start, strip_end in strip_regions:
@@ -739,11 +762,13 @@ def plan_silence_ripple(
                 "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)."
+                    f"(threshold {round(float(item_threshold), 1)} dB, min {min_strip_frames} frames)."
                 ),
                 "evidence": {
                     "basis": "ffmpeg_silencedetect",
-                    "threshold_db": threshold_db,
+                    "threshold_db": round(float(item_threshold), 2),
+                    "threshold_source": "explicit" if threshold_db is not None else "calibrated",
+                    "calibration": spec.get("calibration"),
                     "source_gap_seconds": [round(strip_start, 3), round(strip_end, 3)],
                 },
             })
@@ -755,10 +780,16 @@ def plan_silence_ripple(
             "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)."
+                f"threshold_db={'auto-calibrated per item' if threshold_db is None else threshold_db}, "
+                f"min_strip_frames={min_strip_frames}; items without readable file paths carry no "
+                "waveform evidence, and items whose gate could not be calibrated were kept whole "
+                "rather than stripped against an unvalidated threshold (both — see skipped)."
             ),
+            "calibrations": [
+                {"item": s["item"].get("item_name"), **s["calibration"]}
+                for s in item_specs
+                if s.get("calibration")
+            ],
         }
 
     lifts.sort(key=lambda l: -l["timeline_start_frame"])
@@ -810,11 +841,17 @@ def plan_silence_ripple(
         ),
         "settings": {
             "threshold_db": threshold_db,
+            "threshold_source": "explicit" if threshold_db is not None else "calibrated_per_item",
             "min_strip_frames": min_strip_frames,
             "pre_head_frames": pre_head_frames,
             "post_tail_frames": post_tail_frames,
             "include_audio": bool(include_audio),
         },
+        "calibrations": [
+            {"item": s["item"].get("item_name"), **s["calibration"]}
+            for s in item_specs
+            if s.get("calibration")
+        ],
     })
     result = {
         "success": True,
@@ -1020,3 +1057,140 @@ def plan_swap(
             "version-archived timeline (lift + positioned append, same slot)."
         ),
     }
+
+
+# ── transcript-driven editing (word level) ───────────────────────────────────
+
+
+def plan_transcript_tighten(
+    project_root: str,
+    *,
+    clip_ref: Any,
+    remove_fillers: bool = True,
+    remove_false_starts: bool = True,
+    collapse_pauses: bool = True,
+    max_pause: float = _transcript_edit_mod.DEFAULT_MAX_PAUSE_S,
+    handle: float = _transcript_edit_mod.DEFAULT_HANDLE_S,
+    min_cut: float = _transcript_edit_mod.DEFAULT_MIN_CUT_S,
+) -> Dict[str, Any]:
+    """Word-level tightening for one clip: fillers, false starts, long pauses.
+
+    Complementary to `plan_silence_ripple`, which is silence-driven and cannot
+    touch an audible "um" mid-phrase. Emits `keep_ranges` in the same shape, so
+    the existing variant assembler consumes either without changes.
+    """
+    from src.utils import strata as _strata
+
+    conn, clip, err = _strata.resolve_clip(project_root, clip_ref, require_media=False)
+    if err:
+        return {"success": False, **err}
+    words = _strata.read_words(conn, clip["clip_uuid"])
+    if not words:
+        return {
+            "success": False,
+            "error": "No transcript words for this clip.",
+            "remediation": (
+                "Run media_analysis transcription for the clip, then strata "
+                "backfill_transcript_words, before planning a word-level tighten."
+            ),
+            "clip": {"clip_uuid": clip["clip_uuid"], "clip_name": clip.get("clip_name")},
+        }
+    plan = _transcript_edit_mod.plan_transcript_cuts(
+        words,
+        remove_fillers=remove_fillers,
+        remove_false_starts=remove_false_starts,
+        collapse_pauses=collapse_pauses,
+        max_pause=max_pause,
+        handle=handle,
+        min_cut=min_cut,
+    )
+    plan["clip"] = {
+        "clip_uuid": clip["clip_uuid"],
+        "clip_name": clip.get("clip_name"),
+        "word_count": len(words),
+    }
+    plan["basis"] = "transcript_words"
+    return plan
+
+
+def search_spoken_content(
+    project_root: str,
+    *,
+    query: str,
+    mode: str = "phrase",
+    context_seconds: float = 1.5,
+    handle_seconds: float = 0.5,
+    max_hits: int = 200,
+) -> Dict[str, Any]:
+    """Search the spoken content of every transcribed clip; build selects.
+
+    A different axis from `find_similar`, which retrieves on semantic-visual
+    embedding. This finds *what was said*, which no embedding search surfaces
+    reliably, and returns hits in deterministic order (clip name, then time) so
+    two identical searches produce identical selects.
+    """
+    from src.utils import strata as _strata
+
+    conn = timeline_brain_db.connect(project_root)
+    rows = conn.execute(
+        "SELECT clip_uuid, clip_name, file_path FROM clips ORDER BY clip_name COLLATE NOCASE"
+    ).fetchall()
+    if not rows:
+        return {"success": False, "error": "No clips in the DB — analyze (or db_ingest) first."}
+
+    hits: List[Dict[str, Any]] = []
+    searched: List[str] = []
+    without_speech: List[Dict[str, str]] = []
+    for row in rows:
+        clip = dict(row)
+        words = _strata.read_words(conn, clip["clip_uuid"])
+        if not words:
+            without_speech.append({
+                "clip_uuid": clip["clip_uuid"],
+                "clip_name": clip.get("clip_name"),
+                "reason": "no transcript words",
+            })
+            continue
+        searched.append(clip.get("clip_name") or clip["clip_uuid"])
+        try:
+            found = _transcript_edit_mod.search_words(
+                words, query, mode=mode, context_seconds=context_seconds
+            )
+        except ValueError as exc:
+            return {"success": False, "error": str(exc)}
+        for hit in found:
+            hits.append({
+                **hit,
+                "clip_uuid": clip["clip_uuid"],
+                "clip_name": clip.get("clip_name"),
+                "file_path": clip.get("file_path"),
+            })
+
+    truncated = len(hits) > max_hits
+    hits = hits[:max_hits]
+    selects = [
+        {
+            "clip_uuid": hit["clip_uuid"],
+            "clip_name": hit["clip_name"],
+            "in_seconds": round(max(0.0, hit["start_seconds"] - handle_seconds), 3),
+            "out_seconds": round(hit["end_seconds"] + handle_seconds, 3),
+            "text": hit["text"],
+        }
+        for hit in hits
+    ]
+    return {
+        "success": True,
+        "query": query,
+        "mode": mode,
+        "hit_count": len(hits),
+        "truncated": truncated,
+        "hits": hits,
+        "selects": selects,
+        "handle_seconds": handle_seconds,
+        "clips_searched": searched,
+        "clips_without_speech": without_speech,
+        "note": (
+            "Proposal only — selects are in/out pairs in clip-relative seconds, ordered "
+            "by clip name then time so an identical search yields an identical list."
+        ),
+    }