# pixi-effects — full documentation for AI agents

Concatenation of the skill, cheatsheet, pitfalls, recipes and the DSL / API / media-tools references. Generated by scripts/build-llms.mjs; do not edit.



<!-- ===== skills/pixi-effects/SKILL.md ===== -->

> Written for pixi-effects 0.45.0. Update this skill with `npx skills update`; the newest docs are at https://yjmtmtk.github.io/pixi-effects/

# pixi-effects — write a video as data

You describe a video as a tree of plain objects; the library plays it in a canvas and exports it (MP4/WebM/MOV). You never write per-frame code (except inside a `canvas` layer, which you add only for a picture nothing else draws). **Read `reference/quickstart.md` first (2 KB): the commands, a working title card, and what goes wrong most.** For anything it does not answer, ask the docs: `npx pixi-effects help <word>` prints the sections about a word (mask, threeD, keyframes, music …); `npx pixi-effects recipe` lists the tested recipes (a title, a lower third, a chart, kinetic type, a 2.5D scene …) and `npx pixi-effects recipe <id>` prints one with its code. `reference/cheatsheet.md` (35 KB) and `reference/pitfalls.md` (41 KB, numbered) are for looking things up when a warning or the picture surprises you: search them for the word, do not read them end to end. A simple title needs the quick start and one recipe, nothing more.

## Workflow

1. **Start from the template:** `npx pixi-effects new my-video` writes `my-video.html` (or copy `template.html` by hand); it also has the shared loader (`<div class="pe-loader" data-label="LOADING">` + `pixi-effects/loader.css`: HTML and CSS only, animating just `transform` / `opacity`, so it keeps moving while the page builds the video; `movie.init()` fades it out). Keep it; a loader of your own is fine (`pe-loader--custom`) as long as it only animates `transform` / `opacity`, never with JavaScript or `requestAnimationFrame`; it loads the library from a CDN, collects every console warning into `window.__logs`, and exposes `window.movie`). One HTML file, plain JS. Default canvas 1280×720 @ 30 fps.
2. **Give the movie a poster time.** In `movie.init` add `poster: <seconds>`: the most striking moment (a title fully on screen, not the first frame, which is often black). The canvas shows that picture before play (the playhead stays at 0 and play starts from 0), and the check writes it as `poster.jpg`.
3. **Write the composition as data.** Anything repeated (letters, bars, particles, scenes) is a JS function or loop that returns specs — never copy-paste objects. Derive coordinates and times from constants/data, not magic numbers.
4. **Show the human, EARLY: the first address goes out within two minutes.** Do it right after step 1, BEFORE you write the brief or collect assets: the copied template is already a page. Run `npx pixi-effects view my-video.html` (`--no-open` only prints the address; in the background, it keeps running), tell the human the address in your first message, and keep editing the same file: it opens their browser on the page with a scrubbable, zoomable timeline under it (click / drag to seek, + / − or Ctrl/⌘ + wheel to zoom) and runs until Ctrl-C. When the folder changes the viewer shows "Updated hh:mm:ss — reload (R)" and nothing else: the picture they are looking at never switches by itself, a reload returns to the frame they were on, and the switch "auto" (off by default) reloads only while the movie is paused. Do not restart it after every edit; they see the work grow instead of waiting for the end. **Deliver the file:** `npx pixi-effects render my-video.html -o my-video.mp4` renders the page headless to mp4 / webm / mov / mkv and exits 0 only when the file is written; run it AFTER the check below passes. **Run the check — one command does steps 3, 4 and the export:** `npx pixi-effects check my-video.html` (Node ≥ 22 and Chrome installed). **If `npx` says command not found, or prints nothing** (your npm may hold back a release that is a few days old, or an old release is cached): `npm i pixi-effects`, then `node node_modules/pixi-effects/ai/tools/check.mjs my-video.html` (the same for `render.mjs` and `view.mjs`). It starts its own private Chrome (nothing is shared with other sessions), waits for `window.__ready`, and writes `timeline.html` (every layer as a bar on a time axis: ◆ keyframes, shaded transitions; hand it to the human to open) and prints: console warnings, `movie.inspect` over the WHOLE timeline (grouped), `movie.inspectAudio()`, then exports an mp4 and decodes it again (video size and length, audio length, loudness per second, silence). It writes `check-out/<name>/sheet.png` — **open that picture and look at it** — plus the mp4 and `report.json`. Exit 0 = nothing to fix; exit 1 = a list of problems; fix them and run it again. A key a layer does not have (a typo in a layer key, a keyframe property or a text style key; `anchorX` outside `initial`; `pitch` outside `sfx`) is a warning that names the key and what you probably meant: treat it like any other warning. Text that overlaps text is listed under `review` (not a failure: ghost layers, glow copies and per-letter boxes are often intentional; look at the sheet; `--strict` makes them fail). The manual steps below are for looking at one frame closely. The same judgement is in the page: `await movie.review({ at: 'title@end' })` returns `{ frames, problems, review, fonts, audio, at }` (what `check` prints, as data) and `movie.resolveAt('3.5, title@end')` turns moments into frames.
   **Or by hand: run it and read the logs first.** `window.__ready` must be `true` and `window.__logs` should be `[]`. A pixi-effects warning is an instruction: fix what it names.
5. **Look at it** — you cannot judge motion from code. The library has the tools built in:
   - `await movie.contactSheet({ count: 6, as: 'dataURL' })` → ONE image of several labelled frames (pass `frames: [...]` / `times: [...]` to choose; include the middle of every transition and the last second). Save it and view it.
   - `await movie.inspect(frame)` → every layer's canvas bounds and visibility, plus `issues` (text off the canvas, cut off by an edge, empty, overlapping other text, or hidden / struck through by a picture: an opaque shape or image drawn OVER part of it, or a thin line drawn over its body; a shadow, a glow, a ring or a backdrop under it is not reported). Run it at several frames; fix every issue it names.
   - `await movie.snapshot(frame, { as: 'dataURL' })` → one frame, canvas only (no player bar).
   - `movie.inspectAudio()` → **hear with numbers**: for every sound its `start`, `sound.length`, `sound.peakDb`, `sound.loudestAt` (line this up with the picture) and `sound.brightnessHz` (< 500 dark, > 8000 airy), plus `issues` (limited mix, inaudible or cut-off sounds). Check it whenever the movie has audio; `render()` encodes this same mix.
   - **A moment, a movement, the sound (`pixi-effects check` options):** `--at 3.5,title@end,50%,f120` writes those pictures to `check-out/<name>/frames/*.png` (and `at.png`; with `--out DIR` they land in `DIR/frames/` and `DIR/at.png`, there is no `<name>/` inside DIR); add `--crop X,Y,W,H` (canvas pixels) to get each picture as just that part, enlarged up to 4x, so a 40 px figure, a fine line or a texture can be judged (the contact sheet tiles are too small for that): the last frame of a layer is `name@end`, the middle `name@mid`. `--seam` (for a movie made to loop) compares the last frame with the first against the steps between ordinary neighbouring frames and says `the loop closes` or `JUMP` with the numbers (a jump is a problem, exit 1); `--onion 1:3` writes `onion.png`, eight frames of seconds 1–3 overlaid (the later the stronger): a trail that shows a movement's path and easing (even steps = constant speed, bunched = slow). `report.audio` now has `loudness` (`integratedLufs`, `truePeakDb`, `clippedSamples`, `silences`), `scenes` (per named top-level composition), `cues` (when each sound starts) and `notes` (advice: quiet or loud for web video, little headroom, silent stretches; web video is typically −14 to −16 LUFS); `waveform.png` draws the mix with the scene edges and the cues. A web font that failed to load fails the check; a text layer none of whose fonts is installed is listed for review.
   - **A deck** (`composition.stops`, `deck()`): `await movie.contactSheet({ frames: movie.stops.map(s => s.frame), as: 'dataURL' })` is one picture of every stop (the check writes it as `stops.png`); what the audience reads while a page waits is that picture, so check every one. `await inspectStops(movie)` (from `pixi-effects/present`) lists the stops where the picture is still changing (a stop landing before its animation ends); the check prints it as a review list: move the stop later or flag a settled one `pdf: true`. `await stopImages(movie, { which: 'pages' })` / `exportPDF(movie)` give the pages themselves.
   From a browser tool the result is a `data:` URL string: `agent-browser eval "movie.contactSheet({ count: 6, as: 'dataURL' })" | python3 scripts/save-image.py /absolute/sheet.png`, then open the PNG. Sheet tiles are small (~480 px): use `snapshot` for detail. `inspect` output is long on busy scenes: pass `{ layers: 'none' }` and read `issues` first. Give layers a `name` so inspect paths are readable. A moving ticker is not flagged as cut off.
6. **Iterate** on what you saw (clipped text, collisions, wrong timing). Fast motion looks choppy: add `motionBlur: true` to `movie.init` (render, snapshot and contact sheet then show a film-style blur; renders take ~8× longer). Then export: `const blob = await movie.render({ format: 'mp4' })` (about real time; `movie.on('progress', …)` reports 0–100). **While you iterate, do not export the whole movie:** `check --no-export --at <the moment you changed>` takes seconds (3 to 10 s on the gallery pieces: most of it is loading the page and measuring the sound); to see motion, `render({ range: [from, to] })` / `pixi-effects render --range 10:15` / `--scene name` exports only that part (picture and sound); `draft: true` / `--draft` is half size, low quality and no motion blur: a much smaller file (a piece that asks for motion blur renders much faster as a draft: 4 s of a firework piece took 14.0 s, and 8.2 s as a draft, about 7 s of either being the browser's start-up), but the drawing itself is not faster. Export the whole movie once, at the end.

## For a film (more than a title card): direct it first

**Read `reference/direction.md` before writing a composition for a product film, a company introduction, a launch or a data story.** It is renderer-neutral: write `brief.md` (the one sentence to remember, the REAL assets with paths, what must never be invented; if a needed asset is missing, stop and ask), `style-guide.md` (palette and type taken from the real source, a motion rule per class of object) and `shotlist.md` (a row per beat with entry and exit state) next to the page; then build, then review the rendered frames cold. What is specific to this library:

- **Time and sound:** pick a tempo whose bar is a round number of seconds (96 bpm: 2.5 s; 120 bpm: 2 s), put every cut on a bar line and every sfx on its beat. `npx pixi-effects check` prints a `music` read-back (bars per track, what starts on which beat, the drum span): verify the sound with it.
- **Interactive pages (a person clicks, hovers, drags):** `movie.pick(x, y)` says what is under a point, `movie.hover({ onEnter, onLeave })` and the recipes `pick-click`, `drag-drop`, `drag-3d` build on it; **test the page with `check --do "hover Lime; click Lime; drag card > 770,240; wait 1"`**: real mouse and key events on the page (a point is `x,y` in canvas pixels or a layer name, the middle of its box), run after everything else, and the report says per step what was under the pointer, which variables changed (`score 0→1`), whether the page warned, and keeps one picture each in `steps/` (look at them). A step on a layer that is not there, or a point outside the picture, is a problem. To do the same by hand (a browser tool, Chrome's protocol; serve the folder over http: a model, an image or a module beside the page does not load from file://): `const r = canvas.getBoundingClientRect(); canvas.dispatchEvent(new PointerEvent('pointerdown', { clientX: r.left + x * r.width / W, clientY: r.top + y * r.height / H, bubbles: true, pointerId: 1 }))` (then `pointermove`, `pointerup`, with a `settle` of 300 ms after a `setVars` rebuild), and read `movie.vars`, `movie.currentFrame`, `movie.isPlaying`, `movie.pick(x, y)` and the canvas's `style.cursor`. A canvas for touch has `style="touch-action: none"`.
- **Review:** `check` prints a `motion` line (how much of the movie moves, when the last movement ends, the longest still stretch) and lists, for review, a plain-colour last frame, a first second with nothing on screen, and a hold of 3 s or more: `OK` does not mean the film is rich, only that nothing is broken, so read those lines and the contact sheet. `check --at 3.5,title@end,50% --pick 640,360` also says what is under that canvas point at each moment (the layers, top first; a three layer names the object) — a layout question you can answer without looking; `check --at 3.5,title@end,50%` writes the contact sheet and single frames; look at mid-transition frames of the exported file too. Frames are seekable and deterministic here: render the same range twice and compare the frames if you doubt it.
- **Formats:** make the formats the human asked for, one if they did not say. When a vertical cut is wanted it is its own composition: one source, a layout function, `?f=9x16` (recipe `two-formats`); `check` and `render` take `--query f=9x16`.
- Fit a picture into a rectangle with the `photo()` helper of that recipe (`scale: 'cover'` fits the PARENT only); designed pictures (posters, flyers, screenshots) are shown whole, never cropped.

## If your shell is a sandbox that is not the person's computer

A browser chat's code execution is a small container (often root, a weak CPU, a closed network), not the person's computer, and `check` / `render` there stall (Chrome refuses to start as root without `--no-sandbox`; with the CDNs unreachable `check` waits minutes and only says "timed out"). **Do not use the workflow below there: follow the chat way** (https://raw.githubusercontent.com/yjmtmtk/pixi-effects/main/ai/CHAT.md), even though you have a shell. No `npx`, no `npm i`, no `check` / `render` / `view`: take the template from the chat guide above (or copy `template.html` of this skill), edit the composition, look things up in `reference/*.md` with your file tools, and give the person the page as it is (the CDN imports stay: their browser reaches them). **Do not start Chrome or render an MP4 there** (a weak container: very slow): the person presses the download button in the player bar and their browser exports it on their own computer; warnings reach you through the red box of the chat template, which they paste back. If something stalls, stop after two tries (no wrapper for Chrome, no rewired import map) and say what you did not check.

## Look at footage before you use it

If you are handed a 3D model (.glb / .gltf), `probe model.glb` lists its clip names and its size before you write any code (recipe `gltf-in-space`). If you are handed a video or a sound (a clip to put in the video, a reference to match), look at it first, with no ffmpeg needed: `npx pixi-effects probe clip.mp4` (size, length, rotation, whether it has sound), `npx pixi-effects frames clip.mp4 --sheet -o looks` (a contact sheet: open the PNG), `npx pixi-effects sound clip.mp4` (loudness, peak, silences), `npx pixi-effects trim clip.mp4 3 8 -o cut.mp4` to cut it (by copy, starting on the next key frame, and it says the real times; `--exact` re-encodes), `npx pixi-effects concat a.mp4 b.mp4 -o both.mp4` to join clips by copy (same codecs, size, rotation and sound, or it says what differs) and `npx pixi-effects audio clip.mp4 -o sound.m4a` for the sound alone. A clip you have not looked at is a clip you do not know: phone clips are often rotated, screen recordings often have no sound. `frames`, `sound` and `trim --exact` use Chrome; if ffmpeg is installed and the job is a long transcode, use ffmpeg. `npx pixi-effects help media` has the reference.

The same command checks a file you MADE before it goes somewhere with rules (a stock site, a platform, a client): `npx pixi-effects probe out.mp4 --expect "size=3840x2160 fps=30 frames=300 bitrate>=35M audio=none"` measures the file itself and prints ok / FAIL per number (exit 1 if any fails). A render's `bitrate` is a ceiling, not a target: a quiet picture is written far under it, so ask `probe`, do not trust the setting.

## The rules that cause most failures

- **Keyframe `at` starts at 0 when the layer appears** (negative = back from the layer's end). A layer's own `at` and a transition's `at` are composition time.
- **Layers are hidden, not removed, after their lifespan; z-order is array order.** Switch scenes by stacking layers with `at`/`duration` over an opaque background rect.
- **Angles are degrees. `+z` is toward the viewer. Numbers can be expressions** (`'GW/2 - w/2'`; no `pi`; no per-frame variable).
- **Anchors**: rect/circle/ellipse are centred on `x,y`; text and image are top-left (use `anchorX/anchorY: 0.5`); compositions use `pivotX/pivotY`. A bar that grows from its base needs `anchorY: 1`.
- **Sound effects need no files:** `{ type: 'audio', sfx: 'swoosh', at: 2 }` — presets `click pop swoosh swipe hit riser chime beep coin glitch typewriter`; knobs `pitch`, `brightness`, `seed`. The layer lasts as long as the sound (`duration` stretches it); a `riser` is loudest at its end (`at = hit − duration`), a `swoosh` 0.16 s in. A music file shorter than its layer goes silent — `loop: true`.
- **Masks live in the parent's coordinates and don't follow the masked layer.** **`filterArea` is in the layer's own coordinates.** **One mask for several layers: name the layer and write its name as the `mask`** (`mask: 'band'`; `{ layer, channel: 'luma', invert: true }`; a list intersects); the named layer is not drawn and must live as long as its users. A **luma wipe** is a transition: `{ kind: 'luma', map: 'radial' | 'linear' | 'diagonal' | '<grayscale asset>', softness, flip }`.
- **2.5D needs `threeD: true`** on each layer plus a `{ type: 'camera' }` layer; camera props go in `initial`/keyframes; keep every `z` below the camera distance (≈ 989 at 720p, fov 40); under a dolly zoom only `z = 0` stays fixed; **depth of field** is two camera props, `focus` (a threeD layer's name or a z) and `aperture` (30 default, 0 off), and a rack focus is a keyframe on `focus`.
- **Group / parent layers = `{ type: 'null', name: 'rig' }`** (draws nothing, only moves) + `parent: 'rig'` on the layers that should follow it: their `x`/`y` are then measured from the null's origin, and the null's position / rotation / scale / alpha carry them (orbits, clock hands, grouped fades). Nulls chain. Only `null` layers can be parents; not for `threeD` layers.
- **Time:** `speed` (slow motion, backward) and `time` (a curve of the layer's own seconds: freeze, rewind, ramp) on video, audio-file and composition layers; put what you want to rewind in a composition. Children of such a composition are in ITS seconds. `ease: 'cubic-bezier(.4, 0, .2, 1)'` is the CSS curve. See the recipe `rewind-and-replay` and pitfalls 69–73.
- **Built in:** `animateText()` (per-letter / per-word / per-line entrances and exits in one call: `...animateText('Title', style, { x, y, align: 'center', at: 0.5, duration: 5, in: 'rise', out: 'fade', stagger: { each: 0.05 } })`), `splitText()` / `measureText()` (per-letter / per-word layers, exact positions, by hand), `shape: 'arc'` (progress rings, pie / donut slices: animate `endAngle`), `fillGradient` (linear/radial, alpha stops → vignettes), `{value}` counters, `repeat`/`yoyo`, `orbit()`, seeded randomness (`rand(seed)` / `noise(x, seed)` in expressions, `random(seed)` in JS, never `Math.random()`) `wiggle()` (a seeded shake as keyframes; on a camera put it on `offsetX` / `offsetY` so it rides on the move) `cameraPath()` (a camera flight through `[x, y, z]` points as keyframes; layers it passes: `hideBehindCamera: true`) depth of field (camera `focus` + `aperture`: `{ type: 'camera', initial: { focus: 'title' } }` blurs the other threeD layers by depth; a rack focus is a keyframe on `focus`) `music` (a tune with no file: `{ type: 'audio', music: { bpm, tracks: [{ inst: 'keys', notes: 'Cmaj7:4 Am7:4' }, { inst: 'bass', notes: 'c2:2 g1:2' }], drums: { from: 8, kick: 'x...x...' } } }`: notes and chords as text, counted in beats; instruments `keys pluck pad bass sub lead bell musicbox`; `musicEnvelope(music)` feeds `react()`), `audioEnvelope()` / `bpmEnvelope()` + `react()` (visuals that follow music: `const env = await audioEnvelope('music.mp3', { frameRate })` before `movie.init`, then `keyframes: react(env, { duration, props: { scale: { base: 1, amount: 0.4, band: 'bass', release: 0.2 } } })`; `beats: true` pulses on the beats; `bpmEnvelope(120, …)` when there is no file), `deck()` + `Presenter` from `pixi-effects/present` (a talk as one movie: pages, steps, stops that pause playback, arrow keys / click / swipe to move on: `...deck({ transition: { kind: 'slide', duration: 0.6 }, pages: [{ name, duration, stops, sequences }] })`, `new Presenter(movie, { canvas })` from `pixi-effects/presenter`; G = page overview, P = presenter view with notes and a timer; `pixi-effects render talk.html -o talk.pdf` = a PDF of the pages), `particles()` (bursts, snow, confetti, sparks as seeded layers: `...particles({ count: 90, at: 2, life: [1, 1.8], area: { x: 640, y: 330 }, speed: [120, 420], gravity: 240, fade: { out: 0.6 } })`), `followPath()` (a layer along an SVG path: `keyframes: followPath({ d, duration, orient: true })`), path morphing (`{ shape: 'path', d, morphTo, initial/keyframes: morph 0 → 1 }`) and `stagger()` (delays for a wave of layers: `stagger(letters, { each: 0.05, from: 'center' })`, or `stagger(n, …)` for numbers; GSAP-style `each` / `amount` / `from` / `grid` / `ease`). **Not in the DSL (hand-roll with a JS loop):** other per-frame curves (waves, spirals: sample them into short linear keyframes). (Draw-on strokes `trimEnd`, text that changes over time `set: { text }` / `visibleChars`, shake `wiggle()` and particles are built in.)
- **Draw it yourself (`canvas` layer):** when nothing in the library draws what you need (an afterimage, rings, a brush stroke, a pixel sprite, a chart), `{ type: 'canvas', width, height, draw: (ctx, t, info) => { … } }`: your function of the time draws into the layer's own cleared 2D canvas and it is a normal layer. Pure function of `t` and `info.params` (`info.random()` is seeded; no `Math.random` / `Date.now`); a simulation is computed in `setup` and read by `info.frame`. `info.time` is the movie's clock (several layers share it; never add `at` by hand), `info.canvas(w, h)` makes sprites and masks in `setup`, data shared by several canvas layers lives in module scope, and `import { ease, noise, noise2, random, samplePath } from 'pixi-effects'` gives the library's easing, seeded noise and a path walked by length. `check` prints a `canvas` line (deterministic, slowest draw in ms) and does NOT see text drawn in a canvas. `help canvas`, recipes `canvas-trail`, `canvas-life`, `canvas-text-mask`, `canvas-text-on-path`, `canvas-bars`.
- **Shader layer and warp:** `{ type: 'shader', fragment: 'void mainImage(out vec4 fragColor, in vec2 fragCoord) { … }', uniforms: { speed: 1, tint: '#ff8040' } }` draws a Shadertoy-style formula (GLSL ES 3.00; `iTime` `iResolution` `iFrame` are declared; keyframes move `'uniforms.speed'`; opaque by default; it cannot read the layers behind it; a compile error comes back in your own line numbers). `filters: [{ type: 'warp', kind: 'wave' | 'haze', strength: 6 }]` bends a layer's picture like water or heat.
- **Light, shadow, fog (2.5D):** a `{ type: 'light', kind: 'ambient', initial: { intensity: 0.2 } }` plus a `spot` / `point` / `parallel` light (`castsShadows: true` on the light AND on the `threeD` layers that cast) shades every `threeD` layer by angle and distance; `lit: false` opts a layer out; camera `fogNear` / `fogFar` / `fogColor` fade what is far. What no light reaches is black (add the ambient light); layers are drawn in distance order (no depth buffer). `check --at` prints how lit each layer is.
- **Blend modes:** `blendMode` takes 18 CSS names (`add` `screen` `multiply` `overlay` `soft-light` `hard-light` `color-dodge` `color-burn` `darken` `lighten` `difference` `exclusion` `hue` `saturation` `color` `luminosity` `linear-burn`, hyphenated) on any layer: glows and light leaks (`add`, `color-dodge`), colour casts and contrast (`soft-light`, `overlay`), vignettes (`multiply`). It blends with everything below the layer; on a composition each child blends (as one picture: `threeD: true` or a filter); 10+ of the new modes on screen at once warn; it works with every mask.
- **One `Movie` per page.** A sound effect needs no `duration` (it lasts as long as its clip). Seeking is safe: counters, colours and growing shapes are right after any jump.

## Layout sanity (the cheap bugs a screenshot catches)

Centred text must be positioned by `anchorX/anchorY: 0.5`; estimate text width as ~0.6 × `fontSize` per glyph (monospace) or ~0.8 (heavy sans) and leave margin; captions stay above the bottom 60 px; nothing important within 5 % of the frame edge; a `threeD` layer can be sorted in front of text.

## Files

- For an AI in a chat with no shell, the short version is https://raw.githubusercontent.com/yjmtmtk/pixi-effects/main/ai/CHAT.md (it copies https://raw.githubusercontent.com/yjmtmtk/pixi-effects/main/ai/chat-template.html: one self-contained page that loads from a single CDN and shows warnings in a red box).
- `reference/cheatsheet.md` — every layer type, prop, default and rule on one page.
- `reference/recipes.md` — tested building blocks: slam type, lower-third, marquee, count-up, bar chart, 2.5D title, camera orbit, slideshow with transitions + music, looping, particles, gradients/vignette, three.js metal.
- `reference/pitfalls.md` — the full list of real mistakes, with status.
- `reference/direction.md` — how to direct a film (any renderer): brief, style guide, shot list, assets rule, sound on the beat grid, review protocol, formats, gates.
- `npx pixi-effects check` — the one-command review (see Workflow step 5).
- `template.html` — the starting file. (It loads the released library from a CDN, so it works from any folder.)
- `scripts/save-image.py` — save a `dataURL` result (contact sheet / snapshot) to a PNG.
- Full reference: https://yjmtmtk.github.io/pixi-effects/docs/dsl.md and https://yjmtmtk.github.io/pixi-effects/docs/api.md


<!-- ===== skills/pixi-effects/reference/quickstart.md ===== -->

# pixi-effects quick start

    npx pixi-effects new my-video          # a page to edit (--size 1080x1920 --duration 20)
    npx pixi-effects view my-video.html    # look at it while you edit
    npx pixi-effects check my-video.html   # warnings, layout, sound, a contact sheet: LOOK at the PNG
    npx pixi-effects help <word>           # the docs about a word: mask, threeD, keyframes, music
    npx pixi-effects recipe [id]           # tested pieces to copy

A video is data: `sequences` (text, shape, image, video, audio, composition, camera), each with `at`, `duration`, `initial`, `keyframes`.

```js
// @recipe quickstart
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#10162b' } },
  { type: 'text', text: 'Hello', at: 0.3, duration: 4, style: { fontSize: 140, fill: '#ffffff', fontWeight: '800' },
    initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
    keyframes: [{ at: 0, from: { y: 'GH/2 + 40', alpha: 0 }, to: { y: 'GH/2', alpha: 1 }, duration: 0.6, ease: 'power3.out' }] },
];
```

What goes wrong most:
- A keyframe `at` is seconds from the layer's own start; a layer's `at` and a transition's `at` are movie seconds.
- A layer stays hidden after its time; z-order is array order; a scene is layers with `at`/`duration` over an opaque rect.
- Numbers may be expressions (`'GW/2 - w/2'`); angles are degrees.
- Anchors: rect and circle are centred on x,y; text and image are top-left (use `anchorX: 0.5`).
- A warning is an instruction: `window.__logs` must be `[]`. Fix what it names.
- Sound needs no files: `{ type: 'audio', sfx: 'swoosh', at: 2 }`, or `music: { bpm, tracks }`.
- Never say done before you have looked at the check's PNG: it cannot judge a line break, a font, or how a fade ends.
- Exist already (`help <word>`): `spans` (colour part of a text line), `vars` + `--var name=value` / `--size 1080x1920` (one page, many versions).
- Anything else: `help <word>` first; the cheatsheet is for grep, not for reading.


<!-- ===== skills/pixi-effects/reference/cheatsheet.md ===== -->

# pixi-effects cheatsheet

A video is **data**: a tree of plain objects. Everything below is a JS object you put in `composition.sequences`. Build repeated structure with JS functions and loops; the spec is just objects.

## Conventions (state once, never guess)

| Thing | Rule |
|---|---|
| Canvas | pixels, origin top-left, `+x` right, `+y` down. Typical: 1280×720 @ 30 fps |
| Angles | **degrees**: `rotation`, `skew*`, `rotationX`, `rotationY` |
| Depth (`z`) | `+z` toward the viewer (bigger, nearer) |
| Numbers | any number may be an **expression string**: `'GW/2 - w/2'`, `'min(W,H)*0.4'` (build-time only; no per-frame time variable). Functions: `min max abs floor ceil round sqrt pow sin cos tan lerp clamp smoothstep mod step`, `PI`, and **seeded** `rand(seed)` (0…1) / `noise(x, seed)` (−1…1): give each layer its own seed, never `Math.random()`. **Relative values** work in a keyframe's `to` / `from` / `set` (not in `initial`, a style, or the start of a `from`+`to`): `'+=36'` / `'-=36'` are measured from where the layer stands, and the right side is an expression (`'-=GW*0.1'`). A slide-in is `from: { x: '-=36' }`, a nudge `to: { y: '+=40' }`; keyframes one after another stack; with `repeat` the same move replays from the same start (it does not stack). Expressions work in layer `x y` and the other numeric props, **not** in `line.from / to`, `polygon.points` or `path.d`: compute those in JS (`const W = 1920`) |
| Colours | `'#rrggbb'` strings or numbers; text colour is `style.fill` (or `initial: { fill }`; a `fill` keyframe animates it), shape colour is `fillColor`/`strokeColor`, image colour is `tint` |
| Z-order | **array order**, later = on top. A layer is hidden (not removed) outside `[at, at+duration)` and keeps its last values |
| Time of a sequence's `at` | seconds from the start of its **parent composition** (default 0) |
| `from` before its `at` | a keyframe's `from` holds **from the start of the layer**, not from its `at` (so a title waits invisible with `from: { alpha: 0 }`), and it replaces `initial`: `initial: { alpha: 0 }` with `{ at: 2, from: { alpha: 1 }, … }` shows the layer at alpha 1 from 0 s. To appear only at 2 s give the layer `at: 2`, or start from the same value in both |
| Time of a keyframe's `at` | seconds from the start of **its own layer**; **negative = back from the layer's end** |
| Time of a transition's `at` | seconds from the start of the **parent composition**; negative = back from its end |
| `duration` | defaults to the parent composition's duration |
| Time **inside** a layer | `speed` (a multiplier on the layer: 1 = as is, 2 = twice as fast, 0.5 = slow motion, **negative = backward**) and `time` (seconds of the layer's own content, in `initial` / keyframes: a video's or audio file's position in the file, a composition's local playhead; **negative = back from the end of the content**) on **video, audio file and composition** layers. **The layers inside a composition write `at` / `duration` / `keyframes` in THAT composition's own seconds** (its local time); the composition's own `at`, `duration` and keyframes stay in the outer time. `duration` is always the layer's life in the outer time (`{ duration: 4, speed: 2 }` lives 4 s in the movie and plays 8 s of content; its children, with no `duration` of their own, last those 8 s) |

## Expressions

Operators `+ - * /`, parentheses, unary `-`. Functions `min max abs floor ceil round sqrt pow sin cos tan` (radians; there is **no `pi`**: write `3.14159`).

| Variable | Meaning |
|---|---|
| `W`, `H` | parent composition size |
| `GW`, `GH` | root (movie) size |
| `w`, `h` | this layer's own size (image/video natural size, text size **after** its style is applied, shape bounds) |
| `cover`, `contain` | scale that makes the layer cover / fit the parent (`scale: 'cover'`) |
| `t`, `d`, `T` | layer start time, layer duration, parent duration |
| your own names | `movie.init({ vars: { shift: 0, title: 'NORD' } })`: a number is a name in an expression (`'W/2 + shift'`), any value is `{title}` inside a string (`text: '{title}'`, `fillColor: '{accent}'`). Reserved: the names above, `value`, the functions, `PI`. `await movie.setVars({ shift: 40 })` builds again at the same frame; `await movie.resize(w, h)` makes `W` / `H` follow a window. `render --var title=SÜD --size 1080x1920`, `check --size 1920x1080,1080x1920` |

## Common fields (every layer)

```
name, at, duration,
initial: { ...props applied before any keyframe },
keyframes: [ { at, duration, ease, set | to | from | (from + to), repeat?, yoyo?, repeatDelay? } ],
filters: [ { type: 'chromaKey', keyColor, threshold, smoothing, spill } | { type: 'glow', name?, outerStrength: 3, color: '#ffd166' } /* any named filter, see below */ | { type: 'custom', name, filter: <Pixi Filter> } ],
mask: <a layer spec> | 'matteName' | { layer: 'matteName' | <a layer spec>, channel: 'alpha' | 'luma', invert: true } | [ …names or { layer: 'name', … } ],   // an inline mask with no `at` of its own starts and ends with the layer it masks (its keyframes count from that layer's start); an explicit mask `at` is composition time. A NAME points at a sibling layer (the matte, shared by any number of layers, NOT drawn itself, alive for its own `at`/`duration`); a list is an intersection; subtract = `invert: true`
filterArea: { x, y, width, height }   // in the layer's OWN coordinates; lets blur/glow draw past the layer's bounds
threeD: true                          // opt into 2.5D (see below)
blendMode: 'normal' | 'add' | 'screen' | 'multiply' | 'overlay' | 'soft-light' | 'hard-light' | 'color-dodge' | 'color-burn' | 'darken' | 'lighten' | 'difference' | 'exclusion' | 'hue' | 'saturation' | 'color' | 'luminosity' | 'linear-burn'   // CSS names (hyphenated); blends with EVERYTHING BELOW the layer; add / screen brighten (glows), multiply darkens, soft-light / overlay for colour casts and contrast, color-dodge for light sources; on a composition the children each blend (to blend it as one picture: threeD: true or a filter); the 14 new ones cost ~2 ms a layer on WebGL (10+ on screen warns)
```

Animatable props (`initial` / keyframes): `x y alpha rotation scale scaleX scaleY pivotX pivotY anchorX anchorY skewX skewY tint width height visible autoAlpha`, plus for shapes their style/geometry, for text `fill`, for audio `volume`, for 3D `z rotationX rotationY`, filter params as `'filters.<name>.<param>'`, three objects as `'three.<obj>.<path>'`. **These go in `initial` / keyframes, never at the top level of a shape or text layer** (top-level `x`, `rotation`, `strokeColor`, `fillAlpha` each warn "is not a … key"): the top level of a shape holds its geometry (`width height radius d startAngle endAngle cornerRadius anchorX anchorY`), `trimStart` / `trimEnd`, `strokeCap` / `strokeJoin`, `fillGradient`.

Keyframe kinds: `set` (jump at `at`; undone when you seek back), `to` (animate to), `from` (animate from), `from`+`to`; a value may be relative to where the layer stands (`from: { x: '-=36' }` slides in from 36 px to the left of its place). `from` / `from+to` show their start value from the layer's start, so a delayed fade-in needs no `initial.alpha`. `repeat` (finite extra plays), `yoyo`, `repeatDelay` loop any of them (endless repeats are not allowed). `ease` = an ease name (`'none'`, `'power2.out'`, `'expo.out'`, `'back.out(1.7)'`, `'elastic.out(1,0.5)'`, `'sine.inOut'`, `'bounce.out'`, **`'cubic-bezier(.4, 0, .2, 1)'`** (CSS syntax, x1 and x2 in 0…1; `.4, 0, .2, 1` is a gentle in-out; `.2, .8, .2, 1` is FRONT-LOADED, not slow motion: half of the change in the first 13 % of the time, 90 % by 39 %, 99 % by 74 %, then a long settle, so what sits at the END of the content gets the glide; `.2, .8, .5, 1` has a shorter tail). `power1…4` are the powers 2…5: `power2` is a cubic, `power2.in` has done only 12.5 % at half time (42 % at three quarters)… and springs: `'spring(mass, stiffness, damping)'` or `'spring.gentle' | 'snappy' | 'bouncy' | 'wobbly' | 'slow'`; **`duration: 'auto'` = the time the spring takes to settle** (presets, settle time / highest value reached as a multiple of the target: `snappy` 0.42 s / 1.01, `gentle` 0.72 s / 1.02, `bouncy` 1.08 s / 1.28, `slow` 1.29 s / 1.00, `wobbly` 1.61 s / 1.40: time the next beat from these) (real physics; with a number `duration` is the settle time and only the damping ratio shapes it; a damping ratio of 1 or more never overshoots, so `spring(1,170,26)` does not bounce: use damping below 20 at stiffness 170; `'auto'` works on keyframes only, not in `animateText` / `orbit` tweens; a `stagger` ease may be a spring, its delays are held inside the spread). Default ease is linear.

## Layer types

**text** — `text`, `resolution` (1–8: draw at N× the pixels so text inside a parent scaled up N× stays sharp), `style` (any PixiJS TextStyle field: `fontSize fontFamily fontWeight fill letterSpacing lineHeight align wordWrap wordWrapWidth stroke dropShadow padding`; expressions OK for numbers), `colorSpace`. Default anchor is **top-left**; use `anchorX/anchorY: 0.5` to centre on `x,y`. A text layer has one animatable number, `value`, printed where the text contains `{value}` (`text: '{value} users'`, `initial: { value: 0 }`, keyframe `to: { value: 2480 }`; `format: { decimals, grouping, pad /* zero-pad the whole part: pad 2 → 05 */, time: 'hh:mm:ss'|'h:mm:ss'|'hh:mm'|'mm:ss'|'m:ss' /* the value in SECONDS as a clock */ }`) — that is how counters work. **Changing text:** a keyframe `set: { text: 'Two' }` swaps the string at that time (undone on seek back; `to` / `from` cannot tween a string); `visibleChars` (number, first N characters; starts at 0 once animated) is a typewriter: `to: { visibleChars: 30 }, duration: 2.4, ease: 'none'` — use `anchorX: 0` + `style.align: 'left'` so it grows rightward. Multi-line text is centre-aligned by default (`style.align: 'left'` to change). **Colour inside one line:** `spans: [{ text: 'type', fill: '#7fa07f' }, ': ', { text: "'a'", fill: '#ffd166', fontWeight: '700' }, ',\n next line']` instead of `text` (strings use the layer's `style`; a span changes only fill / fontWeight / fontStyle / fontVariant / letterSpacing / dropShadow, never a size, font or stroke (those are the layer's `style`); `\n` starts a line; `style.align: 'left'` for code; `visibleChars` types over all the spans; it becomes a group of text layers `<name>.0…`).

**image** — `asset`, `tint`, `colorSpace: 'rgb'|'oklab'|'oklch'`, `scaleMode: 'nearest'` (hard square pixels when scaled up: pixel art; default `'linear'`, smooth; it belongs to the asset). Default anchor top-left; natural size = `w`,`h`.

**video** — `asset`, `loop`, `audio`, `volume`, **`speed`**; `initial: { scale: 'cover' }`. `speed: 0.5` slow motion, `speed: -1` backward (it starts at |speed| × `duration`, so a 3 s file with no `duration` plays whole, backward); with no `duration` the layer lasts the file's length ÷ |speed|. For anything that is not one straight speed — a freeze, a ramp, a loop — animate **`time`** (seconds in the file) like any property: `keyframes: [{ at: 0, from: { time: 0 }, to: { time: 2 }, duration: 1 }, { at: 1, to: { time: 2 }, duration: 0.5 }, { at: 1.5, to: { time: 6 }, duration: 3, ease: 'power2.inOut' }]` (play 2 s, hold, then accelerate). `repeat` loops it, `yoyo` ping-pongs. `speed` itself is not animatable (it warns): animate `time`. The sound follows (pitch too, like a tape).

**audio** — a file: `asset`, `loop`, `volume`, `speed` (the pitch follows; `time` keyframes work as for video; not for `sfx` / `music`: change an sfx's `pitch` instead, or put it in a composition and remap that); `volume` (top level, or in `initial` like every other layer's starting values); fade with volume keyframes (`{ at: -2, to: { volume: 0 }, duration: 2 }` fades the last 2 s). Omit `duration` for a one-shot clip: it lasts exactly as long as the clip. With `loop: true` and no `duration` it lasts until the composition ends. An explicit `duration` longer than the clip goes silent after the clip unless `loop: true`.
**Or a sound effect with no file — `sfx`:** `{ type: 'audio', sfx: 'swoosh', at: 2 }` is the whole thing. Presets, default length in s: `click` 0.04 · `pop` 0.12 · `swoosh` 0.5 (loudest 0.16 s in, moves left → right) · `swipe` 0.22 · `hit` 0.7 · `riser` 1 (loudest at its END: `at = hit − duration`) · `chime` 1.4 · `beep` 0.16 · `coin` 0.4 · `glitch` 0.35 · `typewriter` 0.06. **The mix's loudness in one line:** `movie.init({ loudness: -16 })` brings the whole mix to -16 LUFS (web video), up or down; `check` says when a mix is quiet. Knobs: `sfx: { preset, pitch /* semitones ±24 */, brightness /* −1 dark … 1 bright */, seed /* another take */ }`. **The layer's `duration` IS the sound's length** (omit it; set it to stretch, e.g. a riser; at most 10 s); `volume` is its level (1 = the preset's standard level, peaking at −12 … −18 dBFS by preset; above 1 is allowed: a sparse track of clicks measured −32 LUFS at 0.5 and needed about 2 to reach −24 LUFS). No `loop`: one layer per hit (a JS loop). Custom sound: `sfx: { voices: [{ wave: 'noise' | 'sine' | 'square' | 'saw' | 'triangle', freq: 440 | [from, to], filter: { type: 'lowpass' | 'highpass' | 'bandpass', freq: [from, to] }, envelope: 'fall' | 'bell' | 'swell' | 'hold', pan: [-1, 1] }] }`. The export (mp4 / webm / mov) encodes this same mix (lossy AAC / Opus), on time within a few ms.
**Or music with no file — `music`:** `{ type: 'audio', music: { bpm: 96, tracks: [{ inst: 'keys', notes: 'Cmaj7:4 Am7:4 Dm7:4 G7:4' }, { inst: 'bass', notes: 'c2:2 g1:2 …' }], drums: { kick: 'x...x...', snare: '....x...', hat: 'x.x.x.x.' } } }` — a tune written as text (notes in LOWERCASE `c4:2` in beats, chords start with a CAPITAL `Am7` `G7` `C@4` `Am7/e` (`g7` is a very high note, not G7), `[c4 e4 g4]`, rest `_`, hold `~`, `!` accent; `|` ignored). Instruments `keys pluck pad bass sub lead bell musicbox`; drums `kick snare hat openhat clap rim tom crash shaker sleigh` as 16th-note step strings (`x` hit, `o` soft, `.` none; a list of `{ from, to, … }` for sections). Score options `bpm` (or `[[beat, bpm], …]` for a ritardando) `meter` (beats in a bar, default 4: names the bars in `check`'s read-back, no effect on the sound) `swing reverb (0–0.6) humanize drumVol grid transpose tail seed`; track options `vol` (or `[[beat, level], …]` for a fade) `pan step strum legato tone reverb attack release ring transpose`. A plain capital letter is a major chord (`G`, `Bb`, `F#`; `Ebmaj7`, `F#m7`), `E5` is root and fifth only (e3 b3), every chord token is struck again (`~` holds), a track can start late with a rest (`_:32 e4:1 …`), `f#3` / `bb2` are sharps and flats, c4 is middle C, chord names are voiced around octave 3 (good ranges for notes: bass c1–c3, keys / pluck c3–c6, pad c2–c5, lead c4–c6, bell c5–c7). **Drums repeat by themselves** (one bar is enough) and `drums: { from: 32, to: 64, … }` counts BEATS, not bars (`drums` is one object, or a list of them for sections). `check` reads the score back (bars per track, what starts in each bar and on which beat: `Am(2)`; drum span): trust that over counting by hand; `await musicEvents(music)` gives the same as data. Lasts its notes + tail, ends with the movie, `loop: true` repeats; peaks −6 dBFS at `volume: 1`. `await musicEnvelope(music, { frameRate })` → an envelope for `react()`; `await musicBuffer(music)` → a Web Audio `AudioBuffer` to play yourself.

**shape** — `shape: 'rect' | 'circle' | 'ellipse' | 'arc' | 'line' | 'polygon' | 'path'`:

| shape | geometry (top level **or** in `initial`) |
|---|---|
| rect | `width height cornerRadius anchorX anchorY` |
| circle | `radius anchorX anchorY` |
| ellipse | `radiusX radiusY anchorX anchorY` |
| arc | `radius innerRadius startAngle endAngle` — degrees, **0° = 3 o'clock, clockwise**; centred on `x, y`; stroke only = an open arc line (`strokeCap: 'round'`), with a fill = a sector, with `innerRadius` = a donut slice; a sweep ≥ 360° = a full circle. A progress ring: `startAngle: -90` and animate `endAngle` from −90 to 270 |
| line | `from: [x,y]  to: [x,y]` — plain canvas coordinates (omit `x,y`; if you give them they place the line's midpoint). Stroke in `initial`: `strokeColor`, `strokeWidth` |
| polygon | `points: [[x,y],…]  open` — canvas coordinates like `line` |
| path | `d` (SVG path data) — canvas coordinates like `line`; leave `x` / `y` out and it sits where `d` says; give them (even `y: 0`) and they place its MIDDLE, not an offset (measured: `y: 0` put a square's centre on the top edge). **Holes:** several sub-paths are each filled alone (a donut written as two circles is a disc) unless `fillRule: 'evenodd'`: the biggest is the shape, the others are holes. **Morph:** `morphTo: 'M…Z'` + animate `morph` 0 → 1 (points half way between, closed outlines lined up so they do not twist; `morphPoints` 8–2048; two outlines with the same number of corners are paired corner to corner, so a quad stays a sharp quad) |

**Draw-on:** every shape but `arc` has `trimStart` / `trimEnd` (0–1 of the outline, default 0 / 1, animatable): `trimEnd: 0` + keyframe `to: { trimEnd: 1 }` draws a line / border / path on; `trimStart` 0 → 1 after it wipes it off; both = a travelling dash. The fill is NOT trimmed. Rect outline starts top-left, circle / ellipse at 12 o'clock, both clockwise. A `path` with several sub-paths walks them in order as one length; `trimEach: true` trims each on its own (all draw on together). Use `strokeCap: 'round'`. **Dashes:** there is no dash option; write the outline as alternating sub-paths (`d: 'M 0 0 L 10 0 M 20 0 L 30 0 …'`, or sample the curve) and `trimEnd` 0 → 1 walks them in order, so the dashes draw on one after another (as in `route-atlas`).

Style (`initial` / keyframes): `fillColor fillAlpha strokeColor strokeAlpha strokeWidth`; `colorSpace: 'oklab'|'oklch'` for clean colour tweens. rect/circle/ellipse are **centred on `x,y` by default** (`anchorX/anchorY` default 0.5): for a bar growing from its base use `anchorY: 1` (or `anchorX: 0` for left-to-right). **`fillGradient`** (top level or `initial`; instead of `fillColor`): `{ type?: 'linear'|'radial', stops: [[0, '#000'], [1, 'rgba(0,0,0,.6)']], angle? /* linear, deg; DEFAULT 90 = top→bottom, 0 = left→right: a wide gradient slid sideways as a matte needs angle: 0 */, center?, innerRadius?, radius? /* radial, 0–1 of the SHAPE's own bounds, not the canvas: a glow on a 1500 px circle is placed with fractions of that circle */ }` — stops may have alpha, so a radial transparent→dark is a vignette. **Animate it** with a partial gradient in a keyframe (`to: { fillGradient: { angle: 360, stops: [...] } }`: keys you leave out stay; the same number of stops; `type` cannot change; a start gradient is required; use `colorSpace: 'oklch'` for a vivid fade). A text layer takes `fillGradient` too (LINEAR only: angle and stops; type / center / radius are ignored with a warning; letters re-rasterised per change). `from` alone runs from that gradient to the layer's own. The names `'fillGradient.angle'` / `gradientAngle` are not properties: write `fillGradient: { angle }`. Stroke ends and corners: `strokeCap: 'butt'|'round'|'square'`, `strokeJoin: 'miter'|'round'|'bevel'` (top level or in `initial`; not animated — `round` keeps sharp corners like an M from poking out).

**composition** — `width height duration sequences transitions`, **`speed`** (the composition's own time: its content plays backward, in slow motion, … — `time` keyframes give a freeze, a rewind, a ramp; a composition's sound and sfx follow; its own x / alpha keyframes stay in the outer time; **children are placed in the composition's local seconds**; the content is as long as the larger of `duration` and the farthest `time` it reaches (`speed: 2` → twice `duration`; `time` keyframes → their largest number), and children default to that length. A child whose life ends exactly where a held `time` stands is hidden during the hold (a life is [at, at + duration)): give it a `duration` that reaches past. `time` keyframes and ordinary ones (`x`, `alpha`, a `wiggle`) may share one `keyframes` list. A sound inside goes silent while the clock stands still). With `threeD: true` it is a **card**: its children are drawn into one texture (content outside its `width × height` is clipped: size it for a soft shadow too; a plain 2D composition does not clip, but is skipped when its whole rectangle is off screen) and move / rotate in depth together. Children use the composition's local coordinates and times. Position/rotate/scale it as a unit; to rotate/scale about its centre set `pivotX/pivotY` to the centre and `x/y` to where that point should sit.

**canvas** — `{ type: 'canvas', width, height, draw: (ctx, t, info) => { … }, setup?, params?, seed?, resolution?, smoothing? }`: a picture drawn by YOUR function of the time into the layer's own cleared canvas (`t` = the layer's seconds; `info` = `{ frame, duration, progress, width, height, resolution, frameRate, params, state, random, start, time, canvas }`: `time` is the MOVIE's seconds (`start + t`; share it between layers instead of adding `at` by hand), `canvas(w, h)` an offscreen canvas for sprites and masks made in `setup`). It is a normal layer (initial, keyframes, mask, filters, blendMode …); `params` are numbers keyframes animate as `'params.x'`; no `Math.random` / `Date.now` (`info.random()` is seeded); a simulation is computed in `setup` and read by `info.frame`; it cannot see what is below it. Data several canvas layers share lives in module scope; `import { ease, noise, noise2, random, rand, samplePath } from 'pixi-effects'` for easing by keyframe name, seeded noise and a path walked by length (`samplePath(d).at(u)` / `.trim(a, b)`). `check` draws it twice per moment (one draw thrown away first) and reports a picture that differs, with how much; it prints a `canvas` line when all pass and does NOT see text drawn in a canvas.

**shader** — `{ type: 'shader', fragment: 'void mainImage(out vec4 fragColor, in vec2 fragCoord) { … }', uniforms: { speed: 1, tint: '#ff8040', pos: [0.5, 0.5] }, width?, height?, resolution?: 0.5, transparent?: false }` — a Shadertoy fragment shader drawn into a layer (GLSL ES 3.00): `iResolution` `iTime` (the layer's own seconds) `iFrame` and your uniforms are declared for you; keyframes move uniforms as `'uniforms.speed'` and components as `'uniforms.tint.0'`; opaque unless `transparent: true`; it cannot read what is behind it (no `iChannel` / `iMouse` / `iDate`); no `while` or non-constant `for`; a compile error is reported in your own line numbers and the layer is a checkerboard.

**null + `parent`** — `{ type: 'null', name: 'rig', initial: { x, y }, keyframes: [...] }` draws nothing; layers with `parent: 'rig'` are drawn inside it and follow its `x y rotation scale skew alpha pivotX pivotY`. Their `x / y` are measured **from the null's origin** (null at (640,360), child `x: 200` → drawn at 840), so rotating the null makes the child circle it. Nulls chain (`parent` on a null). Children are drawn at the null's place in the stack, together. Only `null` layers can be parents; not for `threeD` layers; a mask follows its layer.

**camera** (2.5D) — props in `initial`/keyframes: `x y z lookAtX lookAtY lookAtZ fov focus aperture` (defaults: centred, looking at the z = 0 plane, `fov` 40, `z` auto = `(H/2)/tan(fov/2)` ≈ 989 at 720p). **Depth of field:** `focus` = the sharp plane (a `threeD` layer's name = its first z, or a z number), `aperture` = the lens diameter in px (30 default, 0 off); writing either blurs the other `threeD` layers by their distance from the focus (a rack focus is a keyframe on `focus`; recipe `rack-focus`; `inspect` reports `depthBlur`, and `check --at 2.4` prints each layer's blur). A dolly with no typed distance: leave `z` automatic and animate `offsetZ`. Never on the camera object itself. An orbit is `orbit()`; by hand: `x = cx + R·sin θ`, `z = R·cos θ`, `R = (H/2)/tan(fov/2)`, `lookAt` = the centre at `z = 0`.

**three** (optional entry `pixi-effects/three`) — `three({ type:'three', width, height, setup(ctx) { …; return { objects: { knot } } }, update?, dispose? })`; drive with `'three.knot.rotation.y'` keyframes. Call `registerThree()` before `init`. **In the composition's space:** `followCamera: true` (the layer's PerspectiveCamera is the composition's `camera`; the scene is in composition px with y flipped: the composition's `(x, y, z)` is `(x, -y, z)`; give the layer the composition's size), `followLights: true` (the `light` layers become three lights) and `followFog: true` (the camera's fog becomes the scene's `Fog`: close to, not equal to, the card fog); a light's `castsShadows` casts in three (mark your meshes `castShadow` / `receiveShadow`); `ctx.space` has the raw numbers. **glTF:** `import { threeGltf, threeFrameCamera } from 'pixi-effects/three'`: `const m = await threeGltf(url, { animation: 'Run' | 0 | false, speed, offset, loop })` in `setup` (`ctx.scene.add(m.object)`; `m.fit(px)` scales the longest side to px; `m.clips` names the clips), `update: (t) => m.pose(t)` (a function of t: never `mixer.update(dt)`), `threeFrameCamera(ctx.camera, m.object)` frames the whole model from a three-quarter view. Needs `"three/addons/"` in the import map. Recipe `gltf-in-space`.

## Camera flight and a camera shake

`...cameraPath({ points: [[x, y, z], …], duration, ease, look: 'ahead' | [x, y, z], lookAhead: 0.08, smooth: true, from, to, frameRate })` → camera keyframes (`x y z lookAtX lookAtY lookAtZ`) along a smooth curve at even speed (`ease: 'power2.in'` accelerates). A handheld shake goes on the camera's **offsets** so it never collides with the move: `...wiggle({ duration, props: { offsetX: { around: 0, amp: 5 }, offsetY: {…} } })` (`offsetX/Y/Z`, `lookOffsetX/Y/Z` are added to the position and the look-at point). A threeD layer the camera passes on purpose: `hideBehindCamera: true` (hidden quietly behind the camera, no warning). Recipe `camera-fly-through`.

## 2.5D in one paragraph

Add `threeD: true` to any visual layer, then use `z`, `rotationX`, `rotationY` (centre rotation with `anchorX/Y: 0.5` or `pivotX/Y`). Add a `{ type: 'camera' }` layer for a view. A `threeD` layer at `z: 0` with the default camera looks identical to a 2D one. Consecutive `threeD` layers are drawn farthest-first (equal `z` keeps array order); non-`threeD` layers ignore the camera and keep array order. Layers at/behind the camera plane are hidden. Not supported on `threeD` layers: masks, transitions, `filterArea`. **Light:** `{ type: 'light', kind: 'ambient' | 'point' | 'spot' | 'parallel', falloff?: 'none' | 'smooth' | 'inverseSquare', castsShadows?, initial: { x, y, z, lookAtX, lookAtY, lookAtZ, intensity, color, coneAngle, coneFeather, radius, falloffDistance, shadowDarkness, shadowDiffusion } }` lights every `threeD` layer of the composition (`lit: false` opts out; what no light reaches is black, so add `kind: 'ambient'`); a shadow needs `castsShadows: true` on the light AND on the layer (hard by default, `shadowDiffusion` softens; up to 4 casters per receiver). **Fog:** camera `initial: { fogNear, fogFar, fogColor, fogAmount }` (any one turns it on).

## Poster

`movie.init({ …, poster: 9.5 })` names the moment (seconds; negative = from the end) that stands for the movie: the canvas shows it before play (the playhead stays at 0, play starts from 0), `movie.poster` / `movie.posterFrame` read it, `await movie.posterImage({ as: 'dataURL', type: 'image/jpeg', scale: 0.5 })` is the picture. Pick the most striking moment, not frame 0 (which is often black).

## Player

`new Controller(movie, { canvas, theme: { accent: '#ff4d6d' } })` (import from `pixi-effects/controller`; theme keys `accent foreground track barBackground trackHeight font`, or CSS `--mc-accent` …; `controller.setTheme(…)`). Your own player: `movie.play() pause() gotoFrame(f) volume muted toggleMute()`, state `currentFrame totalFrames frameRate duration isPlaying`, events `ready frame play pause ended seeking seeked volumechange error progress` (`<video>` names).

## Filters by name (no import)

`filters: [{ type: 'glow', name: 'halo', outerStrength: 3, color: '#ffd166' }]` — `type` = the pixi / pixi-filters class name without `Filter`, camelCase, or this library's own **`warp`** (bends the picture: `{ type: 'warp', kind: 'wave' | 'haze', strength: 6 (px), scale: 80 (px), speed: 0.5, angle: 0, seed: 0 }`; `wave` = a travelling wave, `haze` = drifting noise; moves with the frame's time by itself; options animate by name) or **`grain`** (film grain: `{ type: 'grain', amount: 0.08, size: 1.5, seed: 0, fps: 24, color: 0 }`, seeded, new every 1/fps s, mid-tone weighted, same grain pattern on every GPU (values within 1/255), anchored to the filter's frame (it moves with a layer), no pixi-filters needed; on a layer or on `composition.filters`; it costs video bitrate; `noise` is NOT film grain: it is frozen and lifts blacks) (`glow dropShadow outline blur noise alpha adjustment hslAdjustment grayscale pixelate crt rgbSplit oldFilm glitch bulgePinch twist zoomBlur kawaseBlur radialBlur motionBlur emboss ascii colorOverlay advancedBloom bevel dot crossHatch tiltShift …`), the other keys are its options. `colorMatrix` takes `preset: 'sepia'|'grayscale'|'negative'|'polaroid'|'technicolor'|'vintage'|'kodachrome'|'browni'`. Name it to animate: `'filters.halo.outerStrength'` (scalars only; `pixelate` via `sizeX`/`sizeY`). Options: `glow` distance outerStrength innerStrength color alpha · `dropShadow` offset{x,y} blur alpha color · `outline` thickness color · `blur` strength · `adjustment` gamma contrast saturation brightness · `hslAdjustment` hue lightness saturation · `pixelate` size · `crt` curvature lineWidth noise vignetting · `rgbSplit` red/green/blue {x,y} · `oldFilm` sepia noise scratch vignetting · `glitch` slices offset · `twist` radius angle offset · `bulgePinch` center radius strength · `zoomBlur` strength center innerRadius · `colorOverlay` color alpha · `colorGradient` gradientType('linear'|'radial'|'conic') stops[{offset,color,alpha}] angle · `colorReplace` originalColor targetColor tolerance · `convolution` matrix(9) · `shockwave` / `godray` are driven by `time` (animate it) · `colorMap` / `simpleLightmap` need a texture (use `custom`). **Centres/offsets are CANVAS pixels** (default top-left corner): put them on the layer. Glow / shadow / blur draw outside the layer: widen `filterArea` (not for `grayscale` / `oldFilm`, which fill the margin black). Full table: https://yjmtmtk.github.io/pixi-effects/docs/dsl.md → Named filters.

## Transitions (on the parent composition)

```js
transitions: [{ kind: 'crossfade' | 'wipe' | 'iris' | 'slide' | 'dip' | 'zoom' | 'dissolve' | 'luma',
                from: 'nameA', to: 'nameB', at: 3, duration: 1, ease: 'none',
                direction: 'left|right|up|down' /* wipe, slide */, mode: 'in|out' /* iris, zoom */,
                smoothing, fromScale /* zoom */, scale, seed /* dissolve */,
                map: 'linear' | 'diagonal' | 'radial' | '<grayscale image asset>', softness, flip /* luma */ }]
```
`from`/`to` are sibling layer `name`s, `to` declared after `from`, and both layers must be alive for the whole window (overlap them by `duration`). Only those two layers are affected; every other layer stays put. Wipe/iris/dissolve/zoom wrap the layers for you.

## Presets

```js
import { kenBurns, withFade, wiggle, stagger, followPath, cameraPath, particles, audioEnvelope, bpmEnvelope, musicEnvelope, react, random } from 'pixi-effects';
kenBurns({ asset, name, at, duration, motion: 'still'|'scale'|'rotation'|'position',
           fit: 'cover'|'contain', ease, /* scale */ origin, zoom, direction, /* rotation */ angle, /* position */ from, to })
withFade(spec, { in: 0.5, out: 0.5 })   // alpha fade; `out` needs spec.duration
orbit({ duration: 6, degrees: 40 /* , radius, center, start, fov, ease, at */ })   // a camera layer that circles a point
// a seeded shake as keyframes (spread into a layer's keyframes); each prop moves on its own; ends back at `around`
keyframes: [...wiggle({ duration: 6, freq: 4, seed: 3, props: { x: { around: 'GW/2', amp: 6 }, rotation: { around: 0, amp: 1.5 } } })]
stagger(8, { each: 0.08 /* or amount: total s */, from: 'start'|'end'|'center'|'edges'|'random'|index, grid: [cols, rows], ease, seed })   // → delays [0, 0.08, …]: `at: 1 + d[i]`
stagger(layers, { each: 0.05, from: 'center' })   // → the same layers with `at` pushed back (originals untouched)
keyframes: followPath({ d: 'M 120 560 C 360 120 920 120 1160 560', duration: 4, ease, orient: true /* faces the way it goes; rotate: -90 for an up-pointing image */, from: 0, to: 1, frameRate: 30 /* = the movie's */ })   // x / y (and rotation) along an SVG path; give the layer its own `at`
...particles({ count: 90, at: 2, emit: 0 /* 0 = burst; or seconds to spread births */, life: [1, 1.8], area: { x: 640, y: 330 /*, width, height */ }, angle: [0, 360] /* 0 right, 90 down, −90 up */,
               speed: [120, 420], gravity: 240, wind: 0, drag: 1.2, sway: { amp: 30, freq: 0.6 }, size: [2, 4.5], scale: [1, 0], fade: { in: 0.2, out: 0.6 },
               colors: ['#ffd166', '#ff6b9d'], shape: 'circle'|'rect'|'star', spin: [-200, 200], blendMode: 'add', seed: 1, name: 'burst', template: { type: 'image', asset } })   // seeded layers, paths baked into keyframes
// a presentation: stops pause playback (`composition.stops: [2, { at: 5, page: 'Name', notes, advance, pdf }]`; `pdf: true` = the stop that pictures its page in a PDF, `pdf: false` = keep it out; default the page's last stop; a `page` stop begins a page, the others are steps); deck() lays pages out
await movie.init({ canvas, width, height, frameRate, ...deck({ transition: { kind: 'slide', direction: 'left', duration: 0.6 },
  pages: [{ name: 'Hello', duration: 3.2 /* last stop + transition */, stops: [2.6] /* page-local */, notes, sequences: [ /* page-local time; a step = a layer starting at the previous stop */ ] }] }) });
new Presenter(movie, { canvas });         // import { deck, Presenter, next, prev, … } from 'pixi-effects/present' (an import-map line of its own): → ↓ Space Enter click = next, ← = back, Home / End, number+Enter, B / W, F, ?
next(movie) / prev(movie) / goToStop(movie, i) / goToPage(movie, n) / movie.stops / onStop(movie, fn)   // (from 'pixi-effects/present'; the core has movie.playUntil(seconds)) Controller: marks on the seek bar, play / Space / click = play to the next stop (pauseAtStops: false = straight through), a Present button, PDF in the download panel
// Presenter extras: G = page overview (pictures), P = presenter view (a second window: live picture, next picture, notes, timer); start() makes the pictures before the audience sees anything
await stopImages(movie, { as: 'dataURL', scale: 0.25 }) // [{ stop, page, image }] one per page (its last stop); { which: 'stops' } one per stop (a page's picture honours `pdf` flags)
await inspectStops(movie)                              // { stops, issues }: stops whose picture is still changing (a stop landing before its animation ends); the check lists them
await exportPDF(movie, { title })                      // Blob: a PDF page per page of the deck; CLI: pixi-effects render talk.html -o talk.pdf (--all-stops)
const env = await audioEnvelope('music.mp3', { frameRate: 30 })   // BEFORE movie.init: .series.level|bass|mid|treble (0–1 per frame), .beats [s], .bpm, .at(t, band); bands: { name: [Hz, Hz] }
const env = bpmEnvelope(120, { duration: 12 })                     // no audio file: kick / snare / hats exactly on a tempo
keyframes: react(env, { duration: 12, props: { scale: { base: 1, amount: 0.4, band: 'bass', attack: 0.02, release: 0.2 }, alpha: { base: 0.4, amount: 0.6, beats: true, decay: 0.15 } }, audioOffset: 0, loop: false })
const r = random(7); r(); r();      // a repeatable stream in 0…1 for JS loops (never Math.random())
```
`kenBurns` covers the canvas, so source images should be at least canvas-sized (1920×1080 for 1280×720).

```js
import { measureText, splitText, animateText } from 'pixi-effects';   // text layout helpers (measured with the renderer's own fonts)
measureText('Hello', style)                              // → { width, height, lines }
splitText('Hello world', style, { by: 'chars' | 'words' | 'lines', x, y, align: 'left' | 'center' | 'right' })
                                                         // → [{ text, x, y, width, index, line }] — one text layer per piece, same style, anchor top-left
```
Per-letter / per-word / per-line animation in one call: `...animateText(text, style, { x, y, align, vertical: true /* tategaki: down a column, new line = new column to the left, x = RIGHT edge of the first column; 、。 ー 「」 placed and turned for you */, by: 'chars'|'words'|'lines', at, duration /* required: until the last piece is gone */, in: 'rise'|'drop'|'fade'|'pop'|'zoom'|'slide'|'spin'|{ from, to, duration, ease }|false, out: <same, in the same wave (leave `out` out and the pieces stay until the layer ends); by default BACKWARDS FROM THE LAYER'S END (at + duration, so to be gone at time T set duration = T − at); `out: { preset: 'fade', at: 6 }` starts the exit at composition second 6 instead>, stagger: { each, from, … }, idle: { y: 4, rotation: 1 }, styleFor: p => ({ fill }) })` → text layers `<name>-0…` (anchor centre; `x`/`y` in `from` are offsets) to spread into `sequences`. **`x` / `y` are pixel NUMBERS (an expression like `'GW/2'` throws: compute `W / 2`), and `y` is the TOP of the line box**: the visible text is centred `lineHeight / 2` below it, so an underline goes at `y + lineHeight`, not at `y` (recipe `animate-text`). By hand: `splitText(...)` + one layer per piece (recipe `split-text`). A web font must be loaded before measuring.

## Assets

`assets: [{ name, src }]` in `movie.init` (images, audio, video). `src` may be a URL or a `data:`/`blob:` URL (e.g. `canvas.toDataURL()`).

## Movie API

```js
const movie = new Movie();
await movie.init({ canvas, width, height, duration, frameRate, background, assets, composition });
movie.play(); movie.pause();
await movie.gotoFrame(n, true);                 // seek (frames; 30 fps => t = n/30)
const blob = await movie.render({ format: 'mp4' });   // 'mp4' | 'webm' | 'mov' | 'mkv'; ~real-time. `format: 'wav'` / `'ogg'` writes only the movie's SOUND (a `music` score as an audio file). `video: { codec: 'hevc' | 'av1' | 'vp9' | 'avc', bitrate: '8M', hardware, keyFrameInterval }` (a codec this browser cannot encode names the one that works). Part of it: `range: [2, 5]` (seconds) or `range: 'title'` (a top-level layer's span; picture and sound); `scale: 0.5` / `draft: true` (half size, low quality, no motion blur: a smaller file, not a faster drawing). Fast motion: `movie.init({ motionBlur: true })` (8 samples, 180° shutter; or a number / { samples: 2–64, shutter: 0–1 }) blurs render / snapshot / contactSheet, not live playback; a render takes `samples`× as long
movie.on('progress', e => e.progress /* 0–100 */);
await movie.setVars({ shift: 40 });              // declared variables → build again, same frame, sound mixed again only if it changed. `resize(w, h)`, `rebuild({ composition, vars, width, height })`; `movie.on('rebuilt', report => …)`; `movie.vars`
movie.loop = true                                // (or init({ loop: true })) playing goes back to the start at the end instead of stopping; the Controller bar has a loop button (L). playUntil() and render() ignore it
movie.audioBuffer                                // mixed audio (after init), if any audio layers
await movie.contactSheet({ count: 6, as: 'dataURL' })   // ONE image of several labelled frames — look at it. Options: frames | times | count, columns, cellWidth, as
await movie.snapshot(60, { as: 'dataURL' })             // one frame, canvas only (no player bar) — use it for detail; sheet tiles are small
await movie.inspect(60, { layers: 'none' })             // issues only (default lists the visible layers); text off-canvas / cut off / empty / overlapping text. Name your layers so paths are readable
await movie.onionSkin({ from: 1, to: 3, count: 8, as: 'dataURL' })  // frames overlaid into ONE picture of a movement (later = stronger): path and easing at a glance
movie.pick(x, y, { alpha: 0.1 })                 // alpha: look at the picture, not the box (image / video / canvas layers: a pixel at or below it is not a hit). A three hit can be dragged: `hit.three.grab('floor' | 'wall' | 'screen' | [nx, ny, nz]).move(x, y)` → { point, delta } on that plane; `await movie.redraw()` draws the paused frame again. Recipe `drag-3d`
movie.pick(x, y)                                 // what is under a canvas point at the frame on screen: { name, path, type, kind: 'flat' | 'card' | 'three', local?, three?: { object, point, distance } } or null (pickAll: the whole stack, top first; { only, ignore }); in a click handler: `movie.pick(...movie.canvasPoint(event))`; to ask about another frame: `await movie.snapshot(f)` first
movie.hover({ onEnter: (hit) => …, onLeave: (hit) => …, ignore: ['background'], cursor: true })   // which layer the pointer is over (built on pick; follows a picture that moves under a still pointer); returns the stop function. Drag and drop: recipe `drag-drop`
movie.review({ at: 'title@end' })                 // what `pixi-effects check` looks at, as data: { frames, problems (text cut off, off-canvas, no size), review (text overlaps: look at them), fonts, audio, at }; leaves the movie as it was. `strict: true` makes every issue a problem
movie.resolveAt('3.5, 50%, f120, title@end')      // moments → [{ label, frame }]; a mistake says what could not be read
movie.inspectFonts()                             // { missing: [{ layer, family }] (no font of the list is installed), failed: [web fonts whose file did not load] }
movie.inspectAudio()                             // the soundtrack as numbers; also loudness { integratedLufs, truePeakDb, clippedSamples, silences }, scenes, cues, notes (advice: -14 to -16 LUFS is typical for web video) — — you cannot listen: sources[i] = { layer, start, end, peakDb, sound: { length, peakDb, loudestAt, brightnessHz } } (`peakDb` is the MIX's peak between `start` and `end`, not the layer's own: `sound.peakDb` is the sound's; for a sound inside a remapped composition `start` / `end` span every pass it is heard, forward, backward, replayed, in the movie's seconds), windows (`{ t, rmsDb, peakDb, brightnessHz }` per 0.1 s), issues (limited mix, inaudible / cut-off sounds)
new Controller(movie, { canvas })                // optional player bar (overlays the canvas bottom ~60px; not in the export)
```


<!-- ===== skills/pixi-effects/reference/pitfalls.md ===== -->

# pixi-effects pitfalls — what actually went wrong

Collected by having fresh AI sessions build pieces from the docs alone: first six (kinetic type, news lower-third, slideshow, 2.5D showcase, three.js title, bar chart), then a portfolio of 16 more (items 32 and up), made by three different models. Each entry is a real stumble. **Status**: `fixed` = the library now handles or warns; `docs` = nothing can catch it, so remember it; `hand-roll` = the DSL has no feature, see the workaround.

A good habit that catches most of these: after `init`, read `window.__logs` (see `template.html`) — every pixi-effects warning says what to change.

## Time

1. **Keyframe `at` starts at 0 when THIS layer appears** *(fixed in 0.3.0; earlier versions measured from the composition and failed silently)*. A layer at `at: 2` with a keyframe `at: 0` animates at global 2 s. Negative `at` counts back from the layer's end. A keyframe that starts after its layer ends now warns ("never plays").
2. **A layer's own `at` and a transition's `at` are composition time** (seconds from the parent composition's start). Only keyframes are layer-local.
3. **Layers are hidden, not removed, after `[at, at+duration)`** and keep their last values. Z-order is array order (later = on top). To switch scenes, stack scenes with `at`/`duration`, each starting with an opaque full-screen rect. *(docs)*
4. **Transitions need overlapping lifespans.** Both layers must be alive for the whole window: scene `i` starts at `i·(L−T)`, the transition's `at` is the next scene's start, total = `n·(L−T)+T`. A scene that ends while the transition is still running leaves a gap. *(docs)*
5. **Sound effects need no file at all:** `{ type: 'audio', sfx: 'pop', at }` — the layer lasts exactly as long as the sound. **Audio length of a FILE.** Omit `duration` on a one-shot clip: the layer lasts exactly as long as the file (nothing to measure; the only sample file is `examples/_assets/bgm.mp3`, 6 s). `loop: true` with no `duration` lasts until the composition ends. An explicit `duration` longer than the clip goes silent after the clip unless `loop: true` (`bgm.mp3` is 6 s) and warns. Volume fades work like any keyframe: `volume: 0` + `{ at: 0, to: { volume: v }, duration: 2 }` + `{ at: -2, to: { volume: 0 }, duration: 2 }` (the last 2 s only; `set` is a jump). *(fixed: volume keyframes used to ramp from the previous keyframe's end, so the music faded across the whole piece)*
6. **Snap times to the frame grid (`Math.round(t*30)/30`) when two things must stay locked** (a bar and its label). Drive both from one JS easing function with per-frame `set` keyframes rather than mixing a tween with computed positions. *(docs)*
7. **Pick eases on purpose.** `expo.in` stays tiny until the very end (a "flood" circle never reaches the corners — use a bigger radius and `power2.in`). A zoom transition with `power2.out` looks like a cut because the incoming scene is nearly opaque after 40 %. Default is linear. *(docs)*
8. **`render()` runs in roughly real time** (6 s of 720p ≈ 6 s). Listen to `movie.on('progress', e => e.progress)` (0–100). *(docs)*

## Layout and anchors

9. **Defaults differ by type.** rect/circle/ellipse are centred on `x,y`; text and image are top-left; a composition has no anchor — use `pivotX/pivotY` and set `x,y` to where the pivot should land. For a bar growing from its base use `anchorY: 1` (or `anchorX: 0`). *(docs)*
10. **Shape geometry may be at the top level or in `initial`** (`width height radius anchorX …`). *(fixed: `initial` used to be silently ignored)*
11. **Angles are degrees** — `rotation`, `skew*`, `rotationX/Y` — and `rotation: -0.2` is almost no rotation. *(docs)*
12. **Text**: anchor 0.5 centres the line *box*, not the cap height (an underline under serif or italic text needs ~`0.9·size` below the centre: `0.46·size` touches the descenders of a g or y). Arial Black is ~0.8·size wide per glyph, monospace ~0.6·size; leave ~7 % for hold-scale. `style` accepts any PixiJS TextStyle field: `letterSpacing`, `wordWrap` + `wordWrapWidth`, `lineHeight`, `stroke`, `dropShadow`, `padding`. A glow (`dropShadow` with `blur`) is clipped unless `padding ≥ 2·blur`. *(docs)*
13. **`w` / `h` in expressions** are the layer's own size. For text they now describe the styled text (`x: '-w'` scrolls a marquee fully out). *(fixed)*
14. **Masks live in the parent's coordinate space and do not follow the masked layer.** Reveal by growing the mask's `width` from a fixed edge (`anchorX: 0`); exit by tweening `x` and `width` together; slide the content separately. *(docs)*
15. **`line` / `polygon` / `path` use plain canvas coordinates** when you give no `x,y` (they used to be drawn around (0,0)); with `x,y` those place the shape's centre. Stroke colour and width go in `initial`. A background pill must be sized from its text (~0.58 × fontSize per glyph + padding): `inspect` does not check text against shapes. *(fixed)*
15b. **`filterArea` is in the layer's own coordinates** (origin = its local origin, e.g. a circle's centre), not the parent's. A blurred shape is clipped to its bounding box without it: `filterArea: { x: -(r+260), y: -(r+260), width: 2*(r+260), height: 2*(r+260) }`. `threeD` layers pad automatically. *(docs)*
16. **The player bar overlays the bottom ~60 px of the canvas** in browser screenshots (not in the exported video). `movie.snapshot()` / `movie.contactSheet()` never include it; keep captions above it anyway. *(fixed: use the built-in snapshot tools)*

## Missing features (hand-roll)

17. **Gradients / vignettes**: use shape `fillGradient` (linear or radial, stops may have alpha). Earlier sessions hand-rolled canvas images or dozens of stacked bands. *(fixed)*
18. **Counters**: `text: '{value}'` + animate `value` (with `format`). Other text content cannot change over time. Earlier sessions generated one text layer per number (40+ per bar). *(fixed)*
19. **Loops**: `repeat` (finite) / `yoyo` / `repeatDelay` on any keyframe; infinite repeats are rejected with a warning. *(fixed)*
20. **No per-frame expression time.** Expressions are evaluated once at build. A camera orbit is `orbit()`; a shake or drift is `wiggle()`, travel along a path is `followPath()`, and any other curve (waves, spirals) must be sampled into short linear keyframes (~0.1 s) in a JS loop. **Randomness must be seeded** (`rand(seed)` / `noise(x, seed)` in expressions, `random(seed)` in JS): `Math.random()` makes playback and the exported file disagree. *(partly fixed)*
21. **Per-letter / per-word text is `animateText()` (one call: a layer per piece, a wave in and out) or `splitText()` by hand (one layer per piece, positions measured for you); a group / parent is a `{ type: 'null' }` layer + `parent: 'name'`, no caption-linked-to-slide.** One layer per letter; many layers; seeded random loops (`random(seed)`). *(hand-roll)*
22. **Colour tweens look muddy in RGB** (red→green passes through brown). Use `colorSpace: 'oklab'` or `'oklch'` on the layer. In `oklch`, a nearly grey end (chroma < ~0.08, e.g. `#9a9ab4`) borrows the other end's hue, so grey → yellow no longer flashes through pink. *(docs / fixed)*
23. **Generated images**: `canvas.toDataURL()` as an asset `src` works. Make them ≥ canvas size or `kenBurns` zooms look soft. *(docs)*

## 2.5D / three.js

24. **`threeD` is required** for `z`, `rotationX`, `rotationY` (they warn otherwise). Camera props go in `initial`/keyframes, never on the camera object. `+z` is toward the viewer. *(fixed: warns)*
25. **A layer at/behind the camera plane is hidden** — the default camera sits at `z = (H/2)/tan(fov/2)` ≈ 989 at 720p, fov 40 (≈ 808 at fov 48, lower at higher fov). Keep every layer's `z` below it. *(fixed: warns once)* **It is hidden whole when ANY corner of it passes the camera plane**: a big plane tilted with `rotationX` / `rotationY` (a ground plane, an orbit ring) vanishes as soon as one corner swings behind the camera (the warning then says a corner reaches the plane). Tilt it less, shrink it, or keep the camera clear of its depth range. *(docs / fixed: warns)*
26. **Under a dolly zoom only the `z = 0` plane stays put**; everything nearer balloons and clips. Headline at `z: 0`, near cards `z ≤ ~70`. Perspective also pulls far layers toward the centre: put far cards at the outer x, near cards inward, and keep ~10 % margin for an orbit sweep. `orbit({ dollyZoom: { from, to } })` does both together. *(docs)*
27. **Combining orbit and dolly zoom**: `orbit()` specifies `z`, so it stops following `fov` — write your own `fov` and `z = (H/2)/tan(fov/2)` keyframes for the zoom. *(docs)*
28. **Nearer `threeD` layers sort on top of text** — lay out around them; equal `z` keeps array order. A card (rect + icon + label that move together) is a `composition` with `threeD: true`. A final call-to-action or overlay should be a plain 2D layer (last in the array): it ignores the camera, and fade the 3D scene and headline out before it appears (a dim rect alone leaves them visible). *(docs)*
29. **three.js**: the layer clips at its own rectangle — size it to the area you want and pull the camera back (`z ≈ 5.4` for a radius-1 torus knot at fov 50). Metal needs an environment map (`PMREMGenerator(ctx.renderer)`); `three/addons` is not in the importmap. Route `three` through the importmap so there is one copy. Masks/transitions/`filterArea` are not supported on `threeD` layers. *(docs)*

## Tooling (agent harness)

30. **A scene change must keep the outgoing scene alive until the covering flood / wipe has finished**, and the next scene starts when it is complete; the flood circle must reach the corners (radius ≥ half the diagonal) and use `power2.in`, not `expo.in`. *(docs)*
30b. **Unknown option names now warn** (`contactSheet({ cols: 2 })` → did you mean `columns`; `init({ fps })` → `frameRate`). Layer names show up in `inspect` paths, so give layers a `name`. `inspect` ignores faint (alpha < 0.3) layers and, while a geometry keyframe (x y z scale rotation …) is running on the layer, its `null` parent or its composition, a text crossing the edge on purpose (a marquee, a zoom-through); a fade, a `set` and an x written only in `initial` are no motion, so a cut-off title is reported once it has settled. Pixi may print `[BindGroup] … destroyed while still bound` warnings at `movie.destroy()`: harmless (playback and seeking never warn). *(docs)*
30c. **Look with the built-in tools, not OS screenshots**: `await movie.contactSheet({ count: 6, as: 'dataURL' })` returns one labelled image of the whole animation; `await movie.inspect(frame)` returns every layer's canvas bounds and `issues`. If you do use a browser tool, `screenshot` needs an **absolute path**, macOS `sed -i` needs `''`, and a static server may redirect `/x.html` → `/x` and drop `?query`. Keep the template's `try/catch` around `init` so failures land in `window.__logs`. Check ≥ 5 timestamps including mid-transition. *(fixed: tools built in)*
31. **Check audio with `movie.inspectAudio()`**: every sound measured on its own (`sound.length`, `peakDb`, `loudestAt`, `brightnessHz`), when it plays, loudness and brightness per 0.1 s window, and `issues` (the mix was limited, a layer is inaudible, an sfx is cut off by the end). Decoding a render by hand is no longer needed: `render()` encodes the same mix, on time in mp4 / mov / webm / mkv. *(fixed)*

31b. **A mistyped `ease` now warns** (`ease: 'power3.outt'` → did you mean `power3.out`). It used to run silently as the default ease (`power1.out`), so the motion changed and nothing said so.
31c. **`draft` and `scale` make the file smaller, not the drawing faster** (measured: a 48 s 1080p film exports in about the same time as a draft; the file is 7× smaller). To save time, export a part (`range` / `--range` / `--scene`), look at single moments (`check --no-export --at …`), and keep motion blur off while you iterate.

## Round 2 — found by building 16 portfolio pieces (examples/gallery)

32. **Seeking is safe now** *(fixed)*: a `set` keyframe (counter value, text fill, image tint, shape style) is undone when you seek back before it, and shapes are redrawn before they are culled, so a rect growing from `width: 0` at the left edge draws after any jump seek (contact sheet, snapshot, scrubbing, export). The old workarounds (`width: 0.01`, a one-frame `to` instead of `set`) are not needed.
33. **A mask starts and ends with the layer it masks** *(fixed)*, so its keyframes count from that layer's start. A mask with an explicit `at` keeps composition time. Before, a mask `at: 0` reveal had finished before a layer that appeared at 8 s, and the layer stayed invisible without any warning.
34. **`from` and `from+to` show their start value from the LAYER's start**, not from the keyframe's `at` (as in GSAP and After Effects): a delayed fade-in `{ at: 2, from: { alpha: 0 }, to: { alpha: 1 } }` needs no `initial.alpha`. To keep the current value until `at` and then jump, use `set`. *(docs)*
35. **One `Movie` per page.** Creating a second Movie (for an isolated repro) and destroying it breaks the first (`null.clear`). Reload instead. *(docs)*
36. **Multi-line text is centre-aligned by default** (`style.align: 'left'` for left-aligned paragraphs). *(docs)*
37. **Composition size.** A 2D composition does not clip its children (a child outside `width × height` still draws), but its rectangle is the culling area: if the whole rectangle is off the canvas the group is skipped even when a child is on screen — keep it near what it draws, or canvas-sized. A `threeD` composition (a card) IS clipped at its `width × height` (it is rendered into a texture that size): size it for the soft shadow too. A growing `threeD` shape or text is fine: its texture is resized in place (it used to warn "destroyed while still bound"). *(measured; docs / fixed)*
38. **Under an orbit the side the camera swings toward becomes the NEAR side**: a "far" card at `z: −200` can be drawn bigger than 1× on that side and run off the frame (`inspect` only checks text). Pull those cards inward / lower `z`, and check a frame at the extreme of the sweep. After `orbit()` ends the default camera returns, so to hold the final pose add a camera layer that starts there. Near particles balloon under a dolly zoom: cap particle `z` at about +150, or one becomes a fake full stop. *(docs)*
39. **`fillGradient` stops span the whole unmasked shape**, not the visible part: under a mask, place the stops for the visible fraction (e.g. 0.64→1). A translucent shape over near-black reads as grey: put the alpha in the gradient stops. *(docs)*
40. **Rotate a polygon / path / line about a chosen point with `pivotX` / `pivotY`** (in the shape's own canvas coordinates; put the same point in `x, y`): `{ points, initial: { pivotX: 600, pivotY: 300, x: 600, y: 300, rotation: 180 } }` turns about the vertex (600, 300) — measured. Without a pivot the shape turns about the centre of its bounds. `anchorX` / `anchorY` do nothing on these shapes (they are for rect / circle / ellipse). *(docs; the gallery wrapped every polygon in a composition unnecessarily)*
41. **Glow a whole set of layers** by putting them in one `composition` with a blur filter and `filterArea` (only a composition carries a filter for its children): wide enough for the blur, and the set is built once, so the extra copy is just a second group. *(docs)*
42. **Transition looks:** the default `dissolve` reads as a hard black-and-white camouflage and `scale: 220` as static; `scale: 90, smoothing: 0.5` is a soft film dissolve. The default edge softness of `iris` (0.02) and `wipe` blurs flat graphics at 720p: `smoothing: 0.004`–`0.01` gives a clean edge. *(docs)*
43. **Layers built in a loop need their z-order planned**: anything pushed to the array after the loop is drawn over what the loop made (rings crossed over a header). Keyframes on different properties of one layer may overlap in time. Keep a subject in the upper ~60 % of a source image if a caption will sit under it (`inspect` does not look at picture content). *(docs)*
44. **Zero-pad a counter with `format: { pad: 2 }`** (`18:42:{value}` shows `18:42:05`). A `{value}` placeholder that nothing sets or animates prints 0 and now warns: `{value}` is reserved, there is no way to print it literally. *(fixed)*
45. **The same mistake in a loop warns once**: the warning "keyframe starts after the layer ends" is summarised after three layers. The usual cause is an off-by-one (`f <= frames` instead of `f < frames`) that puts the last sample exactly at the layer's end. *(fixed)*
46. **Still not in the DSL (hand-roll):** `zIndex` (stack order is list order). *(Earlier round-two notes listed draw-on strokes, changing text, jitter and particle emitters here: they are built in now: `trimEnd`, `set: { text }` / `visibleChars`, `wiggle()`, `particles()`.)*
46b. **Blend modes exist now** (`blendMode`: `add` `screen` `multiply` and, since 0.22, 15 more CSS names (pitfalls 78–80), on any layer, threeD layers and compositions included; a composition's children inherit it). Additive white cores no longer read grey on a coloured background. It also works on a layer with `filters` (a blurred glow with `add` / `multiply`): the mode is applied by the last filter, because a container's blend inside a filter pass multiplied against nothing and rendered black. With `add`, use dim saturated colours: overlaps sum, and near-white sums to pure white. *(fixed)*
47. **Browser tooling: prefer `npx pixi-effects check page.html`** — it runs its own private Chrome, so none of the following can bite. If you drive a browser by hand instead: the `agent-browser` daemon is shared, so a `contactSheet` can come back from another session: after saving an image, look at it and confirm it is YOUR piece. In zsh a variable holding `agent-browser --session x` is not split into words (use a small wrapper script). `inspect` now clips overlaps to the visible area, ignores the two scenes of a running transition, treats text inside a moving (panned) composition as moving, and does not report text scaled to 0 as "no size"; it still does not compare text with picture content or shapes.
48. **A composition's `alpha` is applied to each child separately, not to the flattened group** (measured: two overlapping opaque circles in a composition at `alpha: 0.5` show the lower one through the upper one in the overlap). Fading a group that has overlapping children therefore shows the overlap; fade the children themselves, or keep overlapping parts out of the group. Expressions have no way to read a sibling's size: measure text with `canvas.measureText` (the font string Pixi uses) and compute pill widths in JS. *(docs)*
49. **sfx timing and level.** An sfx layer's `duration` is the sound's length (it stretches, it does not trim). Align the loud point: a `riser` peaks at its end, a `swoosh` 0.16 s in. Many sounds at the same instant add up: above 0.9 the mix is limited and a warning names the layers to turn down. Preset names, knobs and voice fields are closed lists — a guess (`whoosh`, `ding`, `impact`, `sawtooth`, `lp`, `decay`) warns with the right word. *(fixed: warns)*
50. **An image (or video) works as a mask, inverted too** *(fixed)*: PIXI hides a sprite mask with `renderable = false` and the lifespan toggles used to switch it back on, so the mask picture was drawn over the layer (a white disc) and an inverted mask looked ignored. Use the picture's alpha (or red channel) as the shape: an opaque word or logo on a transparent canvas image is a text-shaped mask with real glyph edges. A `text` layer also works as a mask (cut to its glyphs; measured with a heavy sans `I`). *(docs / fixed)*
51. **Arcs and rings are `shape: 'arc'`** (`radius`, `innerRadius`, `startAngle`, `endAngle`, degrees; 0° = 3 o'clock, clockwise). A progress ring is an arc with `startAngle: -90` and an animated `endAngle` (−90 → 270); `strokeCap: 'round'` rounds BOTH ends. Fill it for a pie slice, add `innerRadius` for a donut slice (a 120-polygon donut is no longer needed). Style (`strokeColor`, `strokeWidth`, `fillColor`) goes in `initial`; `strokeCap` / `strokeJoin` may be top level. *(fixed)*
52. **Measure and split text with `measureText` / `splitText`, not by hand.** `splitText(text, style, { by, x, y, align })` returns each piece's x / y / width in the renderer's own font metrics (kerning kept; verified: a whole line vs the same line in per-letter layers differs only by anti-aliasing). The pieces are for text layers with the default top-left anchor and the same `style`. Load a web font before measuring (`await document.fonts.load('24px "Name"')`) or the fallback font's widths are used. Size a pill from `measureText(...).width + padding` instead of `0.58 × fontSize × length`. *(fixed)*
53. **Draw-on and typewriter need no masks or per-letter layers.** `trimStart` / `trimEnd` (0–1 of the outline, animatable, every shape but `arc`) draw a stroke on: `trimEnd: 0` plus a keyframe `to: { trimEnd: 1 }`. The fill is not trimmed, so fade `fillAlpha` in afterwards; use `strokeCap: 'round'`. Text changes over time with `set: { text }` (swap at a time) and `visibleChars` (typewriter; left-align it so it grows rightward). A `to: { text }` cannot tween a string and warns. *(fixed)*
54. **A deck page lasts until its last stop plus the transition.** `deck()` lays pages out one after another in page-local time and a `transition` overlaps them: a page shorter than its last stop (or shorter than the transition) loses its final step or flashes. A step is a layer that starts at the previous stop (`at: <previous stop>`), so the thing that appears on a press is fully visible when the movie stops. The transition option is `kind`, not `type`. If the last stop is mid-exit on paper, flag the stop you want in the PDF: `{ at, pdf: true }` (in `deck()`: `stops: [1.2, { at: 3, pdf: true }]`), and `pdf: false` keeps one out.
55. **Presenter and Controller both listen to click and keys.** Use the `Presenter` for a talk (or let the Controller's Present button start one); do not run both on the same canvas yourself. `movie.play()` ignores stops, but the Controller's play button / Space / click-on-picture play to the next stop and pause (`pauseAtStops: false` plays through); `next(movie)` (from `pixi-effects/present`) plays to the next stop (a second press skips to it), `prev(movie)` jumps back (nothing plays in reverse).
56. **Analyse audio before `init`, and give it the movie's frame rate.** `const env = await audioEnvelope('music.mp3', { frameRate })` is async; `react()` is pure and bakes the keyframes, so there is no per-frame callback. A custom `bands` list replaces the defaults (include `bass` if you want it; beats are picked there). No file yet: `bpmEnvelope(120, { duration })` is a stand-in with a kick on every beat. Offset the music with `audioOffset` when the audio layer does not start at 0.
57. **Review a deck by its stops, not by its timeline.** `pixi-effects check` writes `stops.png` (one picture per stop, in order) for a page with `stops`; the picture at a stop is what the audience reads while it waits. A stop that lands a few frames before an animation ends shows it half-finished (also in the PDF): `inspectStops(movie)` / the check's review list names such stops; give an animation a little more time than its step (e.g. the next stop 0.3 s after it ends).
58. **`music` counts BEATS, and every track has to add up.** A token's `:n` is beats (a quarter note), a 4/4 bar is 4: a bar of `c4:1 e4:1 g4:1` is a beat short and every later bar drifts. Keep all tracks the same length (the music lasts the longest; a track of rests `'_:16'` sets a length) and check the printed length with `movie.inspectAudio()`. 6/8 is a bar of 3 beats (dotted quarter `:1.5`, eighth `:0.5`) with `grid: 2`; `grid: 3` is triplet eighths in 4/4.
59. **A groove that must enter late needs `from`, not a long string.** `drums: [{ kick: 'x...' }, { from: 8, snare: '....x...' }]`. Patterns repeat; a drum object is a loop of its longest string. A `crash` on the last bar: its own section `{ from: 28, crash: 'x' }`.
60. **Build-ups are layers and `vol` points, not louder notes.** A track's `vol` can be `[[0, 0], [8, 0.7]]` (a fade over 8 beats); the pad's `attack` can be 2–3 s; enter instruments with rests. Per-note `!` and `,` only accent and soften.
61. **Music is a bed: `volume` 0.5–0.8 under speech or sfx.** At `volume: 1` it peaks at −6 dBFS (an sfx peaks at −12). A layer shorter than the music cuts it with a fade; longer is silent after it unless `loop: true`. Do not also add an mp3 bed.
62. **Chord names are voiced close around octave 3**: use `[c3 g3 e4]` for an exact voicing or `Am7/e` for a bass note; `swing` only moves notes that start on an off-beat eighth (`.5`) or sixteenth (`.75`); the bell and music box ring for `ring` seconds whatever the written length (shorten `ring` for fast bell lines); the synth is a handy bed, not an orchestra: keep tracks to 3–6, vary the bars, and end on the tonic.
63. **`animateText()` / `splitText()`: `x` and `y` are pixel numbers, and `y` is the TOP of the line.** An expression such as `x: 'GW/2'` throws (the letters are measured once, at build time): write `x: W / 2`. The pieces are centred half a line below `y`, so a line drawn under the text goes at `y + lineHeight` (about 1.2 × `fontSize`), not at `y`; look at the contact sheet, the layout check cannot see an underline through a word. (`check` writes into `check-out/` of the current folder unless you pass `--out`.)
64. **`animateText()`: `out: { preset, at: T }` starts the exit at composition second T; without `at` the exit is the end of the layer run backwards.** `duration` is still how long until the layer ends (every piece is gone by `at + duration`): with `out.at`, give `duration` room for the exit and the wave after T (a warning says `out.at ≤ …` when it does not fit, or when T is before the entrance has finished). Without `out.at`, to be gone at time T set `duration: T − at` (title at 0.4 s that must be gone by 8.0 s: `duration: 7.6`). A hand-written exit keyframe works the other way: a negative `at` counts back from the end of its own layer, a positive one from the start of its own layer, never from the movie.
65. **A spring that does not spring, and `'auto'` that is not a spring.** `spring(1,170,26)` is critically damped (damping ratio 1): it never overshoots; at stiffness 170 use damping below 20 (`spring(1, 170, 12)`), or pick a preset (`spring.bouncy`, `spring.wobbly`). With a number `duration`, that number is the settle time (mass and stiffness only matter with `duration: 'auto'`). `duration: 'auto'` needs a spring ease (otherwise it warns and uses 0.5 s) and is for keyframes, not for `animateText` / `orbit` tweens. A colour that overshoots is clamped in its colour space; `alpha` past 1 shows nothing.
66. **Animating a gradient: one `fillGradient` object, partial, in the keyframe.** `to: { fillGradient: { angle: 360, stops: [...] } }` (keys you leave out stay). Not `'fillGradient.angle'`, not `gradientAngle`, not `fillGradient: 'red'` (each warns once with what to write). The layer must start with a `fillGradient`; `stops` keep their count; `type` cannot change. A fade between two colours in the default `rgb` passes through grey (green → magenta): set `colorSpace: 'oklch'`. Under a mask the stops still span the whole shape (see 39).
67. **A key the layer does not have is warned about now (it used to be ignored in silence).** `{ type: 'text', anchorX: 0.5 }` (anchors go in `initial`), `{ type: 'audio', sfx: 'click', pitch: 3 }` (the knob goes inside: `sfx: { preset: 'click', pitch: 3 }`), `{ type: 'shape', shape: 'rect', radius: 5 }` (that is a circle's key; a rect has `cornerRadius`), a mistyped property in a keyframe (`alhpa`), a mistyped text `style` key. The warning names the key, the kind of layer and what was probably meant; fix the key, do not silence the warning. Three gallery pieces had the `pitch` mistake for months: their sound effects were never pitched.
68. **A pitched sfx keeps its own length; a radial gradient is placed in the shape's bounds.** `sfx: { preset: 'chime', pitch: -5 }` lasts as long as the sound does, so near the end of the movie give the layer a `duration` that ends with it (`inspectAudio()` reports a sound cut off by the end). A radial `fillGradient`'s `center` / `radius` are fractions of the SHAPE, not the canvas: for a glow on a big circle, convert canvas pixels to fractions of the circle. `music.reverb` is 0–0.6.
69. **Inside a remapped composition, `at` is in THAT composition's seconds.** With `speed: 0.5` a 4 s composition shows only 2 s of its content; a layer at `at: 3` inside is never seen (warns: "its clock only reaches 0–2s"). With `speed: 2` the content is 8 s long, so children default to 8 s and `at: 5` is fine. The composition's own `at`, `duration`, x / alpha keyframes are outer time. To freeze, hold `time` at one value (`to` the same number); to rewind, `to: { time: 0 }`. A sound inside goes silent while the clock stands still, and an `sfx` longer than the clock's reach is reported as cut off by the clock: give it a shorter `duration` (the sfx limit is 10 s) or let the clock run on. A child whose life ends exactly where a held `time` stands is hidden during the hold: give it a `duration` that reaches past (the content is as long as the larger of `duration` and the largest `time`). **With `time` keyframes the composition's own `duration` is its life in OUTER time and must reach the last keyframe** (`keyframes[1] starts at 2.3s, after the layer ends` means `duration` is too short): `at` of a `time` keyframe counts from the composition's start, the content length is a separate thing that comes out of the `time` values.
70. **`speed` is a setting, `time` is the property.** `speed: 2` on the layer; to change the speed over time animate `time` (a curve of seconds in the file), never `keyframes: [{ to: { speed: 3 } }]` (warns). `speed: 0` is not allowed (hold a moment with `time` to the same value twice); `speed` together with keyframed `time`: `time` wins. Other names (`playbackRate`, `timeScale`, `rate`, `reverse: true`, `timeRemap`) are warned about with what to write. `particles({ speed })` is something else: launch speed in px per second.
71. **Sound follows `speed` like a tape: the pitch moves with it.** An audio file or a video's sound at `speed: 2` is an octave up; backward plays reversed. Not for `sfx` / `music` layers (warns): change an sfx with `pitch` (semitones), or put the sfx **inside a remapped composition** and it follows that clock (slower and lower, or backward).
72. **A video at `speed: 2` with no `duration` is half as long; with a `duration` longer than the file it holds the last frame** (add `loop: true` to repeat). A negative `time` counts back from the end of the file (`initial: { time: -2 }` = two seconds before the end).
73. **Know the shape of the curve before you time a beat to it.** `cubic-bezier(.2, .8, .2, 1)` does half of its change in the first 13 % of the time and 99 % by 74 % (not slow motion: over 6 s the first 2 s of content pass in 0.6 s); `.2, .8, .5, 1` has a shorter tail. `power2` is a cubic (`power1` = t², `power3` = t⁴): `power2.in` has done 12.5 % at half time and 42 % at three quarters, so a rewind with it dismantles most of the title in the last third.
74. **`focus` as a layer name means that layer's FIRST `z`, and the name must be unique.** (Two layers with one name: the first `threeD` one is used and it warns.) The camera does not follow a layer whose `z` moves (it warns): to follow it, animate `focus` itself with numbers. A name no layer has, or a layer that is not `threeD`, warns and the `z = 0` plane is used (did-you-mean for typos).
75. **Depth of field blurs `threeD` layers only, and the layer's own depth decides it.** A 2D layer never blurs; a `threeD` layer at the focus depth stays sharp; the depth is measured along the camera's view direction, so with an orbiting or tilted camera a layer off to the side of the look-at point is a little deeper than its `z` says and blurs a little even at the focus `z`; one blur for the whole layer, so a tilted floor is one blur (split it into layers).
76. **`aperture` is the lens diameter in px, not a 0–1 strength.** 30 is the default (clearly shallow), 0 turns it off, 60 is strong, 100 is extreme (small bright objects speckle); the blur never exceeds 32 px. 20 or more blurred layers at once warns (one filter pass each, more on WebGPU).
77. **A dolly does not need the camera's home distance typed in:** keep `z` automatic and animate `offsetZ` (negative = closer). Writing `z` yourself means typing `H / 2 / tan(fov / 2)` (about 989 at 720p, fov 40; as an expression `H / 2 / tan(20 * PI / 180)`). A bokeh field is a few big cards, not dozens of layers: a card at depth `z` fills the frame at size `(W / s) × (H / s)`, `s = camZ / (camZ − z)`.
78. **A blend mode mixes the layer with everything BELOW it, in the order of the array.** The backdrop goes first, the blended layer after it; a layer placed before its backdrop blends with nothing. Names are CSS names with the hyphen: `soft-light`, not `softLight` (the warning says which you meant).
79. **On a plain `composition` a `blendMode` makes each child blend by itself, not the composition as one picture.** To blend the whole group give the composition `threeD: true` (z 0, default camera: nothing else changes) or a filter. A text, image or video layer as the (not inverted) `mask` cannot carry a blend (it warns, draws normal); a shape mask and an inverted mask work.
80. **`soft-light` / `overlay` do almost nothing over near-black or near-white; `color-dodge` over dark gives a saturated colour, not white; `blendMode` cannot be keyframed** (use a second short-lived layer). **The 14 new modes cost about 2 ms a layer on WebGL; 10 or more on screen at once warns.** A glow, a haze or a colour cast is ONE layer with a gradient (`fillGradient`), not dozens of circles; keep `add` / `screen` / `multiply` for big piles of particles.
81. **A layer named in `mask` is a matte: it is not drawn, and it must be alive whenever the layers it cuts are.** `{ name: 'band', … }` plus `mask: 'band'` on the text hides the band itself; the matte's time is the composition's time (its own `at` / `duration`). Where the matte is missing the layers it cuts are invisible: the build warns when its lifespan does not cover its users. To show the band as well, add a second layer that looks the same.
82. **A `mask` name works inside one composition only.** The matte and the layers that name it are siblings in the same `sequences`. A layer inside a nested composition cannot name a matte outside it (warns, with the closest name if there is one, and the layer is drawn without the matte); a layer that a transition wraps keeps its matte. Put the matte inside the nested composition, or the layer next to it.
83. **`channel: 'luma'` reads brightness, `'alpha'` (the default) reads opacity.** A white shape is 1 for both, a black shape is 0 for luma and 1 for alpha, a grey `#808080` is 0.5 luma. Outside the matte layer's own shape both are 0, so a wide gradient rectangle slid across the layers is a soft moving reveal. Use `luma` with a grayscale image or a gradient layer; use the default for shapes and text. `luminance`, `brightness` and `grayscale` are not channel names: they warn ("did you mean luma?") and alpha is used.
84. **Subtract with `invert: true` in a list; a list multiplies.** `mask: ['panel', { layer: 'hole', invert: true }]` is "inside `panel`, outside `hole`". A mask written in place inverts the same way: `mask: { layer: { type: 'shape', … }, invert: true }` (the old `maskInverted: true` key is gone: it warns and says this). A luma wipe's `map` is a built-in name (`linear` `diagonal` `radial`) or a grayscale image asset; an unknown name warns once and wipes as if the map were white.
85. **One light layer lights every `threeD` layer, and what no light reaches is black.** Add `{ type: 'light', kind: 'ambient', initial: { intensity: 0.2 } }` (a white ambient light at 1 is the same as no light). A layer you want flat-lit is `lit: false`. Layers without `threeD` are never lit, and a light only counts while it is alive (give it the scene's `at` / `duration`): with no light alive the layers are drawn unlit.
86. **A shadow needs `castsShadows: true` on the light AND on the layer.** Either alone shows nothing (the build says which half is missing). The caster has to be a `threeD` layer in front of the receiver (between it and the light); a receiver takes at most 4 casters. A hard shadow can look like a dark slab: `shadowDiffusion: 10`–`20` softens it, and soft shadows cost the most, so use them on one or two lights. A spot's pool on the wall has radius about `distance × tan(coneAngle / 2)` and can hide behind the card that stands in front of it.
87. **The light's numbers go in `initial` / `keyframes`; `kind`, `falloff` and `castsShadows` are on the layer.** `{ type: 'light', intensity: 1 }` warns; so do `target` / `pointOfInterest` (use `lookAtX / lookAtY / lookAtZ`), `angle` (`coneAngle`), `castShadows` (`castsShadows`) and `intensity: 80` (it is a multiplier, 1 = full, not a percentage). A spot needs a look-at point (it defaults to the middle of the picture).
88. **A room is layers in distance order, not geometry.** There is no depth buffer: a floor or wall is a big `threeD` layer whose origin is at its far edge (`anchorY: 0` / a `z` behind what stands on it), and planes that cross cannot be drawn. Each composition has its own lights: a light in a nested composition lights only that composition's layers. Fog is the camera's (`fogNear` / `fogFar` / `fogColor`), fades `threeD` layers only, so draw the background in the fog colour.
89. **A shader layer is written like Shadertoy, in GLSL ES 3.00: `mainImage` and `fragColor`.** Not `void main()`, `gl_FragColor`, `texture2D`, `varying`, `#version` or a `uniform float iTime;` (each warns with what to write). `iTime` is the layer's own seconds from its start (not the movie's), `fragCoord` starts at the bottom left, the colour is opaque unless `transparent: true`, and the layer cannot read what is behind it (it is a layer, not a filter): there is no `iChannel0`, `iMouse` or `iDate` in this version.
90. **`uniforms` are declared for you; keyframes name them `'uniforms.speed'`, and vectors and colours by component `'uniforms.tint.0'`.** `uniforms: { tint: '#ff8040' }` is a `vec3` of 0..1, so animate its channels, not the string. Declare every uniform you animate with a starting value (a keyframe on a name that is not there warns with the likely name). Do not write `uniform float speed;` yourself.
91. **A shader that does not compile is a magenta checkerboard, and the warning has your line numbers.** Fix the line it names. Loops need a constant bound (`for (int i = 0; i < 8; i++)`): a `while`, or a bound that is a variable, can hang the GPU and warns. A heavy shader is cheaper with `resolution: 0.5`; many small shader layers cost more than one big one. A mask or matte cuts what the shader drew, it does not move the pattern: put the pattern's centre (a `vec2` uniform) where the matte is. A shader layer with a small `width` / `height` sits by its top-left corner at `initial.x / y`. With `resolution` below 1 the shader's own pixels are fewer: write positions as `fragCoord / iResolution.xy`, or multiply pixel uniforms by `resolution`. A shader can itself be a mask (`mask: { type: 'shader', transparent: true, fragment }`: its alpha is the mask).
92. **`warp` is for bending a layer's picture, a `shader` layer is for drawing something new.** `warp` takes `strength` in px (a ripple is 4 to 10, over 200 is refused) and `scale` in px; `speed: 0` stands still. It follows the time of the frame by itself: do not keyframe a time. Its options animate by the filter's name (`'filters.ripple.strength'`). For a swirl or a lens use `twist` or `bulgePinch`.
93. **A `threeD` layer's shadow budget is four casters per receiver, counted in layer order, not geometry.** Five letters as five `castsShadows` layers over one floor: the fifth casts nothing (the warning names it). Make the word ONE text layer (the light is per pixel, each letter is still lit on its own) or give only the four that matter `castsShadows`. Splitting the floor does not help: each half takes the first four.
94. **`resolution` below 1 softens crisp lines in a shader.** `fwidth` anti-aliased edges come out a little blurry after the upscale: keep `resolution: 1` for line art and use 0.5 only for soft fields (flowing colour, glow).
95. **A `color-dodge` leak over a dark picture is a muddy red disc.** Dodge divides each channel of near-black separately, red first. Cut the dodge to the bright subject with a matte (`mask: 'letters'`, a matte-only copy of the word) and put the warm haze in a separate `screen` radial.
96. **A filter option that is a point (`rgbSplit.red`, `glitch` offsets) is tweened one leaf at a time** (`'filters.s.red.x'`; the whole point as a value switches, it does not tween), and a scalar too: `set: { 'filters.tear.seed': n }` steps `glitch.seed` (a `set` keyframe works on filter options; no warning, visible tearing). To switch between looks on one subject, put the subject in time-windowed `composition` copies, each carrying the filters of its look.
97. **A deck inside your own composition loses its `transitions` and `stops`** unless you take them across: `const d = deck({ width: 1920, height: 1080, pages })`, then `{ type: 'composition', sequences: d.composition.sequences, transitions: d.composition.transitions }`. Pass `width` / `height` yourself for a page that is not the movie's own size.
98. **A matte layer needs a fill.** A named matte (`mask: 'glass'`) that is a shape with no `fillColor` / `fillGradient` (or a text with no fill) cuts everything away and nothing warns: the layers it should show simply vanish. Give the matte a fill (white for `alpha`, a gradient for `luma`).
99. **In a `music` score a capital letter is a chord and a lowercase one a note.** `G7` is G dominant seventh, `C5` a power chord, `C6` a sixth chord; `g7`, `c5`, `c6` are notes (octave 7 is a very high note: it used to be what `G7` meant, silently). A bare note in capitals (`Bb2`) is refused with the lowercase spelling (`bb2`); inside brackets (`[C4 E4 G4]`) any case is a note. An unknown chord kind suggests the nearest (`Cmin7` → `Cm7`, `Csus` → `Csus4`, `CM7` → `Cmaj7`).
100. **Read the score back before you trust it.** `check` prints a `music` block: every track's length in bars (a track that ends early or has a short bar is named), the names that start in each bar with their beat (`Am(2)` starts on beat 2; no mark = the downbeat; the first four names of a bar are shown, `musicEvents()` lists everything), and the drum span. Count bars by the read-back, not by hand: a bar of 3 beats in a score with no `meter` is shown as bars of 4, so set `meter: 3` for a waltz. Drums repeat by themselves and `from` / `to` are beats; `swing` only moves notes that start off the beat, so a comp on beats 2 and 4 stays straight.
101. **A film built from one adjective looks like every other one.** Read `reference/direction.md` and write `brief.md` / `style-guide.md` / `shotlist.md` first: real assets with paths, the one sentence to remember, a row per beat with entry and exit state. If a real asset is missing, ask: a drawn fake (a logo, a dashboard, a figure) is the failure that matters. Judge the contact sheet cold: three defects, each with a timestamp, evidence and a local fix.
102. **A vertical cut is a second composition, not a crop, and only when someone asked for it.** One source, a layout function, `?f=9x16`; `check` and `render` take `--query f=9x16` (recipe `two-formats`). Look at a contact sheet of each format: type that fits wide is tiny tall. Ask which formats are wanted; make one if the answer is open. In a 1080p film keep every line of text at 34 px or more; if you cannot read it in a sheet tile, a phone cannot.
103. **Load a web font BEFORE you measure with it.** `measureText` / `splitText` / `animateText` measure once, when the composition is built. Measured in Chrome: "Respect the Local, Loop the Value." at 80 px Lato 900 is 1487 px wide before the Google font has arrived (the fallback) and 1231 px after; Japanese text in a similar fallback was within 3 px. Every box, line break and centred position built from the wrong width stays wrong. `await document.fonts.load('900 80px "Lato"', theTextYouUse)` first (the text argument loads exactly the glyphs you need), then build the composition.
104. **A variable moves values, not timing, and it is read when the composition is built.** `at` and `duration` are plain numbers; `vars: { shift }` works in `x: 'W/2 + shift'` and `'{title}'` inside any string, not in `at: 'shift'`. `setVars` builds everything again (about 20 ms, plus the sound only if it changed): for a continuous input call it as often as you like, calls that overlap are joined, but do not use it for something that should move every frame (that is a keyframe).
105. **Layout that follows the screen is written in `W` / `H` / `GW` / `GH`, never in pixels.** After `movie.resize(w, h)` an expression sees the new size; a literal `x: 960` stays at 960. A string variable cannot be read in an expression (`x: 'title'` is a number context): use `{title}` in a string, or declare the number. A name that is declared but never read, and a `{name}` that was not declared, are both said at `init` (usually a typo). Load a web font BEFORE the first `setVars` that changes a text (see 103): the text is measured again each rebuild.
106. **A text outline used to spike; it is round-joined now.** `style: { stroke: { color: '#000', width: 12 } }` was drawn with PixiJS's default `miter` join, so the sharp corners of W, V, A, k and 4 grew spikes ("the outline sticks out"). The library now adds `join: 'round'` to an outline that names no join; say `join: 'miter'` or `'bevel'` if you want one. The stroke is centred on the glyph edge, so half of it eats into the letter: keep `width` to about a tenth of `fontSize`, or for a thick outline put a second copy of the text with the stroke UNDER the plain one.
107. **`spans` places pieces by measuring, so the font must be loaded first, and a span cannot change size.** A web font that is not loaded yet is measured as the fallback font and the pieces drift apart: `await document.fonts.load('30px "Name"')` before `movie.init`. `fontSize` / `fontFamily` / `lineHeight` / `align` on a span are ignored (warned): they belong to the layer's `style`. `fill`, `text` and `value` keyframes do not reach a spans layer (it is a group of text layers).
108. **Japanese and Chinese do not wrap at spaces** (Korean has spaces, so `wordWrap` breaks there). `wordWrap: true` alone does nothing for a long line (it runs off the canvas); `breakWords: true` breaks between any two characters and can leave one to three characters alone on the last line. Break the line yourself with `\n` after a comma or a particle and size the font to fit; `check` reports a line cut by the canvas edge but does not judge an ugly break, so look at the contact sheet. Raising `fontSize` can turn a clean line into an orphan: look again after any size change.
109. **No font is bundled, and each script needs a font that has its characters.** The machine's own fonts are used; characters a font lacks are drawn with whatever the machine falls back to, so the same page can look different on another machine. Load a web font that covers the script (Noto Sans JP, Noto Sans KR for Hangul, Noto Sans SC) with `await document.fonts.load('40px "Noto Sans KR"')` before `movie.init`, and say it in `style.fontFamily` (pitfall 103). `check` lists a layer none of whose fonts is available, but a family that nothing installs or loads is silently replaced by the next one in the list (or the generic name) without a word: the first name in `fontFamily` is not proof it was used.
110. **Right-to-left text: three traps.** `splitText` / `animateText` order words left to right, so Arabic or Hebrew comes out reversed (split by words yourself, from the right edge, with `measureText` of the logical prefix); a mark below the font box can be clipped (the dots of an Arabic ي) unless the layer has `style.padding`; `check` sees neither. `bulgePinch.center` is 0–1 of the layer, not pixels (pitfalls elsewhere say canvas pixels for the other centres: `twist`, `zoomBlur`, `shockwave`). `npx pixi-effects help arabic` and `help bulgePinch` print the sections.
111. **Only some named filters are tested on both backends.** `glow`, `outline`, `dropShadow`, `bevel`, `bloom`, `pixelate`, `crt`, `rgbSplit`, `dot`, `radialBlur` and `glitch` look the same on WebGPU (the default) and WebGL; `multiColorReplace` draws everything black on WebGPU, `kawaseBlur` is far weaker and `advancedBloom` sharper there: use `colorReplace`, `blur`, `bloom`. A filter follows the edges of the layer's own picture: `glow` on a full-screen opaque layer shows nothing (put it on the shapes and the text).
112. **Text inside a parent that is scaled up comes out soft.** Text is drawn once at its own size and then stretched, so `{ type: 'null', initial: { scale: 3 } }` with a text child of `fontSize: 30` is blurry (shapes stay sharp). Give the text `resolution: 3` (it is drawn at 3 times the pixels, for a parent that grows to 3x; 1 to 8, the cost is the memory), or write it at the size it is shown (`fontSize: 90`, parent scale 1), or let the parent only scale DOWN (a pull-back from big to normal is sharp the whole way). `check --at … --crop` shows the difference.
113. **Two limits on sound that `help sfx` / `help music` did not say.** An `sfx` lasts at most 10 s (`MAX_LENGTH` in the synth): for a longer rain or room tone, chain two audio layers that overlap by a moment, or use `loop` on a short one. A `music` layer plays at most 16 tracks, and a warning says that only the first 16 play: put the rest in a second audio layer.
114. **A keyframe's `from` is on screen from the start of the layer, and it beats `initial`.** `initial: { alpha: 0 }` plus `{ at: 2, from: { alpha: 1 }, to: { alpha: 0.5 }, duration: 1 }` shows the layer at full alpha from second 0 (measured in Chrome: the red square was there at 0.5 s). That is how a title waits invisible with `from: { alpha: 0 }` until its `at`, but it surprises when `from` is the visible end. Give the layer its own `at: 2`, or use `set` at the moment it should appear. No warning: the same pattern (`initial` = the resting value, `from` = where it starts) is what the recipes do everywhere.
115. **A `canvas` layer is a function of the time, nothing more.** The canvas is cleared before every call and nothing survives into the next, so `x += 1` per call, "draw over the last picture" and `Math.random()` all break: a seek or an export would not match playback (`check` draws each canvas layer twice at a few moments and reports a layer whose pictures differ). Compute from `t` (a trail is the positions of the past), use `info.random()` (seeded) and `params` that keyframes animate, and compute a whole simulation in `setup` (an array by frame) and read `info.frame`. A cache of a pure function is fine (same input, same output); state that depends on which frames were drawn before is not. A canvas layer cannot see or paint on what is below it: use `filters`, a matte or a composition for that. Pixel art needs `smoothing: false` (hard pixels when scaled up) and a small `width` / `height` with a big `initial.scale`.
116. **Several canvas layers that need the same thing: module scope and `info.time`, not `setup` and a hand-added `at`.** The state a layer's `setup` returns is private to that layer. A plant, a city or a palette that two layers draw is computed once before `movie.init` (from `random(seed)` and plain functions) and read by both; the shared clock is `info.time` (the movie's seconds), not `t + 3` with the layer's `at` copied in, which goes wrong without a word when someone moves the layer.
117. **A sprite or mask made in `setup` with `document.createElement('canvas')` can be drawn differently the first time.** A GPU canvas used as the source of `drawImage`, under `destination-in` after many anti-aliased strokes, drew up to 128 of 255 differently over 40 000 pixels of a 1280×720 layer the first time and the same every time after. `info.canvas(w, h)` makes a canvas that does not do this; `check` throws away one draw of each moment before it compares, so it does not blame the layer, but an export that draws a frame for the first time is still safer with `info.canvas`. A mask is also easier to get right as: the words first, then `globalCompositeOperation = 'source-atop'` and the texture (recipe `canvas-text-mask`); two `fillText` under `destination-in` intersect.
118. **`check` does not see text drawn in a canvas.** The layout test (cut-off, off-canvas, overlap) reads the text layers; a label or a caption you draw with `fillText` can run off the edge or collide with another without a word, and "no cut-off text" only speaks for the text layers. Look at the sheet and at `--at … --crop`, and keep a margin.
119. **`bitrate` is a ceiling, not a target: a quiet or mostly black picture is written far below it, and no setting changes that.** Asking for `'150M'` gave 105 to 151 Mbps on grainy dark pictures and 13 to 18 Mbps on clean ones (a platform that wants at least 35 Mbps for 4K then rejects the file). The encoder spends bits on what changes: a constant bitrate mode reaches the encoder (it was measured, with H.264, HEVC and VP9) and still writes 0.1 Mbps for a black frame with a circle, because no encoder pads. So read the real rate of the file (`render` prints it and says when it is far under what you asked; `npx pixi-effects probe file.mp4` too) and, when a minimum is needed, raise it by what the picture really has: fine film grain (a seeded noise of about ±2/255 in the darks, which also hides banding in dark gradients) costs bits and looks right. Do not stretch it with an invisible pattern.


<!-- ===== skills/pixi-effects/reference/recipes.md ===== -->

# pixi-effects recipes

Copy, adapt, run. Every block marked `@recipe` is a function body that **returns the composition's `sequences`** (or `{ sequences, transitions, duration }`); the repo's tests build each one and fail on any warning, so they stay correct. Blocks marked `@docs-only` need a browser (canvas / three.js) and are not executed by the tests.

Assumed canvas: 1280×720 @ 30 fps. `kenBurns`, `withFade` and `orbit` come from `pixi-effects`.

---

## Words that slam in on the beat (kinetic type)

Slam = big scale + tiny rotation easing out fast, plus a white flash rect on the beat. Keyframe `at` is local to the layer, so every word's keyframes start at `0`.

```js
// @recipe slam-words
const WORDS = [['KAFFE', '#ffd166'], ['NORD', '#ef476f'], ['ROAST', '#06d6a0']];
const BEAT = 0.5;                                    // seconds per beat
const sequences = [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#111111' } },
];
WORDS.forEach(([word, color], i) => {
  const at = i * BEAT * 2;
  sequences.push({
    type: 'text', text: word, at, duration: BEAT * 2,
    style: { fontSize: 'GH * 0.4', fontWeight: '900', fill: color, fontFamily: 'Arial Black, Arial, sans-serif' },
    initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
    keyframes: [{ at: 0, from: { scale: 2.6, rotation: -5, alpha: 0 }, to: { scale: 1, rotation: 0, alpha: 1 }, duration: 0.16, ease: 'expo.out' }],
  });
  sequences.push({                                   // white flash on the beat
    type: 'shape', shape: 'rect', width: 'GW', height: 'GH', at, duration: 0.3,
    initial: { x: 'GW/2', y: 'GH/2', fillColor: '#ffffff', alpha: 0.8 },
    keyframes: [{ at: 0, to: { alpha: 0 }, duration: 0.28 }],
  });
});
return sequences;
```

Size text by eye: Arial Black glyphs are ~0.8 × fontSize wide, monospace ~0.6 ×. Leave ~7 % of the frame for a hold-scale.

---

## Lower-third revealed by a wipe mask

A `mask` is a layer in the **parent's** coordinate space and does **not** move with the layer it masks: reveal by growing the mask's `width` from a fixed left edge (`anchorX: 0`); exit by moving the left edge to the right while the width shrinks to 0. Rects are centred by default, hence `anchorX: 0`.

```js
// @recipe lower-third
const bar = (name, y, w, h, color, at) => ({
  type: 'shape', shape: 'rect', name, width: w, height: h, anchorX: 0, at, duration: 3.6,
  initial: { x: 80, y, fillColor: color },
  mask: {
    type: 'shape', shape: 'rect', width: 0, height: h, anchorX: 0,
    initial: { x: 80, y, fillColor: '#ffffff' },
    keyframes: [
      { at: 0, to: { width: w }, duration: 0.5, ease: 'power3.out' },                    // reveal
      { at: -0.5, to: { x: 80 + w, width: 0 }, duration: 0.5, ease: 'power3.in' },        // exit
    ],
  },
});
return [
  bar('name-bar', 600, 520, 56, '#e63946', 0.2),
  bar('title-bar', 656, 420, 40, '#1d3557', 0.35),
  { type: 'text', text: 'JANE DOE', at: 0.5, duration: 3, style: { fontSize: 34, fontWeight: 'bold', fill: '#ffffff' },
    initial: { x: 100, y: 600, anchorX: 0, anchorY: 0.5, alpha: 0 },
    keyframes: [{ at: 0, to: { alpha: 1 }, duration: 0.3 }, { at: -0.4, to: { alpha: 0 }, duration: 0.3 }] },
];
```

---

## Pop in with a spring: a card that lands, a badge that bounces

A spring overshoots and settles: `duration: 'auto'` lets the physics set the length, a preset names the feel (`spring.gentle`, `snappy`, `bouncy`, `wobbly`, `slow`). Different presets on one layer's properties read as different materials.

```js
// @recipe spring-pop
const card = { type: 'shape', shape: 'rect', name: 'card', width: 520, height: 300, cornerRadius: 28, at: 0.3, duration: 3.7,
  initial: { x: 640, y: 360, fillColor: '#f4f1ea', scale: 0.4, alpha: 0 },
  keyframes: [
    { at: 0, to: { scale: 1 }, duration: 'auto', ease: 'spring.snappy' },
    { at: 0, to: { alpha: 1 }, duration: 0.2 },
  ] };
const badge = { type: 'shape', shape: 'circle', name: 'badge', radius: 46, at: 1.0, duration: 3,
  initial: { x: 860, y: 230, fillColor: '#e63946', scale: 0 },
  keyframes: [{ at: 0, to: { scale: 1 }, duration: 'auto', ease: 'spring.bouncy' }] };
const title = { type: 'text', text: 'Hello', name: 'title', at: 0.5, duration: 3.5, style: { fontSize: 88, fontWeight: 'bold', fill: '#1d3557' },
  initial: { x: 640, y: 380, anchorX: 0.5, anchorY: 0.5 },
  keyframes: [{ at: 0, from: { y: 440, alpha: 0 }, to: { y: 380, alpha: 1 }, duration: 'auto', ease: 'spring(1, 170, 12)' }] };
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#1d3557' } },
  card, badge, title,
];
```

---

## Rewind and play again: a composition whose own time you control

Put the part you want to rewind, slow down or freeze **in a composition**, then give that composition `speed` (one straight speed: `0.5` slow motion, `-1` backward) or `time` keyframes (any curve of its own time: play, hold, rewind, play slowly). The layers inside write `at` / `duration` / `keyframes` in the composition's own seconds; the composition's own `at` / `duration` stay in the outer time. A sound or `sfx` inside follows the clock (backward and lower when it rewinds, like a tape). `cubic-bezier(.2, .8, .2, 1)` is front-loaded, not slow motion: half of the replay passes in the first 13 % of its time and 99 % by 74 %, so the replay opens quickly and what sits at the END of the content (the ring, the settle) gets the long glide. `power2` is a cubic: `power2.in` has done only 12.5 % at half time, so the dismantling bunches up in the last third of the rewind.

```js
// @recipe rewind-and-replay
const act = {
  type: 'composition', name: 'act', duration: 11,
  // its own time: play 0 → 2.2 s, hold half a second, rewind to 0 (accelerating), hold, then replay (4.5 s of content over 6 s: a fast start, a long glide at the end)
  keyframes: [
    { at: 0, from: { time: 0 }, to: { time: 2.2 }, duration: 2.2, ease: 'none' },
    { at: 2.2, to: { time: 2.2 }, duration: 0.5 },
    { at: 2.7, to: { time: 0 }, duration: 1.3, ease: 'power2.in' },
    { at: 4, to: { time: 0 }, duration: 0.4 },
    { at: 4.4, to: { time: 4.5 }, duration: 6, ease: 'cubic-bezier(.2, .8, .2, 1)' },
  ],
  sequences: [
    // everything in here is in the composition's own seconds: 0 … 4.5
    { type: 'shape', shape: 'rect', name: 'bar', width: 'GW', height: 16, anchorX: 0, anchorY: 0, at: 0, duration: 4.5,
      initial: { x: 0, y: 330, fillColor: '#ff4d3d', scaleX: 0 }, keyframes: [{ at: 0, to: { scaleX: 1 }, duration: 0.8, ease: 'expo.out' }] },
    { type: 'text', text: 'AGAIN.', name: 'title', at: 0.4, duration: 4.1, style: { fontSize: 150, fontWeight: 'bold', fill: '#f2efe8' },
      initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
      keyframes: [{ at: 0, from: { y: 430, alpha: 0 }, to: { y: 360, alpha: 1 }, duration: 0.9, ease: 'expo.out' }] },
    { type: 'audio', sfx: 'hit', at: 0.4 },
  ],
};
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#0b0b10' } },
  act,
  // an overlay in the OUTER time: it shows while the act rewinds (2.7 s … 4 s of the movie)
  { type: 'text', text: '◀◀ REW', name: 'rew', at: 2.7, duration: 1.3, style: { fontSize: 36, fontWeight: 'bold', fill: '#ff4d3d' }, initial: { x: 60, y: 50 } },
];
```

The shortcuts, when one straight speed is enough: `{ type: 'composition', duration: 4, speed: 0.5, sequences: [ … ] }` (slow motion, the content plays half of its length), `speed: -1` (backward). For a **video file** the same words work on the layer itself:

```js
// @docs-only video-speed
// needs a real clip: assets: [{ name: 'clip', src: 'clip.mp4' }]
return [
  { type: 'video', asset: 'clip', speed: 0.5 },                 // slow motion; with no duration the layer lasts 2x the file
  { type: 'video', asset: 'clip', speed: -1, at: 4 },           // backward, the whole file
  { type: 'video', asset: 'clip', duration: 5, keyframes: [     // play 2 s, hold, then accelerate
    { at: 0, from: { time: 0 }, to: { time: 2 }, duration: 1 },
    { at: 1, to: { time: 2 }, duration: 0.5 },
    { at: 1.5, to: { time: 6 }, duration: 3.5, ease: 'power2.inOut' },
  ] },
];
```

---

## Push in on a whole flat scene (the 2D "camera"): a null that scales, and text drawn big enough

There is no second camera for flat scenes: the camera of the 2.5D layers is for `threeD` layers. For a push-in or pull-back of an ordinary 2D scene, put everything in a `null` layer that sits at the middle of the canvas and scale THAT (children use `parent: 'world'`, and their x / y are measured from the null's origin, so the middle of the canvas is 0, 0). Text is drawn once at its own size and then stretched, so give every text `resolution: R` where R is the biggest scale the group reaches (R 1–8); otherwise it goes soft.

```js
// @recipe scene-zoom
const R = 2;                                                  // the group grows to 2x: its text is drawn at 2x pixels
const inWorld = (spec) => ({ parent: 'world', ...spec });
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#0f1424' } },
  { type: 'null', name: 'world', initial: { x: 'GW/2', y: 'GH/2' },
    keyframes: [{ at: 0.5, from: { scale: 1 }, to: { scale: R }, duration: 3.5, ease: 'power2.inOut' }] },
  inWorld({ type: 'shape', shape: 'circle', radius: 120, initial: { x: 0, y: 0, fillColor: '#3b5bdb' } }),
  inWorld({ type: 'shape', shape: 'circle', radius: 40, initial: { x: 260, y: -120, fillColor: '#ffd166' } }),
  inWorld({ type: 'text', text: 'Zoom in', resolution: R, style: { fontSize: 48, fontWeight: 'bold', fill: '#ffffff' }, initial: { x: 0, y: 0, anchorX: 0.5, anchorY: 0.5 } }),
  inWorld({ type: 'text', text: 'sharp at 2x', resolution: R, style: { fontSize: 22, fill: '#c9d3f5' }, initial: { x: 0, y: 150, anchorX: 0.5, anchorY: 0.5 } }),
];
```

---

## Parallax: layers that scroll past at their own speed (a window of a train, a side-scroller)

Each layer is a long strip of repeated shapes that moves left at a constant speed, `speed × duration` pixels in all, so it must be that long plus the width of the screen. The speed is the depth: the near strip fast, the far one slow. A strip that is longer than it needs to be is only more layers.

```js
// @recipe parallax-strips
const D = 8, W = 1280;
// one strip: `count` shapes `gap` px apart, scrolling left at `speed` px/s from x = 0 for D seconds
const strip = (name, speed, gap, y, size, color) => {
  const count = Math.ceil((speed * D + W) / gap) + 1;
  return Array.from({ length: count }, (_, i) => ({
    type: 'shape', shape: 'rect', name: `${name}-${i}`, width: size, height: size * 2,
    initial: { x: i * gap, y, fillColor: color },
    keyframes: [{ at: 0, to: { x: i * gap - speed * D }, duration: D, ease: 'none' }],
  }));
};
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#1b2a4a' } },
  ...strip('far', 30, 240, 420, 60, '#26365c'),               // distant hills: 30 px/s
  ...strip('mid', 120, 200, 500, 40, '#314a7a'),              // 120 px/s
  ...strip('near', 480, 360, 600, 24, '#0b1220'),             // poles: 480 px/s
];
```

To land something exactly where you want at a time `t` (a moon under a bridge at 6 s), compute the strip's x at `t` the same way: `i * gap - speed * t`.

---

## Draw it yourself: the `canvas` layer (an afterimage, rings that grow, a pixel sprite, a simulation)

When no layer draws what you need, write the drawing as a **function of the time**: `draw(ctx, t, info)` paints into the layer's own cleared 2D canvas and the layer is a normal layer (`initial`, `keyframes`, `filters`, `mask`, export). Rules: the same `t` and `info.params` give the same pixels (no `Math.random` or `Date.now`: `info.random()` is seeded), nothing survives from the last frame, and a simulation is computed whole in `setup`. `help canvas` has the contract.

An **afterimage** is drawn from the positions of the past, not from the last picture:

```js
// @recipe canvas-trail
const at = (t) => ({ x: 640 + 420 * Math.sin(t * 1.7), y: 360 + 200 * Math.sin(t * 2.9) });      // where the dot is at time t
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#101420' } },
  { type: 'canvas', name: 'trail', duration: 6, params: { tail: 0.5 },
    draw: (ctx, t, info) => {
      const N = 14;
      for (let i = N; i >= 0; i--) {                                  // the oldest first, the head last
        const p = at(Math.max(0, t - i * info.params.tail / N));
        ctx.globalAlpha = (1 - i / (N + 1)) * 0.85;
        ctx.fillStyle = '#ff4f1a';
        ctx.beginPath(); ctx.arc(p.x, p.y, 34 - i * 1.6, 0, Math.PI * 2); ctx.fill();
      }
    } },
];
```

**Rings that grow**, wobbling a little with a seeded `random()`, and `params` that keyframes animate (the `progress` of the layer is `info.progress`):

```js
// @recipe canvas-rings
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#efe9dc' } },
  { type: 'canvas', name: 'rings', width: 720, height: 720, duration: 8, seed: 3, params: { years: 0 },
    initial: { x: 640, y: 360, anchorX: 0.5, anchorY: 0.5 },
    keyframes: [{ at: 0, to: { 'params.years': 40 }, duration: 8, ease: 'power1.inOut' }],
    draw: (ctx, t, info) => {
      const cx = info.width / 2, cy = info.height / 2, n = Math.floor(info.params.years);
      const wob = Array.from({ length: n + 1 }, () => [info.random() * 6, info.random() * Math.PI * 2]);      // the same wobble at every frame
      for (let k = n; k >= 0; k--) {
        const r = 8 + k * 8.5 + (k === n ? (info.params.years - n) * 8.5 : 0);
        ctx.beginPath();
        for (let a = 0; a <= 64; a++) { const th = (a / 64) * Math.PI * 2, rr = r + wob[k][0] * Math.sin(th * 3 + wob[k][1]); ctx.lineTo(cx + rr * Math.cos(th), cy + rr * Math.sin(th)); }
        ctx.closePath();
        ctx.fillStyle = k % 2 ? '#c9a36a' : '#a87c45'; ctx.fill();
      }
    } },
];
```

A **pixel sprite**: drawn small with `smoothing: false`, shown big (the layer is scaled up and the pixels stay hard):

```js
// @recipe canvas-pixel-sprite
const ROWS = ['..1111..', '.111111.', '11.11.11', '11111111', '.1.11.1.', '..1111..', '.1....1.', '1......1'];
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#1b1330' } },
  { type: 'canvas', name: 'sprite', width: 8, height: 8, smoothing: false, duration: 8,
    initial: { x: 640, y: 360, anchorX: 0.5, anchorY: 0.5, scale: 30 },
    keyframes: [{ at: 0, from: { y: 300 }, to: { y: 420 }, duration: 8, ease: 'steps(16)' }],             // moves in whole steps
    draw: (ctx, t) => {
      const blink = Math.floor(t * 2) % 2;                          // two frames of animation
      ROWS.forEach((row, y) => [...row].forEach((c, x) => { if (c === '1') { ctx.fillStyle = (y === 2 && blink) ? '#1b1330' : '#ffd166'; ctx.fillRect(x, y, 1, 1); } }));
    } },
];
```

A **simulation** (a game of life) is computed WHOLE in `setup`, one array per generation, and `draw` only reads the generation for the time (`info.frame`, or here `t`): a pure function of the time, so a seek or an export agrees with playback:

```js
// @recipe canvas-life
const W = 48, H = 27, GENERATIONS = 90;
const step = (g) => g.map((row, y) => row.map((v, x) => {
  let n = 0; for (let dy = -1; dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) if (dx || dy) n += g[(y + dy + H) % H][(x + dx + W) % W];
  return n === 3 || (v && n === 2) ? 1 : 0;
}));
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#0b0f14' } },
  { type: 'canvas', name: 'life', width: 960, height: 540, duration: 6, seed: 11, initial: { x: 640, y: 360, anchorX: 0.5, anchorY: 0.5 },
    setup: (info) => {
      let g = Array.from({ length: H }, () => Array.from({ length: W }, () => (info.random() < 0.3 ? 1 : 0)));
      const all = [g]; for (let i = 1; i < GENERATIONS; i++) all.push((g = step(g)));
      return all;
    },
    draw: (ctx, t, info) => {
      const g = info.state[Math.min(info.state.length - 1, Math.floor(t * 15))];          // 15 generations a second
      ctx.fillStyle = '#7bd88f';
      g.forEach((row, y) => row.forEach((v, x) => { if (v) ctx.fillRect(x * 20 + 2, y * 20 + 2, 16, 16); }));
    } },
];
```

---

## Type, curves and charts in a canvas layer (type through a moving texture, text along a curve, bars that swap places)

The `canvas` layer (see the section above and `help canvas`) is also where text effects the text layer cannot do and live charts are drawn. `info.canvas(w, h)` makes sprites and masks in `setup`, `info.time` is the movie's clock, and `ease`, `noise`, `noise2`, `random`, `samplePath` are importable from `pixi-effects`. `check` does not see text drawn in a canvas: look at the sheet and at `--crop` enlargements.

**Type as a window onto something that moves.** Draw the words once into a canvas from `info.canvas` (in `setup`), draw them back first, then paint with `source-atop`: the paint shows only where the words are (two `fillText` under `destination-in` would intersect instead):

```js
// @recipe canvas-text-mask
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#0d0a14' } },
  { type: 'canvas', name: 'window', width: 1100, height: 320, duration: 6, initial: { x: 640, y: 360, anchorX: 0.5, anchorY: 0.5 },
    setup: (info) => {                                                // the words, drawn once into a canvas of their own
      const word = info.canvas(1100, 320), c = word.getContext('2d');
      c.fillStyle = '#fff'; c.font = '900 280px "Arial Black", "Helvetica Neue", sans-serif';
      c.textAlign = 'center'; c.textBaseline = 'middle'; c.fillText('LIGHT', 550, 160);
      return { word };
    },
    draw: (ctx, t, info) => {
      ctx.drawImage(info.state.word, 0, 0);                           // the words first: they are the window …
      ctx.globalCompositeOperation = 'source-atop';                   // … and what is drawn next appears only where they are
      ctx.fillStyle = '#2a1030'; ctx.fillRect(0, 0, 1100, 320);
      for (let k = 0; k < 14; k++) {                                  // bands of colour sliding through
        ctx.fillStyle = k % 2 ? '#ff4f1a' : '#ffb347';
        ctx.fillRect(((k * 90 + t * 160) % 1260) - 80, 0, 38, 320);
      }
    } },
];
```

**Text along a curve, and a line that draws on.** `samplePath(d)` walks SVG path data by length: `at(u)` is the point and the heading a fraction `u` along, `trim(a, b)` the part between two fractions. `ease('power2.out')` is the same easing a keyframe takes. Build the sampler once, outside `draw`:

```js
// @recipe canvas-text-on-path
const route = samplePath('M 140 560 C 340 120 940 120 1140 560');
const WORD = 'ALONG THE CURVE', EASE = ease('power2.out');
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#101420' } },
  { type: 'canvas', name: 'along', duration: 6,
    draw: (ctx, t) => {
      const run = EASE(Math.min(1, t / 3));                           // 0 → 1: the line draws on, then the letters settle
      ctx.strokeStyle = '#ff4f1a'; ctx.lineWidth = 3; ctx.beginPath();
      for (const piece of route.trim(0, run)) { ctx.moveTo(piece[0], piece[1]); for (let i = 2; i < piece.length; i += 2) ctx.lineTo(piece[i], piece[i + 1]); }
      ctx.stroke();
      ctx.font = '700 54px Georgia, serif'; ctx.textBaseline = 'middle'; ctx.fillStyle = '#f4efe6';
      let d = 0;                                                      // distance along the route, in px
      for (const ch of WORD) {
        const w = ctx.measureText(ch).width;
        const u = (d + w / 2 + 90) / route.length - (1 - run) * 0.5;  // where this letter's middle is, a fraction along
        d += w + 4;
        if (u < 0 || u > 1) continue;
        const p = route.at(u);
        ctx.save(); ctx.translate(p.x, p.y); ctx.rotate(p.angle); ctx.globalAlpha = run; ctx.fillText(ch, -w / 2, -30); ctx.restore();
      }
    } },
];
```

**Bars that swap places smoothly.** A bar's row is its rank averaged over the last third of a second, computed from `t` alone (the values at those earlier moments are a function of time too): when two bars change places they glide past each other, passing through one another for the length of the swap as in any bar race, nothing jumps, and a seek is exact:

```js
// @recipe canvas-bars
const NAMES = ['Oslo', 'Lima', 'Kyiv', 'Pune', 'Graz'], FROM = [40, 55, 30, 20, 45], TO = [60, 35, 70, 50, 25];
const BAR = 90, GAP = 28, EASE = ease('power2.inOut');
const valuesAt = (time) => FROM.map((a, i) => a + (TO[i] - a) * EASE(Math.min(1, Math.max(0, time) / 5)));
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#101420' } },
  { type: 'canvas', name: 'race', width: 1000, height: 600, duration: 6, initial: { x: 140, y: 60 },
    draw: (ctx, t) => {
      const now = valuesAt(t), before = Array.from({ length: 8 }, (_, k) => valuesAt(t - k * 0.04));   // the last third of a second
      ctx.font = '700 34px system-ui, sans-serif'; ctx.textBaseline = 'middle';
      now.forEach((value, i) => {
        const rank = before.reduce((sum, v) => sum + v.filter(other => other > v[i]).length, 0) / before.length;   // 0 = top
        const y = rank * (BAR + GAP);
        ctx.fillStyle = i === 2 ? '#ff4f1a' : '#4c5a78'; ctx.fillRect(160, y, value * 10, BAR);
        ctx.fillStyle = '#f4efe6'; ctx.textAlign = 'right'; ctx.fillText(NAMES[i], 140, y + BAR / 2);
        ctx.textAlign = 'left'; ctx.fillText(String(Math.round(value)), 160 + value * 10 + 14, y + BAR / 2);
      });
    } },
];
```

---

## A ticker that scrolls out completely (`w` = the text's own width)

`'-w'` is the exact x at which the text has left the screen on the left (`w` is measured after the style is applied).

```js
// @recipe marquee
return [{
  type: 'text', text: 'BREAKING NEWS  •  MARKETS RALLY  •  NEW RECORD SET', duration: 8,
  style: { fontSize: 30, fontWeight: 'bold', fill: '#ffffff' },
  initial: { x: 'GW', y: 670, anchorX: 0, anchorY: 0.5 },
  keyframes: [{ at: 0, to: { x: '-w' }, duration: 8, ease: 'none' }],
}];
```

---

## Numbers that count up

A text layer has an animatable number, `value`, printed wherever the text has `{value}`. Animate it with ordinary keyframes (ease, `from`/`to`, `repeat`).

```js
// @recipe count-up
return [{
  type: 'text', text: '{value}', format: { grouping: true },            // → "2,480"   (decimals: 0 by default)
  style: { fontSize: 96, fontWeight: 'bold', fill: '#ffffff' },
  initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5, value: 0 },
  keyframes: [{ at: 1, to: { value: 2480 }, duration: 1.2, ease: 'power3.out' }],
}];
```

Prefixes and suffixes go in the text (`'${value}'`, `'{value} users'`, `'{value}%'`). If a bar must stay locked to its counter, give both the same `at`, `duration` and `ease` — see the bar chart below.

---

## Data-driven bar chart

Generate the whole spec from the data. Bars grow from the baseline (`anchorY: 1` + a `height` keyframe); each value label rides the top of its bar and counts up with the same ease and timing, so they stay locked. A line's `from` / `to` are plain canvas coordinates (give `x,y` only to move it). A callout pill must be sized from its text.

```js
// @recipe bar-chart
const data = [['Mon', 12], ['Tue', 30], ['Wed', 22], ['Thu', 41], ['Fri', 35]];
const max = Math.max(...data.map(d => d[1]));
const step = [1, 2, 2.5, 5, 10].map(m => m * 10 ** Math.floor(Math.log10(max / 4))).find(v => max / v <= 5) ?? 10;
const NICE = Math.ceil(max / step) * step;                    // axis top, so the chart survives changed data
const BASE = 600, CHART_H = 380, BAR_W = 90, GAP = 40, DUR = 0.9, EASE = 'power3.out';
const EACH = 0.12;                                            // seconds between bars: 0.12 is a quick wave; EACH = DUR + 0.3 grows them one at a time
const PEAK_AT = Math.max(4, 0.4 + (data.length - 1) * EACH + DUR + 0.2);   // the highlight and the callout come after the last bar has grown
const X0 = (1280 - (data.length * BAR_W + (data.length - 1) * GAP)) / 2, X1 = X0 + data.length * BAR_W + (data.length - 1) * GAP;
const sequences = [];
for (let v = 0; v <= NICE; v += step) {                       // grid lines + tick labels
  const y = BASE - CHART_H * v / NICE;
  sequences.push({ type: 'shape', shape: 'line', from: [X0 - 20, y], to: [X1 + 20, y], initial: { strokeColor: '#33405c', strokeWidth: 1 } });
  sequences.push({ type: 'text', text: String(v), style: { fontSize: 20, fill: '#7f8bb0' }, initial: { x: X0 - 32, y, anchorX: 1, anchorY: 0.5 } });
}
const best = data.findIndex(d => d[1] === max);
data.forEach(([label, value], i) => {
  const x = X0 + i * (BAR_W + GAP) + BAR_W / 2;
  const at = 0.4 + i * EACH;
  const h = CHART_H * value / NICE;
  sequences.push({
    type: 'shape', shape: 'rect', width: BAR_W, height: 0, cornerRadius: 8, anchorY: 1, at, colorSpace: 'oklab',
    initial: { x, y: BASE, fillColor: '#4f6df5' },
    keyframes: [
      { at: 0, to: { height: h }, duration: DUR, ease: EASE },
      ...(i === best ? [{ at: PEAK_AT - at, to: { fillColor: '#ffd166' }, duration: 0.5 }] : [{ at: PEAK_AT - at, to: { alpha: 0.45 }, duration: 0.5 }]),   // highlight the maximum at t = 4 s
    ],
  });
  sequences.push({                                            // value label: counts up while riding the bar's top
    type: 'text', text: '{value}', at,
    style: { fontSize: 28, fontWeight: 'bold', fill: '#ffffff' },
    initial: { x, y: BASE - 14, anchorX: 0.5, anchorY: 1, value: 0 },
    keyframes: [{ at: 0, to: { value, y: BASE - h - 14 }, duration: DUR, ease: EASE }],
  });
  sequences.push({ type: 'text', text: label, at, style: { fontSize: 26, fill: '#aab4d4' }, initial: { x, y: BASE + 16, anchorX: 0.5, anchorY: 0 } });
});
// callout: a pill sized from its text (~0.58 x fontSize per glyph + padding), a pointer triangle, clamped inside the plot
const text = 'Peak: ' + data[best][0] + ' ' + max, FS = 26;
const PW = text.length * FS * 0.58 + 44, cx = Math.min(Math.max(X0 + best * (BAR_W + GAP) + BAR_W / 2, X0 + PW / 2), X1 - PW / 2), cy = BASE - CHART_H - 70;
sequences.push({ type: 'shape', shape: 'rect', width: PW, height: 52, cornerRadius: 26, at: PEAK_AT + 0.2, initial: { x: cx, y: cy, fillColor: '#ffd166', alpha: 0 },
                 keyframes: [{ at: 0, to: { alpha: 1 }, duration: 0.3 }] });
sequences.push({ type: 'shape', shape: 'polygon', points: [[-10, 0], [10, 0], [0, 12]], at: PEAK_AT + 0.2, initial: { x: cx, y: cy + 32, fillColor: '#ffd166', alpha: 0 },
                 keyframes: [{ at: 0, to: { alpha: 1 }, duration: 0.3 }] });
sequences.push({ type: 'text', text, at: PEAK_AT + 0.2, style: { fontSize: FS, fontWeight: 'bold', fill: '#1b1b2f' }, initial: { x: cx, y: cy, anchorX: 0.5, anchorY: 0.5, alpha: 0 },
                 keyframes: [{ at: 0, to: { alpha: 1 }, duration: 0.3 }] });
return sequences;
```

---

## Letters that fly in from depth (2.5D title)

One `threeD` text layer per letter, staggered; monospace so the advance is predictable (~0.6 × fontSize). `fov` eases while `z` auto-follows it, so the `z = 0` plane (the title) stays put. Letters start at `z: 560`, which must stay **below the camera distance** (≈ 808 at `fov` 48) or they are hidden. `dropShadow` glow needs `padding` (≥ 2 × blur).

```js
// @recipe depth-title
const TEXT = 'PIXI EFFECTS', SIZE = 118, ADV = SIZE * 0.602;
const letters = [...TEXT].flatMap((ch, i) => ch === ' ' ? [] : [{
  type: 'text', text: ch, threeD: true,
  style: {
    fontSize: SIZE, fontWeight: '800', fill: '#3de0ff',
    fontFamily: "ui-monospace, 'SF Mono', Menlo, Consolas, monospace",
    dropShadow: { color: '#5b6cff', blur: 20, distance: 0, alpha: 0.9 }, padding: 48,
  },
  initial: { x: 640 + (i - (TEXT.length - 1) / 2) * ADV, y: 330, anchorX: 0.5, anchorY: 0.5, z: 560, rotationY: 75, rotationX: -45, alpha: 0 },
  keyframes: [
    { at: 0.55 + i * 0.075, to: { z: 0, rotationY: 0, rotationX: 0 }, duration: 1.0, ease: 'expo.out' },
    { at: 0.55 + i * 0.075, to: { alpha: 1 }, duration: 0.3 },
    { at: 0.7 + i * 0.075, to: { fill: '#f4f6ff' }, duration: 0.8, ease: 'sine.out' },      // colour flash on landing
  ],
}]);
return [
  { type: 'camera', initial: { fov: 48 }, keyframes: [{ at: 0, to: { fov: 34 }, duration: 6.5, ease: 'sine.inOut' }] },
  ...letters,
];
```

---

## Camera orbit (+ optional dolly zoom)

`orbit()` returns a camera layer that circles a point (the circle is sampled into short linear keyframes; the ease applies to the angle). Add `dollyZoom: { from, to }` and `fov` animates while the radius follows it, so the `z = 0` plane keeps its size and only the perspective changes. Under a dolly zoom everything with `z > 0` balloons toward the viewer: keep the hero content at `z = 0` and near content at small `z`; far layers are pulled toward the centre, so spread far cards to the outer x positions and near cards inward, and leave ~10 % margin for the orbit sweep.

```js
// @recipe camera-orbit
const card = (x, z, color) => ({
  type: 'shape', shape: 'rect', width: 300, height: 200, cornerRadius: 20, threeD: true,
  initial: { x, y: 360, z, fillColor: color },
});
return [
  orbit({ duration: 6, degrees: 50, dollyZoom: { from: 38, to: 62 } }),    // options: radius (not with dollyZoom), center, start, fov, ease
  card(240, -300, '#3a6ea5'), card(640, 0, '#d96a3a'), card(990, 60, '#38a169'),     // near cards stay at small z
];
```

A call-to-action or any overlay that must stay screen-aligned should be a plain 2D layer (no `threeD`) placed last: it ignores the camera and stays on top. Fade the 3D scene and headline out before it appears; a dim rect alone leaves them visible.

---

## A card in depth (a composition with `threeD: true`)

A `composition` with `threeD: true` is a card: its children are drawn into one texture that is then moved in depth, so a rect, an icon and a label rotate and scale together. `threeD` layers at the same `z` keep array order. Entrance from depth, then a gentle bob with `repeat` / `yoyo`.

```js
// @recipe depth-cards
const card = (title, color, x, y, z, at) => ({
  type: 'composition', name: title, at, width: 300, height: 190, threeD: true,
  initial: { x, y, z, pivotX: 150, pivotY: 95 },                       // pivot = the centre, so x,y is where the centre sits
  sequences: [
    { type: 'shape', shape: 'rect', width: 300, height: 190, cornerRadius: 24, initial: { x: 150, y: 95, fillColor: color } },
    { type: 'text', text: title, style: { fontSize: 34, fontWeight: 'bold', fill: '#ffffff' }, initial: { x: 150, y: 95, anchorX: 0.5, anchorY: 0.5 } },
  ],
  keyframes: [
    { at: 0, from: { alpha: 0, z: z - 400, rotationY: 55 }, to: { alpha: 1, z, rotationY: 0 }, duration: 0.9, ease: 'expo.out' },
    { at: 1, to: { y: y - 14 }, duration: 1.2, ease: 'sine.inOut', repeat: 3, yoyo: true },
  ],
});
return [
  { type: 'camera', initial: { fov: 42 } },
  card('Battery', '#3a6ea5', 220, 300, -280, 0.2),         // far cards at the outer x
  card('Sound', '#d96a3a', 1060, 260, -200, 0.4),
  card('Comfort', '#38a169', 640, 380, 0, 0.6),
];
```

---

## Cut to the next scene with an expanding circle

The outgoing scene must stay alive until the covering shape has finished; the next scene starts when the flood is complete. Reach the far corners: radius ≥ half the diagonal (734 px at 720p). `expo.in` stays tiny until the very end — use `power2.in`.

```js
// @recipe scene-flood
const FLOOD_AT = 3, FLOOD = 0.6, END = 6;
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', duration: FLOOD_AT + FLOOD, initial: { x: 'GW/2', y: 'GH/2', fillColor: '#1d2b53' } },
  { type: 'text', text: 'BEFORE', duration: FLOOD_AT + FLOOD, style: { fontSize: 160, fontWeight: '900', fill: '#ffffff' }, initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 } },
  { type: 'shape', shape: 'circle', radius: 0, at: FLOOD_AT, duration: END - FLOOD_AT, initial: { x: 'GW/2', y: 'GH/2', fillColor: '#ffd166' },
    keyframes: [{ at: 0, to: { radius: 820 }, duration: FLOOD, ease: 'power2.in' }] },
  { type: 'text', text: 'AFTER', at: FLOOD_AT + FLOOD, duration: END - FLOOD_AT - FLOOD, style: { fontSize: 160, fontWeight: '900', fill: '#1d2b53' }, initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5, alpha: 0 },
    keyframes: [{ at: 0, to: { alpha: 1 }, duration: 0.25 }] },
];
```

---

## Slideshow with transitions and background music

Scene `i` starts at `i × (L − T)` and overlaps the next by the transition length `T`; the transition's `at` is the next scene's start; total = `n × (L − T) + T`. Transitions and `kenBurns` combine freely. Captions are top-level layers (transitions never touch layers they do not name); keep them above the bottom ~60 px. A music file shorter than the movie (`bgm.mp3` is a 16 s loop) needs **`loop: true`** or it falls silent.

```js
// @recipe slideshow
const photos = ['p1', 'p2', 'p3'], L = 4, T = 1, STEP = L - T;
const kinds = ['crossfade', 'wipe', 'zoom'];
const total = photos.length * STEP + T;
const sequences = photos.map((asset, i) =>
  kenBurns({ asset, name: 'scene' + i, at: i * STEP, duration: L, motion: i % 2 ? 'position' : 'scale' }));
const transitions = photos.slice(1).map((_, i) => ({
  kind: kinds[i % kinds.length], from: 'scene' + i, to: 'scene' + (i + 1), at: (i + 1) * STEP, duration: T,
  ...(kinds[i % kinds.length] === 'wipe' ? { direction: 'left' } : {}),
}));
photos.forEach((_, i) => sequences.push(withFade({
  type: 'text', text: 'Scene ' + (i + 1), at: i * STEP + 0.5, duration: L - 1.5,
  style: { fontSize: 44, fill: '#ffffff', dropShadow: { color: '#000000', blur: 6, distance: 2, alpha: 0.7 } },
  initial: { x: 'GW/2', y: 600, anchorX: 0.5, anchorY: 0.5 },
}, { in: 0.4, out: 0.4 })));
sequences.push({ type: 'audio', asset: 'bgm', loop: true, volume: 0, duration: total,
  keyframes: [{ at: 0, to: { volume: 0.8 }, duration: 2 }, { at: -2, to: { volume: 0 }, duration: 2 }] });
transitions.forEach(tr => sequences.push({ type: 'audio', sfx: 'swoosh', at: tr.at + tr.duration / 2 - 0.16 }));   // a swoosh is loudest 0.16 s in: centre it on the transition
return { sequences, transitions, duration: total };
```

Source images should be at least canvas-sized (`kenBurns` zooms in): draw generated images at 1920×1080 for a 1280×720 movie.

**A plain cut instead of a transition, generated images, music with no file:** scenes are layers one after the other (`at` = `i × L`) with no `transitions`; the images are the assets `p1…p3` (draw them with `placeholderPhoto`, recipe `placeholder-images`). The tune is written as text: at 96 bpm a beat is 0.625 s, so 24 beats are 15 s and every track has to add up to 24 (the check's `music` read-back shows each track's length).

```js
// @recipe slideshow-cuts
const N = 3, L = 5, total = N * L;
const sequences = Array.from({ length: N }, (_, i) =>
  kenBurns({ asset: 'p' + (i + 1), name: 'scene' + i, at: i * L, duration: L, motion: i % 2 ? 'position' : 'scale' }));
sequences.push({ type: 'audio', at: 0, volume: 0.7, duration: total, music: {
  bpm: 96,
  tracks: [
    { inst: 'pad',  notes: 'Am:4 F:4 C:4 G:4 Am:4 F:4' },                     // 6 chords x 4 beats = 24 beats = 15 s
    { inst: 'bass', notes: 'a1:4 f1:4 c2:4 g1:4 a1:4 f1:4' },
  ],
} });
return { sequences, duration: total };
```

---

## Music with no file (`music`)

A tune written as text: tracks of notes and chords (`c4:2`, `Am7:4`, `_` rest), drum patterns, a tempo. Count the beats (a 4/4 bar is 4); keep every track the same length; give the drums `from` so they enter after the intro; fade a track in with `vol` points. It lasts its notes plus a reverb tail and ends with the movie; `loop: true` repeats it. The mix sits at −6 dBFS peak at `volume: 1`: use 0.5–0.8 under speech or sound effects.

```js
// @recipe music-lofi
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#1b1a2e' } },
  { type: 'text', text: 'evening', at: 0.5, style: { fontFamily: 'Georgia, serif', fontSize: 96, fill: '#f3eee4' }, initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
    keyframes: [{ at: 0, from: { alpha: 0 }, to: { alpha: 1 }, duration: 1.2 }] },
  { type: 'audio', at: 0, volume: 0.8, music: {
      bpm: 84, swing: 0.16, reverb: 0.26, seed: 7,
      tracks: [
        { inst: 'keys',  vol: 0.7, pan: -0.15, strum: 0.012, notes: 'Cmaj7:4 Am7:4 Dm7:4 G7:4 | Cmaj7:4 Am7:4 Dm7:2 G7:2 Cmaj7:4' },
        { inst: 'bass',  vol: 0.85, notes: 'c2:1.5 _:0.5 g2:1 c2:1 | a1:1.5 _:0.5 e2:1 a1:1 | d2:1.5 _:0.5 a2:1 d2:1 | g1:1.5 _:0.5 d2:1 g1:1 | c2:1.5 _:0.5 g2:1 c2:1 | a1:1.5 _:0.5 e2:1 a1:1 | d2:2 f2:1 a1:1 | g1:2 b1:1 d2:1 | c2:4' },
        { inst: 'pluck', vol: [[0, 0], [8, 0.55]], pan: 0.25, step: 0.5, notes: '_:8 | e5:1 d5:0.5 c5:0.5 e5:2 | c5:1 a4:1 e5:2 | f5:1 e5:0.5 d5:0.5 a4:2 | d5:1.5 b4:0.5 g4:2 | e5:1 g5:1 e5:1 d5:1 | c5:1 a4:1 c5:2 | d5:1 f5:1 e5:1 d5:1 | b4:2 d5:2 | c5:4' },
        { inst: 'pad',   vol: 0.5, notes: '[c3 g3 e4]:8 [a2 e3 c4]:8 [d3 a3 f4]:8 [g2 d3 b3]:8' },
      ],
      drums: [{ from: 8, kick: 'x.......x.x.....', snare: '....x.......x...', hat: 'x.x.x.x.x.x.x.xo' }],
  } },
];
```

Other feels: a 6/8 lullaby is `bpm: 72`, `grid: 2`, bars of 3 beats (a dotted quarter `:1.5`, an eighth `:0.5`), instruments `musicbox` + `pluck` + `pad`; a build-up is layers entering with rests and `vol` points on the pad, drums from a later `from`; a ritardando is `bpm: [[0, 96], [28, 96], [32, 60]]`; a bright jingle is `lead` + `bell` + `sleigh` / `shaker` over a bouncy `bass`.

## Sound effects without files

No `assets`, no files: a sound effect is one audio layer with `sfx`. It lasts as long as the sound.

```js
// @recipe sfx-minimal
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#0f1424' } },
  { type: 'text', name: 'word', text: 'HELLO', at: 2, duration: 3,
    style: { fontSize: 120, fontWeight: '900', fill: '#ffffff' },
    initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
    keyframes: [{ at: 0, from: { x: -400 }, to: { x: 'GW/2' }, duration: 0.4, ease: 'power3.out' }] },
  { type: 'audio', sfx: 'swoosh', at: 2 },             // flies in with a swoosh…
  { type: 'audio', sfx: 'hit', at: 2.4 },              // …and lands (0.4 s later) with a hit
];
```

Check it without listening, then export — the file encodes this same mix (mp4 / mov: AAC, webm / mkv: Opus; lossy):

```js
// @docs-only render-and-verify
await movie.init({ canvas, width: 1280, height: 720, duration: 5, composition: { sequences } });
const a = movie.inspectAudio();
console.log(a.issues);                                    // must be []
console.log(a.sources.map(s => [s.layer, s.start, s.sound.loudestAt, s.sound.brightnessHz]));
const blob = await movie.render({ format: 'mp4' });
```

---

## Sound effects in sync with the picture

Line up the LOUD point, not the start: a `riser` is loudest at its end (`at = hit − duration`), a `swoosh` 0.16 s in, everything else at its start (`inspectAudio().sources[i].sound.loudestAt` tells you). Vary `pitch` for a series (a rising pitch reads as progress) and `seed` for repeats (no two typewriter keys alike).

```js
// @recipe sfx-cues
const BG = { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#0f1424' } };
const HIT = 1.5, RISE = 1.2;                         // the title slams in at 1.5 s; the riser leads into it
const sequences = [BG,
  { type: 'audio', name: 'riser', sfx: 'riser', at: HIT - RISE, duration: RISE, volume: 0.7 },   // a riser is loudest at its END
  { type: 'audio', name: 'hit', sfx: 'hit', at: HIT },
  { type: 'text', name: 'title', text: 'LAUNCH', at: HIT, duration: 8 - HIT,
    style: { fontSize: 140, fontWeight: '900', fill: '#ffffff', fontFamily: 'Arial Black, Arial, sans-serif' },
    initial: { x: 'GW/2', y: 260, anchorX: 0.5, anchorY: 0.5 },
    keyframes: [{ at: 0, from: { scale: 2.4, alpha: 0 }, to: { scale: 1, alpha: 1 }, duration: 0.18, ease: 'expo.out' }] },
];
['PLAN', 'BUILD', 'SHIP'].forEach((label, i) => {   // each item pops in with a pop; pitch climbs a step per item
  const at = 2.4 + i * 0.5;
  sequences.push({ type: 'text', name: 'item' + i, text: label, at, duration: 8 - at,
    style: { fontSize: 44, fontWeight: 'bold', fill: '#ffd166' },
    initial: { x: 360 + i * 280, y: 430, anchorX: 0.5, anchorY: 0.5 },
    keyframes: [{ at: 0, from: { scale: 0, alpha: 0 }, to: { scale: 1, alpha: 1 }, duration: 0.25, ease: 'back.out(2)' }] });
  sequences.push({ type: 'audio', name: 'pop' + i, sfx: { preset: 'pop', pitch: i * 2 }, at });
});
const CAPTION = 'ships friday', T0 = 4.4, STEP = 0.07;   // typed caption: one letter + one key per step
[...CAPTION].forEach((ch, i) => {
  const at = T0 + i * STEP;
  sequences.push({ type: 'text', name: 'cap' + i, text: ch, at, duration: 8 - at,
    style: { fontSize: 36, fill: '#9fb3d9', fontFamily: 'ui-monospace, Menlo, monospace' },
    initial: { x: 640 - (CAPTION.length * 22) / 2 + i * 22, y: 540, anchorY: 0.5 } });
  if (ch !== ' ') sequences.push({ type: 'audio', sfx: { preset: 'typewriter', seed: i }, at, volume: 0.6 });   // seed: every key sounds a little different
});
sequences.push({ type: 'audio', name: 'done', sfx: 'chime', at: T0 + CAPTION.length * STEP + 0.3 });
return sequences;
```

---

## Progress ring (an arc) with a counter

`shape: 'arc'` is a ring when it has only a stroke: animate `endAngle` from the start angle (−90 = 12 o'clock) round to +270 for a full circle. A second arc under it is the track; `{value}` in the middle counts in step with the same ease.

```js
// @recipe progress-ring
const CX = 640, CY = 360, R = 120, TO = 0.82;            // 82 % filled
const EASE = 'power3.out', AT = 0.3, DUR = 2;
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#0f1424' } },
  { type: 'shape', shape: 'arc', name: 'track', radius: R, startAngle: 0, endAngle: 360,
    initial: { x: CX, y: CY, strokeColor: '#27304d', strokeWidth: 24 } },
  { type: 'shape', shape: 'arc', name: 'progress', radius: R, startAngle: -90, endAngle: -90, strokeCap: 'round',
    initial: { x: CX, y: CY, strokeColor: '#ffd166', strokeWidth: 24 },
    keyframes: [{ at: AT, to: { endAngle: -90 + 360 * TO }, duration: DUR, ease: EASE }] },
  { type: 'text', name: 'percent', text: '{value}%', format: { decimals: 0 },
    style: { fontSize: 72, fontWeight: 'bold', fill: '#ffffff' },
    initial: { x: CX, y: CY, anchorX: 0.5, anchorY: 0.5, value: 0 },
    keyframes: [{ at: AT, to: { value: TO * 100 }, duration: DUR, ease: EASE }] },
];
```

---

## Draw a line, border or check mark on, and type text out

`trimEnd` 0 → 1 strokes a shape's outline on (`trimStart` 0 → 1 afterwards wipes it off); the fill is NOT trimmed, so fade `fillAlpha` in once the outline is done. A rect's outline starts top-left and goes clockwise, a circle's at 12 o'clock. `strokeCap: 'round'` rounds the ends. For text, `visibleChars` types it out and `set: { text }` swaps the string at a time.

```js
// @recipe draw-on-and-type
const ACCENT = '#ffd166', TEAL = '#4cc9f0', GREEN = '#7bd88f';
const drawOn = (at, duration = 1.2) => ({ at, to: { trimEnd: 1 }, duration, ease: 'power2.inOut' });
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#0a0e1a' } },
  // an underline that draws itself
  { type: 'shape', shape: 'line', from: [340, 120], to: [940, 120], trimEnd: 0, strokeCap: 'round',
    initial: { strokeColor: ACCENT, strokeWidth: 6 }, keyframes: [drawOn(0.2, 1)] },
  // a card border (clockwise from the top-left), then its fill fades in
  { type: 'shape', shape: 'rect', width: 360, height: 200, cornerRadius: 28, trimEnd: 0, strokeJoin: 'round',
    initial: { x: 400, y: 360, strokeColor: TEAL, strokeWidth: 8, fillColor: TEAL, fillAlpha: 0 },
    keyframes: [drawOn(0.6, 1.4), { at: 2, to: { fillAlpha: 0.2 }, duration: 0.6 }] },
  // an SVG check mark
  { type: 'shape', shape: 'path', d: 'M 0 50 L 45 95 L 130 0', trimEnd: 0, strokeCap: 'round', strokeJoin: 'round',
    initial: { x: 880, y: 360, strokeColor: GREEN, strokeWidth: 16 }, keyframes: [drawOn(1.8, 0.9)] },
  // a typewriter: left-aligned so it grows rightward; 30 characters over 2.4 s
  { type: 'text', text: 'No mask, no per-letter layers.', at: 3, duration: 5,
    style: { fontSize: 40, fill: '#e8eefc', fontFamily: 'ui-monospace, Menlo, monospace' },
    initial: { x: 120, y: 560, anchorX: 0, anchorY: 0.5, visibleChars: 0 },
    keyframes: [{ at: 0, to: { visibleChars: 30 }, duration: 2.4, ease: 'none' }] },
  // a countdown: one layer whose string changes
  { type: 'text', text: '3', at: 3, duration: 5,
    style: { fontSize: 150, fontWeight: '900', fill: ACCENT },
    initial: { x: 1060, y: 540, anchorX: 0.5, anchorY: 0.5 },
    keyframes: [{ at: 1, set: { text: '2' } }, { at: 2, set: { text: '1' } }, { at: 3, set: { text: 'Go!' } }] },
];
```

---

## Letters and words that animate one by one (`splitText`)

Text content cannot change, so a per-letter or per-word effect is one text layer per piece. `splitText(text, style, { by: 'chars' | 'words' | 'lines', x, y, align })` measures the text with the renderer's own font metrics (kerning kept) and returns each piece's `text`, `x`, `y`, `width`, `index` and `line`: put them straight into the layers. Use the same `style` for the whole text and each piece, and a web font must be loaded first. `measureText(text, style)` gives `{ width, height, lines }` for sizing pills and underlines.

```js
// @recipe split-text
const style = { fontFamily: 'Arial, sans-serif', fontSize: 110, fontWeight: 'bold', fill: '#ffffff' };
const sub = { fontFamily: 'Arial, sans-serif', fontSize: 44, fill: '#ffd166' };
const sequences = [{ type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#0f1424' } }];
splitText('MAKE THINGS', style, { x: 640, y: 200, align: 'center' }).forEach(p => sequences.push({
  type: 'text', name: 'letter-' + p.index, text: p.text, style, at: 0.3 + p.index * 0.06,
  initial: { x: p.x, y: p.y, alpha: 0 },                                   // x / y are the top-left of the letter: anchorX / anchorY stay 0
  keyframes: [{ at: 0, from: { y: p.y + 40, alpha: 0 }, to: { y: p.y, alpha: 1 }, duration: 0.35, ease: 'back.out(2)' }],
}));
splitText('one word at a time', sub, { by: 'words', x: 640, y: 380, align: 'center' }).forEach(p => sequences.push({
  type: 'text', name: 'word-' + p.index, text: p.text, style: sub, at: 1.4 + p.index * 0.25,
  initial: { x: p.x, y: p.y, alpha: 0 },
  keyframes: [{ at: 0, to: { alpha: 1 }, duration: 0.3 }],
}));
return sequences;
```

---

## A wave of delays (`stagger`)

`stagger()` gives the delays for a wave of items, GSAP style: `each` (gap between neighbours) or `amount` (total), `from` (`'start'` `'end'` `'center'` `'edges'` `'random'` or an index), `grid: [cols, rows]`, `ease`, `seed`. Give it a count and it returns numbers; give it layers and it returns them with `at` pushed back.

```js
// @recipe stagger
const style = { fontFamily: 'Arial, sans-serif', fontSize: 96, fontWeight: 'bold', fill: '#ffffff' };
// letters rising from the middle outwards: the same layers, each starting a little later
const letters = stagger(
  splitText('RIPPLE', style, { x: 640, y: 120, align: 'center' }).map(p => ({
    type: 'text', name: 'letter-' + p.index, text: p.text, style, at: 0.2, duration: 4,
    initial: { x: p.x, y: p.y, alpha: 0 },
    keyframes: [{ at: 0, from: { y: p.y + 40, alpha: 0 }, to: { y: p.y, alpha: 1 }, duration: 0.4, ease: 'back.out(2)' }],
  })),
  { each: 0.07, from: 'center' });
// a 6 x 3 grid of tiles that pop in as a ripple from the middle (numbers: use them in `at`)
const COLS = 6, ROWS = 3, delays = stagger(COLS * ROWS, { each: 0.12, grid: [COLS, ROWS], from: 'center', ease: 'sine.out' });
const tiles = delays.map((d, i) => ({
  type: 'shape', shape: 'rect', width: 120, height: 120, cornerRadius: 18, name: 'tile-' + i, at: 1 + d, duration: 3 - d,
  initial: { x: 190 + (i % COLS) * 180, y: 330 + Math.floor(i / COLS) * 150, fillColor: '#4cc9f0', scale: 0 },
  keyframes: [{ at: 0, to: { scale: 1 }, duration: 0.4, ease: 'back.out(2)' }],
}));
return [...letters, ...tiles];
```

---

## Per-letter text in one call (`animateText`)

`animateText(text, style, options)` returns one text layer per character / word / line, laid out like the whole text, each arriving (and leaving) in a wave. `duration` is required: seconds from `at` until the last piece is gone (it throws if the wave does not fit). Letters turn and scale about their own centre.

```js
// @recipe animate-text
const style = { fontFamily: 'Arial, sans-serif', fontSize: 110, fontWeight: 'bold', fill: '#ffffff' };
return [
  ...animateText('Kinetic type', style, { x: 640, y: 230, align: 'center', at: 0.3, duration: 5,
    in: 'rise', out: 'fade', stagger: { each: 0.05, from: 'center' }, idle: { y: 5, rotation: 1 },
    styleFor: p => (p.index === 0 ? { fill: '#ffd166' } : {}) }),
  ...animateText('one word at a time', { fontFamily: 'Arial, sans-serif', fontSize: 44, fill: '#8fa0bf' },
    { by: 'words', x: 640, y: 420, align: 'center', at: 1.6, duration: 3.7, in: 'pop', stagger: { each: 0.25 } }),
];
```

**Vertical Japanese (tategaki)** is one option: `vertical: true`. The characters go down a column and a new line is a new column to the LEFT, so `x` is the RIGHT edge of the first column. The commas sit at the upper right of their cell, and the long vowel mark and the brackets are turned a quarter, as in print.

```js
// @recipe vertical-text
const style = { fontFamily: 'Hiragino Mincho ProN, Yu Mincho, serif', fontSize: 56, fill: '#1c1a17' };
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#efe9dc' } },
  ...animateText('雨のあと、\nコーヒーは「ゆっくり」', style, { x: 900, y: 70, vertical: true, at: 0.3, duration: 5, in: 'fade', stagger: { each: 0.04 } }),
];
```

Presets for `in` / `out`: `rise` (default) `drop` `fade` `pop` `zoom` `slide` `spin`; or `{ from: { x: -30, scale: 0.5, rotation: 20 }, duration: 0.8, ease: 'power3.out' }` (`x` / `y` in `from` are offsets from the resting place, the rest are absolute values). `idle` drifts each piece between the entrance and the exit.

---

## Travel along a path, and morph one shape into another

`followPath()` gives a layer's `x` / `y` (and `rotation` with `orient`) along an SVG path at an even speed. `morphTo` + `morph` turn one path outline into another.

```js
// @recipe follow-path
const ROUTE = 'M 120 560 C 360 120 920 120 1160 560';
return [
  { type: 'shape', shape: 'path', d: ROUTE, duration: 5, initial: { strokeColor: '#ffffff', strokeWidth: 3, strokeAlpha: 0.25 } },     // the route, faint
  { type: 'shape', shape: 'polygon', points: [[-18, -12], [18, 0], [-18, 12]], at: 0.5, duration: 4.5, initial: { fillColor: '#ffd166' },
    keyframes: followPath({ d: ROUTE, duration: 4, ease: 'power2.inOut', orient: true, frameRate: 30 }) },                               // a pointer that faces the way it goes
];
```

```js
// @recipe morph
const BLOB = 'M 640 160 C 780 160 860 260 860 360 C 860 470 770 560 640 560 C 510 560 420 470 420 360 C 420 250 500 160 640 160 Z';
const STAR = 'M 640 130 L 700 300 L 880 300 L 735 410 L 790 590 L 640 480 L 490 590 L 545 410 L 400 300 L 580 300 Z';
return [{
  type: 'shape', shape: 'path', d: BLOB, morphTo: STAR, duration: 4,
  initial: { fillColor: '#ffd166', strokeColor: '#ffffff', strokeWidth: 6, strokeJoin: 'round' },
  keyframes: [{ at: 0.5, to: { morph: 1 }, duration: 1.5, ease: 'power2.inOut', repeat: 1, yoyo: true }],                                // there and back
}];
```

Both outlines are in canvas coordinates. Closed outlines are lined up so they do not twist.

---

## Visuals that follow the music (`audioEnvelope`, `react`)

Analyse the sound **before** `movie.init` (`const env = await audioEnvelope('music.mp3', { frameRate: 30 })`: levels per band per frame and the beats), then `react()` bakes it into keyframes, so playback and export agree. With no audio file at hand, `bpmEnvelope(120, { duration })` is a drum pattern on a tempo (kick = `bass`, snare = `mid`, hats = `treble`), exactly on the beat; it is also how to match sound effects you place on that tempo.

```js
// @recipe audio-react
const env = bpmEnvelope(120, { duration: 8, frameRate: 30 });      // with a file: `const env = await audioEnvelope(url, { frameRate: 30 })`
const bands = ['bass', 'bass', 'bass', 'mid', 'mid', 'mid', 'treble', 'treble'];
const bars = bands.map((band, i) => ({
  type: 'shape', shape: 'rect', name: 'bar-' + i, width: 60, height: 10, cornerRadius: 6, anchorY: 1, duration: 8,
  initial: { x: 330 + i * 86, y: 600, fillColor: ['#ff2d95', '#8a4dff', '#22e0ff'][['bass', 'mid', 'treble'].indexOf(band)] },
  keyframes: react(env, { duration: 8, props: { height: { base: 10, amount: 260, band, release: 0.12 } } }),       // an equaliser bar: up fast, down slowly
}));
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#07060f' } },
  { type: 'shape', shape: 'circle', name: 'orb', radius: 90, duration: 8, initial: { x: 640, y: 260, fillColor: '#ffffff' },
    keyframes: react(env, { duration: 8, props: { scale: { base: 1, amount: 0.5, beats: true, decay: 0.16 }, alpha: { base: 0.55, amount: 0.45, band: 'bass', attack: 0.02, release: 0.15 } } }) },   // a flash on every kick
  ...bars,
];
```

---

## A deck: pages and steps for a presenter (`deck`, `Presenter`)

`deck({ pages, transition })` lays pages out one after the other (each page's layers are written in the page's own time) and turns their `stops` into where a `Presenter` pauses. A **step** is a layer that starts at the previous stop and ends at this one: "press next" plays exactly that animation and stops. A page should last its last stop plus the transition.

```js
// @recipe deck
const paper = { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#f4efe6' } };
const style = { fontFamily: 'Georgia, serif', fontSize: 96, fill: '#1c1a17' };
const line = (text, y, at, dur) => animateText(text, style, { by: 'words', x: 96, y, align: 'left', name: 'l' + y, at, duration: dur - at, in: { from: { y: 40, alpha: 0 }, duration: 0.8, ease: 'power3.out' }, stagger: { each: 0.1 } });
const T = 0.6;
const d = deck({
  transition: { kind: 'slide', direction: 'left', duration: T, ease: 'power3.inOut' },
  pages: [
    { name: 'Hello', duration: 2 + T, stops: [2], sequences: [paper, ...line('The Quiet Hours', 260, 0.4, 2 + T)] },
    { name: 'Two steps', duration: 3.4 + T, stops: [1.6, 3.4], notes: 'pause after the first line',
      sequences: [paper, ...line('We measure speed.', 200, 0.4, 3.4 + T), ...line('We rarely measure attention.', 340, 1.6, 3.4 + T)] },
    { name: 'Thanks', duration: 3, stops: [2], sequences: [paper, ...line('Go slowly.', 260, 0.4, 3)] },
  ],
});
return { duration: d.duration, sequences: d.composition.sequences, transitions: d.composition.transitions };
```

```js
// @docs-only deck-in-page
// in the page: the deck is spread into init; the Presenter (or the Controller, which then shows the stops and a Present button) plays it
import { Movie } from 'pixi-effects';
import { deck, Presenter } from 'pixi-effects/present';     // (add "pixi-effects/present" to the import map)
const movie = new Movie();
await movie.init({ canvas, width: 1280, height: 720, frameRate: 30, ...deck({ /* as above */ }) });
new Presenter(movie, { canvas });     // arrows / Space / Enter / click / swipe = next, ← = back, B = black screen, F = fullscreen, ? = keys
```

---

## A camera flight through a corridor (`cameraPath`, `hideBehindCamera`, a handheld shake)

`cameraPath({ points, duration, ease })` is the camera's route as keyframes: a smooth curve through `[x, y, z]` points at an even speed (an `ease` shapes it; `'power2.in'` is an accelerating rush), facing where it flies (`look: 'ahead'`, the default) or at a fixed `look: [x, y, z]`. Layers the camera passes get `hideBehindCamera: true` (hidden quietly instead of a warning). A handheld shake goes on the camera's **offsets** (`offsetX`, `offsetY`, `offsetZ`, `lookOffsetX`…): they are added to the move, so a `wiggle()` never collides with the dolly.

```js
// @recipe camera-fly-through
const gate = (i, z) => ({
  type: 'composition', name: 'gate-' + i, threeD: true, hideBehindCamera: true, width: 360, height: 480,
  initial: { x: 640, y: 360, z, pivotX: 180, pivotY: 240 },
  sequences: [{ type: 'shape', shape: 'rect', width: 330, height: 450, cornerRadius: 6, initial: { x: 180, y: 240, strokeColor: '#ffe9c4', strokeWidth: 6 } }],
});
return { duration: 8, sequences: [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#0b0a10' } },
  ...Array.from({ length: 9 }, (_, i) => gate(i, -i * 380)),
  { type: 'camera', keyframes: [
    ...cameraPath({ points: [[640, 360, 2200], [690, 330, 900], [640, 360, -3000]], duration: 7, ease: 'power2.in', frameRate: 30 }),
    ...wiggle({ duration: 7, freq: 9, seed: 2, props: { offsetX: { around: 0, amp: 5 }, offsetY: { around: 0, amp: 3 } } }),
  ] },
] };
```

---

## A rack focus (depth of field)

`focus` and `aperture` on the camera blur the `threeD` layers by how far they are from the sharp plane; the layer named in `focus` stays sharp. Writing `focus` alone is enough (`aperture` defaults to 30; 0 turns it off). A rack focus is a normal keyframe on `focus`, and a layer's name works there too (it means that layer's first `z`). Keep `aperture` at 30–60: 100 is extreme.

```js
// @recipe rack-focus
const word = (name, text, x, z, fill) => ({
  type: 'text', name, text, threeD: true, style: { fontSize: 120, fill, fontFamily: 'sans-serif', fontWeight: '700' },
  initial: { x, y: 360, z, anchorX: 0.5, anchorY: 0.5 },
});
return { duration: 5, sequences: [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#101626' } },
  { type: 'camera', initial: { focus: 'near', aperture: 40 },
    keyframes: [
      { at: 1, to: { focus: 'far' }, duration: 1, ease: 'power2.inOut' },          // near -> far
      { at: 3, to: { focus: 'near' }, duration: 1, ease: 'power2.inOut' },         // and back
    ] },
  word('far', 'FAR', 960, -600, '#6ec6ff'),
  word('mid', 'MID', 640, -200, '#ffd166'),
  word('near', 'NEAR', 320, 200, '#ef476f'),
] };
```

---

## Looping motion

`repeat` (a finite count) and `yoyo` go on any keyframe. Total time = `duration × (repeat + 1)`.

```js
// @recipe pulse
return [{
  type: 'shape', shape: 'circle', radius: 40, duration: 6,
  initial: { x: 'GW/2', y: 'GH/2', fillColor: '#ff3b3b' },
  keyframes: [{ at: 0, to: { scale: 1.15 }, duration: 0.5, ease: 'sine.inOut', repeat: 11, yoyo: true }],   // 12 plays x 0.5 s = 6 s
}];
```

---

## Particles (`particles()`: seeded, so every run and export is identical)

`particles()` returns one layer per particle: seeded start, launch angle and speed, size, colour and life, with gravity / wind / drag / sway baked into the keyframes. `count` and `life` are required, and so is the emitter `area` (its centre; add `width` / `height` to spread over a box). `emit: 0` is a burst, `emit: 3` spreads the births over 3 s. `angle`: 0 right, 90 down, −90 up. `blendMode: 'add'` makes overlaps glow. It throws (with the fix) if it would bake too many keyframes: lower `count`, `life` or `sampleRate`.

```js
// @recipe particles
const colors = ['#ffd166', '#ff6b9d', '#4cc9f0', '#ffffff'];
const burst = (at, x, y, seed) => particles({ count: 240, at, life: [1.2, 2], area: { x, y }, speed: [40, 520], gravity: 220, drag: 1.1,
  size: [4, 8], scale: [1, 0.3], colors, fade: { out: 0.7 }, blendMode: 'add', seed, name: 'burst' + seed });   // bursts of sparks
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#0a0f1f' } },
  ...burst(0.5, 400, 260, 1), ...burst(1.6, 880, 200, 2), ...burst(2.8, 640, 330, 3),
];
```

```js
// @recipe particles-snow
return { duration: 10, sequences: [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#16203d' } },
  ...particles({ count: 120, emit: 4, life: [4, 6], area: { x: 640, y: -20, width: 1400 }, angle: 90, speed: [40, 90],
    size: [2, 5], sway: { amp: 30, freq: 0.6 }, fade: { in: 0.5, out: 0.5 }, name: 'snow', seed: 4 }),     // drifting down, swaying
] };
```

---

## Group and orbit with a null layer (`parent`)

A `null` layer draws nothing and only moves; layers with `parent: 'name'` are drawn inside it. Their `x` / `y` are measured from the null's origin, so turning the null makes them circle it. Nulls chain (a moon on a null that is itself on the planet's null).

```js
// @recipe null-orbit
return [
  { type: 'shape', shape: 'circle', radius: 50, duration: 8, initial: { x: 640, y: 360, fillColor: '#ffd166' } },            // the sun
  { type: 'null', name: 'earth-orbit', initial: { x: 640, y: 360 },                                                         // pivot at the sun
    keyframes: [{ at: 0, to: { rotation: 360 }, duration: 8, ease: 'none' }] },
  { type: 'shape', shape: 'circle', radius: 20, parent: 'earth-orbit', initial: { x: 240, y: 0, fillColor: '#4cc9f0' } },     // 240 px from the sun
  { type: 'null', name: 'moon-orbit', parent: 'earth-orbit', initial: { x: 240, y: 0 },                                      // pivot at the earth
    keyframes: [{ at: 0, to: { rotation: 1440 }, duration: 8, ease: 'none' }] },
  { type: 'shape', shape: 'circle', radius: 7, parent: 'moon-orbit', initial: { x: 55, y: 0, fillColor: '#e8eefc' } },        // 55 px from the earth
];
```

---

## Light leaks and colour casts (blend modes)

`blendMode` mixes a layer with everything **below** it. A colour cast is one `soft-light` gradient over the whole picture, a light leak is a `color-dodge` glow that drifts across it, a vignette is a `multiply` radial gradient that goes from clear to dark. Each is ONE layer (a gradient), not a pile of shapes: the blend modes beyond `add` / `screen` / `multiply` cost a full-frame pass each. Over a dark picture a `color-dodge` glow turns the near-black into a muddy red disc: cut it to the bright subject with a matte (`mask: 'letters'`) and put the warm haze in a separate `screen` radial.

```js
// @recipe light-leak
const skyline = Array.from({ length: 9 }, (_, i) => ({
  type: 'shape', shape: 'rect', name: 'block-' + i, width: 90 + (i % 3) * 30, height: 160 + ((i * 53) % 190), anchorX: 0, anchorY: 1,
  initial: { x: 40 + i * 140, y: 650, fillColor: '#0d1220' },
}));
return { duration: 6, sequences: [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', anchorX: 0, anchorY: 0, initial: { x: 0, y: 0 },
    fillGradient: { stops: [[0, '#2a3b66'], [0.55, '#8a5a78'], [1, '#e8a060']] } },
  ...skyline,
  // a colour cast: orange at the top, blue at the bottom, over everything above
  { type: 'shape', shape: 'rect', name: 'cast', width: 'GW', height: 'GH', anchorX: 0, anchorY: 0, blendMode: 'soft-light', initial: { x: 0, y: 0, alpha: 0 },
    fillGradient: { stops: [[0, '#ff9a3c'], [1, '#3c5bff']] },
    keyframes: [{ at: 0.5, to: { alpha: 0.9 }, duration: 2, ease: 'sine.inOut' }] },
  // a light leak: a strong source burning out toward white as it drifts in from the right
  { type: 'shape', shape: 'circle', name: 'leak', radius: 380, blendMode: 'color-dodge', initial: { x: 1500, y: 140 },
    fillGradient: { type: 'radial', stops: [[0, 'rgba(255,120,30,0.9)'], [1, 'rgba(255,120,30,0)']] },
    keyframes: [{ at: 1, to: { x: 900 }, duration: 3.5, ease: 'power2.out' }] },
  // a vignette: clear in the middle, dark at the corners
  { type: 'shape', shape: 'rect', name: 'vignette', width: 'GW', height: 'GH', anchorX: 0, anchorY: 0, blendMode: 'multiply', initial: { x: 0, y: 0 },
    fillGradient: { type: 'radial', radius: 0.8, stops: [[0.5, 'rgba(255,255,255,1)'], [1, 'rgba(60,60,80,1)']] } },
] };
```

---

## A matte shared by several layers (`mask: 'name'`)

Name a layer and write its name as the `mask` of the layers it should cut: the matte is drawn once and **not shown itself**. Here one band sweeps across three lines of text; one line is cut by brightness (`luma`) and one by the opposite of the band (`invert`), so it fills in where the others are cut.

```js
// @recipe shared-matte
const line = (y, text, mask, extra = {}) => ({
  type: 'text', text, mask, style: { fontSize: 120, fill: '#ffffff', fontWeight: 'bold' },
  initial: { x: 640, y, anchorX: 0.5, anchorY: 0.5 }, ...extra,
});
return { duration: 5, sequences: [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', anchorX: 0, anchorY: 0, initial: { x: 0, y: 0, fillColor: '#101626' } },
  // the matte: a bright band that grows to the right; it lives as long as the layers it cuts
  { type: 'shape', shape: 'rect', name: 'band', anchorX: 0, anchorY: 0, width: 0, height: 720,
    initial: { x: 140, y: 0, fillColor: '#ffffff' },
    keyframes: [{ at: 0.4, to: { width: 1000 }, duration: 2, ease: 'power2.inOut' }] },
  line(200, 'ONE MATTE', 'band'),
  line(360, 'SHARED BY', { layer: 'band', channel: 'luma' }),
  line(520, 'THREE LAYERS', { layer: 'band', invert: true }, { initial: { x: 640, y: 520, anchorX: 0.5, anchorY: 0.5, fillColor: '#ffd166' } }),
] };
```

---

## A luma wipe (a transition that follows a brightness map)

`{ kind: 'luma', map: 'radial' }` opens the next scene from the middle; `'linear'` sweeps left to right, `'diagonal'` corner to corner, or give the name of a grayscale image asset (dark parts change first). `softness` is the width of the soft edge and `flip` reverses the direction.

```js
// @recipe luma-wipe
const scene = (name, at, color, label) => ({
  type: 'composition', name, at, duration: 4, width: 1280, height: 720,
  sequences: [
    { type: 'shape', shape: 'rect', width: 1280, height: 720, initial: { x: 640, y: 360, fillColor: color } },
    { type: 'text', text: label, style: { fontSize: 120, fill: '#ffffff', fontWeight: 'bold' }, initial: { x: 640, y: 360, anchorX: 0.5, anchorY: 0.5 } },
  ],
});
return {
  sequences: [scene('a', 0, '#3b5bdb', 'One'), scene('b', 3, '#e64980', 'Two')],     // they overlap for 1 s: 3 to 4
  transitions: [{ kind: 'luma', from: 'a', to: 'b', at: 3, duration: 1, map: 'radial', softness: 0.15 }],
  duration: 7,
};
```

---

## A spotlight across a dark room (light and shadow)

An ambient light keeps the room from going black, a `spot` light sweeps across three cards and they throw shadows on the wall behind them. The shadow needs `castsShadows` on the light **and** on each card; `lookAtX` moves the beam and `x` moves the lamp with it.

```js
// @recipe spot-room
const card = (name, x, fill) => ({
  type: 'shape', shape: 'rect', name, width: 300, height: 200, anchorX: 0.5, anchorY: 0.5, threeD: true, castsShadows: true,
  initial: { x, y: 300, z: 0, fillColor: fill },
});
return { duration: 6, sequences: [
  { type: 'light', kind: 'ambient', initial: { intensity: 0.18 } },
  { type: 'light', kind: 'spot', castsShadows: true,
    initial: { x: 160, y: -120, z: 700, lookAtX: 260, lookAtY: 330, lookAtZ: 0, coneAngle: 34, coneFeather: 0.7, intensity: 1.1, shadowDiffusion: 14 },
    keyframes: [{ at: 0.5, to: { x: 1100, lookAtX: 1020 }, duration: 4.5, ease: 'sine.inOut' }] },
  // the wall, big and behind the cards (a room is layers in distance order: no depth buffer)
  { type: 'shape', shape: 'rect', name: 'wall', width: 1800, height: 900, anchorX: 0.5, anchorY: 0.5, threeD: true, initial: { x: 640, y: 300, z: -260, fillColor: '#6b7280' } },
  card('a', 300, '#e0a458'), card('b', 640, '#58a4e0'), card('c', 980, '#e05876'),
] };
```

---

## Fog that thickens with distance (camera fog)

Fog is the camera's (`fogNear`, `fogFar`, `fogColor`, `fogAmount`): `threeD` layers are mixed toward the fog colour by how far they are. 2D layers are not fogged, so the background is drawn in the fog colour and what is far dissolves into it.

```js
// @recipe fog-depth
const posts = Array.from({ length: 10 }, (_, i) => ({
  type: 'shape', shape: 'rect', name: 'post-' + i, width: 80, height: 420, anchorX: 0.5, anchorY: 1, threeD: true,
  initial: { x: 200 + (i % 2) * 880, y: 620, z: -i * 220, fillColor: '#1f2a44' },
}));
return { duration: 6, sequences: [
  { type: 'shape', shape: 'rect', name: 'sky', width: 'GW', height: 'GH', anchorX: 0, anchorY: 0, initial: { x: 0, y: 0, fillColor: '#9fb4d6' } },
  { type: 'camera', initial: { fogNear: 900, fogFar: 2600, fogColor: '#9fb4d6', fogAmount: 0.95 },
    keyframes: [{ at: 0, to: { offsetZ: -700 }, duration: 6, ease: 'sine.inOut' }] },        // dolly in: the nearer posts come out of the mist
  ...posts,
] };
```

---

## A flowing colour field (a `shader` layer)

A shader is a layer drawn by a formula: write a Shadertoy `mainImage`. `iTime` is the layer's own clock, the `uniforms` are declared for you and keyframes move them (`'uniforms.speed'`, and a component of a colour as `'uniforms.tint.2'`). Opaque by default.

```js
// @recipe shader-plasma
return { duration: 6, sequences: [
  { type: 'shader', name: 'plasma',
    fragment: `
      void mainImage(out vec4 fragColor, in vec2 fragCoord) {
        vec2 uv = fragCoord / iResolution.xy;
        float v = sin(uv.x * 9.0 + iTime * speed) + sin(uv.y * 7.0 - iTime * speed * 1.3) + sin((uv.x + uv.y) * 5.0 + iTime);
        vec3 deep = vec3(0.04, 0.02, 0.18);
        fragColor = vec4(mix(deep, tint, 0.5 + 0.25 * v), 1.0);
      }`,
    uniforms: { tint: '#ff7a3d', speed: 0.6 },
    keyframes: [{ at: 0, to: { 'uniforms.speed': 2, 'uniforms.tint.2': 0.9 }, duration: 6, ease: 'sine.inOut' }] },
  { type: 'text', text: 'PLASMA', style: { fontSize: 140, fill: '#ffffff', fontWeight: 'bold', letterSpacing: 12 }, initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 } },
] };
```

---

## Text seen through water (the `warp` filter)

`warp` bends a layer's picture: `kind: 'wave'` is a travelling wave (the surface of water, a flag), `kind: 'haze'` is drifting noise (heat shimmer). `strength` is the largest shift in px, `scale` the wavelength in px, `speed` how fast it moves (0 stands still). It follows the frame's time by itself, and its options move with keyframes by the filter's name.

```js
// @recipe warp-water
return { duration: 6, sequences: [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', anchorX: 0, anchorY: 0, initial: { x: 0, y: 0 },
    fillGradient: { stops: [[0, '#0b3a5c'], [1, '#021a2e']] } },
  { type: 'text', text: 'UNDER WATER', style: { fontSize: 120, fill: '#d8f3ff', fontWeight: 'bold', letterSpacing: 6 },
    initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
    filters: [{ type: 'warp', name: 'ripple', kind: 'wave', strength: 6, scale: 70, speed: 0.8, angle: 90 },
              { type: 'warp', kind: 'haze', strength: 3, scale: 30, speed: 0.4 }],
    keyframes: [{ at: 0, to: { 'filters.ripple.strength': 16 }, duration: 6, ease: 'sine.inOut' }] },
] };
```

---

## A hand-held shake and a flickering light (`wiggle`, seeded)

`wiggle()` returns keyframes (spread it into `keyframes`): each property drifts between seeded random targets and ends back at `around`. Use `freq` ~3 for a slow float, 8+ for a shake, `ease: 'none'` for a jittery flicker. Per-layer variety: give each its own `seed`.

```js
// @recipe wiggle
return [
  // a title that floats and tilts a little, like a hand-held camera
  { type: 'text', text: 'NIGHT SHIFT', duration: 6,
    style: { fontSize: 120, fill: '#ffffff', fontWeight: '800' },
    initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
    keyframes: wiggle({ duration: 6, freq: 3, seed: 1, props: { x: { around: 'GW/2', amp: 8 }, y: { around: 'GH/2', amp: 6 }, rotation: { around: 0, amp: 1.2 } } }) },
  // a neon sign whose light stutters (fast, straight-line steps)
  { type: 'shape', shape: 'rect', width: 520, height: 8, duration: 6,
    initial: { x: 'GW/2', y: 'GH/2 + 90', fillColor: '#ff4d6d' },
    keyframes: wiggle({ duration: 6, freq: 12, seed: 5, ease: 'none', props: { alpha: { around: 0.8, amp: 0.2 } } }) },
  // dust: every speck has its own seed, so its drift is its own and never changes between runs
  ...Array.from({ length: 24 }, (_, i) => ({
    type: 'shape', shape: 'circle', radius: 2 + rand(i) * 3, duration: 6,
    initial: { x: 40 + rand(i + 100) * 1200, y: 40 + rand(i + 200) * 640, fillColor: '#ffffff', fillAlpha: 0.25 + rand(i + 300) * 0.4 },
    keyframes: [...wiggle({ duration: 6, freq: 0.6, seed: i, props: { y: { around: 40 + rand(i + 200) * 640, amp: 30 } } })],
  })),
];
```

---

## Gradients and vignettes

`fillGradient` fills a shape with a linear or radial gradient (positions are 0–1 of the shape's own bounds; colours can have alpha). A radial gradient from transparent to dark, on a full-screen rect placed last, is a vignette.

```js
// @recipe gradient-background
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2' },
    fillGradient: { stops: [[0, '#1b2a6b'], [0.6, '#7b3fe4'], [1, '#ff6a88']] } },                  // top → bottom
  { type: 'shape', shape: 'rect', width: 520, height: 200, cornerRadius: 30, initial: { x: 'GW/2', y: 'GH/2' },
    fillGradient: { angle: 0, stops: [[0, '#00f5a0'], [1, '#00d9f5']] } },                          // left → right
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2' },
    fillGradient: { type: 'radial', radius: 0.75, stops: [[0.45, 'rgba(0,0,0,0)'], [1, 'rgba(0,0,0,0.7)']] } },   // vignette, last = on top
];
```

---

## A gradient that moves (a turning fade, a drifting glow, letters that change colour)

A keyframe's `fillGradient` is partial: write only what moves. `colorSpace: 'oklch'` keeps the fade vivid.

```js
// @recipe gradient-shift
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', colorSpace: 'oklch', initial: { x: 'GW/2', y: 'GH/2' },
    fillGradient: { angle: 20, stops: [[0, '#1b2a6b'], [1, '#7b3fe4']] },
    keyframes: [{ at: 0, duration: 4, ease: 'sine.inOut', to: { fillGradient: { angle: 200, stops: [[0, '#7b3fe4'], [1, '#ff6a88']] } } }] },
  { type: 'shape', shape: 'circle', radius: 260, initial: { x: 'GW/2', y: 'GH/2' },
    fillGradient: { type: 'radial', center: [0.2, 0.2], radius: 0.3, stops: [[0, 'rgba(255,255,255,0.9)'], [1, 'rgba(255,255,255,0)']] },
    keyframes: [{ at: 0, duration: 4, ease: 'sine.inOut', to: { fillGradient: { center: [0.8, 0.8], radius: 0.6 } } }] },
  { type: 'text', text: 'SHIFT', name: 'title', style: { fontSize: 220, fontWeight: '900' }, colorSpace: 'oklch',
    initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
    fillGradient: { angle: 0, stops: [[0, '#ffd60a'], [1, '#22c55e']] },
    keyframes: [{ at: 0, duration: 4, to: { fillGradient: { angle: 180, stops: [[0, '#00e5ff'], [1, '#ff2d55']] } } }] },
];
```

---

## Film grain over the whole picture

`grain` is seeded, new every 1/`fps` s (24 by default), mid-tone weighted and the same on every GPU. Put it on the root `filters` for the film look, or on one layer. (`noise` is not grain: it is frozen and lifts blacks.) It costs video bitrate.

```js
// @recipe film-grain
// the scene is wrapped in a composition layer that carries the filter (on a whole movie, put the same filter in `composition: { filters: [...] }`)
const scene = [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#3a4a6b' } },
  { type: 'text', text: 'FILM', name: 'title', at: 0.3, duration: 3.7, style: { fontSize: 200, fontWeight: '900', fill: '#f4f1ea' },
    initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5, alpha: 0 }, keyframes: [{ at: 0, to: { alpha: 1 }, duration: 0.8 }] },
];
return [{ type: 'composition', name: 'film', width: 'GW', height: 'GH', sequences: scene, filters: [{ type: 'grain', name: 'g', amount: 0.06, size: 2, color: 0.2 }] }];
```

---

## Generated placeholder images (no photos available)

Draw on a canvas and register `canvas.toDataURL()` as an asset (`data:` URLs work). Make the image at least canvas-sized (1920×1080 for a 1280×720 movie) so `kenBurns` zooms stay sharp.

```js
// @docs-only placeholder-images
function placeholderPhoto(name, hueA, hueB, w = 1920, h = 1080) {
  const c = Object.assign(document.createElement('canvas'), { width: w, height: h });
  const g = c.getContext('2d');
  const grad = g.createLinearGradient(0, 0, w, h);
  grad.addColorStop(0, `hsl(${hueA} 70% 45%)`); grad.addColorStop(1, `hsl(${hueB} 70% 25%)`);
  g.fillStyle = grad; g.fillRect(0, 0, w, h);
  return { name, src: c.toDataURL() };
}
// await movie.init({ assets: [placeholderPhoto('p1', 210, 280), placeholderPhoto('p2', 10, 60)], composition: { … } })
```

---

## Metallic three.js object

`ctx.renderer` is a normal `WebGLRenderer`, so an environment map works; lights alone make `metalness: 1` look black. `three/addons` is not in the importmap: build the environment yourself. Size the layer to the area you want (it clips at its own rectangle) and pull the camera back (`z ≈ 5.4` for a radius-1 torus knot at fov 50).

```js
// @docs-only metallic-three
// registerThree();  const THREE = await import('three');
three({
  type: 'three', width: 'GW * 0.56', height: 'GH * 0.9', initial: { x: 'GW * 0.77', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
  setup: (ctx) => {
    const env = new THREE.Scene();
    for (const [x, y, z] of [[4, 4, 4], [-4, 2, -4], [0, -4, 4]]) {
      const lamp = new THREE.Mesh(new THREE.BoxGeometry(2, 2, 2), new THREE.MeshBasicMaterial({ color: 0xffffff }));
      lamp.position.set(x, y, z); env.add(lamp);
    }
    ctx.scene.environment = new THREE.PMREMGenerator(ctx.renderer).fromScene(env).texture;
    const knot = new THREE.Mesh(new THREE.TorusKnotGeometry(1, 0.32, 128, 32), new THREE.MeshStandardMaterial({ color: 0xcfd8ff, metalness: 1, roughness: 0.25 }));
    ctx.scene.add(knot);
    ctx.camera.position.z = 5.4;
    return { objects: { knot } };
  },
  keyframes: [{ at: 0, to: { 'three.knot.rotation.y': Math.PI * 2 }, duration: 6 }],
})
```

## A glTF model that runs in the same space as the flat layers (`threeGltf`, `followCamera`)

A `three` layer is the free box: `threeGltf` and `threeFrameCamera` (from `pixi-effects/three`) only do the two things that are easy to get wrong by hand: pose the clip by the layer's time (`AnimationMixer.setTime`, never `mixer.update(dt)`: a seek and an export must give the same frame) and frame the whole model. With `followCamera` / `followLights` the composition's own `camera` and `light` layers drive the scene, so ONE `cameraPath()` or `orbit()` flies through the flat layers and the model together.

Rules to read before you copy:
- **Placement.** The scene is in composition pixels with y flipped: the composition point `(x, y, z)` is `object.position.set(x, -y, z)`. The middle of a 1280 × 720 composition is `position.set(640, -360, 0)`.
- **Size.** `fit(px)` scales the model so its longest side (its bounding box in the file's bind pose, which may be longer than a running pose) is `px` pixels. Size it against the other layers: a 480 px fox beside a 420 px title.
- **Facing.** glTF models usually face +z (toward the viewer). `object.rotation.y = Math.PI / 2` turns one to run toward +x.
- **Light.** With a `light` layer present, `threeD` text and shapes are lit too: a bright colour can blow out, and a dark one can sink. `lit: false` keeps a layer's own colour.
- **Order.** The three layer is an ordinary layer in the stack: flat `threeD` layers listed after it are drawn over it (a label), those before it are behind it (a title). Depth does not interleave them.
- **Clips.** `npx pixi-effects probe Fox.glb` lists the clip names and the size of the model before you write code.
- **The page.** The template's import map already has `three` and `three/addons/`; uncomment the `import { registerThree, threeGltf } from 'pixi-effects/three'` line and call `registerThree()` before `movie.init`. The `.glb` is fetched next to the page.

```js
// @docs-only gltf-in-space
// import { registerThree, threeGltf } from 'pixi-effects/three';   registerThree();   (before movie.init)
// composition 1280 x 720, 4 s
let fox;
return [
  { type: 'camera', keyframes: [{ at: 0, from: { x: 420, lookAtX: 'GW/2' }, to: { x: 860 }, duration: 4, ease: 'sine.inOut' }] },   // moves the text card AND the fox
  { type: 'light', kind: 'ambient', initial: { intensity: 0.7 } },
  { type: 'light', kind: 'parallel', initial: { x: 140, y: -260, z: 900, lookAtX: 'GW/2', lookAtY: 'GH/2', lookAtZ: 0, intensity: 1.2 } },
  { type: 'text', text: 'FOX', threeD: true, style: { fontSize: 420, fontWeight: '900', fill: '#ff7a1a' }, initial: { x: 'GW/2', y: 'GH/2', z: -500, anchorX: 0.5, anchorY: 0.5 } },
  { type: 'three', name: 'fox', followCamera: true, followLights: true,                 // a plain spec: the layer covers the composition and sits in the stack like any layer
    setup: async (ctx) => {
      fox = await threeGltf('Fox.glb', { animation: 'Run' });                            // a clip name, an index, or false (the bind pose); speed, offset, loop
      fox.fit(480);                                                                      // the longest side in px: the model is in metres, the scene in pixels
      fox.object.rotation.y = Math.PI / 2;                                               // faces +x
      fox.object.position.set(640, -400, 0);                                             // the composition point (640, 400), y flipped
      ctx.scene.add(fox.object);
    },
    update: (t) => fox.pose(t) },                                                        // the clip at the layer's time: a function of t
];
```

Without `followCamera` the layer keeps its own camera: `threeFrameCamera(ctx.camera, fox.object)` puts it where the whole model fits (a three-quarter view; `{ direction, margin }` change it). Shadows work too: give a light `castsShadows: true` and mark your meshes `castShadow` / `receiveShadow` (a wall that receives, a model that casts; `threeGltf` models cast with `model.object.traverse(o => { if (o.isMesh) o.castShadow = true; })`). Fog: `followFog: true`. A `three` wall under `MeshStandardMaterial` is much brighter than a flat card under the same light (three lights in linear light with physical materials, the composition shades sRGB values), so a flat 2D caption on a three wall can look dark: raise its colour, or give the wall a darker `color`, or make the wall a `MeshLambertMaterial` with three's colour management off (`npx pixi-effects help followLights`).

## A model running through a spotlight, with its shadow on a wall (`castsShadows` in three)

A dark room: a wall that RECEIVES the shadow, a model that CASTS it, one spot light that sweeps (a `light` layer with keyframes, so it moves like any layer), and a flat caption that the same light reveals. The light is the composition's; the layer mirrors it into three (`followLights`). A `three` wall under `MeshStandardMaterial` is brighter than a flat card under the same light (three lights in linear light, the composition shades sRGB values): pick the wall's `color` dark (a mid grey `0x6d717b` reads as a bright disc, not a dark room; `0x3f434b` is moody and the shadow still shows) and look at the picture. Placement, size and facing are as in `gltf-in-space` (`position.set(x, -y, z)`; `fit(px)`; `rotation.y = Math.PI / 2` runs the model toward +x); the `.glb` path is relative to the page.

```js
// @docs-only gltf-shadow-room
// import { registerThree, threeGltf } from 'pixi-effects/three';   registerThree();   import * as THREE from 'three';   (before movie.init)
// composition 1280 x 720, 5 s. The model faces +z in the file: rotation.y = PI / 2 runs it toward +x.
let fox;
return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#030305' } },
  { type: 'light', kind: 'ambient', initial: { intensity: 0.05 } },
  { type: 'light', kind: 'spot', castsShadows: true, initial: { x: -160, y: 430, z: 560, lookAtX: 260, lookAtY: 340, lookAtZ: -100, coneAngle: 40, coneFeather: 0.7, intensity: 1.6, shadowDiffusion: 6 },
    keyframes: [{ at: 0.3, to: { x: 600, lookAtX: 1020 }, duration: 4.4, ease: 'sine.inOut' }] },      // the beam sweeps across the wall
  { type: 'three', name: 'world', followCamera: true, followLights: true,
    setup: async (ctx) => {
      fox = await threeGltf('Fox.glb', { animation: 'Run' });
      fox.fit(360); fox.object.rotation.y = Math.PI / 2;
      fox.object.traverse((o) => { if (o.isMesh) { o.castShadow = true; o.receiveShadow = true; } });         // the model casts
      fox.object.position.set(150, -540, 0);                                                                   // the composition point (150, 540), y flipped: it runs on the floor
      ctx.scene.add(fox.object);
      const wall = new THREE.Mesh(new THREE.PlaneGeometry(2600, 1400), new THREE.MeshStandardMaterial({ color: 0x3f434b, roughness: 0.95 }));
      wall.position.set(640, -330, -130); wall.receiveShadow = true; ctx.scene.add(wall);                      // the wall receives
    },
    update: (t) => { fox.pose(t); fox.object.position.x = 150 + 980 * Math.min(1, t / 4.6); } },              // placed from t: a function of the time
  { type: 'text', text: 'RUN THROUGH THE LIGHT', threeD: true, style: { fontSize: 46, fontWeight: '800', fill: '#ffffff', letterSpacing: 6 },
    initial: { x: 'GW/2', y: 330, z: -126, anchorX: 0.5, anchorY: 0.5 } },                                      // a flat caption just in front of the wall, lit by the same light
];
```

A moving, shadow-casting model is held to "a function of the time" by `check`: place it from `t` in `update` (as above) and let `threeGltf` load it (it draws a skinned mesh always: three culls it by a bounding sphere that does not follow it).

## Click a layer: what is under the pointer (`movie.pick`)

`movie.pick(x, y)` answers "what is drawn under this point, at the frame on screen" with no hit-testing code of yours: a flat layer by its own shape, a `threeD` card by its projected quad, a `three` layer by a ray (the hit says which object). `movie.canvasPoint(event)` turns a pointer event into canvas pixels, whatever size the canvas is shown at. Name the layers you want to react to: `only` / `ignore` take layer names (or paths; a group's name stands for everything in it). A `three` layer covers its whole picture but only what the ray meets is a hit: elsewhere the layers below are hit (the title, the background).

An interactive page is the template with three changes: no `Controller` (it adds a player bar), `movie.loop = true` or `movie.pause()` as the page needs, and a handler on the canvas. A text that changes on a click is a **variable** (`{title}` in the text, `vars: { title }`, then `movie.setVars({ title })`: it rebuilds at the same frame, and a paused movie stays paused); `at` and `duration` are not variables. A **reaction** is a short animation: put its keyframes on the layer, seek to its start and play (`await movie.gotoFrame(0, true); movie.play()`); a movie that is not looping stops at its end by itself.

```js
// @docs-only pick-click
// the page: a title, and a fox (a three layer, name 'fox', followCamera) running in front of it
//   await movie.init({ canvas, width: 960, height: 540, duration: 6, frameRate: 30, loop: true, vars: { title: 'CATCH THE FOX', hint: 'click it' },
//     composition: { sequences: [
//       { type: 'text', name: 'title', text: '{title}', style: { fontSize: 110, fill: '#ffffff' }, initial: { x: 'GW/2', y: 150, anchorX: 0.5, anchorY: 0.5 } },
//       { type: 'text', name: 'hint', text: '{hint}', style: { fontSize: 32, fill: '#8fa0c8' }, initial: { x: 'GW/2', y: 500, anchorX: 0.5, anchorY: 0.5 } },
//       { type: 'three', name: 'fox', followCamera: true, setup: ..., update: (t) => fox.pose(t) },        // recipe gltf-in-space
//     ] } });
//   movie.play();
const canvas = document.getElementById('stage');
movie.hover({ only: ['fox'], cursor: true,                         // 'pointer' over the fox, the normal arrow elsewhere (the title and the background are not listed)
  onEnter: (hit) => console.log('over', hit.name),
  onLeave: (hit) => console.log('left', hit.name) });
canvas.addEventListener('click', async (event) => {
  const hit = movie.pick(...movie.canvasPoint(event), { only: ['fox'] });   // null for a click anywhere else: nothing happens
  if (!hit) return;
  movie.pause();                                                    // the fox stops running
  await movie.setVars({ title: 'GOTCHA!', hint: 'the fox stopped running' });   // the text is a variable: the movie is built again at this frame, still paused
});
// to ask about another frame, or from a test:  await movie.snapshot(90);  movie.pick(480, 270)
// after something outside the movie that a layer reads changes while the movie is paused:  await movie.redraw();
```

`pick` reads the frame as the last draw left it (it takes no time and has no clock). `movie.pick(x, y, { alpha: 0.1 })` looks at the picture and not its box (a transparent corner of a logo, the clear part of a drawn circle: not a hit). Dragging is built on `pick` too: recipes `drag-drop` (a flat layer) and `drag-3d` (an object of a three layer). **Test an interactive page** with `check --do "click fox; drag card > 770,240"` (real mouse events, what was under the pointer, the variables that changed, a picture per step: `SKILL.md`, "Interactive pages").

## Drag a layer and drop it on a target (`pick` and variables)

A layer whose place is two variables moves when the page sets them: `movie.setVars({ cx, cy })` builds the composition again at the same frame (tens of milliseconds for a light composition; calls that fall behind are joined, so it is safe from `pointermove`). A glow whose `alpha` is a variable is a light that is on or off (`alpha: 'doneLit'`: any number a layer takes can be a variable name; write 0 and 1, not booleans). `pick` says what is taken (`only`) and what lies under it when it is let go (`ignore` the dragged layer). Listen on the window while it is held, so the pointer may leave the canvas. A heavy composition (a long sound, many layers) rebuilds slowly: keep what moves a light layer. A `three` layer with a `name` keeps its scene and model across `setVars` (its `setup` runs once), so its place can be a variable read in `update`; for a paused three scene `await movie.redraw()` is still the lightest (recipe `drag-3d`).

A card with a label is two layers: name the card's group (a `composition` layer, whose children are one target) or pass both names (`only: ['card', 'card-label']`). A zone with a label is two layers as well: ask with `only: ['done', 'trash']` and the labels are not in the way. Which zone is the card over: the zone under the card's middle (`pick(cx, cy)`), not under the pointer.

```js
// @docs-only drag-drop
// the page: a canvas with  style="touch-action: none"  (a finger dragging must not scroll the page)
//   await movie.init({ canvas, width: 960, height: 540, vars: { cx: 200, cy: 270, doneLit: 0 }, composition: { sequences: [
//     { type: 'shape', shape: 'rect', name: 'done', width: 260, height: 200, initial: { x: 770, y: 270, anchorX: 0.5, anchorY: 0.5, fillColor: '#182038' } },
//     { type: 'shape', shape: 'rect', name: 'done-glow', width: 260, height: 200, initial: { x: 770, y: 270, anchorX: 0.5, anchorY: 0.5, fillColor: '#3ddc97', alpha: 'doneLit' } },   // the light: a variable
//     { type: 'composition', name: 'card', width: 200, height: 120, duration: 1, initial: { x: 'cx', y: 'cy', pivotX: 100, pivotY: 60 }, sequences: [   // the card and its label: ONE target (the group's name); a composition turns and sits about its pivot
//       { type: 'shape', shape: 'rect', name: 'face', width: 200, height: 120, cornerRadius: 14, initial: { x: 100, y: 60, anchorX: 0.5, anchorY: 0.5, fillColor: '#f2c14e' } },
//       { type: 'text', name: 'label', text: 'Task', style: { fontSize: 34, fill: '#1b1b1b' }, initial: { x: 100, y: 60, anchorX: 0.5, anchorY: 0.5 } },
//     ] },
//   ] } });
//   movie.pause();                                    // a still picture: nothing plays while it is dragged
movie.hover({ only: ['card'], cursor: 'grab' });                     // the cursor says it can be taken
canvas.addEventListener('pointerdown', (e) => {
  const [x, y] = movie.canvasPoint(e);
  if (!movie.pick(x, y, { only: ['card'] })) return;                 // only the card (and its label) can be picked up
  const grip = { dx: movie.vars.cx - x, dy: movie.vars.cy - y };      // where in the card it was taken, so it does not jump
  canvas.style.cursor = 'grabbing';
  const place = (ev) => {
    const [px, py] = movie.canvasPoint(ev);
    const cx = px + grip.dx, cy = py + grip.dy;
    const over = movie.pick(cx, cy, { only: ['done'] });             // the zone under the card's middle: it lights while the card is over it
    return movie.setVars({ cx, cy, doneLit: over ? 0.6 : 0 });
  };
  const move = (ev) => { place(ev); };
  const up = async (ev) => {
    window.removeEventListener('pointermove', move); window.removeEventListener('pointerup', up);
    canvas.style.cursor = '';
    await place(ev);                                                  // the card is where it was let go: now ask what is under it
    const [px, py] = movie.canvasPoint(ev);
    const under = movie.pick(px + grip.dx, py + grip.dy, { only: ['done'] });
    if (under) await movie.setVars({ cx: 770, cy: 270, doneLit: 0 });          // snap into the middle of the zone
    else await movie.setVars({ cx: 200, cy: 270, doneLit: 0 });                // anywhere else: back where it started
  };
  window.addEventListener('pointermove', move); window.addEventListener('pointerup', up);
});
```

## Drag an object of a three layer (`hit.three.grab`)

The scene is the `three` layer's own, so what is taken is a three object: `movie.pick` says which (`hit.three.object`), `hit.three.grab(plane)` fixes a plane through the point that was taken, and `grab.move(x, y)` says where the pointer's ray meets that plane and how far that is from the point taken (`delta`). Planes: `'wall'` (z constant: slides across the picture), `'floor'` (horizontal: slides along the ground), `'screen'` (facing the camera), or a normal. The layer's `update` reads the object's place from a variable of the page, and `await movie.redraw()` draws the paused frame again after each move (a playing movie draws it by itself).

```js
// @docs-only drag-3d
// the three layer (followCamera: true, so the composition's camera is the layer's):  update: () => { cube.position.set(pos.x, pos.y, pos.z); }
// the page's state is the cube's place in three's units (the composition's (x, y, z) is (x, -y, z)):  const pos = { x: 480, y: -270, z: 0 };
canvas.addEventListener('pointerdown', (e) => {
  const hit = movie.pick(...movie.canvasPoint(e), { only: ['world'] });
  if (hit?.three?.object !== 'cube') return;                         // only the cube can be taken
  const grab = hit.three.grab('wall');                               // it slides on the wall plane through the point it was taken at
  const start = { ...pos };                                          // where it was
  const move = (ev) => {
    const m = grab.move(...movie.canvasPoint(ev));                   // the ray of the pointer meets the plane here, this far from the point taken
    if (!m) return;                                                  // a ray that never meets the plane (a floor seen edge-on): leave it
    pos.x = start.x + m.delta[0]; pos.y = start.y + m.delta[1]; pos.z = start.z + m.delta[2];
    movie.redraw();                                                  // the layer reads `pos`: draw the frame again
  };
  const up = () => { window.removeEventListener('pointermove', move); window.removeEventListener('pointerup', up); };
  window.addEventListener('pointermove', move); window.addEventListener('pointerup', up);
});
```

The grabbed point stays under the pointer exactly, whatever the camera does (the maths is the camera's own ray, not a guess of pixels per unit).

**On the ground:** use `'floor'`. Then `m.delta[1]` is 0: write only `pos.x` and `pos.z`, never `y`, and the object stays on the floor. A pointer ray that points above the horizon never meets the floor and `move` answers null (the `if (!m) return` keeps the object where it was). To see a floor in perspective: a camera above it, looking down at it (the composition's `y` runs DOWN, so a camera `y` smaller than the floor's is above it), and a floor big enough that its far edge stays above the horizon of the view.

```js
// @docs-only drag-3d-floor
// in the composition:   { type: 'camera', initial: { x: 480, y: 40, z: 900, lookAtX: 480, lookAtY: 340, lookAtZ: 0 } },
//                       { type: 'three', name: 'world', followCamera: true, setup, update: () => cube.position.set(pos.x, pos.y, pos.z) }
// in setup:   the floor, 9000 px square, turned flat, its top at the composition's y = 440 (three's -440), and the cube standing on it (a 100 px cube: its middle 50 px above)
//   const floor = new THREE.Mesh(new THREE.PlaneGeometry(9000, 9000), new THREE.MeshLambertMaterial({ color: 0x3b4f7a }));
//   floor.rotation.x = -Math.PI / 2;  floor.position.set(480, -440, -400);  ctx.scene.add(floor);
const pos = { x: 600, y: -390, z: -40 };                               // y is the cube's middle: it never changes
canvas.addEventListener('pointerdown', (e) => {
  const hit = movie.pick(...movie.canvasPoint(e), { only: ['world'] });
  if (hit?.three?.object !== 'cube') return;                         // the floor is a hit of the same layer, with another object name
  const grab = hit.three.grab('floor');
  const start = { ...pos };
  const move = (ev) => {
    const m = grab.move(...movie.canvasPoint(ev));
    if (!m) return;                                                  // above the horizon: leave it
    pos.x = Math.max(60, Math.min(900, start.x + m.delta[0]));       // along the floor, kept inside it
    pos.z = Math.max(-600, Math.min(300, start.z + m.delta[2]));     // nearer or farther; y is never written
    movie.redraw();
  };
  const up = () => { window.removeEventListener('pointermove', move); window.removeEventListener('pointerup', up); };
  window.addEventListener('pointermove', move); window.addEventListener('pointerup', up);
});
```

## Subtitles from an SRT file

Subtitles are just text layers. The function reads a `.srt` (numbers, `00:00:01,000 --> 00:00:03,500`, the words) and returns one layer per cue: it appears and disappears over 0.12 s, sits 90 px above the bottom edge, wraps at 1000 px (about 80 % of a 1280 px picture) and has a black outline so it reads on any picture. Two cues that overlap in time are drawn on top of each other: split a long line into two lines in the `.srt` rather than relying on wrapping. Check the result with `pixi-effects check`; it reports text that is cut off by the edge.

```js
// @recipe subtitles
// SRT text -> one text layer per cue. Paste your .srt into SRT; the function does the rest.
const SRT = `1
00:00:00,500 --> 00:00:02,800
Hello, and welcome.

2
00:00:03,000 --> 00:00:05,500
Subtitles are just text layers
that appear and disappear.`;

function srt(text, { bottom = 90, size = 44, color = '#ffffff', width = 1000 } = {}) {
  const sec = (h, m, s, ms) => +h * 3600 + +m * 60 + +s + +ms / 1000;
  return text.replace(/\r/g, '').trim().split(/\n\s*\n/).flatMap((block) => {
    const lines = block.split('\n');
    const i = lines.findIndex((l) => l.includes('-->'));
    const t = i < 0 ? null : lines[i].match(/(\d+):(\d+):(\d+)[,.](\d+)\s*-->\s*(\d+):(\d+):(\d+)[,.](\d+)/);
    if (!t) return [];
    const at = sec(t[1], t[2], t[3], t[4]), end = sec(t[5], t[6], t[7], t[8]);
    return [{
      type: 'text', name: `sub ${at.toFixed(2)}`, text: lines.slice(i + 1).join('\n'), at, duration: end - at,
      style: { fontFamily: 'Arial, sans-serif', fontSize: size, fontWeight: 'bold', fill: color, align: 'center', wordWrap: true, wordWrapWidth: width, stroke: { color: '#000000', width: 6 } },
      initial: { x: 'GW/2', y: `GH - ${bottom}`, anchorX: 0.5, anchorY: 1 },
      keyframes: [{ at: 0, from: { alpha: 0 }, to: { alpha: 1 }, duration: 0.12 }, { at: -0.12, to: { alpha: 0 }, duration: 0.12 }],
    }];
  });
}

return [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#1d2433' } },
  ...srt(SRT),
];
```

## One source, two formats (16:9 and 9:16), and a photo inside a region

Only when a vertical cut is wanted (ask first). It is not a crop of the wide one: write each scene as a function of a layout, switch with a query (`?f=9x16`), and render each format on its own: `npx pixi-effects check film.html --query f=9x16`, `npx pixi-effects render film.html --query f=9x16 -o film-9x16.mp4`. `photo()` fits a picture into any rectangle like CSS `cover` (scale from the image's own size, a mask for the rectangle); `scale: 'cover'` only fits the PARENT.

```js
// @docs-only two-formats
const PORTRAIT = new URLSearchParams(location.search).get('f') === '9x16';
const W = PORTRAIT ? 1080 : 1920, H = PORTRAIT ? 1920 : 1080, MX = PORTRAIT ? 76 : 150;      // margins: nothing important in the outer 5 %
const IMG = { hero: [1920, 1280] };                                                           // each photo's size (assets: [{ name: 'hero', src: '...' }])
const photo = (key, x, y, w, h, duration) => {
  const cover = Math.max(w / IMG[key][0], h / IMG[key][1]);
  return { type: 'image', asset: key, duration,
    mask: { type: 'shape', shape: 'rect', width: w, height: h, initial: { x: x + w / 2, y: y + h / 2, fillColor: '#fff' } },     // the mask lives in the parent's coordinates
    initial: { x: x + w / 2, y: y + h / 2, anchorX: 0.5, anchorY: 0.5, scale: cover },                                             // image anchors go in `initial`
    keyframes: [{ at: 0, to: { scale: cover * 1.1 }, duration, ease: 'sine.inOut' }] };                                             // a slow push
};
const scene = { type: 'composition', name: 'hook', at: 0, duration: 5.5, width: W, height: H, sequences: [
  photo('hero', 0, 0, W, H, 5.5),
  { type: 'text', text: 'Headline', initial: { x: MX, y: PORTRAIT ? 1150 : 620 }, style: { fontSize: PORTRAIT ? 100 : 112, fill: '#fff' } },   // wide: lower left; tall: lower third
] };
// movie.init({ width: W, height: H, composition: { sequences: [scene] } })
```

---

## A batch of videos from a table (one video per row)

A batch of videos is a loop outside the video. The page reads what changes from its address (`new URLSearchParams(location.search)`), and `pixi-effects render --query "name=Aiko&score=92"` opens it with those values. Names with spaces or non-Latin letters must be URL-encoded (`jq -sRr @uri` as below, or `encodeURIComponent` in Node). Each video starts its own browser, so N videos cost N start-ups: try one with `--draft` (half size, fast), then render the real ones. To make the pieces of one row differ in more than text, use the same values to pick colours or an image name.

```js
// @docs-only batch-page
// batch.html: the same video, with the words taken from the address (?name=Aiko&score=92)
const q = new URLSearchParams(location.search);
const NAME = q.get('name') ?? 'World';
const SCORE = q.get('score') ?? '0';
// ...then use NAME and SCORE in the text layers of your composition:
const sequences = [
  { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#1d2433' } },
  { type: 'text', text: `Well done, ${NAME}!`, at: 0.3, duration: 3.7, style: { fontSize: 96, fontWeight: 'bold', fill: '#ffffff' },
    initial: { x: 'GW/2', y: 300, anchorX: 0.5, anchorY: 0.5 }, keyframes: [{ at: 0, from: { alpha: 0, y: 340 }, to: { alpha: 1, y: 300 }, duration: 0.6 }] },
  { type: 'text', text: `${SCORE} points`, at: 0.9, duration: 3.1, style: { fontSize: 64, fill: '#ffd166' },
    initial: { x: 'GW/2', y: 420, anchorX: 0.5, anchorY: 0.5 }, keyframes: [{ at: 0, from: { alpha: 0 }, to: { alpha: 1 }, duration: 0.6 }] },
];
```

```sh
# batch.sh: one video per row of table.csv (name,score). --draft first, to look; remove it for the real files.
mkdir -p out
while IFS=, read -r name score; do
  npx pixi-effects render batch.html --query "name=$(printf %s "$name" | jq -sRr @uri)&score=$score" -o "out/$name.mp4" --quiet
done < table.csv
```

---

## One film, several languages and colours (variables)

Declare what changes as `vars` and write `{name}` in the strings and the names as identifiers in the expressions. One page then makes every variant: a declared variable is set from the command line (`pixi-effects render film.html --var accent=#3949ab -o film-blue.mp4`; a name the page did not declare stops the run), the language below is picked by the page from the query (`--query lang=ja`, on `check` as well as `render`), and a page can switch live with `movie.setVars(...)`. Load the fonts of every language before the first build (pitfall 103); `check` says a variable nothing reads, and a `{name}` nobody declared.

```js
// @docs-only variants
const COPY = { en: { head: 'Spring sale', sub: 'Up to 40% off' }, ja: { head: '春のセール', sub: '最大40%オフ' } };
const lang = new URLSearchParams(location.search).get('lang') ?? 'en';
await movie.init({
  canvas, width: 1920, height: 1080, duration: 5,
  vars: { head: COPY[lang].head, sub: COPY[lang].sub, accent: '#e5399a', lift: 0 },        // numbers can be read in expressions, any value in {name}
  composition: { sequences: [
    { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#12151f' } },
    { type: 'text', text: '{head}', at: 0.3, duration: 4.7, style: { fontSize: 120, fontWeight: 'bold', fill: '{accent}' },
      initial: { x: 'GW/2', y: 'GH/2 - 40 - lift', anchorX: 0.5, anchorY: 0.5 }, keyframes: [{ at: 0, from: { alpha: 0 }, to: { alpha: 1 }, duration: 0.6 }] },
    { type: 'text', text: '{sub}', at: 0.9, duration: 4.1, style: { fontSize: 56, fill: '#ffffff' },
      initial: { x: 'GW/2', y: 'GH/2 + 80', anchorX: 0.5, anchorY: 0.5 }, keyframes: [{ at: 0, from: { alpha: 0 }, to: { alpha: 1 }, duration: 0.6 }] },
  ] },
});
// later, from a button: await movie.setVars({ head: COPY.ja.head, sub: COPY.ja.sub, accent: '#3949ab' });   // same frame, sound untouched
```

---

## A layout that follows the window (liquid)

`resize(w, h)` builds the composition again at that size, and every expression sees it as `W` / `H` / `GW` / `GH`: write the layout in those, never in pixels. For a different arrangement per shape (wide / tall) write the composition in a function of the size and hand it to `rebuild`. Watch a **box** that you size with CSS (`#box { width: 100vw; height: 100vh }`, the canvas inside it `width: 100%; height: 100%`), not the canvas: the movie sets the canvas's pixel size, and an observer on the canvas would see its own change and grow it again. `check --size 1920x1080,1080x1920` makes a contact sheet and a layout review for each size without a browser window.

```js
// @docs-only liquid-layout
const layout = (w, h) => {
  const tall = h > w;
  return { sequences: [
    { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '#12151f' } },
    { type: 'text', text: 'Headline', style: { fontSize: tall ? 'GW * 0.12' : 'GH * 0.14', fontWeight: 'bold', fill: '#ffffff' },
      initial: { x: tall ? 'GW * 0.08' : 'GW/2', y: tall ? 'GH * 0.7' : 'GH/2', anchorX: tall ? 0 : 0.5, anchorY: 0.5 } },
  ] };
};
// <div id="box" style="width:100vw;height:100vh"><canvas id="stage" style="width:100%;height:100%;display:block"></canvas></div>
const box = document.getElementById('box');
const pixels = () => [Math.round(box.clientWidth * devicePixelRatio), Math.round(box.clientHeight * devicePixelRatio)];
const [w0, h0] = pixels();
await movie.init({ canvas, width: w0, height: h0, duration: 6, composition: layout(w0, h0) });
new ResizeObserver(() => {
  const [w, h] = pixels();
  movie.rebuild({ composition: layout(w, h), width: w, height: h }).catch(console.error);   // overlapping calls are joined: only the latest size is built
}).observe(box);
```


<!-- ===== skills/pixi-effects/reference/direction.md ===== -->

# Directing a film (for any AI that makes video with code)

> **No shell or files (a browser chat)?** This guide is not for you: follow https://raw.githubusercontent.com/yjmtmtk/pixi-effects/main/ai/CHAT.md. You can still plan: put three lines in your reply (the one sentence to remember, the real assets you were given, the beats in order) and ask the person before you build.

Read this before you write a composition for anything longer than a title card: a product film, a company introduction, a launch, a data story. It is about the decisions around the renderer, so it names no tool; `SKILL.md` has the pixi-effects commands.

A one-line prompt makes the model fill every missing decision with its safest default: large text in the middle, a gradient behind it, everything fading in, the logo last. The fix is not a cleverer prompt. It is to remove the missing decisions before anything is drawn, and to judge what was drawn with evidence.

## The five layers (do not collapse them into one step)

| Layer | The question | Where the answer lives |
|---|---|---|
| Director | What is the film trying to say, to whom? | `brief.md` |
| Reference | What should it look and feel like? | `style-guide.md` |
| Timeline | What changes at each beat, and why? | `shotlist.md` |
| Renderer | How is every frame produced? | `src/` (seekable code) |
| Critic | What failed, exactly where, and why? | `reviews/` |

## Keep the decisions in files, not in the chat

A film whose only record is a conversation is a lucky session. Put the decisions where the next run can read them:

```
film/
  brief.md        the one-sentence goal, the audience, the product facts, the real assets
  style-guide.md  palette, type, motion rules, banned defaults
  shotlist.md     beats, states, timestamps, purpose
  assets/         approved logos, photos, screens, footage, sound
  src/            the composition and its code
  reviews/        contact sheets and defect notes
  out/            exports
```

The next film swaps the brief and the assets and keeps the rest. A run that stops can resume from the last file it finished and say which one is missing; "the last command exited 0" is never the definition of done.

## brief.md: facts about the product, choices about the film

Separate what is true (it comes from the product) from what is chosen (it comes from you). The model may invent a camera move or a stronger opening. It may not invent a dashboard, a figure, a logo or a client.

```
FILM
One sentence: what the viewer should remember
Audience:     who it is for
Duration:     seconds
Formats:      ask the human; one format unless they name more (see "Formats" below)

ASSETS (paths; everything on screen comes from here)
Logo · photos · screens · copy and numbers · brand type and colours · sound reference

VISUAL RULES
Keep:   traits taken from the reference
Avoid:  the clichés you will not use
Never:  invent a product screen, a metric, a claim or a logo

DELIVERABLES
Final video, poster frame, contact sheets, source, an asset list, a note on what a human still has to check
```

**Collect the assets first, list them, and read the list before building.** If the brief needs an asset that is missing, stop and ask. A convincing fake (a drawn logo, an invented dashboard, a guessed number) is the one failure that cannot be repaired afterwards. Words and numbers on screen are the source's own; take colours and type from the source itself (a site's CSS, a brand sheet), never from an adjective such as "premium".

## style-guide.md: a visual grammar written down

Without one the model supplies its own, which is why unrelated one-prompt films look related. Give it a frame, a film or the real site, and make it write what it saw:

```
REFERENCE ANALYSIS
Palette:      the actual colours (hex), not an adjective
Typography:   family, weight, scale
Composition:  where the eye goes first
Pacing:       average time between meaningful changes
Motion:       snap, glide, overshoot, cut or hold
Texture:      grain, paper, glass, flat
DO NOT COPY:  the reference's subjects, logos, copy or product imagery
```

The result is a style guide, not a collage of borrowed shots. Add a **motion rule per class of object**, because "motion with weight" is the difference between decoration and direction: small controls snap, large panels settle, the camera is almost invisible, headlines enter strongly and then hold long enough to read, one playful object is allowed to overshoot. If everything overshoots, nothing feels precise. After each move ask: does the viewer know where to look?

## shotlist.md: states and beats, not effects

"Zoom in, then morph, then add particles" lists activity. A plan says what the viewer knows at each moment:

```
00-02  HOOK     one image that earns attention
02-05  PROBLEM  the friction, shown, not described in a paragraph
05-09  REVEAL   the product enters through a real interaction
09-13  PROOF    one screen or number that demonstrates the claim
13-16  CLOSE    a clean final state and a readable call to action
```

Each row has an entry state, an exit state and a reason to exist. For a UI film write the state list first (SEARCH → RESULT → DETAIL → ACTION → CONFIRMATION) so one component can change size, colour and content while staying recognisably the same object. The shot list is a contract: a shot nobody can justify is cut.

## Seekable and deterministic, or it cannot be reviewed

Frame 240 must render directly, without replaying frames 0 to 239: no hidden clock, no unseeded randomness, nothing that only works after eight seconds of running. Think of a frame as a query: `frame = render(time, shotlist, assets, style, seed)`. Then a revision is local (change one time value, one curve, one asset) and a reviewed frame stays reviewed. Two renders of the same moment must give the same pixels; check it.

## Sound is on the same timeline

Many AI films look finished with the sound off; then the click lands after the button, the cut misses the beat, the logo arrives before the music resolves. Write a beat grid and drive picture and sound from it: choose a tempo whose bar is a round number of seconds, put every cut on a bar line and every cue on the beat it belongs to. With a licensed or original track, measure its beats and cut against them. Test: close your eyes and listen; if the film has no shape without the picture, the sound is not finished.

## Review the rendered frames, not your intent

Do not start by watching a full export ten times, and do not describe what you meant to make. Ask the renderer for a contact sheet: one frame at every beat, a short strip around the fastest transitions, and a frame from the middle of each cut taken from the exported file. Look cold, then write the **three largest defects** into `reviews/notes.md`, each with a **timestamp**, the **evidence** (what you see) and a **local fix**; patch only those, render those frames again, and note the result. A defect you fixed but did not write down is lost for the next film. Two things are easy to miss on a sheet, so do them on purpose: **measure the smallest text** on screen (its pixel size scaled to a 1080p frame, not the look of it), and look at **both ends of every cut and at every state a card passes through** (an empty frame that holds content a beat later is a defect). Ask for a second pair of eyes on the sheet whenever one is available: the author reads their own intent into it.

```
[ ] text readable at phone size (about 34 px or more on a 1080p frame)
[ ] nothing in the outer 5 % of the frame
[ ] real assets only, none redrawn or invented
[ ] one type and colour system across scenes
[ ] no awkward half-transition frame
[ ] cuts and sound cues land together
[ ] the first two seconds are a real hook
[ ] the last frame works as a poster
```

"The agent made a video" stops when the file exists. "The agent directed a video" stops when the evidence says the film works.

## Formats

A 16:9 film and a 9:16 cut are different compositions: the vertical one needs larger type, fewer things at once, another layout, sometimes a tighter story. Never crop the middle of the wide one. **Do not make a format nobody asked for:** ask which formats are wanted, make one if the answer is "whatever", and offer the others. When more than one is wanted, keep the same assets, timeline and states, define the layout per format, and look at a contact sheet of each: an export is correct because the composition survived the format, not because the encoder finished.

## Gates, and what to do when no human is there

Long runs need places to stop. With a human present:

1. approve the references and the asset list
2. approve the style guide and the shot list
3. look at representative stills
4. look at a rough cut and its contact sheet
5. repair the three highest-impact defects
6. check sound, formats and deliverables

Show the work early: serve the page the moment it exists (a copied template is enough, before the brief is written) and give the human the address in your first message; every later save then shows up as a notice they can act on when they choose. A first draft of the opening scene, served where the human can open it, is worth more than a perfect film at the end; a wrong direction is cheap to fix in the first minutes. Between gates the agent may work for hours; it never makes an irreversible brand decision (logo, claim, number) for the human, and a missing real asset is a blocker, not an invitation to invent one. If the reference is unclear, the right output is a question or one small test frame, not nine hundred polished wrong ones. With nobody to ask, record each decision you took as a "ruling" in the review notes, with what it costs if wrong, and finish with a short note of what still needs a human.

## The loop

PROMPT → CLIP is a demo. BRIEF → SYSTEM → FILM → REVIEW → BETTER SYSTEM is a studio: every stage leaves evidence the next one can use, and the tenth film can be better than the first.

*The shape of this guide follows a published breakdown of building a code-rendered video studio around an AI model ("Motion Engineering", @0xwhrrari, September 2026); the wording and the checklist are rewritten for this library's users.*


<!-- ===== docs/dsl.md ===== -->

# DSL Reference

This document describes the declarative composition spec that you pass to `Movie.init({ composition })`. Every shape is exported as a TypeScript type from `pixi-effects` for editor autocomplete.

- [Composition](#composition)
- [Sequences](#sequences)
- [3D layers & camera](#3d-layers--camera)
- [Assets](#assets)
- [Keyframes](#keyframes)
- [Expressions](#expressions)
- [Filters](#filters)

---

## Composition

A composition is a tree node that has a width, a height, a duration, and a list of child sequences. The root composition is what you pass to `Movie.init({ composition })`. Nested compositions appear inside a parent as a `{ type: 'composition' }` sequence.

```ts
interface CompositionSpec {
  width?: number;        // pixels; defaults to Movie width
  height?: number;       // pixels; defaults to Movie height
  duration?: number;     // seconds; defaults to Movie duration
  sequences?: SequenceSpec[];
  // (also: name, at, initial, keyframes, filters — same as SequenceCommon below)
}
```

Children of a nested composition use that composition's local coordinate system. `W`/`H` in the [scope](#expressions) refer to the **immediate parent**; `GW`/`GH` always refer to the root.

---

## Sequences

Every sequence shares this base shape:

```ts
interface SequenceCommon {
  name?: string;            // optional id, used for cross-references and debugging
  at?: number;              // start time in seconds, measured from the start of the PARENT composition (default 0)
  duration?: number;        // seconds; defaults to the parent's duration
  initial?: Props;          // properties applied before any keyframes evaluate
  keyframes?: Keyframe[];
  filters?: FilterSpec[];
}
```

### Timing at a glance

| What | Measured from |
|---|---|
| a sequence's `at` | the start of its **parent composition** (the root composition starts at 0) |
| a **keyframe's** `at` | the start of **its own sequence** (After Effects style): `at: 0` = the moment the layer appears. **Negative = back from the sequence's end** (`-0.5` = 0.5 s before it ends) |
| a transition's `at` | the start of the **parent composition** (like a sequence's `at`) |
| `audio` volume keyframes | the start of their own sequence (same rule as every other keyframe) |

### Anchors and origins

| Layer | Where `x, y` land by default | To change it |
|---|---|---|
| `shape` rect / circle / ellipse | the **centre** of the shape | `anchorX` / `anchorY` (0–1). A bar growing from its base: `anchorY: 1`; left to right: `anchorX: 0` |
| `shape` line / polygon / path | the centre of the shape's bounds | `pivotX` / `pivotY` (in the shape's own canvas coordinates): the point that sits at `x, y` and that rotation / scale turn about. **`anchorX` / `anchorY` do nothing on these.** A `path` whose `d` is already written in canvas coordinates takes no `x` / `y` at all (they would move its centre to that point); to move it, change the coordinates or wrap it in a composition. |
| `text`, `image`, `video` | the **top-left** corner | `anchorX` / `anchorY: 0.5` to centre |
| `composition` | its top-left corner | `pivotX` / `pivotY` = the point that sits at `x, y` and that rotation / scale turn about |

Shape geometry (`width height radius anchorX …`) may be written at the top level or in `initial`; the top level wins. `rotation`, `skew*` and `rotationX/Y` are in **degrees**.

A layer is **not removed** when its lifespan `[at, at + duration)` ends: it is only hidden, and it keeps its last animated values. Outside the lifespan it is invisible. **z-order is array order** (later = on top). Build scenes by giving layers `at` / `duration` and stacking them; a full-screen background rect in each scene hides what is below it.

`Props` is `Record<string, number | string>`. String values are evaluated as [expressions](#expressions) unless the prop is a textual one (e.g. `fill`, `fontFamily`).

### `text`

Renders a [PIXI.Text](https://pixijs.com/8.x/guides/components/scene-objects/text/text). Animatable position, rotation, scale, opacity and `fill`. `style` accepts any PixiJS `TextStyle` field and is applied once at build time (an outline `stroke: { color, width }` is **round-joined** unless you give `join`: PixiJS's own default, `miter`, grows spikes on the sharp corners of W, V, A, k; the stroke is centred on the glyph edge, so half its width covers the fill: keep `width` to about a tenth of `fontSize`, or put a second, stroked copy of the text under the plain one for a thick outline) — notably `fontSize fontFamily fontWeight fill letterSpacing lineHeight align wordWrap wordWrapWidth stroke dropShadow padding` (numbers may be expressions). A `dropShadow` glow is clipped unless `padding` is at least twice its `blur`. Text content can change over time (see *Changing text* below): a `{value}` placeholder prints an animatable number (counters), a keyframe `set: { text: '…' }` swaps the string, and `visibleChars` types it out. Multi-line text is centre-aligned unless `style.align` says otherwise. In expressions `w` / `h` are the size of the styled text, so `x: '-w'` places it just off the left edge.

```ts
{
  type: 'text',
  text: 'hello',
  initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
  keyframes: [
    { at: 0, from: { alpha: 0 }, to: { alpha: 1 }, duration: 0.5 },
  ],
  style: {
    fontSize: 'GW * 0.05',     // expression OK
    fill: '#ffffff',           // verbatim string
    fontWeight: 'bold',
    fontFamily: 'Inter',
  },
}
```

**Wrapping and fonts for Japanese, Chinese and Korean.** `wordWrap: true` breaks a line at spaces. Japanese and Chinese have none: with `wordWrap` alone a long line does not wrap and runs off the canvas, and `breakWords: true` makes it break between any two characters, so a line can end with one to three characters alone (an orphan) and split a word or phrase in the middle. For a clean break write the line break yourself (`'あの日言えなかった言葉が、\n風に溶けていく'`, after a comma or a particle) and size the font so each line fits; `check` lists a line that is cut by the canvas edge, but it does not judge an ugly break, so look at the sheet. (Korean writes spaces between words, so `wordWrap` breaks there; a very long word still needs `breakWords`.) No font is bundled: the machine's own fonts are used, and a font that lacks the script's characters is replaced for those characters by whatever the machine has, so the look differs from machine to machine. For a result that looks the same everywhere, load a web font that covers the script (for example Noto Sans JP, Noto Sans KR for Hangul, Noto Sans SC) and `await document.fonts.load('40px "Noto Sans KR"')` before `movie.init` (see pitfall 103); give the family in `style.fontFamily`.

**Right-to-left and complex scripts (measured in trials).** With a font that covers the script the text is shaped correctly: Arabic letters connect and read right to left, Hebrew reads right to left, Thai and Devanagari marks stack. The direction follows the first strong letter of the line; place it with `anchorX: 1` and `style.align: 'right'`. Three traps: (1) marks that hang below the font's box can be cut off (the dots of an Arabic ي turn "في" into "فى"): give the layer `style.padding` (30 at a size of 120), and `check` cannot see it, so look at the picture; (2) `splitText` and `animateText` place words and letters from left to right, so an Arabic line comes out in reverse order, and `by: 'chars'` breaks the connected forms: split the line by words yourself and place each word at the right edge minus `measureText` of the logical text up to that word; (3) `visibleChars` shapes each prefix alone, so the last letter can show in its isolated form until the next one arrives: uncovering the whole line with a mask whose width grows keeps the connected forms.

The text's `fill` is also animatable via keyframes (under the `to`/`from`/`set` keys, not under `style`). Set `colorSpace` for perceptual interpolation:

```ts
{
  type: 'text', text: 'COLORSPACE',
  colorSpace: 'oklch',
  style: { fill: '#ff0000', fontSize: 48, fontWeight: 'bold' },
  keyframes: [
    { at: 1, to: { fill: '#00ff00' }, duration: 2, ease: 'sine.inOut' },
  ],
}
```

#### Changing text: `set: { text }` and `visibleChars`

A keyframe `set: { text: 'Two' }` swaps the string at that time (layer-local `at`, undone when you seek back; a string cannot be tweened, so `to` / `from` with `text` warn). A countdown is one layer:

```ts
{ type: 'text', text: '3', duration: 4, style: { fontSize: 150 }, initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
  keyframes: [{ at: 1, set: { text: '2' } }, { at: 2, set: { text: '1' } }, { at: 3, set: { text: 'Go!' } }] }
```

`visibleChars` is a number that shows only the first N characters (counted as you see them: an emoji is one): a typewriter. `initial: { visibleChars: 0 }` and a keyframe `to: { visibleChars: 30 }, duration: 2.4, ease: 'none'` types 30 characters over 2.4 s (it starts at 0 as soon as it is animated). Use a left-aligned layer (`anchorX: 0`, `style.align: 'left'`) so the text grows to the right instead of re-centring each letter; the layer's `w` / `h` are those of the whole text. `set: { text }` and `visibleChars` combine (swap the string, `set: { visibleChars: 0 }`, type it again), and so does a `{value}` placeholder in the string.

#### Counters (`{value}`)

A text layer has one animatable number, `value`, printed wherever the text contains `{value}`. Animate it with the normal keyframes (any ease, `from`/`to`/`set`, `repeat`):

```ts
{
  type: 'text', text: '{value} users', format: { decimals: 0, grouping: true },   // → "2,480 users"
  initial: { value: 0 },
  keyframes: [{ at: 1, to: { value: 2480 }, duration: 1.2, ease: 'power3.out' }],
  style: { fontSize: 72, fill: '#fff' }, ...
}
```

`resolution` (1 to 8, default the renderer's own) draws the text at that many times the pixels: text is drawn once at its own size and then stretched by its parents, so text inside a group scaled up to 3x is soft unless it has `resolution: 3`. `format`: `decimals` (default 0), thousands `grouping` (default false) and `pad` (zero-pad the whole part to that many digits: `pad: 2` gives `05`, so a clock is `text: '18:42:{value}'` with `format: { pad: 2 }`) and `time` (print the value, in SECONDS, as a clock: `'hh:mm:ss'`, `'h:mm:ss'`, `'hh:mm'`, `'mm:ss'` or `'m:ss'`; the seconds are cut, not rounded, and the hours do not wrap, so a day clock keeps the value inside 0–86399 with `mod`: `{ value: 15000 }` with `format: { time: 'hh:mm' }` is `04:10`). Put prefixes and suffixes in the text (`'${value}'`, `'{value}%'`). If `value` is animated but the text has no `{value}`, a warning says so.

**Colour inside one text layer: `spans`.** Instead of `text`, write an array of strings (drawn in the layer's own `style`) and `{ text, fill, … }` objects; they are shown one after the other, and `\n` inside a span starts a new line:

```ts
{ type: 'text', name: 'code', style: { fontFamily: 'Menlo', fontSize: 30, fill: '#e8f5e8', align: 'left' },
  spans: [{ text: 'type', fill: '#7fa07f' }, ': ', { text: "'text'", fill: '#ffd166', fontWeight: '700' }, ',\n  at: 0.5'],
  initial: { x: 120, y: 200 } }
```

A span may change `fill`, `fontWeight`, `fontStyle`, `fontVariant`, `letterSpacing` and `dropShadow`; a size, a font, `lineHeight`, `align` or a `stroke` belongs to the layer's `style` (one outline per layer: a stroke shifts a piece by half its width; a span that sets one of these is warned about once and the key is ignored; `style.wordWrap` and `style.leading` do not apply either: the lines are the `\n` of the spans). `style.align` places the lines on the width of the block (`'left'`, `'center'` — the default, as for every text — or `'right'`). At build time the layer becomes a group (a composition) of ordinary text layers, one per piece of a line, named `<name>.0`, `<name>.1` …, each at the x it has when the pieces are measured one after the other (the same measuring as `splitText`), so `inspect`, the timeline view and `check` see them. The group carries the layer's `name`, `at`, `duration`, `initial` (`anchorX` / `anchorY` are numbers, 0.5 centres the whole block, and cannot be keyframed), `keyframes` (`x`, `y`, `alpha`, `scale`, `rotation`, …), `filters`, `mask` and `blendMode`. A **typewriter** works over all the spans: `initial: { visibleChars: 0 }` and a keyframe `to: { visibleChars: N }` count every character in order, the newline included. `fill`, `text`, `value`, `fillGradient`, `format` and `colorSpace` do not apply to a group (a warning says so): use a separate text layer, or put the colour in a span. Measuring needs the font loaded (`await document.fonts.load('30px "Name"')` for a web font), as for `splitText`; the size and spacing in `style` may be numbers, expressions (`'GH * 0.05'`) or declared variables: they are resolved before the pieces are measured, and a missing `fontSize` is measured as the text layer's own default (Arial, 36).

### `image`

Renders a [PIXI.Sprite](https://pixijs.com/8.x/guides/components/scene-objects/sprite/sprite) from a registered asset. Intrinsic `w`/`h` come from the loaded texture. `scaleMode: 'nearest'` draws the pixels as hard squares when the picture is scaled up (pixel art, a sprite drawn small and shown big); the default `'linear'` smooths. It belongs to the asset: every layer that shows it gets it.

```ts
{
  type: 'image',
  asset: 'logo',
  initial: { x: 'GW/2 - w/2', y: 'GH/2 - h/2' },
}
```

`tint` is animatable via keyframes. Optionally set `colorSpace` to interpolate the tint perceptually:

```ts
{
  type: 'image', asset: 'logo',
  colorSpace: 'oklch',                 // smooth hue sweep instead of muddy sRGB
  initial: { tint: '#ff0000' },
  keyframes: [
    { at: 1, to: { tint: '#00ff00' }, duration: 2, ease: 'sine.inOut' },
  ],
}
```

### `video`

Renders a video. Intrinsic `w`/`h` come from the video's natural size. `currentTime` is driven by the timeline (so seeking the Movie scrubs the video).

```ts
{
  type: 'video',
  asset: 'green',
  loop?: false,           // loop back to start when finished (default false)
  audio?: true,           // route audio track into the mix (default true)
  volume?: 1,             // initial volume 0..1 (animatable via volume keyframes)
  speed?: 1,              // playback speed: 2 = twice as fast, 0.5 = slow motion, negative = backward (see [Time](#time-speed-and-time))
  initial: { x: 0, y: 0, scale: 'cover' },
}
```

Use `scale: 'cover'` or `scale: 'contain'` (these resolve via the [scope](#expressions)) to fit the video to the parent composition.

### `null` and `parent`

A `null` layer draws nothing; it only moves. Any layer can name it as its `parent`, and is then drawn **inside** it: the null's position, rotation, scale, skew and alpha carry the layer along. Use it to move, turn, scale or fade a group at once, to turn something about a point (a planet and its moon, a clock hand, a hinged arm), or to build a rig.

```js
{ type: 'null', name: 'planet', initial: { x: 640, y: 360 },
  keyframes: [{ at: 0, to: { rotation: 360 }, duration: 8, ease: 'none' }] },
{ type: 'shape', shape: 'circle', radius: 20, parent: 'planet', initial: { x: 200, y: 0, fillColor: '#ffffff' } },   // circles the point (640, 360)
```

- A child's `x` / `y` are measured **from the null's origin** (not from the composition's corner): with the null at (640, 360), a child at `x: 200` is drawn at 840. Rotation turns the child about the null's origin; give the null `pivotX` / `pivotY` to turn about another point.
- Nulls **chain**: a null may have a null as its `parent` (shoulder → elbow → hand). A cycle is reported and broken.
- The children are **drawn where the null stands in the list** (stack order), together, not where each is listed: to put another layer between two children, split them across two nulls. A child's own `at` / `duration` still apply, in composition time.
- The null lives for the whole composition unless it has `at` / `duration`; when it is not alive its children are not drawn.
- A **mask** on a child shares the child's space, so it follows the null as well.
- Only `null` layers can be parents (not shapes, text or images), and a `threeD` layer or a camera cannot have a parent. These cases, an unknown name and a cycle are each warned about, and the layer is drawn without a parent.

### `audio`

Audio-only sequence. No visual. Volume is animatable via keyframes.

```ts
{
  type: 'audio',
  asset: 'bgm',
  loop?: false,
  volume: 0,
  keyframes: [
    { at: 0,  to: { volume: 0.6 }, duration: 1 },     // fade in
    { at: -1, to: { volume: 0 },   duration: 1 },     // fade out (negative `at` = relative to end)
  ],
}
```

`speed` (audio **files** only) plays the file faster, slower or backward; the pitch follows, like a tape. It does not apply to `sfx` / `music` (an sfx has `pitch`, in semitones). To change the speed over time animate `time` (see [Time](#time-speed-and-time)).

Audio is mixed during `Movie.init()` and during `Movie.render()`. Volume keyframes interpolate linearly.

**The loudness of the whole mix: `movie.init({ loudness: -16 })`.** Layers make whatever level their `volume` gives (a few `sfx` at volume 0.15 mix to about -40 LUFS, far quieter than web video's -14 to -16). `loudness` is a target for the finished mix in LUFS (ITU-R BS.1770): one gain, up or down, applied before the limiter and the same for playback and export. The loudest sample may not pass -1 dBFS, so a mix with one loud click in a quiet bed stops short of the target, and `check` / `inspectAudio()` say so (`reached -19.4 LUFS`) with the fix (lower that sound, or ask for less). `false` or no option leaves the mix as the layers make it; `check` then says when it is quiet (found in a trial of nine films with sound: eight were -22 to -26 LUFS and only one was raised).

#### Sound effects without files: `sfx`

```ts
{ type: 'audio', sfx: 'swoosh', at: 2 }                                          // a preset at its own length
{ type: 'audio', sfx: { preset: 'hit', pitch: -3, brightness: -0.5 }, at: 4 }    // lower and darker
{ type: 'audio', sfx: 'riser', at: 3, duration: 1.5, volume: 0.7 }              // duration IS the sound's length (stretched)
{ type: 'audio', at: 6, duration: 0.3,                                          // a custom sound
  sfx: { voices: [{ wave: 'square', freq: [1600, 200], filter: { type: 'lowpass', freq: 3000 }, envelope: 'fall' }] } }
```

The sound is synthesised from data at init (no asset, no network), deterministic, and the same mix in playback and in the exported file (encoded there: AAC / Opus are lossy). `at` is where it starts; `volume` and volume keyframes work as for files; `loop` is not available (one layer per hit). Knobs: `pitch` (semitones, ±24), `brightness` (−1 dark … 1 bright), `seed` (another take of the random parts). `volume: 1` is the preset's standard level, peaking at −12 … −18 dBFS depending on the preset; the finished mix is soft-limited above 0.9 with a warning naming the layers. A custom sound has up to 16 `voices`: `wave` (`sine` `triangle` `square` `saw` `noise`), `freq` (Hz or `[from, to]`), `filter` (`{ type: 'lowpass' | 'highpass' | 'bandpass', freq, q }`), `envelope` (`fall` `bell` `swell` `hold`), `pan`, `from` / `to` (part of the sound, 0–1), `gain`; its default length is 0.5 s.

| Preset | Default length | Loudest at | Brightness | Use for |
|---|---|---|---|---|
| `click` | 0.04 s | start | ≈ 12780 Hz | UI click, tick |
| `pop` | 0.12 s | start | ≈ 390 Hz | an element appearing |
| `swoosh` | 0.5 s | 0.16 s | ≈ 3070 Hz | transitions, fly-pasts (moves left → right) |
| `swipe` | 0.22 s | start | ≈ 13190 Hz | quick UI swipe |
| `hit` | 0.7 s | start | ≈ 150 Hz | impact, slam |
| `riser` | 1 s | its end | ≈ 11850 Hz | build-up into a hit |
| `chime` | 1.4 s | start | ≈ 1400 Hz | success, reveal |
| `beep` | 0.16 s | flat | ≈ 1030 Hz | countdown, alert |
| `coin` | 0.4 s | 0.07 s | ≈ 1870 Hz | reward, collect |
| `glitch` | 0.35 s | 0.22 s | ≈ 3970 Hz | digital error |
| `typewriter` | 0.06 s | start | ≈ 3260 Hz | one key (vary `seed` per key) |

Brightness is the spectral centroid that `movie.inspectAudio()` reports (`sound.brightnessHz`), at 48 kHz with no knobs.

#### Music written as text: `music`

A tune with no audio file: notes, chords and drum patterns written as strings, played by a small built-in synthesiser. Deterministic (same score, same sound, in playback and in the exported file); the synthesiser is its own chunk, loaded only when a movie uses it.

```ts
{ type: 'audio', at: 0.5, volume: 0.8, music: {
    bpm: 84, swing: 0.16, reverb: 0.26,
    tracks: [
      { inst: 'keys',  vol: 0.7, pan: -0.15, strum: 0.012, notes: 'Cmaj7:4 Am7:4 Dm7:4 G7:4' },
      { inst: 'bass',  vol: 0.85, notes: 'c2:1.5 _:0.5 g2:1 c2:1 | a1:1.5 _:0.5 e2:1 a1:1 | d2:1.5 _:0.5 a2:1 d2:1 | g1:1.5 _:0.5 d2:1 g1:1' },
      { inst: 'pluck', vol: [[0, 0], [8, 0.55]], step: 0.5, notes: 'e5:1 d5:0.5 c5:0.5 e5:2 | c5:1 a4:1 e5:2 | f5:1 e5:0.5 d5:0.5 a4:2 | d5:1.5 b4:0.5 g4:2' },
    ],
    drums: [{ from: 4, kick: 'x.......x.x.....', snare: '....x.......x...', hat: 'x.x.x.x.x.x.x.xo' }],
} }
```

**Layer.** `at` starts it, `volume` (and volume keyframes) scale it. `duration` defaults to the music's length plus its reverb tail (`tail`, 2.5 s), but never past the end of the composition (the music then ends with the movie, with a short fade). A shorter `duration` cuts it with a fade; a longer one is silent after the music unless **`loop: true`**, which repeats the score until the layer ends (default: the end of the composition). At `volume: 1` the music peaks at −6 dBFS (about −20 dB RMS), a bed that sits under speech and sound effects (an sfx peaks at −12 dBFS). Measured: a 4-bar tune (bell + bass + kick, a pluck and a hat on the repeat) at `volume: 0.8` reads −22 LUFS and −7.7 dBTP; web video is usually −14 to −16 LUFS, so 0.8 is not a limit: raise `volume` and watch `inspectAudio().loudness.truePeakDb`. `inspectAudio()` lists a music layer as ONE source (its start); to line a picture up with a note, take its time from [`musicEvents(music)`](api.md#musicevents) (seconds from the start of the music, the tempo map applied: add the layer's `at`), or build the bars and the score from one array so they cannot drift.

**Score** (`music`): `bpm` (a number, or `[beat, bpm]` points for a tempo change: `[[0, 96], [28, 96], [32, 60]]` slows down over beats 28–32, a ritardando), `tracks`, `drums`, `swing` (0–0.4: delays the off-beat eighths and sixteenths; 0.16 is a gentle lo-fi lilt), `reverb` (0–0.6, default 0.22), `humanize` (seconds of seeded timing jitter, default 0.012), `drumVol` (default 0.8), `grid` (drum steps per beat, default 4), `meter` (beats in a bar, default 4: it only names the bars in [`musicEvents()`](api.md#musicevents) and in the `check` read-back, playback does not use it), `transpose` (semitones, all pitched tracks), `tail`, `seed`. Misspelt names warn with "did you mean". The music's length is its longest track (drums repeat up to it), so a track of rests (`'_:16'`) sets a length.

**Tracks.** `inst` is one of `keys` (electric piano), `pluck` (guitar / harp), `pad` (slow warm synth pad), `bass` (synth bass), `sub` (pure sine bass, for a heartbeat), `lead` (soft melodic lead), `bell` (glockenspiel), `musicbox` (a bright tine with a short ring). Options: `vol` (0–1.5, default 0.8, or `[beat, level]` points joined by lines for a fade-in or a swell), `pan` (−1…1), `step` (length of a token without `:`, in beats, default 1), `strum` (seconds between the notes of a chord, 0.01 sounds natural), `legato` (0.1–1, how much of a note's length it sounds), `tone` (0–1, brightness; lower is darker, a lo-fi dulling), `reverb` (0–1, this track's share of the reverb: dry bass, wet bells), `attack` / `release` (seconds; a pad's fade in and out), `ring` (seconds a bell or musicbox rings), `transpose` (semitones for this track). Good ranges: bass c1–c3, keys / pluck c3–c6, pad c2–c5, lead c4–c6, bell c5–c7.

**`notes` string.** Tokens are separated by spaces (`|` is ignored: use it for bars). The unit is the **beat** (a quarter note); count them, a 4/4 bar is 4 beats.

| Token | Meaning |
|---|---|
| `c4` `f#3` `bb2` | a note, **always lowercase** (c4 = middle C; `bb2` is B flat); `:2` after it is its length in beats (`c4:0.5` an eighth), default `step` |
| `Am7` `F#m` `Bbmaj7` `G7` `C5` `C@4` `Am7/e` | a chord, **always starting with a capital letter** (`G7` is G dominant seventh, `g7` a very high note); voiced close around octave 3 (`@4` puts the root in octave 4; `/e` puts e in the bass). Kinds: none, `m`, `5`, `aug`, `dim`, `sus2`, `sus4`, `6`, `m6`, `add9`, `madd9`, `add11`, `7`, `maj7`, `m7`, `mMaj7`, `dim7`, `m7b5`, `7sus4`, `7b9`, `7#9`, `9`, `maj9`, `m9`, `11`, `m11`, `13`, `maj13`, `m13`, `maj7#11` |
| `[c4 e4 g4]:2` | a chord written out note by note (exact voicings) |
| `_` `_:2` | a rest |
| `~` `~:1` | hold: lengthens the note before |
| `!` `,` | accent / soft, before or after the length: `c4!:1`, `c4:1,` |

**Drums.** `drums` is an object of patterns, or a list of them with `from` / `to` (beats) so a groove can start late or stop (`[{ kick: 'x...' }, { from: 8, snare: '....x...' }]`). A pattern is a string of steps: `x` hit, `o` soft hit, `.` nothing (`|` and spaces are ignored); one step is 1/`grid` of a beat, so with the default grid 4 a 16-step string is one bar of 4/4, and a longer string (32 steps) is a longer figure that repeats. **The pattern repeats by itself** from `from` to `to`: you write one bar, not eight. `from` and `to` are **beats** from the start of the music (not bars): bar 9 of a 4/4 piece is `from: 32`; leave `to` out to play to the end. Drums: `kick snare hat openhat clap rim tom crash shaker sleigh` (`sleigh` is a jingle of small bells).

**Other meters.** The notation counts beats (the quarter note is 1), so 3/4 is bars of 3 beats. 6/8 is bars of 3 beats too: a dotted quarter is `:1.5`, an eighth `:0.5`; set `grid: 2` so a drum step is an eighth note (a 6-step pattern is one bar; the same `grid: 2` gives 6 eighth steps per bar in 3/4), and leave `swing` at 0. `grid: 3` is for triplet eighths in 4/4 (a shuffle).

**Comping on named beats, and swing.** There is no "on beats 2 and 4" option: write the rests, `_:1 Dm7:0.5 _:0.5 _:1 Dm7:0.5 _:0.5` is a short chord on beats 2 and 4 of one bar. `swing` delays only notes that start on an off-beat eighth (`.5`) or sixteenth, so notes on whole beats stay straight; for a swung comp put the chords on the "and" (`_:1.5 Dm7:0.5 ...`).

**Read it back.** `check` prints a `music` block for every music layer: its length in bars per track (a track that ends early, or a bar that is short, is named), the names that start in each bar with their beat (`Am(2)`: on beat 2; no mark: on the downbeat), and where the drums play. That is how to verify a score without listening. Set `meter` for anything but 4/4, or a waltz is reported as bars of 4. [`musicEvents(music)`](api.md#musicevents) gives the same facts as data, with every note's beat, time and pitches.

**Hear it without a movie.** [`musicBuffer(music)`](api.md#musicbuffer) returns a Web Audio buffer, for a page that plays tunes without a movie.

**Seeing the music in the picture.** [`musicEnvelope(music, { frameRate })`](api.md#musicenvelope) analyses the same score into `level` / `bass` / `mid` / `treble` and exact beats for [`react()`](#react), so a title can pulse with the kick of a tune that has no file. [`musicEvents(music)`](api.md#musicevents) lists the notes themselves (which chord, which pitches, which bar), so a keyboard can light the keys that sound or a caption can name the chord.

### `composition`

Nested composition. Same shape as the root spec but with `type: 'composition'` and an explicit `width`/`height`. Children animate within the local coordinate system; the composition itself can be positioned, scaled, and rotated as a unit.

**Size, clipping and culling** (measured): a 2D composition does **not** clip its children — a child far outside `width × height` is still drawn. But the rectangle `width × height` is what the renderer uses to decide the group is on screen: when that whole rectangle is off the canvas the group is skipped even if a child is placed back on screen. So keep the rectangle around what it draws (or make it canvas-sized). A `threeD: true` composition (a card) is rendered into a texture of exactly `width × height`, so it **does** clip its children there; size it for soft shadows too.

```ts
{
  type: 'composition',
  width: 600, height: 120,
  initial: { x: 'GW/2 - 300', y: 'GH * 0.86' },
  keyframes: [
    { at: 2.4, from: { alpha: 0, rotation: -12 },
               to:   { alpha: 1, rotation: 0 },
               duration: 0.7, ease: 'elastic.out(1, 0.5)' },
  ],
  sequences: [
    { type: 'text', text: 'inside', initial: { x: 300, y: 60, anchorX: 0.5, anchorY: 0.5 }, style: { fontSize: 28, fill: '#fff' } },
  ],
}
```

A composition can also have its **own time**: `speed` (2 = its content plays twice as fast, 0.5 = slow motion, negative = backward) and `time` keyframes (see [Time](#time-speed-and-time)). The layers inside then write `at`, `duration` and `keyframes` in the composition's own seconds; the composition's own `at`, `duration` and keyframes stay in the outer time. A sound or `sfx` inside follows the composition's clock.

### `shape`

Parametric primitive backed by PIXI v8 `Graphics`. Six kinds, discriminated by `shape`. All geometry props accept the [expression language](#expressions), so dimensions can follow the canvas:

```ts
// Centered rounded panel that fills 80% of the canvas
{
  type: 'shape', shape: 'rect',
  width: 'W * 0.8', height: 'H * 0.6', cornerRadius: 24,
  initial: {
    x: 'W/2', y: 'H/2',
    fillColor: '#1a2640', fillAlpha: 0.85,
    strokeColor: '#3a5680', strokeWidth: 2,
  },
}
```

Every primitive draws centred on its local origin (so `anchorX`/`anchorY` and `pivotX`/`pivotY` semantics line up with the other sequence types).

| `shape`   | Required props                           | Optional               |
|-----------|------------------------------------------|------------------------|
| `rect`    | `width`, `height`                        | `cornerRadius`, `trimStart`, `trimEnd` |
| `circle`  | `radius`                                 | `trimStart`, `trimEnd` |
| `ellipse` | `radiusX`, `radiusY`                     | `trimStart`, `trimEnd` |
| `arc`     | `radius`                                 | `innerRadius`, `startAngle` (0), `endAngle` (360) |
| `line`    | `from: [x,y]`, `to: [x,y]` (canvas coordinates; stroke in `initial`) | `trimStart`, `trimEnd` |
| `polygon` | `points: [[x,y], …]`                     | `open` (default false), `trimStart`, `trimEnd` |
| `path`    | `d` (SVG path data)                      | `fillRule`, `trimStart`, `trimEnd`, `morphTo`, `morph`, `morphPoints` |

**Holes (`fillRule: 'evenodd'`) on a `path`.** Several sub-paths in one `d` are each filled on their own: a donut written as two circles is a solid disc. With `fillRule: 'evenodd'` the biggest sub-path is the shape and every other one is a hole cut out of it (the stroke goes round the shape and each hole): `{ shape: 'path', fillRule: 'evenodd', d: 'M 0 -100 A 100 100 0 1 1 0 100 A 100 100 0 1 1 0 -100 Z M 0 -50 A 50 50 0 1 0 0 50 A 50 50 0 1 0 0 -50 Z', initial: { x: 640, y: 360, fillColor: '#ffcc00' } }`. Write the sub-paths in absolute coordinates (each starts with `M`); an island inside a hole is not drawn, and a path that morphs (`morphTo`) has no holes.

**`arc`** is an arc around its local origin (the centre). Angles are in **degrees: 0° is 3 o'clock and positive is clockwise**, so a progress ring starts at `startAngle: -90` (12 o'clock) and animates `endAngle` from `-90` to `270`. With a stroke and no fill it is an open arc line (`strokeCap: 'round'` for rounded ends); with a fill it is a sector (a pie slice), and with `innerRadius` a ring segment (a donut slice). A sweep of 360° or more is a full circle; `endAngle < startAngle` sweeps counter-clockwise. `radius`, `innerRadius`, `startAngle` and `endAngle` are all animatable.

```ts
{ type: 'shape', shape: 'arc', radius: 120, startAngle: -90, endAngle: -90, strokeCap: 'round',
  initial: { x: 'GW/2', y: 'GH/2', strokeColor: '#ffd166', strokeWidth: 24 },
  keyframes: [{ at: 0, to: { endAngle: 270 }, duration: 2, ease: 'power3.out' }] }   // a progress ring filling clockwise from the top
```

**Draw-on (`trimStart` / `trimEnd`).** On every shape except `arc`, `trimStart` and `trimEnd` (0–1, default 0 and 1, both animatable) are the part of the outline that is stroked, as fractions of its length. Animate `trimEnd` from 0 to 1 to draw a line, border or SVG path on; animate `trimStart` after it to wipe it off the same way; animate both for a travelling dash. A rect's outline starts at its top-left and goes clockwise, a circle / ellipse's at 12 o'clock and goes clockwise, a polygon's includes its closing edge, and a path's several sub-paths count as one length in order (add **`trimEach: true`** to trim every sub-path on its own, so they all draw on at the same time: a glyph or a logo made of several strokes). **The fill is not trimmed** (the whole shape stays filled): fade `fillAlpha` in after the draw-on. Use `strokeCap: 'round'` for a friendly end. For `arc`, animate `endAngle` instead (a `trim…` on an arc warns).

```ts
{ type: 'shape', shape: 'path', d: 'M 0 50 L 45 95 L 130 0', trimEnd: 0, strokeCap: 'round', strokeJoin: 'round',
  initial: { x: 1040, y: 270, strokeColor: '#7bd88f', strokeWidth: 16 },
  keyframes: [{ at: 0, to: { trimEnd: 1 }, duration: 1, ease: 'power2.inOut' }] }   // a check mark drawing itself
```

**Morph (`morphTo` / `morph`).** (Two outlines with the **same number of corners**, such as two quads, are paired corner to corner, so every in-between picture is a straight-edged quad and no corner is rounded; `morphPoints` only matters when the corner counts differ or the outlines are curves.) A `path` can turn into another outline: give `morphTo` (SVG path data in the same canvas coordinates as `d`) and animate `morph` from 0 (the `d` outline) to 1 (the `morphTo` outline). In between it is drawn as a polygon of points half way from one to the other (`morphPoints`: 8–2048, default 128). Closed outlines are lined up (start point and direction) so they do not twist; sub-paths are paired in order, and an extra one grows from (or shrinks into) its own centre. Fill and stroke both follow, and `trimStart` / `trimEnd` walk the morphing outline. Write both outlines as `M … L … C … Z` in absolute coordinates (arcs and holes work too, but keep the same number of sub-paths on both sides).

```ts
{ type: 'shape', shape: 'path', d: 'M 640 160 C 780 160 860 260 860 360 C 860 470 770 560 640 560 C 510 560 420 470 420 360 C 420 250 500 160 640 160 Z',
  morphTo: 'M 640 130 L 700 300 L 880 300 L 735 410 L 790 590 L 640 480 L 490 590 L 545 410 L 400 300 L 580 300 Z',
  initial: { fillColor: '#ffd166' }, keyframes: [{ at: 0.5, to: { morph: 1 }, duration: 1.5, ease: 'power2.inOut' }] }   // a blob turns into a star
```

`strokeCap` (`'butt'`, `'round'`, `'square'`) and `strokeJoin` (`'miter'`, `'round'`, `'bevel'`) work on every shape, at the top level or in `initial`; they are not animated. Sharp corners (the apex of an M in outlined text, a thin polygon) poke out with the default `miter` join: use `'round'`.

**Style** is set on `initial` and animatable via keyframes:

| Key           | Notes                                                        |
|---------------|--------------------------------------------------------------|
| `fillColor`   | Hex string (`'#3399ff'`) or number (`0x3399ff`). Omit = no fill. |
| `fillAlpha`   | 0..1, default 1                                              |
| `strokeColor` | Hex string or number. Requires `strokeWidth > 0` to render.  |
| `strokeAlpha` | 0..1, default 1                                              |
| `strokeWidth` | Pixels. Default 0 (no stroke).                               |

Colour keys (`fillColor`, `strokeColor`) tween smoothly between hues — no snap at the end. Numeric keys (`fillAlpha` / `strokeAlpha` / `strokeWidth`) animate linearly.

#### `fillGradient`

Fill a shape with a gradient instead of `fillColor` (top level or in `initial`). Positions are in 0–1 of the shape's own bounds, so the gradient follows the shape's size. Colours may carry alpha, so a radial gradient from transparent to dark is a vignette. Animatable (below), on shapes and on text.

```ts
{ type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2' },
  fillGradient: { stops: [[0, '#1b2a6b'], [0.6, '#7b3fe4'], [1, '#ff6a88']] } }                // linear, top → bottom
{ ..., fillGradient: { angle: 0, stops: [[0, '#00f5a0'], [1, '#00d9f5']] } }                    // left → right
{ ..., fillGradient: { type: 'radial', radius: 0.75, stops: [[0.45, 'rgba(0,0,0,0)'], [1, 'rgba(0,0,0,0.7)']] } }   // vignette
```

**Animating a gradient.** A keyframe's `set` / `from` / `to` takes a **partial** `fillGradient` (`angle`, `center`, `innerRadius`, `radius`, `stops`); what you leave out stays as it is. Numbers move linearly; the stop colours move through the layer's `colorSpace` (`'oklch'` keeps a fade vivid: in `'rgb'`, green to magenta passes through grey). The layer needs a starting `fillGradient` (top level or in `initial`), `stops` must keep the same count, and `type` cannot change (linear ↔ radial). A mistake (a mistyped key, another number of stops, `'fillGradient.angle'` or `gradientAngle` instead of `fillGradient: { angle }`) is said once, when the layer is built. A text layer takes a `fillGradient` for its letters too, **linear only** (`angle` and `stops` apply; `type`, `center`, `innerRadius` and `radius` are ignored, with a warning: use a shape for a radial gradient); the letters are re-rasterised on every change. A keyframe with only `from` runs from that gradient to the layer's own.

```ts
{ type: 'shape', shape: 'rect', width: 560, height: 420, initial: { x: 520, y: 540 }, colorSpace: 'oklch',
  fillGradient: { angle: 0, stops: [[0, '#ff2d55'], [1, '#0ea5e9']] },
  keyframes: [{ at: 0, duration: 2, to: { fillGradient: { angle: 360, stops: [[0, '#00e5ff'], [1, '#ffd60a']] } } }] }
{ type: 'text', text: 'GRADIENT', style: { fontSize: 200, fontWeight: '900' }, initial: { x: 640, y: 360, anchorX: 0.5, anchorY: 0.5 },
  fillGradient: { angle: 0, stops: [[0, '#ff2d55'], [1, '#0ea5e9']] },
  keyframes: [{ at: 0, duration: 2, to: { fillGradient: { angle: 180 } } }] }
```

| Field | Notes |
|---|---|
| `type` | `'linear'` (default) or `'radial'` |
| `stops` | at least two: `[offset 0–1, colour]` or `{ offset, color }` |
| `angle` | linear: degrees, `0` = left → right, `90` = top → bottom (default) |
| `center`, `innerRadius`, `radius` | radial: centre in 0–1 (default `[0.5, 0.5]`), inner radius (default 0), outer radius (default 0.5); an ellipse on a non-square shape |

#### `colorSpace`

Per-shape choice of how colour keyframes are interpolated. Default `'rgb'` (a straight lerp of the red, green and blue channels) is fast but classic — a red → green ramp passes through muddy olive at the midpoint. The two perceptually uniform options keep saturation through the transition:

| Value     | Behaviour                                                                                         |
|-----------|---------------------------------------------------------------------------------------------------|
| `'rgb'`   | Default. Linear sRGB lerp.                                                                        |
| `'oklab'` | Straight line in OKLab's chromaticity plane. Brighter, more chromatic midpoints.                  |
| `'oklch'` | (L, C, h) with hue along the shorter angular path. Smooth rainbow-style sweeps; ideal for hue cycling. |

```ts
{
  type: 'shape', shape: 'circle', radius: 40,
  colorSpace: 'oklch',                       // ← red → green via vibrant orange
  initial: { fillColor: '#ff0000' },
  keyframes: [
    { at: 1, to: { fillColor: '#00ff00' }, duration: 2, ease: 'sine.inOut' },
  ],
}
```

```ts
{
  type: 'shape', shape: 'circle', radius: 40,
  initial: { x: 'W/2', y: 'H/2', fillColor: '#ff5577' },
  keyframes: [
    { at: 1, to: { fillColor: '#55ddaa' }, duration: 1.0, ease: 'sine.inOut' },
    { at: 2, to: { strokeColor: '#fff', strokeWidth: 6 }, duration: 0.5 },
  ],
}
```

**Transforms animate normally.** `x`, `y`, `scale`, `scaleX`, `scaleY`, `rotation`, `alpha` etc. all go through the standard keyframe pipeline.

```ts
// SVG-path heart that scale-pops on entry, then beats twice
{
  type: 'shape', shape: 'path',
  d: 'M 0 -20 C -30 -50 -70 -10 0 30 C 70 -10 30 -50 0 -20 Z',
  initial: { x: 'W/2', y: 'H/2', fillColor: '#ff3366' },
  keyframes: [
    { at: 0,   from: { alpha: 0, scale: 0 },
               to:   { alpha: 1, scale: 1 },
               duration: 0.5, ease: 'back.out(2.5)' },
    { at: 1.5, to: { scale: 1.2 }, duration: 0.3, ease: 'power2.out' },
    { at: 1.8, to: { scale: 1.0 }, duration: 0.3, ease: 'power2.in' },
  ],
}
```

**Scalar geometry is animatable.** `width`, `height`, `cornerRadius` (rect), `radius` (circle), `radiusX` / `radiusY` (ellipse) all flow through the same per-frame redraw and can be tweened via keyframes — useful for progress bars (animate `width`), pulsing icons (animate `radius`), or shape-morph callouts. Array geometry (polygon `points`, line endpoints, path `d`) is baked at build time; use `scale` / `scaleX` / `scaleY` for those.

For rect / circle / ellipse, `anchorX` / `anchorY` (default `0.5` each; not available on line / polygon / path, which use `pivotX` / `pivotY`) control which point on the bbox sits at the local origin — `0` is left/top, `1` is right/bottom. They're animatable too. Critical for "grow from one edge" effects:

```ts
// Left-anchored progress bar — width animates 0 → W, left edge stays at x
{
  type: 'shape', shape: 'rect', width: 0, height: 18, cornerRadius: 9,
  anchorX: 0,                                  // ← left edge at x
  initial: { x: 0, y: 'H/2', fillColor: '#5599ff' },
  keyframes: [
    { at: 0, to: { width: 'W' }, duration: 4, ease: 'sine.inOut' },
  ],
}
```

---

### `shader`

A fragment shader as a layer: write a Shadertoy `mainImage` and it is drawn into a picture that is a layer like any other (it moves, fades, masks, filters, blends, goes into 2.5D and receives lights). Use it for what is drawn by a formula: flowing colour fields, plasma, noise, waves, patterns.

```ts
{ type: 'shader', name: 'plasma',
  fragment: `
    void mainImage(out vec4 fragColor, in vec2 fragCoord) {
      vec2 uv = fragCoord / iResolution.xy;
      float v = sin(uv.x * 10.0 + iTime) + sin(uv.y * 8.0 - iTime * 1.3);
      fragColor = vec4(mix(tint, vec3(0.1, 0.0, 0.3), 0.5 + 0.25 * v), 1.0);
    }`,
  uniforms: { tint: '#ff8040', speed: 1 },                                   // declared for you: `uniform vec3 tint;` and `uniform float speed;`
  keyframes: [{ at: 0, to: { 'uniforms.speed': 3, 'uniforms.tint.2': 0.8 }, duration: 4 }] }
```

Fields: `fragment` (the GLSL, required), `uniforms` (below), `width` / `height` (px, expressions allowed; default the composition's size), `resolution` (default 1; `0.5` draws a quarter of the pixels and scales up: the way out for a heavy shader), `transparent` (default `false`), and everything every layer has.

Rules:
1. **Write `mainImage`** — `void mainImage(out vec4 fragColor, in vec2 fragCoord)`, GLSL ES 3.00. `fragCoord` is in the layer's pixels, origin at the **bottom left** (Shadertoy's convention). `iResolution` (a `vec3`: width, height, 1), **`iTime`** (the layer's own seconds, from 0 at its start; inside a time-remapped composition, that composition's clock) and `iFrame` (an `int`) are declared for you, and so is every name in `uniforms`. Do not write `#version`, `precision`, `main()`, `gl_FragColor` (write the colour into `fragColor`), `texture2D` (it is `texture`), `varying` or `attribute`: each warns with what to write.
2. **`uniforms`**: a number is a `float`, 2 to 4 numbers are a `vec2` / `vec3` / `vec4`, a colour `'#rrggbb'` is a `vec3` in 0..1. Keyframes move them as `'uniforms.speed'`; a component of a vector or a colour as `'uniforms.tint.0'` (0 = x or red). A name or index that does not exist warns once with the likely name.
3. **Opaque by default**: the alpha you write is ignored. `transparent: true` uses it (the shader's colour is premultiplied by its alpha, so soft edges blend over what is behind).
4. **It is a layer, not a filter**: it cannot read what is behind it, and this version has no `iChannel` textures, `iMouse`, `iDate` or `iTimeDelta` (using one warns). One pass only: no buffers or feedback.
5. **A compile error is said in your own line numbers** (`line 2: 'x' : undeclared identifier`) and the layer is drawn as a magenta checkerboard until it is fixed, so a mistake is never a silent blank layer.
6. **The GPU cannot be stopped**: a `while` loop, or a `for` whose bound is not a constant, can hang it, so both warn. Give loops a constant bound and `break` early.
7. **Deterministic, with one caveat**: a frame is a pure function of `iTime`, `iFrame` and the uniforms, so playback, seeking and export agree. Different GPUs can round differently, so an export from another machine can differ in the last bits.
8. **Size and place**: with `width` / `height` smaller than the composition the layer's **top-left corner** sits at `initial.x` / `initial.y` (like an image; a shader layer has no anchor to set). **A mask or matte cuts the picture the shader drew over its whole size, it does not move it**: a ripple centred in the shader's own frame stays there, so to show the middle of a pattern through a disc at x = 410, put the pattern's centre at x = 410 (a `vec2` uniform: `uniforms: { centre: [410, 360] }`) or size and place the layer to match. With `resolution` below 1, `iResolution` and `fragCoord` are in the **scaled** buffer's pixels (half size at 0.5), so a pixel-unit uniform (a centre, a radius) must be multiplied by `resolution`; `fragCoord / iResolution.xy` needs no correction.
9. **Cost** (a prototype measurement at 1080p, on one machine, an Apple M1 Pro; the released layer is not re-measured): a 160×90 shader with an 8-step loop, 20 layers, cost 11 ms (WebGPU) to 17 ms (WebGL) a frame more than 20 plain rectangles; one full-size 1920×1080 layer cost about 10 ms more. Every layer pays a fixed cost (about 0.5 to 0.85 ms), so use a few big shaders rather than many small ones, and `resolution` for heavy ones. All shader layers share **one** WebGL2 context (so there is no limit from the browser's number of contexts); a shader layer needs WebGL2 (without it the build warns and draws the checkerboard).

### `canvas`

A picture drawn by **your own function of the time**, into a canvas of the layer's own, shown like an image at its place in the stack. Use it for what no other layer draws: an afterimage, rings that grow, a brush stroke, a waveform, a pixel sprite, a chart, a simulation. It is the escape hatch for "I want to draw this myself".

```ts
{ type: 'canvas', width: 800, height: 450, duration: 4, initial: { x: 640, y: 360, anchorX: 0.5, anchorY: 0.5 },
  params: { size: 40 },
  draw: (ctx, t, info) => {                                  // ctx: the layer's own 2D context, already cleared
    ctx.fillStyle = '#ff4f1a';
    ctx.beginPath(); ctx.arc(400 + 300 * Math.sin(t * 2), 225, info.params.size, 0, Math.PI * 2); ctx.fill();
  } }
```

It is a layer like any other: `name`, `at`, `duration`, `initial`, `keyframes`, `filters`, `mask`, `blendMode`, `parent`, `threeD`, lights, transitions, mattes, export all work on its picture.

| Key | Meaning |
|---|---|
| `draw(ctx, t, info)` | **Required.** Draws the picture at `t`, the layer's own seconds (0 when it starts). The canvas is **cleared before every call** and nothing a call sets (a fill colour, a font, a transform) survives into the next. The units are the layer's pixels. |
| `setup(info)` | Optional, may be async, called once at build: heavy preparation. Its result is `info.state`. |
| `width`, `height` | Layer size in px or an expression (`'GW / 2'`); default the composition's size; at most 8192. |
| `resolution` | 0.25 to 4 (default 1): canvas pixels per layer pixel. Text and fine lines under a zoom (a parent scaled up) need 2 or more. |
| `params` | Numbers that **keyframes can animate**: `keyframes: [{ at: 0, to: { 'params.size': 80 }, duration: 2 }]`; `draw` reads them as `info.params`. |
| `seed` | Integer (default 0) that seeds `info.random()`. |
| `smoothing` | `false`: no smoothing when drawing images into it AND hard pixels when the layer is scaled up (pixel art). Default `true`. |

`info` is `{ frame, duration, progress, width, height, resolution, frameRate, params, state, random, start, time, canvas }`: `frame` is the layer's own frame number, `progress` is `t / duration`, `params` holds the values at this time, `state` is what `setup` returned, `random()` is a **seeded** generator whose sequence starts again at every call (the same frame always draws the same numbers; for a value that must differ from frame to frame, derive it from `t`), **`start`** is where the layer starts on the movie's clock (its `at` plus the starts of the compositions around it; in `setup` just its `at`; inside a composition with a time remap, `speed` or `time`, the clock of that composition) and **`time`** is the movie's time now (`start + t`): read it for anything several layers or the sound share, instead of adding the `at` by hand (which breaks quietly when someone moves the layer). **`info.canvas(width, height)`** returns an offscreen canvas for a sprite, a mask or a scratch picture.

**Helpers you can import** (they are plain functions of their input, so they are safe in `draw`): `import { ease, noise, noise2, random, rand, samplePath } from 'pixi-effects'`. `ease('power3.out')` returns the function `x => eased x` for any ease name a keyframe takes (`back.out`, `elastic.out`, `cubic-bezier(…)`, `spring.…`), so a canvas moves like the other layers. `noise(x, seed)` and `noise2(x, y, seed)` are smooth noise in [-1, 1] (sum a few doublings of `x` and `y` for clouds and terrain); `random(seed)` is a repeatable stream and `rand(seed)` one number for a seed. `samplePath(d)` walks SVG path data by length: `.length`, `.at(u)` gives `{ x, y, angle }` (radians) a fraction `u` along, `.trim(a, b)` gives the part between two fractions as flat `[x, y, …]` pieces for `moveTo` / `lineTo` (a line that draws on, a string set along a curve, a petal that falls along a route). Build a sampler once (module scope or `setup`) and ask it every frame.

**The contract: a function of the time.** The same `t` and the same `params` must give the same pixels, in playback, in a seek and in an export. So: no `Math.random`, `Date.now`, `performance.now` or `new Date()` (a warning at build says so, and `check` draws each canvas layer twice at a few moments and reports a layer whose two pictures differ), and no state that outlives a call (a cache of a pure function, same input same output, is fine: a palette per phase, a table filled on the first call; state that depends on which frames were drawn before is not). A trail is drawn from the positions of the past computed from `t`, not from the last picture. A **simulation** (a game of life, a physics sim, a growth process) is computed whole in `setup` into an array and read by `info.frame` in `draw`. **Data that several canvas layers share** (the same plant, the same city, a palette phase) belongs in module scope, computed before `movie.init` from `random(seed)` and plain functions of the time: the state `setup` returns is private to its layer, and every layer reads the same clock through `info.time`. **Sprites, masks and scratch pictures** are made in `setup` with `info.canvas(w, h)` and drawn back with `drawImage` (a word rendered once, a paper texture, a mask for `destination-in`); not with `document.createElement('canvas')`: a GPU canvas used as a source can draw a little differently the first time (measured: up to 128 of 255 over 40 000 pixels on a 1280×720 layer), which is what `info.canvas` avoids. Everything of the 2D context works (`ctx.filter`, composite operations such as `source-atop` and `destination-in`, `drawImage` of another canvas, `measureText`: in `setup`, `info.canvas(1, 1).getContext('2d')` is a context to measure with). A web font must be loaded before it is measured or drawn: `await document.fonts.load('40px "Name"')` in `setup`. A type effect that shows words through a moving texture is: draw the words (the mask) first, then `ctx.globalCompositeOperation = 'source-atop'` and the texture, which paints only where the words are.

**What it cannot do.** It cannot see or paint on what is below it in the stack (the stage is drawn by the GPU, not by a 2D context): use `filters`, a matte or a composition that holds the layers for that. **`check` does not see text drawn in a canvas**: its layout test (cut-off, off-canvas, overlap) reads the text layers only, so labels and captions you draw yourself can collide without a word; look at the contact sheet and at `--crop` enlargements. It is not audio. For a picture made by a formula on the GPU, the `shader` layer is faster. A spec that holds a `canvas` layer holds functions, so it is not pure JSON (the same standing as `three` and the `custom` filter).

Mistakes are said at build time with the layer's name: no `draw`, a `draw` or `setup` that throws (the frame is a magenta checkerboard and the next frames are tried again), a bad `width` / `height` / `resolution` / `params`, an unknown key (did you mean …), a `params.name` keyframe that names nothing. A draw costs time on every frame that changes (`draw` is called once for each distinct time, so a still picture still redraws every frame of a moving movie: draw what never changes once into a canvas from `info.canvas` in `setup` and `drawImage` it): a slow `draw` slows the export in proportion, and `check` prints the usual time of one draw. The layer's `duration` defaults to its parent's length: with `at` greater than 0 and no `duration`, `info.progress` stops short of 1 when the movie ends, so give a `duration` when you draw from `progress`. `check` draws each canvas layer in a scratch canvas (so reading its pixels does not change how the real one is drawn) at four moments: one draw of each is thrown away (a browser can draw a canvas from `setup` differently the first time), then each moment is drawn twice and in two orders. It prints a `canvas` line when every layer passed (`deterministic · slowest draw 3.2 ms`), so silence is never the only sign that it ran, and a layer that is not deterministic is reported under that heading with the moments, how many channel values differ and by how much (up to N of 255).

## 3D layers & camera

Place any 2D layer in depth and view it through a camera — After Effects style, no three.js. Everything uses the normal `initial` / `keyframes` / expression vocabulary.

### Conventions (read this first)

| Thing | Convention |
|---|---|
| Axes | `+x` right, `+y` down, **`+z` toward the viewer** (like CSS `translateZ`). Bigger `z` = nearer = larger on screen. |
| Units | Positions in composition pixels. **Rotations in degrees.** |
| Rotation signs | Same as CSS: `rotationY: 30` swings the right edge away; `rotationX: 30` brings the bottom edge toward you; `rotation` is the Z axis. |
| Rotation centre | The same point 2D `rotation` uses: `anchorX/anchorY` (sprites, text, shapes) or `pivotX/pivotY` (compositions). Set `anchorX: 0.5, anchorY: 0.5` to spin about the centre. |
| Default camera | Centred, looking straight at the `z = 0` plane, which maps 1:1 to pixels. A `threeD` layer at `z = 0` looks identical to a 2D layer. |
| Camera props | `x`, `y`, `z`, `lookAtX`, `lookAtY`, `lookAtZ`, `fov` — all in `initial` / `keyframes`, never on the camera itself. |

### `threeD` layers

Add `threeD: true` to any visual layer, then use `z`, `rotationX`, `rotationY`:

```json
{
  "sequences": [
    { "type": "text", "text": "tilted", "threeD": true,
      "style": { "fontSize": 64, "fill": "#ffffff" },
      "initial": { "x": "GW/2", "y": "GH/2", "anchorX": 0.5, "anchorY": 0.5, "rotationY": -35 },
      "keyframes": [{ "at": 0, "to": { "rotationY": 0 }, "duration": 1, "ease": "power2.out" }] }
  ]
}
```

`z`, `rotationX` and `rotationY` are ignored on a layer without `threeD: true` (a warning tells you). `threeD: false` layers ignore the camera and keep stack order.

### Camera

The camera is a layer: `{ "type": "camera" }`. It has no visuals. With nothing set it is the default camera.

| Prop | Meaning | Default |
|---|---|---|
| `x`, `y` | camera position | `W/2`, `H/2` |
| `z` | camera depth. **Auto:** if you never set it, it follows `fov` so the `z = 0` plane stays 1:1 | `(H/2) / tan(fov/2)` |
| `lookAtX`, `lookAtY`, `lookAtZ` | the point it looks at | `W/2`, `H/2`, `0` |
| `fov` | vertical field of view, degrees (clamped to 1–179) | 40 |
| `focus` | the plane that is **sharp**: a `threeD` layer's name (its first `z`) or a z number. Turns depth of field on (see [Depth of field](#depth-of-field)) | the `z = 0` plane |
| `aperture` | how shallow: the lens diameter in px. `0` = off. Written alone, or with `focus`, it turns depth of field on | `30` |
| `offsetX`, `offsetY`, `offsetZ`, `lookOffsetX`, `lookOffsetY`, `lookOffsetZ` | **added** to the position and to the look-at point, on top of the camera's own move. Put a handheld shake (`wiggle()`) here and it never collides with a dolly or an orbit (two tweens on the same prop overwrite each other; these are separate props) | 0 |

A flight through the scene is [`cameraPath()`](#camerapath) (a route as keyframes); a threeD layer the camera passes on purpose takes `hideBehindCamera: true` (hidden quietly when it is at or behind the camera, instead of a warning).

```json
{
  "sequences": [
    { "type": "camera", "name": "cam",
      "keyframes": [
        { "at": 0, "from": { "x": "GW/2 - 260", "lookAtX": "GW/2 - 260" },
                   "to":   { "x": "GW/2 + 260", "lookAtX": "GW/2 + 260" },
          "duration": 4, "ease": "sine.inOut" }
      ] },
    { "type": "shape", "shape": "rect", "width": 300, "height": 200, "threeD": true,
      "initial": { "x": "GW/2", "y": "GH/2", "z": -400, "fillColor": "#3a6ea5" } },
    { "type": "shape", "shape": "rect", "width": 300, "height": 200, "threeD": true,
      "initial": { "x": "GW/2", "y": "GH/2", "z": 250, "fillColor": "#d96a3a" } }
  ]
}
```

Moving the camera sideways makes the near rectangle slide faster than the far one (parallax). Animating only `fov` keeps the `z = 0` plane fixed and changes how strong the perspective is (a dolly zoom):

```json
{
  "sequences": [
    { "type": "camera",
      "keyframes": [{ "at": 0, "to": { "fov": 70 }, "duration": 3, "ease": "sine.inOut" }] },
    { "type": "shape", "shape": "circle", "radius": 120, "threeD": true,
      "initial": { "x": "GW/2", "y": "GH/2", "z": 300, "fillColor": "#38a169" } }
  ]
}
```

- A camera affects the `threeD` layers that are its **siblings** (same composition). A nested composition has its own camera for its children, and is itself a layer in its parent's space when it has `threeD: true`.
- Several cameras may exist if their lifespans (`at` / `duration`) do not overlap — each is a camera cut. Overlapping cameras warn; the last-listed one wins.
- With no camera layer the default camera is used.

### Depth of field

Write `focus` (and, if you want, `aperture`) on the camera and the `threeD` layers blur by how far they are from the plane in focus; the layer in focus stays sharp. Nothing else changes: without `focus` and `aperture` there is no blur and no cost.

```json
{
  "sequences": [
    { "type": "camera", "initial": { "focus": "title" } },
    { "type": "text", "name": "title", "text": "Focus", "threeD": true, "style": { "fontSize": 96, "fill": "#ffffff" }, "initial": { "x": "GW/2", "y": "GH/2", "z": 0, "anchorX": 0.5, "anchorY": 0.5 } },
    { "type": "shape", "shape": "circle", "radius": 140, "threeD": true, "initial": { "x": "GW/2 + 260", "y": "GH/2", "z": -500, "fillColor": "#3a6ea5" } }
  ]
}
```

A focus pull is a normal keyframe on `focus`; a layer name works there too:

```json
{
  "sequences": [
    { "type": "camera", "initial": { "focus": "front", "aperture": 60 },
      "keyframes": [{ "at": 1, "to": { "focus": "back" }, "duration": 1, "ease": "power2.inOut" }] },
    { "type": "shape", "shape": "rect", "name": "front", "width": 300, "height": 200, "threeD": true, "initial": { "x": "GW/2 - 200", "y": "GH/2", "z": 100, "fillColor": "#d96a3a" } },
    { "type": "shape", "shape": "rect", "name": "back", "width": 300, "height": 200, "threeD": true, "initial": { "x": "GW/2 + 200", "y": "GH/2", "z": -400, "fillColor": "#3a6ea5" } }
  ]
}
```

- `aperture` is the lens diameter in pixels; the blur radius of a layer is `aperture × focal × |1/depth − 1/focusDepth| / 2` (focal = `(H/2)/tan(fov/2)`), capped at 32 px. With the default camera at 720p and the focus on `z = 0`, a layer at `z = −400` blurs by: `aperture 10` → 1.4 px (a soft hint), `30` → 4.3 px (clearly shallow), `60` → 8.6 px (strong), `100` → 14.4 px (extreme: small bright objects show a faint speckle). A layer further away blurs more, up to the cap.
- A layer **nearer** than the focus blurs too, and for the same `z` distance a near layer blurs more than a far one: with `aperture: 58` and the focus on a sign at `z = −600`, a layer at `z = +250` blurs about 21 px; with the focus on a layer at `z = +250`, a layer at `z = −1100` blurs about 25 px (720p, default camera). Plan a scene with the formula above, or read `depthBlur` from `movie.inspect(frame)`.
- A layer name in `focus` means **the first `z`** of that layer; if its `z` moves later, animate `focus` itself with numbers (a warning says so). A name that no layer has, or a layer that is not `threeD`, warns and uses the `z = 0` plane.
- The blur is the same over the whole layer (decided by the depth of the layer's origin along the camera's view direction: with an orbiting camera a layer far off the look-at axis is a little deeper than its `z`). A tilted floor is one blur: split it into layers.
- It blurs `threeD` layers only. A nested `threeD` composition is blurred as one layer by its parent's camera; its own camera decides its content.
- The layer's own `blur` and its `filters` are separate and add to it.
- Many blurred layers cost one filter pass each (more on WebGPU): 20 or more at once warns. A field of bokeh lights is a few big `threeD` cards (a plain layer or a composition with a few dozen circles in it), not dozens of layers. To make a card at depth `z` fill the frame, size it `(W / s) × (H / s)` with `s = camZ / (camZ − z)` (`camZ` = the camera's z, about 989 at 720p, fov 40): at `z = −720` that is `s = 0.58`, so about 2210 × 1240 for a 1280 × 720 frame.
- A **dolly** needs no typed distance: leave the camera's `z` alone (it stays automatic) and animate `offsetZ` (negative = closer); the focus plane and the layers keep their meaning. Writing `z` yourself means typing the home distance, `H / 2 / tan(fov / 2)`, which as an expression is `H / 2 / tan(20 * PI / 180)` for the default fov 40.
- If two layers have the same `name`, `focus` takes the first `threeD` one (and warns that the name is not unique). `focus` and `aperture` are camera properties: on any other layer they only warn.
- A negative or non-numeric `aperture` warns once and turns depth of field off.
- `movie.inspect(frame)` reports each `threeD` layer's blur as `depthBlur` (px, 0 = sharp).

### Lights

A `light` layer lights the `threeD` layers of its composition: they get darker and brighter with their angle and distance, like cards in a dark room. It is a layer like the camera: it draws nothing, and its numbers go in `initial` and `keyframes` (so it moves, springs, takes expressions and `ease`).

```ts
{ type: 'light', kind: 'ambient', initial: { intensity: 0.2 } },                    // what no other light reaches is this dark, not black
{ type: 'light', kind: 'spot', castsShadows: true,                                  // a spotlight that crosses the picture
  initial: { x: 160, y: -120, z: 700, lookAtX: 260, lookAtY: 330, lookAtZ: 0, coneAngle: 34, coneFeather: 0.7, intensity: 1.1 },
  keyframes: [{ at: 0.5, to: { x: 1100, lookAtX: 1020 }, duration: 4.5, ease: 'sine.inOut' }] },
{ type: 'shape', shape: 'rect', name: 'card', width: 300, height: 200, threeD: true, castsShadows: true, initial: { x: 300, y: 300, z: 0, fillColor: '#e0a458' } },
```

`kind` (a fixed setting on the layer): `'ambient'` (the same colour everywhere), `'point'` (from a position in every direction; the default), `'spot'` (a point light inside a cone around the direction to its look-at point), `'parallel'` (a direction only, from the position toward the look-at point: the sun). `falloff` (also fixed): `'none'` (default), `'smooth'` (full inside `radius`, fading to nothing over `falloffDistance` more), `'inverseSquare'` (full at `radius`, a quarter at twice that). Numbers you can animate:

| name | meaning | default |
|---|---|---|
| `x` `y` `z` | where the light is (px, like a layer; `z` toward the viewer) | up and to the left of the picture, 0.6 of the camera's distance |
| `lookAtX` `lookAtY` `lookAtZ` | the point a `spot` or `parallel` light points at | the middle of the picture |
| `intensity` | a multiplier: 1 = full, 0.25 = a quarter (not a percentage) | 1 |
| `color` | any colour (`'#ffd9a0'`) | white |
| `coneAngle` `coneFeather` | a spot's full angle in degrees, and the soft part of its edge as a fraction of the half angle (0 = hard, 1 = soft all the way in) | 90, 0.5 |
| `radius` `falloffDistance` | where the falloff starts and how far it runs (px) | 500, 500 |
| `shadowDarkness` `shadowDiffusion` | how dark the shadows of this light are (0..1) and how soft their edge is (px; 0 = hard) | 1, 0 |

Rules:
1. **A composition with a `light` layer lights every `threeD` layer in it.** To keep one unlit, write `lit: false` on it. Layers without `threeD` are never lit. **A composition with no light and no fog makes nothing new: the shader is not built and the picture and the cost do not change.**
2. **What no light reaches is black.** Add an ambient light (the build warns when there is none). A white ambient light at intensity 1 is no light at all: the picture is the one you would get without lights. A light behind a layer does not light the side the camera sees.
3. **A light counts only while it is alive** (its own `at` and `duration`). With no light alive at a moment, the layers are drawn unlit, as in a composition without lights; so give the lights the length of the scene.
4. **Each composition has its own lights.** A light inside a nested composition lights only that composition's `threeD` layers; an outer light does not reach inside it. A `threeD` composition (a card) is lit as one picture by its parent's lights.
5. **Layers are drawn in distance order and there is no depth buffer.** Planes that cross each other cannot be shown; for a floor or a wall, put the layer's origin at its far edge so it sorts behind what stands on it.
6. **Shading works on the sRGB values** (like After Effects): a strong light clips to white. The shading is `colour × (ambient + the lights)`, each light by `N·L`, its falloff and its cone.
7. **Order:** the layer's own `filters` run first (they draw into the layer's picture), then the shading, the fog, the depth-of-field blur, and last the `blendMode`. All of them work together.
8. At most 8 lights besides the ambient ones are used (the first 8 in layer order; the build says which are left out). Ambient lights are added up.
9. `color` keyframes mix in sRGB like other colour keyframes (`'#ff0000'` → `'#0000ff'` passes `#800080`). A light has no `colorSpace`.
10. `movie.inspect(frame)` gives each lit `threeD` layer a `light`: how lit its middle is (1 = as bright as with no light, 0 = black); `check.mjs --at` prints the most lit first. It is the number at the layer's **middle** and shadows are not in it, so it can say 1 for a layer whose lit part is hidden.
11. **A spot's pool on a wall** is a circle of radius about `distance × tan(coneAngle / 2)` around where its axis meets the wall (a 36° cone from 700 px away lights a circle about 230 px in radius), softened by `coneFeather`. A card in front of the wall throws its shadow on the far side from the light and can cover the pool behind it: make the cards smaller than the pool, or bring the lamp closer. A caster outside the pool still throws its shadow into it. A **floor** is a big layer with `rotationX: 90` and its origin at its far edge (`anchorY: 0`).

Checked against an independent JS reference of the shading (every pixel within 2/255) on WebGPU and WebGL, for ambient, point, spot and parallel lights, the three falloffs, a card turned on two axes, and a card seen from its back. Cost, measured at 1080p on one machine (an Apple M1 Pro, headless Chrome) as the extra time per frame against the same scene without light: lights alone cost about 1 ms on WebGPU (20 layers, 3 lights: 2.6 ms) and about the same on WebGL; shadows are the price (below).

### Shadows

A shadow needs both halves: the **light** has `castsShadows: true` and the **layer** has `castsShadows: true`. Then the layer's outline (its own picture's alpha) darkens the other lit `threeD` layers behind it, on the side away from the light.

- Hard edges by default (a hard shadow can read as a dark slab: `shadowDiffusion` of 10 to 20 usually looks right). `shadowDiffusion` (px, on the light) widens the edge, wider the farther the shadow falls from the caster, so a card near the wall has a sharp shadow and one far from it a soft one. `shadowDarkness` (0..1) sets how dark.
- A layer receives shadows from at most **4** casters (the first 4 in layer order; the build says which are left out), never from itself, and a caster that is hidden (outside its life, alpha 0, behind the camera) casts nothing. Several shadows join by the strongest, not by adding up, so overlaps are not darker.
- A shadow is the shadow of a flat picture: a card turned on its axis casts the turned outline; there is no self-shadowing, no shadow on a layer that is not lit (`lit: false`), no coloured or see-through shadow.
- **Soft shadows are the expensive part** (16 samples per pixel per caster). Measured at 1080p, extra ms per frame (WebGPU / WebGL): 5 layers, 1 light, hard 1.4 / 1.6, soft 4.6 / 6.1; 20 layers, 1 light, hard 0.8 / 0.1, soft 5.3 / 10.4; 20 layers, 3 lights, hard 2.6 / 8.7, **soft 19.8 / 21.6**. Three or more lights with soft shadows warn; give `shadowDiffusion` to one or two lights.

### Fog

The camera takes `fogNear`, `fogFar` (distances along the view direction, px), `fogColor` and `fogAmount` (0..1, how much of the colour the farthest things get). Writing any one of them turns fog on (the others default to: near = the camera's home distance, far = three times that, black, 1). A `threeD` layer is mixed toward the fog colour by its depth, per pixel (so a floor going away gets a true gradient). It comes after the shading and before the depth-of-field blur. 2D layers are not fogged: draw the background in the fog colour so what is far dissolves into it. Without lights, fog alone costs almost nothing. `fogFar` not beyond `fogNear`, or an amount outside 0..1, warns.

### Depth order and limits

- Consecutive `threeD` layers are drawn farthest-first. A non-`threeD` layer between them splits the group (like After Effects).
- A layer at or behind the camera is hidden for that frame.
- v1 limits: planes do not intersect (whole layers are sorted; with lights this shows when you build a room: see [Lights](#lights)); masks, transitions and `filterArea` are not supported on `threeD` layers (a mask is ignored with a warning); each `threeD` layer costs one extra render pass per frame.
- Wrong-but-likely names (`rotateY`, `translateZ`, `depth`, `perspective`, `zoom`) are not accepted; the console tells you the right name.

---

## three

Composites a [three.js](https://threejs.org/) scene as a normal layer. Each frame, the scene is rendered into an offscreen WebGL canvas and uploaded into the sequence's PIXI texture — so once built, the layer is a plain sprite: 2D `initial` / keyframe props, [masks](#masks), and [filters](#filters) all apply to it exactly like any other sequence type.

`type: 'three'` lives in the optional `pixi-effects/three` entry, not core `pixi-effects` — see [API reference](./api.md#pixi-effectsthree) for install/import details.

```ts
import { registerThree, three } from 'pixi-effects/three';
import * as THREE from 'three';

registerThree();   // once, before Movie.init

three({
  type: 'three',
  name: 'knot',
  width: 'GW * 0.6', height: 'GH * 0.6',
  initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
  setup: (ctx) => {
    const knot = new THREE.Mesh(
      new THREE.TorusKnotGeometry(1, 0.35, 128, 32),
      new THREE.MeshStandardMaterial({ color: 0x7fb4ff }),
    );
    ctx.scene.add(knot);
    ctx.camera.position.z = 4;
    return { objects: { knot } };    // exposes `knot` to keyframes, see below
  },
  keyframes: [
    { at: 0, to: { 'three.knot.rotation.y': Math.PI * 2 }, duration: 6 },
  ],
})
```

### Spec fields

| Field        | Type                                                        | Notes                                                                                   |
| ------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `width?`     | `PropValue`                                                 | layer size in composition px; expressions allowed (e.g. `'W * 0.5'`). Default: parent composition size. |
| `height?`    | `PropValue`                                                 | see `width`.                                                                              |
| `resolution?` | `number`                                                    | supersampling factor for the offscreen canvas. Default `1`.                              |
| `antialias?` | `boolean`                                                   | multisampling of the layer's canvas. Default `true`. `false` makes WebGL and WebGPU agree (see below). |
| `renderer?`  | `'webgl' \| 'webgpu'`                                        | which three.js renderer draws the layer. Default `'webgl'` (`WebGLRenderer`). `'webgpu'` uses `WebGPURenderer` from `three/webgpu` (see below). |
| `setup`      | `(ctx: ThreeContext) => Promise<ThreeSetupResult \| void> \| ThreeSetupResult \| void` | builds the scene once. Add objects to `ctx.scene`, position `ctx.camera` (or replace it via `{ camera }`). Async, so `Movie.init` can await GLTF / texture loading. |
| `followCamera?` | `boolean`                                                | the layer's camera is the composition's `camera` layer (see [below](#living-in-the-compositions-space-followcamera-followlights)). |
| `followLights?` | `boolean`                                                | the composition's `light` layers become three lights in the scene (see below).            |
| `reuse?`     | `boolean`                                                   | a rebuild (`setVars`, `resize`, `rebuild`) keeps a layer that did not change (same `name`, `setup`, size, options): its `setup` runs once. Default `true`; `false` runs `setup` at every rebuild (when it reads a value that variables change). |
| `update?`    | `(t: number, ctx: ThreeContext) => void`                    | optional per-frame hook; `t` is sequence-local time in seconds.                          |
| `dispose?`   | `(ctx: ThreeContext) => void`                                | cleanup for user-created GPU resources (geometries, materials, textures). Called from `destroy()`. |

`ThreeContext` is `{ scene, camera, renderer, width, height, space? }` — the three.js `Scene`, `Camera`, `WebGLRenderer`, the resolved layer size in composition px, and (with `followCamera` / `followLights`) `space`: the composition's camera and the lights alive at this moment, as plain numbers.

### `renderer: 'webgpu'`

The layer's own three.js renderer is `WebGLRenderer` unless you ask for `renderer: 'webgpu'`, which makes it three's `WebGPURenderer` (the picture is still copied into the layer's texture, so filters, masks, blend modes and mattes work as on any layer). It needs three 0.17x or later and `three/webgpu` in the import map next to `three` (both files import the same `three.core.js`, so they share one copy of three). Where the browser has no WebGPU, three itself falls back to its WebGL2 backend.

- **In a movie that PixiJS draws on WebGPU, a `'webgpu'` layer draws on PixiJS's own GPU device** (`shareGpu`, default `true`): it renders into a texture that PixiJS samples directly, with no canvas of its own and no copy. The picture is the same (measured 2026-10-17: 0 of 255 different in every channel of nine pictures, with antialias, fog and tone mapping), it is faster (spike, one Apple machine: 0.7 against 1.1 ms for one layer, 1.6 against 5.7 ms for ten), and the limit of about 32 WebGPU canvases does not apply (60 layers drew in the test film `three-budget`; a layer on the shared device is not counted in the budget warning). `shareGpu: false` gives the layer a canvas of its own as before, and so does a movie PixiJS draws on WebGL (the layer then counts against the 32). If the shared route fails, the layer says so once and is made again on its own canvas before `setup` runs. `movie.inspect()` lists `sharedGpu` for such a layer. This reaches into one field of PixiJS (`source._gpuData`); a PixiJS that moved it makes every layer fall back, with that one warning.
- `ctx.renderer` is a `WebGLRenderer` or a `WebGPURenderer`; `setClearColor`, `toneMapping` and `toneMappingExposure` exist on both.
- **The default stays `'webgl'`.** A scene built the way AI usually writes three code (`ShaderMaterial` / `RawShaderMaterial` with GLSL, a `WebGLRenderTarget` post chain with fullscreen quads, `onBeforeCompile`) cannot run on three's WebGPU renderer; it needs a rewrite with node materials (TSL). Tried on four large stock clips (custom bloom, 4K): all four stop with `Material "ShaderMaterial" is not compatible`. Use `'webgpu'` for scenes made of the built-in `Mesh*Material`s, `InstancedMesh`, `Points` and lights. At 1280×720 and 3840×2160 an MP4 export took the same time with either renderer.
- **One word for a whole page:** `registerThree({ renderer: 'webgpu' })` is the default of every three layer that names no `renderer` of its own (the layer's own value wins; `registerThree()` means `'webgl'`).
- **No WebGPU in the browser:** three's `WebGPURenderer` then draws with its own WebGL2 backend. It is the same picture (measured: 0.00 of 255 without antialias, edges only with it) and the output order of the WebGPU renderer, not that of `WebGLRenderer`. The layer does not choose by machine; `ThreeSequence.backend` says `'webgpu'`, `'webgl2'` or `'webgl'`, and the "WebGPU is not available" warning is not printed.
- **Import three's classes from `three/webgpu` on such a page** (`import * as THREE from 'three/webgpu'`: it re-exports everything in `three`, and its `PMREMGenerator` and the like are the ones that work with a `WebGPURenderer`). A `PMREMGenerator` taken from `three` fails inside `setup`; the layer says so and names the fix.
- Materials that rewrite three's shaders (`onBeforeCompile`, `ShaderMaterial`, `RawShaderMaterial`) do not run on the WebGPU renderer: a layer that chose `renderer: 'webgpu'` stops building, naming the material and the fix (`renderer: 'webgl'`), instead of drawing a picture that is wrong without saying so. Only what `ctx.scene` holds is looked at: a `ShaderMaterial` kept in a scene of your own and drawn through `ctx.renderer` (a post-processing quad) is not found; three then logs `Material "ShaderMaterial" is not compatible` on every render. The built-in `Mesh*Material`s, `InstancedMesh` and `Points` do run.
- **Lights follow the time.** Three's WebGPU renderer updates its light uniforms (and its `time`) once per animation-loop frame, so renders that follow each other in one task (a seek, an export) would all show the same lights and a lamp keyframed with `three.lamp.intensity` would not move. The layer therefore advances three's node frame before each render and gives its `time` the layer's own time (this reaches into a private field of three's renderer: a three that no longer has it makes the layer warn once).
- Measured on one Apple (Metal) machine, headless Chrome, 2026-10-15: the same lit box drew with a mean difference of 0.04–0.06 (of 255) per channel from the WebGL picture (only edge pixels differ). On the repository's own pages the WebGPU picture equals the WebGL one except where a material used `onBeforeCompile` (`three-product-spin`: the floor reflection no longer fades) and where the scene has fog or a hot, thin edge: see "Where the two renderers differ on purpose". The render alone, waiting for the GPU, took about 0.8–0.9 ms either way for a box; for 2,880 instanced rods under two point lights it took about 0.9–1.2 ms on WebGPU against 1.7–2.1 ms on WebGL (1280×720 to 1920×1080). A 90-frame MP4 export took the same time with either (about 22 frames per second: the encode, not three, was the limit).

#### Where the two renderers differ on purpose

Found in `light-as-material` (a brighter amber highlight on WebGPU, mean 2.9 of 255) and pinned by `tests/films/three-renderers`. The shading maths (point lights, PBR, instancing, the environment map, ACES) was compared line by line and measured equal; what differs is the order of the output steps:

- **Fog** is blended in linear light BEFORE tone mapping on WebGPU and AFTER tone mapping and the sRGB encode on WebGL. A lit scene in fog is brighter on WebGPU (mean 3.1 of 255 in the test film; the largest part of the difference).
- **Multisampling** (`antialias`, on by default) is resolved in linear light before tone mapping on WebGPU, after it on WebGL: thin, hot edges come out brighter on WebGPU. `antialias: false` on the layer removes this (use `resolution` for supersampling).

With `antialias: false` and no fog the two agree to 0.04 of 255 (the real film: 0.09). three.js calls the WebGPU order "more correct"; keep one renderer per look, and re-tune fog density or exposure when you switch.

### Living in the composition's space: `followCamera`, `followLights`

By default a `three` layer is a flat picture with a camera and lights of its own: the composition's `camera` and `light` layers move it as a card (with `threeD: true`) but do not reach the scene inside. Two switches make the scene part of the composition's space instead:

```ts
three({ type: 'three', name: 'world', followCamera: true, followLights: true,        // the layer covers the composition (its default size) and sits in the stack like any layer
  setup: (ctx) => {
    for (const [x, y, z, color] of [[300, 270, 0, 0x3a6ea5], [660, 270, -300, 0xd96a3a]]) {
      const card = new THREE.Mesh(new THREE.BoxGeometry(200, 200, 200), new THREE.MeshLambertMaterial({ color }));
      card.position.set(x, -y, z);                                                    // composition pixels, y flipped: the composition's (x, y, z) is (x, -y, z) here
      ctx.scene.add(card);
    }
  } }),
{ type: 'camera', keyframes: [{ at: 0, to: { x: 780, fov: 70 }, duration: 3 }] },    // moves the flat layers AND this scene (cameraPath() works the same)
{ type: 'light', kind: 'point', initial: { x: 300, y: 100, z: 700 } },
```

- **`followCamera`** puts the layer's `PerspectiveCamera` where the composition's active camera is, every frame: position, look-at point and vertical `fov` (also the `offset` props of a handheld shake). The scene is in **composition pixels with y flipped** (three's y runs up, the composition's down; +z is toward the viewer in both), so a flat layer and a three object at the same `(x, -y, z)` land on the same pixel (checked to 1e-6 px for several cameras, and in the real picture against the composition's own cards: mean 0.14–0.19 of 255, edges only). `near` is 1 and `far` 20000 (it is px: the default camera is about 740 away). The camera must be a `PerspectiveCamera` and the layer must have the composition's aspect ratio (the camera shows the whole composition): both are warned once. Your own `update(t, ctx)` runs after the camera is set, so it may nudge it.
- **`followLights`** makes the composition's `light` layers three lights in `ctx.scene`, one per light alive, moved every frame (a light that ended is switched off). `ambient` → `AmbientLight`, `point` → `PointLight`, `spot` → `SpotLight` (`coneAngle` / 2 is the angle, `coneFeather` the penumbra), `parallel` → `DirectionalLight` toward its look-at point; position `(x, -y, z)`, colour and `intensity` as written (three divides a diffuse surface by π, so the layer multiplies by π: intensity 1 is "as bright as the colour", like a card). `falloff: 'none'` is no attenuation. `'inverseSquare'` is decay 2 and full at `radius`: **outside the radius it matches the composition's** (measured mean 0.02–0.03 of 255), but inside it three keeps rising where the composition holds 1 (4× at half the radius): the layer warns once when an object is closer than 0.8 of the radius, and the way out is a smaller radius or `'smooth'`. `'smooth'` fits three's cut-off to the composition's curve (1 inside `radius`, a smoothstep to 0 at `radius + falloffDistance`): three's curve is gentler, so the fit halves the largest difference (about 0.09–0.17 of the light's strength for a fall that is not steep, mean 0.08–0.28 of 255 in the real picture; a fall that is steep against its radius, say `falloffDistance` 100 at `radius` 500, can differ by about 0.3). **Shadows** follow the light: a light with `castsShadows: true` casts in three (the darkness is the shadow's intensity, `shadowDiffusion` softens its edge; the layer switches its renderer's shadow map on), and the layer's own meshes decide who casts and who receives (`mesh.castShadow = true`, `mesh.receiveShadow = true`; a plane needs `material.shadowSide = THREE.DoubleSide` to cast). The composition's `castsShadows` on a layer is not read (its layers are not in the scene). **Fog** is `followFog`. The layer's own lights stay as they are.
- **`followFog`** makes the composition camera's fog (`fogNear`, `fogFar`, `fogColor`) the scene's `Fog`, every frame (the `Fog` goes when the camera that wrote it is over; a `scene.fog` the layer made itself is never touched; `ctx.space.fog` has the numbers). It is **close, not equal**: three fades with `smoothstep` between `near` and `far` where the composition fades linearly, and three's Fog has no amount below 1 (`fogAmount` other than 1 warns once and the full amount is used). Measured against the composition's own cards: a mean difference of 0.5–1.8 of 255, where the fog itself changes the picture by 2–7. On `renderer: 'webgpu'` fog is blended before tone mapping, as for any three scene (see below).
- **How close the shadow is to a card's.** A card in front of a wall under a spot light throws the same shadow on the wall as the composition's cards do (same place, size and darkness): mean difference 0.2–0.35 of 255, on WebGL and WebGPU; what differs is the edge of the shadow map (a hard shadow of a small card is a little jagged at the default 2048 map). Soft shadows (`shadowDiffusion`) are three's PCF blur, not the composition's 16-sample penumbra: similar in kind, not in shape.
- **How close the light is to a card's.** The composition shades a card on sRGB values (`colour × (ambient + the lights)`); three lights in linear light. With `MeshLambertMaterial` and three's colour management off (`THREE.ColorManagement.enabled = false` and `ctx.renderer.outputColorSpace = THREE.LinearSRGBColorSpace` at the top of `setup`; **both are global to the page's three**, so they colour every three layer there) the planes shade like the cards: measured mean 0.02–0.04 of 255 (ambient), 0.16–0.20 (point), 0.11–0.14 (parallel), 0.14–0.16 (spot). With three's defaults (the right choice for glTF models and `MeshStandardMaterial`) the lights are close and not equal: mean 0.8–1.4 of 255. A physically based material answers the light the way it does in three, not the way a card does.
- **Where it sits.** The layer is an ordinary layer at its place in the stack (not a `threeD` card): flat `threeD` layers and this scene order by the stack, not by depth, and there are no shadows between them. Give the layer `threeD: true` only if you want the whole picture to be a card again.
- `ctx.space` is `{ camera: { x, y, z, lookAtX, lookAtY, lookAtZ, fov }, lights: [...] }` in composition pixels, the numbers before the y flip. A composition with a `camera` or `light` and no `threeD` layer no longer warns "has no effect" when a three layer follows it.
- The layer's frame is a function of the time: the camera and the lights are read for the layer's own moment, so a seek, an export and a repeat give the same picture (`tests/films/three-space`, also across a light that begins and ends, and with `renderer: 'webgpu'`).

### glTF models: `threeGltf`, `threeFrameCamera`

A `three` layer stays the free box; two helpers from `pixi-effects/three` do what is easy to get wrong by hand (the page's import map needs `"three/addons/"` next to `"three"`; Draco / KTX2 / Meshopt files need their decoder set up by hand):

```ts
import { threeGltf, threeFrameCamera } from 'pixi-effects/three';
let fox;
three({ type: 'three', width: 'GW', height: 'GH',
  setup: async (ctx) => { fox = await threeGltf('Fox.glb', { animation: 'Run' }); ctx.scene.add(fox.object, new THREE.AmbientLight(0xffffff, 1.2), new THREE.DirectionalLight(0xffffff, 2)); threeFrameCamera(ctx.camera, fox.object); },
  update: (t) => fox.pose(t) })
```

- **`threeGltf(url, { animation, speed, offset, loop })`** loads the file with three's `GLTFLoader` and returns `{ object, clips, size, pose(t), fit(px), dispose() }`. `object` is a `Group` whose origin is the centre of the model's bounding box (bind pose): place it, turn it and scale it about its centre. `clips` are the names in the file; `animation` is a name, an index or `false` (the bind pose), default the first clip. **`pose(t)`** puts the model in the pose of the clip at `t × speed + offset` seconds (`loop: false` holds the last pose): `AnimationMixer.setTime` re-evaluates the clip from zero on every call, so a seek, an export and a repeat give the same frame. (`mixer.update(dt)` or a clock in `update` would not: they are what the layer's rule 2 forbids.) A failed load names the URL; a clip name the file does not have lists the ones it has. **`fit(px)`** scales `object` so the model's longest side is `px`: a glTF is in metres, a scene that follows the composition is in pixels.
- **`threeFrameCamera(camera, object, { direction, margin })`** puts a `PerspectiveCamera` where the whole of `object` (its box now, with its scale and place) fits the frame, looking at its centre, from a three-quarter view (`direction` default `[0.45, 0.3, 1]`) with 10 % room (`margin` 1.1): the smallest distance at which the 8 corners of the box fit both the vertical and the horizontal field of view (a bounding sphere would leave a long model small and head-on). It uses the camera's own `fov` and `aspect` and sets `near` / `far`. The box is the bind pose: a clip that travels far needs a camera of your own.
- With `followCamera` the composition's camera is the layer's camera (do not call `threeFrameCamera`); with `followLights` its lights light the model. See the recipes `gltf-in-space` and `gltf-shadow-room`. `orbit()` and `cameraPath()` drive the composition's `camera` layer, so they carry a following scene too.

### Keyframe paths: `three.<name>.<path>`

Objects returned from `setup`'s `{ objects }` are addressable from keyframes as `three.<name>.<path>`, using the same `from`/`to`/`set` vocabulary as every other prop:

```ts
setup: (ctx) => {
  const knot = new THREE.Mesh(/* ... */);
  ctx.scene.add(knot);
  return { objects: { knot } };
},
keyframes: [
  { at: 0, to: { 'three.knot.rotation.y': Math.PI * 2 }, duration: 6 },
  { at: 0, to: { 'three.knot.position.x': 1.5 },         duration: 3 },
],
```

`camera` is exposed implicitly as `three.camera.<path>` unless `setup`'s `objects` already defines a `camera` key.

### Rules

1. Call `registerThree()` before `Movie.init` builds a composition containing a `type: 'three'` sequence — the sequence type is looked up by name at build time.
2. `update(t)` must derive all state purely from `t` — no wall clock, no unseeded randomness. Playback and export both seek arbitrarily; anything else in `update` means identical timestamps can render different pixels. **`check` holds the layer to it, as it does a `canvas` layer:** it draws the scene at four moments in two orders (one draw thrown away first) and reports a layer whose same frame is not the same picture (a clock, `Math.random`, a mixer advanced with `mixer.update(dt)`, a speed that builds up from call to call), naming the moments and the fix; a `Math.random` / `Date.now` / `performance.now` / `new Date` in `update` also warns at build. It prints a `three` line when every layer passed, on WebGL and WebGPU alike.
3. Each three sequence owns one renderer and so one graphics context (an offscreen canvas). A browser keeps about **16 live WebGL contexts for the whole page** (PixiJS and a `shader` layer use some too) and about **32 WebGPU ones** (measured on Chrome, 2026-10-15; a `'webgpu'` layer that shares PixiJS's GPU device has no context of its own and is not counted); layers beyond that draw nothing, without an error. The layer therefore says so: once, when more than 12 WebGL (or 28 WebGPU) three layers are alive (with the count and the way out: put several objects in one layer, destroy layers that are over, or use the other renderer for some), and when the browser takes a layer's context away (`webglcontextlost`: the layer is named). Prefer one three layer with many objects to many layers.
4. Like `custom` filters, the spec carries functions (`setup`, optionally `update` / `dispose`) and is **not** JSON-serializable.
5. The scene renders into the layer rectangle: anything that projects outside it is clipped at the layer's edges. Frame the camera with margin for the whole animation — rotating objects often project taller/wider than their resting pose (a `TorusKnotGeometry(radius, tube)`, for instance, extends to `1.5 * radius + tube`, not `radius`).

---

## Masks

> A mask is a layer in the **parent's** coordinate space and does **not** follow the layer it masks: slide the content and the mask separately. Reveal by growing the mask's `width` from a fixed edge (`anchorX: 0`); exit by tweening `x` and `width` together.

Any sequence can carry an inline `mask` — itself a full sequence — that shapes which pixels of the maskee are visible. The mask runs in the same coordinate space as the maskee (added to the same parent composition) and shares its lifetime, so a circular avatar crop is just:

```ts
{
  type: 'image', asset: 'photo',
  initial: { x: 'W/2', y: 'H/2', anchorX: 0.5, anchorY: 0.5 },
  mask: {
    type: 'shape', shape: 'circle', radius: 130,
    initial: { x: 'W/2', y: 'H/2', fillColor: '#ffffff' },
  },
}
```

The mask is itself a sequence, so it can have `keyframes` of its own — useful for reveal animations (a circle growing from `scale: 0` to full size, a rect wiping across, …):

```ts
// Iris reveal — image is wiped in by a growing circle
{
  type: 'image', asset: 'photo',
  initial: { x: 'W/2', y: 'H/2', anchorX: 0.5, anchorY: 0.5 },
  mask: {
    type: 'shape', shape: 'circle', radius: 200,
    initial: { x: 'W/2', y: 'H/2', fillColor: '#ffffff', scale: 0 },
    keyframes: [
      { at: 0, to: { scale: 1 }, duration: 1.0, ease: 'power2.out' },
    ],
  },
}
```

Notes:
- The mask sequence is rendered as a mask, not as a normal child — its `fillColor` / `strokeColor` only matter for which pixels are kept, not for the visible colour.
- Any sequence type works as a mask (shape / image / text / video / nested composition); shapes are the natural choice for geometric reveals.
- A plain **shape** mask (not inverted) is a hard-edged stencil, the cheapest way. Every other mask (a text, image or video layer, an inverted or luma mask, a named matte, a list) is drawn into a texture once per frame and applied as a **matte filter**: its edges are soft and antialiased, it costs one offscreen pass, and `blendMode` works with it (see [Mattes](#named-mattes-and-luma)).
- For a left-to-right wipe, give the mask `anchorX: 0` (rect/circle/ellipse) so `width: 0 → full` grows rightward from the left edge.

#### An inverted mask: `mask: { layer, invert: true }`

Write the mask layer inside `layer` and add `invert: true` to flip the mask sense: pixels INSIDE the mask shape become transparent, pixels OUTSIDE stay visible. Useful for knockout / cutout effects (punch a circular hole through a panel, etc.). It works inside a masked group too: the hole is cut out of what the outer mask lets through, and nothing shows outside the outer mask.

```ts
// Photo with a circular hole punched through the middle
{
  type: 'image', asset: 'photo',
  initial: { x: 'W/2', y: 'H/2', anchorX: 0.5, anchorY: 0.5 },
  mask: {
    invert: true,
    layer: {
      type: 'shape', shape: 'circle', radius: 80,
      initial: { x: 'W/2', y: 'H/2', fillColor: '#ffffff' },
      keyframes: [
        { at: 0, to: { radius: 120 }, duration: 1.5, ease: 'sine.inOut' },
        { at: 1.5, to: { radius: 80 }, duration: 1.5, ease: 'sine.inOut' },
      ],
    },
  },
}
```

An inverted mask goes through the matte filter (the letters of a text mask, or a hole with a soft edge), so it works with every `blendMode` and with a mask that has its own `filters`. `{ layer: <the mask layer>, invert: true }` is the same thing as `{ layer: 'matteName', invert: true }` on a named matte (below); `channel: 'luma'` works on a layer written in place too. (A layer written in place cannot go inside a list of masks: give it a name.)

#### Named mattes and luma

A layer can be named and used as the mask of **several** layers (After Effects' track matte). Write its name as the `mask`; the matte layer itself is then **not drawn**. It is drawn once per frame into a texture, so three layers sharing one moving matte cost one extra pass, not three.

```ts
// one moving band cuts three layers; the band itself is not on screen
{ type: 'shape', shape: 'rect', name: 'wipe', anchorX: 0, width: 0, height: 420,
  initial: { x: 60, y: 300 }, keyframes: [{ at: 0.3, to: { width: 560 }, duration: 1.5 }] },
{ type: 'text', text: 'SHARED', mask: 'wipe' },
{ type: 'text', text: 'MASK', at: 0.2, mask: 'wipe' },
{ type: 'composition', width: 400, height: 300, mask: 'wipe', sequences: [ /* a whole picture, cut as one */ ] },

// by brightness instead of opacity (a grayscale image or a gradient layer), inverted, and a list
{ type: 'image', asset: 'photo', mask: { layer: 'vignette', channel: 'luma' } },
{ type: 'shape', shape: 'rect', width: 400, height: 300, mask: ['panel', { layer: 'hole', invert: true }] },  // inside `panel`, outside `hole`
```

| form | meaning |
|---|---|
| `mask: 'name'` | the same as `{ layer: 'name' }` |
| `mask: { layer, channel?, invert? }` | `channel: 'alpha'` (default: how opaque the matte is) or `'luma'` (how bright it is, Rec. 709); `invert: true` flips it (1 − matte) |
| `mask: [ref, ref, …]` | every one must let the pixel through: the result is the **product** (an intersection). **To subtract a matte, put `invert: true` on it** |
| `mask: { type: …, … }` | an inline mask layer, as above |

Rules:
1. **Outside the matte layer's own shape the matte is 0, for `luma` too** (nothing there is transparent and black), so a matte can be a wide gradient rectangle that you slide across the layers for a soft, moving reveal. **A layer that is used as a matte is not drawn.** It still needs to live long enough: the matte's time is the composition's time (its own `at` and `duration`). Where the matte is missing, the layers it cuts are **invisible**, so a matte whose lifetime does not cover its users warns.
2. **The name must be in the same composition** as the layer that uses it (a layer inside a nested composition cannot name a matte outside it). A layer that a transition wraps keeps its matte: the transition carries the `mask` to the wrapper.
3. A matte with a `parent` follows its parents (the null layers) as any layer does. A masked layer with a `parent` warns: the matte is in the composition's space, the layer in the null's space; put the mask on the null instead.
4. `threeD` layers cannot be mattes and cannot have one (a warning; the matte is drawn as the `threeD` layer it is, the mask is ignored).
5. **`blendMode` works with every matte**: the layer is cut by the matte and then blended (inside the matte it blends with the backdrop, outside it is the backdrop). A matte on a composition cuts the composition as one picture, as any filter does (its children's blends happen inside that picture).
6. A matte inside a **rotated or scaled nested composition** differs from the stencil only at the edges (soft instead of hard).
7. **Cost** (a prototype measurement at 1080p; not yet re-measured on the released code): WebGPU 0.32 ms for one layer, 0.75 ms for three, 2.65 ms for ten (0.67 ms and 1.97 ms when the layers share one matte); WebGL 1.22 / 4.03 / 11.0 ms. One matte is a texture of the composition's size (about 8 MiB at 1080p, more with anti-aliasing): **more than 8 mattes in one composition warns**. Share a matte between layers, or use fewer.
8. `inspect` does not list a matte layer (it is not drawn), and does not clip a masked layer's box by a named matte.

#### `blendMode`

How a layer blends with what is **behind it** (everything drawn below it in the stack): 18 modes, the CSS `mix-blend-mode` names (`add` and `linear-burn` are the two that CSS does not have; `linear-burn` is the After Effects / Photoshop name). Default `'normal'`. It works on every layer type, on `threeD` layers, and on a composition.

| mode | what it does |
|---|---|
| `normal` | the layer covers what is behind it |
| `add`, `screen` | brighten: overlapping glows, halos and light leaks add up instead of covering each other |
| `multiply` | darkens: shadows, vignettes, a tint over a photo |
| `overlay` | contrast: darks get darker, lights lighter, by what is behind |
| `soft-light` | a gentle `overlay`: colour casts, soft vignettes, a graded look |
| `hard-light` | `overlay` decided by the layer instead of the backdrop: strong punch |
| `color-dodge` | strong light: burns bright spots out toward white (light sources, lens flares) |
| `color-burn`, `linear-burn` | deep shadows and saturated darks |
| `darken`, `lighten` | keep the darker / the lighter of the two, channel by channel |
| `difference`, `exclusion` | the distance between the two colours (`exclusion` is softer): inversions, "film negative" looks |
| `hue`, `saturation`, `color`, `luminosity` | put only the hue, the saturation, the colour (hue + saturation) or the brightness of the layer onto the backdrop |

Rules:

1. **The order of layers decides what is blended.** Put the backdrop first (earlier in the array) and the blended layer after it.
2. **Names are CSS names, with the hyphen** (`soft-light`, not `softLight` / `soft_light`; a slip like that warns with the name you meant).
3. **Colours are mixed as the sRGB values you see** (as CSS does), not in linear light.
4. **`alpha` fades the blended result** (as CSS `opacity` does).
5. **On a composition the mode is inherited by its children, each blending with what is behind it** (not as one picture). To blend a composition as a whole, give it `threeD: true` (at `z: 0` with the default camera nothing else changes) or a filter.
6. **The 14 new modes are heavier** (each is a full-frame pass; about 1.5–2 ms a layer on WebGL at 1080p in the author's measurement, much less on WebGPU). 10 or more on screen at once warns (a composition with one counts each layer inside it, since its children blend one by one; one without counts the most that its own layers add at one time); a glow or a haze should be one layer (a gradient), not a pile.
7. **Together with `filters`, `threeD` and depth of field they all work** (the blend is applied after the layer's own filters, and after the depth-of-field blur).
8. **Some modes only act on some tones.** `overlay` and `soft-light` change almost nothing over a near-black or a near-white backdrop (their formulas leave 0 and 1 where they are), so a colour cast needs a **mid-tone** picture under it; `color-dodge` over a dark backdrop gives a saturated colour (each channel is lifted separately), over a bright one it burns out to white; `multiply` can only darken and `screen` / `add` only brighten.
9. **`blendMode` is a setting of the layer, not an animatable property** (`initial` or a keyframe with it warns). To change the mode for a moment, put a second, short-lived layer (`at` / `duration`) on top, or fade a layer's `alpha`.
10. **With `mask`:** every mask works with every mode: the layer is cut by the mask first, then blended. A plain shape mask (not inverted) is a stencil as before; a text, image or video mask, an inverted mask and a named matte go through the matte filter (see [Named mattes and luma](#named-mattes-and-luma)), and the blend is applied after it.

Checked against the W3C formulas on WebGPU and WebGL: every pixel within 2/255 (measured worst: 0.5/255 at alpha 1, 1.5/255 at alpha 0.5; over opaque backdrops and over nothing, as inside a `threeD` composition: a half-transparent layer over a half-transparent backdrop can differ more, because Pixi lays the blended result over the backdrop once more); on the same machine a frame is the same picture however it was reached. Another GPU can differ by a step or two.

```ts
// A soft white glow that brightens whatever it overlaps
{ type: 'shape', shape: 'circle', radius: 120, blendMode: 'add',
  fillGradient: { type: 'radial', stops: [[0, 'rgba(255,255,255,0.9)'], [1, 'rgba(255,255,255,0)']] },
  initial: { x: 'W/2', y: 'H/2' } }

// A colour cast over everything below it: orange at the top, blue at the bottom
{ type: 'shape', shape: 'rect', width: 'GW', height: 'GH', anchorX: 0, anchorY: 0, blendMode: 'soft-light',
  fillGradient: { stops: [[0, '#ff9a3c'], [1, '#3c5bff']] } }

// A light leak: a strong source that burns out toward white where it meets the picture
{ type: 'shape', shape: 'circle', radius: 380, blendMode: 'color-dodge',
  fillGradient: { type: 'radial', stops: [[0, 'rgba(255,120,30,0.9)'], [1, 'rgba(255,120,30,0)']] },
  initial: { x: 1000, y: 160 } }
```

---

## Assets

Pass a flat list of named assets to `Movie.init({ assets })`. Sequences refer to them by `name`.

```ts
await movie.init({
  assets: [
    { name: 'logo',  src: '/img/logo.png' },
    { name: 'bgm',   src: '/audio/bgm.mp3' },
    { name: 'green', src: '/video/green.mp4' },
  ],
  composition: { /* sequences reference 'logo', 'bgm', 'green' */ },
});
```

Supported formats are whatever PixiJS Assets and the browser's audio/video decoders accept (typically PNG/JPG/WebP for images; MP3/AAC/Opus for audio; MP4/WebM for video).

---

## Keyframes

```ts
interface Keyframe {
  at?: number;       // start, in seconds from the start of THIS sequence; negative = back from the sequence's end (-0.5 = 0.5 s before it ends)
  duration?: number | 'auto'; // seconds (default 0 — instantaneous); 'auto' = the time a spring ease takes to settle
  ease?: string;     // Ease name (default 'none'), or a spring: 'spring(mass, stiffness, damping)', 'spring.gentle|snappy|bouncy|wobbly|slow'
  set?:  Props;      // jump to these values at `at`
  to?:   Props;      // animate from current to these values over `duration`
  from?: Props;      // animate from these values to current
  // `from` + `to` together is a 'fromTo' tween
}
```

**Relative values.** A number in `to`, `from` or `set` may be written `'+=36'` or `'-=36'`: it is measured from where the property stands when the keyframe starts (the way GSAP writes them), and the right side is an expression (`'-=GW*0.1'`). `from: { x: '-=36' }` starts 36 px to the left of where the layer is and arrives there (the usual slide-in); `to: { y: '+=40' }` moves 40 px further. Several keyframes one after another stack, whatever order you seek in; with `repeat` the same move plays again from the same start (it does not stack). A relative value in `initial`, a style, or the start side of a `from` + `to` keyframe has nothing to be measured from: it warns and is read as the number.

The four kinds are mutually exclusive per keyframe:

- **`set`** — instantaneous property assignment at `at`.
- **`to`** — tween from whatever the property is at `at` to the given values, over `duration`.
- **`from`** — tween from the given values back to the current property, over `duration`.
- **`from` + `to`** — full fromTo tween, with explicit start and end values.

### Time: `speed` and `time`

Video, audio-file and composition layers have a clock of their own. **`speed`** is a fixed multiplier on the layer (`1` as it is, `2` twice as fast, `0.5` slow motion, negative backward; it starts at |speed| × `duration`, so `speed: -1` plays the first `duration` seconds in reverse; with no `duration` a video or audio file lasts its length ÷ |speed|). **`time`** is the same clock as an ordinary animatable property, in seconds of the layer's own content (a file's position, a composition's local playhead), in `initial` and `keyframes`, with every keyframe word (`at`, `duration`, `ease`, `repeat`, `yoyo`, `from`, `to`, `set`):

```js
// a freeze (the same value twice), then a ramp
keyframes: [
  { at: 0,   from: { time: 0 }, to: { time: 2 }, duration: 1 },        // plays 2 s of the file in 1 s
  { at: 1,   to: { time: 2 },   duration: 0.5 },                       // holds
  { at: 1.5, to: { time: 6 },   duration: 3, ease: 'power2.inOut' },   // then accelerates
]
```

A negative `time` counts back from the end of the content (`initial: { time: -2 }`, two seconds before the end). `speed` is not animatable (animate `time`); `speed` and keyframed `time` together: `time` wins. **Inside a composition with its own time the children are in that composition's local seconds** (with `speed: 2` the content is twice as long as `duration`, so children default to that length; with `speed: 0.5` a child at `at: 3` of a 4 s composition is never reached, and warns). The composition's own `at`, `duration`, `x` / `alpha` keyframes are outer time. The sound follows (pitch too); a sound inside a composition goes silent while its clock stands still, and an `sfx` longer than the clock's reach is reported ("its composition's clock only reaches …"). The content is as long as the larger of `duration` and the farthest `time` the clock reaches; a child whose life ends exactly where a held `time` stands is hidden during the hold (give it a longer `duration`).

### Springs

The ease `'spring(mass, stiffness, damping)'` (defaults 1, 100, 10) or a preset (`spring.gentle`, `spring.snappy`, `spring.bouncy`, `spring.wobbly`, `spring.slow`) moves a value as a damped spring would: it overshoots its target and rings, then rests. `duration: 'auto'` gives the keyframe the time the spring needs to settle (within 0.5 %), so mass and stiffness are real physics; with a number, `duration` is that settle time and only the damping ratio `damping / (2 √(stiffness × mass))` shapes the motion (below 1 it overshoots, 1 or more it does not: `spring(1, 170, 26)` does not bounce, `spring(1, 170, 12)` does).

```ts
{ at: 0.2, from: { y: -200 }, to: { y: 0 }, duration: 'auto', ease: 'spring.bouncy' }
{ at: 0,   to: { scale: 1 },  duration: 0.8,    ease: 'spring(1, 170, 12)' }
```

| Preset | Settles in | Highest value (target = 1) |
|---|---|---|
| `spring.snappy` | 0.42 s | 1.01 |
| `spring.gentle` | 0.72 s | 1.02 |
| `spring.bouncy` | 1.08 s | 1.28 |
| `spring.slow` | 1.29 s | 1.00 (no overshoot) |
| `spring.wobbly` | 1.61 s | 1.40 |

A colour is clamped in its colour space when it overshoots, and `alpha` past 1 is not visible. `'auto'` is for keyframes: `animateText` / `orbit` tweens take a spring name but a number `duration`. A malformed spring (`spring(1, 170`, `spring.floppy`) is reported once, with what is wrong.

### Repeating

`repeat` (extra plays, a finite whole number), `yoyo` (every other play runs backwards) and `repeatDelay` (seconds between plays) work on every kind of animation — position, alpha, colour, shape geometry, filters, text `fill`/`value`:

```ts
{ at: 0, to: { scale: 1.15 }, duration: 0.5, ease: 'sine.inOut', repeat: 5, yoyo: true }   // a heartbeat: 6 plays, 6 s total
```

Total time = `duration × (repeat + 1)` (+ delays). Endless repeats are not allowed (the timeline needs a fixed length); `repeat: -1` / `Infinity` is ignored with a warning — repeat as many times as the layer lasts.

### Negative `at`

If `at < 0`, it's interpreted as `duration + at` — measured back from the end of **the sequence the keyframe belongs to**. Useful for fade-outs:

```ts
{ type: 'text', text: 'bye', at: 2, duration: 3,
  keyframes: [{ at: -0.5, to: { alpha: 0 }, duration: 0.5 }] }   // fades during the last 500 ms of this text (global 4.5 s – 5 s)
```

### Easing

`'cubic-bezier(x1, y1, x2, y2)'` is the CSS curve exactly (x1 and x2 between 0 and 1, y1 and y2 may overshoot): `'cubic-bezier(.4, 0, .2, 1)'` is a gentle in-out, `'cubic-bezier(.2, .8, .2, 1)'` is front-loaded, not slow motion (half of the change in the first 13 % of the time, 99 % by 74 %, then a long settle). `power2` is a cubic: `power2.in` has done only 12.5 % at half time. A malformed one warns once and runs as `'none'`.

Ease strings (the names GSAP made familiar): `'none'`, `'linear'`, `'power1.in'` ... `'power4.inOut'`, `'sine.in/out/inOut'`, `'expo.in/out/inOut'`, `'circ.in/out/inOut'`, `'back.in/out/inOut(overshoot)'`, `'elastic.in/out/inOut(amplitude, period)'`, `'bounce.in/out/inOut'`. `'steps(n)'` is n equal steps.

### PIXI shorthands

These keys are shorthands the timeline understands when used in `initial` / `set` / `to` / `from` / `keyframes`:

```
scale, scaleX, scaleY
anchor, anchorX, anchorY
pivot, pivotX, pivotY
skew, skewX, skewY
position, positionX, positionY
tilePosition, tilePositionX, tilePositionY
tileScale, tileScaleX, tileScaleY
tint, autoAlpha
fillColor, fillAlpha                 (a shape's own colour keys)
```

(In addition to plain DisplayObject props like `x`, `y`, `rotation`, `alpha`, `width`, `height`, `visible`.) `blur`, `colorize` and the other colour-matrix shorthands of GSAP's PixiPlugin are gone: use a named filter and animate `filters.<name>.<prop>` (below). **Angles are in degrees**: `rotation`, `skew` / `skewX` / `skewY`, and `rotationX` / `rotationY` for 3D layers.

### Filter keyframe paths

Animate a named filter's parameter using a dot-path key:

```ts
import { BlurFilter } from 'pixi.js';

{
  type: 'video',
  asset: 'green',
  filters: [
    { name: 'k', type: 'chromaKey', keyColor: '#00ff00' },
    { name: 'b', type: 'custom', filter: new BlurFilter({ strength: 0 }) },
  ],
  keyframes: [
    { at: 2, to: { 'filters.b.strength': 8 }, duration: 1 },
    { at: 4, to: { 'filters.k.threshold': 0.5 }, duration: 1 },
  ],
}
```

The path is `filters.<filter-name>.<animatable-param>`. A filter must have a `name` to be addressable.

---

## Expressions

Any string `Props` value may be an arithmetic expression. Strings whose first character is a letter or digit are tried as expressions; verbatim strings (color hex, font names, etc.) are passed through when used in fields that don't expect a number.

The expression parser is in-tree (no eval, CSP-safe). See [`src/expr/Parser.ts`](../src/expr/Parser.ts).

### Operators and functions

| Form                    | Notes                                                |
| ----------------------- | ---------------------------------------------------- |
| `+ - * /`               | binary arithmetic                                    |
| `-x`, `+x`              | unary                                                |
| `( ... )`               | parens                                               |
| `1`, `1.5`, `.25`       | decimals                                             |
| `min(a, b)`, `max(a, b)`| variadic                                             |
| `abs(x)`                |                                                      |
| `floor(x)`, `ceil(x)`, `round(x)` |                                            |
| `sqrt(x)`               |                                                      |
| `pow(a, b)`             | power                                                |
| `sin(x)`, `cos(x)`, `tan(x)` | radians                                         |
| `lerp(a, b, t)`         | `a + (b - a) * t`                                    |
| `clamp(x, lo, hi)`      |                                                      |
| `smoothstep(a, b, x)`   | 0 below `a`, 1 above `b`, smooth in between          |
| `mod(a, b)`             | never negative (`mod(-1, 3)` is 2)                   |
| `step(edge, x)`         | 0 below `edge`, 1 from `edge` on: the way to write an "if" |
| `rand(seed)`            | a number in 0…1; the same seed always gives the same number |
| `noise(x, seed)`        | smooth noise in −1…1, continuous in `x`; `seed` is optional |
| `PI`                    | a constant                                           |

No comparison, conditional, bitwise, or string operators — keep it numeric (`step()` and `clamp()` cover most "if"s).

**Randomness is seeded.** `rand(seed)` and `noise(x, seed)` depend only on their arguments, so playback, seeking and export agree; never use `Math.random()` for anything that ends up in the picture. Expressions are still evaluated once, when the layer is built, so give each layer its own seed (in a JS loop: `x: `W/2 + rand(${i}) * 200``). For randomness in plain JS use `random(seed)` (`const r = random(7); r(); r()`), exported by the library. For a shake that changes over time use [`wiggle()`](#wiggle).

### Scope variables

(Your own names, set from outside, are [Variables](#variables) below.)

Each sequence has its own scope, computed at build time:

| Name      | Meaning                                                                               |
| --------- | ------------------------------------------------------------------------------------- |
| `w`       | sequence intrinsic width (e.g. video natural width). 0 if not applicable.             |
| `h`       | sequence intrinsic height.                                                            |
| `W`       | parent composition width (or root if no parent).                                      |
| `H`       | parent composition height.                                                            |
| `GW`      | global (root) composition width.                                                      |
| `GH`      | global (root) composition height.                                                     |
| `contain` | scale factor that makes the sequence fit inside the parent (preserve aspect, no crop) |
| `cover`   | scale factor that makes the sequence cover the parent (preserve aspect, may crop)     |
| `t`       | sequence start time (the `at` after negative-`at` resolution), seconds                |
| `d`       | sequence duration, seconds                                                            |
| `T`       | parent (or root) duration, seconds                                                    |

### Examples

```ts
// Center an image
initial: { x: 'GW/2 - w/2', y: 'GH/2 - h/2' }

// Fit a video without cropping
initial: { x: 0, y: 0, scale: 'contain' }

// Fill a video, may crop
initial: { x: 0, y: 0, scale: 'cover' }

// Responsive font size
style: { fontSize: 'min(GW, GH) * 0.06' }

// Subtitle 4% above bottom
initial: { x: 'GW/2', y: 'GH * 0.96', anchorX: 0.5, anchorY: 1 }
```

### Variables

A **variable** is a name with a value you can change after the movie is built: the language of a title, a brand colour, an offset, the screen size. Declare them once in `movie.init`; the composition reads them by name.

```ts
await movie.init({
  vars: { title: 'NORD', accent: '#e5399a', shift: 0 },           // a number or a string; no booleans (write 0 / 1)
  composition: { sequences: [
    { type: 'shape', shape: 'rect', width: 'GW', height: 'GH', initial: { x: 'GW/2', y: 'GH/2', fillColor: '{accent}' } },
    { type: 'text', text: '{title}', initial: { x: 'W/2 + shift', y: 'H/2' } },
  ] },
});
await movie.setVars({ title: 'SÜD', shift: 40 });                 // builds the composition again, at the same frame
```

| Where | How it reads a variable |
| --- | --- |
| a numeric expression (`x`, `scale`, `width`, `fontSize` … any value that takes an [expression](#expressions)) | the **name**, like `W` or `GW`: `'W/2 + shift'`. Only number variables. |
| any string anywhere in the composition (`text`, a colour, `asset`, a layer `name`, nested layers) | **`{name}`**: `'{title}'`, `'#{hex}'`, `'{lang}-logo'`. The text is replaced before the layer is built. A `{name}` that was not declared stays as written (`{value}` is the [counter](#counters-value) of a text layer, so it is also a name no variable can take). `$` is not used: it is a price (`'$5'`). |

Rules, all checked when the movie is built (each warning says what to change):
- A name is letters, digits and `_`, not starting with a digit. These are **reserved** and are refused: `w h W H GW GH t d T contain cover value`, every expression function (`min max abs … step rand noise lerp clamp smoothstep mod`) and `PI`.
- A variable that nothing reads (no `{name}` in a string, no use in an expression) is said: it is usually a typo on one side. A `{name}` that was not declared says the declared name it looks like.
- Values are read **when the composition is built**, once (not every frame). `at` and `duration` are plain numbers, so a variable moves values, not timing; to change the structure in time, call `movie.rebuild({ composition })` with a composition made by your own function.
- `setVars` of a name that was not declared is ignored with a did-you-mean; `setVars` of the values it already has does nothing.
- Everything is built again, the playhead stays at the same frame, a playing movie keeps playing, and the sound is mixed again **only if** the sound changed. See [`movie.rebuild`](api.md#movie-variables-and-rebuilding-vars-setvars-resize-rebuild).
- A video file is a function of the script **and** the variables: `pixi-effects render page.html --var title=SÜD --var shift=40`, `check --size 1920x1080,1080x1920` (a contact sheet per size).
- Layout that should follow the screen size uses `W` / `H` / `GW` / `GH`, not pixels: after `movie.resize(w, h)` they are the new size.

---

## Stops (presentations)

`composition.stops` says where a presentation pauses: seconds, or `{ at, page?, notes?, advance?, pdf? }` (see [Presentations in the API reference](api.md#presentations-stops-and-pixi-effectspresent)). A stop with `page` begins a page (a name, or `true`), the others are steps of it; with no `page` anywhere each stop is a page. `movie.play()` ignores them; the `Controller` shows marks on the seek bar and its play button plays to the next stop (`pauseAtStops: false` plays through), and `next(movie)` and `Presenter` (both from `pixi-effects/present`) pause on them. **`pdf: true` / `pdf: false`** on a stop chooses which moment stands for a page in a PDF: `true` = this stop is the page's picture, `false` = never use it (default: the page's last stop). Use it when the last stop is mid-exit. [`deck()`](#deck) builds the whole thing from pages.

## Transitions

A composition can declare scene-to-scene `transitions` that compress paired keyframes into a single line and add visual effects (mask wipes, iris reveals) that aren't expressible at the keyframe level.

```ts
{
  sequences: [
    { type: 'video', name: 'A', asset: 'a', at: 0, duration: 5 },
    { type: 'video', name: 'B', asset: 'b', at: 4, duration: 5 },
  ],
  transitions: [
    { kind: 'crossfade', from: 'A', to: 'B', at: 4, duration: 1, ease: 'sine.inOut' },
  ],
}
```

Common fields (`TransitionCommon`):

| Field      | Type    | Notes                                                                                  |
| ---------- | ------- | -------------------------------------------------------------------------------------- |
| `from`     | string  | sibling sequence's `name`. Must exist in the same composition.                         |
| `to`       | string  | sibling sequence's `name`. Must be declared **after** `from` in `sequences[]`.         |
| `at`       | number  | start of the transition, in the **parent composition's** time (like a sequence's `at`, not sequence-local); negative = back from the parent's end. |
| `duration` | number  | seconds, must be > 0.                                                                  |
| `ease`     | string? | Ease name. Default `'none'` (linear).                                           |

Validation runs at composition build time. Errors throw with the offending `transitions[<index>]` quoted in the message: missing names, `to` before `from`, transition window outside either sequence's lifespan, duplicate use of one sequence as `from`, `from === to`, `duration <= 0`.

### `crossfade`

Alpha cross-dissolve. `from` fades to `alpha: 0`, `to` starts at `alpha: 0` and fades to `1`, both over `[at, at + duration]`.

```ts
{ kind: 'crossfade', from: 'A', to: 'B', at: 4, duration: 1, ease: 'sine.inOut' }
```

If `to` already has an explicit `initial.alpha` (other than 0), the expander throws — remove the manual setting.

### `wipe`

A directional reveal. `to` is masked by a soft edge that travels across the screen.

```ts
{
  kind: 'wipe', from: 'A', to: 'B', at: 4, duration: 1,
  direction: 'left' | 'right' | 'up' | 'down',
  smoothing: 0.04,    // 0..1 edge softness (default 0.02)
}
```

`direction` is the direction the wipe edge travels — `'left'` means the edge moves leftward across the canvas, exposing B starting from the right side. Mirror that for `'right'` / `'up'` / `'down'`.

### `iris`

A circular reveal centered on the canvas.

```ts
{
  kind: 'iris', from: 'A', to: 'B', at: 4, duration: 1,
  mode: 'in',         // default — B opens up from a point. 'out' = A closes down to a point.
  smoothing: 0.03,    // 0..1 edge softness (default 0.02)
}
```

`mode: 'in'` (default): B emerges from the center and grows outward.
`mode: 'out'`: A disappears from the outside in, exposing B.

### `slide`

Both sequences slide together; the new scene comes in from the opposite side.

```ts
{
  kind: 'slide', from: 'A', to: 'B', at: 4, duration: 1,
  direction: 'left' | 'right' | 'up' | 'down',
}
```

`direction` is the direction of motion. `'left'` means A slides off to the left and B enters from the right.

The slide macro reads each sequence's existing `initial.x` / `initial.y` (if any) and treats it as the natural resting position. `B` is shifted off-screen by ±W or ±H from that position and slides back to it; `A` slides from its position to off-screen on the opposite side. So a centered text with `initial: { x: 'GW/2', anchorX: 0.5 }` ends the slide centered, not at `x: 0`.

If you've manually keyframed `x` / `y` on `A` or `B`, the slide expansion appends new keyframes alongside — your existing motion is not overwritten. Behavior with conflicting motion is the user's responsibility.

### `dip`

"Dip through": A fades out across the first half of the window and B fades in across the second half. The visible color during the dip is whatever sits behind A and B — set `Movie.background` (or place a persistent layer beneath them) for dip-to-black / dip-to-white / dip-to-color.

```ts
{ kind: 'dip', from: 'A', to: 'B', at: 4, duration: 1, ease: 'sine.inOut' }
```

If `to` already has a non-zero `initial.alpha`, the expander throws — remove the manual setting.

### `zoom`

A scaled punch-in / punch-out. By default `B` opens up: it starts large and zooms back to scale 1 while fading in; `A` simply fades. With `mode: 'out'` it's the opposite — `A` zooms outward as it fades, and `B` fades in at scale 1.

```ts
{
  kind: 'zoom', from: 'A', to: 'B', at: 4, duration: 1,
  mode: 'in',          // default — B opens up. 'out' = A closes outward.
  fromScale: 4,        // starting scale of the zoomed sequence (default 4)
  ease: 'power2.out',
}
```

### `dissolve`

A noise reveal driven by deterministic 2D Perlin noise. Pixels with a low noise value reveal first; as `uProgress` advances, more pixels reveal. At the default `scale` of 30 it reads as large blotches (about 40 px each), not as grain: `scale: 200` or more gives a fine grain. The same `seed` always produces the same dissolve pattern, so a render is bit-exact reproducible.

```ts
{
  kind: 'dissolve', from: 'A', to: 'B', at: 4, duration: 1,
  scale: 30,         // pattern frequency (higher = finer grain). Default 30.
  seed: 0,           // pattern offset. Different seeds → different reveal patterns.
  smoothing: 0.05,   // edge softness within each chunk. Default 0.05.
}
```

### `luma`

A wipe that follows a **brightness map** (After Effects' Gradient Wipe): the dark parts of the map change first, the light parts last. `to` appears through a soft edge; `from` holds until `to` has covered it (a hard cutoff, as `wipe` and `iris` do).

```ts
{
  kind: 'luma', from: 'A', to: 'B', at: 4, duration: 1,
  map: 'radial',     // 'linear' (left to right, default), 'diagonal', 'radial' (from the middle, a circle on screen),
                     // or the name of a grayscale image asset (dark parts change first)
  softness: 0.1,     // width of the soft band, in brightness units (0..1). Default 0.1.
  flip: false,       // true = reverse the map (light parts first)
}
```

The three built-in maps need no image (they are computed on the GPU from the position on screen). A `map` name that is neither a built-in nor a loaded asset warns once (with the likely name) and wipes as if the map were white. The map covers the whole composition, so give it the composition's aspect ratio.

---

## Filters

> **`filterArea`** (on any layer) is a rectangle in the layer's **own** coordinates — origin = its local origin, e.g. a circle's centre — that widens the area a filter may draw into. Without it a blur or glow is clipped to the layer's bounding box: `filterArea: { x: -(r + 260), y: -(r + 260), width: 2 * (r + 260), height: 2 * (r + 260) }` for a circle of radius `r` blurred by up to 260 px. `threeD` layers add the filters' padding automatically.

Filters are named, ordered, and per-sequence. Animate parameters via `'filters.<name>.<param>'` keyframe paths.

### `chromaKey`

Removes a key color from the source. Works on video, image, or composition layers.

```ts
{
  name: 'k',
  type: 'chromaKey',
  keyColor?: string | [number, number, number],  // hex '#00ff00' or RGB 0..1; default green
  threshold?: number,        // default 0.4 — distance from key color counted as transparent
  smoothing?: number,        // default 0.1 — softness of the cutoff edge
  spill?: number,            // default 0.2 — green-tint suppression
}
```

Animatable: `threshold`, `smoothing`, `spill`. `keyColor` is set at build time.

### Named filters (`{ type: 'glow', … }`)

**Which ones to use.** A filter works on a layer's own pixels (a glow around the letters, an outline, a shadow), which a `shader` layer cannot do (it draws new content). The 38 named filters that come from `pixi-filters` are not equally trustworthy: `tests/tools/filterSweep.test.ts` draws these on WebGPU (the default backend) and on WebGL and requires that each one shows and looks the same: **`glow`, `outline`, `dropShadow`, `bevel`, `bloom`, `pixelate`, `crt`, `rgbSplit`, `dot`, `radialBlur`, `glitch`** (`grain`, `warp` and `blur` are this library's or PixiJS's own). Reach for these first. The others are not tested on both backends; measured differences: `multiColorReplace` draws the whole picture black on WebGPU (use `colorReplace`), `kawaseBlur` blurs far less on WebGPU (use `blur`), `advancedBloom` is sharper on WebGPU (use `bloom`), `ascii` shows stripes on WebGPU. A filter only shows along the edges of a layer's own picture: on a full-bleed opaque layer `glow` and `outline` have nothing to follow, so put them on the shapes and text. `radialBlur` did nothing on WebGPU before 0.34 (an upstream i32 / f32 mismatch, worked around).

A filter by name, as plain data. `type` is the filter's class name without `Filter`, in camelCase (case does not matter), and every other key is that filter's own option. No import, and the layer stays JSON:

```ts
{ type: 'text', text: 'NEON', style: { fontSize: 140, fill: '#fff' }, initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
  filters: [{ type: 'glow', name: 'halo', outerStrength: 0, color: '#ff4d9d', distance: 20 }],
  keyframes: [{ at: 0, to: { 'filters.halo.outerStrength': 6 }, duration: 1 }] }       // animate any scalar option by name
```

Name a filter (`name: 'halo'`) to animate it with `'filters.halo.<option>'`. `blur`, `noise`, `alpha`, `colorMatrix` and `grain` need no extra package (`grain` is this library's own). All the others come from the **`pixi-filters`** package, which is loaded the first time a layer uses one (add `"pixi-filters": "https://esm.sh/pixi-filters@6.1.5?external=pixi.js"` to the import map, or `npm i pixi-filters`; `skills/pixi-effects/template.html` already has it). A misspelt type says what you probably meant. Rendering and exporting were verified in a real browser for 40 of them (`tests/films/named-filters.html` and `named-filters-2.html`); `colorMap` and `simpleLightmap` need a texture, which JSON cannot hold, so use `custom` for those two:

| `type` | Options (the useful ones) | What it does |
|---|---|---|
| `blur` | `strength`, `quality` | Gaussian blur (pixi.js) |
| `noise` | `noise` (0–1), `seed` | Uniform noise (pixi.js): one frozen pattern (the seed is random unless you give it), the same strength at every tone, it lifts blacks. For film grain use `grain` |
| `grain` | `amount` (0.08: the standard deviation at mid-grey, of full scale), `size` (px, 1.5), `seed` (0), `fps` (24: new grain this many times a second, 0 = still), `color` (0 = luminance only, 1 = per channel), `loop` (seconds after which the pattern starts again: give the movie's `duration` for a clip made to loop, so the grain has no jump at the seam; `loop × fps` must be a whole number of grain frames, e.g. 10 s at 24 fps, or it warns) | Film grain: seeded, new every 1/`fps` s, weighted to the mid-tones (it fades out toward black and white: blacks are not lifted, the mean brightness does not move), an integer hash so every GPU draws the same grain pattern (the 8-bit values agree to within 1/255). The grain is anchored to the filter's own frame: on a layer it moves with the layer, on the root it is fixed to the picture. On a layer or on the root `composition.filters`. A static pattern is `fps: 0`. Keyframe it by name: `'filters.g.amount'`. Grain eats video bitrate (see pitfall 119 in `skills/pixi-effects/reference/pitfalls.md`) |
| `alpha` | `alpha` | Whole-layer opacity (pixi.js) |
| `colorMatrix` | `preset`: `'sepia' 'grayscale' 'negative' 'polaroid' 'technicolor' 'vintage' 'kodachrome' 'browni'`, or `matrix` (20 numbers) | Colour grade (pixi.js) |
| `adjustment` | `gamma contrast saturation brightness red green blue alpha` (1 = unchanged) | Colour grading |
| `hslAdjustment` | `hue` (degrees) `saturation lightness colorize alpha` | Hue shift |
| `grayscale` | – | Black and white |
| `glow` | `distance outerStrength innerStrength color alpha quality knockout` | Glow around the shape |
| `dropShadow` | `offset: { x, y }` `blur alpha color shadowOnly` | Shadow |
| `outline` | `thickness color alpha quality knockout` | Stroke around the shape |
| `pixelate` | `size` (a number, or `[w, h]`); animate `sizeX` / `sizeY` | Mosaic |
| `crt` | `curvature lineWidth lineContrast noise vignetting vignettingAlpha time` | Old monitor |
| `rgbSplit` | `red green blue` (each `{ x, y }` offset) | Chromatic aberration |
| `oldFilm` | `sepia noise scratch scratchDensity vignetting seed` | Aged film |
| `glitch` | `slices offset direction seed average` | Digital glitch |
| `warp` | `kind: 'wave' \| 'haze'`, `strength` (max shift, px, 6), `scale` (wavelength or cell size, px, 80), `speed` (0.5), `angle` (degrees: the way a wave travels, 0), `seed` (`haze`) | Bends the picture: a travelling wave (flags, water) or drifting noise (heat haze). This library's own, time-driven |
| `bulgePinch` | `center radius strength` (`center`: 0–1 of the layer) | Bulge (+) / pinch (−) |
| `twist` | `radius angle offset: { x, y }` | Swirl |
| `zoomBlur` | `strength center innerRadius radius` | Radial zoom streaks |
| `kawaseBlur` | `strength quality` | Cheap, wide blur |
| `radialBlur` / `motionBlur` | `angle center radius` / `velocity kernelSize` | Spin / directional blur |
| `emboss` | `strength` | Relief |
| `ascii` | `size color replaceColor` | Text-art |
| `colorOverlay` | `color alpha` | Tint over everything |
| `advancedBloom` / `bloom` | `threshold bloomScale brightness blur` | Bloom |
| `bevel` | `thickness rotation lightColor lightAlpha shadowColor shadowAlpha` | Raised edge |
| `dot` / `crossHatch` | `scale angle grayscale` / – | Halftone / hatching |
| `godray` | `angle gain lacunarity alpha parallel time` | Light shafts (animate `time`) |
| `reflection` | `mirror boundary amplitude waveLength alpha time` (ranges are `[start, end]`) | Water reflection |
| `simplexNoise` | `strength scale offset` | Cloudy noise over the layer |
| `colorGradient` | `gradientType: 'linear' 'radial' 'conic'` (the filter's own option is `type`, which the DSL uses), `stops: [{ offset, color, alpha }]`, `angle` | A gradient laid over the layer |
| `colorReplace` / `multiColorReplace` | `originalColor targetColor tolerance` / `replacements: [[from, to], …] tolerance` | Swap colours |
| `convolution` | `matrix` (9 numbers), `width height` | Sharpen, edge detect |
| `tiltShift` / `tiltShiftAxis` | `blur gradientBlur start end` (canvas pixels) | Miniature blur |
| `shockwave` | `center amplitude wavelength brightness speed radius time` (animate `time` 0 → 1) | A ripple from a point |
| `backdropBlur` | `strength` | Blurs what is BEHIND the layer, so alone it shows nothing |
| the rest of pixi-filters (`colorMap`, `simpleLightmap`) | need a texture: `{ type: 'custom' }` | see the [pixi-filters docs](https://pixijs.io/filters/docs/) |

Gotchas, all measured:

- **Distortion:** `warp` (`wave`: a flag or the surface of water, `haze`: heat shimmer; moves with the frame's time, no keyframes needed, and pads the layer by `strength` so a shifted edge is not cut), `twist` (a swirl), `bulgePinch` (a lens), `shockwave` (a ring that spreads), `rgbSplit` (colour fringes), `glitch` (slices). `warp`'s time is the time of the frame (inside a time-remapped composition, that composition's clock), `speed: 0` stands still, `strength` is in px and is capped at 200. It bends the layer's picture; to draw something that does not exist yet, use a `shader` layer.
- **`bulgePinch.center` is a fraction of the filtered layer, not pixels** (measured): `{ x: 0.5, y: 0.5 }` is the layer's middle and `{ x: 0.7, y: 0.7 }` is a bit down and to the right of it, and it can be animated (`filters.bp.center.x`, 0 to 1). A pixel value such as `{ x: 900, y: 500 }` puts the bulge far outside the layer and nothing shows (it warns).
- **The other centres and offsets are in canvas pixels, not the layer's:** `twist.offset`, `zoomBlur.center`, `radialBlur.center`, `shockwave.center` default to the canvas's top-left corner, so a layer in the middle looks unaffected. Put the centre on the layer: `{ type: 'twist', offset: { x: 640, y: 360 } }` for a layer centred on a 1280×720 canvas.
- **A filter works inside the layer's bounds.** Glow, dropShadow, outline and blur draw outside it and are clipped unless you widen the area (`filterArea: { x: -24, y: -24, width: w + 48, height: h + 48 }`, in the layer's own coordinates). Do not widen it for `grayscale`, `oldFilm` or other filters that paint the whole area: they fill the extra margin with black.
- **Animate scalars by name** (`'filters.halo.outerStrength'`). Options that are points (`rgbSplit.red`, `dropShadow.offset`) are animated one leaf at a time: `'filters.<name>.red.x'` / `'filters.<name>.red.y'` tween like any number (the whole point `red: { x, y }` as a keyframe value switches at its keyframe and does not tween; a path that leads nowhere is warned about once and ignored). `pixelate` animates through `sizeX` / `sizeY`, not `size`.
- `shockwave` and `godray` are driven by `time` (a still frame at `time: 0` looks like nothing): animate it. `radialBlur`, `shockwave` and `tiltShift` positions are canvas pixels too.
- Some filters take their value as one argument; the DSL hides that (`{ type: 'pixelate', size: 8 }`, `{ type: 'emboss', strength: 6 }`).

### `custom`

Escape hatch for any PIXI `Filter` instance — including PIXI's own built-ins (`BlurFilter`, `ColorMatrixFilter`, `NoiseFilter`, etc.), [pixi-filters](https://github.com/pixijs/filters), community packages, or your own `Filter` subclass. The instance is used as-is; animation works the same way as for `chromaKey` as long as the filter has writable scalar properties at the addressed paths.

```ts
import { BlurFilter } from 'pixi.js';
import { GlowFilter, OldFilmFilter } from 'pixi-filters';

{
  type: 'image',
  asset: 'photo',
  filters: [
    { type: 'custom', name: 'b',    filter: new BlurFilter({ strength: 0 }) },
    { type: 'custom', name: 'glow', filter: new GlowFilter({ outerStrength: 1, color: 0xffaa00 }) },
    { type: 'custom', name: 'film', filter: new OldFilmFilter() },
  ],
  keyframes: [
    { at: 1,    to: { 'filters.b.strength': 8 },          duration: 0.5 },
    { at: 2,    to: { 'filters.glow.outerStrength': 4 },  duration: 1 },
    { at: -0.5, to: { 'filters.film.noise': 0 },          duration: 0.5 },
  ],
}
```

Notes:

- `filter` must be a `Filter` instance (constructor must have run on the consumer side).
- A dotted key (`'filters.s.red.x'`) is a path into the filter: the leaf of the point is written in place, which `pixi-filters` reads when it draws (checked on `RGBSplitFilter` in a real browser, `tests/tools/pointOptions.test.ts`). Before 0.32 such a key was written as a property literally named `red.x` and nothing moved.
- Without a `name`, the filter still applies but cannot be addressed via `filters.<name>.<prop>` keyframe paths.

Notes:

- `filter` must be a PIXI `Filter` instance (constructor must have run on the consumer side). Plain object literals throw.
- Use `custom` for a filter that has no name above (a community filter, or your own `Filter`). For everything in pixi.js and `pixi-filters`, prefer the named form.
- Without a `name`, the filter still applies but cannot be addressed via `filters.<name>.<prop>` keyframe paths.

---

## Presets

Presets are pure helpers that return a ready-to-use `SequenceSpec`. They expand into the existing keyframe / initial primitives — no engine surgery — so anything you can do with a preset you can also write by hand.

### `kenBurns`

Per-image motion preset for slideshows. Returns an `ImageSequenceSpec`; drop the result straight into `sequences[]`. Pair with `crossfade` / `dip` etc. transitions for the cuts between images — `kenBurns` itself emits no fade.

```ts
import { kenBurns } from 'pixi-effects';

sequences: [
  kenBurns({ asset: 'photo1', name: 'p1', at: 0,  duration: 6, motion: 'scale',    origin: [0.25, 0.25], zoom: 1.2 }),
  kenBurns({ asset: 'photo2', name: 'p2', at: 5,  duration: 6, motion: 'rotation', angle: 6 }),
  kenBurns({ asset: 'photo3', name: 'p3', at: 10, duration: 6, motion: 'position', from: [0, 0], to: [1, 1] }),
  kenBurns({ asset: 'photo4', name: 'p4', at: 15, duration: 6, motion: 'still' }),
],
```

The image is centred on the canvas; `fit` (default `'cover'`) controls how the texture is scaled to fill. The fitted scale is computed at runtime from the texture's intrinsic size, so you don't pass `imageWidth` / `imageHeight`.

#### Common fields

| Field      | Type                  | Notes                                                                                |
| ---------- | --------------------- | ------------------------------------------------------------------------------------ |
| `asset`    | string                | image asset name (registered via `Movie.init({ assets })`)                           |
| `duration` | number                | seconds of animation (required)                                                      |
| `name?`    | string                | sequence name so transitions can reference it                                        |
| `at?`      | number                | start time, parent-relative seconds                                                  |
| `fit?`     | `'cover'` \| `'contain'` | how the texture fills the canvas. Default `'cover'`.                              |
| `ease?`    | string                | Ease name. Default `'sine.inOut'`.                                            |

#### `motion: 'still'`

Image sits at the canvas centre, fitted but unanimated. Useful as a stable "rest" in between motion-heavy frames.

#### `motion: 'scale'`

Zoom in or out around an arbitrary 9-point pivot.

| Field        | Type                       | Notes                                                                                       |
| ------------ | -------------------------- | ------------------------------------------------------------------------------------------- |
| `origin?`    | `[number, number]`         | pivot in [0..1] image coords. Default `[0.5, 0.5]` (centre). The original convention uses the 9-point grid `0.25 / 0.5 / 0.75`. |
| `zoom?`      | number                     | zoom factor relative to the fitted base. Default `1.15`.                                    |
| `direction?` | `'in'` \| `'out'`          | `'in'`: 1 → zoom (default). `'out'`: zoom → 1.                                              |

The pivot point stays pinned at its world position; the rest of the image grows / shrinks around it. This is the "focal-point" zoom you want for ken-burns slideshows — the eye anchors on the pivot while the surrounding pixels move.

#### `motion: 'rotation'`

Gentle rotation while keeping the image filling the canvas.

| Field        | Type                                | Notes                                                                                       |
| ------------ | ----------------------------------- | ------------------------------------------------------------------------------------------- |
| `angle?`     | number                              | total rotation in degrees. Default `8`. Capped at 30.                                       |
| `direction?` | `'cw'` \| `'ccw'` \| `'through'`    | `'cw'` (default) = 0 → +angle. `'ccw'` = 0 → −angle. `'through'` = −angle/2 → +angle/2.     |

The scale is over-set so the rotated bounding box still covers the canvas — no background gaps as the image tilts.

#### `motion: 'position'`

Pan the image between two points within its over-scaled bounds.

| Field   | Type                | Notes                                                                                  |
| ------- | ------------------- | -------------------------------------------------------------------------------------- |
| `from?` | `[number, number]`  | start position in [0..1] of the over-scaled bounds. Default `[0.25, 0.25]`.            |
| `to?`   | `[number, number]`  | end position. Default `[0.75, 0.75]`.                                                  |
| `zoom?` | number              | over-scale factor (must be > 1 for any pan to be visible). Default `1.15`.             |

`[0, 0]` looks at the top-left of the image; `[1, 1]` looks at the bottom-right. The default pans diagonally across the upper-left and lower-right quarters of the over-scaled image (matches the Yajima-Motion preset).

### `orbit`

A camera that circles a point. There is no per-frame expression in the DSL, so the circle is sampled into short linear keyframes (one per 0.1 s; the easing is applied to the angle). Returns a `camera` layer for `sequences[]`.

```ts
import { orbit } from 'pixi-effects';

sequences: [
  orbit({ duration: 6, degrees: 40 }),                                   // ±20° around the centre of a 1280×720 canvas
  // …threeD layers…
]
```

| Option | Notes |
|---|---|
| `duration`, `degrees` | required. `degrees` is the total sweep (negative = the other way) |
| `start` | start angle in degrees; default `-degrees / 2` (0 = straight in front of the centre) |
| `radius` | distance from the centre; default = the default camera distance for `height` and `fov`, so `z = 0` is 1:1 at angle 0 |
| `center` | `[x, y]` to circle and look at; default the canvas centre |
| `width`, `height` | canvas size for the defaults (1280 × 720) |
| `fov`, `ease`, `at`, `name`, `stepsPerSecond` | `ease` default `'sine.inOut'` |

`z` is specified, so it stops following `fov`; for an orbit **plus** a dolly zoom write your own `fov` and `z = (H/2) / tan(fov/2)` keyframes.

### `wiggle`

A seeded shake as keyframes (an expression cannot change over time, so it is baked into ordinary keyframes): drift, hand-held camera, a flickering light.

```ts
import { wiggle } from 'pixi-effects';

{ type: 'text', text: 'hi', at: 0, duration: 6, initial: { x: 'GW/2', y: 'GH/2' },
  keyframes: [
    ...wiggle({ duration: 6, freq: 4, seed: 3, props: { x: { around: 'GW/2', amp: 6 }, rotation: { around: 0, amp: 1.5 } } }),
  ] }
```

| Option | Type | Notes |
| ------ | ---- | ----- |
| `duration` | number | seconds; required |
| `props` | `{ [prop]: { around, amp } }` | each property moves on its own (x and y are not in lockstep). `around` is the resting value: a number or an expression; the shake starts and ends there. `amp` is how far it strays. Any animatable name works (`rotation`, `scale`, `alpha`, `'filters.blur.blur'`). |
| `at` | number | start, seconds from the start of the layer (default 0) |
| `freq` | number | new random targets per second (default 3 drifts; 8 and up shakes) |
| `seed` | number | another seed is another take (default 0) |
| `ease` | string | between targets (default `'sine.inOut'`; `'none'` gives jittery straight lines) |

It returns `Keyframe[]`: spread it into `keyframes`, next to others. Do not put another keyframe on the same property during the wiggle.

### `particles`

Particles as plain layers: a burst, a fountain, snow, confetti, sparks. Each particle is a layer with its own **seeded** start, launch angle and speed, size, colour and life, and a path baked into keyframes, so playback, seeking and export agree; it exists only while it is alive. Spread the result into `sequences`.

```ts
import { particles } from 'pixi-effects';

...particles({ count: 240, at: 2, life: [1.2, 2], area: { x: 640, y: 330 }, speed: [40, 520], gravity: 220, drag: 1.1,
               size: [4, 8], scale: [1, 0.3], colors: ['#ffd166', '#ff6b9d', '#4cc9f0'], fade: { out: 0.7 }, blendMode: 'add' })   // a burst of sparks
```

| Option | Notes |
| ------ | ----- |
| `count`, `life` | required: how many, and how long each lives (a number or `[min, max]` seconds) |
| `area` | required: `{ x, y }` is the centre they start from; add `width` / `height` to spread over a box (snow: `{ x: 640, y: -20, width: 1400 }`) |
| `at`, `emit` | the first birth, and the seconds over which births are spread (`0`, the default, is a burst) |
| `angle`, `speed` | launch direction (degrees: 0 right, 90 down, −90 up; default `[0, 360]`) and speed (px/s; default `[100, 300]`) |
| `gravity`, `wind`, `drag` | accelerations (px/s², down and sideways) and air drag per second |
| `sway` | `{ amp, freq }`: a smooth side-to-side wobble (snow, leaves, embers) |
| `size`, `scale`, `fade` | radius (default `[3, 6]`), scale over the life (`[1, 0]` shrinks away), alpha ramps `{ in, out }` in seconds |
| `colors`, `shape` | fill colours picked per particle; `'circle'` (default), `'rect'` (square) or `'star'` |
| `spin` | degrees per second (they also start at a random angle) |
| `blendMode` | `'add'` makes overlaps glow |
| `template` | any layer (an image, a text) used for every particle instead of a shape; its keyframes are kept |
| `seed`, `name` | another seed is another burst; layers are named `<name>-0`, `<name>-1`, … |
| `sampleRate` | samples per second of a curved path (default 20); a path with no gravity, wind, drag or sway is one straight tween |

It throws, with the fix, when it would bake an absurd number of keyframes: lower `count`, `life` or `sampleRate`. Particles are real layers (names like `burst1-0`), so `inspect` and the timeline list them, grouped as one family.

### `cameraPath`

A camera flight as keyframes for `x`, `y`, `z`, `lookAtX`, `lookAtY` and `lookAtZ`: a route through `[x, y, z]` points, walked by arc length (an even speed whatever the curve) and sampled once per frame.

```ts
import { cameraPath, wiggle } from 'pixi-effects';

{ type: 'camera', keyframes: [
  ...cameraPath({ points: [[640, 360, 2200], [690, 330, 900], [640, 360, -3000]], duration: 7, ease: 'power2.in', frameRate: 30 }),
  ...wiggle({ duration: 7, freq: 9, props: { offsetX: { around: 0, amp: 5 }, offsetY: { around: 0, amp: 3 } } }),      // a handheld shake on the offsets
] }
```

| Option | Notes |
| ------ | ----- |
| `points` | `[[x, y, z], …]`, at least two, the route in order |
| `duration` | seconds; required |
| `at` | start, seconds from the start of the camera layer (default 0) |
| `ease` | Ease for the progress along the route (default `'none'`: constant speed; `'power2.in'` an accelerating rush) |
| `look` | `'ahead'` (default: face where it flies) or a fixed `[x, y, z]` |
| `lookAhead` | with `'ahead'`: how far ahead, as a fraction 0–1 of the route (default 0.08); past the end it continues along the last direction |
| `smooth` | `true` (default): a smooth curve through the points (Catmull-Rom); `false`: straight lines |
| `from` / `to` | fractions 0–1 of the route to start and stop at (default 0 → 1; `from: 1, to: 0` flies it backwards) |
| `frameRate` | samples per second: your movie's `frameRate` (default 30) |

Layers the camera passes take `hideBehindCamera: true`. The recipe `camera-fly-through` in `skills/pixi-effects/reference/recipes.md` is a whole corridor.

### `followPath`

A layer travelling along an SVG path, as keyframes for `x` and `y` (and `rotation`). The layer's own `x` / `y` are the points of the path (give shapes their centre there, and text `anchorX: 0.5, anchorY: 0.5`). The path is walked by arc length, so the speed is even whatever the curve, and sampled once per frame as short straight steps: set `frameRate` to the movie's and the layer is exactly on the path at every frame.

```ts
import { followPath } from 'pixi-effects';

{ type: 'shape', shape: 'polygon', points: [[-18, -12], [18, 0], [-18, 12]], at: 0.5, duration: 4,
  initial: { fillColor: '#ffd166' },
  keyframes: followPath({ d: 'M 120 560 C 360 120 920 120 1160 560', duration: 4, ease: 'power2.inOut', orient: true, frameRate: 30 }) }
```

| Option | Notes |
| ------ | ----- |
| `d` | the route: SVG path data in canvas coordinates; several sub-paths are walked in order; a closed one comes back to its start |
| `duration` | seconds; required |
| `at` | start, seconds from the start of the layer (default 0): give the layer its own `at` so it is not drawn at the origin before the trip |
| `ease` | Ease for the progress along the path (default `'none'`: constant speed) |
| `from` / `to` | fractions 0–1 of the path to start and stop at (default 0 → 1; `from: 1, to: 0` goes backwards) |
| `orient` / `rotate` | `orient: true` also keyframes `rotation` (degrees) to face the way it is going, without ever jumping by a turn; `rotate` adds an offset (`-90` for an image that points up) |
| `frameRate` | samples per second (default 30) |

It returns `Keyframe[]`: spread it next to other keyframes, but not another `x`, `y` or `rotation` during the trip.

### `react`

Keyframes that follow a sound: `base + amount × level`, sampled once per frame from an envelope. Analyse the sound first (`await audioEnvelope(url)`, or `bpmEnvelope(bpm, { duration })` with no file), then:

```ts
import { audioEnvelope, react } from 'pixi-effects';

const env = await audioEnvelope('music.mp3', { frameRate: 30 });
{ type: 'shape', shape: 'circle', radius: 120, initial: { x: 640, y: 360 },
  keyframes: react(env, { duration: 12, props: {
    scale: { base: 1, amount: 0.4, band: 'bass', attack: 0.02, release: 0.2 },     // swells with the low end, falls back slowly
    alpha: { base: 0.5, amount: 0.5, beats: true, decay: 0.15 },                    // flashes on every beat
  } }) }
```

See [the API reference](api.md#audio-reactive-audioenvelope-react-bpmenvelope) for the options. A bar equaliser is one layer per band with `height: { base: 6, amount: 220, band: 'b7' }`.

### `deck`

A deck of pages as one movie, for a `Presenter` (`import { deck, Presenter } from 'pixi-effects/present'`). Each page is a nested composition laid out after the one before (so its layers are written in the page's own time), the stops come from the pages, and an optional `transition` joins them with the existing transitions.

```ts
import { deck } from 'pixi-effects/present';

await movie.init({ canvas, width: 1280, height: 720, frameRate: 30, ...deck({
  transition: { kind: 'slide', direction: 'left', duration: 0.6, ease: 'power3.inOut' },
  pages: [
    { name: 'Hello', duration: 3.2, stops: [2.6], sequences: [ /* the title, at: 0 = the start of the page */ ] },
    { name: 'Why',   duration: 5.2, stops: [1.5, 3.0, 4.6], sequences: [ /* three bullets, each starting at the previous stop */ ] },
  ],
}) });
```

| Option | Notes |
| ------ | ----- |
| `pages[]` | required: `{ name?, duration, sequences, stops?, notes?, advance?, initial?, keyframes?, filters?, … }` |
| `page.duration` | seconds; **a page should last its last stop plus the transition** (after the last stop the next press plays the rest of the page and the slide) |
| `page.stops` | page-local times, or `{ at, pdf? }`: the first is the page settled, the others are steps (a bullet, a growing chart: **a step is a layer that starts at the previous stop and ends at this one**). Default: where the transition begins (the end for the last page) |
| `page.notes`, `page.advance` | notes stay on the page's first stop; `advance` (seconds) on its last |
| `transition` | `{ kind, duration, … }`: any [transition](#transitions) without `from` / `to` / `at`; the next page starts `duration` seconds early and the transition plays across the overlap. It must be shorter than every page |
| movie options | `width`, `height`, `frameRate`, `background`, `canvas`, `assets`, `poster`, `motionBlur`, `loader` pass through |

It returns `{ duration, composition: { sequences, transitions?, stops }, …your movie options }`, ready to spread into `movie.init`. The page layers are named `page-1`, `page-2`, …

### `stagger`

Delays for a wave of items, in the style of GSAP's `stagger`. Pure and seeded, so playback and export agree.

```ts
import { stagger } from 'pixi-effects';

const d = stagger(6, { each: 0.08 });                      // [0, 0.08, 0.16, 0.24, 0.32, 0.4]  -> `at: 1 + d[i]`
const letters = stagger(layers, { each: 0.05, from: 'center' });   // the same layers, `at` pushed back (the originals are not touched)
const ripple = stagger(18, { each: 0.12, grid: [6, 3], from: 'center', ease: 'sine.out' });
```

| Option | Notes |
| ------ | ----- |
| `each` | seconds between neighbours (the farthest one waits `each` × its distance). Default 0.1. Not together with `amount`. |
| `amount` | seconds from the first to the last, however many there are |
| `from` | `'start'` (default), `'end'`, `'center'` (outward), `'edges'` (inward), `'random'` (a seeded shuffle of the same delays) or an item index |
| `grid` | `[columns, rows]`: items fill the grid row by row, and the wave travels by straight-line distance (a ripple) |
| `ease` | an ease that reshapes the spread (default `'none'`); the first stays at 0, the last at the full spread |
| `seed` | for `from: 'random'`: another seed, another order |

With a layer array each layer's own `at` is kept and the delay is added to it. Keyframes inside the layers stay as they are (they count from the layer's start).

### `withFade`

Spec helper that adds alpha fade-in / fade-out to **any** sequence spec. Mutates and returns the spec, so it composes with other presets (`kenBurns`, …) and drops straight into `sequences[]`.

```ts
import { kenBurns, withFade } from 'pixi-effects';

sequences: [
  withFade(kenBurns({ asset: 'photo', at: 0, duration: 6, motion: 'scale' }), { in: 0.5, out: 0.5 }),
  withFade({ type: 'text', text: 'hi', at: 5, duration: 3, initial: { x: 'GW/2' } }, { in: 0.4 }),
]
```

| Option | Type   | Notes                                                                                         |
| ------ | ------ | --------------------------------------------------------------------------------------------- |
| `in?`  | number | fade-in length in seconds, at the start of the sequence. Sets `initial.alpha = 0`.            |
| `out?` | number | fade-out length in seconds, anchored to `at + duration`. **Requires `duration` on the spec** (throws otherwise). |

The added keyframes are layered on top of any keyframes the spec already has. `withFade` is available since `0.2.0`.


<!-- ===== docs/api.md ===== -->

# API Reference

- [`Movie`](#movie) — composition runtime: init, playback, render
- [`Controller`](#controller) — drop-in player UI overlay
- [`pixi-effects/three`](#pixi-effectsthree) — optional three.js integration

For DSL types (composition spec, sequences, filters, keyframes, expressions), see [DSL reference](./dsl.md).

---

## `Movie`

Imported from `pixi-effects`.

```ts
import { Movie } from 'pixi-effects';

const movie = new Movie();
await movie.init({ /* ... */ });
movie.play();
```

### Constructor

```ts
new Movie()
```

No arguments. State is fully populated by `init()`.

### `movie.init(options): Promise<void>`

Loads assets, builds the composition tree, mixes audio, and renders frame 0.

```ts
interface MovieOptions {
  width?:      number;              // canvas pixels  (default 1920)
  height?:     number;              // canvas pixels  (default 1080)
  duration?:   number;              // seconds         (default 10)
  frameRate?:  number;              // fps             (default 30)
  background?: string;              // CSS color hex   (default '#000000')
  canvas?:     HTMLCanvasElement;   // existing canvas to render into; otherwise PixiJS creates one
  assets?:     AssetSpec[];         // [{ name, src }]
  composition?: CompositionSpec;    // root composition (see DSL reference)
  vars?:       Record<string, number | string>;   // named values the composition reads: a number as a name in an expression, any as {name} in a string (see Variables)
  loop?:       boolean;             // start with movie.loop on: playing goes back to the start at the end (default false, like a <video>)
  loudness?:   number | false;      // the whole mix at this many LUFS (-16 is usual for web video): one gain, up or down, the loudest sample kept at -1 dBFS or under; false / left out: the mix as the layers make it (check says when it is quiet)
  poster?:     number;              // seconds: the frame shown before play (negative: from the end), see movie.poster
  motionBlur?: boolean | number | { samples?: number; shutter?: number };   // blur for render() / snapshot() / contactSheet(), not live playback; see Motion blur
  loader?:     HTMLElement | string | false;   // the page's loader (see pixi-effects/loader.css): shows how far init is (a bar, "BUILDING LAYERS 62%"), faded out when ready, stopped if init fails; default: a .pe-loader next to the canvas
}
```

Resolves once the composition is ready and the first frame has been rendered. Emits the `ready` event.

### `movie.play(): void`

Starts the requestAnimationFrame loop that drives `gotoFrame()` per tick. If `currentFrame >= totalFrames`, restarts from 0.

If audio sources exist, schedules them on the AudioContext at the appropriate offsets.

### `movie.pause(): void`

Stops the rAF loop and any playing audio. Emits `'pause'` only when the previous state was playing (so calling `pause()` on an already-paused movie is a no-op for listeners).

### `movie.gotoFrame(frame, force?): Promise<void>`

```ts
gotoFrame(frame: number, force?: boolean): Promise<void>
```

Seeks to a specific frame. Pauses if currently playing? **No** — does not change `isPlaying`. Updates `timeline.time()`, awaits any video frame readiness, renders, and emits `'frame'`.

`force=true` skips the early-return when the requested frame equals `currentFrame`. Use it after a composition rebuild.

### `movie.playUntil(seconds?): Promise<boolean>`

Play, and pause exactly at `seconds` (the frame `round(seconds × frameRate)`). It resolves `true` when the playhead has landed there; `false` when something else ended it first (a `pause()`, a seek, a newer `playUntil()`) or when there is nothing to play toward (a time at or before the playhead: it also pauses the movie where it is; a movie that is not ready). A time at or past the end lands on the last frame; with no time at all it plays to the end, says `ended`, and resolves `true`. An ordinary `play()` is not affected. It is the one move a presentation (`pixi-effects/present`) is built on; it is also the way to "play the intro, then wait": `await movie.playUntil(4.5)`.

### `movie.peek(fn): Promise<T>`

Look around and put the movie back: pauses, runs `fn` (seek, take pictures with `snapshot()`; the seeks made inside are not reported as `seeking` / `seeked`), then puts the playhead (or the poster) back where it was, whatever `fn` did, and returns what `fn` returned. `stopImages()` and `inspectStops()` (`pixi-effects/present`) are made with it.

### Movie variables and rebuilding: `vars`, `setVars()`, `resize()`, `rebuild()`

Variables are declared in `init({ vars: { title: 'NORD', shift: 0 } })` and read by the composition (see [Variables](dsl.md#variables)). Changing one builds the composition again: the new one is built off the stage first and swapped in when it is whole, at the same frame; a failure leaves the old one in place.

```ts
movie.vars                                         // the current values (a copy)
await movie.setVars({ shift: 40 });                // the declared names only (others: ignored with a did-you-mean); the same values: nothing happens
await movie.resize(1080, 1920);                    // the movie's size; W / H / GW / GH follow. Beats a width / height the composition names
await movie.rebuild({ composition, vars, width, height });   // the general form: any of the four; `composition` replaces the whole spec (your layout function, called again)
// all three resolve to a report, and fire 'rebuilt' with it:
interface RebuildReport { reason: 'vars' | 'resize' | 'rebuild'; ms: number; audio: 'reused' | 'mixed' | 'none'; frame: number; playing: boolean; unchanged?: true }
```

- The new composition is built while the old one goes on; at the swap the movie keeps doing what it is doing at that moment: the same frame, playing or paused (a `pause()`, a seek or a `play()` you made during the build is kept), the poster if it was shown. A playing movie whose sound is unchanged (`audio: 'reused'`) is not stopped at all: the frame clock and the sound go on and only the picture is swapped, so rebuilds in a row (a pointer) do not hold the playhead back. When the sound changed, the movie stops and plays on from the same frame with the new sound. A `playUntil()` in flight ends. The canvas changes size at the swap, not before. A `render()` or `peek()` in flight is not interrupted: the swap waits for it.
- The sound is mixed only when it changed: `audio: 'reused'` means the same mix as before (the mix is the slow part, 0.6 to 0.8 s for a film; the rest takes about 20 ms). A time remap (`warp` / `sourceMap`) turns the cache off.
- Calls that arrive during a rebuild are joined: at most one rebuild runs and one waits, with the latest values. Safe to call from `pointermove` or `scroll`: a rebuild that leaves the sound alone takes tens of milliseconds (11 to 42 ms on four gallery pieces), one that mixes the sound again 0.6 to 0.8 s, so a slider that changes the sound will lag behind the hand.
- A rebuild builds every layer again, **except a `three` layer that did not change**: one with a `name`, the same `setup` function, the same size and options keeps its scene, its renderer (and its graphics context) and its texture, so `setup` does not run again and a model is not loaded again (measured on a box scene: 15 ms for a rebuild of a WebGL layer built again, 1 ms kept; WebGPU 7 ms against 1 ms). `update` is the new composition's own and runs on the kept scene. A layer with no `name`, another size or another `setup`, or `reuse: false` is built again (the old one is disposed once, when the swap is done; a rebuild that fails leaves the old one untouched). Put what must follow a variable in `update` or in keyframes, not in `setup`; a `setup` that reads `movie.vars` needs `reuse: false`. A model still loads again when the composition changes (`rebuild({ composition })` with a new `setup` function).
- A rebuild that fails (a bad expression, a missing asset, a size that is not pixels) rejects, emits `error` with `where: 'rebuild'`, and the movie goes on with what it had. A `destroy()` during a rebuild ends it the same way.
- To follow a window: observe a CSS-sized box around the canvas, not the canvas itself (the movie sets the canvas's pixel size): `new ResizeObserver(() => movie.resize(Math.round(box.clientWidth * devicePixelRatio), Math.round(box.clientHeight * devicePixelRatio))).observe(box)` (the `liquid-layout` recipe).

### `movie.snapshot(frame?, options?): Promise<Blob | string>`

```ts
snapshot(frame?: number, options?: { scale?: number; type?: 'image/png' | 'image/jpeg'; quality?: number; as?: 'blob' | 'dataURL' | 'imageData'; motionBlur?: MotionBlurSpec }): Promise<Blob | string | ImageData>
```

A picture of one frame: **the canvas only** (the player bar is not in it). Seeks to `frame` (default: the current frame) and stays there. `as: 'dataURL'` returns a `data:` URL string, `as: 'imageData'` the pixels as an `ImageData` (to measure or compare; `quality` is the JPEG quality, 0 to 1), handy when a script can only return text. Use it to look at what you built.

### `movie.thumbnail(frame, options?): Promise<HTMLCanvasElement | null>`

```ts
thumbnail(frame: number, options?: { width?: number; scale?: number }): Promise<HTMLCanvasElement | null>   // width default 160 px
movie.thumbnailsOff   // null, 'video' or 'variables'
```

A small picture of any frame, made **without moving the playhead or changing what is on the canvas**, also while the movie plays (a seek-bar preview): the scene is put on that moment, drawn, copied and put back inside one task, so the browser never shows the in-between. It is the picture `snapshot()` gives at that size, without motion blur. It gives `null` when it cannot be made right now (a seek, a render or another thumbnail is running; ask again) and always when `movie.thumbnailsOff` is set: `'video'` for a movie with a video layer (the footage would have to seek twice), `'variables'` for a movie that declares variables. The player bar uses it for `thumbnails: true`.

### `movie.contactSheet(options?): Promise<Blob | string>`

```ts
contactSheet(options?: {
  frames?: number[]; times?: number[]; count?: number;   // which frames: explicit, in seconds, or `count` evenly spread (default 6)
  columns?: number;                                       // default 3
  cellWidth?: number;                                     // picture width in px, default 480
  as?: 'blob' | 'dataURL';
  motionBlur?: MotionBlurSpec;                            // see Motion blur
}): Promise<Blob | string>
```

Many frames on **one** PNG, each labelled `frame N · T s`. The cheapest way to check a whole animation by eye (include the middle of every transition and the last second). Restores the current frame afterwards.

### `measureText(text, style?): { width, height, lines }` and `splitText(text, style?, options?): TextPiece[]`

Text layout helpers, exported from `pixi-effects`. They measure with the renderer's own font metrics (the same numbers a text layer with that `style` has), so a layout built from them matches what is drawn. `style` is a text layer's `style` with numbers (no expressions). A web font must be loaded first.

```ts
measureText('Hello', { fontSize: 72 });                       // { width: 187.4, height: 81.3, lines: 1 }

interface SplitOptions { by?: 'chars' | 'words' | 'lines'; x?: number; y?: number; align?: 'left' | 'center' | 'right'; vertical?: boolean }
interface TextPiece { text: string; x: number; y: number; width: number; index: number; line: number; cx?: number; cy?: number; rotation?: number }   // cx / cy / rotation: vertical text only
splitText('Hello world', style, { by: 'words', x: 640, y: 300, align: 'center' });
// → [{ text: 'Hello', x, y, width, index: 0, line: 0 }, { text: 'world', ... }]
```

`x` is the line's left edge, or its centre / right edge with `align` (each line of a `\n` text is aligned on its own width); `y` is the top of the first line, and further lines go down by the line height. **Vertical writing (`vertical: true`, tategaki):** characters go down a column and a new line is a new column to the LEFT; `x` is the RIGHT edge of the first column, `y` the top of a column (`align: 'center'` / `'right'` put `y` at its middle / bottom). Each piece also has `cx` / `cy` (the centre of its cell, with 、。 moved to the upper right and small kana a little up and right) and `rotation` (90 for the long vowel mark, dashes, waves, leaders and brackets, which lie turned in vertical text): put a text layer with `anchorX: 0.5, anchorY: 0.5` at `cx` / `cy` with `rotation: p.rotation`, or call `animateText(..., { vertical: true })`, which does it. Latin letters and digits stay upright, one per cell (no tate-chu-yoko), and a line is only cut at `\n` (no kinsoku). Only `by: 'chars'` has a vertical form. Whitespace takes its room but is not returned as a piece. Use one text layer per piece with the same `style` and the default top-left anchor: `{ type: 'text', text: p.text, style, initial: { x: p.x, y: p.y } }`. Kerning is kept (a piece's x is the measured width of everything before it).

### `movie.inspect(frame?, options?): Promise<InspectReport>`

Where every layer is drawn at `frame`, as JSON — for checking layout without eyes. Seeks there and stays there. `options.layers`: `'visible'` (default, only layers drawn at this frame), `'all'`, or `'none'` (just `summary` and `issues`). Faint layers (alpha < 0.3) and text whose x / y is animated (tickers) are not reported.

```ts
interface InspectReport {
  frame: number; time: number; canvas: { width: number; height: number };
  summary: { layers: number; visible: number };
  issues: string[];              // text off the canvas / cut by an edge / empty / overlapping other text / partly hidden by an opaque shape or image drawn over it / struck through by a thin line drawn over it — read this first
  layers: Array<{
    path: string;                // names (or type#index) from the root, joined by '/'
    name?: string; type: string; threeD: boolean;
    visible: boolean;            // alive at this frame, not hidden by an ancestor, alpha > 0
    alpha: number;
    bounds: { x: number; y: number; width: number; height: number } | null;   // canvas pixels; null inside a threeD layer
    onCanvas: 'full' | 'partial' | 'none' | null;
  }>;
}
```

### `movie.pick(x, y, options?): PickHit | null`, `movie.pickAll(x, y, options?): PickHit[]`, `movie.canvasPoint(event): [x, y]`

What is under a point of the canvas, at the frame that is on screen: the layer on top (`pick`), or every layer under the point, the top first (`pickAll`). `x`, `y` are canvas pixels (the movie's own `width` × `height`); `canvasPoint(event)` makes them from a pointer event (`clientX` / `clientY`) when the canvas is shown larger or smaller than its own size: `movie.pick(...movie.canvasPoint(event))`. It reads the frame as the last draw left it, so after `await movie.snapshot(frame)` or any seek it answers for that frame; it takes no time and has no clock.

```ts
interface PickHit {
  name?: string; path: string; type: string;     // path: as in inspect(), names or type#index joined by '/'
  kind: 'flat' | 'card' | 'three';               // a 2D layer, a threeD layer (its projected card), a three layer
  point: { x: number; y: number };               // the point asked about
  local?: { x: number; y: number };              // a flat layer: the point in the layer's own pixels
  three?: { object: string; point: [number, number, number]; distance: number; object3d: unknown;     // a three layer: what the ray met first
            grab?: (plane?) => { move: (x, y) => { point, delta } | null } };                          // drag it: see below
}
// options: { only?: string[], ignore?: string[], alpha?: number }   layer names or paths; alpha: see below
```

The hit is the layer that was drawn at the point, not the group it is in: a card made of a `composition` with a face and a label gives the face (`name: 'face0'`, `path: 'card0/face0'`), and a layer with no name of its own gives no `name` at all. To know which group was hit, read the first segment of the path (`hit.path.split('/')[0]`); `only: ['card0']` asks only about the group (a group's name stands for everything in it).

A `three` layer covers its whole picture, but only what its ray meets is a hit: elsewhere the layers below are hit (a title, the background). `only` / `ignore` entries are layer names or paths, and a group's name (a nested composition) stands for everything in it: a card and its label are one target as `only: ['card']`.

How a layer is asked: a flat layer by its own shape (a rotated one by its rotated rectangle, a shape by its outline: a circle is hit inside the circle, not at the corners of its box), text, images and video by their box (or by their picture with `alpha`); a `threeD` layer by its projected quad (the card seen from behind is hit too; a `threeD` composition is one card: what is inside it is not asked); a `three` layer by a ray through its camera (with `followCamera` the composition's camera), skipping invisible objects: `hit.three.object` is the name of the object it met (its own, or its nearest ancestor's that has one) and `object3d` the live three object. A layer not alive at the frame, at alpha 0, hidden by a parent, or outside its mask is not hit; a group (a nested composition without `threeD`) is not a target, the layers in it are. **`{ alpha }` looks at the picture, not the box**: `movie.pick(x, y, { alpha: 0.1 })` leaves out a pixel of an image, a video, a `canvas` layer or the letters of a `text` layer (the gap between letters, the hole of an O: a text layer is its glyphs, drawn again once per text and style with PixiJS's own generator; measured 2026-10-17: it agrees with the picture on over 95 % of the points of three texts, the rest are antialiased edges) whose alpha is at or below 0.1 (a transparent corner of a logo, the clear part of a circle drawn on a canvas); without it the box is the picture and nothing is read. Shapes are always hit by their outline, text and `shader` layers by their box (a shader's WebGL picture cannot be read back safely). A picture that cannot be read (an image from another origin: load it with `crossorigin="anonymous"` or from the same site) stays a hit, with one warning. What is not here: touch with several fingers.

**Dragging an object of a `three` layer**: `hit.three.grab(plane)` fixes a plane through the point that was taken (`'screen'` facing the camera, the default; `'floor'` horizontal; `'wall'` with z constant; or a normal `[x, y, z]`), and `grab.move(x, y)` takes the pointer in canvas pixels and gives where its ray meets that plane (`point`) and how far that is from the point taken (`delta`; `null` where the ray never meets the plane: a floor seen edge-on). Move the object by `delta`, from where it was when it was taken, and it follows the pointer exactly. The ray is the layer's own camera's (with `followCamera`, the composition's). The layer's `update` should read where the object is from the page's own state, and the page calls `await movie.redraw()` to draw the frame again while the movie is paused (recipe `drag-3d`).

### `movie.redraw(): Promise<void>`

Draws the frame on screen again, quietly (no `seeking` / `seeked`). For a paused movie when something outside it that a layer reads has changed, such as a `three` layer whose `update` reads the page's own state. A playing movie needs no call: the next frame draws it.

Hover is `movie.hover` (below); drag and drop of a flat layer is the recipe `drag-drop`.

### `movie.hover(options?): () => void`

Which layer the pointer is over, as two callbacks, built on `pick`: `onEnter(hit)` when the layer under the pointer (or, in a `three` layer, the object: `hit.three.object`) changes to another, `onLeave(hit)` for the one it left, also when the pointer leaves the picture or the returned function is called. While the pointer rests inside the picture it is asked again on every frame, so a picture that moves under a still pointer is followed (the runner leaves, the cursor changes) with no pointer event in between. Options: `only` / `ignore` as for `pick`, `cursor` (`true` is `'pointer'`, or any CSS cursor: shown while something is hovered, put back otherwise). Returns the function that stops it. Pointer events cover a mouse, a pen and a finger (a touch is "entered" when it lands and "left" when it lifts). It is a page-side tool: an exported video has no pointer. A handler that throws is said once and does not stop the next hover.

```ts
const stop = movie.hover({ ignore: ['background'], cursor: true, onEnter: (hit) => glow(hit.name), onLeave: (hit) => unglow(hit.name) });
```

### `movie.inspectAudio(options?): AudioReport`

The soundtrack as numbers — for checking sound without listening. Every sound is also measured on its own, so overlaps do not blur it. `options.window`: seconds per row of `windows` (default 0.1).

```ts
interface AudioReport {
  duration: number; sampleRate: number;
  peakDb: number; peakAt: number;          // the mix before limiting; > 0 dBFS means it was limited
  sources: Array<{
    layer: string; source: string;         // 'layer "hit"', 'sfx "hit"' | 'asset "bgm"' | 'video "clip"'
    start: number; end: number;            // movie time
    peakDb: number;                        // the MIX while it plays
    sound: { length: number; peakDb: number; loudestAt: number; brightnessHz: number };   // the sound alone
    belowMixDb?: number;                   // how far below the loudest sample of the mix (itself included) around its own loudest moment it is; short sfx more than 12 dB under get ONE note, "buried", naming the worst
  }>;
  windows: Array<{ t: number; rmsDb: number; peakDb: number; brightnessHz: number }>;
  issues: string[];                        // limited mix, inaudible layer, sfx cut off by the end, no audio — read first
}
```

### `inspectSound(pcm, options?): SoundReport`

The same measurement for the sound of ANY file (not only a movie's mix): decode it to PCM (an `AudioBuffer` works) and ask. The numbers are the ones `movie.inspectAudio()` gives for the same samples, so `check` and `pixi-effects sound` agree. `options.window`: seconds per row of `windows` (default 0.1).

```ts
import { inspectSound } from 'pixi-effects';
// pcm: { numberOfChannels, sampleRate, length, getChannelData(ch): Float32Array }
interface SoundReport {
  duration: number; sampleRate: number; channels: number;
  peakDb: number;                                  // the loudest sample, dBFS
  loudness: { integratedLufs: number | null;       // ITU-R BS.1770; null for a sound under 0.4 s or with nothing above −70 LUFS
              truePeakDb: number; clippedSamples: number; silences: Array<{ from: number; to: number }> };
  windows: Array<{ t: number; rmsDb: number }>;    // the level over time
  notes: string[];                                 // quiet or loud for web video, little headroom, silent stretches
}
```

The command line wraps it: `pixi-effects sound <file>` (see `docs/media.md`). The page of that command loads it from `dist/sound.js`, a build of this function with no PixiJS in it.

`render()` encodes this same mix: AAC in mp4 / mov (the encoder delay is trimmed with an edit list), Opus in webm / mkv.

### `movie.render(options?): Promise<Blob>`

Renders the entire timeline to a single video file. Pauses playback first. **The file has exactly `duration × frameRate` frames** (a 10 s movie at 30 fps is 300 frames and 10.000 s: frames 0 to 299; the moment `duration` itself is not a frame, it belongs to the next one), and a `range: [a, b]` is the frames from `a` up to, not including, `b` (`[1, 2]` is 30 frames at 30 fps). So a clip made to loop has no repeated frame at its seam. `movie.totalFrames` is that number, and `movie.seek` / `gotoFrame` may still go to the end moment (frame `totalFrames`) to look at it.

```ts
interface RenderOptions {
  format?: 'mp4' | 'mov' | 'webm' | 'mkv' | 'wav' | 'ogg';   // default 'mp4'; wav / ogg: ONLY the movie's sound (an error when it has none)
  video?: {
    codec?:   string;   // 'avc' (H.264) | 'hevc' | 'vp9' | 'av1' | 'vp8'; default per format (mp4/mov→avc, webm→vp9, mkv→vp9)
    bitrate?: 'very-low' | 'low' | 'medium' | 'high' | 'very-high' | number | string;   // default 'high'; or bits a second: 8_000_000, '8M', '800k'
    hardware?: 'no-preference' | 'prefer-hardware' | 'prefer-software';   // where to encode (default 'no-preference')
    keyFrameInterval?: number;   // seconds between keyframes (default 2): shorter seeks faster, a bigger file
  };
  audio?: {
    codec?:   string;   // default per format (mp4/mov→aac, webm/mkv/ogg→opus, wav→pcm-s16)
    bitrate?: 'very-low' | 'low' | 'medium' | 'high' | 'very-high' | number | string;   // default 'high' (not for wav: it is not compressed)
  };
  motionBlur?: boolean | number | { samples?: number; shutter?: number };   // overrides movie.init's; false turns it off
}
```

#### Motion blur

`movie.init({ motionBlur })` (or the same option on a single `render()`, `snapshot()` or `contactSheet()` call) exposes each frame the way a film camera does: the frame is drawn `samples` times at moments spread over the shutter interval around its time, and the pictures are averaged. Fast motion smears along its path; a still picture is unchanged. `true` is 8 samples at a 180° shutter, a number is the sample count (2–64), `{ samples, shutter }` sets both (`shutter` is the fraction of a frame the shutter stays open, above 0 and up to 1; `0.5` is the film look, `1` blurs more). `false` turns it off for one call.

- It applies to what is **made**: the exported file, snapshots, contact sheets (so `pixi-effects check` and `inspect`-style reviews show what the file will have). Live playback is not blurred.
- Cost: a render takes about `samples` times as long (video layers are decoded once per sample). Eight samples is enough for most motion; raise it for very fast or large movement, where fewer samples show as separate ghost images instead of a smear.
- After a blurred snapshot, contact sheet or render the playhead and the stage are on an exact frame again, not a sample.
- `pixi-effects render --motion-blur 8 [--shutter 0.5]` sets it for one file.

**Video codec:** unless you name `video.codec`, the usual one for the format is used (mp4 / mov: `avc`; webm: `vp9`); if this browser cannot encode it, the next that works is used and a warning says so. A codec you name is never swapped: it is used, or the error names the one that would work (`"av1" ... "avc" would work: render({ format: 'mp4', video: { codec: 'avc' } })`). `hevc` and `av1` make smaller files at the same quality but play in fewer places than `avc`; `hardware: 'prefer-hardware'` asks the GPU's encoder.

**Sound only:** `render({ format: 'wav' })` (16-bit PCM, no loss) or `render({ format: 'ogg' })` (Opus) writes the movie's mixed sound without drawing a frame: a tune written as `music` becomes an audio file. `range` cuts it like a video. `pixi-effects render page.html -o mix.wav` does the same from a script. `mp3` and `flac` are not offered: browsers cannot encode them.

**Audio codec fallback:** unless you name `audio.codec`, the first codec this browser can actually encode is used (mp4: `aac`, then `opus`, `mp3`, `flac`; webm: `opus`, `vorbis`). Chrome on Linux has no AAC encoder, so there an mp4 with sound carries Opus and a warning says so (before, the export failed with a message about encoder configurations). A codec you name is never swapped: if it cannot be encoded the error says which one would work.

Returns a `Blob` whose `type` is the container's MIME (e.g. `video/mp4`). Emits `'progress'` repeatedly during the render.

The renderer also forces a keyframe every ~2 seconds so the resulting file scrubs efficiently in standard players.

### Poster time: `movie.init({ poster })`, `movie.poster`, `movie.posterImage()`

A movie can say which moment stands for it before it plays, the way `<video poster>` names a picture, except that here it is a **time**, so the picture comes from the same data and needs no separate image file:

```js
await movie.init({ /* … */ poster: 9.5 });          // seconds; a negative value counts back from the end (-2 = two seconds before the end)
movie.poster;                                       // 9.5, or null
movie.posterFrame;                                  // 285 at 30 fps, or null
const blob = await movie.posterImage();             // the picture at that time (frame 0 if there is no poster); { as: 'dataURL', type: 'image/jpeg', scale: 0.5 } like snapshot()
```

- Once the movie is ready the **canvas shows the poster frame**, while the playhead stays at frame 0 (`currentFrame` is 0, the player shows 0:00). The first `play()` or `gotoFrame()` replaces it, and **play starts from 0**.
- `posterImage()` leaves the movie as it was: still showing the poster, or back at the frame it was at. `contactSheet()` does the same.
- A time past the end is clamped to the last frame, and something that is not a number is ignored; both warn.
- `pixi-effects check` writes the poster as `poster.jpg`.

### `movie.timelineData(): TimelineData` and `movie.timelineChart(options?): string`

The whole movie as rows on a time axis, for a person to read at a glance. `timelineData()` is the data: `{ duration, rows, transitions }`, a row per layer with `name`, `type`, `depth` (1 inside a composition), absolute `start` / `end` in seconds, `keys` (when each keyframe starts) and, for a family of generated layers, `parts` (one span per layer). Layers of one type whose names differ only by numbers (`ring10-0`, `ring9-1`, `pop-3` …), four or more, become ONE row (`ring#-# ×19`), so a movie with 700 generated layers is a screenful. `timelineChart({ title })` returns one self-contained HTML page (an inline SVG, no scripts): bars coloured by type, ◆ at each keyframe start, a shaded band per transition, a tooltip per bar. `pixi-effects check` writes it next to the contact sheet as `timeline.html`.

`movie.timelineSvg()` is the chart alone (one `<svg>`, geometry in `data-*` attributes, each row `<g class="row" data-start>`): `pixi-effects view` puts a playhead on it and turns a click into a seek.

### Your own layer type: `Sequence` and `registerSequenceType(type, ctor)`

A layer type that the library does not have (a different renderer, a data view) is a subclass of `Sequence`, registered under a `type` name; then `{ type: 'mine', at, duration, initial, keyframes, filters, mask }` works like any layer, in any composition.

```js
import { Sequence, registerSequenceType } from 'pixi-effects';
import { Container } from 'pixi.js';

class Mine extends Sequence {
  async build() { this.target = new Container(); this.intrinsicWidth = 200; this.intrinsicHeight = 100; }   // the display object the keyframes move
  async awaitFrameAt(local) { /* optional: draw the frame at `local` seconds (playback and export both call it, so draw from the time only) */ }
}
registerSequenceType('mine', Mine);
```

`target` is the Pixi display object; `spec`, `parent`, `root`, `at`, `duration` are set for you; `scope()` gives the expression scope. Keyframes, filters, masks and the lifespan work on `target` as for the built-in layers. `awaitFrameAt(local)` is called once per frame by `gotoFrame` (the one path playback and export share), after the timeline has been set to that frame.

### `ease(name): (p: number) => number`

The function behind an ease name (`ease('power2.out')(0.5)`, `ease('spring.bouncy')`, `ease('cubic-bezier(.4, 0, .2, 1)')`), for a preset or a check of your own. A name nobody knows warns once and runs as `power1.out`.

### `movie.destroy(): Promise<void>`

Pauses playback, destroys the underlying PIXI Application, releases audio buffers and AudioContext, and marks the instance unusable.

### Events

```ts
movie.on(event, fn): this
movie.off(event, fn): this
```

| Event       | Payload                                           | Fired                                                 |
| ----------- | ------------------------------------------------- | ----------------------------------------------------- |
| `'ready'`   | none                                              | once, after `init()` resolves                         |
| `'frame'`   | `{ frame: number; totalFrames: number }`          | every `gotoFrame` (so once per playback frame too)    |
| `'play'`    | none                                              | when `play()` actually transitions from paused        |
| `'pause'`   | none                                              | when `pause()` actually transitions from playing      |
| `'progress'`| `{ progress: number; frame: number; totalFrames: number }` | during `render()`, once per encoded frame    |
| `'loadprogress'` | `{ stage: 'assets' \| 'build' \| 'sound' \| 'frames'; loaded: number; total: number; progress: number }` | during `init()`, after each asset and each layer built, once the sound is mixed; `progress` is 0 to 1 for the whole init. The page's `.pe-loader` already shows it; `movie.loadStages` gives the milliseconds per stage afterwards |
| `'seeking'` / `'seeked'` | `{ frame, totalFrames }` (the frame it lands on) | a `gotoFrame()` to another frame starts / has finished. NOT emitted for playback ticks, `render()`, `snapshot()` or `contactSheet()` |
| `'ended'`   | none                                              | playback ran off the end (after `'pause'`); pausing by hand does not emit it |
| `'volumechange'` | `{ volume: number; muted: boolean }`         | `volume` or `muted` really changed (clamping counts) |
| `'loopchange'` | `{ loop: boolean }`                            | `movie.loop` really changed (the first value from `init({ loop })` is not a change) |
| `'error'`   | `{ where: 'init' \| 'render' \| 'playback' \| 'rebuild'; message: string; error: unknown }` | `init()` / `render()` / a rebuild failed (the call still rejects), or a frame failed during playback |
| `'rebuilt'` | `RebuildReport` (see above) | a `setVars()` / `resize()` / `rebuild()` built the composition again (not for a call that changed nothing) |

The names are the ones an HTML5 `<video>` uses, so a player written for `<video>` ports over.

`progress` is `0..100` (rounded integer percent).

### Public properties

| Property         | Type      | Notes                                                   |
| ---------------- | --------- | ------------------------------------------------------- |
| `isPlaying`      | boolean   | true while the rAF loop is active                       |
| `currentFrame`   | number    | 0-based current frame                                   |
| `totalFrames`    | number    | `Math.round(duration * frameRate)`                      |
| `frameRate`      | number    | from `init`                                             |
| `duration`       | number    | seconds                                                 |
| `width`, `height`| number    | canvas pixels                                           |
| `background`     | string    | CSS color                                               |
| `volume`         | number    | 0..1 getter/setter; immediate. Setter clamps and applies to active audio |
| `muted`          | boolean   | getter/setter; immediate                                |
| `loop`           | boolean   | getter/setter, default `false`. When true, an ordinary `play()` that reaches the end goes back to the start and plays on: no `ended`, no `pause` / `play` events at the wrap, the sound starts again (a short gap). `playUntil()` and `render()` ignore it. Say `loopchange` when it changes |
| `app`            | `pixi.js Application \| null` | PIXI Application instance (advanced/escape hatch) |
| `timeline`       | `Timeline \| null`              | the movie's timeline (advanced): `time(t)`, `duration()`, `segments()` |
| `vars`           | `Record<string, number \| string>` | the current variable values (a copy) |
| `stops`          | `Stop[]`  | the composition's stops: named times (see Presentations); empty for an ordinary movie |

### Presentations: `stops` and `pixi-effects/present`

A composition can say where a presentation pauses: `composition: { stops: [...] }`. A stop is a time in seconds or `{ at, page?, notes?, advance?, pdf? }`; a stop with `page` (a name, or `true`) begins a page, the others are steps of it; with no `page` anywhere each stop is a page; the first stop always begins one. A negative `at` counts back from the end; two stops on one frame are one; a stop outside the movie is ignored with a warning. `movie.play()` ignores the stops and plays to the end; the `Controller`'s play button, Space and a click on the picture play to the next stop and pause there (see `pauseAtStops`). `pdf: true` marks the stop whose picture stands for its page in a PDF (and in the page overview); `pdf: false` keeps a stop's picture out of the PDF (a last stop that is mid-exit, a step you do not want on paper). Without flags a page is pictured by its last stop.

```ts
import { next, prev, goToStop, goToPage, onStop, stopIndex, pageIndex, pageCount, currentStop } from 'pixi-effects/present';

movie.stops                    // (the core) Stop[]: { index, at, frame, page: string | null, pageIndex, pageStart, notes?, advance?, pdf? }
await next(movie);             // play to the next stop and pause exactly on its frame; pressed again while playing, skip to that stop at once;
                               // after the last stop play to the end. Resolves when it has landed (or stopped for another reason).
await prev(movie);             // jump back to the previous stop at once (no reverse playback); from the first stop, to the start
await goToStop(movie, i);      // 0-based
await goToPage(movie, n);      // 0-based: the first stop of page n
stopIndex(movie) / pageIndex(movie) / pageCount(movie) / currentStop(movie)      // where the playhead is (-1 / null before the first stop)
const off = onStop(movie, ({ index, stop, pageIndex }) => …);                    // a stop was landed on; off() stops listening
```

The presentation side is a separate entry, `pixi-effects/present`, built on the core's public API only (an import map line: `"pixi-effects/present": ".../dist/present.js"`). The core knows `stops` (named times) and two general moves it is made of: `movie.playUntil(seconds)` and `movie.peek(fn)` (below). An ordinary `movie.play()` ignores the stops. `onStop` listeners belong to the `pixi-effects/present` module the page imported: the `Controller` loads `present.js` from beside itself, so map `"pixi-effects/present"` to the same folder as `Controller.js`, or a Controller landing will not reach your `onStop`.


`deck({ pages, transition? })` (from `pixi-effects/present`) builds such a movie from pages (see the DSL reference). **`Presenter`** (also `pixi-effects/present`) is the player for it:

```ts
import { Presenter } from 'pixi-effects/present';
const presenter = new Presenter(movie, { canvas });     // instead of Controller; await presenter.start() to go fullscreen and play to the first stop
```

| Option | Default | Notes |
| ------ | ------- | ----- |
| `canvas` | required | |
| `keyboard` | `true` | **next**: → ↓ Space Enter PageDown · **back**: ← ↑ Backspace PageUp · Home (first page) · End (last stop) · a page number then Enter · **G** the page overview · **P** the presenter view · B or `.` black screen · W or `,` white screen · F fullscreen · `?` / H the list of keys · Esc closes / leaves |
| `clickToAdvance` | `true` | a click or tap on the picture is next |
| `swipe` | `true` | a swipe to the left is next, to the right is back |
| `indicator` | `true` | a page counter (`3 / 8`), the page name and a progress line along the bottom; they fade out when nothing happens, and the pointer hides with them |
| `autoAdvance` | `true` | a stop with `advance: seconds` moves on by itself |
| `loop` | `false` | run off the end: go back to the start and play again |
| `accent` | white | the progress line's colour |
| `onExit` | none | Escape with nothing left to close, or fullscreen left |

**The page overview (`G`)** is a grid of every page with its picture, the current page marked: arrows choose, Enter or a click goes there, `G` or Esc closes. **The presenter view (`P`)** opens a second window for the speaker: the picture that is on screen (live), the picture of the next stop, the notes of the page, a timer (with reset), the page counter and Back / Next buttons; the keys work there too. Both use a picture of every stop that `start()` makes **before** the audience sees anything (behind a "Preparing…" cover; taking them moves the playhead through the stops and back, so it must not happen on screen); `presenter.ensureThumbs()` makes them on demand (an overview opened before that does it on the spot, with a flicker). A browser needs a click or key press to open a popup: `P` is one; if it is blocked a warning says so.

`presenter.start()`, `presenter.openPresenterView()`, `presenter.closePresenterView()`, `presenter.next()`, `presenter.prev()`, `presenter.setCover('black' \| 'white' \| 'off')`, `presenter.exit()`, `presenter.destroy()`. It uses the canvas's positioned parent, or wraps the canvas like `Controller` does. A movie with stops shown through a **`Controller`** gets a mark per stop on the seek bar and a Present button (`presentButton: false` leaves the marks only) that hands the page to a `Presenter` (fullscreen, keys, click and swipe move through the stops; Esc gives the bar back).

### `inspectStops(movie, options?)`

Is the picture at each stop still changing? Each stop is compared with the picture `lookback` frames before it (default 3); when more than `tolerance` (default 0.004, a share of the pixels) differs, the audience, the page overview and a PDF would see a half-finished animation. Returns `{ stops: [{ index, page, at, frame, moving, settled }], issues: string[] }`; each issue names the stop and the page and says what to do (move the stop to after the animation has ended, or flag a settled stop of the page `pdf: true`). Leaves the playhead where it was. `pixi-effects check` runs it for any page with `stops` (it loads the page's own `pixi-effects/present`; add that line to the import map).

### Pictures of the stops and the deck as a PDF: `stopImages(movie)`, `exportPDF(movie)`

```ts
import { stopImages, exportPDF } from 'pixi-effects/present';
const pages = await stopImages(movie, { as: 'dataURL', type: 'image/jpeg', scale: 0.25 });   // one picture per PAGE: its last stop, fully built
// [{ stop, page, image }, …]; { which: 'stops' } is one per stop, { pick: 'first' } the first stop of each page; onImage(img) is called as each one is ready
const pdf = await exportPDF(movie, { title: 'My talk' });                                    // a Blob: one PDF page per page of the deck (JPEG at the canvas size)
```

Both pause the movie and leave the playhead where it was; a movie with no stops returns an empty list / throws (a PDF needs pages). The picture of a page is, in order: its last stop flagged `pdf: true`, else its last (with `pick: 'first'`, first) stop that is not `pdf: false`; a page whose stops are all `pdf: false` is left out of a PDF (a page list still shows it by its last stop); `which: 'stops'` makes a page of every stop that is not `pdf: false`. `exportPDF` options: `which`, `pick`, `scale`, `quality` (JPEG, default 0.92), `title`, `motionBlur`, `onImage`. A transparent background comes out black in a JPEG: give the movie a `background`. From a script, `npx pixi-effects render my-talk.html -o my-talk.pdf` (add `--all-stops` for a page per stop).

### Audio-reactive: `audioEnvelope()`, `react()`, `bpmEnvelope()`

Make things follow the sound, deterministically (playback, seeking and export agree): analyse the sound **before** `movie.init`, then bake what it does into keyframes.

```ts
import { audioEnvelope, bpmEnvelope, react } from 'pixi-effects';

const env = await audioEnvelope('music.mp3', { frameRate: 30 });      // a URL, Blob / File, ArrayBuffer or AudioBuffer
// env.series.level / bass / mid / treble: one value per frame, 0–1 on a log (perceptual) scale, measured against the loudest of them
// env.beats: times of the beats (seconds); env.bpm: the tempo (null with too few beats); env.at(time, 'bass')
await movie.init({ /* … */ composition: { sequences: [
  { type: 'shape', shape: 'circle', radius: 120, initial: { x: 640, y: 360 },
    keyframes: react(env, { duration: 12, props: { scale: { base: 1, amount: 0.4, band: 'bass', attack: 0.02, release: 0.2 } } }) },
  { type: 'audio', asset: 'music', loop: true },
] } });
```

| `audioEnvelope(source, options)` | |
| --- | --- |
| `frameRate` | one value per video frame: use the movie's (default 30) |
| `bands` | `{ name: [fromHz, toHz] }`. Default `{ bass: [20, 150], mid: [150, 2000], treble: [2000, 10000] }`; give your own for a spectrum (24 log-spaced bands) and the beat detector looks in `bass` (set `beatBand` if you have no such band) |
| `beatSensitivity` | above 1 finds more beats, below 1 fewer |

`react(env, options)` returns keyframes (one linear step per frame): `{ at?, duration, props, audioOffset?, loop?, frameRate? }`. Each prop is `{ base, amount, band?, beats?, decay?, attack?, release?, invert?, curve? }`: the value is `base + amount × level`. `band` picks a series (default `level`); `beats: true` follows the beats instead (a jump to full on each, falling off with `decay` seconds); `attack` / `release` smooth the rise and fall in seconds like a level meter (a quick rise and a slow fall bounces); `curve` above 1 lets only the loud parts move it. `audioOffset` is where in the sound the layer's start is (a layer that begins 2 s after the music: `audioOffset: 2`); `loop: true` for a looping music layer. It refuses to bake more than 4000 steps (lower `frameRate`).

`bpmEnvelope(120, { duration, frameRate })` is a stand-in with no audio file: a kick on every beat (`bass`), a snare on 2 and 4 (`mid`), hats on the eighths (`treble`), exactly on the tempo. Use it to try an idea, or to make visuals that match sound effects you place on the same tempo. The analysis is the same code the check tool trusts: pure and deterministic.

### `musicEnvelope()`

```ts
import { musicEnvelope } from 'pixi-effects';
const music = { bpm: 96, tracks: [{ inst: 'bass', notes: 'c2:2 g1:2' }], drums: { kick: 'x...x...' } };       // the same object the audio layer plays
const env = await musicEnvelope(music, { frameRate: 30 });                                                     // BEFORE movie.init; async: the synthesiser is its own chunk
```

The [audio-reactive](#audio-reactive-audioenvelope-react-bpmenvelope) envelope of an audio layer's [`music`](dsl.md#music-written-as-text-music): it renders the score and analyses that very sound, so `env.series` (`level`, `bass`, `mid`, `treble`, or your `bands`) follows the notes. `env.beats` are exact (the kick hits, or every beat when the score has no kick) and `env.bpm` is the starting tempo. Options are `audioEnvelope`'s (`frameRate`, `bands`, `beatBand`, `beatSensitivity`). Throws, saying why, when the score cannot play (for example no `bpm`). The envelope covers the music and its tail; when the layer starts at `at`, pass `at` to `react()`.

### `musicEvents()`

```ts
import { musicEvents } from 'pixi-effects';
const ev = await musicEvents(music);                    // the same object the audio layer plays; BEFORE movie.init, async like musicEnvelope()
ev.tracks[0].notes[0];                                  // { beat: 0, time: 0, duration: 4, seconds: 2, bar: 1, beatInBar: 1, name: 'Am7', chord: true, midi: [57, 60, 64, 67], velocity: 0.8 }
ev.drums[0];                                            // { kind: 'kick', hits: [{ beat, time, bar, beatInBar, velocity }, ...] }
```

What a [`music`](dsl.md#music-written-as-text-music) score plays, as data: every note and chord with its `beat` and `time` (seconds from the start of the music, the tempo map applied: add the audio layer's `at` for movie time; swing and humanize are not applied), `duration`, `bar` and `beatInBar` (from `meter`, default 4), the audible `midi` pitches (`transpose` is in), the `name` **as the score wrote it** (a transposed score still says `Am7` while `midi` sounds a tone higher: caption from `midi` if you transpose), and every drum hit with the pattern repeated out. Also `bpm`, `meter`, `beats`, `bars`, `seconds` and per track `beats` / `bars`. Use it to make the picture follow the score: light the keys of the chord that sounds, caption its name, flash on the snare. A score that cannot play throws with the reason; warnings are logged as for the layer.

### `musicBuffer()`

```ts
import { musicBuffer } from 'pixi-effects';
const buffer = await musicBuffer(music, { sampleRate: 44100, duration?, loop? });                    // an AudioBuffer (stereo)
const src = audioContext.createBufferSource(); src.buffer = buffer; src.connect(audioContext.destination); src.start();
```

The sound of [`music`](dsl.md#music-written-as-text-music) as a Web Audio buffer, for a page that plays tunes without a movie (a jingle on a button, your own player). `duration` (seconds) cuts it or, with `loop: true`, repeats it up to that length; the default is the music's length plus its tail. Warnings are printed like for an audio layer; it throws, saying why, when the score cannot play. Async: the synthesiser is its own chunk.

### `movie.toggleMute(): boolean`

Flips `muted` and returns the new value.

---

## Building your own player

`Controller` is one optional player; everything it does is public on the movie, so a player of your own is plain HTML + CSS + a few handlers:

```js
const el = id => document.getElementById(id);
movie.on('ready', () => { el('seek').max = movie.totalFrames; });
movie.on('frame', ({ frame }) => { el('seek').value = frame; el('time').textContent = (frame / movie.frameRate).toFixed(1) + ' s'; });
movie.on('play',  () => { el('play').textContent = '❚❚'; });
movie.on('pause', () => { el('play').textContent = '▶'; });
movie.on('ended', () => { el('play').textContent = '↻'; });                 // play() at the end starts again from 0
movie.on('volumechange', ({ volume, muted }) => { el('vol').value = muted ? 0 : volume; });
el('play').onclick = () => (movie.isPlaying ? movie.pause() : movie.play());
el('seek').oninput = e => movie.gotoFrame(+e.target.value);
```

What you have: `play()`, `pause()`, `gotoFrame(frame)`, `volume`, `muted` / `toggleMute()`; the state `currentFrame`, `totalFrames`, `frameRate`, `duration`, `isPlaying`, `isReady`, `loadStages` (milliseconds `init()` spent in `assets` / `build` / `sound` / `frames`), `audioBlocked` (true while the browser keeps the movie's sound silent until a tap: show "tap for sound"; a tap or key press that arrives while `play()` is pending, or the next `play()` made from a tap, starts it); the events above; `render()` for a download button; `snapshot()` for a thumbnail; `timelineData()` / `timelineSvg()` for a timeline like `pixi-effects view`'s. Keep the movie's `canvas` wherever your layout wants it (the page's CSS sizes it). To only change how `Controller` looks, see **Theme** below.

## `Controller`

Imported from `pixi-effects/controller`.

```ts
import { Controller } from 'pixi-effects/controller';

const ctrl = new Controller(movie, { canvas });
// later:
ctrl.destroy();
```

A YouTube-style overlay anchored to the canvas:

```
[▶] [🔉━━━] 0:00 / 0:08 ··· [⬇] [⛶]
└── play   └── volume   └── time     └── export   └── fullscreen
```

The bar auto-hides 2.5s after pointer activity stops (in both playing and paused state) and reappears on pointer move. Clicking the download icon opens a popover with format/quality selectors and a `Download` confirm button. Fullscreen scales the canvas + bar to the viewport.

### Constructor

```ts
new Controller(movie: Movie, options: ControllerOptions)

interface ControllerOptions {
  canvas: HTMLCanvasElement;          // required
  exportButton?: boolean;             // default true; false hides ⬇ + popover
  keyboard?: boolean;                 // default true
  presentButton?: boolean;            // default true: a movie with stops gets a Present button (marks on the seek bar are always shown)
  loopButton?: boolean;               // default true: a loop button next to the volume (and the L key) that flips movie.loop
  thumbnails?: boolean;               // default false: a small picture of the frame under the pointer above the seek bar (movie.thumbnail()); off by itself with video footage or variables
  pauseAtStops?: boolean;             // default true: with stops, play / Space / click on the picture play to the next stop and pause; false plays straight through
  clickToPlay?: boolean;              // default true: a click / tap on the picture plays / pauses (like <video>); false leaves the canvas alone
  className?: string;                 // default 'movie-controller'
  theme?: ControllerTheme;            // colours / thickness / font of the bar, see Theme
}
```

Mounting strategy:

- If `canvas.parentElement` already has a non-static `position`, the controller is appended directly into it.
- Otherwise the canvas is wrapped in a `<div class="movie-controller-wrap">` (with `position: relative`). The wrapper is removed on `destroy()`.

### Theme: change the colours of the bar

The bar is blue by default. Every colour and the track thickness are CSS custom properties with the old values as defaults, so there are two ways to change them:

```js
new Controller(movie, { canvas, theme: { accent: '#ff4d6d', foreground: '#ffe9a8', trackHeight: 5 } });   // in code
controller.setTheme({ accent: '#7bd88f' });          // later, live; only the keys you give change
controller.setTheme({ accent: null });               // null = back to the default
```
```css
:root { --mc-accent: #ff4d6d; }                      /* or in your page CSS: the canvas's parent, or :root */
```

| `theme` key | CSS property | What | Default |
|---|---|---|---|
| `accent` | `--mc-accent` | progress bar, its thumb, focus rings, the export button | `#007AFF` |
| `foreground` | `--mc-fg` | icons, the time, the volume slider | `#fff` |
| `track` | `--mc-track` | the unfilled part of the progress / volume bars | `rgba(255,255,255,0.25)` |
| `barBackground` | `--mc-bar-bg` | the background behind the buttons (any CSS background, e.g. a gradient) | black fading to transparent upward |
| `trackHeight` | `--mc-track-height` | thickness of the progress bar (a number is px) | `3px` |
| `font` | `--mc-font` | `font-family` of the bar | system UI font |

A misspelt key warns with the valid ones. To restyle more than the theme covers, set the `--mc-*` custom properties (or override the `.movie-controller` classes) in your own CSS.

### `controller.destroy(): void`

Idempotent. Removes:

- the controller bar DOM
- all listeners (Movie events, document keydown/pointerdown/fullscreenchange, wrapper pointermove/mouseleave)
- the auto-hide timer
- the wrapper, if it was created here
- the injected stylesheet (ref-counted across multiple controllers)

If the controller still owns `document.fullscreenElement`, it calls `exitFullscreen()`.

### Export popover

Format options: **MP4**, **WebM**, **MOV** (mp4 ↔ avc/aac, webm ↔ vp9/opus, mov ↔ avc/aac).

Quality options: **Low**, **Medium**, **High** (default), **Very High**.

These map directly to `Movie.render()`'s `format` and `video.bitrate` / `audio.bitrate` parameters. Selection persists for the lifetime of the controller instance (no localStorage).

The download is triggered by an in-page `<a download>` click, so the file lands in the browser's default download location with a name like `movie-{YYYYMMDD-HHMMSS}.{ext}`.

### Keyboard shortcuts

Active when `keyboard: true` and the key target is not `<input>`/`<textarea>`/`<select>`/contenteditable.

| Key         | Action                                              |
| ----------- | --------------------------------------------------- |
| `Space`     | play / pause                                        |
| `←` / `→`   | step ±1 frame                                       |
| `↑` / `↓`   | volume ±5% (clears mute when increasing past zero)  |
| `M`         | toggle mute                                         |
| `L`         | toggle loop (`movie.loop`)                          |
| `Shift+E`   | export with current settings (skips the popover)    |
| `F`         | toggle fullscreen                                   |
| `Esc`       | close the export popover or exit fullscreen (browser) |

### Theming

The bar uses fixed colors (`#007AFF` for the active track / fill / confirm button, white for icons, `rgba(0,0,0,0.75)` gradient background). Override by adding stricter CSS rules under `.movie-controller`. A theming API (CSS custom properties) is on the roadmap.

## `pixi-effects/three`

Optional three.js integration, imported from its own entry so the core `pixi-effects` entry never touches three.js:

```ts
import { registerThree, three, threeGltf, threeFrameCamera, ThreeSequence } from 'pixi-effects/three';
```

**Install:** `npm i three`. `three` is a peer dependency marked optional (`peerDependenciesMeta.three.optional = true`) — consumers who never import `pixi-effects/three` are unaffected either way. A page that loads a glTF with `threeGltf` also needs `"three/addons/"` in its import map (three's `examples/jsm/`); `renderer: 'webgpu'` needs three 0.17x or later and `"three/webgpu"`.

For the `type: 'three'` spec shape (fields, keyframe paths, `followCamera` / `followLights` / `followFog`, rules), see [DSL reference § three](./dsl.md#three).

### `registerThree(options?: { renderer?: 'webgl' | 'webgpu' }): void`

Registers the `'three'` sequence type with the composition builder. Call once, before `Movie.init()` builds a composition containing a `type: 'three'` sequence. Idempotent. `renderer` is the page-level default of every three layer that names no `renderer` of its own (default `'webgl'`; the last call wins).

### `three(spec: ThreeSequenceSpec): SequenceSpec`

Typing helper — accepts a strongly-typed three spec and returns it as a plain `SequenceSpec`, so it drops straight into `composition.sequences` alongside `text` / `image` / etc. A cast only; not required for the sequence to work, but gives editor autocomplete on `setup` / `update` / `dispose`.

### `threeGltf(url: string, options?: ThreeGltfOptions): Promise<ThreeGltfModel>`

Loads a `.glb` / `.gltf` with three's `GLTFLoader` (a page that never calls it never loads the addon) for use in a three layer's `setup` / `update`. Options: `animation` (a clip name, an index, or `false` for the bind pose; default the first clip), `speed`, `offset`, `loop`. Returns `{ object, clips, size, pose(t), fit(px), dispose() }`: `object` is a `Group` whose origin is the centre of the model's bounding box; `pose(t)` poses the clip at `t × speed + offset` seconds with `AnimationMixer.setTime` (a function of the time: a seek, an export and a repeat give the same frame); `fit(px)` scales `object` so the model's longest side is `px`. Skinned meshes are drawn always (`frustumCulled = false`). A failed load names the URL; an unknown clip name lists the clips the file has. Draco / KTX2 / Meshopt files need a decoder you set up yourself (`npx pixi-effects probe model.glb` says whether a file needs one).

### `threeFrameCamera(camera, object, options?: { direction?, margin? }): void`

Puts a `PerspectiveCamera` where the whole of `object` (its bounding box now, with its scale and place) fits the frame, looking at its centre, from a three-quarter view (`direction` default `[0.45, 0.3, 1]`) with 10 % room (`margin` 1.1). Uses the camera's own `fov` and `aspect`; sets `near` and `far`.

### `ThreeSequence`

The `Sequence` subclass that backs `type: 'three'`. Exported for advanced use (e.g. `instanceof` checks). `renderer` (`'webgl'` / `'webgpu'`) and `backend` (`'webgl'` / `'webgpu'` / `'webgl2'`: three's WebGPURenderer found no WebGPU and used its WebGL2 backend) say what drew it once it is built; `checkDeterminism(times)` is what `check` and `movie.review()` call to hold the layer to "a function of the time".

### Exported types

```ts
import type { ThreeContext, ThreeSetupResult, ThreeSequenceSpec, ThreeGltfModel, ThreeGltfOptions, ThreeFrameCameraOptions, ThreeRendererKind } from 'pixi-effects/three';
```

| Type                | Notes                                                                          |
| ------------------- | ------------------------------------------------------------------------------- |
| `ThreeContext`      | `{ scene, camera, renderer, width, height, space? }` handed to `setup` / `update` / `dispose`; `renderer` is a `WebGLRenderer` or a `WebGPURenderer`; `space` is the composition's camera, lights and fog when the layer follows them. |
| `ThreeSetupResult`  | `{ objects?, camera? }` returned from `setup`.                                 |
| `ThreeSequenceSpec` | the `type: 'three'` sequence spec.                                             |
| `ThreeGltfModel`, `ThreeGltfOptions`, `ThreeFrameCameraOptions` | what `threeGltf` and `threeFrameCamera` take and return. |
| `ThreeRendererKind` | `'webgl' \| 'webgpu'`.                                                         |


<!-- ===== docs/media.md ===== -->

# Media tools: look at, listen to, cut and join footage

Six commands for an AI agent (or a person) who is handed a video or a sound and has no ffmpeg: `probe` says what is in it, `frames` shows it, `sound` measures it, `trim` cuts it, `concat` joins clips, `audio` takes the sound out. They read and write files with [mediabunny](https://mediabunny.dev) (which ships with pixi-effects), so there is nothing else to install; the ones that decode or re-encode use the headless Chrome that `check` and `render` already use.

**If ffmpeg is installed and the job is a long transcode, use ffmpeg.** It is faster at that, and it does far more. These commands are for the other cases: no ffmpeg, a quick look, and answers shaped for an agent: structured output (`--json`), the real times of a cut, and no flag-order traps.

Exit code: **0** done · **1** a problem (the file, the browser, the job as asked) · **2** usage. Every command prints a short report, or the same facts as JSON with `--json`. A file argument is a path or an `http(s)` URL. A mistake is one sentence that names the file and what to do, never a stack trace.

## Media

```
pixi-effects probe  <file|url> [--keyframes] [--expect "…"]      what is in it: codecs, size, rotation, sound; for a .glb / .gltf model its clips and size   (help probe)
pixi-effects frames <file|url> [--at 1,50%,end] [--sheet]        pictures of a video, and a contact sheet       (help frames)
pixi-effects sound  <file|url> [--waveform] [--window 0.5]       loudness, peak, silences, loudest stretch      (help sound)
pixi-effects trim   <file|url> <start> <end> -o <out> [--exact]  cut it, and say the real times                 (help trim)
pixi-effects concat <a> <b> [<c> …] -o <out>                     join clips by copy, and say where each starts  (help concat)
pixi-effects audio  <file|url> -o <out.m4a>                      the sound of a file, copied out                (help media: `help audio` is the DSL's audio layer)
```

All of them take a path or an `http(s)` URL and `--json`. `probe`, `trim` by copy, `concat` and `audio` need no browser; `frames`, `sound` and `trim --exact` use Chrome. A mistake exits 1 (the file, the browser, the job as asked) or 2 (usage) with one sentence.

## Look before you use footage

Footage you have not looked at is footage you do not know. Before a clip goes into a video: `probe` it (size, length, rotation, sound), look at a few frames with `frames --sheet` and read the numbers of `sound`. A clip from a phone is often rotated and has a variable frame rate; a screen recording often has no sound; a download may be 4K when the video is 720p. Each of those is one line of `probe`.

```sh
npx pixi-effects probe footage.mp4
npx pixi-effects frames footage.mp4 --sheet -o looks
npx pixi-effects sound footage.mp4
```

## probe

```sh
npx pixi-effects probe footage.mp4 --keyframes
```

```
footage.mp4
  MP4 · 6.036 s · 53 KB
  video  avc 320×180 · 30 fps · 8 kb/s · colour bt709 (transfer iec61966-2-1, limited range)
  audio  aac 48000 Hz · 2 ch · 157 kb/s
  key packets at: 0, 2, 4, 6 s
```

Container, duration, size, and a row per track: codec, size **as it is shown** (a rotated clip says `180×320 shown (stored 320×180, turned 90° clockwise)`: the stored size, the shown size and the direction are all there, and whether the picture then reads upright depends on how the file was made, so look at a frame), frame rate (and whether it varies), bitrate, sample rate, channels. `--keyframes` lists the key packets (the only places a cut by copy can start). Notes say what an author would trip on: `no audio`, `no video`, `rotated 90°`, `variable frame rate`, `the video starts at 0.5 s` (the first frame is not at 0, so the sound can start before the picture). Runs in Node, no browser.

**Check a file against what it must be: `--expect`.** A platform or a brief asks for numbers (a size, a frame rate, a frame count, a bitrate, no sound). Write them, and `probe` measures the file (every packet, not a header) and answers one line each, exit 1 when one does not hold:

```sh
npx pixi-effects probe footage.mp4 --expect "size=320x180 fps=30 frames=181 audio=aac container=mp4"
```

```
  ok    size      320x180  (wanted =320x180)
  ok    frames    181  (wanted =181)
  …
RESULT: all 5 expectations hold
```

The words: `size` (`3840x2160`), `width`, `height`, `fps`, `frames`, `duration` (seconds, right to half a frame), `bitrate` (of the whole file's picture: `35M`, `800k` or bits a second), `video` and `audio` (a codec, `none` or, for audio, `any`), `container`, `matrix` and `transfer` (the colour tags the file carries: `matrix=bt709` is what a platform that asks for Rec.709 means; the files `render()` writes have the Rec.709 primaries and matrix, limited range, and the **sRGB transfer** `iec61966-2-1`, which is the true name of what was encoded, since the pixels are drawn as sRGB: editors and players treat it as Rec.709 in practice). Operators: `=` `!=` `>=` `<=` `>` `<` (`size`, `video`, `audio` and `container` take only `=` and `!=`). Separate by spaces or commas; a misspelt word gets `did you mean`. `--json` adds an `expect` list with `got` and `ok` for each. Remember: a render's `bitrate` is a ceiling, not a target (a quiet or mostly black picture is written far under it): ask `probe` what the file really has.

## trim


```sh
npx pixi-effects trim footage.mp4 2 4 -o cut.mp4
npx pixi-effects trim footage.mp4 3.3 4.9 -o cut.mp4 --force
npx pixi-effects trim footage.mp4 3.3 4.9 -o cut.mp4 --force --exact
```

`trim <file> <start> <end> -o <out>`: times are seconds (`12.5`) or `1:02.5`. The output type follows the extension (`.mp4 .mov .webm .mkv .m4a`); an existing file is only replaced with `--force`.

**By copy (the default)** nothing is re-encoded: the picture and sound are the source's own bytes, so there is no loss and it takes a moment. A copy can only start on a **key frame**, so it starts on the next one and says so:

```
cut.mp4  13 KB
  asked 3.3–4.9 s, got 4–4.9 s
  copied: video avc, audio aac (no re-encode)
  note   a copy can only start on a key frame: it starts on the next key frame, 4 s, not 3.3 s (0.7 s later); use --exact to start on 3.3 s …
```

Read `got`, not `asked`: `--json` has `requested`, `actual`, `reencoded`. A range with no key frame inside it (a cut shorter than the gap between key frames) is refused with the key frames around it. The cut is made starting ON that key frame, so picture and sound start together at 0 and the file is as long as `got` says (checked by reading the file back: both tracks start within 0.05 s of 0 and last what the report says). Why not mediabunny's default, which starts exactly where asked by writing the frames before it as hidden earlier frames: it plays right in Chrome and in ffmpeg (measured), but other players treat those hidden frames differently and were not measured, and a glitch there would be invisible to an agent. The report is read back from the written file, not predicted; the output is made aside and moved into place only when it worked, so a refused copy leaves no file and never empties one that was there. `probe --keyframes` lists where a copy can start.

**`--exact`** re-encodes the picture in the browser so the cut starts on the frame asked for (the sound is copied, not re-encoded: its packets are the source's own); `actual` is read back from the file, so it is where the picture really stops. The cut is held in memory until it is written, so it is for clips, not for hours: for those, ffmpeg.

## concat

```sh
npx pixi-effects concat footage.mp4 footage.mp4 -o joined.mp4
```

```
joined.mp4  1.9 MB
  2 clips, 12.07 s, joined by copy (no re-encode): video avc, audio aac
  1  footage.mp4  0–6.03 s
  2  footage.mp4  6.03–12.07 s
```

`concat <a> <b> [<c> …] -o <out>`: the clips one after another, in the order given, by copy: the packets are the sources' own bytes, so there is no loss and it takes a moment. The report says where each clip starts in the output (`from`), which is where to look for a seam with `frames`.

**What a copy cannot hide is refused, naming what differs**: the video or audio codec, **the decoder parameters** (two H.264 or HEVC files with the same codec name can have different profile, level or parameter sets, and a joined file can carry only the first clip's, so the others would decode as garbage: this was found by a review on two real encodes), the shown size, the rotation, the sample rate, the channel count, or sound in one and not in the other. Make them the same first (re-encode them with ffmpeg, whose concat filter does that). Clips from one phone with the same settings usually have the same parameters; a clip you cut with `trim` (by copy) joins the clips it came from; a `trim --exact` cut is re-encoded by the browser and usually has other parameters, so it is refused unless they happen to match.

**The seams.** Each clip starts where the longest track of the one before it ends, and its picture and sound keep their own offset to each other (a sound that begins 0.5 s after its picture still does, in every clip; one start per clip, not one per track, which is what kept them together over many joins). The encoder-delay packet of AAC (the one before time 0, which decodes to silence) is not copied into the middle of the file. If a clip's sound is much longer or shorter than its picture the report says so: the picture ends first and its last frame stays on screen while the sound goes on. Only the first picture and the first sound track of a clip are joined (a clip with two sound tracks says so). For clips with a picture the output is `.mp4`, `.mov`, `.webm` or `.mkv` (`.m4a` and `.mka` are for sound only). The output is made aside and moved into place when it worked: a refused join leaves no file and no new folder and never empties one that was there; an existing output needs `--force`; the output cannot be an input under another spelling of its name either (`A.MP4` for `a.mp4` on a disk that ignores case). Inputs are opened one at a time, so hundreds of clips are fine.

## audio

```sh
npx pixi-effects audio footage.mp4 -o sound.m4a
```

`audio <file> -o <out>`: the first sound track of a file as a file of its own, copied: the packets are the source's, nothing is re-encoded. The output type decides what can go in: AAC → `.m4a`, Opus or Vorbis → `.webm`, anything → `.mka`; a codec the type cannot hold is refused naming the codec and a type that can. A file with no sound is refused. Whether the first AAC packet (the encoder delay, before time 0, which no player plays) is kept depends on how the file was made: it was left out of a file from our renderer and kept in one from ffmpeg. If the sound began later than the picture in the source (a phone clip's often does), the report says so: the new file starts at 0, so that offset is gone. `sound` measures the result like any file.

## frames

```sh
npx pixi-effects frames footage.mp4 --at 0.5,50%,end --sheet -o looks
```

`frames <file> [--at <list>] [--size 480] [--sheet] [-o dir]`: a PNG of the frame at each time, named by time (`01-0.50s.png`), and with `--sheet` one **contact sheet** (`sheet.png`: every frame with its time under it) so a whole clip is one picture to look at. `--at` takes seconds (`3.5`), a percentage (`50%`), a frame (`f120`), `start`, `end` (the last frame) and `every:2s`, separated by commas (`--at every:2s,end`; with a space, quote the whole value: `--at "every 2s"`); the default is `0,25%,50%,75%,end`. At most 60 frames. `--size` is the width in pixels (default 480; a smaller video is not enlarged). A rotated video comes out the way up it is shown. A time past the end of the file is refused with the length of the file; a time before the first frame (a video that starts at 0.5 s, which `probe` says) gives the first frame; `end` and `%` are of the VIDEO, not of a longer sound. Pictures with the same names in an existing folder are replaced and nothing else in it is touched or removed.

The words are the ones `check --at` uses where they overlap (seconds, `%`, `f120`), so a time you read off one works in the other.

## sound

```sh
npx pixi-effects sound footage.mp4 --waveform -o sound-report
```

```
footage.mp4
  6.036 s · 48000 Hz · 2 ch
  loudness  -12.7 LUFS · true peak -10.4 dBTP · peak -11.9 dBFS · 0 sample(s) at full scale
  silences  none (nothing quieter than −60 dBFS for a second or more)
  level     -15 -15 -15 -15 -15 -15 dBFS rms, every 1 s
```

Integrated loudness (ITU-R BS.1770), true peak, the number of samples at full scale, silences with their times, the level over time in rows of `--window` seconds (default 1; the rows are in the text with one decimal and in `--json` with their times), the **loudest and quietest** rows with times, and a `reference` line: web video is typically −14 to −16 LUFS, so it says how many LU under (or over) −14 this is and the **headroom** (how many dB it can be raised before the true peak reaches −1 dBTP), and whether raising it to −14 would need a limiter (plain gain would clip). The `notes` are the library's advice and start late on purpose: **below −24 LUFS** (quiet), **above −9 LUFS** (loud), or less than 1 dB of headroom, so an empty note does not mean "fine for the web": read `reference`. `--waveform` writes `waveform.png`. These are the numbers `check` gives for a movie's mix, from the same code (`inspectSound`, see [the API reference](./api.md)), so a clip you measure here and the movie you check agree. Measured on one of our own exports, `sound` read the −14.8 LUFS that `check` had said (true peak −3.6 against −3.7: the file is AAC, `check` measured the mix before encoding); on a second, very quiet one it read −30 where `check` had said −29.7. The whole sound is decoded into memory, so it takes sounds up to 600 s; for longer, ffmpeg's `-af ebur128`. A last window shorter than half a window is not shown as a row (a file that ends 36 ms into a second would read −90 dBFS there).

## What it needs

- **No ffmpeg**, anywhere. A test runs every command with only `node` on `PATH`.
- **Chrome** for `frames`, `sound` and `trim --exact` (it decodes and re-encodes; `--chrome PATH` or `CHROME_PATH`); `probe` and `trim` by copy run without a browser. With no Chrome the three say so in one sentence.
- **Offline**: mediabunny comes from this package.
- Which codecs the browser can decode and encode depends on the machine. Headless Chrome on the author's Mac decoded and encoded H.264, HEVC, VP8, VP9, AV1, AAC and Opus; MP3 decodes only; no FLAC. A codec it cannot decode is named in the error.

## What was measured, and what was not

- A lossless cut of 5.6 s of a 3.9 MB file took 0.05–0.15 s in ffmpeg and 0.10–0.15 s with mediabunny in plain Node; a 5.6 s re-encode took 0.6–0.75 s in ffmpeg (the browser re-encode was not timed). **One file, one machine.**
- The files tried: H.264 + AAC made by our own renderer, the same as WebM (VP9 + Opus) and MOV, and a rotated and a one-track version of it; and **one real iPhone clip** (6.4 s, HEVC 1080×1920 stored 1920×1080 and turned 90°, variable frame rate around 59.94 fps, AAC, key frames every 0.93 s). On it: `probe` said all of that; `frames` came out upright and sharp in 2.4 s; `sound` read −41.8 LUFS (a quiet room) with its note; a copy cut took 0.2 s and kept HEVC; three cuts joined with `concat` (HEVC, 6.7 s) had their seams checked frame by frame, and `audio` gave a 127 KB `.m4a` that `sound` measured at the same −41.8 LUFS; `--exact` took 8 s and came out as H.264 (the note says so); the first and last frame of each of four cuts matched the source's frame at that time when put side by side. Not tried: other phones and cameras, ProRes sources, files over 1 GB, clips over a few minutes.
- A cut was checked in Chrome by playing it and reading the colour of every frame, and its packets were compared byte for byte with the source's. Not checked: QuickTime, VLC, a phone.