wizz-method 2.11.1 → 2.12.0

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

@@ -0,0 +1,175 @@
+# -*- coding: utf-8 -*-
+"""LOUDNESS gate on the final piece: integrated LUFS and true peak.
+
+Measures the final MP4 (or audio) with ffmpeg `loudnorm` in analysis mode
+(print_format=json) and BLOCKS when:
+    - integrated loudness is outside loudness.target_lufs +/- loudness.tolerance_lu
+    - true peak is above loudness.max_true_peak_db
+On failure it prints the ready two-pass ffmpeg command that fixes the file
+(pass 1 = this measurement, pass 2 = loudnorm with the measured values and
+linear=true, video stream copied).
+
+Why a gate and not a habit: masterizing louder than the target does not help
+(the platform turns it down) and a true peak near 0 dBTP distorts on the
+platform re-encode. The numbers and their weak source live in the config.
+
+Exit code: 0 pass, 1 fail, 2 error (missing file, ffmpeg without loudnorm
+output).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+from config import ConfigError, Loudness, add_config_arg, load
+
+FIELDS = ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset")
+VIDEO_EXT = {".mp4", ".mov", ".m4v", ".mkv"}
+
+
+class LoudnessError(Exception):
+    """File missing or loudnorm output not found."""
+
+
+LOSSLESS_EXT = {".wav", ".flac", ".aiff", ".aif"}
+
+
+def loudnorm_filter(lo: Loudness, measured: dict | None = None, tp_margin: float = 0.0) -> str:
+    """tp_margin: dB kept under max_true_peak_db in pass 2, for lossy output."""
+    base = (f"loudnorm=I={lo.target_lufs:g}:TP={lo.max_true_peak_db - tp_margin:g}"
+            f":LRA={lo.lra:g}")
+    if measured is None:
+        return base + ":print_format=json"
+    return (base + f":measured_I={measured['input_i']:g}:measured_TP={measured['input_tp']:g}"
+            f":measured_LRA={measured['input_lra']:g}"
+            f":measured_thresh={measured['input_thresh']:g}"
+            f":offset={measured['target_offset']:g}:linear=true:print_format=summary")
+
+
+def parse_loudnorm(stderr: str) -> dict:
+    """The LAST JSON object in ffmpeg's stderr, numeric fields as floats.
+    Silence gives "-inf", which becomes -math.inf (and fails the gate)."""
+    end = stderr.rfind("}")
+    start = stderr.rfind("{", 0, end + 1)
+    if start < 0 or end < 0:
+        raise LoudnessError("no loudnorm JSON in ffmpeg output")
+    try:
+        raw = json.loads(stderr[start:end + 1])
+    except json.JSONDecodeError as e:
+        raise LoudnessError(f"loudnorm JSON unreadable: {e}") from e
+    out = {}
+    for k in FIELDS:
+        if k not in raw:
+            raise LoudnessError(f"loudnorm JSON has no {k!r}")
+        out[k] = float(str(raw[k]).strip())   # float() accepts "-inf"
+    return out
+
+
+def measure(path: Path, lo: Loudness) -> dict:
+    if not path.exists():
+        raise LoudnessError(f"file not found: {path}")
+    r = subprocess.run(["ffmpeg", "-hide_banner", "-nostats", "-i", str(path),
+                        "-af", loudnorm_filter(lo), "-f", "null", "-"],
+                       capture_output=True, text=True)
+    try:
+        return parse_loudnorm(r.stderr)
+    except LoudnessError as e:
+        if "audio:0KiB" in r.stderr or "does not contain any stream" in r.stderr:
+            raise LoudnessError(f"{path}: has no audio stream") from e
+        raise LoudnessError(f"{path}: {e}: {r.stderr.strip()[-300:]}") from e
+
+
+def evaluate(m: dict, lo: Loudness) -> list[str]:
+    """Violations, empty when the measurement passes."""
+    errs = []
+    i, tp = m["input_i"], m["input_tp"]
+    if not math.isfinite(i):
+        errs.append("integrated loudness is -inf: the audio is silent or missing")
+    elif abs(i - lo.target_lufs) > lo.tolerance_lu:
+        errs.append(f"integrated {i:.1f} LUFS outside loudness.target_lufs "
+                    f"{lo.target_lufs:g} +/- loudness.tolerance_lu {lo.tolerance_lu:g}")
+    if tp > lo.max_true_peak_db:
+        errs.append(f"true peak {tp:.1f} dBTP above loudness.max_true_peak_db "
+                    f"{lo.max_true_peak_db:g}")
+    return errs
+
+
+def fix_command(path: Path, m: dict, lo: Loudness) -> str:
+    """Pass 2 of the two-pass loudnorm (pass 1 is the measurement above).
+
+    A lossy output (AAC in the MP4, MP3...) overshoots the true peak loudnorm
+    set, so its TP target sits loudness.encode_tp_margin_db lower: a fix that
+    fails the gate it came from is not a fix."""
+    out = path.with_name(path.stem + ".loudnorm" + path.suffix)
+    # loudnorm upsamples to 192 kHz internally: set the output rate back.
+    codec = "-c:v copy -c:a aac -b:a 192k -ar 48000" if path.suffix.lower() in VIDEO_EXT \
+        else "-ar 48000"
+    margin = 0.0 if path.suffix.lower() in LOSSLESS_EXT else lo.encode_tp_margin_db
+    return " ".join([
+        "ffmpeg -hide_banner -i", shlex.quote(str(path)),
+        "-af", shlex.quote(loudnorm_filter(lo, m, margin)), codec, shlex.quote(str(out))])
+
+
+def dynamic_warning(m: dict, path: Path, lo: Loudness) -> str | None:
+    """loudnorm only keeps linear=true when the gain it needs fits under the
+    true-peak target; otherwise it silently falls back to dynamic compression
+    (measured: +12.8 dB on a quiet narration flattened LRA from 3.1 to 1.8).
+    Say so before the fix runs, so the fix is a choice and not a surprise."""
+    margin = 0.0 if path.suffix.lower() in LOSSLESS_EXT else lo.encode_tp_margin_db
+    peak_after = m["input_tp"] + (lo.target_lufs - m["input_i"])
+    ceiling = lo.max_true_peak_db - margin
+    if not (math.isfinite(peak_after) and peak_after > ceiling):
+        return None
+    return (f"the fix needs {lo.target_lufs - m['input_i']:+.1f} dB, which puts the true peak "
+            f"at {peak_after:.1f} dBTP over the {ceiling:.1f} target: loudnorm will switch to "
+            f"dynamic compression. Prefer raising the narration before the render (it is "
+            f"usually the quiet layer) and measuring again.")
+
+
+def check(path: Path, lo: Loudness) -> tuple[dict, list[str]]:
+    m = measure(path, lo)
+    return m, evaluate(m, lo)
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        description="Loudness gate: integrated LUFS and true peak of the final piece.")
+    add_config_arg(ap)
+    ap.add_argument("files", nargs="+", help="final MP4 or audio file(s)")
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    args = ap.parse_args(argv)
+    try:
+        lo = load(args.config).loudness
+        results = {p: check(Path(p), lo) for p in args.files}
+    except (ConfigError, LoudnessError) as e:
+        print(f"ERROR: {e}")
+        return 2
+    failed = [p for p, (_, errs) in results.items() if errs]
+    if args.json:
+        finite = {p: {**{k: (v if math.isfinite(v) else None) for k, v in m.items()},
+                      "violations": e, "passed": not e} for p, (m, e) in results.items()}
+        print(json.dumps(finite, indent=2))
+        return 1 if failed else 0
+    for p, (m, errs) in results.items():
+        print(f"== loudness of {p} ==")
+        print(f"  integrated {m['input_i']:.1f} LUFS   true peak {m['input_tp']:.1f} dBTP"
+              f"   LRA {m['input_lra']:.1f} LU")
+        for e in errs:
+            print(f"  ERROR: {e}")
+        if errs and math.isfinite(m["input_i"]):
+            warning = dynamic_warning(m, Path(p), lo)
+            if warning:
+                print(f"  warning: {warning}")
+            print("  fix (pass 2 of 2):")
+            print(f"    {fix_command(Path(p), m, lo)}")
+        print("  FAILED" if errs else "  ok")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,137 @@
+# -*- coding: utf-8 -*-
+"""RHYTHM check on a timeline JSON. It only WARNS (always exit 0).
+
+Why it only warns: the numbers behind it (change something every 3-5s,
+Reels cuts every 2.5-4s) come from pacing blogs without a declared method.
+The config marks them with `_source`. A number backed only by opinion
+becomes a warning, never a gate.
+
+What it measures, over the visual changes listed in rhythm.counts_as_change
+(scene starts, punches, shakes, flashes, interrupts, element entries):
+    - longest static stretch: the longest span with no visual change, from
+      0 to the duration. Warns above rhythm.max_static_s.
+    - hook cadence: average interval between changes inside (0, rhythm.hook_s],
+      computed as hook_s / number of changes. Warns above
+      rhythm.hook_cut_every_s.
+    - body cadence: the same inside (hook_s, duration - rhythm.cta_tail_s].
+      Warns outside rhythm.body_cut_every_s [min, max]: below min is
+      frantic, above max is slow. The CTA tail is excluded on purpose: it
+      lowers effect density to keep price and button legible.
+SFX are audio and never count as a visual change.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import sys
+from pathlib import Path
+
+from config import ConfigError, Rhythm, add_config_arg, load
+import timeline as tl
+
+# timeline key -> how to read its instants
+_READERS = {
+    "scenes": lambda d: tl.instants(d.get("scenes"), "start"),
+    "punches": lambda d: tl.instants(d.get("punches")),
+    "shakes": lambda d: tl.instants(d.get("shakes")),
+    "flashes": lambda d: tl.instants(d.get("flashes")),
+    "interrupts": lambda d: tl.instants(d.get("interrupts")),
+    "elements": lambda d: tl.instants(d.get("elements")),
+}
+
+
+def change_points(data: dict, kinds: tuple[str, ...]) -> list[float]:
+    """Sorted unique instants of visual change. Unknown kinds are ignored."""
+    pts = {round(t, 3) for k in kinds if k in _READERS for t in _READERS[k](data)}
+    return sorted(pts)
+
+
+def longest_static(points: list[float], total: float) -> tuple[float, float]:
+    """(length, start) of the longest span without change within [0, total]."""
+    edges = sorted({0.0, total, *(p for p in points if 0.0 <= p <= total)})
+    best, at = 0.0, 0.0
+    for a, b in zip(edges, edges[1:]):
+        if b - a > best:
+            best, at = b - a, a
+    return best, at
+
+
+def cadence(points: list[float], start: float, end: float) -> float:
+    """Average seconds per change inside (start, end]; inf with no change."""
+    n = sum(1 for p in points if start < p <= end)
+    length = max(0.0, end - start)
+    return length / n if n else math.inf
+
+
+def analyze(data: dict, name: str, r: Rhythm) -> dict:
+    total, derived = tl.duration(data)
+    pts = change_points(data, r.counts_as_change)
+    static, static_at = longest_static(pts, total)
+    hook_end = min(r.hook_s, total)
+    body_end = max(hook_end, total - r.cta_tail_s)
+    hook = cadence(pts, 0.0, hook_end)
+    body = cadence(pts, hook_end, body_end) if body_end > hook_end else None
+    warns = []
+    if static > r.max_static_s:
+        warns.append(f"{static:.1f}s without visual change from {static_at:.2f}s "
+                     f"> rhythm.max_static_s {r.max_static_s:g}s")
+    if hook > r.hook_cut_every_s:
+        shown = "no change" if math.isinf(hook) else f"one change every {hook:.1f}s"
+        warns.append(f"hook (0-{hook_end:g}s): {shown} > rhythm.hook_cut_every_s "
+                     f"{r.hook_cut_every_s:g}s")
+    lo, hi = r.body_cut_every_s
+    if body is not None and not lo <= body <= hi:
+        shown = "no change" if math.isinf(body) else f"one change every {body:.1f}s"
+        warns.append(f"body ({hook_end:g}-{body_end:.1f}s): {shown} outside "
+                     f"rhythm.body_cut_every_s [{lo:g}, {hi:g}]s")
+    return {"name": name, "duration": total, "duration_derived": derived,
+            "changes": len(pts), "longest_static_s": static, "longest_static_at": static_at,
+            "hook_every_s": hook, "body_every_s": body, "warnings": warns}
+
+
+def _finite(rep: dict) -> dict:
+    """JSON has no infinity: an absent cadence becomes null."""
+    return {k: (None if isinstance(v, float) and math.isinf(v) else v) for k, v in rep.items()}
+
+
+def _fmt(v) -> str:
+    return "-" if v is None else ("none" if math.isinf(v) else f"{v:.2f}s")
+
+
+def print_report(rep: dict) -> None:
+    print(f"== rhythm of {rep['name']} ==  {rep['duration']:.1f}s, {rep['changes']} visual change(s)")
+    if rep["duration_derived"]:
+        print("  note: no 'duration' in the JSON; derived from scenes")
+    print(f"  longest static: {rep['longest_static_s']:.2f}s at {rep['longest_static_at']:.2f}s")
+    print(f"  hook cadence:   {_fmt(rep['hook_every_s'])}   body cadence: {_fmt(rep['body_every_s'])}")
+    for w in rep["warnings"]:
+        print(f"  WARNING: {w}")
+    if not rep["warnings"]:
+        print("  ok: rhythm inside the configured references")
+    print()
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        description="Rhythm check (warn only): static stretches and cut cadence.")
+    add_config_arg(ap)
+    ap.add_argument("timelines", nargs="+", help="timeline JSON path(s)")
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    args = ap.parse_args(argv)
+    try:
+        r = load(args.config).rhythm
+        reps = [analyze(tl.load(p), Path(p).stem, r) for p in args.timelines]
+    except (ConfigError, tl.TimelineError) as e:
+        print(f"ERROR: {e}")
+        return 2
+    if args.json:
+        print(json.dumps({x["name"]: _finite(x) for x in reps}, indent=2))
+    else:
+        for x in reps:
+            print_report(x)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,221 @@
+# -*- coding: utf-8 -*-
+"""SAFE ZONE gate: legible content must live between the profile's top and
+bottom, measured on the FINAL MP4.
+
+Why it exists. Pieces were approved with screens invading the platform UI (a
+CTA 44px from the top, 7px from the bottom). A green lint and an eye check do
+not catch that; only measuring does.
+
+Profiles. The config declares `safe_zones.organic` and `safe_zones.ad` (Meta
+paid Stories/Reels). The profile is, in order: --profile, the timeline's
+`safe_zone_profile` (--timeline), then the config default `safe_zone_profile`.
+
+How it measures (lessons already paid for):
+    - LOCAL CONTRAST, not mean brightness: the horizontal std-dev of each row,
+      sampled at safe_zone_gate.sample_width columns. On a light background
+      the mean of every row passes any brightness threshold.
+    - Its own threshold, safe_zone_gate.dp_min, not density.dp_min: a low
+      threshold flags background glow as text.
+    - EVERY frame, in one continuous ffmpeg decode. Sampling at 1 fps missed
+      the peak of entry animations that last tenths of a second.
+    - safe_zone_gate.edge_artifact_rows ignored at each frame edge (encoder
+      border), and fewer than safe_zone_gate.min_rows_to_fail invading rows
+      is a warning, not a failure (a card corner grazing vs a whole label).
+Only the vertical limits are measured, like the gate this was ported from;
+left/right live in the config for layout.
+
+Before moving a layout on FAIL, look at the frame (a low top with max dp near
+the threshold is glow; a max dp in the tens is text):
+    ffmpeg -ss T -i VIDEO -frames:v 1 -vf "crop=1080:400:0:0" frame-top.png
+
+Exit code: 0 pass, 1 fail, 2 file missing or unreadable.
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+
+from config import Config, ConfigError, SafeZone, add_config_arg, load
+import timeline as tl
+
+
+class ReadError(Exception):
+    """Video missing or unreadable."""
+
+
+def row_std(px) -> float:
+    """Std-dev of a row in ONE pass (sum and sum of squares)."""
+    n = len(px)
+    if n == 0:
+        return 0.0
+    s = s2 = 0
+    for v in px:
+        s += v
+        s2 += v * v
+    m = s / n
+    var = s2 / n - m * m
+    return var ** 0.5 if var > 0 else 0.0
+
+
+def content_rows(frame: bytes, width: int, height: int, dp_min: float,
+                 margin: int) -> list[tuple[int, float]]:
+    """(y, dp) of every row that holds legible content, edges excluded."""
+    rows = []
+    for y in range(margin, height - margin):
+        v = row_std(frame[y * width:(y + 1) * width])
+        if v >= dp_min:
+            rows.append((y, v))
+    return rows
+
+
+def _scale_filter(width: int, height: int) -> str:
+    return "format=gray,scale=%d:%d:flags=area" % (width, height)
+
+
+def read_frame(video: str, t: float, width: int, height: int) -> bytes:
+    """One gray frame reduced to width x height, by seek."""
+    r = subprocess.run(
+        ["ffmpeg", "-v", "error", "-ss", str(t), "-i", video, "-frames:v", "1",
+         "-vf", _scale_filter(width, height), "-f", "rawvideo", "-pix_fmt", "gray", "-"],
+        capture_output=True)
+    if r.returncode != 0:
+        raise ReadError(f"ffmpeg could not read {video} at t={t:.2f}: "
+                        f"{r.stderr.decode(errors='replace').strip()}")
+    return r.stdout
+
+
+def video_fps(video: str) -> float:
+    """Real fps of the file (the config fps is only the render target)."""
+    o = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0",
+                        "-show_entries", "stream=r_frame_rate", "-of", "csv=p=0", video],
+                       capture_output=True, text=True)
+    txt = o.stdout.strip().rstrip(",")
+    if not txt:
+        raise ReadError(f"ffprobe could not read the fps of {video}: {o.stderr.strip()}")
+    if "/" in txt:
+        num, den = txt.split("/")
+        return float(num) / float(den)
+    return float(txt)
+
+
+def all_frames(video: str, width: int, height: int):
+    """Yield (t, gray bytes) for EVERY frame, in one streaming decode."""
+    fr = video_fps(video)
+    size = width * height
+    proc = subprocess.Popen(
+        ["ffmpeg", "-v", "error", "-i", video, "-vf", _scale_filter(width, height),
+         "-f", "rawvideo", "-pix_fmt", "gray", "-"],
+        stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    i = 0
+    try:
+        while True:
+            d = proc.stdout.read(size)
+            if len(d) < size:
+                break
+            yield i / fr, d
+            i += 1
+    finally:
+        proc.stdout.close()
+        err = proc.stderr.read()
+        code = proc.wait()
+    if code != 0:
+        raise ReadError(f"ffmpeg could not decode {video}: {err.decode(errors='replace').strip()}")
+    if i == 0:
+        raise ReadError(f"ffmpeg returned no frame from {video}")
+
+
+def _side(rows: list[tuple[int, float]], bad, label: str, limit: int, fail_rows: int):
+    hit = [v for y, v in rows if bad(y)]
+    if not hit:
+        return None, False
+    severe = len(hit) >= fail_rows
+    edge = rows[0][0] if label == "TOP" else rows[-1][0]
+    sign = "<" if label == "TOP" else ">"
+    return (f"{label} {edge}{sign}{limit} ({len(hit)} row(s), max dp {max(hit):.1f}) "
+            f"[{'FAIL' if severe else 'warn'}]"), severe
+
+
+def evaluate(frame: bytes, cfg: Config, zone: SafeZone) -> tuple[str, int | None, int | None, list[str]]:
+    """(state, top, bottom, problems); state in short/empty/ok/warn/fail."""
+    g, h = cfg.safe_zone_gate, cfg.frame.height
+    if len(frame) < g.sample_width * h:
+        return "short", None, None, []
+    rows = content_rows(frame, g.sample_width, h, g.dp_min, g.edge_artifact_rows)
+    if not rows:
+        return "empty", None, None, []
+    problems, severe = [], False
+    for label, bad, limit in (("TOP", lambda y: y < zone.top, zone.top),
+                              ("BOTTOM", lambda y: y > zone.bottom, zone.bottom)):
+        msg, sev = _side(rows, bad, label, limit, g.min_rows_to_fail)
+        if msg:
+            problems.append(msg)
+            severe = severe or sev
+    state = "ok" if not problems else ("fail" if severe else "warn")
+    return state, rows[0][0], rows[-1][0], problems
+
+
+def resolve_profile(cfg: Config, profile: str | None, timeline_path: str | None) -> SafeZone:
+    if profile:
+        return cfg.safe_zone(profile)
+    if timeline_path:
+        return cfg.safe_zone(tl.load(timeline_path).get("safe_zone_profile"))
+    return cfg.safe_zone()
+
+
+def _scan(video: str, times: list[float], cfg: Config, zone: SafeZone):
+    """Yield (t, state, top, bottom, problems) for explicit times or every frame."""
+    w, h = cfg.safe_zone_gate.sample_width, cfg.frame.height
+    source = ((t, read_frame(video, t, w, h)) for t in times) if times \
+        else all_frames(video, w, h)
+    for t, d in source:
+        yield (t, *evaluate(d, cfg, zone))
+
+
+def run(video: str, times: list[float], cfg: Config, zone: SafeZone) -> int:
+    fails, warns, total, empty = [], [], 0, 0
+    print(f"profile: {zone.name}  y={zone.top}..{zone.bottom}")
+    print(f"{'t':>7} {'top':>6} {'bottom':>6}   verdict")
+    for t, state, top, bottom, probs in _scan(video, times, cfg, zone):
+        total += 1
+        if state in ("empty", "short"):
+            empty += 1
+            continue
+        if state in ("fail", "warn") or times:
+            print(f"{t:7.2f} {top:6d} {bottom:6d}   {' | '.join(probs) or 'ok'}")
+        if state == "fail":
+            fails.append(t)
+        elif state == "warn":
+            warns.append(t)
+    print(f"   {total} frame(s): {len(fails)} failing, {len(warns)} warning, "
+          f"{empty} empty, rest ok.")
+    if warns:
+        print(f"   {len(warns)} frame(s) graze the zone with fewer than "
+              f"{cfg.safe_zone_gate.min_rows_to_fail} rows. Not blocking: look first.")
+    if fails:
+        print(f"FAILED: {len(fails)} frame(s) invade the '{zone.name}' safe zone.")
+        return 1
+    print(f"PASSED: every frame inside y={zone.top}..{zone.bottom} ('{zone.name}').")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Safe-zone gate on the final MP4 (every frame).")
+    add_config_arg(ap)
+    ap.add_argument("video", help="final MP4")
+    ap.add_argument("times", nargs="*", type=float,
+                    help="optional instants (s) to inspect instead of every frame")
+    ap.add_argument("--profile", help="safe zone profile name (e.g. organic, ad)")
+    ap.add_argument("--timeline", help="timeline JSON whose safe_zone_profile applies")
+    args = ap.parse_args(argv)
+    try:
+        cfg = load(args.config)
+        zone = resolve_profile(cfg, args.profile, args.timeline)
+        return run(args.video, args.times, cfg, zone)
+    except (ConfigError, tl.TimelineError, ReadError) as e:
+        print(f"ERROR: {e}")
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())