wizz-method 2.11.2 → 2.13.0

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.

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.