wizz-method 2.11.2 → 2.13.0

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())