davinci-resolve-mcp 2.68.1 → 2.69.0

package/src/utils/shot_assembly.py

@@ -0,0 +1,259 @@
+"""Assembly for footage that does not talk.
+
+Everything else in this codebase finds edit points in speech — word boundaries,
+pauses, fillers. Point that at motorsport, a music video, a live performance or
+an event recap and it does not degrade, it inverts: engine noise reads as
+content, a quiet straight reads as dead space, and the cuts land in all the
+wrong places. A viewer predicted exactly that before trying it, and he was
+right, because the tool was answering a question his footage never asked.
+
+Speechless footage has its own structure. Not words: **shots and motion**.
+
+- **Shot boundaries** are where the camera or the subject already changed. They
+  are the cut points the material is offering.
+- **Motion energy** says which of those shots is doing something, and where
+  inside a shot the action peaks or resolves.
+
+## What this does not do
+
+It does not decide what the sequence is *about*. Ranking shots by how much is
+moving in them is a measurement, not an edit — a static wide of a landscape may
+be the most important shot in the piece and will score last on every metric here.
+The output is a **string-out in a defensible order with the evidence attached**,
+which is what an assistant hands an editor, not a cut.
+
+## No-script mode
+
+The same machinery answers "I have no script, just footage." Cluster what is
+there, propose a structure, and **require approval before anything is cut** —
+which is what the tutorial author himself concluded after watching an agent
+freelance: handhold it, and do not let it cut without permission.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional, Sequence
+
+#: Shots shorter than this are almost always flash frames or transition
+#: artefacts rather than content, and putting them in a string-out is noise.
+MIN_USABLE_SECONDS = 0.5
+
+#: Motion energy below this reads as a locked-off or near-static shot. Static is
+#: not a defect — it is a fact about the shot, reported rather than penalised.
+STATIC_MOTION_THRESHOLD = 0.05
+
+#: Group boundary: a gap between shots larger than this suggests a different
+#: setup, location or time, so it starts a new cluster.
+CLUSTER_GAP_SECONDS = 30.0
+
+
+def _duration(shot: Mapping[str, Any]) -> float:
+    return max(0.0, float(shot.get("end_seconds", 0)) - float(shot.get("start_seconds", 0)))
+
+
+def rank_shots(shots: Sequence[Mapping[str, Any]]) -> Dict[str, Any]:
+    """Order shots by measurable activity, with the measurement attached.
+
+    Each shot: `{"name", "start_seconds", "end_seconds", "motion_energy"?}`.
+    `motion_energy` is 0-1; absent means unmeasured, which is reported as such
+    and never treated as zero — a shot nobody measured is not a static shot.
+    """
+    usable, rejected = [], []
+    for shot in shots:
+        duration = _duration(shot)
+        if duration < MIN_USABLE_SECONDS:
+            rejected.append({
+                "shot": shot.get("name"),
+                "reason": f"{duration:.2f}s — under the {MIN_USABLE_SECONDS}s floor; "
+                          "almost certainly a flash frame or transition artefact",
+            })
+            continue
+        motion = shot.get("motion_energy")
+        usable.append({
+            "shot": shot.get("name"),
+            "start_seconds": round(float(shot.get("start_seconds", 0)), 3),
+            "end_seconds": round(float(shot.get("end_seconds", 0)), 3),
+            "duration_seconds": round(duration, 3),
+            "motion_energy": round(float(motion), 4) if motion is not None else None,
+            "motion_measured": motion is not None,
+            "character": _character(motion, duration),
+        })
+    ranked = sorted(
+        usable,
+        key=lambda s: (s["motion_energy"] is None, -(s["motion_energy"] or 0.0), -s["duration_seconds"]),
+    )
+    for position, shot in enumerate(ranked, start=1):
+        shot["activity_rank"] = position
+    return {
+        "shots": ranked,
+        "rejected": rejected,
+        "unmeasured_count": sum(1 for s in ranked if not s["motion_measured"]),
+    }
+
+
+def _character(motion: Optional[float], duration: float) -> str:
+    if motion is None:
+        return "unmeasured — not the same as static"
+    if float(motion) < STATIC_MOTION_THRESHOLD:
+        return "static or locked off — a fact about the shot, not a fault"
+    if duration > 10:
+        return "sustained action"
+    return "action"
+
+
+def cluster_shots(
+    shots: Sequence[Mapping[str, Any]],
+    *,
+    gap_seconds: float = CLUSTER_GAP_SECONDS,
+) -> List[Dict[str, Any]]:
+    """Group shots into candidate sequences by temporal proximity.
+
+    A crude proxy for "these belong together" and labelled as one. Real grouping
+    is by content and intent; this groups by the clock, which correlates with
+    location and setup often enough to be a useful starting point and not often
+    enough to be trusted.
+    """
+    ordered = sorted(shots, key=lambda s: float(s.get("start_seconds", 0)))
+    clusters: List[Dict[str, Any]] = []
+    current: List[Mapping[str, Any]] = []
+    for shot in ordered:
+        if current and float(shot.get("start_seconds", 0)) - float(current[-1].get("end_seconds", 0)) > gap_seconds:
+            clusters.append(_close_cluster(current, len(clusters) + 1))
+            current = []
+        current.append(shot)
+    if current:
+        clusters.append(_close_cluster(current, len(clusters) + 1))
+    return clusters
+
+
+def _close_cluster(shots: Sequence[Mapping[str, Any]], index: int) -> Dict[str, Any]:
+    return {
+        "cluster": index,
+        "shot_count": len(shots),
+        "start_seconds": round(float(shots[0].get("start_seconds", 0)), 3),
+        "end_seconds": round(float(shots[-1].get("end_seconds", 0)), 3),
+        "shots": [s.get("name") for s in shots],
+    }
+
+
+def plan_string_out(
+    shots: Sequence[Mapping[str, Any]],
+    *,
+    order: str = "chronological",
+    gap_seconds: float = CLUSTER_GAP_SECONDS,
+) -> Dict[str, Any]:
+    """A reviewable string-out of speechless footage. Cuts nothing.
+
+    `order`: `chronological` (default — the safest, and what an assistant hands
+    over) or `activity` (most movement first, for finding the action in a long
+    unstructured shoot).
+    """
+    if order not in ("chronological", "activity"):
+        return {"success": False, "error": f"unknown order {order!r}; expected chronological or activity"}
+    if not shots:
+        return {"success": False, "error": "No shots supplied"}
+
+    ranked = rank_shots(shots)
+    if not ranked["shots"]:
+        return {
+            "success": False,
+            "error": "No shots long enough to use",
+            "rejected": ranked["rejected"],
+        }
+
+    sequence = (
+        sorted(ranked["shots"], key=lambda s: s["start_seconds"])
+        if order == "chronological" else ranked["shots"]
+    )
+    clusters = cluster_shots(shots, gap_seconds=gap_seconds)
+    total = sum(s["duration_seconds"] for s in sequence)
+
+    return {
+        "success": True,
+        "kind": "shot_string_out",
+        "order": order,
+        "shot_count": len(sequence),
+        "total_seconds": round(total, 2),
+        "sequence": sequence,
+        "clusters": clusters,
+        "rejected": ranked["rejected"],
+        "unmeasured_motion_count": ranked["unmeasured_count"],
+        "clustering_basis": (
+            f"temporal proximity, {gap_seconds:g}s gap — a PROXY for 'these belong "
+            "together'. Real grouping is by content and intent; this groups by the "
+            "clock, which tracks location and setup often enough to be useful and "
+            "not often enough to trust."
+        ),
+        "note": (
+            f"A string-out of {len(sequence)} shots in {order} order — **not a cut**. "
+            "Speechless footage is cut from shots and motion, not from silence: a "
+            "speech gate reads engine noise as content and a quiet straight as dead "
+            "space. Ranking by movement is a measurement, not an edit — a locked-off "
+            "wide may be the most important shot here and will rank last on every "
+            "metric. Decide the order yourself; this hands you the material with the "
+            "evidence attached."
+            + (f" {ranked['unmeasured_count']} shots have no motion measurement and "
+               "sit at the end — unmeasured is not static."
+               if ranked["unmeasured_count"] else "")
+        ),
+    }
+
+
+# ── no-script mode ───────────────────────────────────────────────────────────
+
+
+def propose_structure(
+    topics: Sequence[Mapping[str, Any]],
+    *,
+    min_topic_seconds: float = 5.0,
+) -> Dict[str, Any]:
+    """Propose an order for material that arrived without a script.
+
+    Each topic: `{"label", "total_seconds", "clip_count", "first_seconds"?}` —
+    typically the output of clustering transcript content.
+
+    **Requires approval and says so.** The tutorial that prompted this programme
+    ended with its author's own conclusion after watching an agent freelance:
+    handhold it, and do not let it cut without permission. A structure proposed
+    from clustering is a hypothesis about what the piece is, and that is the one
+    decision least safe to take silently.
+    """
+    if not topics:
+        return {"success": False, "error": "No topics supplied"}
+
+    usable, thin = [], []
+    for topic in topics:
+        seconds = float(topic.get("total_seconds") or 0.0)
+        record = {
+            "label": topic.get("label"),
+            "total_seconds": round(seconds, 2),
+            "clip_count": int(topic.get("clip_count") or 0),
+            "first_seconds": topic.get("first_seconds"),
+        }
+        (usable if seconds >= min_topic_seconds else thin).append(record)
+
+    ordered = sorted(usable, key=lambda t: -t["total_seconds"])
+    for position, topic in enumerate(ordered, start=1):
+        topic["proposed_position"] = position
+
+    return {
+        "success": True,
+        "kind": "proposed_structure",
+        "requires_approval": True,
+        "topic_count": len(ordered),
+        "proposed_order": ordered,
+        "thin_topics": thin,
+        "basis": (
+            "ordered by how much material each topic has — a measure of what was "
+            "SHOT, not of what matters. The most-covered subject is frequently not "
+            "the point of the piece."
+        ),
+        "note": (
+            f"{len(ordered)} topics proposed in coverage order. **This is a "
+            "hypothesis about what the piece is, and nothing is cut.** Approve, "
+            "reorder or discard it before any assembly — a structure inferred from "
+            "clustering is the single decision least safe to take silently."
+            + (f" {len(thin)} topics under {min_topic_seconds:g}s were set aside as "
+               "thin, not deleted." if thin else "")
+        ),
+    }

package/src/utils/silence_ripple.py

@@ -58,8 +58,33 @@ 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
+
+#: Guard bands around a removed silence. These are the difference between a cut
+#: that sounds clean and one that clips speech, and they were previously 0 and 1
+#: frame — effectively none.
+#:
+#: `apply_silence_handles` shrinks each detected silence [s, e] inward:
+#: `s + pre_head` and `e - post_tail`. Only what remains is removed. So:
+#:
+#: - **pre_head protects the OUTGOING word's decay.** `silencedetect` marks `s`
+#:   the moment amplitude falls below the gate, but a word's tail — and the room
+#:   reverb after it — stays audible below that gate. Stripping from `s` clips
+#:   the release and the cut sounds abrupt.
+#: - **post_tail protects the INCOMING word's onset.** `silencedetect` marks `e`
+#:   when amplitude rises back above the gate. A soft attack (s, f, th, or any
+#:   unstressed syllable) crosses the gate *later* than the word actually
+#:   begins, so `e` sits inside the word. Stripping up to `e` eats the attack.
+#:
+#: post_tail is the larger of the two because that asymmetry is the one users
+#: hear: reviewers of the first public tutorial for this project independently
+#: reported that "the first split seconds of your clips are trimmed so the audio
+#: is a bit cut off" — an eaten onset, produced by a one-frame onset guard.
+#:
+#: Frames, not milliseconds, to match Resolve's own handle model and the rest of
+#: this module's API. At 24 fps these are 83 ms and 167 ms; at 30 fps, 67 ms and
+#: 133 ms — both inside the range dialogue editors use by hand.
+DEFAULT_PRE_HEAD_FRAMES = 2
+DEFAULT_POST_TAIL_FRAMES = 4
 
 #: Where in the trough→peak bracket the gate sits. Above 0.5 deliberately: see
 #: the module docstring — silencedetect compares instantaneous amplitude while
@@ -73,6 +98,68 @@ DIGITAL_SILENCE_HEADROOM_DB = 24.0
 GATE_MIN_DB = -60.0
 GATE_MAX_DB = -24.0
 
+#: How aggressively to tighten. The default is deliberately the *loosest* one.
+#:
+#: Editorial practice is that a first assembly contains everything and tightens
+#: over successive passes — the first cut is supposed to be long. Tools default
+#: the other way because tight output demos better, and that is backwards for
+#: the person doing the work: trimming a generous assembly is fast and visible,
+#: while recovering material the machine already discarded is slow and, worse,
+#: invisible — you cannot review a cut that was never proposed.
+#:
+#: Each preset scales the guard bands and the minimum strip length. `generous`
+#: widens the guards and only removes long, unambiguous gaps. `tight` reproduces
+#: roughly the historical behaviour for anyone who wants it back.
+TIGHTNESS_PRESETS = {
+    "generous": {"guard_scale": 1.5, "min_strip_scale": 1.5},
+    "balanced": {"guard_scale": 1.0, "min_strip_scale": 1.0},
+    "tight": {"guard_scale": 0.5, "min_strip_scale": 0.6},
+}
+DEFAULT_TIGHTNESS = "generous"
+
+
+def resolve_tightness(tightness: Optional[str]) -> Tuple[str, dict]:
+    """Map a tightness name to its scaling factors.
+
+    Unknown names are an error rather than a silent fall-back to the default:
+    a caller asking for "aggressive" and quietly getting "generous" would be
+    told nothing and see cuts they did not ask for.
+    """
+    name = (tightness or DEFAULT_TIGHTNESS).strip().lower()
+    if name not in TIGHTNESS_PRESETS:
+        raise ValueError(
+            f"unknown tightness {tightness!r}; expected one of "
+            f"{', '.join(sorted(TIGHTNESS_PRESETS))}"
+        )
+    return name, dict(TIGHTNESS_PRESETS[name])
+
+
+def apply_tightness(
+    *,
+    tightness: Optional[str],
+    pre_head_frames: float,
+    post_tail_frames: float,
+    min_strip_frames: float,
+) -> dict:
+    """Scale guards and minimum strip length by the chosen tightness.
+
+    Guards are floored at the module defaults regardless of preset: `tight` is
+    allowed to remove more, never to start clipping speech again. That floor is
+    the whole point of the guard bands and is not a knob.
+    """
+    name, scales = resolve_tightness(tightness)
+    return {
+        "tightness": name,
+        "pre_head_frames": max(
+            DEFAULT_PRE_HEAD_FRAMES, pre_head_frames * scales["guard_scale"]
+        ),
+        "post_tail_frames": max(
+            DEFAULT_POST_TAIL_FRAMES, post_tail_frames * scales["guard_scale"]
+        ),
+        "min_strip_frames": max(1.0, min_strip_frames * scales["min_strip_scale"]),
+    }
+
+
 #: 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)

package/src/utils/sound_density.py

@@ -0,0 +1,253 @@
+"""The Law of Two-and-a-Half — how much sound an audience can actually follow.
+
+A long-standing observation in sound editing: an audience can follow roughly **two
+and a half simultaneous streams** of sound before the remainder stops being
+distinguishable and becomes texture. Past that point the mix is not richer, it
+is just louder — the extra elements are present, paid for, mixed, and not heard.
+
+This is the only principle in the classical set that is *fully* measurable, and
+nothing in this
+codebase touched sound as more than a track to mirror picture cuts onto.
+
+## The distinction that makes or breaks it
+
+The naive implementation counts active tracks and flags every mixed timeline in
+existence, because almost every finished sequence has music under dialogue under
+atmos. That tool is useless on its first run.
+
+The real question is not how many streams are *playing*, it is how many are
+**competing for the same attention**. A music bed sitting well under dialogue is
+one stream plus texture. Two overlapping voices at the same level are two
+streams, and adding a third is where the boundary bites.
+
+So each active stream at each moment is classified against the loudest one:
+
+- Within `BED_MARGIN_DB` of the loudest → **competitor**. Same attentional
+  foreground.
+- Further below → **bed**. Present, felt, not competing.
+
+That is a heuristic and it is stated as one. It is also the difference between a
+tool an editor uses twice and one they keep.
+
+## On the threshold
+
+Two-and-a-half is **an observation, not a measured constant**. It is a soft
+boundary that varies with material, mix and audience. It is a parameter here,
+and its provenance travels with every result — nobody should cite a number this
+module returns as though it were physics.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional, Sequence
+
+#: The two-and-a-half boundary. A soft observation, not a constant,
+#: and a parameter everywhere it is used.
+STREAM_LIMIT = 2.5
+
+#: A stream this far below the loudest active one reads as underneath it rather
+#: than alongside it — a bed, not a competitor. 12 dB is roughly the point where
+#: an element stops pulling focus and starts supporting.
+BED_MARGIN_DB = 12.0
+
+#: Below this a stream is not audibly present at all.
+AUDIBILITY_FLOOR_DB = -50.0
+
+#: Shortest overcrowded stretch worth reporting. A momentary pile-up on a hard
+#: effect is normal; a sustained one is a mix problem.
+MIN_CROWDED_SECONDS = 1.5
+
+
+def classify_moment(
+    levels: Mapping[str, float],
+    *,
+    bed_margin_db: float = BED_MARGIN_DB,
+    audibility_floor_db: float = AUDIBILITY_FLOOR_DB,
+) -> Dict[str, Any]:
+    """Split the streams audible at one moment into competitors and beds.
+
+    `levels` maps a stream name to its level in dBFS at this moment.
+    """
+    audible = {k: float(v) for k, v in levels.items() if float(v) > audibility_floor_db}
+    if not audible:
+        return {"competitors": [], "beds": [], "silent": True, "loudest_db": None}
+    loudest = max(audible.values())
+    competitors, beds = [], []
+    for name, level in sorted(audible.items(), key=lambda kv: -kv[1]):
+        (competitors if level >= loudest - bed_margin_db else beds).append(
+            {"stream": name, "level_db": round(level, 1)}
+        )
+    return {
+        "competitors": competitors,
+        "beds": beds,
+        "silent": False,
+        "loudest_db": round(loudest, 1),
+    }
+
+
+def audit(
+    samples: Sequence[Mapping[str, Any]],
+    *,
+    stream_limit: float = STREAM_LIMIT,
+    bed_margin_db: float = BED_MARGIN_DB,
+    min_crowded_seconds: float = MIN_CROWDED_SECONDS,
+) -> Dict[str, Any]:
+    """Report attentional density over time.
+
+    `samples`: `[{"time_seconds": float, "levels": {stream: dBFS}}, ...]`,
+    ordered. Kept as plain numbers so the analysis is testable without decoding
+    audio.
+    """
+    if not samples:
+        return {"success": False, "error": "No audio samples supplied"}
+
+    curve: List[Dict[str, Any]] = []
+    for sample in samples:
+        moment = classify_moment(
+            sample.get("levels") or {}, bed_margin_db=bed_margin_db
+        )
+        curve.append({
+            "time_seconds": round(float(sample.get("time_seconds") or 0.0), 3),
+            "competitors": len(moment["competitors"]),
+            "beds": len(moment["beds"]),
+            "competing_streams": [c["stream"] for c in moment["competitors"]],
+            "bed_streams": [b["stream"] for b in moment["beds"]],
+        })
+
+    # Contiguous stretches over the limit.
+    crowded: List[Dict[str, Any]] = []
+    run_start: Optional[float] = None
+    run_peak = 0
+    for index, point in enumerate(curve):
+        over = point["competitors"] > stream_limit
+        if over and run_start is None:
+            run_start, run_peak = point["time_seconds"], point["competitors"]
+        elif over:
+            run_peak = max(run_peak, point["competitors"])
+        elif run_start is not None:
+            _close_run(crowded, run_start, point["time_seconds"], run_peak, min_crowded_seconds)
+            run_start, run_peak = None, 0
+    if run_start is not None:
+        _close_run(crowded, run_start, curve[-1]["time_seconds"], run_peak, min_crowded_seconds)
+
+    peak = max((p["competitors"] for p in curve), default=0)
+    findings = [{
+        "criterion": "rhythm",
+        "scope": "scene",
+        "at": run["start_seconds"],
+        "summary": (
+            f"{run['peak_competitors']} sounds competing for "
+            f"{run['duration_seconds']}s"
+        ),
+        "detail": (
+            f"From {run['start_seconds']}s to {run['end_seconds']}s, up to "
+            f"{run['peak_competitors']} streams sit within {bed_margin_db:.0f} dB of "
+            "each other, so they are all asking for the same attention. An audience "
+            "follows about two and a half streams at once; past that the extra elements "
+            "are mixed, paid for, and not heard. Either duck something or lose it."
+        ),
+    } for run in crowded]
+
+    return {
+        "success": True,
+        "kind": "sound_density_audit",
+        "sample_count": len(curve),
+        "peak_competitors": peak,
+        "stream_limit": stream_limit,
+        "crowded_stretch_count": len(crowded),
+        "crowded_stretches": crowded,
+        "density_curve": curve,
+        "findings": findings,
+        "threshold_provenance": (
+            f"{stream_limit} comes from a long-standing observation in sound editing "
+            "about how many simultaneous streams an audience can follow. It is NOT a "
+            "measured constant — it is a soft boundary that moves with material, mix and "
+            "audience, and it is a parameter here. Do not cite it as physics."
+        ),
+        "method": (
+            f"A stream within {bed_margin_db:.0f} dB of the loudest active one counts as "
+            "competing; anything further under counts as a bed. That is what stops a "
+            "music bed under dialogue reading as two competitors — it is one stream "
+            "plus texture. Heuristic, and deliberately so."
+        ),
+        "note": (
+            f"Peak of {peak} competing streams across {len(curve)} samples; "
+            + (f"{len(crowded)} stretches over the limit." if crowded
+               else "nothing sustained over the limit.")
+        ),
+    }
+
+
+def _close_run(
+    out: List[Dict[str, Any]], start: float, end: float, peak: int, minimum: float
+) -> None:
+    duration = end - start
+    if duration >= minimum:
+        out.append({
+            "start_seconds": round(start, 2),
+            "end_seconds": round(end, 2),
+            "duration_seconds": round(duration, 2),
+            "peak_competitors": peak,
+        })
+
+
+def measure_track_levels(
+    media_paths: Mapping[str, str],
+    *,
+    window_seconds: float = 0.5,
+    duration_seconds: Optional[float] = None,
+) -> Dict[str, Any]:
+    """Sample per-stream levels from files via ffmpeg. Honest-refuses if absent.
+
+    Separated from the analysis so the classification above stays testable
+    without decoding audio.
+    """
+    import shutil
+    import subprocess
+
+    if not shutil.which("ffmpeg"):
+        return {"success": False, "error": "ffmpeg not found on PATH — cannot measure levels"}
+    try:
+        import numpy as np
+    except Exception:
+        return {"success": False, "error": "numpy is required", "remediation": "pip install numpy"}
+
+    rate = 8000  # plenty for an energy envelope
+    per_stream: Dict[str, Any] = {}
+    length = 0
+    for name, path in media_paths.items():
+        cmd = ["ffmpeg", "-v", "error", "-i", path, "-vn", "-ac", "1",
+               "-ar", str(rate), "-f", "f32le", "-"]
+        if duration_seconds:
+            cmd[4:4] = ["-t", str(duration_seconds)]
+        try:
+            proc = subprocess.run(cmd, capture_output=True, timeout=120)
+        except (subprocess.SubprocessError, OSError) as exc:
+            return {"success": False, "error": f"decode failed for {name}: {exc}"}
+        if proc.returncode != 0 or not proc.stdout:
+            return {
+                "success": False,
+                "error": (proc.stderr or b"").decode("utf-8", "replace").strip()
+                         or f"no audio decoded from {name}",
+            }
+        signal = np.frombuffer(proc.stdout, dtype="<f4")
+        step = max(1, int(rate * window_seconds))
+        windows = signal[: len(signal) // step * step].reshape(-1, step)
+        rms = np.sqrt((windows.astype("float64") ** 2).mean(axis=1))
+        with np.errstate(divide="ignore"):
+            db = 20.0 * np.log10(np.maximum(rms, 1e-9))
+        per_stream[name] = db
+        length = max(length, len(db))
+
+    samples = [
+        {
+            "time_seconds": index * window_seconds,
+            "levels": {
+                name: float(values[index])
+                for name, values in per_stream.items()
+                if index < len(values)
+            },
+        }
+        for index in range(length)
+    ]
+    return {"success": True, "samples": samples, "window_seconds": window_seconds}