wizz-method 2.11.2 → 2.13.0

package/src/skills-lib/wizz-video-effects/scripts/fill_breaths.py

@@ -0,0 +1,355 @@
+# -*- coding: utf-8 -*-
+"""Anchor effects in the real breaths of the speech.
+
+Why it exists. A generator that picks transitions by position left pieces
+with 6s+ holes without any event and identical transition sequences. The
+right rhythm is already in the audio: in the worst measured hole there were
+six breaths spaced 2.4 to 2.9s apart, exactly the cadence vertical video asks
+for. This script reads those breaths and uses them as anchors.
+
+The breath says WHEN, the screen says WHAT: where the frame has room at the
+edges a `punch` (scale, the strongest effect) fits; where content is glued to
+the safe zone edge the punch would push it out at its peak
+(breaths.punch_peak_scale), so a `flash` (opacity only) takes the breath.
+Refusing the breath would waste the one place where an effect fits without
+stepping on speech. Without --visual every breath is treated as a flash.
+
+Holes are closed from the widest down, never past the budget of the chosen
+kind (budget.ceiling) nor its gap_min, and never wider than budget.burst_gap_s.
+Every new punch asks for a sound (breaths.punch_sound_event), evaluated
+TOGETHER with the sounds already in the timeline. Scene transitions and cut
+sounds follow the pace of speech in each scene (breaths.pace_profiles).
+
+Breath source: --narration FILE[@OFFSET] (ffmpeg silencedetect with
+breaths.silence_db / breaths.min_silence_s), otherwise the gaps between
+words[] (ctc-align output, in the timeline or via --words).
+
+Deterministic: same input, same output. Runs after the timeline is generated
+and before render; it reports only unless --write or --out is given.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+import sound
+import timeline as tl
+from check_safe_zone import ReadError, content_rows, read_frame
+from config import Config, ConfigError, SafeZone, add_config_arg, load
+
+# ---------------------------------------------------------------- breath sources
+
+
+def breaths_from_audio(path: Path, cfg: Config) -> list[tuple[float, float]]:
+    """(start, end) silence windows in an audio file."""
+    b = cfg.breaths
+    out = subprocess.run(
+        ["ffmpeg", "-hide_banner", "-i", str(path), "-af",
+         f"silencedetect=n={b.silence_db:g}dB:d={b.min_silence_s:g}", "-f", "null", "-"],
+        capture_output=True, text=True).stderr
+    starts = [float(x) for x in re.findall(r"silence_start: (-?[\d.]+)", out)]
+    ends = [float(x) for x in re.findall(r"silence_end: (-?[\d.]+)", out)]
+    return list(zip(starts, ends))
+
+
+def breaths_from_words(words: list[dict], cfg: Config) -> list[tuple[float, float]]:
+    """Gaps between consecutive words at least breaths.min_silence_s long."""
+    ws = sorted(words, key=lambda w: float(w["start"]))
+    return [(float(a["end"]), float(b["start"])) for a, b in zip(ws, ws[1:])
+            if float(b["start"]) - float(a["end"]) >= cfg.breaths.min_silence_s]
+
+
+def candidates_from(breaths: list[tuple[float, float]], offset: float, total: float,
+                    cfg: Config) -> list[float]:
+    """Middle of each breath (never glued to a word), inside the edge guard."""
+    g = cfg.breaths.edge_guard_s
+    mids = (round(offset + (a + b) / 2, 3) for a, b in breaths)
+    return sorted(t for t in mids if g < t < total - g)
+
+
+# ------------------------------------------------------------ punch or flash
+
+
+def punch_band(zone: SafeZone, cfg: Config) -> tuple[int, int]:
+    """(min top row, max bottom row) content may occupy so that a punch at
+    breaths.punch_peak_scale, scaling around the frame centre, stays inside."""
+    c, k = cfg.frame.height / 2.0, cfg.breaths.punch_peak_scale
+    return math.ceil(c - (c - zone.top) / k), math.floor(c + (zone.bottom - c) / k)
+
+
+def effect_for_frame(frame: bytes, zone: SafeZone, cfg: Config) -> str:
+    """'punch' when the content fits the punch band, else 'flash'. Measured
+    exactly like the safe-zone gate: measuring differently would approve what
+    the gate fails."""
+    g = cfg.safe_zone_gate
+    rows = content_rows(frame, g.sample_width, cfg.frame.height, g.dp_min, g.edge_artifact_rows)
+    if not rows:
+        return "punch"
+    top, bottom = punch_band(zone, cfg)
+    return "punch" if rows[0][0] >= top and rows[-1][0] <= bottom else "flash"
+
+
+# -------------------------------------------------------------- hole filling
+
+
+def _holes(line: list[float], burst: float, skip: set) -> list[tuple[float, float, float]]:
+    return sorted(((b - a, a, b) for a, b in zip(line, line[1:])
+                   if b - a > burst and (a, b) not in skip), reverse=True)
+
+
+def _has_budget(t, effect_of, used, ceilings) -> bool:
+    kind = "punch" if effect_of.get(t) == "punch" else "flash"
+    return used[kind] < ceilings[kind]
+
+
+def fill_holes(candidates: list[float], existing: list[float], effect_of: dict[float, str],
+               total: float, punches: list[float], flashes: list[float], cfg: Config):
+    """Close holes wider than budget.burst_gap_s with breaths, widest first,
+    re-evaluated after each pick (a split hole may still be too wide).
+
+    Returns (new, no_breath, no_budget, stopped_at_punch_ceiling):
+      new            chosen instants, in decision order
+      no_breath      holes (a, b) where speech does not breathe
+      no_budget      holes that breathe but whose kinds ran out of budget
+      stopped...     (n, ceiling) the first time a punch was left out by the
+                     ceiling (not by gap), or None
+    """
+    rule = cfg.budget.rule("punch")
+    if rule is None:
+        raise ConfigError("budget.per_effect has no rule for 'punch'")
+    gap, burst = rule.gap_min, cfg.budget.burst_gap_s
+    ceilings = {"punch": cfg.budget.ceiling("punch", total),
+                "flash": cfg.budget.ceiling("flash", total)}
+    used = {"punch": len(punches), "flash": len(flashes)}
+    new: list[float] = []
+    no_breath, no_budget, stopped = set(), set(), None
+    while True:
+        holes = _holes(sorted(set(existing + new + [0.0, total])), burst, no_breath | no_budget)
+        if not holes:
+            break
+        _, a, b = holes[0]
+        inside = [t for t in candidates if t not in new and a + gap <= t <= b - gap]
+        if not inside:
+            no_breath.add((a, b))
+            continue
+        funded = [t for t in inside if _has_budget(t, effect_of, used, ceilings)]
+        if not funded:
+            no_budget.add((a, b))
+            if stopped is None and used["punch"] >= ceilings["punch"] \
+                    and any(effect_of.get(t) == "punch" for t in inside):
+                stopped = (used["punch"], ceilings["punch"])
+            continue
+        pick = min(funded, key=lambda t: abs(t - (a + b) / 2))
+        new.append(pick)
+        used["punch" if effect_of.get(pick) == "punch" else "flash"] += 1
+    return new, no_breath, no_budget, stopped
+
+
+# -------------------------------------------------------------------- sounds
+
+
+event_of = sound.event_of  # kept here for callers of the old location
+
+
+def request_punch_sounds(new_punches: list[float], existing: list[dict], cfg: Config):
+    """One `breaths.punch_sound_event` request per new punch (a mute punch is
+    half a punch), mapped TOGETHER with the sounds already there, so a new
+    request cannot slip past a collision or a same-sound run.
+
+    Returns (new_shots, new_refusals, unrecoverable, displaced):
+      unrecoverable  existing entries whose event cannot be rebuilt (left out
+                     of the joint evaluation, reported)
+      displaced      existing instants the joint evaluation would no longer
+                     accept; they are reported, never rewritten silently
+    """
+    old, unrecoverable = [], []
+    for e in existing:
+        ev = event_of(e, cfg)
+        if ev:
+            old.append((float(e["at"]), ev))
+        else:
+            unrecoverable.append(e)
+    req = [(t, cfg.breaths.punch_sound_event) for t in new_punches]
+    res = sound.map_requests(old + req, cfg)
+    by_t = {s.t: s for s in res.shots}
+    displaced = sorted({t for t, _ in old} - set(by_t))
+    shots = [by_t[t] for t in new_punches if t in by_t]
+    news = set(new_punches)
+    return shots, [r for r in res.refusals if r.t in news], unrecoverable, displaced
+
+
+# ---------------------------------------------------------------- scene pace
+
+
+def words_per_second(words: list[dict], start: float, end: float) -> float:
+    n = sum(1 for w in words if start <= float(w["start"]) < end)
+    return n / (end - start) if end > start else 0.0
+
+
+def pace_profile(index: int, wps: float, cfg: Config) -> str:
+    """'first' for the opening scene (a direct entry, nothing competing with
+    the hook), then 'fast' for burst speech, 'slow' for dragging speech."""
+    if index == 0:
+        return "first"
+    return "fast" if wps >= cfg.breaths.fast_speech_wps else "slow"
+
+
+def scene_updates(scenes: list[dict], words: list[dict], cfg: Config) -> list[tuple[dict, float]]:
+    """(new scene dict, words per second) with transition and cut sound by pace."""
+    out = []
+    for i, sc in enumerate(scenes):
+        start = float(sc["start"])
+        wps = words_per_second(words, start, start + float(sc.get("dur", 0.0)))
+        prof = cfg.breaths.pace_profiles[pace_profile(i, wps, cfg)]
+        ev = cfg.sound.event(prof.sound_event)
+        out.append(({**sc, "transition": prof.transition,
+                    "sfx": {"event": prof.sound_event, "src": cfg.sound.src(prof.sound_event),
+                            "vol": ev.vol}}, round(wps, 2)))
+    return out
+
+
+# ------------------------------------------------------------------ pipeline
+
+
+def _narration_breaths(specs: list[str], cfg: Config, total: float) -> list[float]:
+    """Candidates from --narration FILE[@OFFSET] entries."""
+    out: list[float] = []
+    for spec in specs:
+        path, _, off = spec.partition("@")
+        p = Path(path)
+        if not p.exists():
+            raise ReadError(f"narration not found: {p}")
+        out += candidates_from(breaths_from_audio(p, cfg), float(off or 0.0), total, cfg)
+    return sorted(set(out))
+
+
+def _effects_by_frame(cands: list[float], visual: str | None, zone: SafeZone,
+                      cfg: Config) -> dict[float, str]:
+    if not visual:
+        return {t: "flash" for t in cands}
+    w, h = cfg.safe_zone_gate.sample_width, cfg.frame.height
+    return {t: effect_for_frame(read_frame(visual, t, w, h), zone, cfg) for t in cands}
+
+
+def plan(data: dict, cfg: Config, cands: list[float], effect_of: dict[float, str]) -> dict:
+    """Everything the script would change, as a report dict (pure)."""
+    total, _ = tl.duration(data)
+    words = data.get("words") or []
+    scenes = scene_updates(data.get("scenes") or [], words, cfg)
+    punches = tl.instants(data.get("punches"))
+    flashes = tl.instants(data.get("flashes"))
+    existing = sorted(punches + flashes + tl.instants(data.get("shakes"))
+                      + tl.instants(data.get("interrupts"))
+                      + [float(sc["start"]) for sc, _ in scenes])
+    new, no_breath, no_budget, stopped = fill_holes(
+        cands, existing, effect_of, total, punches, flashes, cfg)
+    new_p = sorted(t for t in new if effect_of.get(t) == "punch")
+    new_f = sorted(t for t in new if effect_of.get(t) != "punch")
+    after = {**data, "scenes": [sc for sc, _ in scenes]}
+    shots, refused, unrec, displaced = request_punch_sounds(new_p, tl.sounds(after), cfg)
+    return {"total": total, "candidates": cands, "existing": existing, "scenes": scenes,
+            "new_punches": new_p, "new_flashes": new_f, "shots": shots, "refused": refused,
+            "unrecoverable": unrec, "displaced": displaced, "stopped": stopped,
+            "no_breath": sorted(no_breath), "no_budget": sorted(no_budget)}
+
+
+def apply(data: dict, p: dict) -> dict:
+    """The new timeline (a new dict; the input is not mutated)."""
+    extra = [{"at": round(s.t, 3), "event": s.event, "src": s.src, "vol": s.vol}
+             for s in p["shots"]]
+    return {**data,
+            "scenes": [sc for sc, _ in p["scenes"]],
+            "punches": sorted(set(tl.instants(data.get("punches")) + p["new_punches"])),
+            "flashes": sorted(set(tl.instants(data.get("flashes")) + p["new_flashes"])),
+            "sfx": sorted(list(data.get("sfx") or []) + extra, key=lambda s: float(s["at"]))}
+
+
+def _largest_hole(events: list[float], total: float) -> float:
+    ev = sorted(set(events + [0.0, total]))
+    return max((b - a for a, b in zip(ev, ev[1:])), default=0.0)
+
+
+def print_plan(name: str, p: dict) -> None:
+    total, ex = p["total"], p["existing"]
+    new = p["new_punches"] + p["new_flashes"]
+    print(f"== {name} ==  {total:.1f}s, {len(p['scenes'])} scenes")
+    print(f"  breaths found        : {len(p['candidates'])}")
+    print(f"  new events           : {len(new)}   punch={p['new_punches']}   flash={p['new_flashes']}")
+    print(f"  largest hole         : {_largest_hole(ex, total):.1f}s -> "
+          f"{_largest_hole(ex + new, total):.1f}s")
+    print(f"  punch sounds         : asked={len(p['new_punches'])} accepted={len(p['shots'])} "
+          f"refused={len(p['refused'])}")
+    for r in p["refused"]:
+        print(f"    t={r.t:.2f}s [{r.rule}] {r.detail}")
+    if p["unrecoverable"]:
+        print(f"  warning: {len(p['unrecoverable'])} existing sound(s) without a rebuildable "
+              f"event were left out of the joint sound evaluation")
+    if p["displaced"]:
+        print(f"  warning: {len(p['displaced'])} existing sound(s) would no longer be accepted "
+              f"jointly; they were not touched: {p['displaced']}")
+    if p["stopped"]:
+        print(f"  stopped at {p['stopped'][0]} punches, ceiling is {p['stopped'][1]}")
+    if p["no_breath"]:
+        print("  holes without breath : " + ", ".join(f"{a:.1f}-{b:.1f}s" for a, b in p["no_breath"])
+              + "   <- look at the script, not the edit")
+    if p["no_budget"]:
+        print("  holes without budget : " + ", ".join(f"{a:.1f}-{b:.1f}s" for a, b in p["no_budget"]))
+    for sc, wps in p["scenes"]:
+        print(f"  scene at {float(sc['start']):6.2f}s: {sc['transition']:5} + "
+              f"{sc['sfx']['event']}   ({wps} words/s)")
+
+
+def _parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(description="Anchor punches and flashes in the breaths of speech.")
+    add_config_arg(ap)
+    ap.add_argument("timeline", help="timeline JSON (see references/data-contract.md)")
+    ap.add_argument("--narration", action="append", default=[], metavar="FILE[@OFFSET]",
+                    help="narration audio, optionally with its start in the piece (s); repeatable")
+    ap.add_argument("--words", help="ctc-align words JSON (default: timeline words[])")
+    ap.add_argument("--visual", help="mute visual render, to choose punch vs flash per breath")
+    ap.add_argument("--profile", help="safe zone profile (default: timeline, then config)")
+    out = ap.add_mutually_exclusive_group()
+    out.add_argument("--write", action="store_true", help="rewrite the timeline in place")
+    out.add_argument("--out", help="write the new timeline to this path")
+    return ap
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        cfg = load(args.config)
+        data = tl.load(args.timeline)
+        if args.words:
+            data = {**data, "words": json.loads(Path(args.words).read_text(encoding="utf-8"))}
+        total, _ = tl.duration(data)
+        if args.narration:
+            cands = _narration_breaths(args.narration, cfg, total)
+        elif data.get("words"):
+            cands = candidates_from(breaths_from_words(data["words"], cfg), 0.0, total, cfg)
+        else:
+            print("ERROR: no breath source: pass --narration, --words or put words[] in the timeline")
+            return 2
+        zone = cfg.safe_zone(args.profile or data.get("safe_zone_profile"))
+        if not args.visual:
+            print("  note: no --visual, every breath is treated as a flash")
+        p = plan(data, cfg, cands, _effects_by_frame(cands, args.visual, zone, cfg))
+    except (ConfigError, tl.TimelineError, ReadError) as e:
+        print(f"ERROR: {e}")
+        return 2
+    print_plan(Path(args.timeline).stem, p)
+    target = args.timeline if args.write else args.out
+    if target:
+        tl.save(target, apply(data, p))
+        print(f"  written: {target}")
+    else:
+        print("  (report only; use --write or --out to apply)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/skills-lib/wizz-video-effects/scripts/measure_density.py

@@ -0,0 +1,122 @@
+# -*- coding: utf-8 -*-
+"""DENSITY gate: is the frame full enough, measured on the FINAL MP4.
+
+The area between the active safe zone top and bottom is split into
+density.n_bands uniform bands; at every density.step_s a band counts as
+filled when its local contrast (std-dev of luma, sampled at
+density.sample_width columns) reaches density.dp_min. The piece fails where
+fewer than density.min_filled bands are filled.
+
+Traps already paid for:
+    - Measuring max brightness instead of occupancy: one line of white text
+      passes a max with the screen 90% black.
+    - A brightness threshold instead of contrast: a dark card (luma 21) and
+      the background glow (luma 22) overlap, no absolute threshold separates
+      them. Contrast does.
+    - The sample at t=0.0 is skipped: it is the first frame, before any entry
+      animation began. A piece that really opens black still fails at t=step.
+    - Samples that cannot be read are an error, never skipped silently (a
+      file measured while the render was still writing it once returned a
+      plausible number over a third of the film).
+
+Exit code: 0 pass, 1 fail, 2 file unreadable.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+
+from check_safe_zone import ReadError, read_frame, resolve_profile, row_std
+from config import Config, ConfigError, SafeZone, add_config_arg, load
+import timeline as tl
+
+
+def duration(video: str) -> float:
+    o = subprocess.run(["ffprobe", "-v", "error", "-show_entries", "format=duration",
+                        "-of", "default=nw=1:nk=1", video], capture_output=True, text=True)
+    try:
+        return float(o.stdout.strip())
+    except ValueError as e:
+        raise ReadError(f"ffprobe could not read the duration of {video}") from e
+
+
+def filled_bands(frame: bytes, bands: list[tuple[int, int]], width: int, dp_min: float) -> int:
+    return sum(1 for y0, y1 in bands if row_std(frame[y0 * width:y1 * width]) >= dp_min)
+
+
+def group_runs(poor: list[tuple[float, int]], step: float) -> list[tuple[float, float]]:
+    """Contiguous poor samples as (first, last) runs: what the viewer sees."""
+    if not poor:
+        return []
+    runs, start, prev = [], poor[0][0], poor[0][0]
+    for t, _ in poor[1:]:
+        if t - prev > step + 0.01:
+            runs.append((start, prev))
+            start = t
+        prev = t
+    runs.append((start, prev))
+    return runs
+
+
+def sample(video: str, cfg: Config, zone: SafeZone):
+    """(history [(t, filled)], unread count) over the whole video."""
+    d = cfg.density
+    total = duration(video)
+    bands = d.bands(zone.top, zone.bottom)
+    hist, unread, t = [], 0, d.step_s   # t=0.0 skipped on purpose (see docstring)
+    while t < total:
+        frame = read_frame(video, t, d.sample_width, cfg.frame.height)
+        if len(frame) >= d.sample_width * cfg.frame.height:
+            hist.append((round(t, 2), filled_bands(frame, bands, d.sample_width, d.dp_min)))
+        elif t < total - d.step_s:
+            # The last sample can land a few ms before the end with no frame to
+            # give: rounding, not a broken file. Only earlier gaps count.
+            unread += 1
+        t = round(t + d.step_s, 2)
+    return total, hist, unread
+
+
+def report(video: str, cfg: Config, zone: SafeZone) -> int:
+    d = cfg.density
+    total, hist, unread = sample(video, cfg, zone)
+    name = os.path.basename(video)
+    if unread:
+        print(f"{name}: {unread} of {unread + len(hist)} samples could NOT be read.")
+        print("  The file may still be written by the render, or truncated. Measure again.")
+        return 2
+    mean = sum(c for _, c in hist) / len(hist) if hist else 0.0
+    print(f"{name}: {total:.1f}s, {len(hist)} samples, profile '{zone.name}'")
+    print(f"  mean {mean:.1f} of {d.n_bands} bands filled (minimum density.min_filled={d.min_filled})")
+    poor = [(t, c) for t, c in hist if c < d.min_filled]
+    if not poor:
+        print(f"  ok: no instant below {d.min_filled}/{d.n_bands}")
+        return 0
+    runs = group_runs(poor, d.step_s)
+    secs = sum(b - a + d.step_s for a, b in runs)
+    print(f"  BELOW {d.min_filled}/{d.n_bands} in {len(runs)} run(s), {secs:.1f}s "
+          f"({100.0 * secs / total:.0f}% of the piece):")
+    for a, b in runs:
+        worst = min(c for t, c in poor if a <= t <= b)
+        print(f"     {a:5.1f}s -> {b + d.step_s:5.1f}s  worst: {worst}/{d.n_bands}")
+    return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Density gate: bands with content on the final MP4.")
+    add_config_arg(ap)
+    ap.add_argument("video", help="final MP4 (with actor and captions, not the mute render)")
+    ap.add_argument("--profile", help="safe zone profile the bands span (default: config)")
+    ap.add_argument("--timeline", help="timeline JSON whose safe_zone_profile applies")
+    args = ap.parse_args(argv)
+    try:
+        cfg = load(args.config)
+        return report(args.video, cfg, resolve_profile(cfg, args.profile, args.timeline))
+    except (ConfigError, tl.TimelineError, ReadError) as e:
+        print(f"ERROR: {e}")
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/skills-lib/wizz-video-effects/scripts/normalize_audio.py

