# Direction: from what the person gave to the film in one line

Read this at step 3, whole. The quality of the video is decided here, before a line of scene code: a clear direction
turns into a good plan, a vague one into a generic reel that no check can rescue.

## Contents
1. Read everything, in this order
2. What the input is → what the hero is
3. Where it plays → the opening, the sound, the format
4. The brand's own voice
5. Energy, mood and the sound's role
6. Three concepts, one film
7. The direction card
8. Worked directions (eight briefs)
9. Brief contagion: the defaults every model reaches for

## 1. Read everything, in this order

1. **The person's words** win over everything below, in any language: how it should feel ("dynamic", "calm",
   "like Apple"), a genre ("phonk", "rock"), a length, a format, where it will run, what to show. Quote them in the
   direction card — words in another language with their English gloss in quotes after them — and the plan and the
   checks hold the video to them (`tools/plan-check.mjs` reads the Energy line, in English).
2. **What they gave** (§2): a site, a repository, an app, screenshots, a recording, photos, a logo, only a name.
3. **Where it plays** (§3), said or implied: a release post on X, Reels, a site header, a pitch.
4. **The brand's voice** (§4): how its copy talks, its colours and type, how its own interface moves, who it serves.
5. **References**, when given: their pace, their music arc and their techniques (`ref-sheet.mjs`, step 2). None
   given: the two closest patterns in `wow-library.md` set the bar.
6. **The topic** last: a car parts shop and a clinic differ, but two clinics differ too — the topic alone makes every
   brand of a kind look the same.

Write what you read in one line per signal before deciding anything; a direction is only as good as what it read.

## 2. What the input is → what the hero is

The best videos make the real thing the hero: the product's own interface, its own data, its own words. Invented UI,
invented numbers and a logo redrawn from memory read as fake at once.

