wizz-method 2.11.2 → 2.13.0

package/src/skills-lib/wizz-video-effects/assets/effects.config.template.json

@@ -0,0 +1,178 @@
+{
+  "_readme": "Every canonical number of the effects engine lives HERE. A doc cites the key, never rewrites the value: a number copied to a second place ends up with two versions. Copy this file to your project as effects.config.json and fill `offer`. Keys starting with `_` are notes and are ignored by the loader. A key whose number has a weak source carries a sibling `_source`.",
+  "version": 1,
+  "offer": "",
+
+  "paths": {
+    "media_root": "public",
+    "sfx_subdir": "sfx",
+    "_note": "Both relative to the folder that holds this config. media_root is what the renderer serves (Remotion `public/`); sound `src` values written into the timeline are relative to it (e.g. `sfx/pop.mp3`). Every script also accepts --sfx-dir to override."
+  },
+
+  "frame": {
+    "width": 1080,
+    "height": 1920,
+    "fps": 30,
+    "_note": "9:16 vertical. No script assumes this resolution: they all read it from here."
+  },
+
+  "safe_zone_profile": "organic",
+  "_safe_zone_profile": "Default profile. A timeline JSON can override it per piece with a top-level `safe_zone_profile`. The safe-zone and density gates measure against the declared profile.",
+  "safe_zones": {
+    "organic": {
+      "top": 250,
+      "bottom": 1570,
+      "left": 60,
+      "right": 920,
+      "recommended_margin": 30,
+      "_source": "Organic Reels/TikTok UI, measured on real pieces of the project this engine came from. The right edge is tighter than the left because the interaction icon column lives there. Third-party guides put the organic bottom UI at 320-400px on 1080x1920 (low to medium credibility, no own measurement)."
+    },
+    "ad": {
+      "top": 269,
+      "bottom": 1248,
+      "left": 65,
+      "right": 1015,
+      "recommended_margin": 30,
+      "_source": "Meta Business Help Center, 'About text overlays and the Safe Zone for ads in Stories and Reels' (https://www.facebook.com/business/help/980593475366490/): keep ~14% top, ~35% bottom and ~6% each side free of text, logo and key elements. Converted on 1080x1920: top 0.14*1920=268.8 -> 269, bottom 1920-0.35*1920=1248, sides 0.06*1080=64.8 -> 65 and 1015. Read from the indexed summary of the page on 2026-09-24, not the full HTML."
+    }
+  },
+
+  "safe_zone_gate": {
+    "dp_min": 15.0,
+    "edge_artifact_rows": 3,
+    "min_rows_to_fail": 10,
+    "sample_width": 216,
+    "_dp_min": "Row contrast (horizontal std-dev of luma) that counts as legible content. Own threshold, not density.dp_min: density asks 'is there anything here?', the safe zone asks 'is there LEGIBLE TEXT past the line?'. Measured on a real piece: real text 69, background glow and grid 7.0 to 8.6.",
+    "_edge_artifact_rows": "Rows ignored at each frame edge: the encoder leaves 1 to 2 dark pixels at the border, which pass dp_min on a light background without being content.",
+    "_min_rows_to_fail": "Below this many invading rows the gate warns instead of failing: a whole label past the line measured 27 rows, a rounded card corner grazing it measured 6."
+  },
+
+  "density": {
+    "n_bands": 7,
+    "min_filled": 3,
+    "dp_min": 7.0,
+    "step_s": 0.5,
+    "sample_width": 216,
+    "_note": "Uniform bands between the active safe zone top and bottom, only to measure how full the frame is. Measures local contrast (std-dev of luma), never mean brightness: a light background makes mean brightness pass everything.",
+    "_source": "min_filled 3 of 7 is a house rule of the source project, not an external benchmark."
+  },
+
+  "budget": {
+    "_readme": "The anti-excess engine. An effect only enters if its curve section still has budget, it respects the minimum distance and it does not repeat too much. When two candidates collide, the higher narrative strength wins.",
+    "gap_min_global": 2.0,
+    "burst_gap_s": 5.0,
+    "_burst_gap_s": "Two same-type effects further apart than this are not read as one burst: the viewer had visual rest between them. Also the widest hole fill_breaths.py tries to close.",
+    "per_effect": {
+      "punch": { "max_per_min": 10, "gap_min": 3.5, "max_in_row": 2, "dominant": true },
+      "flash": { "max_per_min": 10, "gap_min": 2.5, "max_in_row": 3, "dominant": false },
+      "shake": { "max_per_min": 3, "gap_min": 8.0, "max_in_row": 1, "dominant": true, "max_dur_s": 0.25 },
+      "interrupt": { "max_per_min": 7, "gap_min": 8.0, "max_in_row": 1, "dominant": true },
+      "transition": { "max_per_min": 30, "gap_min": 1.2, "max_in_row": 2, "dominant": false }
+    },
+    "_per_effect": "House numbers of the source project, tuned on 14 pieces after an audit measured one zoom punch every 2.5s. No external source.",
+    "curve": [
+      { "name": "hook", "until_frac": 0.06, "weight": 1.2 },
+      { "name": "body", "until_frac": 0.86, "weight": 1.0 },
+      { "name": "cta", "until_frac": 1.0, "weight": 1.2 }
+    ],
+    "_curve": "Weights are almost flat on purpose: dynamism belongs to the WHOLE video, never concentrated in the hook. Hook and CTA get 20% more, nothing else."
+  },
+
+  "sound": {
+    "_readme": "Which sound marks which happening. The key is SEMANTIC (what is happening in the story), never the file name. Changing SFX library means changing the `sound` column, without touching any rule.",
+    "narration_volume": 1.0,
+    "relative_ceiling": 0.65,
+    "_relative_ceiling": "No event `vol` may exceed relative_ceiling * narration_volume. A SFX that competes with the voice steals attention instead of marking it.",
+    "max_same_sound_in_row": 3,
+    "collision_window_s": 0.08,
+    "_collision_window_s": "Two sounds closer than this are heard as one dirty sound. House number, no external source.",
+    "reference_level_db": -20.0,
+    "max_peak_db": -3.0,
+    "_levels": "Level contract for every SFX file (normalize_audio.py): mean at reference_level_db, peak locked at max_peak_db, the peak always wins. The `vol` table below only means something if every file starts from the same level. Measured on a real piece: narration at -20.6 dB mean, an un-normalized whoosh ended at -36.1 dB after its vol, i.e. inaudible. An accent sits 6 to 10 dB under the voice.",
+    "_strength": "When an event has `triggers`, `strength` (0..1) is the narrative weight of the visual effect it fires, independent from `vol`: volume is mix, strength is how much the moment matters.",
+    "bed": {
+      "ambience": { "file": "bed/ambience.mp3", "vol": 0.13 },
+      "music": { "file": "bed/music.mp3", "vol": 0.2 },
+      "_readme": "OPTIONAL continuous layers under everything, relative to paths.media_root. Each enters only if the file exists; a missing file never breaks a render. Music must come from a source cleared for the piece's platform and use (paid ad vs organic)."
+    },
+    "events": {
+      "block_cut": { "sound": "whoosh", "vol": 0.55, "when": "switch of narrative block" },
+      "scene_cut": { "sound": "whoosh", "vol": 0.45, "when": "screen change inside the same block" },
+      "element_in": { "sound": "pop", "vol": 0.5, "when": "a card, line or label enters" },
+      "text_in": { "sound": "riser-metal", "vol": 0.42, "when": "a TEXT card enters: headline, title, anchor sentence" },
+      "list_item": { "sound": "coin", "vol": 0.42, "when": "item of a repeating list; the checklist plink" },
+      "verdict": {
+        "sound": "stamp",
+        "vol": 0.65,
+        "strength": 0.95,
+        "when": "verdict, seal or decision slammed down",
+        "triggers": ["shake"]
+      },
+      "message": { "sound": "notif", "vol": 0.55, "when": "a message, notification or alert arrives" },
+      "typing": { "sound": "type", "vol": 0.35, "when": "text being typed on screen" },
+      "paste": { "sound": "paste", "vol": 0.45, "when": "copy or paste" },
+      "click": { "sound": "click", "vol": 0.4, "when": "interface interaction, cursor, tap" },
+      "send": { "sound": "send", "vol": 0.5, "when": "send, publish, submit" },
+      "price": { "sound": "cash", "vol": 0.55, "when": "the price appears or changes" },
+      "gain": { "sound": "coin", "vol": 0.45, "when": "value gained, savings, counter going up" },
+      "done": { "sound": "success", "vol": 0.55, "when": "check, ready, task done" }
+    }
+  },
+
+  "ducking": {
+    "depth_db": 4.0,
+    "attack_ms": 30,
+    "release_ms": 200,
+    "assumed_sfx_duration_s": 0.4,
+    "_source": "extrapolation, no primary source. Research proposal: 3-6 dB depth, attack < 50 ms, release 150-300 ms, applied only when a transient SFX collides with the start of a spoken word. Derived from music-under-voice ducking guides (18-25 dB, attack < 300 ms, release 300-700 ms), which target a continuous bed, not short SFX.",
+    "_assumed_sfx_duration_s": "Used only when neither the timeline nor the file on disk gives a SFX duration."
+  },
+
+  "loudness": {
+    "target_lufs": -14.0,
+    "tolerance_lu": 1.0,
+    "max_true_peak_db": -1.0,
+    "lra": 11.0,
+    "encode_tp_margin_db": 1.0,
+    "_encode_tp_margin_db": "Measured on the test piece (2026-09-24): re-encoding the loudnorm output to AAC pushed the true peak from -1.0 to -0.8 dBTP, so the fix command failed its own gate. For lossy outputs the printed fix aims this much under max_true_peak_db.",
+    "_source": "Industry mastering practice for TikTok and Reels (-14 LUFS integrated, -1 dBTP), replicated by mastering guides; neither TikTok nor Meta publishes an official loudness spec. Mastering louder does not help: the platform turns it down and may distort on re-encode. lra is the ffmpeg loudnorm default, used only by the printed fix command."
+  },
+
+  "rhythm": {
+    "max_static_s": 5.0,
+    "hook_s": 3.0,
+    "hook_cut_every_s": 3.0,
+    "body_cut_every_s": [2.5, 4.0],
+    "cta_tail_s": 3.0,
+    "counts_as_change": ["scenes", "punches", "shakes", "flashes", "interrupts", "elements"],
+    "_source": "Weak source: pattern-interrupt and pacing blogs (change something every 3-5s; Reels cuts every 2.5-4s) plus the 3-second hook rate metric of Meta Ads Manager. That is why check_rhythm.py only warns, never blocks.",
+    "_hook_s": "Owner decision: the hook closes at 3s.",
+    "_cta_tail_s": "No source. Seconds at the end excluded from the body cadence, because the CTA lowers effect density on purpose to keep price and button legible."
+  },
+
+  "breaths": {
+    "min_silence_s": 0.22,
+    "silence_db": -30,
+    "edge_guard_s": 0.4,
+    "fast_speech_wps": 2.8,
+    "punch_peak_scale": 1.066,
+    "pace_profiles": {
+      "first": { "transition": "cut", "sound_event": "block_cut" },
+      "fast": { "transition": "whip", "sound_event": "block_cut" },
+      "slow": { "transition": "zoom", "sound_event": "element_in" }
+    },
+    "punch_sound_event": "element_in",
+    "_note": "An effect anchors in the real silence of speech, in the MIDDLE of the silence, never glued to a word. Below min_silence_s a gap is a pause between syllables, not a breath. punch_peak_scale is the real peak of a punch multiplied by the continuous micro-zoom (1.035 * 1.03); a point closer to the frame edge than the zone edge divided by it leaves the safe zone at the peak.",
+    "_fast_speech_wps": "House number: words per second above which a block reads as a burst and gets an aggressive cut. No external source."
+  },
+
+  "avatar": {
+    "_optional": "Only for pieces with a generated avatar. Delete the block otherwise.",
+    "max_full_shot_s": 4.5,
+    "max_occlusion_s": 5.0,
+    "max_take_s": 6.0,
+    "variation_step_s": 4.0,
+    "min_variation_s": 1.2,
+    "_source": "The gesture cycle of a generated avatar is around 7.5s and then visibly repeats. Every ceiling here derives from that observation on one provider; re-measure for another."
+  }
+}

