wizz-method 2.11.2 → 2.12.0

package/src/skills-lib/wizz-video-effects/references/sfx-licensing.md

@@ -0,0 +1,40 @@
+# SFX and music licensing: organic post vs paid ad
+
+Research done on 2026-09-24; every source accessed that day. The question is never "is this sound trending" but "can this file run in a paid ad on the platform where the piece will run".
+
+## The central trap
+
+- **Trending audio from the Instagram or TikTok picker is for personal use.** Meta mutes it at boost approval (reported since about Q1 2026 by [killthedj](https://killthedj.com/meta-sound-collection/); the official Meta announcement was not found, treat as third-party report). TikTok forbids the general library for commercial use; businesses must use the Commercial Music Library ([TikTok Ads Help](https://ads.tiktok.com/help/article/commercial-music-library?lang=en)). This is structural, not taste: **no trending picker audio in any ad.**
+- **Meta has two things called "Sound Collection".** The in-app picker (availability varies by account type and region; "available in the app is not cleared for paid" per [usethirdchair, 2026-09-11](https://usethirdchair.com/blog/meta-sound-collection-explained-for-brands-and-rights-holders)) and the **Meta Business Sound Collection** (Business Suite / sound.facebook.com, 14,000+ royalty-free tracks and effects, cleared for videos, ads, Reels and Stories **inside Facebook and Instagram only**: [Meta Business Help 880459498798521](https://www.facebook.com/business/help/880459498798521), [1821972904537292](https://www.facebook.com/business/help/1821972904537292)).
+- **TikTok CML is valid only inside TikTok.** Reposting the same video elsewhere loses the licence ([Velveteen](https://www.velveteen.fm/guides/tiktok-for-musicians/tiktok-commercial-music-library-explained)).
+
+## Source table
+
+| Source | Organic Reels/TikTok | Paid ad | Attribution | Traps |
+|---|---|---|---|---|
+| Instagram picker trending audio | yes | **no** | n/a | muted at boost approval, no warning beforehand |
+| TikTok general library | yes | **no** | n/a | commercial use requires the CML |
+| Meta Sound Collection (in-app picker) | varies | not guaranteed | no | in the app does not mean cleared for paid |
+| Meta Business Sound Collection | yes | yes, Facebook/Instagram only | no | not portable to TikTok or YouTube |
+| TikTok CML | yes | yes, TikTok only | no | loses the licence outside TikTok; SFX coverage not confirmed in the official docs |
+| **Pixabay Content License** ([summary](https://pixabay.com/service/license-summary/)) | yes | **yes**, mixed into a work | no | no standalone use (reselling the raw file); no printing on merch; content showing third-party brands; **zero indemnification** ([PicDefense](https://picdefense.io/resources/source-intel/pixabay/)); keep the licence certificate per file |
+| Mixkit ([terms](https://mixkit.co/terms/), [license](https://mixkit.co/license/)) | yes | yes per the general terms | no | the specific "Sound Effects Free License" text could not be read on 2026-09-24: **open it by hand before adding Mixkit files** |
+| Freesound CC0 | yes | yes | no | mixed library: confirm the licence of each file |
+| Freesound CC-BY | yes | yes | **always** | visible credit is hard in a 15 s ad; keep a per-file record |
+| Freesound CC-BY-NC | only truly non-commercial | **never** | yes | "commercial gain" includes ads and brand content |
+| Epidemic Sound ([Pro plan](https://help.epidemicsound.com/hc/en-us/articles/26247236323858-Pro-plan)) | depends on plan | Pro and up (paid social); Business broader | no | confirm what happens to published work after cancelling |
+| Artlist ([licence](https://help.artlist.io/hc/en-us/articles/29490991524253-Understanding-Artlist-s-license)) | yes | Pro and up only | no | the Social plan explicitly excludes paid media |
+
+## What this skill ships
+
+- `assets/sfx/` holds only files with proven Pixabay provenance (see `assets/sfx/CREDITS.md` for the file list, derived cuts and what was left out).
+- Portability decides the default: Pixabay files work on Meta ads, Reels and TikTok without switching library per channel. If a pipeline ever renders per platform, the Meta Business Sound Collection becomes a zero-risk option for Meta-only pieces.
+- **Left out on purpose:** "vine boom", "record scratch" and "glitch". None has performance data, every source is a meme blog or a post count, and the comedy tone does not fit product and UI demos. They are out as fashion, not as a licence ban; reopening needs an argument, not enthusiasm.
+- `cash` and `coin` stay: the concept is alive (TikTok discovery pages), but the file must come from a licensed library, never a viral clip captured from a feed.
+
+## Adding a sound
+
+1. Download from a source in the table whose "Paid ad" column says yes for the piece's platform.
+2. Save the licence certificate or the page URL and date next to the entry in `CREDITS.md`.
+3. Run `normalize_audio.py` so the file enters the level contract.
+4. Map it to a semantic event in the config (the event is the key, the file is a column). Run `sound.py` for coverage.

package/src/skills-lib/wizz-video-effects/references/when-to-use.md

@@ -0,0 +1,129 @@
+# When to use each effect, and when not
+
+A catalogue of effects is easy; the refusal rule is what decides whether a video looks professional or zooms every two seconds.
+
+**No number on this page is canonical.** Every value lives in the project's `effects.config.json` and is cited here by key. If this page and the config disagree, the config wins and this page is wrong.
+
+## How to read
+
+Each effect has seven fields. The first three are the decision; the last four are execution.
+
+| Field | Question |
+|---|---|
+| **Purpose** | what narrative work the effect does |
+| **Enters when** | the trigger: always an event in the speech or on screen, never the clock |
+| **Does not enter when** | the refusal; if empty, the effect is not ready for automatic use |
+| **Intensity / duration** | config key or component constant |
+| **Frequency** | ceiling and minimum gap from the previous one |
+| **Conflicts** | what it cannot coexist with |
+| **Priority** | the 0-1 `strength` it carries into the budget when competing for an instant |
+
+Strength is not the effect's importance: it is the strength of the **narrative claim of that concrete instant**. The same punch is worth 0.9 on the sentence that turns the offer and 0.3 on an ordinary breath.
+
+## The rule above all others
+
+**An effect that always happens stops marking what matters.**
+
+A production system once had the rule "zoom punch on every SFX with volume >= 0.5". Almost every SFX sat at 0.50 or 0.55, so it fired on all of them: one zoom every 2.5 seconds, measured. The effect that existed to underline became the background. Hence the three laws:
+
+1. **Every effect goes through the budget.** No path writes an effect straight into the timeline data.
+2. **When it does not fit, switch effect; do not drop the instant.** Where the screen has headroom at the top, `punch`; where content sits against the safe zone, `flash`, which only touches opacity and moves no pixel.
+3. **The instant comes from a speech breath, never from the clock.** An effect on top of a word competes with it (`fill_breaths.py`).
+
+## Camera movement
+
+### `punch`: zoom pulse
+- **Purpose:** underline the sentence just said. The system's exclamation mark.
+- **Enters when:** the breath right after a sentence that carries the argument (the offer turn, the number that hurts, the promise), and at a narrative block cut.
+- **Does not enter when:** screen content sits inside the punch margin of the piece's safe-zone profile (computed from `breaths.punch_peak_scale`); the punch scales around the centre and multiplies with micro-zoom, so at its peak it pushes content through the safe zone. `fill_breaths.py --visual` measures this per breath and gives the breath to a `flash` instead. Nor over a block of text the viewer must read whole, nor twice in the same sentence.
+- **Intensity / duration:** peak about 1.035 (1.05 when the triggering sound is loud), window about 0.22 s.
+- **Frequency:** `budget.per_effect.punch` (`max_per_min`, `gap_min`, `max_in_row`).
+- **Conflicts:** `shake` in the same window, never both.
+- **Priority:** 0.9 offer turn, 0.7 block cut, 0.4 an unloaded breath; below that it is not worth spending.
+
+### `microZoom`: slow continuous zoom
+- **Purpose:** take the image out of photograph state. Not noticed; it is what keeps a still shot from looking still.
+- **Enters when:** by default, on any shot longer than two seconds.
+- **Does not enter when:** the screen already has strong motion of its own, or content is within about 21 px of the safe-zone edge: micro-zoom eats that margin and has failed pieces by one pixel.
+- **Frequency:** continuous; does not count against the budget. It multiplies the punch, which is why the punch ceiling must account for it.
+
+### `drift`: handheld camera
+- **Purpose:** physical presence for a shot that is otherwise a generated image.
+- **Enters when:** actor shot or scene with depth.
+- **Does not enter when:** the screen is a list, a table or anything read line by line. **Never raise its amplitude.**
+- **Conflicts:** `shake`.
+
+## Impact
+
+### `shake`: short tremor
+- **Purpose:** physical weight for something that lands: a stamp, a seal, a verdict.
+- **Enters when:** the `verdict` sound event fires. That is the only trigger, declared in the config (`triggers` on the event).
+- **Does not enter when:** there is no visual impact; never sustained, never as background rhythm, **never over text the viewer must read**.
+- **Frequency:** `budget.per_effect.shake`, deliberately the rarest effect in the system, with `max_dur_s`.
+- **Conflicts:** `drift` and `punch` in the same window.
+- **Priority:** 0.95. When a verdict lands it almost always wins: it is the only effect with an exclusive semantic trigger.
+
+### `flash`: cut flash
+- **Purpose:** mark a change without displacing anything. The punch's substitute exactly where the punch does not fit.
+- **Enters when:** narrative block cut; as punch substitute on a screen pressed against the safe zone.
+- **Does not enter when:** inside the same block without a screen change: a flash without a cut reads as a render glitch.
+- **Frequency:** `budget.per_effect.flash`; more tolerant than punch because it moves no pixel.
+- **Priority:** 0.6 block cut, 0.35 as substitute.
+
+## Transitions
+
+The default transition is the **hard cut**. A transition is justified only when the screen change is also a change of subject.
+
+- **`whip`** (blurred sweep): block cut during fast speech (`breaths.fast_speech_wps` and up; `breaths.pace_profiles` picks transition and cut sound per pace). Not on dragging speech or within the same subject. Duration in **frames**, while everything else is in seconds.
+- **`zoom`** (scale transition): block cut in a dragging stretch, where whip would be violent. Not when the next shot opens with a punch.
+- **`cut`**: every other cut. Never refused; it is the default.
+- Fade and crossdissolve: cut (see [do-not-use.md](do-not-use.md)).
+
+All transitions share `budget.per_effect.transition`.
+
+## Pattern interrupts
+
+Share a tight budget (`budget.per_effect.interrupt`): a break that repeats stops breaking.
+
+- **`suddenzoom`**: the sentence reframes the argument ("but you won't like the answer"). Not in the same block as another interrupt.
+- **`freeze`**: a reaction to hold (the price, the result, the face). Not while speech continues on top: freezing the image with the voice running reads as a render failure.
+
+## Text and captions
+
+- **Karaoke caption:** always when there is narration, from ctc-align word timestamps. The caption band is **exclusive**: no readable content inside it, ever. Silenced while a headline is on screen, but keep that window short: silencing captions removes a whole density band.
+- **Headline:** at the start of a block, anchoring the subject. It does not repeat the caption; the price leads the headline only if the hook is the price. An unknown style name must fail, never fall back silently to a default.
+
+## Element entrance and exit
+
+- **Entrance:** on the word that names the element, not before: nothing appears before it is mentioned. Two levels avoid the empty screen while waiting: the element exists as **base** (opacity about 0.4) from the start of the beat and rises to **highlight** (opacity 1) on the word.
+- **Exit:** an element **recedes to context** (higher, smaller, low opacity); it never vanishes into emptiness. It leaves for good only when something else enters at the same instant.
+
+## Rhythm by stretch
+
+Read by `check_rhythm.py`, which warns and never blocks (the sources are weak, see [editing-patterns.md](editing-patterns.md)):
+
+- **Hook** closes at `rhythm.hook_s` (3 s, the window Meta's hook rate measures). Something moves from the first frame.
+- **Body:** no stretch longer than `rhythm.max_static_s` without any visual change; cut cadence around `rhythm.body_cut_every_s`.
+- **CTA:** lower effect density; no punch or zoom on the final card; price and button readable. Repeat the CTA visually mid-offer and on the final frame.
+
+## Avatar
+
+Only for pieces with a generated avatar (`avatar.*`, optional block):
+
+- **Full-shot ceiling:** after it, the actor leaves the shot or recedes to a card. The cut prefers the end of a sentence, then the longest pause near the ceiling, and only as a last resort the raw clock.
+- **Occlusion ceiling:** a full-shot actor with nothing on top for longer is a layout error.
+- **Take ceiling:** a generated avatar's gesture cycle repeats visibly after about 7.5 s.
+- After each render, look at a frame of the CTA block: the actor has covered the price and the button with every gate green.
+
+## Checklist before approving a piece
+
+No gate replaces this; several items are here because they failed in production.
+
+1. The excess gate passes, or what fails is justified in writing.
+2. No dominant effect closer than `budget.gap_min_global` to another.
+3. The caption band is clean **in the rendered frame**, not in a lint.
+4. A frame of the CTA block, looked at: price and button visible.
+5. If there is an avatar, the mouth matches this piece's audio. Look; do not trust the gate.
+6. No shake over text meant to be read.
+7. Loudness gate passes on the final file.
+8. The largest cluster of effects is not an accident: it marks something, or it goes.

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

@@ -0,0 +1,211 @@
+# -*- coding: utf-8 -*-
+"""Anti-excess engine: effects compete for a budget instead of all entering.
+
+Why it exists. A rule like "zoom punch on every SFX with vol >= 0.5" fired on
+almost every SFX of the source project (one zoom every 2.5s on the busiest
+pieces). An effect that always happens stops marking what matters.
+
+This module does not decide IF a SFX asks for an effect (that is `triggers`
+in the sound config) nor HOW the effect is drawn. It only decides WHICH
+candidates, from a list that already arrived too long, earn the right to
+appear: by narrative strength first, then a ceiling per curve section, a
+minimum distance between repeats of the same kind, a minimum global distance
+between dominant effects, and a limit on same-kind effects in a burst.
+
+Usage:
+    from budget import Candidate, select
+    res = select([Candidate(t=3.2, kind="punch", strength=0.8, reason="verdict")],
+                 total=55.0, cfg=cfg)
+    print(res.report())
+"""
+from __future__ import annotations
+
+from bisect import bisect_left, insort
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from config import Config, CurveSection
+
+
+@dataclass(frozen=True)
+class Candidate:
+    """An effect asking for a place in the timeline."""
+    t: float
+    kind: str        # key of budget.per_effect: punch, flash, shake, interrupt, transition
+    strength: float  # 0..1, narrative claim
+    reason: str      # short human-readable why
+
+
+@dataclass(frozen=True)
+class Refusal:
+    candidate: Candidate
+    rule: str        # "gap_min" | "gap_min_global" | "max_in_row" | "ceiling" | "unknown_kind"
+    detail: str
+
+
+@dataclass(frozen=True)
+class Result:
+    accepted: tuple[Candidate, ...]   # always sorted by t
+    refusals: tuple[Refusal, ...]
+
+    def by_kind(self) -> dict[str, int]:
+        count: dict[str, int] = {}
+        for c in self.accepted:
+            count[c.kind] = count.get(c.kind, 0) + 1
+        return count
+
+    def report(self) -> str:
+        lines = [f"accepted: {len(self.accepted)}   refused: {len(self.refusals)}"]
+        if self.accepted:
+            lines.append("by kind:")
+            for kind, n in self.by_kind().items():
+                lines.append(f"  {kind:<10} {n}")
+        if self.refusals:
+            lines.append("refusals:")
+            for r in self.refusals:
+                lines.append(f"  t={r.candidate.t:6.1f}s {r.candidate.kind:<10} "
+                             f"[{r.rule}] {r.detail}")
+        return "\n".join(lines)
+
+
+def _durations_and_weights(cfg: Config, total: float) -> list[tuple[str, float, float]]:
+    """Seconds of each curve section with its weight. The curve stores
+    CUMULATIVE fractions: a section runs from the previous until_frac to its own."""
+    out = []
+    prev = 0.0
+    for s in cfg.budget.curve:
+        out.append((s.name, (s.until_frac - prev) * total, s.weight))
+        prev = s.until_frac
+    return out
+
+
+def section_ceiling(cfg: Config, kind: str, section: CurveSection, total: float) -> int:
+    """How many `kind` events fit in this section.
+
+    The whole-piece ceiling (budget.ceiling, from max_per_min) is SPLIT across
+    the sections in proportion to duration * weight. A heavier section gets a
+    bigger slice of the SAME total; it never invents a new ceiling:
+
+        slice = total_ceiling * (dur * weight) / sum(dur_i * weight_i)
+
+    Rounded to the nearest integer. A short section may round to 0: there is
+    no per-section floor, only the whole-piece floor of 1.
+    """
+    total_ceiling = cfg.budget.ceiling(kind, total)
+    parts = _durations_and_weights(cfg, total)
+    weighted = sum(d * w for _, d, w in parts)
+    if weighted <= 0:
+        return total_ceiling
+    dur, weight = next((d, w) for name, d, w in parts if name == section.name)
+    return round(total_ceiling * (dur * weight) / weighted)
+
+
+def _nearest_gap(times: list[float], t: float) -> float | None:
+    """Distance to the nearest neighbour in a sorted list; None when empty."""
+    if not times:
+        return None
+    i = bisect_left(times, t)
+    near = []
+    if i > 0:
+        near.append(t - times[i - 1])
+    if i < len(times):
+        near.append(times[i] - t)
+    return min(near)
+
+
+def _in_row_if_inserted(accepted: list[Candidate], pos: int, kind: str,
+                        t: float, burst_gap: float) -> int:
+    """How many same-kind events would sit in the SAME BURST if a candidate
+    entered at `pos` of a list sorted by t.
+
+    Counted on the FINAL ORDER BY TIME, never on processing order (which is by
+    strength): a candidate accepted early for its strength can end up
+    surrounded, in time, by same-kind neighbours accepted later.
+
+    `burst_gap` separates bursts. Without it, "in a row" would span the whole
+    piece and a third punch 20s after the second would fail max_in_row=2,
+    cancelling the per-piece ceiling. A rule that cancels another rule of the
+    same module is wrong.
+    """
+    back, i, prev = 0, pos - 1, t
+    while i >= 0 and accepted[i].kind == kind and prev - accepted[i].t <= burst_gap:
+        back, prev, i = back + 1, accepted[i].t, i - 1
+    fwd, i, nxt = 0, pos, t
+    while i < len(accepted) and accepted[i].kind == kind and accepted[i].t - nxt <= burst_gap:
+        fwd, nxt, i = fwd + 1, accepted[i].t, i + 1
+    return back + fwd + 1
+
+
+def as_candidate(c) -> Candidate:
+    """Accept a Candidate or a dict with the same keys (sound.py emits dicts
+    on purpose, so the two modules stay independent). A missing key fails
+    here with its name, not later mid-selection."""
+    if isinstance(c, Candidate):
+        return c
+    try:
+        return Candidate(t=float(c["t"]), kind=str(c["kind"]),
+                         strength=float(c["strength"]), reason=str(c.get("reason", "")))
+    except (KeyError, TypeError) as e:
+        raise TypeError(
+            f"invalid candidate: {c!r}. Expected a Candidate or a dict with keys "
+            f"t, kind, strength (reason optional). Missing or wrong: {e}") from e
+
+
+def _check(cand: Candidate, cfg: Config, total: float, state: dict) -> tuple[str, str] | None:
+    """The first rule the candidate breaks, as (rule, detail), or None."""
+    rule = cfg.budget.rule(cand.kind)
+    if rule is None:
+        return "unknown_kind", (f"kind {cand.kind!r} is not in budget.per_effect. "
+                                f"Known: {', '.join(sorted(cfg.budget.per_effect))}")
+    sec = cfg.budget.section(cand.t, total)
+    cap = section_ceiling(cfg, cand.kind, sec, total)
+    used = state["per_section"].get((cand.kind, sec.name), 0)
+    if used >= cap:
+        return "ceiling", f"section {sec.name!r} of {cand.kind} already has {used} of {cap} allowed"
+    gap = _nearest_gap(state["times"].get(cand.kind, []), cand.t)
+    if gap is not None and gap < rule.gap_min:
+        return "gap_min", f"gap {gap:.1f}s < {rule.gap_min:.1f}s required for {cand.kind}"
+    if rule.dominant:
+        g = _nearest_gap(state["dominant"], cand.t)
+        if g is not None and g < cfg.budget.gap_min_global:
+            return "gap_min_global", (f"gap {g:.1f}s < {cfg.budget.gap_min_global:.1f}s "
+                                      f"required between dominant effects")
+    pos = bisect_left([c.t for c in state["accepted"]], cand.t)
+    row = _in_row_if_inserted(state["accepted"], pos, cand.kind, cand.t, cfg.budget.burst_gap_s)
+    if row > rule.max_in_row:
+        return "max_in_row", (f"{row} {cand.kind} in one burst (burst gap "
+                              f"{cfg.budget.burst_gap_s}s) > {rule.max_in_row} allowed")
+    return None
+
+
+def select(candidates: Iterable[Candidate | dict], total: float, cfg: Config) -> Result:
+    """Decide which candidates enter, by these rules in order:
+
+    1. Process by decreasing strength (tie: increasing t): the strongest
+       narrative claim picks its place first. PRIORITY is by strength;
+       final ACCEPTANCE is read in time order.
+    2. Unknown kind is never accepted silently.
+    3. Ceiling per curve section (see `section_ceiling`).
+    4. gap_min of the kind against accepted events of the SAME kind.
+    5. gap_min_global against accepted DOMINANT events of any kind (a
+       non-dominant candidate is not held by this rule).
+    6. max_in_row, measured on the final timeline sorted by t.
+
+    Deterministic: same input, same Result (no sets, no hash order, no random).
+    """
+    ordered = sorted((as_candidate(c) for c in candidates), key=lambda c: (-c.strength, c.t))
+    state = {"accepted": [], "per_section": {}, "times": {}, "dominant": []}
+    refusals: list[Refusal] = []
+    for cand in ordered:
+        broken = _check(cand, cfg, total, state)
+        if broken:
+            refusals.append(Refusal(cand, *broken))
+            continue
+        pos = bisect_left([c.t for c in state["accepted"]], cand.t)
+        state["accepted"].insert(pos, cand)
+        key = (cand.kind, cfg.budget.section(cand.t, total).name)
+        state["per_section"][key] = state["per_section"].get(key, 0) + 1
+        insort(state["times"].setdefault(cand.kind, []), cand.t)
+        if cfg.budget.rule(cand.kind).dominant:
+            insort(state["dominant"], cand.t)
+    return Result(accepted=tuple(state["accepted"]), refusals=tuple(refusals))

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

@@ -0,0 +1,218 @@
+# -*- coding: utf-8 -*-
+"""EXCESS gate: measures what the other gates do not.
+
+Why it exists. Every other gate measures a LACK (of density, of anchor, of
+room inside the safe zone). None measured the opposite: an audit counted one
+zoom punch every 2.5s on the busiest pieces and no gate said anything. This
+script counts the real effects of a timeline JSON and fails when they exceed
+the budget in the config (`budget`).
+
+Timeline keys read (see references/data-contract.md; all may be absent):
+    punches, shakes, flashes   numbers or objects {"at": ...}
+    interrupts                 objects {"at": ..., "kind": ...}
+    scenes                     a scene with `transition` other than "" or
+                               "cut" counts as a transition event
+    duration                   if absent, derived from the scenes (and said)
+    sfx, scenes[].sfx          every sound, checked TOGETHER against the three
+                               refusals of sound.map_requests (unknown event,
+                               collision, same sound too many times in a row)
+
+Per effect kind it reports: count and per minute against the piece ceiling
+(budget.ceiling), smallest gap against gap_min, longest run of same-kind
+events closer than gap_min against max_in_row, and pairs of DIFFERENT dominant
+kinds closer than gap_min_global. It always reports the largest cluster of
+dominant effects in a CLUSTER_WINDOW_S window: it is what the viewer sees.
+
+Exit code: 0 pass, 1 fail, 2 usage error or missing file. --warn measures and
+always exits 0 (use it only while calibrating; the gate is meant to block).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from config import Budget, Config, ConfigError, add_config_arg, load
+import sound
+import timeline as tl
+
+# Report window for the largest cluster. A display choice, not a rule: the
+# span a viewer perceives at once.
+CLUSTER_WINDOW_S = 10.0
+
+
+def smallest_gap(times: list[float]) -> tuple[float | None, float | None]:
+    """(gap, instant of the first of the pair), or (None, None) with < 2 events."""
+    if len(times) < 2:
+        return None, None
+    a, b = min(zip(times, times[1:]), key=lambda p: p[1] - p[0])
+    return b - a, a
+
+
+def longest_run(times: list[float], gap_min: float) -> tuple[int, float | None]:
+    """Longest run where each consecutive pair is closer than gap_min. Reuses
+    gap_min as the only threshold the config gives for 'glued'."""
+    if not times:
+        return 0, None
+    best = cur = 1
+    cur_start = best_start = times[0]
+    for a, b in zip(times, times[1:]):
+        if b - a < gap_min:
+            cur += 1
+        else:
+            cur, cur_start = 1, b
+        if cur > best:
+            best, best_start = cur, cur_start
+    return best, best_start
+
+
+def _dominant(events: dict[str, list[float]], budget: Budget) -> list[tuple[float, str]]:
+    return sorted((t, kind) for kind, lst in events.items() for t in lst
+                  if (r := budget.rule(kind)) and r.dominant)
+
+
+def dominant_crossings(events: dict[str, list[float]], budget: Budget) -> list[tuple]:
+    """Pairs of DIFFERENT dominant kinds closer than gap_min_global. The
+    per-kind gap only guards repeats of the SAME kind; a punch glued to a
+    shake passes both and still overloads the same instant."""
+    marked = _dominant(events, budget)
+    found = []
+    for i, (ta, ka) in enumerate(marked):
+        for tb, kb in marked[i + 1:]:
+            dt = tb - ta
+            if dt >= budget.gap_min_global:
+                break
+            if ka != kb:
+                found.append((ta, ka, tb, kb, dt))
+    return found
+
+
+def largest_cluster(events: dict[str, list[float]], budget: Budget,
+                    window: float = CLUSTER_WINDOW_S) -> tuple[int, float | None]:
+    """Window of `window` seconds with the most dominant effects (two pointers)."""
+    dom = [t for t, _ in _dominant(events, budget)]
+    if not dom:
+        return 0, None
+    best_n, best_t, j = 1, dom[0], 0
+    for i in range(len(dom)):
+        while dom[i] - dom[j] >= window:
+            j += 1
+        if i - j + 1 > best_n:
+            best_n, best_t = i - j + 1, dom[j]
+    return best_n, best_t
+
+
+def _kind_row(kind: str, times: list[float], total: float, cfg: Config) -> tuple[dict, list[str]]:
+    rule = cfg.budget.rule(kind)
+    n = len(times)
+    per_min = (n / total * 60.0) if total > 0 else 0.0
+    ceiling = cfg.budget.ceiling(kind, total)
+    gap, gap_at = smallest_gap(times)
+    run, run_at = longest_run(times, rule.gap_min)
+    row = {"kind": kind, "n": n, "per_min": per_min, "ceiling": ceiling,
+           "gap_measured": gap, "gap_required": rule.gap_min,
+           "run_measured": run, "run_allowed": rule.max_in_row}
+    errs = []
+    if n > ceiling:
+        errs.append(f"{kind}: {n} event(s) > ceiling of {ceiling} for {total:.1f}s "
+                    f"({per_min:.1f}/min, limit budget.per_effect.{kind}.max_per_min="
+                    f"{rule.max_per_min:g})")
+    if gap is not None and gap < rule.gap_min:
+        errs.append(f"{kind}: gap of {gap:.2f}s at {gap_at:.2f}s < gap_min {rule.gap_min:.1f}s")
+    if run > rule.max_in_row:
+        errs.append(f"{kind}: {run} in a row from {run_at:.2f}s > max_in_row {rule.max_in_row}")
+    return row, errs
+
+
+def sound_violations(data: dict, cfg: Config) -> list[str]:
+    """The three sound refusals of sound.map_requests, applied to EVERY sound
+    in the timeline at once (sfx[] plus scene cut sounds). Sounds mapped in
+    separate passes can each be fine alone and still collide together."""
+    requests, errs = [], []
+    for s in tl.sounds(data):
+        ev = sound.event_of(s, cfg)
+        if ev is None:
+            errs.append(f"sound {s.get('src', '?')}@{float(s['at']):.2f}s refused "
+                        f"(unknown_event): no `event` and no unique (file, vol) match in "
+                        f"sound.events")
+            continue
+        requests.append((float(s["at"]), ev))
+    for r in sound.map_requests(requests, cfg).refusals:
+        errs.append(f"sound {r.event}@{r.t:.2f}s refused ({r.rule}): {r.detail}")
+    return errs
+
+
+def analyze(data: dict, name: str, cfg: Config) -> dict:
+    """Measure one timeline and return a structured report. Never prints."""
+    total, derived = tl.duration(data)
+    events = tl.effect_events(data)
+    rows, violations = [], []
+    for kind in cfg.budget.per_effect:
+        row, errs = _kind_row(kind, events.get(kind, []), total, cfg)
+        rows.append(row)
+        violations.extend(errs)
+    for ta, ka, tb, kb, dt in dominant_crossings(events, cfg.budget):
+        violations.append(f"{ka}@{ta:.2f}s glued to {kb}@{tb:.2f}s ({dt:.2f}s) "
+                          f"< gap_min_global {cfg.budget.gap_min_global:.1f}s")
+    violations.extend(sound_violations(data, cfg))
+    n_dom, t_dom = largest_cluster(events, cfg.budget)
+    return {"name": name, "duration": total, "duration_derived": derived, "rows": rows,
+            "cluster": {"n": n_dom, "start": t_dom}, "violations": violations,
+            "passed": not violations}
+
+
+def print_report(rep: dict) -> None:
+    print(f"== excess of {rep['name']} ==")
+    if rep["duration_derived"]:
+        print(f"  warning: no 'duration' in the JSON; derived from scenes: {rep['duration']:.2f}s")
+    print(f"  {'kind':<10} | {'n':>3} | {'per min':>7} | {'cap':>4} | "
+          f"{'min gap':>8} | {'required':>8} | {'in a row':>8}")
+    for r in rep["rows"]:
+        gap = f"{r['gap_measured']:.2f}s" if r["gap_measured"] is not None else "-"
+        print(f"  {r['kind']:<10} | {r['n']:>3} | {r['per_min']:>7.1f} | {r['ceiling']:>4} | "
+              f"{gap:>8} | {r['gap_required']:>7.1f}s | "
+              f"{str(r['run_measured']) + '/' + str(r['run_allowed']):>8}")
+    c = rep["cluster"]
+    if c["start"] is not None:
+        print(f"  largest cluster: {c['n']} dominant effect(s) in {CLUSTER_WINDOW_S:.0f}s "
+              f"from {c['start']:.2f}s")
+    else:
+        print("  largest cluster: no dominant effect in the piece")
+    for v in rep["violations"]:
+        print(f"  ERROR: {v}")
+    print(f"  FAILED: {len(rep['violations'])} excess violation(s)" if rep["violations"]
+          else "  ok: no excess measured")
+    print()
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        description="Excess gate: count effects of timeline JSON(s) against the budget.")
+    add_config_arg(ap)
+    ap.add_argument("timelines", nargs="+", help="timeline JSON path(s)")
+    ap.add_argument("--warn", action="store_true", help="measure but always exit 0")
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    args = ap.parse_args(argv)
+    try:
+        cfg = load(args.config)
+        reports = [analyze(tl.load(p), Path(p).stem, cfg) for p in args.timelines]
+    except (ConfigError, tl.TimelineError) as e:
+        print(f"ERROR: {e}")
+        return 2
+    if args.json:
+        print(json.dumps({r["name"]: r for r in reports}, ensure_ascii=False, indent=2))
+    else:
+        for r in reports:
+            print_report(r)
+        if len(reports) > 1:
+            failed = [r["name"] for r in reports if not r["passed"]]
+            print(f"== summary: {len(failed)}/{len(reports)} failed: {', '.join(failed)} =="
+                  if failed else f"== summary: {len(reports)}/{len(reports)} passed ==")
+    if args.warn:
+        return 0
+    return 0 if all(r["passed"] for r in reports) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())