| Given | The hero | Take from it | Watch out |
|---|---|---|---|
| A site | its UI and its promise | `site-kit.mjs`: colours, fonts, logo, sections; `ui-shot.mjs` for single elements (a card, a button, a chart) on a transparent ground | the site's cookie banner and chat bubble are not the brand |
| A GitHub repository | the tool at work: the terminal, the code, the output, the diff | the README's promise and feature list, the install command, a real example from the docs, release notes; numbers only as the page states them (stars, contributors, commits) | GitHub's own interface is not the brand — take the project's logo, colours and wording; a repo with no brand gets a look chosen for its audience (`look-cards.md`) |
| A service or an app | a flow the viewer recognises: a tap, a result, a number going the right way | real screens (site-kit sections, ui-shot, the user's screenshots); the one action that shows the value | never draw a screen that does not exist; a state the screenshots lack is staged on the page copy (`ui-shot --eval`) and said in the report |
| Screenshots only | the UI in them, animated | crops at 2×, the palette from them (`palette.mjs`) | personal data in them never reaches the video |
| A screen recording | the product at work, zoomed to where it happens | `footage.mjs scan`: where the picture changes, second by second — the camera's targets | shown whole it is unreadable on a phone (`footage.md` §10) |
| Photos or the person's footage | the people, the places, the product in real light | `footage.mjs scan`: the shots, the liveliest seconds, the camera's direction, the light; colours; the story they tell | faces only with consent; a photo is a hero, not wallpaper (`footage.md`) |
| A logo or only a name | a world built around the mark | its shapes, angles, letters (`trace-logo.mjs`) as the transition language | "no material" is not "no idea": draw the world (`story-and-motion.md` §7) |
| A Telegram bot or channel | the chat: messages, buttons, the answer that arrives | the avatar and description (site-kit on the t.me link) | the CTA drives to the bot, not to a site |

## 3. Where it plays → the opening, the sound, the format

Every platform's own guidance says the same about the opening: motion and a readable claim in the first second or
two. None of them recommends a calm opening that builds later.

| Placement | Format | Opening | Sound | Length |
|---|---|---|---|---|
| Reels, TikTok, Shorts, Stories | 9:16 | a claim in 3–6 words, moving from frame 1 | on: the groove from the first bar | 10–30 s |
| X, YouTube, Telegram, a site's video section | 16:9 | as above; X loops short videos, so the end can fold into the start | on | 10–45 s |
| Feeds that start muted (Facebook, Instagram feed, LinkedIn) | 1:1, 4:5, 16:9 | the words carry the story on their own; the first frame is the thumbnail | a bonus: the picture must work without it | 10–30 s |
| A site's hero loop, a background | 16:9 or the slot's shape | calm, never competing with the headline; loops seamlessly (`LOOP`) | none, or a quiet bed the page may never play | 8–20 s |
| A pitch, a presentation, an event screen | 16:9 | clear, readable from across a room | often silent: the type must be self-sufficient | 20–60 s |

A placement nobody named: a promo for a business is posted where people scroll — plan for sound on, a hook in the
first second, and a first frame that works as a thumbnail.

## 4. The brand's own voice

- **Copy**: short and playful, precise and technical, warm and human, formal and reassuring, luxurious and sparse.
  The on-screen words keep that voice; the motion follows it (playful copy → bouncy springs, sparse copy → holds).
- **Colours and type**: a white site is a light video; heavy grotesk and saturated colour → hard, graphic motion;
  thin serif and muted colour → slow, spacious motion. The look card in `look-cards.md` is picked from these.
- **Its own interface**: how its buttons, menus and pages move is the brand's motion already — match its speed and
  its easing, and the video feels like the product.
- **Audience**: developers read clean and precise as competent (not as calm); kids and consumer apps read bouncy and
  bright; business buyers read confident and clear; luxury reads slow and spacious.

## 5. Energy, mood and the sound's role

**Energy** (how hard it hits, per scene: `ENERGY` in `js/timeline.mjs`). Motion graphics is a genre of movement, and
most people who ask for a promo want it to drive. The default for a promo, a launch, a reel or an ad is the groove from
the first bar (a pickup of a bar at most), energy held through every scene, contrast made by adding (a new layer, a
fill, a hole before the biggest hit) rather than by thinning. The seven references this skill is measured on all
drive from their first seconds.

Calm needs a reason, written in the card: the person asked for it; the brand lives in calm (a spa, a clinic, a
luxury house, a memorial, a meditation app); the placement is a background or a hero loop; the subject is sensitive.
Even a calm film moves from frame 1 — slower, softer, never still.

**Mood** is a separate axis from energy: bright or dark, warm or cool, playful or serious. A driving video can be
bright and playful (a kids' app) or dark and serious (a security tool). Mood picks the key, the harmony and the kit;
energy picks how much of the groove plays.

**The sound's role**:
- **music-led** — the track carries the film and the cuts ride it: kinetic type, brand films, footage, reels. Sound
  effects mark the big hits and the transitions.
- **ui-led** — every visible interface event has its own sound, tuned to the key: taps, toggles, typing, pops, a
  success chime; the music is a lighter groove underneath, 3–6 dB lower than in a music-led mix. Services, apps and
  product demos, where the product is the hero: the viewer hears it working.
- A voice-over (the person's recording) leads when there is one: the picture and the music are timed to it.

## 6. Three concepts, one film

A concept is one sustained device that carries the whole film, plus one signature moment the viewer remembers. The
strongest videos use one device from start to end; a montage of unrelated effects reads as a template.

Write three concepts in two lines each — the device, the signature moment, the structure — as different from each
other as the brief allows. Devices that work (breakdowns in `wow-library.md`):
- one shape that never cuts: a dot grows into a button, the button into a card, the card into the next screen;
- a smart camera over the real product that follows the cursor and zooms where the work happens;
- the terminal as a stage: typed statements, real output, the release in its own medium;
- kinetic statements, one word per beat, each triad paying off a claim (three steps of the product's own process);
- a grid of synchronised mini-scenes, looping;
- one layout recoloured per mode, theme or genre;
- the brand's own shape as the transition language (a slash, a curve, a letter);
- a real number counting to its payoff on the drop;
- a known film's grammar rebuilt with this brand (only when the person names it).

Score each 1–5 on: says the promise; the hero is the real product or material; the signature moment is memorable;
it can be built well in code in this session; it is not what the last video in this folder did. Take the highest;
write the other two in one line each in the card (a reviewer sees the choice was made).

## 7. The direction card

Written into the project README (the template has the fields) before any scene code, then checked with
`node tools/plan-check.mjs` once `js/timeline.mjs` holds the plan:

- **Film in one line**: what the viewer feels and does at the end.
- **Read from**: the person's words (quoted), what they gave, where it plays, the brand's voice.
- **Concept**: the device and the signature moment; the two concepts not taken, one line each.
- **Look**: a card from `look-cards.md` and this brand's changes to it; palette roles with hexes; type with sizes.
- **Energy**: per scene, and where it came from ("dynamic, punchy" → high from bar 1).
- **Sound role**: music-led or ui-led, and the genre card that fits both the energy and the mood.
- **Beat map**: the story table (beats → shot → how it enters and leaves → sound).
- **Banned**: the anti-generic list (`story-and-motion.md` §9) plus what this brand rules out.

A person who pasted a detailed direction of their own gets it to the frame; the card fills only what they left open.

## 8. Worked directions

Made-up briefs, to show how different inputs lead to different films — the reasoning to copy, not the answers.

1. **A GitHub repo of a CLI tool, "a release video, lots of energy".** Words: energy → high from bar 1.
   Input: a repo → the terminal is the hero; the README's three headline features. Placement: X → 16:9, sound on,
   25–35 s. Voice: developers → clean and precise, not noisy. Concept: *terminal as a stage* — each feature a typed
   statement under real output; signature: the install command types itself and the whole screen assembles around it.
   Look: terminal release. Sound: music-led, a driving breakbeat or UK garage at 125–135 with key clicks in the kit.
2. **A SaaS invoicing site, no words about the feel.** No energy words → the promo default: drive from bar 1,
   bright mood. Input: real dashboard sections + ui-shot of the invoice card and the "Paid" badge. Concept: *one shape
   never cuts* — a dot → the New-invoice button → the invoice card → a "Sent" pill → the paid badge; signature: the
   total counts to £0.00 on the drop. Look: product film (light). Sound: ui-led — every click and pop tuned, a light
   2-step underneath.
3. **A spa's site, no words.** The brand lives in calm → low–mid, warm. Input: photos of the rooms, a serif
   wordmark. Concept: slow pushes through three photos with the words rising out of a mask line; signature: the
   wordmark draws itself like steam. Look: cinematic premium, light variant. Sound: music-led, ambient pulse, long
   tails; motion from frame 1, just slow.
4. **A kids' learning app, screenshots, "for TikTok".** Placement: 9:16, 15–20 s, sound on. Voice: playful.
   Energy: high, bright. Concept: the app's mascot and lesson cards bounce in on the beat, each tap pops; signature:
   a lesson card flips into a medal. Look: playful pop. Sound: ui-led, marimba pop, a pop per card.
5. **A logistics company, "calm, premium", for a pitch.** Words: calm, premium → mid at most. Placement: a
   presentation → silent-safe type. Concept: *data story* — a route draws across a map, real volumes roll; signature:
   the network lights up city by city. Look: data story, dark. Sound: minimal pulse, a tick per digit.
6. **A fitness tracker's launch, a product page and app screenshots, "make it explosive".** Explosive → high from
   bar 1. Concept: a day told by the tracker's own rings — each stat closes its ring on a beat while the day speeds
   past; signature: every ring snaps shut together on the drop. Look: neon kinetic, from the app's colours. Sound:
   music-led, broken beat, a tick per stat.
7. **A personal travel reel from photos, "fast, with bold transitions".** High. The photos are the heroes. Concept:
   whip pans between photos on every downbeat, the place names slam in, a map route draws between cities;
   signature: a zoom through one photo's window into the next city. Look: from the photos' own colours, grain.
   Sound: music-led, 120–130 BPM, cuts on downbeats (not every beat).
8. **A restaurant opening, a site and a menu, for Reels.** Default drive, warm mood. Concept: the menu's dishes land
   on a table grid one per beat, prices from the site; signature: the doors open on the opening date. Look: editorial
   print. Sound: music-led, funk or latin groove, a pan sizzle as the brand sound.

## 9. Brief contagion: the defaults every model reaches for

Two briefs that ask for the same thing come out alike — not for their ambition, but for everything they leave open.
Left to itself, every model reaches for the same answers: a dark screen with a green or purple glow; a cream canvas with
numbered labels ("01 · CREATE"); centred text fading in on a gradient; frames and text in the corners; an invented
logo; screens that do not exist; beeps "like a microwave"; house at 128 in A minor. The direction above exists to
replace each of these with a choice made for this brand: every line of the card should be something the last video
in this folder did not do.

# Footage: films cut from the person's own clips and photos

## Contents
1. When the material is footage
2. Look at it first: scan
3. Pick the moments, plan the edit on the beat
4. Cut: frames at the video's size
5. The screen: drawing footage
6. Speed ramps and slow motion
7. Transitions that carry the motion
8. Grades
9. Surfaces, grids, a screen in the screen
10. Screen recordings: the camera goes where the work happens
11. Photos
12. Sound from the clips, and people speaking
13. Captions
14. Traps

## 1. When the material is footage

When the person gives clips — a trip, an event, a product filmed on a phone, a screen recording — or a folder of
photos, that material is the hero. Type, shapes and interface serve it and never cover the best part of a shot. The
edit is music-led (`sound-design.md`, the sound's role): cuts on the downbeats, the drop on the best shot, the ramps
into the hits. A travel, event or sport reel is dynamic by default: whips that carry the camera's motion, speed ramps
into hits, zoom punches, a freeze with words. A calm request (a wedding film, a spa, a slow travel diary) gets long
holds, slow push-ins and match cuts made with the same care — never slideshow fades.

Footage follows the rules that protect the client: people who did not agree to be filmed are not the subject of a
shot; blur or skip faces, number plates and screens with private data when the person asks or the material is not
theirs.

## 2. Look at it first: scan

```bash
node tools/footage.mjs scan <their clips or a folder>      # in the scaffolded project (SKILL.md step 1)
```

For every clip it prints each shot (it finds the cuts inside a clip), how much moves, which way the camera goes and
how fast ("camera pans right 21 %/s — the picture moves left"), the light (dark, bright), the liveliest and the
calmest second, and for a still shot where the picture changes, second by second. It writes
`assets/footage/scan.json` and a sheet per clip — a frame every second or two with the second in its corner. Open
the sheets: you cannot direct footage you have not looked at. Photos in the folder are listed with their size.

## 3. Pick the moments, plan the edit on the beat

- **The hook is the most kinetic moment**, already moving in frame 1 — the liveliest second of the best shot, not
  the establishing view.
- **Order the shots as a story**: arrive → explore → the peak → a breath → the end; or, for a product, problem →
  hands on it → the result. Group by place or by colour so the grade holds sections together.
- **One shot per beat or two in a drive, one per bar in a calm film.** A shot shorter than half a second reads as a
  flash; use that on purpose (a stutter, a rewind), not by accident.
- **The drop lands on the best shot**; the biggest ramp or punch sits right before it.
- **Plan the transitions from the scan**: a whip continues the direction the outgoing shot's picture moves; a zoom
  punch goes into a still subject; a match cut joins two shots with the same shape, colour or motion.
- The beat map in the README lists every shot with its clip, its source seconds, its ramp keys and its transition.

## 4. Cut: frames at the video's size

```bash
node tools/footage.mjs cut <clip> 12.4-16.0 --name walk [--focus 0.4,0.5] [--scale 1.3] [--fps 60] [--sound]
```

The stretch becomes `assets/footage/walk/00000.jpg …` at the video's size, cover-cropped around the focus (0..1 of
the source; move it onto the subject when a wide shot becomes vertical), at the clip's own frame rate (capped at 60;
phone clips with a varying rate come out constant), and an entry in `js/footage.data.mjs`. Cut only what the edit
uses, with a little extra for the ramps: a vertical frame is 50–300 KB, a minute at 60 fps is 3,600 of them. A shot
the camera pushes into needs `--scale` at least as large as the push (a 1.3× push from a 1× cut is soft). `--sound`
also writes the stretch's sound to `audio/kit/<name>.wav`.

## 5. The screen: drawing footage

Footage and photos are drawn on one WebGL2 canvas under every scene (`js/screen.js`), so type and shapes in the
scene's DOM paint over them. A scene reads `ctx.screen` (it is created on first use), draws its layers every frame,
lists every image it draws in `render.needs(t)` — they are decoded before the frame, which keeps every worker's frame
identical — and sets the frame's effects on `ctx.gl`:

```js
import { P, ease } from '../engine.js';
import { W, H } from '../kit.js';
import { CUE, S } from '../timeline.mjs';
import { view } from '../screen.js';
import { frame, urls, remap } from '../footage.mjs';

const TEAL = { contrast: 1.1, saturation: 1.12, sh: [0, 0.06, 0.12, 0.35], hi: [0.12, 0.06, 0, 0.3] };   // §8

export function build(ctx) {
  const screen = ctx.screen;
  const [a, z] = S.walk;
  const src = remap([[a, 0], [CUE.ramp, 1.2], [z, 3.4]]);   // output second → source second
  const at = (t) => frame('walk', src(t));
  const render = (t) => {
    if (t < a || t > z) return;
    const fr = at(t);
    const push = 1 + 0.06 * P(t, a, z);                      // a slow push the whole shot
    screen.draw(fr.url, view({ z: push, cx: 0.5, cy: 0.45 }).m, { next: fr.next, mix: fr.mix, grade: TEAL });
    ctx.gl.used = true;                                       // the screen shows this frame
  };
  render.needs = (t) => (t < a || t > z ? [] : urls(at(t)));
  return render;
}
```

- `view({ sw, sh, z, cx, cy, px, py, r })` places a source of `sw × sh` px (default: the video's size, as `cut`
  makes it): the source point (cx, cy) lands on the screen point (px, py), `z` relative to cover, `r` degrees. Its
  `css` puts a DOM element (a label, a sticker, a cursor) on the same picture.
- `screen.draw(url, m, { op, blend, grade, next, mix, feather, mask, clampOut })` — `blend` 'normal', 'screen',
  'add' or 'max'; `mask` [x0, y0, x1, y1] in the source's 0..1; `feather` a soft edge.
- `ctx.gl` (the effects pass, for the whole screen): `zb` [x, y, strength] zoom blur, `rgb` px + `rgbAngle` or
  `rgbRadial`, `glitch` 0..1 + `glitchH` + `glitchSeed`, `vhs` + `vhsSquash` + `vhsBand`, `crtX` / `crtY` (a CRT
  squeeze, 1 = full) + `crtGlow` + `scan`, `spot` [x, y, radius, strength], `flash` (white), `fade` (black), `grade`.
- Everything is a function of t (a glitch's seed too: `glitchSeed: Math.floor(t * 30)`), and fast moves are in
  `WHIPS`: the renderer's motion blur then smears a whip over 16 real samples.

## 6. Speed ramps and slow motion

`remap(keys)` turns [output second, source second] keys into a smooth curve that never runs backwards (unless the
keys do). The slope is the speed (`src.speed(t)`): steeper runs faster than life, shallower is slow motion, two equal
source seconds freeze the frame.

- **Ramp into a hit**: 1× → 3–5× over the beat before the hit → the hit → 0.3–0.5× right after it; the whip or the
  punch sits on the fastest part.
- **Slow motion** blends two neighbouring frames (`next`, `mix` from `frame()`), so a 30 fps clip slows without
  stutter; 60 fps footage slows cleaner. `frame(name, s, { blend: false })` for a hard, stepped look.
- **Steps on the beat**: put keys at the source seconds where a foot lands and at the output beats you want them on;
  the score reads the same `remap` to place the footsteps.
- **A rewind** is keys that go back in source time; add `vhs` and `rgb` for the tape look.

## 7. Transitions that carry the motion

- **Whip that continues the camera**: the outgoing shot's picture keeps moving the way the scan says it moves ("the
  picture moves left" → out to the left over 0.2–0.3 s, `ease.inOutCubic`), the next shot enters from the other side;
  `zb` and `rgb` peak in the middle (`Math.sin(Math.PI * p)`), a whoosh on it, the pair in `WHIPS`.
- **Zoom punch-through**: z 1 → 3 over a beat (`zoomLog`), `zb` rising at the end, the next shot starts at z 1.25 →
  1 on the downbeat.
- **Spin**: r 0 → 90 with a push, the next shot from −90 → 0; for one hit per film, not every cut.
- **Flash cut**: `flash` 1 → 0 over three frames on the downbeat.
- **Glitch hit**: `glitch` 0.5–0.7 for two frames on a hit, a new `glitchSeed` each frame.
- **Freeze + words**: a flat stretch in the ramp, a colour pass (`grade: { pass: 1, passHue: <the subject's or the
  brand's hue> }`), the words slam in; a shutter or a tape stop.
- **Echo trail**: the last three frames drawn again behind the current one with `op` 0.35 / 0.2 / 0.1 and `blend:
  'screen'` (`frame('walk', src(t - k * 0.05))`; list them in `needs`).
- **Match cut**: two shots with the same shape, colour or direction — planned from the sheets, cut on the downbeat.
- **CRT off / on**: `crtY` 1 → 0.01 then `crtX` 1 → 0 (off); the reverse to open a section.

## 8. Grades

One grade per place or per section, kept across its shots: the film looks shot by one person. Start from these and
move them towards the brand's colours:

| Look | grade |
|---|---|
| Teal and orange (travel, sport) | `{ contrast: 1.1, saturation: 1.12, sh: [0, 0.06, 0.12, 0.35], hi: [0.12, 0.06, 0, 0.3] }` |
| Warm film (a diary, food) | `{ contrast: 1.05, saturation: 0.9, tint: [1.06, 0.98, 0.9], tintAmt: 0.6, crush: 0.04 }` |
| Night city | `{ exposure: -0.2, contrast: 1.15, saturation: 0.85, sh: [0, 0.03, 0.12, 0.4], hi: [0.15, 0.08, 0, 0.25] }` |
| Black and white punch | `{ bw: 1, contrast: 1.25, crush: 0.03 }` |
| Colour pass | `{ pass: 1, passHue: 0 }` — everything grey but red (60 yellow, 120 green, 210 blue) |

A dark shot gets `exposure` 0.3–0.6 before anything else; a shot that stays muddy is left out.

## 9. Surfaces, grids, a screen in the screen

- **A picture on a surface** (a phone screen, a billboard, a poster): `screen.draw(url, mat.inv(mat.square2quad([p0,
  p1, p2, p3])))` — p0..p3 are the picture's corners on screen in px (top-left, top-right, bottom-right,
  bottom-left); move them with the surface and the picture stays glued to it.
- **A grid of shots**: one `draw` per cell with a `view()` whose `px, py` is the cell's centre and `mask` its box;
  cells pop in on the 16ths, one plays while the others hold their first frame.
- **A screen in the screen**: `feather` 0.02 for a soft edge, then the camera dives into it (z → cover) on a riser.

## 10. Screen recordings: the camera goes where the work happens

A recording shown whole is unreadable on a phone. The scan's `activity` of a still shot says where the picture
changes, second by second — the camera's targets. Zoom so the change fills about 60 % of the frame, hold while it
happens, move on the beat before the next:

```js
import scan from '../../assets/footage/scan.json' with { type: 'json' };   // or copy the boxes into the scene
import { track, SPRING } from '../engine.js';
import { CUTS, frame, urls } from '../footage.mjs';
const [a] = S.demo;                                        // the scene plays the cut 'demo' at 1× from its start
const act = scan.clips.find((c) => c.name === 'recording').shots[0].activity;
const keys = act.map(({ t, box: [x0, y0, x1, y1] }) =>
  [a + t - CUTS.demo.from, [(x0 + x1) / 2, (y0 + y1) / 2, Math.min(2.4, 0.6 / Math.max(x1 - x0, y1 - y0))]]);
// every frame:
const [cx, cy, z] = track(t, keys, SPRING.base);
const fr = frame('demo', t - a);
screen.draw(fr.url, view({ z: Math.max(1, z), cx, cy }).m, { next: fr.next, mix: fr.mix });
```

The boxes are in the clip's own frame: they match the cut when the recording keeps its shape (a wide recording in a
wide film); for a vertical film cut from a wide recording, set `--focus` on the work and convert the boxes by the
crop, or plan the targets from the sheet by eye.

Cut the recording with `--scale` equal to the deepest zoom (2 for 2×) and `--fps 30`. Text in focus is at least 28 px
on screen at 1080p; a click gets a sound and a small punch; the cursor can be drawn in the DOM with `view().css`.

## 11. Photos

`screen.draw('assets/img/photo.jpg', view({ sw, sh, z, cx, cy }).m)` with `[sw, sh] = screen.size(url)` (known once
decoded; list the photo in `needs`). The photo's own orientation is respected. A photo is never shown still: a slow
push (z 1 → 1.08 over its time), a drift towards the subject, or a parallax of two crops; photos cut together on the
beat read as a reel, not a slideshow. A photo wall, a split-flap of places, a map with pins between them:
`scene-cookbook.md`.

## 12. Sound from the clips, and people speaking

`cut --sound` keeps the stretch's own sound — waves, a crowd, an engine — as a brand-world sound: `sample(t,
'audio/kit/<name>.wav', { align: 'start', vel: 0.5 })` under the music at 1× shots. A ramped shot's natural sound would
run at the wrong speed: give it designed sounds instead (a whoosh on the whip, an impact on the punch).

When someone speaks — a founder to camera, a testimonial, a guide, a toast — the sound leads and the picture
follows:

- **Cut where it is quiet.** The scan lists each clip's quiet stretches (≥ 0.35 s): those are the clean cuts between
  phrases. 0.15–0.35 s works after a look at the frames; anything shorter is inside a phrase. Never inside a word.
- **Pad every cut** 30–200 ms around the kept words — tight for a punchy reel, loose for a calm film — and keep a
  laugh or a reaction after a punchline: it is part of the beat.
- **Filler and dead air go** ("um", false starts, the pause before a retake); the best take of each line wins, in
  the story's order, not the recording's.
- **The music ducks 12–15 dB under the voice** and comes back up in the gaps; it steps out before the end card
  instead of fading under the call to action.
- **An animation lands on its word**: start its reveal that many seconds before the word it illustrates, so the
  landing frame and the word coincide.

## 13. Captions

Most feeds play muted: a video with speech carries its words on screen. The words come from the person — an SRT or
VTT (a phone's or an editor's export, a transcription they made) or word timings as JSON; this skill does not
transcribe (a local speech-to-text tool is used only when it is already installed and the person agrees).

```js
import { el, set, clamp } from '../engine.js';
import { S } from '../timeline.mjs';
import { CUTS } from '../footage.mjs';
import { wordsOf, chunks, shift, at } from '../captions.mjs';
// build (it may be async): the clip's subtitles, moved to the film's time — the cut 'talk' plays at 1× from S.talk[0]
const subs = await (await fetch('assets/footage/talk.srt')).text();
const caps = shift(chunks(wordsOf(subs), { max: 2, upper: true }), S.talk[0] - CUTS.talk.from);
const box = el('div', 'caption', ctx.stage);            // CSS: z-index above every scene; the heavy display face
// frame:
const c = at(caps, t);
box.innerHTML = c ? c.words.map((w) => `<span class="${t >= w.start ? 'on' : ''}">${w.w.toUpperCase()}</span>`).join(' ') : '';
set(box, { y: 0, s: c ? 1 + 0.08 * (1 - clamp((t - c.start) / 0.12)) : 1, o: c ? 1 : 0 });   // a small pop per chunk
```

- One or two words at a time for a reel, four to seven for a calm film; a chunk never flashes for less than a third
  of a second (`chunks` grows it instead).
- The word being said lights up in the accent colour; the others stay white with a dark outline or shadow.
- Inside the safe area of the platform: in 9:16 above the bottom ~320 px and below the top ~220 px; never over the
  speaker's mouth.
- Captions paint over everything — footage, type, stickers: nothing may cover them. Escape the words if the text
  can hold `<` or `&`.
- A shot played at another speed moves its words with the ramp: map each word's time through the inverse of the
  ramp, or keep speaking shots at 1×.

## 14. Traps

- **An image drawn but not listed in `needs`** is not decoded yet: that frame is empty (QA `flash` or `pops`). List
  every url a frame draws — the echo's too.
- **A push into a 1× cut** softens the picture: cut it with `--scale`.
- **Every shot the same length** reads as a slideshow; vary them with the music (short in the build, long after the
  drop).
- **Covering the best part of a shot with type**: put words where the scan's calm second leaves room, or in the sky.
- **Too much at once**: one effect per hit (a glitch or a flash or a punch), the rest of the shot clean.
- **WebGL2 is needed**: Chrome and Edge have it; a headless render may draw it in software — slower, the same frames.

# Genre cards

Recipes to start a score from — tempo, drum grid, bass, harmony, signature voices, effects, mix — written in the
synth's own terms (synth-api.md). A card is a starting point: change the kit characters, the progression and the hook
so the result belongs to the brand (sound-design.md §7, §12).

Grid notation: 16 steps per bar (sixteenth notes). `X` accent, `x` hit, `o` ghost, `.` rest — feed straight to
`steps(pattern, { from, to })`. Progressions in roman numerals for `prog()`, or chord symbols for `harmony()`.

## Contents
1. Drift phonk · 2. Trap · 3. House / tech house · 4. Deep house · 5. Nu-disco · funk / boogie · 6. Future bass / pop EDM ·
7. Synthwave · 8. Lo-fi hip-hop · 9. Afro house / amapiano · 10. Latin / dembow · 11. Drum & bass · 12. UK garage ·
13. Cinematic hybrid · 14. Corporate / minimal pulse · 15. Kids / playful pop · 16. Chiptune · 17. Luxury ambient ·
18. Rock-ish hybrid · 19. Breakbeat / big beat · 20. Jersey club · 21. Baile funk · 22. Hyperpop / glitch-pop

Groove families (sound-design.md §3): four on the floor 3, 4, 5 (nu-disco), 9, 14 (4/4); backbeat 5 (funk / boogie),
7, 8, 15, 18; half-time 1, 2, 6, 13, 22; broken 11, 12, 19, 20, 21; no kick 17, 14 without its kick. Four on the floor
is what every generated promo reaches for — take it only when the brand lives in clubs or the user asks for it.

## 1. Drift phonk
- **Tempo / key**: 125–145 BPM (128–135 sweet spot); minor, phrygian or harmonic minor. -12 LUFS.
- **Drums**: kick '808' or 'hard' `X.....x...x.....`; clap on 2 & 4 `....X.......X...`; hats 8ths `x.x.x.x.x.x.x.x.` with a
  32nd-note `roll` into every second bar; open hat on the last off-beat of odd bars.
- **Bass**: `bass808` drive 2.5–3.5, a note on every kick, gliding (`from`) into the next root; octave jumps on
  syncopations.
- **Harmony**: i–i–VI–VII or i–VI–iv–V (harmonic minor); dark pad under the breakdowns only.
- **Signature**: `cowbell` riff — a one-bar syncopated motif (steps 0, 3, 6, 8, 11, 13) doubled an octave up in drop 2;
  the lead bus loud (phonk puts the cowbell up front).
- **FX**: reverse cymbals into drops, tape stop into breaks, impacts with an 808 under the slams, car / street foley.
- **Mix**: bass duck 0.55, plate reverb short, bass and drums driven.
- **Fits**: cars, gyms, streetwear, gaming, anything with attitude.

## 2. Trap
- **Tempo / key**: 130–150 BPM with a half-time feel; minor. -12 LUFS.
- **Drums**: kick 'punch' sparse `X.........X.....`; snare 'trap' on beat 3 `........X.......`; hats 8ths with rolls
  (`roll(t0, t1, fn, { from: 1/8, to: 1/32 })`) and triplet bursts; open hat once per 2 bars.
- **Bass**: `bassLine` with slides (`slide: true`), long 808 notes; drive 2–3.
- **Harmony**: i–VI or i–iv minor loops; sparse.
- **Signature**: dark `bell` (ratio 3.5) or `pluck` 'fm' melody, a `vox` or `chop` for the hook.
- **FX**: risers + `gap` before drops, `stutter` on the last beat of a phrase.
- **Mix**: bass duck 0.4 (the 808 is the low end), drums hot, reverb 'dark'.
- **Fits**: fashion, sneakers, sport, nightlife, bold launches.

## 3. House / tech house
- **Tempo / key**: 120–126 BPM; minor or dorian. -13 LUFS.
- **Drums**: kick 'punch' `X...X...X...X...`; clap `....X.......X...`; open hat off-beats `..X...X...X...X.`
  (decay 0.08–0.12); closed 16ths with ghosts `x.o.x.o.x.o.x.oo` (swing 0.06–0.1); `shaker` 16ths.
- **Bass**: `houseBass` off-beat `..x...x...x...x.` or rolling `..x.x.x...x.x.xX` (octave on X); `acid` for tech house.
- **Harmony**: i–VI–VII–i, or dorian vamps (i7–IV7); m7 / m9 chords.
- **Signature**: off-beat `stab` (supersaw) or `keys` 'organ' stabs, a filtered `pluck` arp in drop 2.
- **FX**: `automate(bus, 'lp', …)` filter opening over the build, reverse cymbal, crash on drops.
- **Mix**: bass duck 0.55, music 0.4; plate reverb; delay 0.75 beat on plucks.
- **Fits**: apps, e-commerce, lifestyle, fashion, bars, "modern and busy".

## 4. Deep house
- **Tempo / key**: 118–122 BPM; minor 7th / 9th colours. -14 LUFS.
- **Drums**: kick 'deep' four-on-the-floor; `rim` or `snap` on 2 & 4; `shaker` 16ths; soft open hats.
- **Bass**: `sub` + a soft `houseBass` (bright 0.4), long notes.
- **Harmony**: i9–iv9 or ii9–V9–i; `keys` 'ep' or 'organ' chords with long releases.
- **Signature**: `chop` vocal hooks (vowel 'a' → 'o'), `pad` 'air'.
- **FX**: sparse; long reverb swells, gentle risers.
- **Mix**: reverb 'hall', duck 0.4, wide pads.
- **Fits**: beauty, fashion, hotels, premium lifestyle.

## 5. Nu-disco (4/4) · funk / boogie (backbeat)
- **Tempo / key**: nu-disco 110–122 BPM; funk / boogie 95–112 BPM; major or dorian. -13 LUFS.
- **Drums, nu-disco**: kick 'punch' 4/4; `snare` 'tight' or `clap` on 2 & 4; open hats on off-beats; `conga`
  `..x..x.x..x..x..`. Four on the floor: only for a club-minded brand (sound-design.md §3).
- **Drums, funk / boogie**: kick 'soft' `X.....x...X..x..`; `snare` 'tight' with ghosts `....X..o.o..X.o.`; 16th hats,
  swing 0.08; a `tom` fill at phrase ends. The kick never lands on every beat — that is the whole difference.
- **Bass**: nu-disco: octave `houseBass` 8ths `x.x.x.x.x.x.x.x.`; funk: a syncopated `bassLine` with slides and short
  notes `X..x.x..X.x..x.x` (root, octave, fifth), never a note on every 8th.
- **Harmony**: IV–V–iii–vi or I7–IV7 vamps; 7th and 9th chords.
- **Signature**: `keys` 'clav' riffs, `brass` stabs, `pad` 'strings' swells.
- **FX**: filter sweeps, `crash`es, `sparkle`s on reveals.
- **Mix**: room reverb, moderate duck 0.35 (funk: 0.2 — a live band does not pump).
- **Fits**: food, restaurants, events, playful retail — funk for the warm ones, nu-disco for the club-minded.

## 6. Future bass / pop EDM
- **Tempo / key**: 140–160 BPM, half-time feel; major (IV–V–vi–I or I–V–vi–IV). -11…-12 LUFS.
- **Drums**: kick `X.......X.x.....`; snare 'trap' on beat 3; hats with rolls; a snare `roll` + `gap` into every drop.
- **Bass**: `fmBass` with `wobble` 2–4 Hz, or `supersaw` chords doubled an octave down.
- **Harmony**: big `supersaw` chords, 7 voices, detune 0.2–0.3, heavy pump (music duck 0.7).
- **Signature**: `chop` vocal hooks pitched to the melody; `bell` sparkles.
- **FX**: long risers, `boom` + `impact` on drops, reverse cymbals.
- **Mix**: pump everything except drums; plate reverb; loud.
- **Fits**: youth apps, events, tech launches, gaming.

## 7. Synthwave / retrowave
- **Tempo / key**: 90–118 BPM; minor (i–VI–III–VII). -13 LUFS.
- **Drums**: kick 'punch' 4/4 or 1 & 3; `snare` 'gated' on 2 & 4 (big reverb); hats 8ths.
- **Bass**: 8th-note octave pulse — `lead` wave 'saw', cut 700, or `bassLine` straight 8ths.
- **Harmony**: `pad` 'warm' + 'strings'; long chords.
- **Signature**: `lead` saw with `vib` 0.25 and delay, a 16th `arp` of `pluck` 'synth'.
- **FX**: slow sweeps, reverse cymbals, `zap`s.
- **Mix**: hall reverb, chorus on the music bus, duck 0.35.
- **Fits**: gaming, neon nightlife, retro cars, tech with nostalgia.

## 8. Lo-fi hip-hop / chillhop
- **Tempo / key**: 70–90 BPM, swing 0.12–0.2; maj7 / m9, ii–V–I. -15 LUFS.
- **Drums**: kick 'soft' `X......x..X.....`; `snare` 'lofi' on 2 & 4 with ghosts; hats `metal: 0` swung 8ths;
  `humanize: 0.008` everywhere.
- **Bass**: `sub` or a soft `houseBass` (bright 0.3), laid back.
- **Harmony**: `keys` 'ep' jazzy voicings (maj7, m9, 6/9), `voiceLead` them.
- **Signature**: vinyl crackle bed (`noiseHit` pink, hp 900, long, quiet + random pops), tape wobble (music bus
  `chorus: { rate: 0.4, depth: 0.003, mix: 0.3 }`), `crush: { bits: 10, rate: 2 }` on drums.
- **FX**: few: page flips, cup clinks, room tone.
- **Mix**: room reverb, bus `lp` 9000 on music, duck 0.2.
- **Fits**: cafés, bakeries, books, study apps, cozy brands.

## 9. Afro house / amapiano
- **Tempo / key**: 112–118 BPM; minor or major gospel colours (I–vi–ii–V). -13 LUFS.
- **Drums**: kick 'deep' 4/4 (drop some beats); `shaker` 16ths; `conga` / `tom` pattern `..x..x.x..x.x...`;
  `clave` 3-2 son clave `x..x..x...x.x...`.
- **Bass (amapiano log drum)**: `tom` with long decay, or `toneSweep` sine from note + 5 semitones down to the note
  (0.3 s, 'decay' envelope), syncopated.
- **Harmony**: `keys` 'piano' chords, `pad` 'air'.
- **Signature**: `chop` vocals, log-drum bass, shakers.
- **Mix**: room / plate reverb, duck 0.35.
- **Fits**: fashion, beauty, lifestyle, festivals, youth.

## 10. Latin / dembow
- **Tempo / key**: 90–100 BPM; minor (i–VI–III–VII). -12 LUFS.
- **Drums**: kick on every beat `X...X...X...X...`; `snare` 'tight' / `rim` on the dembow `...x..x....x..x.`; hats 8ths.
- **Bass**: `bass808` or `sub` on the kicks, short.
- **Harmony**: `pluck` 'ks' (guitar-like) arpeggios, `brass` hits.
- **Signature**: plucked riffs, brass stabs, `conga`s.
- **Mix**: plate reverb, duck 0.4.
- **Fits**: food, beach, fitness, parties, latin audiences.

## 11. Drum & bass
- **Tempo / key**: 170–176 BPM; minor. -12 LUFS.
- **Drums**: kick `X.........X.....`; snare 'tight' on 2 & 4 (steps 4, 12); hats 16ths / `ride`; fills with `roll`.
- **Bass**: `reese` (dark, neuro-lite) or `sub` + a pad (liquid).
- **Harmony**: liquid: `pad` 'air' + `pluck` 'fm'; neuro: minimal, bass-led.
- **FX**: `riser`, `downlifter`, `zap`, `glitch`.
- **Mix**: drums very present, bass duck 0.5, plate reverb.
- **Fits**: sport, extreme, energy drinks, "fast delivery", speed claims.

## 12. UK garage / 2-step
- **Tempo / key**: 130–134 BPM; minor 7 / 9. -13 LUFS.
- **Drums**: 2-step kick `X.........X...x.`; `clap` on 2 & 4; shuffled hats (swing 0.18) with 'o' ghosts;
  `shaker`.
- **Bass**: `keys` 'organ' low or `houseBass`, bouncy.
- **Harmony**: m7 / m9 `stab`s.
- **Signature**: pitched `chop` vocals, organ bass.
- **Mix**: room reverb, duck 0.45.
- **Fits**: urban fashion, nightlife, music apps.

## 13. Cinematic hybrid (trailer)
- **Tempo / key**: 60–100 BPM, or 120 with half-time hits; minor / phrygian. -14 LUFS, wide dynamics (LRA 6–10).
- **Drums**: taiko-like `tom` (low notes) + kick 'boom' patterns; ticking pulse (bright `tick` 8ths + `sub` pulse).
- **Bass**: `sub` drones, `boom` drops on hits.
- **Harmony**: `pad` 'strings' ostinato (16th `pluck` 'ks' or short `lead` saw), `pad` 'dark'.
- **Signature**: `braam` on reveals, `riser` type 'shepard' for tension, silence (`gap`) before every big hit.
- **FX**: `impact` + `boom` + `crash` stacks, `downlifter`s after hits.
- **Mix**: huge / hall reverb, little duck.
- **Fits**: launches, B2B, real estate, finance, "serious" announcements.

## 14. Corporate / minimal pulse
- **Tempo / key**: 100–120 BPM; major / lydian (bright) or minor (serious). -14 LUFS.
- **Drums**: half-time — kick 'tight' on 1 `X.........x.....`, `snap` / `clap` on 3, sparse hats; or no kick at all: a
  bright `tick` pulse in 8ths over a `sub` on the roots. 4/4 only for an upbeat consumer brand.
- **Bass**: `sub` on the roots, some `houseBass` bright 0.5.
- **Harmony**: `pad` 'glass', `pluck` 'fm' 16th arps.
- **Signature**: a clean `bell` motif (ratio 2.01), subtle `glitch` and data `blip`s in the scale.
- **Mix**: plate reverb, delay on plucks, duck 0.3.
- **Fits**: SaaS, fintech, AI, B2B, consulting.

## 15. Kids / playful pop
- **Tempo / key**: 100–125 BPM; major pentatonic. -14 LUFS.
- **Drums**: a backbeat — kick 'soft' `X.......X.x.....`, `clap` on 2 & 4, `shaker`, handclap fills.
- **Bass**: `chipBass`, or a bouncy `bassLine` jumping octaves on the off-beats — not a note on every 8th.
- **Harmony**: I–V–vi–IV, `pad` 'glass' bright.
- **Signature**: `pluck` 'marimba' / 'kalimba' melodies, whistle (`toneSweep` sine glides), `boing`, `pop`, `goo`.
- **Mix**: room reverb, duck 0.3.
- **Fits**: kids' EdTech, toys, family, pets.

## 16. Chiptune
- **Tempo / key**: 120–160 BPM; major or minor. -13 LUFS.
- **Drums**: `hat` metal 0 short (noise channel), kick 'punch' short, `snare` 'tight'; music bus `crush: { bits: 6, rate: 3 }`.
- **Bass**: `chipBass` (triangle).
- **Harmony**: `chip` with `arp: [0, 4, 7]` at rate 1/8 beat (the chip chord).
- **Signature**: `chip` lead duty 0.25 / 0.125 with `echo`, `blip`s, pixel sweeps (fast `chip` runs).
- **Mix**: little reverb, no sidechain or a light one.
- **Fits**: games, pixel brands, retro tech, kids' tech.

## 17. Luxury ambient
- **Tempo / key**: 60–95 BPM, sparse or no drums; lydian, maj7 / add9. -16…-15 LUFS.
- **Drums**: a `heartbeat` or kick 'deep' every bar at most; `shaker` very soft.
- **Bass**: `sub` long notes.
- **Harmony**: `keys` 'piano' + `pad` 'glass' / 'air', `voiceLead`.
- **Signature**: `pluck` 'harp' glissandi, `sparkle`s, long `bell` tails.
- **FX**: slow swells, reverse reverbs (a `riser` type 'tone', soft).
- **Mix**: huge reverb, delay 0.75 beat, no duck.
- **Fits**: jewellery, perfume, spa, premium real estate, flowers.

## 18. Rock-ish hybrid
- **Tempo / key**: 120–150 BPM; minor / mixolydian. -12 LUFS.
- **Drums**: kick 'hard' + `snare` 'fat', crashes on phrase starts, `tom` fills.
- **Bass**: `reese` or `bassLine` driven hard.
- **Harmony**: power chords (root + fifth) as `brass` / `supersaw` with bus `drive: 3` and `lp` 3500 — a synth take on
  guitars (lean into it; don't fake a real guitar).
- **FX**: impacts, `riser`s, `stutter`s.
- **Mix**: room reverb, duck 0.3, drums loud.
- **Fits**: sport, gyms, auto, extreme.

## 19. Breakbeat / big beat
- **Tempo / key**: 125–140 BPM; minor or mixolydian. -12 LUFS.
- **Drums**: a broken beat, never 4/4 — kick 'punch' `X.........X.x...`, `snare` 'fat' `....X..o.o..X..o`, hats
  `x.x.x.x.x.x.x.xX` with an open hat on the last step of odd bars; drums bus `drive: 3` and
  `crush: { bits: 12, rate: 2 }` for the sampled-break grit; vary the second bar (a kick moved, a snare flam).
- **Bass**: `acid` riff with `automate(bus, 'lp', …)` opening over 8 bars, or a driven `reese`.
- **Harmony**: riff-based, one or two chords (i–VII); `brass` or `stab` hits on the accents.
- **Signature**: the acid squelch, a shouted `chop` hook, `zap`s; a `tapeStop` into the break.
- **FX**: `stutter` on phrase ends, `riser` + `crash` into drops, `impact` on slams.
- **Mix**: room reverb, duck 0.3, drums up front.
- **Fits**: energy drinks, sport, gaming, streetwear, bold and loud launches.

## 20. Jersey club
- **Tempo / key**: 135–145 BPM (140); minor. -11…-12 LUFS.
- **Drums**: the five-kick bounce `X..X..X...X.X.X.` (kick '808' short, `len` 0.25); `clap` `....X.......X...` plus a
  16th flam before beat 4 in every second bar; sparse hats.
- **Bass**: short `bass808` notes on selected kicks.
- **Harmony**: a minor two-chord loop, thin (`pad` 'dark' or none).
- **Signature**: a pitched `chop` stuttering in 16ths, a squeak (`goo` or a short `boing`) on the off-beats — the
  genre's calling card.
- **FX**: `stutter`, `gap`s before every drop, siren sweeps (`toneSweep` sine).
- **Mix**: plate, duck 0.4, loud and dry drums.
- **Fits**: sneakers, youth and dance apps, TikTok-first brands, parties.

## 21. Baile funk
- **Tempo / key**: 125–135 BPM (130); minor or phrygian. -11…-12 LUFS.
- **Drums**: the tamborzão — kick '808' + low `tom` on `X..x..x...x..x..`, `clap` or `snap` `....x.......x...`,
  `shaker` 16ths; `humanize: 0.006`.
- **Bass**: distorted short `bass808` following the tamborzão.
- **Harmony**: minimal: a two-note `lead` 'square' riff or `brass` stabs, phrygian colour.
- **Signature**: a `vox` / `chop` call-and-response shout, whistle glides (`toneSweep` sine), `cowbell` accents
  (with a `cowbell` riff on top it becomes Brazilian phonk).
- **FX**: `glitch`, `stutter`, sirens.
- **Mix**: drums and bass `drive: 2.5`, duck 0.35, short plate.
- **Fits**: fashion, streetwear, beachwear, fitness, parties, anything hot and bold.

## 22. Hyperpop / glitch-pop
- **Tempo / key**: 140–170 BPM; major with sugary colours (I–V–vi–IV) or minor. -10…-11 LUFS (loud on purpose).
- **Drums**: kick 'punch' with `drive: 4` (clipped on purpose), `snare` 'trap' on beat 3 (half-time) or on 2 & 4, 16th
  hats with `roll`s; a `stutter` every 2 bars.
- **Bass**: `fmBass` or `bass808`, heavily driven.
- **Harmony**: `supersaw` chords high (oct 5), `chip` arps, `pad` 'glass'.
- **Signature**: pitched `chop` vocals, a `chip` lead on a crushed lead bus (`crush: { bits: 8, rate: 2 }`), `glitch`
  bursts, a `stutter` with `slice: 1/16` into every drop.
- **FX**: `glitch`, `zap`, `tapeStop`, `sparkle`s, sudden `gap`s.
- **Mix**: bright, plate reverb, duck 0.5.
- **Fits**: youth apps, gaming, creators, AI toys, internet-native brands.

# Look cards: nine visual languages

A look is more than a palette: the canvas, the type, the way things move and the texture have to agree, or the video
reads as a template. Left alone, every video comes out in the template's own look (a dark ground, one neon accent,
slams). Pick a card at step 3 from the brand's own surfaces and voice (`direction.md` §4), then change it for this
brand — its colours, its fonts, its shapes. Do not take the card the last video in this folder took.

Timing is in beats: "stagger ⅛" = the next element starts ⅛ beat later; "hold 2" = text stays 2 beats after landing.
Springs are `SPRING` feels in `js/engine.js` (snap, base, heavy, play).

## Contents
1. Product film (light) · 2. Terminal release · 3. Liquid glass · 4. Neon kinetic · 5. Editorial print ·
6. Data story · 7. Playful pop · 8. Cinematic premium · 9. Grid system — and how to pick

## 1. Product film (light)
- **When**: SaaS, apps, tools with a clean light site; launches that sell the product itself.
- **Canvas**: warm white or light grey; a faint tint of the accent behind whatever is in focus. No dark scenes.
- **Type**: a heavy sans for statements (800, tight tracking), one accent word per line in a contrasting face (a
  serif italic) or the accent colour; UI text at the product's own size × the camera zoom.
- **Colour**: the brand accent means one thing (good news, the key word); everything else neutral.
- **Motion**: words rise out of a mask line one per beat; things change shape into the next thing (a dot → a button →
  a card); springs base, snap on UI; stagger ⅛, hold 2.
- **Transitions**: morphs and match moves; almost no hard cuts.
- **Camera**: one camera over the product, following the cursor, zoom in log space.
- **Texture**: real UI crops on white cards — radius, a 1 px border, a soft wide shadow.
- **Sound**: ui-led — clicks, pops, typing tuned to the key over a light 2-step, garage or minimal groove.
- **Banned**: glows, gradients on UI chrome, particles, 3D tilts for their own sake, crossfades, holds over 1½ beats.

## 2. Terminal release
- **When**: developer tools, CLIs, libraries, open source, APIs; a repo is the input.
- **Canvas**: near-black ink, a subtle grid or scanline texture at 3–5 %.
- **Type**: a mono face for captions and code (lowercase statements work: "hot reload. no restart."), one sans or the
  project's wordmark for the name; the accent colour marks one word per caption.
- **Colour**: the project's colour as the single accent (orange, green, violet); syntax colours kept muted.
- **Motion**: typing at a readable rate, decode/scramble for names, panels sliding on snap springs; stagger ¼, hold 2.
- **Transitions**: hard cuts on downbeats, split panes, a caret that becomes the next frame.
- **Camera**: mostly still, with pushes into the output that matters.
- **Texture**: real terminal output, real code from the docs, the install command at the end.
- **Sound**: music-led with the kit clean and tight; key clicks and data blips from the typing schedule.
- **Banned**: neon glow on everything, fake "hacker" matrices, HUD corners, invented commands or output.

## 3. Liquid glass
- **When**: design-forward apps, consumer tech, a brand with soft gradients and rounded UI.
- **Canvas**: a slow pastel gradient field; blurred colour blobs drifting.
- **Type**: a clean sans (600–700), large; words may sit under a glass lens that refracts them.
- **Colour**: pastel ground, white glass, one saturated accent for the active state.
- **Motion**: one glass element morphs into each component (a button, a player, a tab bar, a chart); springs base with
  a hair of overshoot; stagger ⅛, hold 1½.
- **Transitions**: the morph is the transition; never a hard cut.
- **Camera**: still or a very slow drift; the objects move, not the camera.
- **Texture**: frosted glass (blurred, lightened copy of the ground), a specular edge, soft shadows.
- **Sound**: ui-led or music-led: soft plucks, glass bells, an airy groove at 110–125.
- **Banned**: heavy slabs, hard cuts, dark scenes, speed lines.

## 4. Neon kinetic
- **When**: cars, sport, gaming, nightlife, streetwear, energy drinks; a dark brand that wants impact.
- **Canvas**: dark, with light glows and a vignette; depth from blurred colour fields.
- **Type**: a heavy italic or condensed display face, huge (15–30 % of the frame height), one word per slam.
- **Colour**: one neon accent that owns the hits; white type.
- **Motion**: slams with overshoot, whip pans, shakes on hits, speed lines, flashes on the biggest hits only;
  stagger ⅛, hold 1.
- **Transitions**: whips, brand-angle wipes, zoom-throughs, a hole before the reveal.
- **Camera**: alive — pushes, shakes, parallax.
- **Texture**: sparks, streaks, grain.
- **Sound**: music-led and driving: phonk, drum & bass, breakbeat, rock-ish hybrid.
- **Banned** for health, kids, luxury and most B2B — and as the default: it is the template's own look.

## 5. Editorial print
- **When**: food, craft, culture, media, bookshops, anything with a warm or handmade voice.
- **Canvas**: paper or a warm off-white, visible grain; ink black.
- **Type**: a serif display (with italics), a grotesk for labels; big headlines set like a magazine page.
- **Colour**: two inks plus one spot colour; photos keep their own colour.
- **Motion**: cut-paper pieces sliding in, stamps landing, ink strokes drawing; springs heavy; stagger ¼, hold 2.
- **Transitions**: page turns, paper tears, a stamp that fills the frame.
- **Camera**: top-down over a table; small shifts.
- **Texture**: halftone, paper fibres, torn edges, the brand's own photos.
- **Sound**: music-led: funk, boogie, lo-fi, latin, brass; paper and stamp sounds from the brand's world.
- **Banned**: glass, glows, neon, 3D.

## 6. Data story
- **When**: B2B, fintech, logistics, analytics, reports, anything proven by numbers.
- **Canvas**: dark navy or clean white; a fine grid.
- **Type**: a clean sans for words, a mono or tabular figure face for numbers (numbers never jump: they roll).
- **Colour**: neutral charts, one accent for the number that matters, red only for the problem.
- **Motion**: charts drawing, bars rising, counters rolling to real values, routes drawing across a map, split-flap
  boards; springs base; stagger ⅛, hold 2 (numbers need reading time).
- **Transitions**: zoom from the whole chart into the one bar; a line that becomes the next chart's axis.
- **Camera**: slow, deliberate; a push into the key number.
- **Texture**: real data only, each figure with its source in the brief; an illustrative value carries "Example".
- **Sound**: cinematic hybrid or minimal pulse; a tick per digit, a chime when the payoff number lands.
- **Banned**: invented statistics, 3D pie charts, dashboards that exist nowhere.

## 7. Playful pop
- **When**: kids, education, consumer apps, delivery, pets, games, anything friendly and bright.
- **Canvas**: bright flat colours, a colour change per scene.
- **Type**: a rounded bold face; words bounce in.
- **Colour**: 3–4 saturated brand colours, used in blocks.
- **Motion**: squash and stretch, bouncy springs (play), stickers popping, confetti on the payoff; stagger ⅛, hold 1½.
- **Transitions**: a shape that grows to fill the frame in the next colour; bounces.
- **Camera**: bouncy pushes on the hits.
- **Texture**: flat shapes, a thick outline, the mascot if the brand has one.
- **Sound**: ui-led: marimba or pluck pop, a pop per element, boings, a success arpeggio.
- **Banned**: dark grounds, heavy type, glows, aggressive genres.

## 8. Cinematic premium
- **When**: luxury, real estate, jewellery, premium wellness, serious B2B, a founder's film.
- **Canvas**: deep colour or black; or a quiet light stone colour.
- **Type**: a thin or high-contrast serif, generous tracking, small words with a lot of space.
- **Colour**: a restrained palette, metallic or muted accent.
- **Motion**: slow pushes (log zoom), light sweeps, long holds, few moves at a time; springs heavy; stagger ½, hold 3.
- **Transitions**: light streaks, slow dissolves through a shape, match cuts.
- **Camera**: slow and continuous; the frame always breathes.
- **Texture**: film grain, soft light, the product's real photography.
- **Sound**: music-led, low–mid energy: ambient pulse, cinematic hybrid, piano and glass; long tails.
- **Banned**: slams, shakes, flashes, bouncy easing, speed lines.

## 9. Grid system
- **When**: a brand with several products or features to show at once; portfolios; loops for social.
- **Canvas**: a strict 2×2 or 3×3 grid on a neutral ground; gutters as a design element.
- **Type**: a big grotesk, one statement across the grid.
- **Colour**: black and white plus one colour, or each cell in one brand colour.
- **Motion**: every cell a mini-scene moving in sync on the beat; cells swap on downbeats; springs snap; stagger ⅛.
- **Transitions**: cells flipping, the grid collapsing into one cell that fills the frame.
- **Camera**: static; the grid is the camera.
- **Texture**: real product shots per cell.
- **Sound**: music-led, driving and steady (broken beats, garage, jersey club); a hit per cell change.
- **Banned**: slow holds, uneven cells, more than one statement at a time.

## How to pick
1. The brand's surfaces first: a white site → 1, 3, 5 or 7; a dark site → 2, 4, 6 or 8.
2. The voice and the audience second (`direction.md` §4): developers → 2 or 1; kids → 7; luxury → 8; food → 5.
3. The direction's energy third: calm films take 3, 5 or 8 more easily; driving films 1, 2, 4, 7 or 9.
4. Not the card the last video in this folder used (look at its README). Two cards can blend when the brand spans
   both (a fintech app: 1 with the numbers of 6) — one leads.

# Pipeline: previews, renders, formats, delivery, troubleshooting

## Contents
1. Project layout
2. The capture protocol
3. Fonts and images
4. Previewing without rendering
5. Rendering
6. Motion blur
7. Formats and platforms
8. Language cuts
9. Cutdowns and covers
10. QA
11. What to re-run after a change
12. Long films
13. Another engine: Remotion, HyperFrames, an editor
14. Troubleshooting (known traps)

## 1. Project layout

```
index.html, css/fonts.css, css/style.css    the page (brand tokens in style.css)
js/timeline.mjs    W, H, FPS, BPM, b(), DURATION, S (scene windows), ENERGY (per scene), CUE, WHIPS, COVERS, LOOP — shared with the score
js/copy.mjs        every word and contact, per language — shared with the score;  js/lint.mjs  words from elsewhere
js/engine.js       time: ease, spring, SPRING, track, zoomLog, hash, noise; the DOM: el, set, show, splitChars
js/kit.js          scene helpers: textBlock, fitFont, slam, whip, rise, camera, roll, scramble, shakes, sparks, speed lines
js/main.js, js/reel.js, js/i18n.js
js/scenes/*.js     one file per scene: build(ctx) → (t, frame) => void; SCENES in reel.js lists them in order
js/screen.js       the WebGL footage screen (created on first use);  js/footage.mjs  frames and speed ramps;
                   js/footage.data.mjs  the cuts (written by tools/footage.mjs);  js/captions.mjs  SRT / VTT → chunks
audio/score.mjs    this video's score;  audio/synth/  the synth library;  audio/kit/  recorded sounds + KIT.md (tools/kit.mjs)
tools/             capture, render, qa, plan-check, pops, audio-check, energy, sound-print (+ demo-print.json), kit,
                   footage, cutdown, aac, export-timeline (all .mjs)
README.md          the direction card, the story table, the sound brief;  brief.md  facts + sources;  REVIEW.md  critique rounds
assets/fonts, assets/img, assets/ui (ui-shot.mjs: element PNGs + ui.json), assets/footage (scan.json, sheets, cuts)
out/               renders, covers/, qa/, review/, stills/, timeline.json;  .cache/  browser profiles, render chunks
brand/             site-kit.mjs: site.md, site.json, shots/, sections/, logo/, fonts/ (+ fonts.css), img/, palettes
refs/              references (fetched clips + <name>.post.json), refs/analysis/ (ref-sheet: sheets and numbers)
```

## 2. The capture protocol

`tools/capture.mjs` serves the project on a random local port, opens `index.html` in a headless Chromium (Chrome, Edge,
Chromium or Brave — found automatically; `--browser <path>` or env `CHROME_PATH` to choose), and talks to it over the
DevTools protocol. The page must expose `window.__ready` (true after fonts, images and scenes are built),
`window.__render(t, frame)` (draw time t), and optionally `window.__samples(t)` (blur samples wanted: 16 in WHIPS,
else 8). Scenes get `(t, frame)`: `t` moves inside the shutter for motion blur, `frame` is the output frame every
sample of it shares — text that changes is computed from `frame / FPS`, so a blurred frame never mixes two values.
With `LOOP` in the timeline, `__render` wraps `t` into [0, DURATION): the last scene can run into the first one's
look, and QA's `loop` row checks that the last frame meets the first. Every browser gets its own profile in
`.cache/browser/` and its own ports, so several renders can run side by side on one machine — never kill browser
processes you did not start.

## 3. Fonts and images

- `main.js` loads every `@font-face` in `css/fonts.css` before building; a missing file prints `[fonts] cannot load`.
- The template bundles Montserrat 700 / 900 / 900 italic and JetBrains Mono 400 / 700 (SIL OFL; Latin and Cyrillic,
  arrows). A character a font lacks is drawn by a system font and looks pasted in: `main.js` prints
  `[fonts] <family> has no glyph for "₹"` for every such case in the built scenes. Use the
  brand's font files if you have them, or an OFL font (fonts.google.com); keep the licence file next to them.
- `site-kit.mjs` downloads the Google Fonts a site uses into `brand/fonts/` as full TTFs (every script in one file,
  static weights 100 apart) and writes `brand/fonts/fonts.css` with rules ready for `css/fonts.css`; its coverage line
  says whether each draws the letters and signs of the site's own text, and names the ones it lacks. Sites rename fonts ("brandMulish", "__Inter_1a2b3c", "plexMono"); the
  tool maps them back to the Google name.
- Some display fonts lack glyphs (a no-break space, a newer currency sign, arrows) and show empty boxes: replace the character or pick
  a font that has it; check every language's sheet.
- Images: PNG / JPG / WebP in `assets/img`, pre-scaled to ≤ 2× their on-screen size; preloaded as `<img>` in build.

## 4. Previewing without rendering

```
node tools/capture.mjs sheet 0 12 24 [--query only=hook,proof] [--cols 6]     contact sheet (with a time label)
node tools/capture.mjs still 3.75 4.2 8 [--out out/stills] [--debug]          full-size PNG frames
node tools/capture.mjs eval "document.querySelectorAll('.card').length" --times 5
node tools/capture.mjs review [--out out/review]                         the critique set (below)
node tools/capture.mjs verify [--n 12]                                   is every frame a function of t?
```
Times are seconds, or beats with a `b` suffix (`still 16b 16.5b`, `sheet 0b 32b 24`, `render.mjs --range 24b-32b`) —
the timeline counts in beats, the tools in seconds; the suffix saves the conversion mistakes.
`?only=scene1,scene2` builds a subset (fast); `?debug` shows time / beat / bar. Look at the sheet after every scene,
and at full-size stills around every CUE and transition (± 0.1 s): overflow, overlaps, empty frames, readability.

`review` writes what a harsh director looks at before a render (SKILL.md step 7): `beats.png` — a frame on every
beat, the whole film on one page; `phone.png` — frames at 360 px wide, as a feed shows them, without the debug
overlay (can the words be read?); `strip-<t>s.png` — 12 frames through the middle of each fast move in `WHIPS`
(does it smear the right way, does anything pop?). `verify` renders the same frames forward, backward and shuffled
and hashes what is visible (elements and canvases): a scene that keeps state between frames, reads the clock or
rolls `Math.random` FAILs — the kind of bug that makes chunks rendered by different workers not join. Run it
after each scene, and before every full render.

## 5. Rendering

```
node audio/score.mjs                       the score first (out/music.wav)
node tools/render.mjs --draft              half size, no blur: ~1–2 min for 30 s — timing check with sound
node tools/render.mjs                      full quality → out/<slug>.mp4, out/<slug>-web.mp4, out/covers/, QA
node tools/render.mjs --range 12-18        re-render only the 2-s chunks touching 12–18 s, reuse the rest
node tools/render.mjs --skip-frames        re-mux only (after changing the score) — seconds
```
`--jobs N` sets parallel browsers (default ≈ CPU threads / 3; lower it on a busy machine), `--chunk` the chunk
length, `--query lang=en` a language cut, `--grain 0` no film grain. Full quality costs roughly 1–2 minutes of wall
time per second of video on 3–4 workers at 1080p60 with blur; plan renders, don't repeat them for small fixes —
use `--range`.

Nothing half-made replaces a good file: every chunk and every delivery file is written beside its final name
(`.partial`) and moved there only when complete. A stopped render resumes with `--range <where it stopped>-<end>`:
the chunks already in `.cache/` are reused, and a chunk missing anywhere is rendered too. On Windows a video open
in a player cannot be replaced — the render says so and leaves the new one as `<name>.partial.mp4`.

## 6. Motion blur

Each output frame averages up to 16 captures spread over a 180° shutter (half the frame interval), in ffmpeg (`tmix`).
Frames where nothing moves are detected (first and last capture identical) and captured twice instead of 16 times,
so static holds are cheap. `WHIPS` in the timeline marks fast moves for 16 samples; elsewhere 8. Blur comes for free
from real motion — never fake it with CSS blur.

## 7. Formats and platforms

`scripts/new-project.mjs --format 16:9 | 9:16 | 1:1 | 4:5` sets `W × H`; scenes size things in `U` (1 = 1080 px on
the short side) and can branch on `VERTICAL`.
- 16:9 1920×1080 — YouTube, X, VK, Telegram, websites.
- 9:16 1080×1920 — Reels, Shorts, TikTok, VK Clips, Stories: keep text inside the middle 1080×1420 (UI covers the top
  ~220 px and the bottom ~320 px).
- 1:1 / 4:5 — feeds.
- 60 fps for motion-heavy work (default), 30 fps halves render time.
- Master: H.264 High, CRF 15, yuv420p, AAC 320k 48 kHz, faststart. Web: CRF 21, AAC 192k, capped bitrate — small enough
  for messengers.
- Every delivery file's audio goes through `tools/aac.mjs`: FFmpeg's AAC encoder can add several dB of peak (a −5 dBTP
  score came out at 0.0 dBTP in a 192k copy), mostly through noise substitution and intensity stereo. Both are off, the
  encode is measured after decoding and made quieter by the excess if it still tops −1 dBTP. `node tools/aac.mjs <file>`
  prints any file's loudness and true peak.

## 8. Language cuts

Add `COPY.xx` in `js/copy.mjs` (same keys), then `node audio/score.mjs --lang xx` (sound that follows the text — typing
clicks, one pop per word — changes with it) and `node tools/render.mjs --query lang=xx`. `fitFont()` keeps longer
translations inside the frame; check a sheet of the new cut. To prove a cut did NOT change after edits to shared
code, compare a hash of `#stage` markup over many times (`capture.mjs eval`) and the WAV's md5 before and after —
pixels vary run to run, markup and audio bytes do not.

## 9. Cutdowns and covers

`node tools/cutdown.mjs --ranges "0b-8b,24b-32b,56b-64b"` builds a short version from the rendered frames and the
score, cut on bars (`b` = beats), with 20 ms audio fades at joins and a longer fade at the end, then QA'd like the
master. Covers: the times in
`COVERS` are saved as PNGs after the final render (a strong mid-video frame and the end card).

## 10. QA

`tools/qa.mjs` runs after every render: codec, size, fps, duration against the timeline, audio stream, loudness and
true peak, black stretches, frozen stretches (a held end card is expected), `flash` (runs of near-empty frames
between scenes — the gap a 24-frame sheet never lands on; look at stills there), the `look` (dark / light — is it the
brand's?), silences, leftover `@template-demo` code in the files the video uses, whether the soundtrack is new
(`unique`: FAIL on the demo score, WARN at ≥ 0.75 to a promo next to this project), and a contact sheet of the
encoded file (`out/qa/<name>-sheet.png` — look at it). No FAIL may remain; every `flash` is either fixed or a hold
you meant. Four rows read the picture the way a viewer does:

- `hook` — the longest still stretch in the first 1.5 s: over 0.5 s, the opening waits instead of grabbing (WARN);
- `pops` — a single frame unlike both its neighbours while they match each other (a flicker, a scene shown for one
  frame, an element that blinks at a boundary); the times are listed — look at stills there (`tools/pops.mjs
  <video>` runs it alone);
- `edges` — text cut by the frame at a settled moment of a scene (a long word, a translation, a number that grew);
- `language` — a word on screen in another script than the video's language (`<html lang>`, from `DEFAULT_LANG` or
  `?lang=`): copy left from another brief, or the wrong language code (WARN); `demo` — the template demo's own lines
  or contacts on screen (FAIL);
- `loop` — only with `LOOP`: the last frame against the first; a visible jump FAILs.

Before any of this, `tools/plan-check.mjs` checks the plan itself (SKILL.md step 4): the energy the person asked
for against `ENERGY`, the first second, something new every 4 s, the end card's hold, holes between scenes, a scene
counter in the copy, copy written in another script than its language.
`tools/audio-check.mjs` checks the score alone (sound-design.md §11) and whether it is new (§12): it writes
`out/qa/<name>-print.json`, which later projects in the same folder compare against. `node tools/sound-print.mjs
a.wav --against b.wav dir/` compares any files (it reads mp3/mp4 too; the first analysis of a file is cached).

## 11. What to re-run after a change

| You changed | Re-run |
|---|---|
| a word or a contact (`js/copy.mjs`) | stills of the scenes that show it; `audio/score.mjs` when sound follows the text (typing, a pop per word); `render.mjs --range` over those scenes |
| one scene file | its sheet and stills, `capture.mjs verify`; `render.mjs --range <its window>` |
| `js/timeline.mjs` (tempo, windows, cues) | `plan-check.mjs`, the score, a full render — every frame after the change moves |
| `audio/score.mjs` | `score.mjs --report`, `audio-check.mjs`, `render.mjs --skip-frames` (seconds: no frames are captured) |
| colours or fonts (`css/`, `assets/fonts`) | stills in every language; a full render |
| a recorded sound (`audio/kit/`) | `tools/kit.mjs` on the new file (its peak moves), the score, `render.mjs --skip-frames` |

## 12. Long films

Past ~90 seconds a video is built like a film: one plan, several makers, stricter checks.

- **Pick the sync backbone before any scene.** The beat grid (the default) holds to about 90 s. A film cut to an
  existing song takes the song's grid and drops from `ref-sheet.mjs`; sung words appear from a table of lines
  `[start, end, text]`, each word revealed over a share of its line (longer words take longer). A chorus that comes
  back returns to the same stage and escalates it each time — the motif the viewer learns. A voiced film is driven by
  its narration: the scene windows are the real clip lengths chained together (a short pause before, a gap between,
  a tail after), never hand-picked seconds. The person supplies the voice-over files (or an SRT / VTT with line
  times); `tools/kit.mjs vo/*.wav` gives each clip's length.
  ```js
  // js/timeline.mjs — a voiced film: the clip lengths from audio/kit/KIT.md, in the order of the script
  const VO = [['hook', 3.84], ['problem', 6.21], ['how', 9.02], ['proof', 7.4], ['end', 4.1]];
  const PRE = 0.5, GAP = 0.4, TAIL = 2.5, OVER = 0.3; // a breath before the first line, between lines, after the last
  export const LINE = {};                             // where each clip starts
  let at = PRE;
  for (const [name, len] of VO) { LINE[name] = at; at += len + GAP; }
  export const DURATION = at - GAP + TAIL;
  const from = VO.map(([n]) => LINE[n] - PRE);        // a scene arrives just before its line; the first one at 0
  export const S = Object.fromEntries(VO.map(([n], i) => [n, [from[i], i + 1 < VO.length ? from[i + 1] + OVER : DURATION]]));
  ```
  The score places each clip from the same table — `sample(LINE.hook, 'audio/kit/vo-hook.wav', { align: 'start' })` —
  and thins its parts while a line plays; the hits still sit on the beat grid inside the windows.
- **One story bible.** The direction card grows: a palette arc per chapter, one recurring motif that pays off at the
  end, and for a dense stretch the reads (`story-and-motion.md` §4) in order, each with its window.
- **Split the work so no two makers touch one file.** A film of vignettes splits in time — one scene file per
  20–40-second chapter, each importing the shared timeline, palette and kit. One continuous world splits by concern —
  the camera, the map, the particles, the overlay each own a module every scene calls. Each maker edits only their
  file; a bug in a shared file is reported to whoever owns it, never patched in passing.
- **Brief every maker with the same words.** Paste the direction card's palette, type and banned list verbatim into
  every maker's brief — a paraphrase drifts the look within two chapters. Give each its window and its slice of the
  cues; done means a sheet across its own boundaries and `verify` passing on its range.
- **Render in larger pieces.** `--chunk 4` or more cuts the per-chunk overhead of a five-minute render; iterate with
  `--range` and never re-render the whole film for one fix.

## 13. Another engine: Remotion, HyperFrames, an editor

`node tools/export-timeline.mjs` writes `out/timeline.json`: the size and fps, every scene window in seconds and in
frames, the named cues with their beats, the fast moves, the energy plan and the score's path. A Remotion composition
places its `<Sequence from={fromFrame} durationInFrames={frames}>` and its `<Audio>` from it; a HyperFrames page its
clips; an editor its markers. The cuts still land on the beats the music was written to. This skill renders by itself;
the export is for a person who finishes the film elsewhere. Remotion needs a company licence for a business of four
or more people — say so when you point someone to it.

## 14. Troubleshooting (known traps)

| Symptom | Cause | Fix |
|---|---|---|
| `page never set window.__ready` | a scene threw while building (see `[page error]`), or a missing module | fix the error; run `still 0` to iterate |
| text in a fallback font / wrong widths | font file missing or not declared | check `[fonts]` warnings, paths in css/fonts.css |
| element stays invisible after a fade | `set()` without `o` falls back to CSS; `vis: false` sticks until `vis: true` | pass `o` every frame; pass `vis: true` when showing |
| two transforms fight | `set()` rebuilds the whole transform | combine x, y, s, r in one call |
| a scene's background hides the previous scene | an early window with an opaque backdrop | fade the backdrop in with its first element |
| a visible browser window pops up | `chrome.exe --version` on Windows launches the browser instead of printing | never run it; `capture.mjs doctor` finds the browser without starting it |
| a process "ended" at once but is still running (Windows, Git Bash) | `kill -0 <pid>` does not see Windows PIDs | check with PowerShell `Get-Process -Id <pid>` |
| render: "the project changed during the render" | a file was edited while chunks were rendering | re-render what the edit touches (`--range`), or everything; edit between renders |
| the previous scene shows through a new scene after its wipe | a `clipPath` wipe hides, it does not paint | give the clipped scene an opaque `var(--bg)` background |
| a few flat frames between a wipe and the next slam (QA: `flash`) | something is gated to its own cue (`o: t < cue ? 0 : …`) while the thing before it has already gone — a backdrop, a glow or the hero itself | blend the incoming element with the transition's progress; `capture.mjs sheet a b 12` across the range QA names |
| a wipe reads as a flash | too fast / wrong ease | `inOutSine` over ≥ 0.3 s |
| blank or half-drawn frames | an image swapped mid-render, or unloaded | preload `<img>`s; don't change `src` per frame |
| Node cannot import a shared module | the score imported a `.js` file (CommonJS in Node) or one that touches the DOM | shared data in `.mjs`, no DOM at module level |
| render much slower than expected | huge images, animated CSS filters on big layers, too many workers for the CPU | pre-scale images, bake filters, lower `--jobs` |
| `EADDRINUSE` / a stuck profile | an old custom script with fixed ports | the tools pick free ports; delete `.cache/browser/<stale>` |
| audio clicks | a voice without attack / release ramps, or a cut without fades | ramp every start / end; `cutdown.mjs` fades joins |
| a recorded sound lands late on its hit | it was placed from its start; a whoosh peaks 0.7 s in | `sample()` places the loudest moment on the cue by default (`align: 'peak'`); `tools/kit.mjs` lists each file's peak |
| `verify` FAILs at some times | a scene keeps state between frames, reads the clock, or rolls `Math.random` | compute everything from `t` (and text from `frame / FPS`); `hash(i, seed)` for randomness |
| `[screen] cannot load assets/footage/…` | the cut was not made, or a source second past its end | `node tools/footage.mjs cut …`; `frame()` clamps inside the cut, a hand-built url does not |
| an empty frame in a footage shot (QA `flash` / `pops`) | an image drawn but not listed in `render.needs(t)` | list every url the frame draws, the echo's too |
| "WebGL2 is not available" | a browser without WebGL2 (an old Chromium, GPU switched off by policy) | Chrome or Edge; headless draws it in software |
| a number shows two values at once in a blurred frame | the counter was computed from the sample time | compute it from `frame / FPS` |
| `ui-shot`: "not clicked: … submits a form" | the target is a submit button, or a plain button inside a form | stage the state another way (`--eval`, `--type` without submitting) |
| `ui-shot`: "blocked N request(s) that would have sent data" | the page tried to post something (a form, a tracker, a beacon); only GET, HEAD and OPTIONS leave the browser | the shot is still right unless the state needed the server's answer — then stage that state with `--eval` |
| loudness far off target | a huge peak (fx hit) makes the limiter pull hard | lower that bus; see the render's limiter report |
| `/json/new?url` loses query params after `&` | a DevTools quirk | the tools open about:blank, then navigate |
| numbers or words cut at the edges | long translations / big numbers | `fitFont()`; wider boxes; check every language |
| system drive fills up | caches in the temp folder | the tools keep caches in the project's `.cache/` |
| site-kit: "the site shows a bot check" | the site blocks automated browsers | do not work around it; ask the user for screenshots and the texts |
| site-kit: no logo found, or the candidates are icons | a wordmark drawn in CSS, a canvas logo, an unusual header | the 4× screenshots in `brand/logo/`, the icons and the share image; else ask for the file |
| site-kit: a font "not on Google Fonts" | the site serves its own (possibly licensed) font, or Adobe Fonts | use it only if the client owns it; otherwise the closest open font |
| site-kit: empty areas in a screenshot | content that appears on scroll or on hover | the tool scrolls through with reduced motion; use `sections/` and the phone shots, or ask for screenshots |
| site-kit on a t.me link gives only an avatar | the page's logo, colours and fonts are Telegram's | by design: the avatar's palette and the description are the brand's |
| ref-sheet: NOT FETCHED "the post has no video or image" | a text post, an X article, a thread whose clip is in a reply | ask for the clip or the right post link |
| ref-sheet: NOT FETCHED "… without yt-dlp" | YouTube, Instagram, TikTok, Vimeo need yt-dlp | ask for the file; install yt-dlp only with the user's consent |
| ref-sheet: "no hard cuts: one continuous shot" | motion design moves by wipes and morphs, not cuts | read the motion line (hits per minute, share on the beat) and the key-frame sheet |

# Scene cookbook

Code patterns for the scenes, using the template's `js/engine.js` (`el`, `set`, `P`, `ease`, `clamp`, `lerp`, `keys`,
`spring`, `SPRING`, `track`, `zoomLog`, `hash`, `noise1`, `rng`) and `js/kit.js` (`U`, `VERTICAL`, `W`, `H`, `fitFont`,
`spans`, `slam`, `whip`, `shake(s)`, `flash`, `roll`, `rise`, `camera`, `scramble`, `slashClip`, `ring`, `makeSparks` /
`drawSparks`, `drawSpeedLines`).
Adapt them — they are idioms, not finished scenes. The person's own footage and photos on the WebGL screen (speed
ramps, whips that carry the camera, grades, a screen recording zoomed to the work) live in `footage.md`.

## Contents
1. Scene skeleton and the frame contract
2. Kinetic type: a word per beat
3. Per-letter reveal
4. Decode text
5. Rolling numbers
6. Typing, shared with the score
7. Glass card / UI panel with a cursor
8. Phone mockup with a scrolling feed
9. 3D photo wall from the client's photos
10. Map with routes drawing
11. Traced logo: letters, cut, sparks
12. Logo drawing on (stroke → fill)
13. Brand-angle wipe
14. Zoom-through
15. 2×2 grid of mini scenes
16. Particles, speed lines, light streaks
17. Split-flap board
18. Charts and progress
19. The lockup (CTA + contacts)
20. Images, performance, sharing data with the score
21. Split and open: a shape cracks into two halves
22. One shape, never cut: a morphing container
23. The smart-camera screen demo
24. Words rising out of a mask line
25. The proof number
26. The loop end card
27. Construction wipe
28. Rack focus

## 1. Scene skeleton and the frame contract

```js
import { el, set, P, ease, clamp } from '../engine.js';
import { CUE, S, b } from '../timeline.mjs';
import { TX } from '../i18n.js';
import { W, H, U, fitFont, slam } from '../kit.js';

export async function build(ctx) {             // runs once: build DOM, measure text (fonts are loaded)
  const root = el('div', 'scene', ctx.stage);
  root.style.zIndex = '4';                      // later scenes above earlier ones
  const title = el('div', 'kin', root, TX.offer);
  title.style.fontSize = `${180 * U}px`;
  const tw = fitFont(title, W * 0.88);
  return (t, f) => {                            // runs every frame: a pure function of t (f = the frame number)
    const on = t >= S.offer[0] && t <= S.offer[1];
    set(root, { vis: on });
    if (!on) return;
    const s = slam(t, CUE.offer);
    set(title, { x: W / 2 - tw / 2, y: H * 0.4, s: s.s, o: s.o });
  };
}
```

The contract: a frame depends only on `t` — no CSS animations or transitions, no `Date`, `Math.random`, timers,
`<video>`; text that changes (a rolling number, decoding letters, typing) is computed from the frame's own time
`f / FPS`, so the motion-blur samples of one frame all show the same characters and only the movement blurs; every animated property is written every frame (`set()` rewrites the whole transform and opacity; pass `o`
for anything you ever fade); a scene hides itself outside its window; an early-starting scene must not cover the
previous one with an opaque background (fade its backdrop in with its first element).

Two traps of `set()` that look right in code: a second `set()` on the same element in the same frame wipes the first
(the page warns once: `[page] set() called twice on …`) — build one call; and a position set once in `build()` is
wiped by the first frame's `set()` without `x`/`y` — pass the position every frame, or place the element with CSS
`left` / `top` and animate only the rest. Within a scene, later-created elements paint on top; give layers an
explicit `zIndex` (background, hero, foreground accents) instead of relying on the order of `el()` calls.

## 2. Kinetic type: a word per beat

```js
const words = TX.claim.map((w, i) => {
  const d = el('div', `kin${i === TX.claim.length - 1 ? ' accent glow' : ''}`, root, w);
  d.style.fontSize = `${220 * U}px`;
  return { d, w: fitFont(d, W * 0.86), t0: CUE.claim + b(i) };
});
// frame:
words.forEach((wd, i) => {
  const s = slam(t, wd.t0, { from: 1.7, dur: 0.24 });
  set(wd.d, { x: W / 2 - wd.w / 2, y: H / 2 - 100 * U + (i - 1) * 205 * U, s: s.s, skx: -10 * (1 - clamp((t - wd.t0) / 0.24)), o: s.o });
});
```
Pair with `shakes(t, words.map((w) => w.t0), 14, 0.35)` on the camera layer and an `impact` per word in the score.

Lines under or through text (underlines, strokes that draw, strikethroughs) go from the measured box
(`getBoundingClientRect()` after fonts load), never from the font size: descenders (g j p q y, and their
kin in other scripts) hang below the baseline, and an underline placed for capitals cuts through them. Check a still.

## 3. Per-letter reveal

```js
const line = el('div', 'kin', root);
const chars = spans(line, TX.brand);            // inline-block spans
// frame: each letter 1/16 beat after the previous, rising from below a mask
chars.forEach((c, i) => {
  const p = ease.outExpo(clamp((t - (CUE.logo + i * b(0.25))) / 0.4));
  set(c, { y: lerp(120 * U, 0, p), o: p > 0 ? 1 : 0 });
});
line.style.clipPath = 'inset(0 -20% 0 -20%)';  // hides letters below the baseline box
```

## 4. Decode text

```js
node.textContent = scramble(TX.vin, clamp((t - CUE.decode) / 0.8), t, 3);   // monospace font keeps the width fixed
```

## 5. Rolling numbers

```js
num.textContent = roll(f / FPS, CUE.stat, 0.9, 0, 1200).replace(/\B(?=(\d{3})+(?!\d))/g, ' ');   // 1 200
```
In the score, place ticks where the digits change with the same easing (outCubic: `t0 + dur * (1 - Math.cbrt(1 - k / n))`).

## 6. Typing, shared with the score

Put the schedule in a `.mjs` file so the score imports the same times:

```js
// js/typing.mjs — plain ESM, no DOM: the picture prints letters, the score clicks keys
import { CUE, b } from './timeline.mjs';
export const typeTimes = (text, t0 = CUE.typing, step = b(0.125)) => [...text].map((_, i) => t0 + i * step);
```
Picture: `node.textContent = TX.query.slice(0, typeTimes(TX.query).filter((x) => x <= t).length)` + a caret that
blinks on beats. Score: `typeTimes(TX.query).forEach((t) => A.key(t, { vel: 0.5 }))`.

## 7. Glass card / UI panel with a cursor

```js
const card = el('div', 'card', root, `<div class="ui-title">${TX.panel}</div>`);
Object.assign(card.style, { width: `${720 * U}px`, height: `${440 * U}px`, backdropFilter: 'blur(18px)' });
const cursor = el('div', 'abs', root, '<svg width="40" height="40" viewBox="0 0 24 24"><path d="M3 2l7 19 2.5-7.5L20 11z" fill="#fff" stroke="#000" stroke-width="1"/></svg>');
// frame: the cursor glides to the button, presses (scale 0.9 for 0.1 s), the button lights up
const k = keys(t, [[CUE.move, [1400, 900]], [CUE.move + 0.6, [980, 610], ease.inOutCubic]]);
const press = t > CUE.click && t < CUE.click + 0.1;
set(cursor, { x: k[0] * U, y: k[1] * U, s: press ? 0.9 : 1, o: 1 });
```
Score: `click(CUE.click)`; a `success` when the result appears.

## 8. Phone mockup with a scrolling feed

A rounded rectangle (radius ~12 % of its width) with a notch, `overflow: hidden`; inside, a tall column of UI blocks
moved by `y = -scroll(t)` where `scroll` is `keys()` with `ease.inOutCubic` stops on each beat. Real screenshots from
the client can be the blocks (crop them; blur personal data).

## 9. 3D photo wall from the client's photos

```js
const wall = el('div', 'layer', root);
wall.style.perspective = `${1600 * U}px`;
const tiles = photos.map((src, i) => { const im = el('img', 'abs', wall); im.src = src; im.style.width = `${300 * U}px`; return im; });
// frame: tiles fly in from depth one per 32nd note, then the wall rotates slowly
tiles.forEach((im, i) => {
  const p = ease.outExpo(clamp((t - (CUE.wall + i * b(0.125))) / 0.5));
  const col = i % 8; const row = Math.floor(i / 8);
  set(im, { x: (col - 3.5) * 320 * U + W / 2 - 150 * U, y: (row - 2) * 230 * U + H / 2 - 100 * U, z: lerp(-2000, 0, p), ry: lerp(35, 0, p), o: p > 0 ? 1 : 0 });
});
set(wall, { ry: -8 + 6 * P(t, CUE.wall, S.orders[1]), o: 1 });
```
Pre-scale photos with ffmpeg to about twice their on-screen size (`ffmpeg -i in.jpg -vf scale=640:-2 out.jpg`) — big
images slow every capture.

## 10. Map with routes drawing

SVG paths for routes; set `stroke-dasharray` to the path length (`path.getTotalLength()` at build) and animate
`stroke-dashoffset` from the length to 0; stops pop (scale 0 → 1, `outBack`) when the route reaches them (compute the
time from the length fraction). Do not draw borders or territory claims you cannot source.

## 11. Traced logo: letters, cut, sparks

`node <skill>/scripts/trace-logo.mjs logo.png --out assets/logo` → `assets/logo.json` with one shape per letter
(sorted left → right). Build one `<svg>` per shape (or one svg with a `<path>` each) and slam them one per 16th; for a
two-colour logo trace each colour (`--mode color --color #hex`) and layer them. A cut: a clip-path polygon at the
logo's own angle sweeping across, with `makeSparks` along its edge.

## 12. Logo drawing on (stroke → fill)

```js
// build: path.style.fill = 'transparent'; path.style.stroke = 'var(--text)'; const len = path.getTotalLength();
path.style.strokeDasharray = `${len}`;
// frame:
path.style.strokeDashoffset = String(len * (1 - P(t, CUE.logo, CUE.logo + 0.8, ease.inOutCubic)));
path.style.fillOpacity = String(P(t, CUE.logo + 0.7, CUE.logo + 1.0));
```

## 13. Brand-angle wipe

```js
nextScene.style.background = 'var(--bg)';   // a clip only hides: without a fill the old scene shows through the holes
nextScene.style.clipPath = slashClip(P(t, CUE.wipe, CUE.wipe + 0.35, ease.inOutSine), 24);   // the logo's angle
```
Add a solid accent band riding the edge (a rotated div following the same x) and a `whoosh` of the same length.
Without a wipe, an opaque backdrop of the incoming scene fades in over the overlap of the two windows —
`P(t, S.next[0], S.prev[1])` — never before the old scene starts leaving (it covers the exit) and never after it is
gone (flat frames).
Whatever glows or moves in the background of the new scene follows the wipe's progress, not the new scene's first
cue — otherwise the frames between the end of the wipe and the first slam are flat and dead (QA reports them as
`flash`; both traps are in pipeline.md §11).

## 14. Zoom-through

Scale the current scene around the centre of a letter's counter (the hole of an "O"), a dot or a screen: set
`transformOrigin` at that point, `s` from 1 to 30 with `ease.inExpo` over ~0.5 s; the next scene starts inside it at
`s` 0.6 → 1 (`outExpo`). A `whoosh` shape 'in' ending on the switch.

## 15. 2×2 grid of mini scenes

Four `.layer` cells (each `overflow: hidden`, a gap of 12–20 px, rounded corners); each runs its own mini animation from
the same `t` with an offset of a beat; the grid itself scales in from 1.1 and rotates 0 → -2°. Great for "four
features at once" or "four cases".

## 16. Particles, speed lines, light streaks

Draw on `ctx.fx` (cleared every frame, above all scenes):
```js
const sparks = makeSparks({ seed: 3, n: 180, t0: CUE.slash, spread: 0.3, origin: (u) => [x0 + u * len, y0], dir: -Math.PI / 3, cone: 0.8 });
if (t > CUE.slash && t < CUE.slash + 1.2) drawSparks(ctx.fx, sparks, t);
if (t > CUE.whip - 0.05 && t < CUE.whip + 0.4) drawSpeedLines(ctx.fx, t, { dir: -1, alpha: 0.5 });
```
Sparks glow and cool to red (light added on top). Confetti keeps its colours and paints normally — the right one on a
light background: `makeSparks({ …, ember: false, color: [[255, 90, 54], [255, 194, 75], [90, 160, 255]] })`.
A light streak: a long thin gradient div (transparent → white → transparent), `mix-blend-mode: screen`, sweeping
across with `ease.inOutCubic`, plus a `swish`.

## 17. Split-flap board

Keep the flip schedule (which character each cell shows, and when each flap falls) in a `.mjs` module; the scene draws
each cell as top / bottom halves and a flap rotating `rx` 0 → -90° (top) and 90° → 0 (bottom) over ~50 ms per flip;
the score imports the same schedule and plays one `tick` per flap (thinned to one per 10 ms bucket).

## 18. Charts and progress

Bars: width `lerp(0, value, ease.outCubic(p))` with staggered starts and the value rolling on top; lines: an SVG
polyline with the dashoffset draw-on; donuts: `stroke-dasharray` on a circle. Real data only.

## 19. The lockup (CTA + contacts)

The template's `lockup.js` is the pattern: the logo slams (+ ring, sparks, flash, shake, an `impact` + the sonic logo),
the tagline rises one beat later, the CTA slides in, contact pills pop one per half-beat with icons, the frame holds
with a slow push, a last hit on a downbeat. In portrait (`VERTICAL`) stack the pills.

## 20. Images, performance, sharing data with the score

- Preload images in `build` as `<img>` elements and toggle their visibility; never swap `img.src` during the render
  (an undecoded frame can get captured). `main.js` decodes every `<img>` before `__ready`.
- `object-fit: cover` for photos; `mix-blend-mode: multiply` to drop an off-white background from a raster logo.
- Prefer transforms and opacity; avoid animating `filter: blur()` on large layers every frame (slow) — use it on small
  elements or bake it into images; canvases for particles.
- An SVG `<clipPath>` must contain the shapes directly (a wrapping `<g>` clips everything away).
- Measure positions once in `build`, not per frame (layout inside transformed parents is unstable).
- Anything the score needs (word lists, schedules, curves) lives in `js/*.mjs` — plain ESM, no DOM — so Node can import
  it. Keep `copy.mjs` and `timeline.mjs` that way.

## 21. Split and open: a shape cracks into two halves

A bean cracks, a box opens, a logo splits along its own line: draw the shape twice, clip each copy to one side of the
line, and move the halves apart along the line's normal. Any SVG or HTML works — no path surgery.
```js
// build: two copies of the same mark, each clipped to one half-plane of the line through (x0, y0)–(x1, y1), in %
const halves = [0, 1].map(() => { const h = svgEl(markSvg, layer); h.classList.add('abs'); return h; }); // stacked, not in flow
halves[0].style.clipPath = 'polygon(0 0, 55% 0, 45% 100%, 0 100%)';      // left of the crack
halves[1].style.clipPath = 'polygon(55% 0, 100% 0, 100% 100%, 45% 100%)'; // right of the crack
// frame: apart along the normal of the crack, with a little rotation, sparks from the line (§16), a crack sound
const k = P(t, CUE.crack, CUE.crack + 0.35, ease.outExpo);
set(halves[0], { x: bx - 60 * k * U, y: by - 8 * k * U, r: -6 * k, o: 1 });
set(halves[1], { x: bx + 60 * k * U, y: by + 8 * k * U, r: 6 * k, o: 1 });
```
A curved crack: `clip-path: path('…')` with the same curve closing each side. Put what was inside (the wordmark, a
product) between the halves at a lower `zIndex`, so it is revealed as they part.

## 22. One shape, never cut: a morphing container

One element carries the whole scene: its box springs from state to state (a dot → a button → a card → a pill) while
its content swaps inside. If you can point at a moment where one thing disappears and another appears, it is a cut.

```js
const box = el('div', 'morph', root);           // CSS: position absolute; overflow hidden; background var(--surface)
const states = [                                // [cue, [x, y, w, h, radius]]
  [CUE.dot,    [W / 2 - 12 * U,  H / 2 - 12 * U,  24 * U,  24 * U,  12 * U]],
  [CUE.button, [W / 2 - 160 * U, H / 2 - 36 * U,  320 * U, 72 * U,  36 * U]],
  [CUE.card,   [W / 2 - 380 * U, H / 2 - 260 * U, 760 * U, 520 * U, 28 * U]],
  [CUE.pill,   [W / 2 - 120 * U, H / 2 - 30 * U,  240 * U, 60 * U,  30 * U]],
];
const faces = ['dot', 'button', 'card', 'pill'].map((n) => {  // real crops from ui-shot.mjs, transparent corners
  const im = el('img', 'abs', box); im.src = `assets/ui/${n}.png`; im.style.width = '100%'; return im;
});
// frame:
const [x, y, w, h, r] = track(t, states, SPRING.base);
Object.assign(box.style, { left: `${x}px`, top: `${y}px`, width: `${w}px`, height: `${h}px`, borderRadius: `${r}px` });
faces.forEach((face, i) => {
  // a face enters once its morph has started and leaves before the next one: never two at full opacity
  const tIn = states[i][0] + 0.08;
  const tOut = (states[i + 1]?.[0] ?? Infinity) - 0.1;
  set(face, { o: Math.min(clamp((t - tIn) / 0.12), clamp((tOut - t) / 0.1)) });
});
```
- The box's size changes through width and height, not a scale: the content inside keeps its own size and sharpness.
- A colour change is a shape too: a circle grows from the cursor and floods the box, instead of a fade.
- A big shrink uses a firmer spring (`SPRING.snap`) so an overshoot never clips the content ("Sent" cut to "Sen").
- A cursor drives the changes: each state's cue is a click (§7), and the score clicks from the same cues.

## 23. The smart-camera screen demo

The real product on one large card; a cursor does real actions; one camera zooms to wherever the work happens.

```js
const cam = el('div', 'abs', root);             // everything the camera films, the cursor included
cam.style.transformOrigin = '0 0';
const ui = el('img', 'abs', cam); ui.src = 'assets/ui/dashboard.png';   // ui-shot at 2×, drawn at its CSS size
const cursor = el('div', 'abs', cam, CURSOR_SVG);
const moves = [[CUE.m1, [1200, 700]], [CUE.m2, [310, 420]], [CUE.m3, [880, 520]]];          // in the UI's pixels
// the camera moves in the beat before each action and holds while it happens (a key repeated = a hold)
const shots = [[CUE.m2 - b(1), [960, 540, 1]], [CUE.m2, [360, 420, 2.2]], [CUE.m3 - b(1), [360, 420, 2.2]],
  [CUE.m3, [880, 520, 2.6]], [CUE.out - b(1), [880, 520, 2.6]], [CUE.out, [960, 540, 1]]];
const clicks = [CUE.m2 + 0.35, CUE.m3 + 0.35];                                             // the cursor has landed
// frame:
cam.style.transform = camera(t, shots).transform;  // not set(cam): set() writes its own transform
const [cx, cy] = track(t, moves, SPRING.base);
const press = clicks.some((c) => t > c && t < c + 0.1);
set(cursor, { x: cx, y: cy, s: press ? 0.88 : 1, o: 1 });
```
- One move at a time: the camera arrives, the cursor acts, then the next move; zoom is in log space (`camera()`).
- The cursor lives inside the camera, so it scales with the zoom like a screen recording.
- The camera arrives a beat before the click; UI text in focus is at least 28 px on screen at 1080p — zoom until it is.
- Score: a click per press (the same `clicks`), a soft whoosh per camera move, a ding when the result appears.

## 24. Words rising out of a mask line

```js
const line = el('div', 'rise-line', root);      // CSS: display flex; gap .28em; line-height 1.05
const lineH = 190 * U;
const words = TX.hook.map((w, i) => {
  const mask = el('span', 'mask', line);        // CSS: display inline-block; overflow hidden; height = lineH
  return el('span', i === TX.hook.length - 1 ? 'kin accent-face' : 'kin', mask, w);
});
// frame: each word starts a little before its beat, so it has settled when the beat lands
words.forEach((s, i) => set(s, { y: (rise(t, CUE.hook + b(i) - 0.12) / 100) * lineH, o: 1 }));
```
- The accent word takes the contrasting face (a serif italic) or the accent colour; nothing fades in.
- A second line: the first slides up by a line height on a spring, the next rises under it.
- A stack of real rows can follow, one per beat, and squeeze into one dot that becomes the next scene (§22).

## 25. The proof number

```js
// real rows from brief.md; the total is their sum — checked here, not trusted
const rows = [{ amount: 3150 }, { amount: 2400 }, { amount: 1275 }, { amount: 850 }];
const total = rows.reduce((a, r) => a + r.amount, 0);
// frame: from the frame's own time, so a blurred frame never shows a number that was never on the way
const tf = f / FPS;
let v = total;
rows.forEach((r, i) => { v -= r.amount * ease.outCubic(clamp((tf - (CUE.rows + b(2 * i))) / 0.5)); });
num.textContent = fmtMoney(Math.max(0, Math.round(v)));   // Math.max: never "-0.00"
```
- The payoff value lands on the drop (the last row's cue + its settle = `CUE.drop`).
- No spring on a number: an overshoot would show a value that is not real.
- Score: a tick per change of the displayed value (from the same schedule), a coin or a chime on each row, the
  impact on the payoff.

## 26. The loop end card

X plays short videos in a loop; when the last frame is the first, the loop disappears and people watch twice.

```js
// js/timeline.mjs: export const LOOP = true;   (QA compares the first and the last frame; main.js wraps the
// motion-blur samples of frame 0 around the end, so the seam frame is blurred like any other)
const fold = P(t, DURATION - b(2), DURATION, ease.inOutCubic);   // the last two beats fold everything back
set(logo, { s: lerp(1, 0.2, fold), o: 1 - fold });
set(dot, { s: lerp(0.2, 1, fold), o: fold });                    // at DURATION: exactly frame 0's dot
```
- Everything ends where frame 0 starts: positions, scales, colours, the cursor's place and its speed.
- The score's last bar leads into its first (its tail becomes the pickup), or the loop jumps in the sound.

## 27. Construction wipe

A line sweeps across an element: behind it the finished thing, ahead of it the wireframe — the product built in front
of the viewer (a logo from its outline, a screen from its skeleton).

```js
const p = P(t, CUE.build, CUE.build + b(2), ease.inOutSine);
done.style.clipPath = `inset(0 ${(1 - p) * 100}% 0 0)`;   // the real crop, revealed left of the sweep
rough.style.clipPath = `inset(0 0 0 ${p * 100}%)`;         // outlines only, right of it
set(sweep, { x: x0 + p * width, o: p > 0 && p < 1 ? 1 : 0 });
```
Score: a rising `toneSweep` under the sweep, a `sparkle` as it completes.

## 28. Rack focus

Two depths trade focus on a beat — a change of subject without a cut.

```js
const k = P(t, CUE.rack, CUE.rack + 0.5, ease.inOutCubic);
set(front, { blur: k * 10 * U, o: 1 - 0.3 * k });
set(back, { blur: (1 - k) * 10 * U, s: 1 + 0.03 * k, o: 1 });
```
Blur filters are costly to render: two layers at most, and not on large text that must be read at that moment.

# Sound design: an original score for every video

The picture is half of a promo. The other half is a track that belongs to this brand and this edit — never a generic
bed that could sit under any video. This file is how to choose it, write it, and check it without ears.

## Contents
1. Working without ears
2. The sound brief (write it before any code)
3. Choosing the sound: brand × audience × pace of the edit
4. When the user names a sound (or brings a track)
5. The energy map: arrangement follows the story
6. The hook and the sonic logo
7. Brand-world sounds: the signature of each video
8. The SFX map: every visible event gets a decision
9. Mixing
10. Loudness
11. Checking: report, audio-check, the spectrogram
12. Never the same twice: the fingerprint check and what to change

## 1. Working without ears

You cannot listen to what you make, so every decision rests on four legs:
- **Structure you know works**: genre patterns (genre-cards.md), progressions, arrangement conventions.
- **Calibrated voices**: at `vel: 1` every synth voice sits in a known range (one-shots peak near 0 dB, a 4-note pad
  ≈ -17 dB RMS, a lead ≈ -12 dB RMS, a bass ≈ -6 dB RMS); bus defaults set a sane balance. Change levels by bus gain
  and `vel`, in dB steps you can reason about.
- **Numbers**: `node audio/score.mjs --report` (per-bus level per scene) and `node tools/audio-check.mjs` (loudness,
  true peak, band balance, energy per scene).
- **Pictures**: `out/qa/music-audio.png` — spectrogram over waveform with every cue drawn as a line. Open it and read it
  (section 11). If the user can listen, ask them to check the draft: their ears beat every metric.

## 2. The sound brief

Write this into the project README before touching `audio/score.mjs`. It forces real choices instead of defaults.

```
Sound brief
- Feel / genre:   <genre> — because <brand personality, audience, pace of the edit>
- Tempo & key:    <BPM> (one bar = 240 / BPM s), <root> <mode> — chosen, not A minor by habit
- Energy:         <low | mid | high per scene = ENERGY in js/timeline.mjs> — from <the person's words | the references'
                  music arc | the promo default | a calm brand or placement> (direction.md §5)
- Role:           <music-led | ui-led> — music-led: the track carries the cuts; ui-led: every interface event is voiced
                  and the groove sits lighter under it
- Groove:         <family: four on the floor | backbeat | half-time | broken | no kick> — why this one;
                  kick <16 steps>, snare/clap <16 steps>, hats <16 steps>, straight or swung
- Kit:            kick <type, tune Hz, decay>, snare <type, tone, bright>, hats <metal, tone>, drums bus <colour>
- Percussion:     <conga, shaker, clave, toms… or none>
- Bass:           <voice> — <pattern / relationship to the kick>
- Harmony:        <progression> — <mood it gives>
- Hook:           <voice>, motif <notes, rhythm> — where it plays (always on the logo)
- Brand world:    <2–4 sounds from the product's world> — where each lands
- Energy map:     <scene → intro / build / drop / break / outro at its ENERGY, what enters and leaves>
- Transitions:    <risers, holes, tape stops, reverse cymbals — at which cues>
- Mix:            <LUFS target>, reverb <room|hall|plate|huge|dark>, what ducks under what
- Not like the last one because: <genre / tempo / key / kit / lead that differ>
```

## 3. Choosing the sound

Choose in this order — groove family, genre, tempo, key, kit — because a listener recognises a track by its groove
first and its chords last.

**First, look at what already exists.** List the promos in the folder where this project lives (and any folder the
user keeps promos in): `node tools/sound-print.mjs --list <folder>` prints each one's tempo, key and groove. Pick a
family and a genre none of them used. `node tools/sound-print.mjs --suggest "<brand>" --world <row> --in <folder>`
does both steps below for you: it orders the brand row's cards (the table further down) by the brand's name — the
same brand always gets the same start, different brands of one kind get different ones — puts four on the floor last
outside nightlife, moves the families, keys and tempos the folder already has to the back, and proposes a tempo, a key
and a kit character for each. It is a start, not a verdict: the user's words, the references and the edit win.

**The groove family.** Every video picks one on purpose:

| Family | The low end | Genres (card) | Feels |
|---|---|---|---|
| Four on the floor | a kick — or a bass note — on every beat (the fingerprint hears kick and bass together, as a listener does) | house 3, deep house 4, nu-disco 5, afro house 9, corporate 4/4 14 | club, drive — and what almost every generated promo already is |
| Backbeat | kick on 1 and 3 with pickups, snare on 2 and 4 | funk / boogie 5, lo-fi 8, kids pop 15, rock-ish 18, synthwave 7 | human, groovy, warm |
| Half-time | kick on 1, snare on 3, fast hats over a slow body | trap 2, future bass 6, phonk 1, hyperpop 22, cinematic 13 | big, modern, heavy — and it feels like half its BPM (141 → ~70) |
| Broken | syncopated kicks off the grid | breakbeat 19, UK garage 12, drum & bass 11, jersey club 20, baile funk 21 | fast, nervous, street, young |
| No kick | ticks, plucks, a heartbeat, swells | luxury ambient 17, cinematic pulse 13, minimal pulse 14 without its kick | calm, premium, precise |

**Four on the floor is the trap.** Asked for "dynamic, more energy" — and shown a showreel at 128 BPM — every model
reaches for it: house at 128, or its neighbours nu-disco at 116 and corporate 4/4 at 110, for a coffee shop, a
school and a garage alike — a set of promos made that way sounds like one song, and in this skill's own test runs
"not house at 128" alone only moved the videos to nu-disco at 116. Energy is a level, not a genre:
"dynamic" decides how early and how constantly the groove drives (`ENERGY` high from the first bars), while the brand
still picks the genre — four on the floor stays for a brand that lives in clubs or when the user asks for it. A
reference sets the energy and the pace of the cuts, never the genre or the tempo of your score.

**Energy comes from the person.** Their words decide it, in any language, by meaning: dynamic / drive / hype / hard /
powerful / rock-n-roll / "more energy" → high from the first bars (a full-time groove, or a half-time one driven by
busy hats and rolls); calm / soft / premium / cozy / tender → low–mid (no kick or a gentle groove, space, long tails);
"quiet, then a blast" → low → high where they said. Without such words the
references' music arc decides (`ref-sheet` prints "music by second"); without references, a promo, a launch, a reel
or an ad takes the default of this genre — the groove from the first bar, held — and calm needs a reason: a brand
that lives in calm, a background placement, a sensitive subject (`direction.md` §5). Write the choice down as
`ENERGY` before composing and pass it: `sound-print --suggest … --energy`. `sound-print --suggest … --energy`
orders the row below by it — every row has at least two cards at every energy, still spread across brands by name.

Then the genre from the brand — the first options of each row are outside four on the floor:

| Brand world / vibe | Genres to consider (BPM) |
|---|---|
| Cars, moto, tuning, gyms, streetwear, energy, gaming — aggressive | drift phonk (128–145), trap (140 half-time), drum & bass (174), rock-ish hybrid (130–150), baile funk; calm: night-drive ambient, lo-fi |
| Tech, SaaS, AI, fintech — clean, smart | minimal pulse, half-time or no kick (90–110), glitch-pop, UK garage (132), liquid drum & bass (174), rock-ish hybrid, breakbeat, ambient pulse; tech house (4/4) |
| Apps, delivery, marketplaces, e-commerce — friendly, fast | future bass (140–150 half-time), breakbeat (125–135), UK garage (132), jersey club (140), playful pop; calm: lo-fi, ambient pulse; house / nu-disco (4/4) |
| Food, cafés, bakeries, coffee — warm, cozy | lo-fi hip-hop (75–90, swing), funk / boogie with a backbeat (95–112), bossa / latin groove (clave, conga), amapiano; driving: rock-ish hybrid, dembow; nu-disco (4/4) |
| Beauty, fashion, flowers, jewellery — elegant | luxury ambient (60–95), minimal pulse, amapiano log drums (112–118, the kick drops beats), UK garage (132), fashion trap; driving: big-beat breaks, liquid drum & bass; deep house (4/4) |
| Kids, education, family, pets — playful | marimba / kalimba pop with a backbeat (100–125), chiptune (120–150), a bouncy breakbeat with toy sounds, sugary future bass; calm: soft lo-fi, music-box ambient |
| B2B, industry, logistics, real estate, finance — serious, confident | cinematic hybrid (braams, pulses; 80–100 or 120 half-time), minimal pulse, ambient pulse, synthwave; driving: breakbeat, rock-ish hybrid |
| Health, clinics, spa, wellness — calm, trust | ambient pulse (70–90), soft piano + glass pads, gentle plucks, soft lo-fi; steady: gentle backbeat pop, easy amapiano; fitness and sport: driving breakbeat, drum & bass |
| Events, bars, nightlife | house / techno (4/4, 122–130), UK garage (130–134), jersey club (140), baile funk, deep house; calm: lounge ambient, lo-fi lounge |
| Regional flavour | latin / dembow (90–100), baile funk, afro (100–118), brass funk, East Asian pentatonic plucks (koto = `pluck` 'ks'), ambient with a regional voice |
| Developer tools, open source, CLIs, APIs — precise, driving (`--world dev`) | breakbeat (125–135), UK garage (132), liquid drum & bass (174), synthwave (100–118), rock-ish hybrid for a big version, glitch-pop; calm: minimal pulse without its kick, ambient pulse; tech house (4/4) |
| Travel, sport, events, personal reels — kinetic, music-led (`--world lifestyle`) | breakbeat (120–135), baile funk, drift phonk (128–145), afro / amapiano, future bass, uplifting pop; calm: a lo-fi travel diary, ambient landscapes; nu-disco (4/4) |

Then let the **edit** decide the details: cuts on every beat and whip pans → 120+ BPM, busy hats, short sounds; long
holds, slow camera, luxury → 70–100 BPM or half-time, space, long reverbs. The hook scene sets the first impression —
the first 2 seconds of sound must already say "this brand".

**The key.** Left alone, models write in A minor (or C major) every time. Choose it: darker F, B♭ or C♯ minor; warm
E♭ or B♭ major (brass sits well there); bright D or E major; funky D or E dorian. Never the key of the last promo.

**The kit is half of the timbre.** The same `kick()` defaults in every video sound like the same video. Give each
one a character (all of these are options of the drum voices, synth-api.md §3):

| Character | Kick | Snare / clap | Hats | Drums bus |
|---|---|---|---|---|
| Clean, precise (tech, SaaS, fintech) | 'tight', `click` 0.6 | `snap`, or 'tight' with `bright` 3500 | `metal` 0.9, `tone` 1.2, short | dry |
| Warm, round (food, cafés, kids) | 'soft', `decay` 0.18 | `rim`, or 'lofi' | `metal` 0.2, `tone` 0.85 | `lp` 9000, room |
| Dusty (lo-fi, vintage, craft) | 'soft', `drive` 1.2 | 'lofi' | `metal` 0, swung | `crush: { bits: 10, rate: 2 }`, `lp` 7000 |
| Hard, loud (sport, auto, street) | 'hard', or '808' with `drive` 4 | 'fat', `snap` 1.6 | `metal` 0.8 | `drive` 3 |
| Big, cinematic (launches, B2B) | 'boom', `decay` 0.9 | 'gated', or `clap` in a hall | few or none | hall reverb |
| Bouncy club (nightlife) | 'punch', `len` 0.35 | `clap`, wide `spread` | open hats on off-beats, `decay` 0.1 | pump the rest |

Tune the kick to the key: `tune` = the root in octave 1 (`hz('F1')` ≈ 43.7 Hz); roots C to E♭ sit under 40 Hz there,
so use their fifth (key of D → `hz('A1')` = 55 Hz). A tuned kick and bass sound like one instrument.

## 4. When the user names a sound (or brings a track)

- **Mood words → parameters.** "aggressive / hard / street" → distorted 808, hard kick, phonk or trap, -12 LUFS;
  "expensive / premium" → sparse, deep, wide reverb, piano / glass, slow; "fun / light" → major key, bouncy bass,
  plucks, claps; "techy / futuristic" → glitch, arps, FM plucks, clean kick; "epic" → cinematic hybrid.
- **"Like the reference".** Run `scripts/ref-sheet.mjs` on the reference to get its tempo, loudness and how its cuts
  sit on the beat; describe its instrumentation in words from what you can see and infer; then write an ORIGINAL piece
  with that energy. Never copy a melody, a hook or a recognisable riff.
- **"Like <artist>".** Translate to traits (tempo, kit, bass, harmony, texture) and write something new in that
  world. Never imitate a specific song.
- **Their own licensed track.** Do not compose; run `ref-sheet.mjs` on it for BPM, the first beat and its drops
  (where the bass comes in — a beat tracker can put the bar a beat off, the bass level cannot), build
  `js/timeline.mjs` on that grid (set BPM, shift cues by the first-beat offset), land the biggest visual moment on
  the first drop (start the song at whatever offset that needs), trim scenes by whole beats and never stretch time,
  and still design the SFX with the synth, mixed under their track (`render.mjs --audio <mix.wav>` after you mix
  both, or mux theirs as is).
- **Recorded sounds they supply** (their product's own chime, a real crunch, a click they recorded): `node
  tools/kit.mjs <files>` converts them to 48 kHz WAV in `audio/kit/` and lists where each is loudest; `sample(t,
  'audio/kit/crunch.wav', { vel, pan })` places that loudest moment on the cue (a whoosh peaks 0.7 s in: started on
  its cue it lands late). The person answers for the licence (fill in `audio/kit/KIT.md`): their own recordings, or
  files they downloaded themselves under a licence that allows commercial use — never a library pulled by a script,
  and a "free" track can still draw a Content ID claim. The score stays composed: recordings are spice, not the bed.

## 5. The energy map

The track follows the story, scene by scene (bars = 240 / BPM seconds each; plan scenes in whole bars), at the
energy `ENERGY` gives each scene. A promo's default is the drive shape: the groove in from the first bar (a pickup of
a bar at most), no scene thinned below it, contrast made by adding — a new layer, a fill, a filter opening, a hole
before the biggest hit, a second drop with what the first one didn't have. The parts below also describe the
contrast shape (a low or mid opening that builds to the drops): a plan for a calm brand, or for words that ask for it.

| Part | Where | What happens |
|---|---|---|
| Intro / hook | a pickup of up to 1 bar in the drive shape; 2–8 bars only in a contrast or calm plan | no or filtered drums (`automate(bus, 'lp', …)` opening), hits on the words, a pad or a riff hinting the hook — in a high plan the beat is already under the words |
| Build | into the first reveal | riser, snare/hat roll (`roll()`), filter opening, a reverse cymbal ending on the reveal |
| Hole | ⅛–½ beat before the biggest hits | `gap()` — silence makes the next hit twice as big |
| Drop 1 | the brand reveal / core promise | full groove, impact + crash, the bass enters |
| Verse | information-dense scenes | at a mid plan thinner: fewer layers, lower hats, so text reads; at a high plan the drums and bass stay — clear room by lowering pads and leads instead |
| Break | before the payoff | pad + motif, no kick; a tape stop or stutter into it for a jolt |
| Drop 2 | the payoff (proof, offer) | the fullest section — add a layer the first drop didn't have |
| Outro | the lockup / CTA | the sonic logo, a last hit, then a tail ≥ 1.5 s (reverb, last chord); nothing new after it |

Keep something changing every 2–4 bars (a layer in or out, a fill, a new bass rhythm, a filter move) — a one-bar
loop repeated for 8 bars sounds like a template. Start the drums where `ENERGY` says: on the first reveal in a
contrast plan, within the first 2 bars in a high one.

## 6. The hook and the sonic logo

- A motif of 2–4 notes in the key, one bar or shorter, rhythmically simple — hummable.
- It plays on the logo reveal, every time the brand appears, and once earlier as a hint (first product shot).
- Its timbre fits the brand: bells / glass (clean tech), brass (bold), vox (human, warm), harp / pluck (organic,
  flowers, kids), cowbell (phonk), chip (games), piano (premium, emotional).
- Tune UI pops, dings and blips to the scale (`scale('F', 'minor').deg(i, 5)`), so sound effects sound like music.

## 7. Brand-world sounds

One to four sounds that only this brand's video would have — the ingredient that stops every promo sounding alike.
Build them from `noiseHit` (shaped noise), `toneSweep` (glides, motors), `bell` (metal, glass), `tick`, or a new voice
(synth-api.md, "Writing a new voice"). Drive them from the same schedule as the picture (an rpm curve that moves the
needle AND the engine; a typing schedule that prints letters AND clicks keys).

| World | Sound ideas |
|---|---|
| Auto parts, cars | engine (saw `toneSweep` + noise following an rpm curve), starter, turbo blow-off (noise sweep down), grinder sparks, tyre screech, gear shift clunk |
| Coffee, cafés | burr grinder (band-passed noise with random amplitude), steam wand (high-passed noise, slow attack), cup clink (bell ratio 2.76, short), pour (low-passed noise sweeping) |
| Bakery, food | crunchy crust (dense ticks), oven ding, dough thud, sizzle (high-passed noise crackle) |
| Flowers, gifts | paper wrap (`paper`), stem snip (bright tick + short noise), airy chimes, a bloom swell |
| Delivery, logistics | scooter (square `toneSweep` + LFO), door knock (`thud` ×2), box landing, notification `ding` |
| Fintech, shops | `coin`, card tap (`click` + `blip`), `success` arpeggio, till drawer (noise burst + bell) |
| AI, bots, SaaS | data blips in the scale, `glitch`, `key` typing, message `pop`, generated-content whoosh |
| Fitness, health | `heartbeat`, breath (shaped noise), barbell clank (bell ratio 1.41 + `thud`) |
| Real estate | door, keys jingle (dense high bells), footsteps (soft thuds), city air (low-passed pink noise) |
| Kids, games | `boing`, `goo`, `pop`, whistle (sine `toneSweep`), xylophone runs, `blip` confirmations |
| Beauty, fashion | spray (high-passed noise, 50 ms attack), cap click, `sparkle`, silk swish (soft `whoosh`) |

## 8. The SFX map

List every visible event of the storyboard and decide its sound (or a deliberate silence):

| On screen | Sound | Timing |
|---|---|---|
| Text / logo slam | `impact` (sub in the key), `crash` for the big ones | exactly on the landing frame |
| Whip pan, fast move | `whoosh` — dur = the move, pan follows its direction; 'in' when it lands on something | starts with the move |
| Items appearing (cards, icons, pills) | `pop` tuned to the scale, one per item, pan by screen x | on each appearance |
| Number rolling | `tick`s at the times the digits change (same easing as the picture), pitch rising | computed from the easing |
| Typing | `key` per character, from the same schedule as the text | per character |
| Tap, click, toggle | `click`, `blip`; success → `success` / `ding`; error → `errorBuzz` | on the press |
| Glitch, decode | `glitch` or rapid ticks | over the effect |
| Shine, sweep of light | `swish` high or `sparkle` | with the sweep |
| Big reveal | `riser` before + `reverseCymbal` ending on it + `gap` + `impact` + `boom` + `crash` | the reveal frame |
| Camera shake | short `boom` / soft kick | on the shake |
| Paper, photos, cards flying | `paper` | per item, thinned out |
| Split-flap, counters of many digits | one `tick` per flap, capped to one per 10 ms bucket | per flap |
| End card | final hit + ring-out ≥ 1.5 s, nothing new after | the last hit |

SFX live 3–6 dB under the music except the hero hits in a music-led film; in a ui-led one every visible interface
event gets its sound, tuned to the scale, 0–3 dB under the music, and the groove leaves them room (fewer hats,
no busy lead). Never two whooshes on the same moment; the smaller the UI element, the quieter and shorter its
sound. A sound repeated many times (footsteps, ticks, pops) varies a little each time — a semitone up or down on a
synth voice, `rate: 0.92–1.08` on a sample — or it sounds pasted.

## 9. Mixing

- **Bus gains (dB) to start from**: drums -2, bass -4…-6, music -5…-8, lead -6…-8, fx -4…-6. Adjust with the report.
- **Sidechain** (`duck` on a bus, keyed by kicks): bass 0.5–0.6, music 0.35–0.45, lead 0.2; EDM / future bass pump
  0.6–0.75; lo-fi and ambient 0.15–0.3 or none. Add a second key for hero hits: `trigger('hit', t)` +
  `duck: [{ from: 'kick', depth: 0.5 }, { from: 'hit', depth: 0.4, release: 0.3 }]`.
- **Low end has one owner at a time**: a kick and an 808 note on the same hit fight — let the 808 carry it, or duck the
  bass under the kick. `render({ monoBass: 120 })` keeps everything under 120 Hz mono.
- **Mud**: pads and keys high-passed at 150–250 Hz (`supersaw` does 180 by default); thin chords to 3–4 notes.
- **Space**: reverb 'plate' (pop, EDM), 'hall' (cinematic), 'room' (lo-fi, funk), 'dark' (moody), 'huge' (ambient);
  delay 0.75 beat (dotted eighth) on leads and plucks; reverb lives on the sends, not on the kick or the bass.
- **Colour**: `drive` on drums / bass for grit (phonk, trap, rock); `crush` for lo-fi and chip; `chorus` on keys and
  pads for width; `eq` bands on a bus to carve (e.g. music `eq: [{ f: 300, g: -3 }]` when the kick is boomy).

## 10. Loudness

`render(file, { lufs, truePeak })` normalises to the target (ITU BS.1770) with a true-peak-safe limiter.
- -14 LUFS: default (YouTube, Instagram, TikTok normalise around there).
- -12 … -11 LUFS: club genres (phonk, trap, EDM) posted where nothing normalises (Telegram, VK, X).
- -16 … -15 LUFS: ambient, luxury, lo-fi — let them breathe.
- True peak ≤ -1 dBTP always (AAC adds a little). If the render says the limiter pulls more than 6 dB, a bus is too
  peaky (usually fx hits or drums) — lower it rather than squashing the mix.

## 11. Checking

1. `node audio/score.mjs --report` — per-bus RMS for every scene window. In drops the drums bus is the loudest; music
   sits 4–10 dB under; the levels follow `ENERGY` — a low scene sits 3+ LU under the drops, a high scene within about
   2 LU of the loudest one (`audio-check` checks this against the plan and FAILs a high scene 2.5+ LU down).
2. `node tools/audio-check.mjs` — must show no FAIL. Read the band balance: typical for bass-driven genres sub -8…-4,
   bass -7…-3, low-mid -16…-10, mid -20…-14, presence -26…-18, air -30…-18 dB; ambient and lo-fi sit lower in sub
   and air. It warns about mud, dullness, harshness, a flat energy arc, an abrupt ending.
3. Open `out/qa/music-audio.png`. Cyan lines = scene starts, yellow = cues, faint white = bars. Check:
   - every hit's bright vertical stripe sits ON its yellow line (not before, not after);
   - drops are denser and brighter than intros; the hole before the logo is a dark column;
   - risers are rising diagonals that end on the cue; the tail fades to black before the end;
   - no constant bright band in the low-mids (mud) or across the top (hiss).
4. Zoom into a transition: `node tools/audio-check.mjs --zoom 7-9`.
Fix, re-render the score (seconds), re-check. Only then render the video.

## 12. Never the same twice

The trap: one synth, one habit, and every video ends up house at 120–128 BPM with the same kick on every beat, the
same off-beat hats and the same pads. A listener hears one song again, even with new chords each time.
What a listener recognises first is the **groove** (where kick, snare and hats fall) and the **timbre** (the kit and
the instruments); then tempo and key; the chords last.

`node tools/audio-check.mjs` measures it: the `unique` line and the "nearest scores" list compare this track's
fingerprint (`tools/sound-print.mjs`: tempo, key, a 16-step kick/snare/hat pattern, a 24-band spectrum, the chroma)
with the template demo, with every promo project in the same parent folder (their `out/qa/*-print.json` or
`out/music*.wav`) and with anything you pass: `--against ../old-promo other.wav`. 1.00 is the same track; ≥ 0.75
too close (WARN); the demo itself FAILs at ≥ 0.85. The list says what matches ("same tempo 128≈128, groove r 0.93,
timbre Δ 1.8 dB"). Change what it names — not the seed, not the chords alone:

| It says | Change |
|---|---|
| groove | another genre card: half-time trap, broken beat, DnB, 6/8, amapiano log drums, lo-fi swing, no kick at all |
| timbre | other voices: a different kick type, `ks` / harp / marimba instead of pads, brass or vox lead, a band (keys + bass + kit) instead of synths |
| tempo | 20 % or more away (a 120 → 96 or 150), or half-time over the same BPM |
| key / chord colours | another root and mode (Dorian, Lydian, pentatonic), a different progression shape |

The score is groove 35 %, timbre 35 %, tempo 30 % — the per-trait numbers after each match show which one to move.
A new lead or hook voice, new chords or a new key hardly move it, on purpose: over the same kit, groove and tempo
they are the same track to a listener. Nudging a pattern until the number slips just under 0.75 is not the goal
either — a different brief should land well below 0.65.

Also compare by the brief: same genre? same kick type? same lead voice? same hook shape? If three or more match an
earlier video, it is not new yet. Every score needs at least one brand-world sound (section 7) — the part no other
brand's video can have. A series for one brand may keep its sonic logo on purpose; everything around it still moves.

# Story and motion: what makes a promo sell and look like a showreel

## Contents
1. From brief to concept
2. Length and beat sheets
3. The selling arc, scene by scene
4. Motion craft
5. Transitions
6. Type in motion
7. Colour, light, depth
8. Showreel vocabulary (what the trend references do)
9. Anti-generic list
10. Frame quality checklist

## 1. From brief to concept

1. **One promise.** Compress the business into one sentence a viewer repeats: "a bike fixed the same day",
   "every invoice paid on time". Every scene serves it.
2. **Proof points.** 3–5 facts that make the promise believable: numbers, how it works, real photos, real
   cases, guarantees. Only facts from the brief, the site or the user (brief.md lists the source of each).
3. **The action.** What the viewer does next and where (a bot, a site, a phone). If sales happen in a Telegram bot,
   the CTA and the end card drive to the bot — not to the site.
4. **The brand's visual DNA.** Find the brand's own shape and motion and reuse it everywhere: an angle in the logo
   becomes the wipe (a slanted stroke in the logo sets the angle of every wipe); the product's world gives the metaphor
   (a car → ignition, tachometer, sparks; flowers → a bloom; a bot → a chat; a marketplace → a cart filling up).
5. **One signature moment.** The shot people remember: a logo that lights up like headlights, a wall of real
   orders bursting out of a parcel, a split-flap board spelling the offer. Plan it first; build toward it.

## 2. Length and beat sheets

The person's number wins: a "15-second" ask gets 15 seconds — keep the strongest facts, say what was left out and
offer a longer version. Without a number, choose the length from the content with the table below. One bar = 240 /
BPM seconds (at 120 BPM: 2 s; at 128: 1.875 s).

| Length | Bars at 120–130 BPM | Shape |
|---|---|---|
| 15 s | 8 | hook (1) · reveal (1) · 2 proof beats (3) · lockup + CTA (3) |
| 30 s | 16 | hook (2) · reveal (2) · proof ×3 (6) · offer (2) · lockup (4) |
| 45 s | 24 | hook (2–4) · reveal (2) · how it works (6) · proof / cases (6) · offer (2) · lockup (4) |
| 60 s | 32 | as 45 s + a second act (a breakdown and a second drop) — only if there is enough to say |

Write the direction in the README — a table (beats | shot | enters → leaves | sound) plus the palette roles, the type,
the banned list and the sound cue list — then encode it in `js/timeline.mjs`: scene
windows `S` (neighbours overlap by up to a beat — that is where transitions live), named `CUE`s (every slam, reveal,
card, drop), `WHIPS` (fast moves → 16 blur samples), `COVERS` (thumbnail times), `DURATION` (last hit + 1.5–2.5 s — under a fixed length, place the last hit that far before the end, so the
tail fits).

**A worked direction** — for a made-up brand, Loafly (loafly.example, a bakery-delivery app), 30 s at 132 BPM. It
shows the level of detail to reach before building, not a style or a genre to reuse: yours come from your brand, its
references and `sound-print --suggest`.

| Beats | Shot | Enters → leaves | Sound |
|---|---|---|---|
| 0–4 | "Warm bread at 7:00." — one word per beat, black 900 on a crust-coloured gradient | each word drops in with a 3-frame overshoot → the last one smears sideways into the next shot | shaker from frame 1, a crust crackle per word |
| 4–12 | the logo's loaf rises like dough (scale Y 0.2 → 1 with a soft wobble), the wordmark types in | rises from the bottom edge on the drop → the loaf's outline becomes the frame of the first app card (match cut) | the drop: the full 2-step groove; the 3-note sonic logo |
| 12–32 | the real app screens (`brand/sections/`) tilted in 3D; each tap ripples | a whip in from the right on beat 1 of each bar → an accelerating exit left | a tick per tap from the same schedule; an oven door on the third card |
| 32–48 | "38 bakeries" rolls up (a number from the site) as pins pop onto a city map | pins pop on the off-beats → a zoom into one pin with a blur ramp | pin pops on the hats' off-beats; a bell as the count lands |
| 48–60 | lockup: logo, "Order in the app", loafly.example — held 3 s | cut 2 frames before the last downbeat → holds with a slow push | a beat of silence, the sonic logo, a reverb tail |

Palette as roles: page #FFF8EE, surface #F2E3CC, ink #2B1A10, accent #E4572E — the accent marks only the key word
of each line. Type: the site's display face at 900 for statements (120–160 px), its text face at 500 for UI labels
(≥ 28 px). Hard cuts on beats 4, 32 and 48; everything else is a match cut or a whip. Banned here: cross-fades, a logo
on black first, a scene counter, stock bread photos, HUD corners, emoji, a kick on every beat. Energy: the brief asked
for energy, so `ENERGY = { hook: 'mid', reveal: 'high', app: 'high', proof: 'high', lockup: 'high' }` — the groove is
under the words from bar 1. Sound brief (`--suggest … --energy high` offered rock-ish first; the references' shuffle
decided): UK garage 2-step, 132 BPM, D♭ major, shuffled hats, organ stabs, a subby kick; brand-world sounds — crust
crackle, oven door, paper bag; −14 LUFS.

**The pace in numbers.** The motion references this skill was measured on move in 67–100 % of their frames, land
45–91 visual hits a minute (`wow-library.md` §1), and put most of them on the beat (or at one constant offset — cuts a frame or two early on
purpose). Measure your draft the same way: `ref-sheet.mjs out/<slug>-draft.mp4 --bpm <BPM>`. A calm film may sit
lower on hits; a still frame outside the end card is a bug in any film.

## 3. The selling arc, scene by scene

- **Hook (0–3 s)**: the promise or the pain in 3–6 words, with motion from frame 1 — never a logo on black first.
- **Reveal**: the brand arrives with the drop; the logo does something only it can do.
- **How it works**: 2–4 steps shown, not told — UI in motion, the product in use, a map, a timer.
- **Proof**: numbers that roll, real photos (the client's), cases, guarantees. Faces and names only if the client
  gave them for this purpose.
- **Offer**: what is special now (only if real: a price from the site, a free consultation, a delivery promise).
- **Lockup + CTA**: logo, one-line CTA, contacts large and readable, held ≥ 2.5 s; the sonic logo plays.

## 4. Motion craft

- **Easing vocabulary.** Entrances: `outExpo` / `outCubic` (fast, settles). Exits: `inExpo` (accelerates away).
  Wipes: `inOutSine` over ≥ 0.3 s (a faster wipe reads as a flash cut). UI and bouncy things: `outBack`,
  `spring()`. Linear only for continuous motion (drift, parallax, rotation).
- **Anticipation and overshoot.** A slam scales from ~1.7 to 1 with a small overshoot (`slam()`); a whip starts slow
  and ends fast; nothing starts and stops at full speed.
- **Stagger.** Groups enter one by one, 1/8–1/4 beat apart, in reading order; never all at once.
- **The beat is the clock.** Hard cuts, slams and reveals land ON beats (CUEs are beats). Secondary motion can sit on
  8ths and 16ths. A hard cut may lead its beat by a frame or two: light arrives before sound, and editors cut early
  so the cut feels like the hit.
- **Cut on motion.** Every shot enters already moving (a fast ease-out that is still travelling on its first frame)
  and leaves on an accelerating move, a whip or a blur ramp. Two still frames on either side of a cut read as a
  slideshow; one planned hold per video is plenty.
- **The camera is alive.** A slow push (2–6 %) through every hold, a shake on hits (`shake`, 10–25 px, 0.3–0.5 s),
  parallax between layers. A frozen frame reads as a slide.
- **Motion blur sells speed.** Every fast move gets 16 samples (`WHIPS`) and speed lines; don't fake blur with CSS
  filters. Blur is a smear of real travel, not polish — leave it out where it hurts: a move shorter than the
  element's own width, a fade or a colour change (nothing travels), text that must be read at that instant, a slow
  drift of under half a pixel a frame, a whole scene at once. Text and numbers that change are computed from the
  frame's own time (`f / FPS`, `scene-cookbook.md` §1), so a blurred frame never mixes two values.
- **Springs give weight.** A move that settles like a real object — accelerates, overshoots a hair, stops — reads as
  expensive; the same move on a fixed curve reads as cheap. `SPRING` in `js/engine.js` has four feels: snap (buttons,
  toggles, the leading edge of an indicator), base (cards, containers, the camera), heavy (big type, the logo: no
  overshoot), play (stickers, mascots). A value that changes target several times (a cursor, a container) is a sum of
  springs — `track(t, keys, SPRING.base)` — so a new target mid-move never jerks. Type never bounces.
- **Depth.** 3–4 layers (background glow, midground, hero, foreground particles), each moving at its own speed; light
  blobs and vignette for focus.
- **Flashes and shakes are spice.** A 0.1-s white flash at 10–40 % on the biggest hits only.
- **Holds.** Text that must be read holds ≥ 0.6 s per 3 words after it lands; the end card ≥ 2.5 s.
- **One read at a time.** List what the viewer must understand, in order; give each read its window (to find it,
  understand it, register it) and never start the next read inside it. Motion around a read may continue; a second
  message may not.
- **Cut on downbeats, not on every beat.** A cut on every beat reads as a music video; hits on every beat, cuts on
  the downbeats (or every second beat) read as a film. Something new still happens every 2–4 seconds.

## 5. Transitions

| Transition | How (scene-cookbook.md) | Use for |
|---|---|---|
| Whip pan | `whip()` out + in, 0.3–0.45 s, speed lines, 16 blur samples, a whoosh | energy, next topic |

A whip lasts from its exit cue to the next scene's landing cue (`whip(t, CUE.exit, CUE.land - CUE.exit, …)`, as in
the demo's hook). Measured to any nearer marker it finishes early and the scene sits off-screen for the rest of its
window — in a still that looks like a broken scene, not a fast transition.
| Brand-shaped wipe | `slashClip()` at the logo's angle, `inOutSine` ≥ 0.3 s | the brand's signature |
| Zoom-through | scale into a letter's counter / a dot / a screen until it fills the frame | reveal the next world |
| Match cut | same shape or position in both scenes, hard cut on the beat | elegance |
| Split-flap / scramble | characters flip / decode into the next words | information, prices, names |
| Card stack | the next scene is a card that slides over, with shadow | UI, steps |
| Light streak | a streak crosses the frame, the scene changes under it | premium, tech |
| Mask reveal | text or logo as a window into the next scene | bold statements |
| Glitch cut | 2–4 frames of offset slices + `glitch` sound | tech, AI |
| Hole | everything freezes and goes silent ½ beat, then the hit | before the biggest reveal |

## 6. Type in motion

- One display face (heavy, italic caps read as speed) + one supporting face (mono for data, a sans for small text).
- Sizes at 1080p: statements 150–260 px, card numbers 120–160 px, labels 28–36 px, never below 26 px (phones).
- Hierarchy is a ratio, not a range: the hero text of a scene is at least 1.8× the next text on screen and 2.5× the
  smallest. A 150 px statement beside 140 px numbers has no hero.
- One accent word per statement: in the accent colour, or set in a contrasting face (a serif italic among heavy
  sans) — the trend launch films use both, never more than one word per line.
- 1–4 words per slam; a line per beat. Split long sentences into beats.
- Numbers roll (`roll()`), never jump; units in a contrasting style.
- Measure text after fonts load (they are, in main.js) and `fitFont()` anything that could overflow — especially in
  other languages.

## 7. Colour, light, depth

- **Light or dark comes from the brand**, not from the template: look at the brand's own surfaces (site background,
  the logo's ground, packaging, the bot's avatar). A white site, kids, food, flowers, health, most retail → a light
  video; cars, gaming, nightlife, developer tools → dark. `css/style.css` has a light preset — swap it in first. Left
  alone, every video comes out dark with one neon accent (the template's look): three different briefs, one look.
- 4–6 colours from the brand (`scripts/palette.mjs` on the logo / screenshots), one accent that owns the hits.
- **Scale**: the hero owns the frame — a key word at 15–30 % of the frame height, a UI card or a product at 50–80 %
  of the width, cropped by the frame edge when it moves (that is energy, not a mistake). A small card floating in
  the middle of an empty frame reads as a slide.
- **Layers**: a background that lives (a slow brand shape or pattern, large blurred colour fields, a grid, paper,
  grain), a midground hero, a foreground accent (particles, a line that draws, a sticker) — each at its own speed.
- **No photos? Draw the world.** SVG and canvas can draw the product's objects at hero size: beans, a cup and
  steam; pencils, paper and scribbles; a server rack and a pulse line. One drawn signature element per brand (the
  pencil line that draws every transition) makes the video this brand's.
- **Detail by depth.** Every drawn surface gets three things — a base (a gradient, not a flat fill), a texture of its
  material (grain, fibres, a pattern) and one edge (a highlight, a line, a shadow). The hero gets full detail; far
  layers get only grain at 40–60 %. Draw back to front in a fixed order: ground, far, mid, props, hero, effects.
- Dark grounds make light effects glow; light grounds need shadows and depth to avoid a flat slide. On white, a white
  element needs a 1-px edge and a faint shadow, or it vanishes.
- Frosted glass that reads on any ground: a blurred, lightened copy of what is behind, clipped to the shape (letters
  included — giant glass titles over a photo).
- Glow = the accent at 30–60 % in `text-shadow` / `box-shadow`; bloom-like light blobs behind heroes.
- Real client photos keep their colours; unify with a grade (a shared overlay tint at 5–15 %) rather than filters.

## 8. Showreel vocabulary

What trending motion reels (product launches, "made with code" reels) do — recreate techniques, never footage:
- **Product UI in motion**: toolbars, cursors that click, panels that slide, typing, a 3D tilt of the screen.
- **Glass**: frosted cards (`backdrop-filter: blur()`, a light border, a specular gradient), refraction via an SVG
  displacement filter on still layers.
- **Grids**: 2×2 or 3×3 panels moving in sync, each a mini scene.
- **Kinetic type**: one word per beat, huge, slamming, with shakes; decoding text; split-flap boards.
- **Counters and maps**: odometers and rolling prices of real facts, routes drawing across a map with stops
  lighting up — a number on screen is always a fact about the brand, never an index of the video.
- **Photo walls**: real photos flying into a 3D wall (CSS perspective), cards fanning out.
- **Particles**: sparks from a grinder, confetti, dust, light streaks — canvas, deterministic.
- **Logo moments**: traced logo letters slam one by one, a cut sweeps through with sparks, headlights ignite,
  a shockwave ring.

## 9. Anti-generic list

These make a promo look cheap or AI-made — avoid unless the brand really calls for them:
- centred text fading in and out on a gradient (a slideshow); a logo alone on black as the first frame;
- the template's look for every brand: a dark ground, one neon accent, small cards floating in empty space;
- everything easing the same way, everything moving at once, linear motion;
- stock-looking icons, emoji, rainbow gradients, neon on everything, lens-flare spam;
- default system fonts, more than two typefaces, text under 26 px;
- **a scene counter or chapter label** — "01 / 06", "02/06", "SCENE 03", "CH. 2", "step 1 of 4" in a corner, a row of
  progress dots. Every model adds one to look "designed", and viewers read it as a template: it numbers the edit
  instead of selling the brand. No exceptions — the video never numbers its own scenes. `main.js` warns about one in
  the capture log and `qa.mjs` fails it;
- HUD overlays (timecodes, frame counters, BPM readouts, corner brackets, "REC", coordinates) — unless the brand's
  world is literally a HUD;
- invented numbers, fake reviews, fake client logos; an illustrative number carries a visible "Example" label;
- the defaults every model reaches for when given nothing (`direction.md` §9): a dark screen with a green glow, a
  cream canvas with numbered labels, centred text fading in on a gradient, an invented logo, screens that do not
  exist, beeps that sound like a microwave;
- a generic "corporate" music bed; the same track as the last video.

## 10. Frame quality checklist

Before the final render, from `node tools/capture.mjs review` (a frame per beat, the phone view, strips through every
fast move) and stills at every CUE (± 0.1 s around each transition) — score them as in SKILL.md step 7:
- the look is the brand's (a light brand is a light video); in most frames the hero fills the frame;
- nothing cut off at the edges; text readable at phone size; no text on busy photos without a scrim;
- no empty (all-background) frames except intended holds; no scene covering the one before too early;
- the accent colour marks the key word of every statement;
- every transition has motion in both scenes (no dead frames in the overlap);
- the end card is balanced, the CTA and contacts are the largest things after the logo.

# Synth API

`audio/synth/` in every project — zero dependencies, deterministic (seeded), 48 kHz stereo, offline. Import all of it:
`import * as A from './synth/index.mjs'`. Times are seconds (use `b(n)` from `js/timeline.mjs` for beats); notes are
MIDI numbers or names ('C3', 'F#4', 'Bb2'); chords are arrays of notes. `node audio/synth/selftest.mjs` renders every
voice and checks it; `--wav out/tour.wav` writes all of them one after another.

## Contents
1. Song, buses, time
2. Theory and sequencing
3. Drums
4. Bass
5. Pads, stabs, keys, plucks, bells
6. Leads, chip, brass, voices, arps
7. Sound effects and builders
8. Arrangement moves and automation
9. Render (mix and master)
10. Writing a new voice

Common options on every voice, including rows below that list none: `vel` (loudness, 1 = calibrated default), `pan`
(-1 … 1), `bus` (target bus name), `verb` / `delay` (per-hit sends, 0 … 1). Times are seconds, frequencies Hz (notes as
'C4' where a row says so); a wrong type makes NaN, and `render()` then stops with the bus and the time it appeared.

## 1. Song, buses, time

| Call | What |
|---|---|
| `init({ duration, bpm, seed })` | start a song; duration = the video length (seconds) |
| `bus(name, opts)` | configure a bus: `gain` (dB), `pan`, `width` (0 mono … 2), `hp` / `lp` (Hz), `lpq`, `eq: [{ f, g, q, type: 'peak'|'low'|'high' }]`, `drive` (1 … 6), `crush: { bits, rate }`, `chorus: { rate, depth, mix }`, `comp: { threshold, ratio, attack, release, makeup }`, `duck` (0 … 1 against kicks, or `[{ from, depth, attack, release }]`), `verb`, `delay` (send levels), `mute` |
| default buses | `drums` -2 dB · `bass` -4 dB duck 0.5 · `music` -4 dB duck 0.35 · `lead` -5 dB duck 0.25 · `fx` -4 dB · `verb`, `delay` = the returns' gain |
| `beats(n)`, `bars(n)` | durations in seconds at the song's bpm |
| `note('C#3')`, `hz(n)`, `mtof(m)` | note name → MIDI → Hz |
| `rand()`, `between(a, b)` | seeded randomness (never Math.random) |
| `trigger(key, t, amount)` | a sidechain trigger (kicks register `'kick'` themselves) |

## 2. Theory and sequencing

| Call | What |
|---|---|
| `scale(root, mode)` → `{ deg(i, oct), notes(oct) }` | modes: major, minor, dorian, phrygian, lydian, mixolydian, harmonicMinor, melodicMinor, phrygianDominant, pentatonic, minorPentatonic, blues, wholeTone, hirajoshi, inSen |
| `chord('Am7', oct)` | chord symbol → notes (`.root` = bass note an octave below). Qualities: '' m dim aug 5 sus2 sus4 6 m6 7 maj7 m7 mM7 dim7 m7b5 7sus4 add9 madd9 9 maj9 m9 11 m11 13 6/9, slash chords 'C/E' |
| `prog('i VI III VII', 'A', 'minor', { oct, sevenths })` | roman numerals → chords (upper case major, lower minor, ° diminished, trailing 7) |
| `voiceLead([chord, chord, …], center)` → the list re-voiced | move chord notes by octaves for smooth pads and keys; one chord: `voiceLead([c])[0]` |
| `harmony([[beat, 'Fm9'], [beat, 'Dbmaj7'], …], { oct })` → `{ at(beat), spans(b0, b1) }` | ONE progression table that bass, stabs, pads and arps all read |
| `steps('X...x...', { from, to, step, swing, humanize })` → `[{ t, vel, i, bar }]` | drum-grid pattern, loops from `from` to `to`; X 1.0, x 0.8, o 0.45 |
| `seq('C4 . Eb4 _ G4~ Bb4!', { from, step, loops })` → `[{ t, dur, note, vel, slide, accent }]` | note string: '.' rest, '_' hold, '~' slide into, '!' accent |

## 3. Drums (bus 'drums')

| Voice | Character options |
|---|---|
| `kick(t, { type, tune, sweep, decay, click, drive, len, duck })` | type 'punch' · 'deep' · 'hard' · '808' · 'soft' · 'boom' · 'tight'; `tune` in Hz or a note ('A1'); registers a 'kick' trigger unless `duck: false` |
| `snare(t, { type, tone, snap, decay, bright })` | 'tight' · 'fat' · 'trap' · 'lofi' · 'gated'; `tone` in Hz or a note |
| `clap(t, { spread, decay, tone })` | four bursts + tail |
| `rim(t, { tune })`, `snap(t)` | side-stick, finger snap |
| `hat(t, { open, decay, tone, metal })` | metal 0.8 = TR-808 six-oscillator metal, 0 = soft noise (lo-fi, chip); tone is a multiplier, 0.8 dark … 1.3 bright (not Hz) |
| `ride(t)`, `crash(t, { dur })`, `shaker(t, { tone })` | |
| `tom(t, note, { decay, slap })`, `conga(t, note)`, `clave(t, note, { decay })` | pitched percussion |
| `cowbell(t, note, { dur, cut, duty })` | TR-808 cowbell, pitched — the phonk riff voice (bus 'lead') |
| `roll(t0, t1, (t, vel, i) => …, { from, to, vel0, vel1, curve })` | accelerating fills: step from `from` to `to` beats |

## 4. Bass (bus 'bass')

| Voice | Use |
|---|---|
| `bass808(t, dur, note, { from, glide, drive, decay, punch, cut })` | trap / phonk 808, glide from `from` |
| `bassLine([{ t, dur, note, slide, vel, decay }], { drive, cut, glide })` | a whole line as one voice, in ONE call: build the list, then call `bassLine(list)` once — building it plays nothing; slides glide from the pitch actually sounding |
| `sub(t, dur, note, { attack, release, drive })` | clean sub |
| `reese(t, dur, note, { detune, cut, env, move, wobble, subLevel, drive })` | dnb, dark techy |
| `acid(t, dur, note, { from, cut, env, reso, decay, accent, wave, drive })` | 303-style, tech house |
| `houseBass(t, dur, note, { bright, decay })` | plucky house / disco bass with a sub |
| `fmBass(t, dur, note, { ratio, index, sustain, wobble, drive, cut })` | growl, future bass |
| `chipBass(t, dur, note)` | NES triangle |

## 5. Pads, stabs, keys, plucks, bells (bus 'music')

| Voice | Use |
|---|---|
| `supersaw(t, dur, notes, { voices, detune, width, cut | cutFn(tAbs) | cutHi+cutLo+fdec, hp, attack, release, q })` | EDM chords, pads |
| `stab(t, notes, { dur, … })` | short chord hit |
| `pad(t, dur, notes, { type, attack, release, cut, move })` | 'warm' · 'dark' · 'air' · 'strings' · 'glass' |
| `keys(t, dur, notes, { type, bright, release })` | 'ep' (Rhodes-like) · 'organ' · 'piano' · 'clav' (short and plucky: a long `dur` does not sustain it — for held chords use 'ep' or 'organ') |
| `pluck(t, note, { type, dur, bright, cutHi, cutLo, fdec, ratio })` | 'synth' · 'harp' · 'ks' (string) · 'marimba' · 'kalimba' · 'fm' |
| `bell(t, note, { ratio, index, idec, dur })` | ratio 3.5 bell · 3.01 glass · 2 chime · 4 wood · 1.41 metal |

## 6. Leads, chip, brass, voices, arps

| Voice | Use |
|---|---|
| `lead(t, dur, note, { wave, pw, unison, detune, cut, env, fdec, reso, vib, vibRate, vibDelay, from, glide, drive, attack, release })` | bus 'lead'; wave 'saw' · 'square' · 'pulse' · 'sine' · 'tri' |
| `chip(t, dur, note, { duty, slide, vib, arp: [0, 4, 7], rate, decay, cut, echo })` | NES-like pulse; `arp` = the chip chord |
| `brass(t, dur, notes, { swell, cut })` | stabs and swells |
| `vox(t, dur, note, { vowel, toVowel, attack, release, vib })` | formant voice: choir pads, 'ooh / aah' |
| `chop(t, note, { dur, vowel })` | vocal chop hook |
| `arp(t0, t1, notes, { rate, pattern, octaves, gate, voice(t, note, dur, vel, i) })` | 'up' · 'down' · 'updown' · 'random' |

## 7. Sound effects and builders (bus 'fx')

| Call | Use |
|---|---|
| `whoosh(t, dur, { f0, f1, q, pan: [from, to], shape })` | shape 'swell' (passes) · 'in' (lands) · 'out' (leaves); the only voices with a moving `pan: [from, to]` are `whoosh` and `swish` — every other voice takes one number |
| `swish(t, { dur, pan })` | short bright move |
| `riser(t0, t1, { type, f0, f1, curve })` | 'both' (noise + tone) · 'noise' · 'tone' · 'shepard' |
| `downlifter(t, dur)`, `reverseCymbal(tEnd, dur)` | reverse cymbal ENDS at tEnd |
| `impact(t, { sub, air, crack, decay })`, `boom(t, { from, to, dur })`, `braam(t, dur, { note })` | hits |
| `tick(t, { bright, dur, q })`, `click(t)`, `key(t)` | UI, counters, typing |
| `pop(t, note)`, `blip(t, note, { dur, duty })`, `ding(t, note, { n2 })` (n2: the second note, default a fifth up), `success(t, root)`, `sparkle(t, { count, spacing })` | tuned UI |
| `coin(t)`, `shutter(t)`, `buzz(t, { dur })`, `paper(t, { dur })`, `thud(t, { f0 })` | foley |
| `glitch(t, dur)`, `zap(t)`, `boing(t, { f })`, `goo(t, dur, { f0, f1 })`, `heartbeat(t)`, `errorBuzz(t)` | character |
| `noiseHit(t, dur, { bp | lp | hp, q, attack, decay, sweepTo, pink })` | shaped noise — steam, spray, sizzle, sand, air, crowd |
| `toneSweep(t, dur, { wave, from, to, bend, cut, drive, vibrato, env })` | glides — motors, lasers, sirens, whistles; `from`/`to` notes or `{ hz }` |

## 8. Arrangement moves and automation

| Call | What |
|---|---|
| `gap(t0, t1, { buses, fade })` | silence buses (default drums, bass, music, lead) — the hole before a hit |
| `tapeStop(t, dur, { buses, until })` | real tape stop of what was written, silent until `until` |
| `stutter(t, { reps, slice, buses })` | repeat the first `slice` beats |
| `automate(bus, 'lp' | 'hp' | 'gain', [[t, value], …])` | filter sweeps (Hz, exponential), gain rides (dB) |

Moves apply after all notes are written, whatever order you call them in.

## 9. Render

`render(file, { lufs, truePeak, reverb, delay, eq, glue, monoBass, fadeOut, sections, report })`

- `lufs` -14 default; `truePeak` -1 dBTP ceiling (limiter keeps a 0.2 dB margin).
- `reverb`: 'room' · 'hall' · 'plate' · 'huge' · 'dark' or `{ room, damp, width, predelay }`.
- `delay`: `{ beats: 0.75, feedback: 0.38, lp: 3800 }` (ping-pong on the delay sends).
- `eq`: master bands `[{ f, g, q, type }]`; `glue` 0 … 1 soft saturation (default 0.3); `monoBass` Hz (default 120).
- `sections`: `S` from the timeline → with `report: true` or `--report`, a per-bus level table per scene.
- Prints integrated LUFS, true peak, the limiter's largest gain reduction. Returns `{ I, tp, gr }`.
- `loudness(L, R)` → `{ I, window(t0, t1) }` and `truePeak(L, R)` are exported for your own checks.

## 10. Writing a new voice

Any sound you can describe as oscillators, noise, filters and envelopes is ~15 lines. Pattern:

```js
import { SR, TAU, writer, at, noise, svf, drive, hz } from './synth/index.mjs';

/** Espresso steam: high-passed noise that swells in, with a hissing flutter. */
export function steam(t, dur, o = {}) {
  const w = writer(o.bus || 'fx', { pan: o.pan, verb: o.verb ?? 0.2, gain: o.vel ?? 1 });
  const f = svf();
  const i0 = at(t);
  for (let k = 0; k < dur * SR; k++) {
    const s = k / SR;
    const env = Math.min(1, s / 0.15) * Math.min(1, (dur - s) / 0.1);          // attack, release: no clicks
    const flutter = 0.8 + 0.2 * Math.sin(TAU * 23 * s);
    w(i0 + k, f(noise(), 3500 + 1500 * s / dur, 0.9).hp * env * flutter * 0.5);
  }
}
```

Rules: ramp every start and end (1–5 ms minimum) or it clicks; use `noise()` / `rand()` (seeded), never
`Math.random`; keep `vel: 1` near the other voices' levels (run the selftest's approach: peak ≈ 0 dB for hits); a
stereo voice passes `(i, left, right)` to `w`.

# Wow library: what the videos people save have in common

The level this skill aims for, measured. Read §1 at step 3 and the two patterns closest to your direction card. The
patterns are public videos described in words — their structure and pace, never their footage, words, logos or music.

## Contents
1. The bar in numbers
2. Ten patterns
3. How to use the library

## 1. The bar in numbers

Measured with `ref-sheet.mjs` on the seven motion references this skill is calibrated on, and read from a survey of
over a thousand videos made from code in the same season:
- **The music drives from the first second** in six of seven (the seventh waits two seconds) and never drops out: a
  loudness range of 0.6–4.3 LU across the whole video.
- **Tempo 105–129 BPM**: driving, not frantic.
- **Constant motion**: something moves in 67–100 % of frames; 45–91 visual hits a minute, most on the beat or at one
  constant offset (cuts a frame or two early on purpose).
- **Few hard cuts, often none**: three of seven are one continuous shot carried by morphs and camera moves.
- **The real product is the hero** in six of seven: its interface, its terminal, its app screens.
- **Copy in short parallel statements**, 1–4 words, one accent word — the shape, not these words: "Build.
  Preview. Ship." for a CLI, "Your menu. Your prices. Your guests." for a café.
- **One visual system per video** and one signature moment; real numbers roll; the end is a lockup with the name,
  one line and where to go (a URL, an install command), held.
- The most-saved videos in the survey open already in motion (no establishing shot), carry one device from start to
  end, and are either short (≤ 20 s) or genuinely long; every one of them is locked to its music.

## 2. Ten patterns

**1. One shape, never cut** (a UI morph loop; 14–16 s; 1:1 or 16:9; 120 BPM). A single element changes size, corner
radius, fill and content from state to state — a button, a player, a tab bar, a chart, a search field, a
notification — each change driven by a cursor click or the beat; the last frame is the first, so it loops. Text is
three words at most. Build: `scene-cookbook.md` §22 (`track()` springs, `ui-shot` crops). Fits: apps, design systems,
any product with several interface moments.

**2. The pipeline in four words** (an infrastructure platform's launch; 15 s; 129 BPM; dark). A point of light; three
claims slam one per beat; the install command types; the logo assembles from pixels; a live pipeline graph with a
running timer, one word per stage; a count rolls up beside a sphere of app icons; a
globe with arcs; two benefit flashes (one a split-flap board); an inverted frame; the lockup. A two-second intro, then
the groove to the end; 76 hits a minute. Fits: developer platforms, infrastructure, any product with a process.

**3. The terminal as a stage** (a command-line tool's major release; 48 s; 112 BPM). The prompt types the tool's name;
the logo decodes; each feature is a lowercase caption typed at the bottom — two short sentences —
over the real interface doing exactly that, one accent word per caption; it ends on the rewrite story, real
repository numbers decoding, and the install command. The groove plays from the first second; 45 hits a minute leave
time to read. Build: §6 typing, §4 decode. Fits: CLIs, libraries, open source, APIs.

**4. The 2×2 grid** (an app's loop; 10 s; 105 BPM). Four synchronised mini-scenes — the phone, a claim, a jackpot
number rolling, a 3D product burst — swap on downbeats; every frame moves. Fits: consumer apps with several hooks,
social ads. Build: §15.

**5. One layout, every mode** (a music app's promo; 24 s; 117 BPM). The same card recoloured per genre, each genre with
its own palette; a two-part tagline; kinetic triads; a 3D bar city on the beat; the app icon; a four-word
invitation. 91 hits a minute. Fits: products with modes, themes, templates, personalisation.

**6. The smart-camera demo** (a screen-capture tool's launch; 58 s; 129 BPM; light, Apple-like). A glass toolbar on a
blurred wallpaper; short phrases with one blue word; a cursor does real
actions while the camera zooms to where the work happens; the result lands in a chat; a pixel dissolve into the
logo; a two-line promise. Build: §23 (`camera()`, log zoom). Fits: SaaS, tools, any flow of actions.

**7. The kinetic hook** (the first 4–6 s of many launch films). Words rise out of a mask line, one per beat, the key
word in the accent face; the stack slides up for the second line; real rows of data stack under it, one per beat,
each with a click; everything squeezes into one dot that becomes the next scene. Build: §24 (`rise()`). Fits: every
promo — the promise or the pain in 3–6 words.

**8. The proof number** (the moment people screenshot). A real total, huge; the real rows land one per two beats,
each with a check, each taking its exact amount off; it lands on the payoff (£0.00, 100 %, "Live") on the drop;
the line rises under it. The arithmetic is checked before animating and every frame shows a real value. Build: §25.
Fits: fintech, invoicing, savings, performance, anything measurable.

**9. The loop end card** (X loops short videos). A dot springs into the logo mark; the wordmark wipes out from behind
it; the line rises; the CTA pops and the cursor clicks it; everything folds back into the dot — the last frame is the
first, the cursor included. Build: §26, `LOOP = true` in `js/timeline.mjs`; QA checks the seam.

**10. The reference remake** (a launch film everyone knows, rebuilt shot by shot for another brand, shown side by
side). The grammar carries over — timing, transitions, framing, camera — the footage, words and logo never do. Only
when the person asks for it ("like this video"): SKILL.md step 2.

## 3. How to use the library

- **No references from the person**: pick the two patterns closest to your direction card; take their numbers (pace,
  tempo, how early the groove plays) as the bar and their structure as a starting point. The concept is still this
  brand's (`direction.md` §6) — two briefs of the same kind should not come out as the same pattern.
- **References given**: analyse them (`ref-sheet.mjs`); they outrank this library.
- **Measure the draft**: `node <skill>/scripts/ref-sheet.mjs out/<slug>-draft.mp4 --bpm <BPM>` — moving share, hits a
  minute and the on-beat share should sit in the ranges above for a driving film; a calm film sits lower on hits, but
  a still frame outside the end card is a bug in any film.