wizz-method 2.11.1 → 2.12.0

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

@@ -0,0 +1,583 @@
+# -*- coding: utf-8 -*-
+"""Loader for `effects.config.json`: the single home of every canonical number.
+
+Why it exists. Numbers copied into a second place drift into two versions (the
+source project once had six quantities with two values each). The rule this
+module enforces: the number lives in the config and whoever needs it imports
+it. No doc rewrites a value; it cites the key.
+
+This file knows nothing about any offer, piece or project path. Everything
+that changes per project lives in the JSON.
+
+Lookup order for the config file:
+    1. explicit path (argument or --config on any CLI)
+    2. environment variable VIDEO_EFFECTS_CONFIG
+    3. ./effects.config.json in the current working directory
+Nothing found is an error: copy assets/effects.config.template.json first.
+
+CLI, to print what is in force:
+    python3 config.py [--config PATH]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+ENV_CONFIG = "VIDEO_EFFECTS_CONFIG"
+DEFAULT_NAME = "effects.config.json"
+TEMPLATE = Path(__file__).resolve().parent.parent / "assets" / "effects.config.template.json"
+
+
+class ConfigError(Exception):
+    """Invalid config. Better to fail here than to render something wrong."""
+
+
+# ------------------------------------------------------------------ structures
+
+
+@dataclass(frozen=True)
+class Frame:
+    width: int
+    height: int
+    fps: int
+
+
+@dataclass(frozen=True)
+class SafeZone:
+    name: str
+    top: int
+    bottom: int
+    left: int
+    right: int
+    recommended_margin: int = 0
+
+    def inside(self, x: float, y: float) -> bool:
+        return self.left <= x <= self.right and self.top <= y <= self.bottom
+
+
+@dataclass(frozen=True)
+class SafeZoneGate:
+    dp_min: float
+    edge_artifact_rows: int
+    min_rows_to_fail: int
+    sample_width: int
+
+
+@dataclass(frozen=True)
+class Density:
+    n_bands: int
+    min_filled: int
+    dp_min: float
+    step_s: float
+    sample_width: int
+
+    def bands(self, top: int, bottom: int) -> list[tuple[int, int]]:
+        """N uniform bands between top and bottom, to measure occupancy."""
+        h = (bottom - top) // self.n_bands
+        return [(top + i * h, top + (i + 1) * h) for i in range(self.n_bands)]
+
+
+@dataclass(frozen=True)
+class EffectRule:
+    max_per_min: float
+    gap_min: float
+    max_in_row: int
+    dominant: bool
+    max_dur_s: float | None = None
+
+
+@dataclass(frozen=True)
+class CurveSection:
+    name: str
+    until_frac: float
+    weight: float
+
+
+@dataclass(frozen=True)
+class Budget:
+    gap_min_global: float
+    burst_gap_s: float
+    per_effect: dict[str, EffectRule]
+    curve: tuple[CurveSection, ...]
+
+    def rule(self, kind: str) -> EffectRule | None:
+        return self.per_effect.get(kind)
+
+    def section(self, t: float, total: float) -> CurveSection:
+        """Which part of the piece the instant t falls in."""
+        frac = (t / total) if total > 0 else 0.0
+        for s in self.curve:
+            if frac <= s.until_frac:
+                return s
+        return self.curve[-1]
+
+    def ceiling(self, kind: str, total: float) -> int:
+        """How many events of this kind fit in the whole piece (floor 1)."""
+        r = self.rule(kind)
+        if r is None:
+            return 0
+        return max(1, int(round(r.max_per_min * total / 60.0)))
+
+
+@dataclass(frozen=True)
+class SoundEvent:
+    key: str
+    sound: str
+    vol: float
+    when: str
+    triggers: tuple[str, ...] = ()
+    # Narrative weight (0..1) of the visual effect this event fires. Volume is
+    # mix, strength is weight. None falls back to vol, and says so.
+    strength: float | None = None
+
+
+@dataclass(frozen=True)
+class BedLayer:
+    """Optional continuous layer (ambience or music), relative to media_root."""
+    file: str
+    vol: float
+
+
+@dataclass(frozen=True)
+class Sound:
+    sfx_subdir: str
+    narration_volume: float
+    relative_ceiling: float
+    max_same_sound_in_row: int
+    collision_window_s: float
+    events: dict[str, SoundEvent]
+    reference_level_db: float = -20.0
+    max_peak_db: float = -3.0
+    bed: tuple[BedLayer, ...] = ()
+
+    def event(self, key: str) -> SoundEvent:
+        if key not in self.events:
+            known = ", ".join(sorted(self.events))
+            raise ConfigError(
+                f"unknown sound event: {key!r}. Events are semantic, not file "
+                f"names. Known: {known}")
+        return self.events[key]
+
+    def src(self, key: str) -> str:
+        """Path of the event's file relative to media_root (timeline `src`)."""
+        return f"{self.sfx_subdir}/{self.event(key).sound}.mp3"
+
+    def sounds_used(self) -> set[str]:
+        return {e.sound for e in self.events.values()}
+
+
+@dataclass(frozen=True)
+class Ducking:
+    depth_db: float
+    attack_s: float
+    release_s: float
+    assumed_sfx_duration_s: float
+
+
+@dataclass(frozen=True)
+class Loudness:
+    target_lufs: float
+    tolerance_lu: float
+    max_true_peak_db: float
+    lra: float
+    # Headroom the printed fix leaves under max_true_peak_db when it writes a
+    # lossy file (AAC/MP3): the encoder overshoots the peak loudnorm set.
+    encode_tp_margin_db: float = 1.0
+
+
+@dataclass(frozen=True)
+class Rhythm:
+    max_static_s: float
+    hook_s: float
+    hook_cut_every_s: float
+    body_cut_every_s: tuple[float, float]
+    cta_tail_s: float
+    counts_as_change: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class PaceProfile:
+    transition: str
+    sound_event: str
+
+
+@dataclass(frozen=True)
+class Breaths:
+    min_silence_s: float
+    silence_db: float
+    edge_guard_s: float
+    fast_speech_wps: float
+    punch_peak_scale: float
+    pace_profiles: dict[str, PaceProfile]
+    punch_sound_event: str
+
+
+@dataclass(frozen=True)
+class Avatar:
+    max_full_shot_s: float
+    max_occlusion_s: float
+    max_take_s: float
+    variation_step_s: float
+    min_variation_s: float
+
+
+@dataclass(frozen=True)
+class Config:
+    version: int
+    offer: str
+    source: Path
+    media_root: Path
+    frame: Frame
+    safe_zone_profile: str
+    safe_zones: dict[str, SafeZone]
+    safe_zone_gate: SafeZoneGate
+    density: Density
+    budget: Budget
+    sound: Sound
+    ducking: Ducking
+    loudness: Loudness
+    rhythm: Rhythm
+    breaths: Breaths
+    avatar: Avatar | None = None
+    extra: dict = field(default_factory=dict)
+
+    @property
+    def sfx_dir(self) -> Path:
+        return self.media_root / self.sound.sfx_subdir
+
+    def safe_zone(self, name: str | None = None) -> SafeZone:
+        """The named profile, or the default one when name is None."""
+        key = name or self.safe_zone_profile
+        if key not in self.safe_zones:
+            raise ConfigError(
+                f"unknown safe zone profile: {key!r}. "
+                f"Known: {', '.join(sorted(self.safe_zones))}")
+        return self.safe_zones[key]
+
+
+# ---------------------------------------------------------------------- reading
+
+
+def _need(d: dict, key: str, where: str):
+    if not isinstance(d, dict) or key not in d:
+        raise ConfigError(f"missing {where}.{key} in config")
+    return d[key]
+
+
+def _notes_out(d: dict) -> dict:
+    """Drop `_note` style keys: they document, they never configure."""
+    return {k: v for k, v in d.items() if not k.startswith("_")}
+
+
+def resolve_path(path: str | os.PathLike | None = None) -> Path:
+    """Where the config comes from, by the documented lookup order."""
+    if path:
+        return Path(path)
+    env = os.environ.get(ENV_CONFIG)
+    if env:
+        return Path(env)
+    return Path.cwd() / DEFAULT_NAME
+
+
+def _read_json(p: Path) -> dict:
+    if not p.exists():
+        raise ConfigError(
+            f"config not found: {p}. Copy {TEMPLATE.name} from the skill's "
+            f"assets/ to your project as {DEFAULT_NAME}, or pass --config, or "
+            f"set {ENV_CONFIG}.")
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise ConfigError(f"{p} is not valid JSON: {e}") from e
+
+
+def _read_safe_zones(d: dict) -> dict[str, SafeZone]:
+    zones = {}
+    for name, z in _notes_out(_need(d, "safe_zones", "root")).items():
+        zones[name] = SafeZone(
+            name=name, top=int(_need(z, "top", name)),
+            bottom=int(_need(z, "bottom", name)),
+            left=int(_need(z, "left", name)), right=int(_need(z, "right", name)),
+            recommended_margin=int(z.get("recommended_margin", 0)))
+    if not zones:
+        raise ConfigError("safe_zones has no profile")
+    return zones
+
+
+def _read_budget(d: dict) -> Budget:
+    b = _need(d, "budget", "root")
+    per_effect = {}
+    for kind, r in _notes_out(_need(b, "per_effect", "budget")).items():
+        per_effect[kind] = EffectRule(
+            max_per_min=float(_need(r, "max_per_min", kind)),
+            gap_min=float(_need(r, "gap_min", kind)),
+            max_in_row=int(_need(r, "max_in_row", kind)),
+            dominant=bool(r.get("dominant", False)),
+            max_dur_s=(float(r["max_dur_s"]) if "max_dur_s" in r else None))
+    curve = tuple(
+        CurveSection(name=c["name"], until_frac=float(c["until_frac"]),
+                     weight=float(c["weight"]))
+        for c in _need(b, "curve", "budget"))
+    return Budget(gap_min_global=float(_need(b, "gap_min_global", "budget")),
+                  burst_gap_s=float(_need(b, "burst_gap_s", "budget")),
+                  per_effect=per_effect, curve=curve)
+
+
+def _read_sound(d: dict, sfx_subdir: str) -> Sound:
+    s = _need(d, "sound", "root")
+    events = {}
+    for key, e in _notes_out(_need(s, "events", "sound")).items():
+        events[key] = SoundEvent(
+            key=key, sound=str(_need(e, "sound", key)),
+            vol=float(_need(e, "vol", key)), when=str(e.get("when", "")),
+            triggers=tuple(e.get("triggers", ())),
+            strength=(float(e["strength"]) if "strength" in e else None))
+    bed = tuple(
+        BedLayer(file=str(v["file"]), vol=float(v.get("vol", 0.0)))
+        for k, v in _notes_out(s.get("bed", {})).items()
+        if isinstance(v, dict) and "file" in v)
+    return Sound(
+        sfx_subdir=sfx_subdir,
+        narration_volume=float(s.get("narration_volume", 1.0)),
+        relative_ceiling=float(_need(s, "relative_ceiling", "sound")),
+        max_same_sound_in_row=int(_need(s, "max_same_sound_in_row", "sound")),
+        collision_window_s=float(_need(s, "collision_window_s", "sound")),
+        events=events,
+        reference_level_db=float(s.get("reference_level_db", -20.0)),
+        max_peak_db=float(s.get("max_peak_db", -3.0)), bed=bed)
+
+
+def _read_rhythm(d: dict) -> Rhythm:
+    r = _need(d, "rhythm", "root")
+    body = _need(r, "body_cut_every_s", "rhythm")
+    if not (isinstance(body, list) and len(body) == 2):
+        raise ConfigError("rhythm.body_cut_every_s must be [min, max]")
+    return Rhythm(
+        max_static_s=float(_need(r, "max_static_s", "rhythm")),
+        hook_s=float(_need(r, "hook_s", "rhythm")),
+        hook_cut_every_s=float(_need(r, "hook_cut_every_s", "rhythm")),
+        body_cut_every_s=(float(body[0]), float(body[1])),
+        cta_tail_s=float(r.get("cta_tail_s", 0.0)),
+        counts_as_change=tuple(_need(r, "counts_as_change", "rhythm")))
+
+
+def _read_breaths(d: dict) -> Breaths:
+    b = _need(d, "breaths", "root")
+    profiles = {
+        k: PaceProfile(transition=str(v["transition"]), sound_event=str(v["sound_event"]))
+        for k, v in _notes_out(_need(b, "pace_profiles", "breaths")).items()}
+    for k in ("first", "fast", "slow"):
+        if k not in profiles:
+            raise ConfigError(f"missing breaths.pace_profiles.{k} in config")
+    return Breaths(
+        min_silence_s=float(_need(b, "min_silence_s", "breaths")),
+        silence_db=float(_need(b, "silence_db", "breaths")),
+        edge_guard_s=float(_need(b, "edge_guard_s", "breaths")),
+        fast_speech_wps=float(_need(b, "fast_speech_wps", "breaths")),
+        punch_peak_scale=float(_need(b, "punch_peak_scale", "breaths")),
+        pace_profiles=profiles,
+        punch_sound_event=str(_need(b, "punch_sound_event", "breaths")))
+
+
+def _read_avatar(d: dict) -> Avatar | None:
+    a = d.get("avatar")
+    if not isinstance(a, dict) or not _notes_out(a):
+        return None
+    return Avatar(
+        max_full_shot_s=float(_need(a, "max_full_shot_s", "avatar")),
+        max_occlusion_s=float(_need(a, "max_occlusion_s", "avatar")),
+        max_take_s=float(_need(a, "max_take_s", "avatar")),
+        variation_step_s=float(_need(a, "variation_step_s", "avatar")),
+        min_variation_s=float(_need(a, "min_variation_s", "avatar")))
+
+
+def _read_small_blocks(d: dict) -> dict:
+    g = _need(d, "safe_zone_gate", "root")
+    den = _need(d, "density", "root")
+    du = _need(d, "ducking", "root")
+    lo = _need(d, "loudness", "root")
+    return {
+        "safe_zone_gate": SafeZoneGate(
+            dp_min=float(_need(g, "dp_min", "safe_zone_gate")),
+            edge_artifact_rows=int(g.get("edge_artifact_rows", 0)),
+            min_rows_to_fail=int(_need(g, "min_rows_to_fail", "safe_zone_gate")),
+            sample_width=int(_need(g, "sample_width", "safe_zone_gate"))),
+        "density": Density(
+            n_bands=int(_need(den, "n_bands", "density")),
+            min_filled=int(_need(den, "min_filled", "density")),
+            dp_min=float(_need(den, "dp_min", "density")),
+            step_s=float(_need(den, "step_s", "density")),
+            sample_width=int(_need(den, "sample_width", "density"))),
+        "ducking": Ducking(
+            depth_db=float(_need(du, "depth_db", "ducking")),
+            attack_s=float(_need(du, "attack_ms", "ducking")) / 1000.0,
+            release_s=float(_need(du, "release_ms", "ducking")) / 1000.0,
+            assumed_sfx_duration_s=float(_need(du, "assumed_sfx_duration_s", "ducking"))),
+        "loudness": Loudness(
+            target_lufs=float(_need(lo, "target_lufs", "loudness")),
+            tolerance_lu=float(_need(lo, "tolerance_lu", "loudness")),
+            max_true_peak_db=float(_need(lo, "max_true_peak_db", "loudness")),
+            lra=float(lo.get("lra", 11.0)),
+            encode_tp_margin_db=float(lo.get("encode_tp_margin_db", 1.0))),
+    }
+
+
+def load(path: str | os.PathLike | None = None) -> Config:
+    """Read and validate the config. Fails instead of assuming a default."""
+    p = resolve_path(path)
+    d = _read_json(p)
+    paths = d.get("paths", {})
+    fr = _need(d, "frame", "root")
+    cfg = Config(
+        version=int(d.get("version", 1)),
+        offer=str(d.get("offer", "")),
+        source=p.resolve(),
+        media_root=(p.resolve().parent / paths.get("media_root", ".")),
+        frame=Frame(int(_need(fr, "width", "frame")), int(_need(fr, "height", "frame")),
+                    int(_need(fr, "fps", "frame"))),
+        safe_zone_profile=str(_need(d, "safe_zone_profile", "root")),
+        safe_zones=_read_safe_zones(d),
+        budget=_read_budget(d),
+        sound=_read_sound(d, str(paths.get("sfx_subdir", "sfx"))),
+        rhythm=_read_rhythm(d),
+        breaths=_read_breaths(d),
+        avatar=_read_avatar(d),
+        **_read_small_blocks(d),
+    )
+    validate(cfg)
+    return cfg
+
+
+# ------------------------------------------------------------------- validation
+
+
+def _validate_zones(c: Config) -> None:
+    if c.safe_zone_profile not in c.safe_zones:
+        raise ConfigError(
+            f"safe_zone_profile {c.safe_zone_profile!r} is not in safe_zones "
+            f"({', '.join(sorted(c.safe_zones))})")
+    for z in c.safe_zones.values():
+        if z.top >= z.bottom:
+            raise ConfigError(f"safe_zones.{z.name}.top ({z.top}) >= bottom ({z.bottom})")
+        if z.left >= z.right:
+            raise ConfigError(f"safe_zones.{z.name}.left ({z.left}) >= right ({z.right})")
+        if z.top < 0 or z.left < 0 or z.bottom > c.frame.height or z.right > c.frame.width:
+            raise ConfigError(f"safe_zones.{z.name} leaves the frame")
+    if c.density.min_filled > c.density.n_bands:
+        raise ConfigError("density.min_filled is larger than density.n_bands")
+
+
+def _validate_budget(c: Config) -> None:
+    fracs = [s.until_frac for s in c.budget.curve]
+    if not fracs:
+        raise ConfigError("budget.curve is empty")
+    if fracs != sorted(fracs):
+        raise ConfigError("budget.curve is not sorted by until_frac")
+    if abs(fracs[-1] - 1.0) > 1e-9:
+        raise ConfigError("the last budget.curve section must end at until_frac 1.0")
+    for kind, r in c.budget.per_effect.items():
+        # A per-effect gap below the global gap is a rule that contradicts
+        # itself: the engine would have to pick which one to ignore.
+        if r.dominant and r.gap_min < c.budget.gap_min_global:
+            raise ConfigError(
+                f"budget.per_effect.{kind}.gap_min ({r.gap_min}) is below "
+                f"gap_min_global ({c.budget.gap_min_global}) on a dominant effect")
+        if r.max_in_row < 1:
+            raise ConfigError(f"budget.per_effect.{kind}.max_in_row must be >= 1")
+
+
+def _validate_sound(c: Config) -> None:
+    s = c.sound
+    ceiling = s.relative_ceiling * s.narration_volume
+    for key, e in s.events.items():
+        if not 0.0 <= e.vol <= 1.0:
+            raise ConfigError(f"sound.events.{key}.vol outside 0..1: {e.vol}")
+        if e.vol > ceiling:
+            raise ConfigError(
+                f"sound.events.{key}.vol ({e.vol}) exceeds the ceiling relative "
+                f"to narration ({ceiling}). A SFX that competes with the voice "
+                f"steals attention instead of marking it.")
+        if e.strength is not None and not 0.0 <= e.strength <= 1.0:
+            raise ConfigError(f"sound.events.{key}.strength outside 0..1: {e.strength}")
+        for t in e.triggers:
+            if t not in c.budget.per_effect:
+                raise ConfigError(
+                    f"sound.events.{key}.triggers names effect {t!r}, which has "
+                    f"no rule in budget.per_effect")
+    used = [p.sound_event for p in c.breaths.pace_profiles.values()]
+    for ev in used + [c.breaths.punch_sound_event]:
+        if ev not in s.events:
+            raise ConfigError(f"breaths names sound event {ev!r}, not in sound.events")
+
+
+def _validate_audio_blocks(c: Config) -> None:
+    d, lo, r = c.ducking, c.loudness, c.rhythm
+    if d.depth_db <= 0 or d.attack_s <= 0 or d.release_s <= 0:
+        raise ConfigError("ducking.depth_db, attack_ms and release_ms must be > 0")
+    if lo.tolerance_lu <= 0:
+        raise ConfigError("loudness.tolerance_lu must be > 0")
+    if lo.encode_tp_margin_db < 0:
+        raise ConfigError("loudness.encode_tp_margin_db must be >= 0")
+    if lo.max_true_peak_db > 0:
+        raise ConfigError("loudness.max_true_peak_db must be <= 0 dBTP")
+    lo_b, hi_b = r.body_cut_every_s
+    if not 0 < lo_b <= hi_b:
+        raise ConfigError("rhythm.body_cut_every_s must be 0 < min <= max")
+    if r.hook_s <= 0 or r.max_static_s <= 0 or r.hook_cut_every_s <= 0:
+        raise ConfigError("rhythm.hook_s, max_static_s and hook_cut_every_s must be > 0")
+    if c.breaths.punch_peak_scale < 1.0:
+        raise ConfigError("breaths.punch_peak_scale must be >= 1.0")
+
+
+def validate(c: Config) -> None:
+    """The incoherences that already cost a wrong render."""
+    _validate_zones(c)
+    _validate_budget(c)
+    _validate_sound(c)
+    _validate_audio_blocks(c)
+
+
+# -------------------------------------------------------------------- CLI glue
+
+
+def add_config_arg(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--config", metavar="PATH",
+        help=f"effects config JSON (default: ${ENV_CONFIG}, then ./{DEFAULT_NAME})")
+
+
+def _print_summary(c: Config) -> None:
+    print(f"config: {c.source}")
+    print(f"offer: {c.offer or '(empty)'}  version {c.version}")
+    print(f"frame: {c.frame.width}x{c.frame.height} @ {c.frame.fps}fps")
+    for z in c.safe_zones.values():
+        mark = "  [default]" if z.name == c.safe_zone_profile else ""
+        print(f"safe zone {z.name:8} x={z.left}..{z.right} y={z.top}..{z.bottom}{mark}")
+    print("budget (55s piece):")
+    for kind, r in c.budget.per_effect.items():
+        print(f"   {kind:10} ceiling {c.budget.ceiling(kind, 55.0):3}  gap {r.gap_min:.1f}s"
+              f"  max {r.max_in_row} in a row{'  [dominant]' if r.dominant else ''}")
+    print(f"sfx dir: {c.sfx_dir}")
+    for key, e in c.sound.events.items():
+        print(f"   {key:12} -> {e.sound:12} @{e.vol:.2f}   {e.when}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Validate and print the effects config in force.")
+    add_config_arg(ap)
+    args = ap.parse_args(argv)
+    try:
+        c = load(args.config)
+    except ConfigError as e:
+        print(f"INVALID CONFIG: {e}")
+        return 1
+    _print_summary(c)
+    print("ok: config is valid.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())