wizz-method 2.11.2 → 2.12.0

package/src/skills-lib/wizz-video-effects/assets/remotion/useEffects.ts

@@ -0,0 +1,120 @@
+// Pure, deterministic math for the effects timeline (references/data-contract.md).
+// No Math.random, no Date: the same frame always gives the same value.
+
+export type Instant = number | { at: number; [k: string]: unknown };
+
+export type SfxEntry = { at: number; event?: string; src: string; vol: number; dur?: number };
+
+export type Scene = {
+  start: number;
+  dur: number;
+  transition?: string;
+  sfx?: Omit<SfxEntry, "at">;
+};
+
+export type Duck = {
+  start: number;
+  end: number;
+  depth_db: number;
+  attack_s: number;
+  release_s: number;
+};
+
+export type EffectsTimeline = {
+  fps?: number;
+  duration?: number;
+  scenes?: Scene[];
+  sfx?: SfxEntry[];
+  punches?: Instant[];
+  shakes?: Instant[];
+  flashes?: Instant[];
+  ducking?: Duck[];
+};
+
+// Component constants. The budget (how many, how far apart) lives in
+// effects.config.json and was already applied by the scripts; these only
+// shape one effect once it has been accepted.
+export const PUNCH = { peak: 1.035, windowS: 0.22 };
+export const FLASH = { peakOpacity: 0.35, windowS: 0.18 };
+export const SHAKE = { amplitudePx: 9, durS: 0.25 };
+export const TRANSITION = { whipFrames: 6, zoomFrames: 9, zoomFrom: 1.12, whipPx: 140 };
+
+export const instants = (items?: Instant[]): number[] =>
+  (items ?? []).map((i) => (typeof i === "number" ? i : Number(i.at))).sort((a, b) => a - b);
+
+/** Every sound of the piece: sfx[] plus each scene's cut sound at its start. */
+export const allSounds = (tl: EffectsTimeline): SfxEntry[] => {
+  const scene = (tl.scenes ?? [])
+    .filter((s) => s.sfx)
+    .map((s) => ({ ...(s.sfx as Omit<SfxEntry, "at">), at: s.start }));
+  return [...(tl.sfx ?? []), ...scene].sort((a, b) => a.at - b.at);
+};
+
+/** Narration gain for the ducking windows (same math as gain_db_at in sound.py).
+ *  `frame` is relative to the <Audio>; pass its start frame when it is not 0. */
+export const narrationVolume =
+  (ducking: Duck[], fps: number, startFrame = 0) =>
+  (frame: number): number => {
+    const t = (frame + startFrame) / fps;
+    let db = 0;
+    for (const w of ducking) {
+      if (t < w.start || t > w.end) continue;
+      let shape = 1;
+      if (t < w.start + w.attack_s) shape = (t - w.start) / w.attack_s;
+      else if (t > w.end - w.release_s) shape = (w.end - t) / w.release_s;
+      db = Math.min(db, -w.depth_db * Math.max(0, Math.min(1, shape)));
+    }
+    return Math.pow(10, db / 20);
+  };
+
+/** Triangle pulse 0..1..0 centred on the nearest instant within the window. */
+const pulse = (t: number, at: number[], windowS: number): number => {
+  let best = 0;
+  for (const a of at) {
+    const d = Math.abs(t - a);
+    if (d < windowS / 2) best = Math.max(best, 1 - d / (windowS / 2));
+  }
+  return best;
+};
+
+export const punchScale = (t: number, punches: number[]): number =>
+  1 + (PUNCH.peak - 1) * pulse(t, punches, PUNCH.windowS);
+
+export const flashOpacity = (t: number, flashes: number[]): number =>
+  FLASH.peakOpacity * pulse(t, flashes, FLASH.windowS);
+
+/** Short decaying tremor starting at each shake instant, never longer than SHAKE.durS. */
+export const shakeOffset = (t: number, shakes: number[]): { x: number; y: number } => {
+  for (const a of shakes) {
+    const d = t - a;
+    if (d >= 0 && d < SHAKE.durS) {
+      const decay = 1 - d / SHAKE.durS;
+      const amp = SHAKE.amplitudePx * decay;
+      return { x: amp * Math.sin(d * 95), y: amp * 0.6 * Math.cos(d * 71) };
+    }
+  }
+  return { x: 0, y: 0 };
+};
+
+/** Scene transition at frame `f`: scale and horizontal offset for the incoming shot. */
+export const transitionAt = (
+  f: number,
+  fps: number,
+  scenes: Scene[],
+): { scale: number; x: number; blurPx: number } => {
+  for (const s of scenes) {
+    const from = Math.round(s.start * fps);
+    const local = f - from;
+    if (s.transition === "zoom" && local >= 0 && local < TRANSITION.zoomFrames) {
+      const p = local / TRANSITION.zoomFrames;
+      const ease = 1 - Math.pow(1 - p, 3);
+      return { scale: TRANSITION.zoomFrom + (1 - TRANSITION.zoomFrom) * ease, x: 0, blurPx: 0 };
+    }
+    if (s.transition === "whip" && local >= 0 && local < TRANSITION.whipFrames) {
+      const p = local / TRANSITION.whipFrames;
+      const ease = 1 - Math.pow(1 - p, 3);
+      return { scale: 1, x: TRANSITION.whipPx * (1 - ease), blurPx: 18 * (1 - ease) };
+    }
+  }
+  return { scale: 1, x: 0, blurPx: 0 };
+};