@@ -0,0 +1,189 @@
+# -*- coding: utf-8 -*-
+"""Bring every SFX (and the optional bed layers) to the same level contract,
+so the semantic `vol` of the config means something.
+
+Why it exists. Measured on a real piece: narration at -20.6 dB mean, an
+un-normalized SFX library from -19.6 to -30.9 dB. The whoosh that marks block
+changes ended at -36.1 dB after its vol, 15.5 dB under the voice: inaudible.
+The `vol` table only means something if every file starts from the same place.
+
+Per file:
+    1. Measure mean_volume and max_volume with ffmpeg volumedetect.
+    2. gain = sound.reference_level_db - mean. The PEAK ALWAYS WINS: if that
+       gain would push the peak past sound.max_peak_db, it is cut so the peak
+       lands exactly on the ceiling.
+    3. Apply with ffmpeg volume=<gain>dB, re-encode mp3 at a CBR bitrate at
+       or above the original (sources are VBR; round up to a standard step).
+
+The original is always kept: before the first write, the file goes to
+`_originals/` next to it and is never touched again.
+
+Idempotent: a file within APPLY_TOLERANCE_DB of its target is left alone.
+
+Known limit: the mean is taken over the WHOLE file. A SFX with a long silent
+tail gets its audible part pushed toward the ceiling. Trim silence first,
+then normalize.
+
+Scope: the loudness of the FINAL piece (LUFS) is check_loudness.py, not this.
+
+Exit code: 0 done/pass, 1 --check found files off target, 2 error.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from config import Config, ConfigError, add_config_arg, load
+
+# Tolerances of this tool (not creative numbers): writing is stricter than
+# failing on purpose. Rewriting just to erase 0.4 dB of re-encode drift is not
+# worth the generation loss; failing only happens on real drift.
+APPLY_TOLERANCE_DB = 0.3
+CHECK_TOLERANCE_DB = 1.0
+
+# Standard MP3 CBR steps (a codec fact).
+MP3_BITRATES_KBPS = (32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320)
+
+RE_MEAN = re.compile(r"mean_volume:\s*(-?[\d.]+)\s*dB")
+RE_MAX = re.compile(r"max_volume:\s*(-?[\d.]+)\s*dB")
+TMP_SUFFIX = ".normalizing.mp3"
+ORIGINALS = "_originals"
+
+
+class AudioError(Exception):
+    """Missing file or ffmpeg/ffprobe failure."""
+
+
+def parse_volumedetect(stderr: str) -> tuple[float, float]:
+    m, p = RE_MEAN.search(stderr), RE_MAX.search(stderr)
+    if not m or not p:
+        raise AudioError(f"no volumedetect output: {stderr.strip()[-300:]}")
+    return float(m.group(1)), float(p.group(1))
+
+
+def measure(path: Path) -> tuple[float, float]:
+    """(mean_volume, max_volume) in dB."""
+    r = subprocess.run(["ffmpeg", "-hide_banner", "-i", str(path), "-af", "volumedetect",
+                        "-f", "null", "-"], capture_output=True, text=True)
+    try:
+        return parse_volumedetect(r.stderr)
+    except AudioError as e:
+        raise AudioError(f"{path}: {e}") from e
+
+
+def target_bitrate_kbps(bps: int) -> int:
+    kbps = bps / 1000.0
+    return next((s for s in MP3_BITRATES_KBPS if s >= kbps), MP3_BITRATES_KBPS[-1])
+
+
+def compute_gain(mean_db: float, peak_db: float, cfg: Config) -> tuple[float, str]:
+    """Gain in dB to land the mean on the reference, unless the peak would
+    pass the ceiling: then the peak wins."""
+    gain = cfg.sound.reference_level_db - mean_db
+    if peak_db + gain > cfg.sound.max_peak_db:
+        return cfg.sound.max_peak_db - peak_db, "peak"
+    return gain, "mean"
+
+
+def _bitrate(path: Path) -> int:
+    r = subprocess.run(["ffprobe", "-v", "error", "-show_entries", "format=bit_rate",
+                        "-of", "csv=p=0", str(path)], capture_output=True, text=True)
+    s = r.stdout.strip()
+    if not s.isdigit():
+        raise AudioError(f"ffprobe could not read the bitrate of {path}: {r.stderr.strip()}")
+    return int(s)
+
+
+def apply_gain(path: Path, gain: float) -> None:
+    """Write the normalized file in place, keeping the original once."""
+    backup = path.parent / ORIGINALS / path.name
+    tmp = path.with_name(path.stem + TMP_SUFFIX)
+    kbps = target_bitrate_kbps(_bitrate(path))
+    r = subprocess.run(["ffmpeg", "-hide_banner", "-y", "-i", str(path),
+                        "-af", "volume=%.3fdB" % gain, "-c:a", "libmp3lame",
+                        "-b:a", "%dk" % kbps, str(tmp)], capture_output=True, text=True)
+    if r.returncode != 0 or not tmp.exists():
+        tmp.unlink(missing_ok=True)
+        raise AudioError(f"ffmpeg failed applying gain on {path}: {r.stderr.strip()[-300:]}")
+    backup.parent.mkdir(exist_ok=True)
+    if backup.exists():
+        path.unlink()
+    else:
+        shutil.move(str(path), str(backup))
+    shutil.move(str(tmp), str(path))
+
+
+def targets(cfg: Config, sfx_dir: Path) -> tuple[list[Path], list[str]]:
+    """Files to process, and optional bed layers missing on disk (report only)."""
+    if not sfx_dir.is_dir():
+        raise AudioError(f"sfx folder not found: {sfx_dir}")
+    files = [f for f in sorted(sfx_dir.glob("*.mp3")) if not f.name.endswith(TMP_SUFFIX)]
+    missing = []
+    for layer in cfg.sound.bed:
+        p = cfg.media_root / layer.file
+        if p.exists():
+            files.append(p)
+        else:
+            missing.append(layer.file)
+    return files, missing
+
+
+def process(path: Path, cfg: Config, write: bool) -> dict:
+    mean0, peak0 = measure(path)
+    gain, by = compute_gain(mean0, peak0, cfg)
+    done = abs(gain) <= APPLY_TOLERANCE_DB
+    mean1, peak1, written = mean0, peak0, False
+    if write and not done:
+        apply_gain(path, gain)
+        mean1, peak1 = measure(path)
+        written = True
+    return {"file": path.name, "by": by, "gain": gain, "done": done, "written": written,
+            "mean_before": mean0, "peak_before": peak0, "mean_after": mean1, "peak_after": peak1}
+
+
+def print_table(rows: list[dict]) -> None:
+    print("%-24s %8s %8s %9s  %-5s  %8s %8s  state"
+          % ("file", "mean-", "peak-", "gain", "by", "mean+", "peak+"))
+    for r in rows:
+        state = "already normalized" if r["done"] else "applied" if r["written"] else "pending"
+        print("%-24s %8.1f %8.1f %+9.2f  %-5s  %8.1f %8.1f  %s"
+              % (r["file"], r["mean_before"], r["peak_before"], r["gain"], r["by"],
+                 r["mean_after"], r["peak_after"], state))
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        description="Normalize every SFX to sound.reference_level_db (peak locked at "
+                    "sound.max_peak_db).")
+    add_config_arg(ap)
+    ap.add_argument("--sfx-dir", help="SFX folder (default: from the config paths)")
+    ap.add_argument("--check", action="store_true",
+                    help=f"measure only; exit 1 if a file is more than {CHECK_TOLERANCE_DB} dB off")
+    args = ap.parse_args(argv)
+    try:
+        cfg = load(args.config)
+        files, missing = targets(cfg, Path(args.sfx_dir) if args.sfx_dir else cfg.sfx_dir)
+        rows = [process(f, cfg, write=not args.check) for f in files]
+    except (ConfigError, AudioError) as e:
+        print(f"ERROR: {e}")
+        return 2
+    print_table(rows)
+    for m in missing:
+        print(f"(optional bed layer missing, skipped: {m})")
+    if not args.check:
+        return 0
+    off = [r["file"] for r in rows if abs(r["gain"]) > CHECK_TOLERANCE_DB]
+    if off:
+        print(f"\nFAILED: {len(off)} file(s) more than {CHECK_TOLERANCE_DB} dB off target: "
+              f"{', '.join(off)}")
+        return 1
+    print(f"\nPASSED: all {len(rows)} file(s) within {CHECK_TOLERANCE_DB} dB of target.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())