package/src/skills-lib/wizz-video-effects/assets/remotion/EffectsLayer.tsx

@@ -0,0 +1,87 @@
+// Reference layer that plays a wizz-video-effects timeline in Remotion.
+// Copy into the project and adapt; see README.md.
+import React from "react";
+import { AbsoluteFill, Sequence, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+import { Audio } from "@remotion/media";
+import {
+  EffectsTimeline,
+  allSounds,
+  flashOpacity,
+  instants,
+  narrationVolume,
+  punchScale,
+  shakeOffset,
+  transitionAt,
+} from "./useEffects";
+
+/** Narration with the ducking callback, plus every SFX at its `at` and `vol`. */
+export const EffectsAudio: React.FC<{
+  timeline: EffectsTimeline;
+  narrationSrc: string;
+  narrationStart?: number; // seconds
+}> = ({ timeline, narrationSrc, narrationStart = 0 }) => {
+  const { fps } = useVideoConfig();
+  const startFrame = Math.round(narrationStart * fps);
+  return (
+    <>
+      <Sequence from={startFrame} name="narration">
+        <Audio
+          src={staticFile(narrationSrc)}
+          volume={narrationVolume(timeline.ducking ?? [], fps, startFrame)}
+        />
+      </Sequence>
+      {allSounds(timeline).map((s, i) => (
+        <Sequence key={`sfx-${i}`} from={Math.round(s.at * fps)} name={`sfx ${s.event ?? s.src}`}>
+          <Audio src={staticFile(s.src)} volume={s.vol} />
+        </Sequence>
+      ))}
+    </>
+  );
+};
+
+/** Shake moves everything inside it. Put the whole stage here, never the captions alone. */
+export const ShakeStage: React.FC<{ timeline: EffectsTimeline; children: React.ReactNode }> = ({
+  timeline,
+  children,
+}) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const { x, y } = shakeOffset(frame / fps, instants(timeline.shakes));
+  return <AbsoluteFill style={{ transform: `translate(${x}px, ${y}px)` }}>{children}</AbsoluteFill>;
+};
+
+/** Punch and scene transitions scale the shot. Wrap only the shot (footage or
+ *  screen), inside a container with overflow hidden: scaling the whole frame
+ *  pushes text through the safe zone at the peak. */
+export const PunchShot: React.FC<{ timeline: EffectsTimeline; children: React.ReactNode }> = ({
+  timeline,
+  children,
+}) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const t = frame / fps;
+  const tr = transitionAt(frame, fps, timeline.scenes ?? []);
+  const scale = punchScale(t, instants(timeline.punches)) * tr.scale;
+  return (
+    <AbsoluteFill
+      style={{
+        transform: `translateX(${tr.x}px) scale(${scale})`,
+        filter: tr.blurPx > 0 ? `blur(${tr.blurPx}px)` : undefined,
+      }}
+    >
+      {children}
+    </AbsoluteFill>
+  );
+};
+
+/** Opacity-only flash: moves no pixel, so it fits where a punch does not. */
+export const FlashOverlay: React.FC<{ timeline: EffectsTimeline; color?: string }> = ({
+  timeline,
+  color = "#FFFFFF",
+}) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const opacity = flashOpacity(frame / fps, instants(timeline.flashes));
+  if (opacity <= 0) return null;
+  return <AbsoluteFill style={{ backgroundColor: color, opacity, pointerEvents: "none" }} />;
+};