package/src/skills-lib/wizz-video-effects/assets/sfx/CREDITS.md

@@ -0,0 +1,56 @@
+# SFX credits and licence
+
+## Source
+
+Every file in this folder comes from [Pixabay sound effects](https://pixabay.com/sound-effects/), either untouched or derived by cutting and pitching a Pixabay original (table below). The originals reached this skill through the `media-use` audio library (`manifest.json` there holds per-file descriptions) and were carried into the ad pipeline this engine was ported from.
+
+## Licence: Pixabay Content License
+
+Summary of [pixabay.com/service/license-summary](https://pixabay.com/service/license-summary/), read on 2026-09-24:
+
+- Commercial use is allowed, **including paid ads**, with no attribution required (credit is given here for transparency).
+- Modification is allowed.
+- **Never standalone.** A SFX may only ship mixed into a video (narration, visuals, edit). Selling, uploading or redistributing the raw files on their own, as a sound pack or a library, is forbidden. This folder is a working asset of the skill, not a redistribution: do not publish it as a pack.
+- No printing on physical goods for resale, and no commercial use tied to a recognizable third-party brand or logo shown in the content.
+- **No indemnification.** Pixabay does not cover legal costs in a dispute (third-party risk analysis by PicDefense, consistent with the absence of an indemnity clause in the official terms). Keep the licence certificate or the page URL and download date of every new file you add.
+- Content ID: the reported claims concern music tracks on YouTube, not short SFX. Risk is low, not zero; the Pixabay certificate is what clears a claim.
+
+## Files shipped
+
+Originals (untouched in content; some normalized in level by `normalize_audio.py`): `chime`, `click`, `click-soft`, `error`, `impact-bass-1`, `impact-bass-2`, `key-press`, `notification`, `ping`, `pop` (cut, see below), `riser`, `sparkle`, `typing`, `whoosh`, `whoosh-short`, `whoosh-cinematic`.
+
+Derived files, one per sound the config's semantic events expect (`sound.events.*.sound`):
+
+| File | Source (Pixabay original) | Treatment |
+| --- | --- | --- |
+| `whoosh.mp3` | `whoosh-short.mp3` | none; byte-identical copy |
+| `click.mp3` | itself | none |
+| `pop.mp3` | itself (0.72s) | cut to 0.30s + 60 ms fade-out |
+| `coin.mp3` | `ping.mp3` | `atrim=0.28:0.68` (drops the lead-in silence, keeps the plink tail) + 60 ms fade-out |
+| `stamp.mp3` | `impact-bass-1.mp3` | cut to 0.45s + 60 ms fade-out |
+| `notif.mp3` | `notification.mp3` | cut to 0.70s + 60 ms fade-out |
+| `type.mp3` | `typing.mp3` | cut to 0.80s + 60 ms fade-out |
+| `paste.mp3` | `click-soft.mp3` | copied without cut (already 0.37s) |
+| `send.mp3` | `whoosh-short.mp3` | `asetrate=44100*1.28,aresample=44100` (higher pitch, ~0.45s) + 60 ms fade-out |
+| `cash.mp3` | `chime.mp3` | cut to 0.60s + 60 ms fade-out |
+| `success.mp3` | `sparkle.mp3` | cut to 0.70s + 60 ms fade-out (a different texture from `cash`) |
+| `riser-metal.mp3` | `riser.mp3` | window 3.25s to 4.15s + `asetrate*1.8` (shorter and brighter) + fades, 0.54s; silence trimmed BEFORE normalizing |
+
+`riser-metal.mp3` was missing from the original credits table. Its provenance was recovered from the working-session record of 2026-09-16 that created it (derivation above) and checked on 2026-09-24: the same window and rate applied to the Pixabay `riser.mp3` gives 0.50s, the shipped file is 0.54s (0.50s plus MP3 encoder padding). It is kept because its only source is a Pixabay original.
+
+Every file follows the level contract of the config (`sound.reference_level_db`, `sound.max_peak_db`, peak always wins). Check with `python3 scripts/normalize_audio.py --check --sfx-dir assets/sfx`.
+
+## Left out, and why
+
+| File | Why |
+| --- | --- |
+| `glitch-1.mp3`, `glitch-2.mp3`, `glitch-3.mp3` | Licence is fine (Pixabay); left out as a style decision: glitch is meme or fashion, with no performance data and a comedy tone that does not fit product and UI demos. |
+
+No other file of the source folder was excluded. Nothing without proven Pixabay provenance is shipped.
+
+## Adding a file
+
+1. Only from a source cleared for the piece's use (paid ad vs organic) and portable across the platforms it will run on.
+2. Save the licence certificate or the page URL and date in this file.
+3. Trim silence, then run `normalize_audio.py`.
+4. Map it to a semantic event in the config (the event is the key, the file is a column) and run `python3 scripts/sound.py coverage`.

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

@@ -0,0 +1,87 @@
+# Audio: which sound for which event, at what level
+
+**No number on this page is canonical.** They live in the `sound`, `ducking` and `loudness` blocks of `effects.config.json`.
+
+## Why the key is semantic
+
+Measured in a production batch before this rule existed: eleven SFX files on disk, **two** used in practice (`pop` 184 times, `whoosh` 119), four never used. `pop` and `whoosh` are the neutral sounds, the ones that mean nothing in particular. The sounds that meant something (money, send, typing, stamp) sat idle.
+
+The cause was not laziness: no rule tied a sound to an event, and without a rule whoever picks by hand always picks the sound that is never wrong. A whole piece with two sounds is the same as no sound design.
+
+So whoever edits asks for **`verdict`**, not **`stamp.mp3`**:
+
+```python
+res = sound.map_requests([(6.2, "verdict"), (13.4, "price")], cfg)
+```
+
+What comes with it:
+
+1. **Changing SFX library is changing one column** of the config. No rule and no code changes.
+2. **An invented event is refused** with the list of valid ones, instead of playing the wrong sound.
+3. **Volume always comes from the config**, never from an argument: the mix ruler stays the same from start to finish.
+
+## The events
+
+`sound.events` in the template (the event is the key; `sound` is the file stem under the SFX folder):
+
+| Event | Sound | When |
+|---|---|---|
+| `block_cut` | whoosh | switch of narrative block |
+| `scene_cut` | whoosh (lower) | screen change inside the same block |
+| `element_in` | pop | a card, line or label enters |
+| `text_in` | riser-metal | a text card enters: headline, title, anchor sentence |
+| `list_item` | coin (lower) | item of a repeating list; the checklist plink |
+| `verdict` | stamp | verdict, seal, decision slammed down. **Also triggers `shake`** |
+| `message` | notif | a message, notification or alert arrives |
+| `typing` | type | text being typed on screen |
+| `paste` | paste | copy or paste |
+| `click` | click | interface interaction, cursor, tap |
+| `send` | send | send, publish, submit |
+| `price` | cash | the price appears or changes |
+| `gain` | coin | value gained, savings, counter going up |
+| `done` | success | check, ready, task done |
+
+`list_item` exists apart from `element_in` for one reason: the fifth item of a list does not deserve the volume of the first element entering the scene; without the distinction a ten-item list sounds like a machine gun. `text_in` exists because text entrances otherwise fell back to the neutral `pop` and whole batches came out sounding the same.
+
+## The three refusals
+
+- **Unknown event.** Refused, with the valid list in the message. Never falls back to a default sound.
+- **Collision.** Two requests closer than `sound.collision_window_s` sound like one dirty sound, not two. The first stays.
+- **Same sound too many times in a row.** `sound.max_same_sound_in_row`. A sound that repeats stops being information and becomes texture.
+
+## Levels
+
+Three layers, in this order:
+
+1. **File level contract.** `normalize_audio.py` brings every SFX to `sound.reference_level_db` with the peak locked at `sound.max_peak_db`. The `vol` table only means something if every file starts from the same place: measured in production, a library ranging from -19.6 to -30.9 dB made the block-cut whoosh come out 15.5 dB under the voice, inaudible. An accent must sit roughly 6 to 10 dB under the voice: heard without competing. Trim silent tails before normalizing (the gate measures the whole file, so a long silent tail makes the sound come out too loud).
+2. **Semantic volume.** `vol` per event, capped by `sound.relative_ceiling` times the narration volume; the loader **refuses the whole config** if any event exceeds it. An effect that competes with the voice takes attention instead of marking it, and the voice is what sells. The verdict is the loudest and still under the ceiling.
+3. **Master loudness.** The final file is measured by `check_loudness.py` against `loudness.target_lufs` (-14 LUFS integrated), `loudness.tolerance_lu` and `loudness.max_true_peak_db` (-1 dBTP). TikTok and Reels normalise playback to about -14 LUFS; mastering louder brings nothing and risks distortion after the platform re-encodes. Meta never published an official number; -14 / -1 is the industry value replicated for both (sources in [editing-patterns.md](editing-patterns.md) and the research behind this skill). When it fails, the gate prints the two-pass ffmpeg `loudnorm` command that fixes it; for lossy outputs the fix aims `loudness.encode_tp_margin_db` under the peak ceiling, because AAC re-encoding overshoots the true peak. If the gain needed does not fit under the peak, loudnorm compresses instead of scaling and the gate says so: raise the narration before the render instead.
+
+## Strength is not volume
+
+The verdict plays at 0.65 and is worth 0.95 in the effects budget. Two different things:
+
+- **volume** is mixing: how loud without covering the voice;
+- **strength** is narrative weight: who wins the instant when two effects compete.
+
+Deriving strength from volume cost a real defect: the verdict lost its instant to an ordinary punch, against the written rule. Strength is its own field (`strength`); where it is absent the module falls back to volume **and says so**.
+
+## Ducking
+
+Each SFX used to play over the narration at a fixed level, only adding. That is the most audible gap between amateur and professional editing.
+
+`sound.py duck` writes `ducking[]` windows: the narration dips by `ducking.depth_db` only when a SFX sounds over the **start of a spoken word**, with `ducking.attack_ms` and `ducking.release_ms`. Overlapping windows merge. The Remotion volume callback is in [data-contract.md](data-contract.md).
+
+The numbers are marked in the config as an **extrapolation without a primary source**: classic music ducking (18 to 25 dB under the voice) is for a continuous bed, not for short transient SFX, and no source gave numbers for the transient case. A small dip (3 to 6 dB), fast attack and short release is the adaptation.
+
+## Background bed
+
+`sound.bed` accepts an optional ambience and an optional music track. Each enters only if the file exists; without it the build goes on and says so. Music only from a source cleared for the piece's platform ([sfx-licensing.md](sfx-licensing.md)). With a music bed, classic ducking applies to the bed, not the small SFX dip above.
+
+## Coverage
+
+```bash
+python3 scripts/sound.py --config effects.config.json coverage
+```
+
+Says which sounds are on disk, which sounds no event uses (waste) and which events point at a missing file (a broken render waiting to happen). Run it after touching the library.

package/src/skills-lib/wizz-video-effects/references/data-contract.md

@@ -0,0 +1,145 @@
+# Timeline data contract
+
+The scripts in `scripts/` read and write one JSON object per piece: the **timeline**. It is the hand-off between whoever plans the edit (HyperFrames screens, `ctc-align` timing) and whoever renders the audio and effects (Remotion). Times are always **seconds from the start of the piece**, as floats. Every list is optional: an absent list is an empty list, never an error.
+
+Numbers that decide anything (gaps, ceilings, depths) are never in the timeline: they live in `effects.config.json` and are cited by key.
+
+## Top-level keys
+
+| Key | Type | Read by | Written by | Meaning |
+| --- | --- | --- | --- | --- |
+| `fps` | int | `sound.py duck` | planner | render fps; default `frame.fps` of the config |
+| `duration` | float | every check | planner | piece length; if absent, derived from the largest scene end (reports say so) |
+| `safe_zone_profile` | string | `check_safe_zone.py`, `measure_density.py`, `fill_breaths.py` | planner | `organic` or `ad` (any key of `safe_zones`); overrides the config default for this piece |
+| `words[]` | list | `sound.py duck`, `fill_breaths.py` | `ctc-align` | spoken words |
+| `scenes[]` | list | `check_excess.py`, `check_rhythm.py`, `fill_breaths.py` | planner, `fill_breaths.py` | screens |
+| `sfx[]` | list | `sound.py duck`, `fill_breaths.py` | planner, `fill_breaths.py` | point sounds |
+| `punches[]` | list | `check_excess.py`, `check_rhythm.py` | planner, `fill_breaths.py` | zoom punches |
+| `shakes[]` | list | same | planner | short shakes (`budget.per_effect.shake.max_dur_s`) |
+| `flashes[]` | list | same | planner, `fill_breaths.py` | opacity flashes |
+| `interrupts[]` | list | same | planner | pattern interrupts |
+| `elements[]` | list | `check_rhythm.py` | planner | element entries (cards, labels) that count as visual change |
+| `ducking[]` | list | renderer | `sound.py duck --write` | narration duck windows |
+
+### `words[]` (ctc-align output, unchanged)
+
+```json
+{ "text": "price", "start": 1.84, "end": 2.21, "score": -0.12 }
+```
+
+Only `start` and `end` are required. Breaths are the gaps between words at least `breaths.min_silence_s` long.
+
+### `scenes[]`
+
+```json
+{
+  "start": 3.2,
+  "dur": 4.1,
+  "transition": "whip",
+  "sfx": { "event": "block_cut", "src": "sfx/whoosh.mp3", "vol": 0.55 }
+}
+```
+
+- `transition`: `cut`, `whip`, `zoom` or any name the renderer knows. Anything other than `""` or `cut` counts as a `transition` event in the budget.
+- `sfx` (optional): the cut sound, played at `start`. Same shape as an `sfx[]` entry without `at`.
+
+### `sfx[]`
+
+```json
+{ "at": 5.4, "event": "verdict", "src": "sfx/stamp.mp3", "vol": 0.65, "dur": 0.45 }
+```
+
+- `event`: the semantic key of `sound.events`. Always write it: without it, scripts must rebuild the event from the `(file, vol)` pair, which only works while that pair is unique in the config.
+- `src`: relative to `paths.media_root` (Remotion `staticFile(src)`).
+- `vol`: copied from the config, never chosen by hand.
+- `dur` (optional): seconds. Without it, `sound.py duck` probes the file, then falls back to `ducking.assumed_sfx_duration_s`.
+
+### Effects: `punches[]`, `shakes[]`, `flashes[]`, `interrupts[]`, `elements[]`
+
+Each item is a number (the instant) or an object with `at`:
+
+```json
+"punches": [2.4, { "at": 9.1, "vol": 0.5 }],
+"interrupts": [{ "at": 14.0, "kind": "question-card" }],
+"elements": [{ "at": 0.6, "kind": "text" }]
+```
+
+### `ducking[]`
+
+Written by `python3 scripts/sound.py duck TIMELINE --write`. One window per group of SFX that sound over the **start of a spoken word**; nothing else ducks.
+
+```json
+{
+  "start": 5.37,
+  "end": 6.05,
+  "depth_db": 4.0,
+  "attack_s": 0.03,
+  "release_s": 0.2,
+  "from_frame": 161,
+  "to_frame": 182,
+  "cause": "verdict@5.400s over word 'price'@5.500s"
+}
+```
+
+Shape of each window: the gain ramps linearly from 0 dB to `-depth_db` over `attack_s` starting at `start` (so full depth is in place when the SFX hits), holds, then ramps back to 0 dB over the last `release_s` before `end`. Overlapping windows are merged, deepest depth wins. Numbers come from the `ducking` block of the config, which marks them as an extrapolation without a primary source.
+
+Remotion volume callback for the narration (same math as `gain_db_at` in `sound.py`). `frame` is relative to the `<Audio>`, so add the narration's start frame when it does not start at 0:
+
+```tsx
+type Duck = { start: number; end: number; depth_db: number; attack_s: number; release_s: number };
+
+export const narrationVolume = (ducking: Duck[], fps: number, startFrame = 0) => (frame: number) => {
+  const t = (frame + startFrame) / fps;
+  let db = 0;
+  for (const w of ducking) {
+    if (t < w.start || t > w.end) continue;
+    let shape = 1;
+    if (t < w.start + w.attack_s) shape = (t - w.start) / w.attack_s;
+    else if (t > w.end - w.release_s) shape = (w.end - t) / w.release_s;
+    db = Math.min(db, -w.depth_db * Math.max(0, Math.min(1, shape)));
+  }
+  return Math.pow(10, db / 20);
+};
+
+// <Audio src={staticFile(narration)} volume={narrationVolume(data.ducking, fps)} />
+```
+
+## Minimal example
+
+```json
+{
+  "fps": 30,
+  "duration": 12.0,
+  "safe_zone_profile": "ad",
+  "words": [
+    { "text": "Stop", "start": 0.2, "end": 0.5 },
+    { "text": "scrolling", "start": 0.55, "end": 1.1 },
+    { "text": "this", "start": 1.6, "end": 1.8 },
+    { "text": "costs", "start": 1.85, "end": 2.2 },
+    { "text": "nine", "start": 5.5, "end": 5.8 }
+  ],
+  "scenes": [
+    { "start": 0.0, "dur": 5.0, "transition": "cut" },
+    { "start": 5.0, "dur": 7.0, "transition": "whip", "sfx": { "event": "block_cut", "src": "sfx/whoosh.mp3", "vol": 0.55 } }
+  ],
+  "sfx": [{ "at": 5.4, "event": "price", "src": "sfx/cash.mp3", "vol": 0.55 }],
+  "punches": [1.35],
+  "flashes": [],
+  "shakes": [],
+  "interrupts": [],
+  "elements": [{ "at": 0.6, "kind": "text" }],
+  "ducking": []
+}
+```
+
+## Which script touches what
+
+| Script | Reads | Writes | Exit codes |
+| --- | --- | --- | --- |
+| `fill_breaths.py TIMELINE [--narration F@OFF] [--visual MP4] [--write\|--out P]` | `words`, `scenes`, effects, `sfx`, `duration` | `scenes[].transition`, `scenes[].sfx`, `punches`, `flashes`, `sfx` | 0, 2 |
+| `sound.py duck TIMELINE [--write]` | `sfx`, `scenes[].sfx`, `words`, `fps` | `ducking` | 0, 2 |
+| `check_excess.py TIMELINE... [--warn]` | effects, `scenes`, `duration` | nothing | 0 pass, 1 fail, 2 error |
+| `check_rhythm.py TIMELINE...` | `scenes`, effects, `elements`, `duration` | nothing | always 0 (warn only) |
+| `check_safe_zone.py MP4 [--timeline T]` | `safe_zone_profile` | nothing | 0, 1, 2 |
+| `measure_density.py MP4 [--timeline T]` | `safe_zone_profile` | nothing | 0, 1, 2 |
+| `check_loudness.py MP4` | the final file only | nothing | 0, 1, 2 |

package/src/skills-lib/wizz-video-effects/references/do-not-use.md

@@ -0,0 +1,54 @@
+# What this system does not do
+
+A catalogue says what is possible; this page says what was already decided, so the discussion does not repeat. Every line has a reason. A refusal without a reason is fashion, and fashion changes; a refusal with a reason is a rule.
+
+Before proposing a new effect, look for it here. If it is listed, it is not a gap, it is a decision, and reopening it needs a new argument. If it is neither here nor in [when-to-use.md](when-to-use.md), it is undecided territory: propose it **with its "do not use when" already written**. An effect without a refusal rule does not enter this system.
+
+## Cut for legibility
+
+These pieces sell by being read in three seconds on a phone. Anything that dirties the image works against that.
+
+| Effect | Reason |
+|---|---|
+| Film grain | adds noise to an image whose job is to be sharp |
+| VHS, scanlines | degradation aesthetic over a product sold as modern |
+| Dust, scratches | same problem, and unrelated to the subject |
+| Vignette | darkens corners where the layout already places content, and eats the safe zone |
+| Light leak | removes contrast from text exactly where it is unpredictable |
+| Chromatic aberration | illegibility pretending to be style, worst on small text |
+| Letterbox | in a vertical format it is lost area where space is already short |
+
+The 2026 research found VHS and grain described as a trend only for brand and aesthetic content, never for performance ads with product and price on screen ([editing-patterns.md](editing-patterns.md)).
+
+## Cut for cost without return
+
+| Effect | Reason |
+|---|---|
+| Liquid, morph | complex, fragile in deterministic render, no evidence of retention |
+| Lens distortion | same, and it fights the safe zone in ways that are hard to measure |
+| Particles | heavy to render, and in a UI creative they illustrate nothing |
+
+## Cut for contradicting a rule of the system
+
+- **Crossdissolve and fade between takes.** The default is the hard cut: in vertical short video the cut is what holds attention. Fade only at the very start or end, if ever.
+- **Automatic beat detection.** The beat of a narrated piece is the voice, and forced alignment (ctc-align) gives speech boundaries to the millisecond. A beat detector would give a worse signal over a clock that is already better.
+- **Speed ramp.** Over narration it desynchronises speech from screen, and speech anchors all timing.
+- **Typewriter out of context.** Only where the narration talks about writing. It competes with the first sentence, which is the most expensive sentence of the piece.
+- **More shake to raise dynamism.** The refusal that repeats most in production: dynamism grows through **cut, punch, element entrance and new scene**, never through more vibration. Shake and drift are seasoning.
+- **Meme sounds** ("vine boom", "record scratch", "glitch"). No performance data and a comedy tone; see [sfx-licensing.md](sfx-licensing.md).
+- **Trending picker audio in ads.** Licensing, not taste; see [sfx-licensing.md](sfx-licensing.md).
+
+## Avatar rule, which is also a refusal
+
+**No reused avatar clip. No lip sync against audio that is not this piece's audio.** Without a take generated with the exact words of that block, the piece goes out **without the avatar**, in screens only. A whole piece was once rejected because the actor's mouth said last week's script while a gate showed green.
+
+## Waiting list (gaps, not refusals)
+
+A refusal closes a discussion; a gap invites it.
+
+| Missing | Status |
+|---|---|
+| Background music | the most expensive open decision, because of licence and mix. The config accepts an optional music bed; the file must come from a source cleared for the piece's platform |
+| Callouts | often requested, never built. For offers that demonstrate screens it is what is most missed |
+| Re-enabling a giant-word overlay (`textpunch`) | it must go through the layout bands first; drawn on top of the frame it ignored the stage |
+| Silence before the CTA | no reliable source; test as A/B, not as a rule |

package/src/skills-lib/wizz-video-effects/references/editing-patterns.md

@@ -0,0 +1,58 @@
+# Editing patterns for ads and Reels: what has a source, and what does not
+
+Research done on 2026-09-24 with real web sources (every link below was accessed that day). Each claim is tagged:
+
+- **DATA**: official platform documentation, or a named vendor with real measurement infrastructure.
+- **OPINION**: agency, creator or tool blog. Most "2026 benchmark" results on the web come from a cluster of look-alike blogs with no sample, method or primary source; treat their numbers as planning hints, never as a gate.
+
+The rule for this skill follows from the tags: **a number backed only by OPINION becomes a config default that warns, never a gate that blocks.**
+
+## Hook (0 to 3 s)
+
+- **DATA.** Hook rate (thumb-stop ratio) is 3-second plays divided by impressions in Meta Ads Manager. The hook window of this skill is therefore 3 s (`rhythm.hook_s`). Sources: [Coinis glossary](https://coinis.com/glossary/hook-rate), [Adrio](https://adrio.ai/blog/thumbstop-rate-vs-hook-rate-vs-hold-rate).
+- **DATA.** TikTok recommends stating the content's proposition in the first 3 seconds and says top ads use pattern interrupts (unexpected visual, bold claim, curiosity gap) that stop the scroll in 2 to 3 s. [TikTok Ads Help, creative best practices](https://ads.tiktok.com/help/article/creative-best-practices).
+- **OPINION.** "Good" hook rate: floor 25%, good 30 to 40%, elite 40%+. [Motion, Creative Benchmarks 2026](https://motionapp.com/thumbstop-pulse/creative-benchmarks-2026) (full report not readable).
+- **Consequence here:** the first frame already moves and already says something. The budget curve gives the hook a small bonus, never a spike: dynamism is spread over the whole video, not packed into the opening.
+
+## Rhythm and retention in the body
+
+- **DATA.** ThruPlay = watched to 15 s or to the end if shorter. Hold rate = viewers reaching 15 s (or 75%) divided by viewers past 3 s; it isolates body retention from the hook. [AdSights, ThruPlay](https://www.adsights.ai/resources/glossary/metrics/thruplay), [AdSights, hold rate vs ThruPlay](https://www.adsights.ai/resources/comparisons/hold-rate-vs-thruplay-rate).
+- **OPINION.** Cut cadence: TikTok every 1.5 to 3 s, Reels every 2.5 to 4 s, "change something on screen every 3 to 5 s". [edicionvideopro](https://edicionvideopro.com/en/editing-for-platforms-video-marketing/pattern-interrupts-tiktok-retention-guide/). No primary source.
+- **In this skill:** `rhythm.max_static_s` (longest stretch with no visual change), `rhythm.hook_cut_every_s` and `rhythm.body_cut_every_s` are defaults read by `check_rhythm.py`, which **warns only**.
+
+## Call to action
+
+- **OPINION.** Repeat the CTA visually mid-offer and again on the final frame (end card): name, plain-language offer, CTA, high contrast. [Sovran](https://sovran.ai/blog/direct-response-video-ad-endings).
+- **In this skill:** a documentation rule, not a gate. The CTA itself is a script decision (who says what, and when) and belongs to the script, not to the edit. In the CTA block the edit lowers effect density: no punch or zoom on the final card, price and button readable.
+
+## Captions and on-screen text
+
+- **DATA (historical).** 80 to 85% of feed video is watched without sound ([Digiday, 2016-05-17](https://digiday.com/media/silent-world-facebook-video/)). The number is from 2016 and is repeated, not re-measured; it still justifies designing sound-off first.
+- **OPINION.** Word-by-word (karaoke) captions dominate in 2026; high contrast (white or yellow with black outline), lower-middle third. [OpusClip](https://www.opus.pro/blog/tiktok-caption-subtitle-best-practices).
+- **In this skill:** captions come from the ctc-align word timestamps; the caption band is exclusive (nothing readable inside it); every claim that matters is also on screen as text, because the SFX never carries critical information.
+
+## Two safe zones, not one
+
+| Profile | Source | Numbers |
+|---|---|---|
+| `ad` | **DATA**, [Meta Business Help Center: text overlays and the Safe Zone for ads in Stories and Reels](https://www.facebook.com/business/help/980593475366490/) | keep about 14% top, 35% bottom and 6% each side free of text, logo and key elements |
+| `organic` | **OPINION** ([campaignswift](https://campaignswift.com/blog/instagram-safe-zone-sizes), [pod2reels](https://www.pod2reels.com/blog/instagram-reels-safe-zone-guide)) plus measurement from production | the organic Reels UI (profile, caption, like/comment/share column, audio line) covers roughly 320 to 400 px at the bottom of a 1080x1920 frame and the right column |
+
+The piece declares its profile; `check_safe_zone.py` measures against that profile. A piece that runs both as an ad and as an organic post is checked against both.
+
+## Organic reach on Instagram
+
+- **DATA.** Adam Mosseri, reported 2025-01-22: the three signals that matter most for ranking are watch time, likes per reach and sends per reach; sends weigh more for reaching non-followers. [Social Media Today](https://www.socialmediatoday.com/news/instagram-shares-algorithm-insights-2025/738034/). The "a send is worth 3 to 15 likes" multipliers found on blogs do not appear in any direct quote: do not use them.
+- **DATA.** Accounts that repost third-party content 10+ times in 30 days are excluded from recommendations; the original is shown instead of near-identical reposts. [MediaPost](https://www.mediapost.com/publications/article/414773/instagram-algorithm-update-discourages-reposted-co.html), [PetaPixel, 2026-04-30](https://petapixel.com/2026/04/30/new-instagram-policies-target-reposted-content/).
+- **Consequence for editing:** originality is a distribution rule, not taste. Each piece gets its own screens and its own dynamics; reuse the technical structure (bands, gates, data contract), never the composition.
+
+## What reads as dated
+
+- **OPINION, contradictory.** Some sources call VHS, scanlines and grain a 2026 trend; the same searches say heavy production lost ground to "barely edited" authenticity. Where VHS appears as a trend, it is brand or aesthetic content, never performance ads with product and price on screen. The refusals in [do-not-use.md](do-not-use.md) stand.
+- **OPINION.** Classic talking head, ring-light testimonial and USP list are recognised as ads "in half a second" ([Pixis](https://pixis.ai/blog/ugc-in-2026-whats-working-whats-stale-and-how-to-refresh-your-hook-library/)).
+
+## Gaps (recorded, not hidden)
+
+- "Silence before the CTA" as a practice: no reliable dated source found. It is an A/B hypothesis, not a rule.
+- The pattern-interrupt retention figure (58% vs 32%) and the "zoom +68% engagement" figure have no primary source.
+- Meta's official video spec page returned 403; length guidance (6 to 15 s feed vs 15 to 60 s) comes from blogs and describes awareness use, not direct-response selling.

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

@@ -0,0 +1,37 @@
+# Gates: what each one measures, and what none of them sees
+
+Two sentences this system paid to learn, more than once: **a gate that checks a different file from the one that will be rendered is not a gate**, and **green without proof is worth less than red**, because red at least says something needs eyes.
+
+Thresholds are cited by config key. Every script exits `0` pass, `1` fail, `2` input missing or unreadable, so a pipeline can chain them with `set -e`.
+
+## The table
+
+| Gate | Runs on | Measures | Blocks? | What it does NOT see |
+|---|---|---|---|---|
+| `config.py` | the config | coherence of every block (ranges, event volumes under `sound.relative_ceiling`, budget values); refuses the whole config on the first error | yes | whether the numbers are right for this offer |
+| `sound.py coverage` | config + SFX folder | sounds no event uses, events pointing at a missing file | reports | whether the sound fits the event (that is taste, reviewed by ear) |
+| `normalize_audio.py --check` | SFX folder | every file at `sound.reference_level_db`, peak under `sound.max_peak_db` | yes | silent tails: it measures the whole file, so trim first |
+| `check_excess.py` | timeline JSON | every sound together (`sfx[]` and scene cut sounds) against the three refusals: unknown event, collision, same sound in a row; per effect kind: ceiling per minute, smallest gap, longest run in a row (`budget.per_effect.*`); dominant effects of different kinds closer than `budget.gap_min_global`; always reports the densest 10 s cluster | yes (`--warn` only while calibrating) | effects drawn inside the screens themselves (HyperFrames timelines); only what the timeline declares |
+| `check_rhythm.py` | timeline JSON | longest stretch with no visual change (`rhythm.max_static_s`), cut cadence in the hook (`rhythm.hook_s`, `rhythm.hook_cut_every_s`) and body (`rhythm.body_cut_every_s`), CTA tail excluded (`rhythm.cta_tail_s`). SFX never count as change | **no, warns only** | motion inside a screen; its numbers come from weak sources ([editing-patterns.md](editing-patterns.md)) |
+| `check_safe_zone.py` | **final MP4** | per row, local contrast (std-dev, `safe_zone_gate.dp_min`) on every frame; the highest and lowest content rows must sit inside the piece's profile (`safe_zones.<profile>` top and bottom) | yes | whether what invades is text, a card or background glow; left and right edges. Full-screen footage fails by construction: frame it inside the zone. On a fail, extract the frame and look |
+| `measure_density.py` | **final MP4** | how many of `density.n_bands` bands across the active safe zone have content (`density.dp_min`), sampled every `density.step_s`; fails under `density.min_filled` | yes | whether the content makes sense there: a band full of noise counts like a band full of information |
+| `check_loudness.py` | **final MP4 or audio** | integrated loudness and true peak (ffmpeg `loudnorm`) against `loudness.*`; prints the two-pass fix and warns when the fix will switch loudnorm to dynamic compression | yes | the balance inside the mix (voice vs SFX); that is the level contract and the ear |
+
+Order that matches the pipeline: config and coverage once per project; excess and rhythm on the timeline before the expensive render; safe zone, density and loudness on the final file.
+
+## Two profiles, measured separately
+
+The safe zone depends on where the piece runs: `safe_zones.ad` (Meta's ad guidance for Stories and Reels) and `safe_zones.organic` (the organic Reels UI). The timeline's `safe_zone_profile` picks the one to measure. A piece that runs as ad and as organic post passes both: run `check_safe_zone.py` again with `--profile` for the other one.
+
+## Failures already paid for
+
+- **A gate that could never fail.** The density measurement once ran with `|| true` in the build script and never rejected anything. A gate that cannot fail is decoration.
+- **Verified the wrong file.** A voice check matched files by basename while the render played a different file with the same name; five pieces went green with old audio. Match by path, measure the file that renders.
+- **Measured before the render finished.** A file read while still being written returned a plausible number over a third of the film. Unreadable samples are an error, never skipped.
+- **Sampling missed the peak.** One frame per second missed entry animations lasting tenths of a second; the safe-zone gate decodes every frame.
+- **Micro-zoom ate the margin.** An element 10 px inside the safe zone in the screen render crossed it in the final file, because the assembly scales the whole frame. Measure the final MP4, never the isolated screen.
+- **A threshold that always fails gets bypassed by habit.** The safe-zone gate inherited the density threshold and flagged background glow on almost every frame; it now has its own (`safe_zone_gate.dp_min`).
+
+## What no gate replaces
+
+Every gate here can be green with a broken frame: a chip rendered blank, the actor covering the price, a mouth saying last week's script. **Extract frames from the final file and look**, including one frame of the CTA block, every time.