package/src/skills-lib/wizz-video-effects/assets/remotion/README.md

@@ -0,0 +1,37 @@
+# Remotion reference layer
+
+Reference code to **copy into your Remotion project** (for example `src/effects/`) and adapt. It is not a package and nothing imports it from here.
+
+It plays a timeline written by this skill's scripts ([../../references/data-contract.md](../../references/data-contract.md)):
+
+| Export | File | Does |
+|---|---|---|
+| `EffectsAudio` | `EffectsLayer.tsx` | narration with the `ducking[]` volume callback, every `sfx[]` entry and every scene cut sound at its `at` and `vol` |
+| `ShakeStage` | `EffectsLayer.tsx` | short decaying tremor on `shakes[]`, never longer than `SHAKE.durS` |
+| `PunchShot` | `EffectsLayer.tsx` | zoom pulse on `punches[]` and the `zoom` / `whip` scene transitions |
+| `FlashOverlay` | `EffectsLayer.tsx` | opacity-only flash on `flashes[]` |
+| pure math | `useEffects.ts` | the same functions, frame in, value out, deterministic |
+
+Usage sketch:
+
+```tsx
+<AbsoluteFill>
+  <ShakeStage timeline={tl}>
+    <div style={{ position: "absolute", overflow: "hidden", ...shotBox }}>
+      <PunchShot timeline={tl}>{/* silent screen or footage */}</PunchShot>
+    </div>
+    {/* cards and captions of the piece */}
+  </ShakeStage>
+  <FlashOverlay timeline={tl} />
+  <EffectsAudio timeline={tl} narrationSrc="narration.mp3" />
+</AbsoluteFill>
+```
+
+Rules the layer assumes:
+
+- It draws what the timeline says and decides nothing. How many effects and where was decided by the scripts and the budget.
+- Wrap only the shot in `PunchShot`, inside a box with `overflow: hidden`. Scaling the whole frame pushes captions and cards through the safe zone at the peak.
+- Shake constants (`SHAKE`, `PUNCH`, `FLASH`, `TRANSITION` in `useEffects.ts`) shape one accepted effect; they are component constants, not budget numbers.
+- `src` values are relative to Remotion `public/` (`staticFile`), as the data contract says.
+
+For the Remotion API itself (`<Audio>`, `<Sequence>`, `<Video>` props such as `objectFit`), invoke the `wizz-remotion-best-practices` skill.

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.