belt-trailer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ed9f2883e65374fed7efa5bddb143815548b666eeef890a4131c8a9fd2cdb0d7
+  data.tar.gz: db1be41d567472e59d903753807bef4931343bfacd16bb5d86759f19cbb21faf
+SHA512:
+  metadata.gz: cbcbcb3fca347996debac439fea243eaf69046f91194f3c63468f3066dfd5a27277a0f5007230dbfbd02a1888e3f40b3a5ae253b0b8ad51adf977c541f21c064
+  data.tar.gz: 8e950ded3ad819261b365ea9b2e2baa0db8e2187bf65e67325429c50d0090ae3a365c2f0530716516e509cd9e2c3126def5090dd27f71b8b2f852703c61ce3e9

data/AGENTS.md

@@ -0,0 +1,78 @@
+# AGENTS.md — belt-trailer
+
+For agents (and humans) working **on this gem**. To *use* it, read
+[README.md](README.md).
+
+## Layout
+
+```
+engine/                                  # the Node engine: no Belt in here
+├── bin/trailer.mjs                      # CLI: film | cut | check
+├── titles.html                          # the titles page (themed by the app's CSS)
+├── lib/
+│   ├── config.mjs                       # trailer.config.mjs + defaults; the app's Playwright
+│   ├── showcase.mjs                     # build/serve the showcase, canned API, the router
+│   ├── clock.mjs                        # freeze the page clock, step a frame
+│   ├── camera.mjs                       # crop camera: focus, punch, shake, cues, sounds
+│   ├── titles.mjs                       # film the titles page for a beat
+│   ├── sound.mjs                        # capture init script, live sounds, effect mix
+│   ├── film.mjs | cut.mjs | check.mjs   # the three commands
+│   ├── ffmpeg.mjs                       # ffmpeg/ffprobe helpers and report parsers
+│   └── args.mjs                         # the CLI's options
+└── test/                                # node:test for the pure parts
+lib/
+├── belt/trailer.rb                      # engine paths, requirements check
+├── belt/commands/trailer_command.rb     # belt trailer film|cut|check → node engine
+├── belt/generators/trailer_generator.rb # belt g trailer
+└── belt/trailer/templates/              # config, titles theme, showcase scaffold
+examples/posh-nosh/                      # Posh Nosh's trailer as a config
+skills/belt-trailer/                     # the skill for agents *using* the gem (npx skills add)
+```
+
+## Design rules
+
+- **The engine never learns about Belt or any one app.** Anything Posh Nosh
+  needed (its soundboard, `__say`, its music stand-ins) is expressed in its
+  config. If a second app needs something, add a config option, not a branch.
+- **The engine runs from the gem.** It loads Playwright from the app with
+  `createRequire(appDir/package.json)`. Don't add npm dependencies to the
+  engine; Node's standard library and ffmpeg cover it.
+- **Every rule in the README's "learned the hard way" list was a real bug.**
+  Don't undo one (the half-pixel scale, the cut-is-done rule, overlaying on
+  the clean clip, the silent first `amix` input, one measured gain) without
+  filming Posh Nosh before and after.
+- **Clips are exactly as long as the frames filmed.** Audio is trimmed to
+  the full-precision length and muxed with `-t`, never `-shortest`: an audio
+  track a fraction of a millisecond short drops the last video frame.
+
+## Keep the skill true
+
+`skills/belt-trailer/` is what agents making a trailer actually read
+(`belt trailer guide` prints it; `npx skills add stowzilla/belt-trailer`
+installs it). When you change a command, an option, the `play()` API or a
+default, update it in the same change, and keep every command in it runnable
+as written. It installs on its own, without the gem, so its links must stay
+inside its own directory (spec/belt/skill_spec.rb checks); refer to the gem's
+files as `<gem>/…`, which `belt trailer guide` fills in.
+
+## Verifying a change to the engine
+
+Unit tests cover the arithmetic. For anything that touches filming, film the
+Posh Nosh example against a posh_nosh checkout with the trailer showcase
+fixtures, and compare with the previous clips: the `.json` files should
+match, and the pictures should agree to encoder noise (PSNR well above
+40 dB):
+
+```bash
+cp examples/posh-nosh/trailer* ../posh_nosh/frontend/
+node engine/bin/trailer.mjs film --app ../posh_nosh/frontend --out /tmp/after
+ffmpeg -i /tmp/before/strike-wide.mp4 -i /tmp/after/strike-wide.mp4 -lavfi psnr -f null -
+```
+
+## Releasing
+
+Bump `lib/belt/trailer/version.rb` (and the CHANGELOG) and merge to `main`.
+`.github/workflows/auto-tag.yml` builds the gem, pushes it to RubyGems with
+the `RUBYGEMS_API_KEY` secret, tags `vX.Y.Z` and makes the GitHub release.
+It skips whatever is already done, so a failed run can be re-run from the
+Actions tab (`workflow_dispatch`).

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.0
+
+- The engine, split out of Posh Nosh's launch trailer (Fizzy #1818) and made
+  generic: a frame-stepped crop camera, a titles layer themed by the app,
+  captured sound effects, the cut and mix levelled to −14 LUFS, and a check
+  that passes or fails the cut. Configured per app by `trailer.config.mjs`.
+- `belt generate trailer`: the config, a titles theme, and a showcase for a
+  React + Vite frontend that has none.
+- `belt trailer film|cut|check`.
+- Beat clips and the cut are exactly as long as the frames filmed. Posh
+  Nosh's scripts trimmed the audio to the millisecond and muxed with
+  `-shortest`, which dropped a beat's last frame whenever rounding its length
+  to the millisecond made the audio shorter (Posh Nosh's `dragon` beat: 124
+  frames filmed, 123 in the clip).
+- `examples/posh-nosh/`: Posh Nosh's trailer as a config.
+- `skills/belt-trailer/`: a skill for the agents making a trailer
+  (storyboard, showcase and fixtures, beats, reviewing frames). Install it
+  with `npx skills add stowzilla/belt-trailer --skill belt-trailer`, or print
+  the copy in the gem with `belt trailer guide`; `belt generate trailer` writes `trailer-storyboard.md`
+  and points the app's `AGENTS.md` at the skill.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stowzilla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,223 @@
+# belt-trailer
+
+Films a launch trailer of a web app from the app itself: its real screens, a frame at a time, at 1080p and 30 fps, with a moving camera, titles in the app's own fonts and the sound effects the app plays as it's filmed. Cuts the shots together with music under them, levelled to −14 LUFS, and checks whether the result is fit to publish.
+
+Nothing is drawn or generated. Every frame is the app's own UI and every sound is one the app plays, so the trailer can't promise something the app doesn't do. Re-filming after a design change is one command and a few minutes.
+
+It came out of Posh Nosh's launch trailer (Fizzy #1818). [`examples/posh-nosh/`](examples/posh-nosh/) is that trailer's config.
+
+## For AI agents
+
+Most trailers will be made by an agent: writing the storyboard, the fixtures and the beats, then reviewing what it filmed. [`skills/belt-trailer/`](skills/belt-trailer/SKILL.md) is the skill for that (Agent Skills format), with references on the storyboard, the showcase and fixtures, scripting beats, and reviewing frames. Two ways to get it to an agent:
+
+- **Install it** into a project or for a user, with the [skills CLI](https://github.com/vercel-labs/skills):
+
+  ```bash
+  npx skills add stowzilla/belt-trailer --skill belt-trailer      # into this project (.claude/skills/ …)
+  npx skills add stowzilla/belt-trailer --skill belt-trailer -g   # for every project
+  ```
+
+  The repo is private for now, so this needs git access to it (an SSH key or `gh auth login`).
+- **Print it** from the installed gem: `belt trailer guide`. This copy always matches the gem's version. `belt generate trailer` also adds a pointer to it in the app's `AGENTS.md`.
+
+## Belt, or any website
+
+The engine ([`engine/`](engine/)) is plain Node and knows nothing about Belt. It needs a page Playwright can load and drive, and a `trailer.config.mjs`. The Belt part is a thin layer on top:
+
+- `belt generate trailer` scaffolds the config, a titles theme and a showcase for a React + Vite frontend.
+- `belt trailer film|cut|check` runs the engine on the frontend.
+
+The engine runs from the gem's directory and is never copied into the app. It loads the app's own Playwright from the frontend's `node_modules`.
+
+## Requirements
+
+- Node 20 or later
+- Playwright in the frontend: `npm install -D playwright && npx playwright install chromium`
+- ffmpeg and ffprobe, with `drawtext` (for the contact sheet)
+
+## Quick start (Belt)
+
+```ruby
+# Gemfile
+gem 'belt-trailer', git: 'git@github.com:stowzilla/belt-trailer.git'
+```
+
+```bash
+bundle install
+belt generate trailer --url myapp.com     # frontend/trailer.config.mjs, trailer-storyboard.md, trailer-titles.css, scripts/showcase/
+cd frontend && npm install -D playwright && npx playwright install chromium && cd ..
+belt trailer film --format wide           # frontend/tmp/trailer/<beat>-wide.mp4 …
+belt trailer cut --format wide            # frontend/tmp/trailer/trailer-wide.mp4
+belt trailer check --format wide          # PASS or FAIL, and trailer-wide-sheet.png
+```
+
+The starter films the Belt welcome page in two beats. From there it's yours: write the storyboard (`trailer-storyboard.md`), the fixtures it films, and the beats. `belt trailer guide` walks through each.
+
+## Any other site
+
+```bash
+node path/to/belt-trailer/engine/bin/trailer.mjs film --app path/to/site
+```
+
+`--app` is the directory with `trailer.config.mjs` and the `package.json` whose Playwright is used. The commands and options are the same as `belt trailer`'s.
+
+## Words
+
+- **Showcase.** The app's screens rendered from hand-written states (fixtures) with no backend. A screen is chosen by name (`?view=<fixture>`), and `window.__setView(name)` switches state without reloading, so the app's own components animate and play their sounds as they would on a real update. API calls are answered with canned JSON by Playwright route interception.
+- **Beat.** One shot of the storyboard, named by the app. `--only` takes those names. There are no built-in beat names.
+- **Format.** An output shape: `wide` (1920×1080, filmed from a 1280×720 page) and `tall` (1080×1920, from a 432×768 phone-sized page) by default.
+- **Story.** The fixtures every shot is built from: one session at later moments, so the same records appear in every shot.
+- **Mark.** A named moment a beat records for the cut, e.g. `hush` where the music stops.
+
+## Commands
+
+```
+belt trailer film  [--only a,b] [--format wide|tall|both] [--clean] [--keep-frames] [--sounds bundled]
+belt trailer cut   [--format …] [--music PLAN] [--sounds bundled]
+belt trailer check [--format …] [--music PLAN]
+belt trailer guide                       # the agent skill, with full paths
+```
+
+All take `--frontend NAME` (from `config/frontends.yml`; default `frontend/`), `--out DIR` and `--config FILE`.
+
+**film** films each beat into the output directory (default `<frontend>/tmp/trailer`):
+
+| File | |
+|---|---|
+| `<beat>-<format>.mp4` | H.264 with titles and the beat's effects |
+| `<beat>-<format>-clean.mp4` | The same without titles, for an editor (and for `check`) |
+| `<beat>-<format>.json` | The sounds the app played (time and file), the beat's marks |
+
+`--clean` deletes those beats' old clips, leftover frame directories and the cached live sounds first. `--sounds bundled` plays the app's bundled files rather than the live site's replacements.
+
+**cut** joins the beats in config order, lays every effect where the app played it (ringing on past its own beat) and the music by the plan, and levels the whole thing. Writes `trailer-<format>.mp4` and `trailer-<format>.json` (where each beat starts, and every audio file in the cut). `--music PLAN` cuts with a named plan from `music.plans` into `trailer-<format>-<PLAN>.mp4`.
+
+**check** passes or fails a cut, exiting 1 on a fail:
+
+- audio starts at 0 and lasts as long as the video (±0.05 s)
+- integrated loudness −14 LUFS ±1
+- true peak below −1 dBFS
+- at most 30 s (the App Store preview limit; `check.maxSeconds`)
+- every captured effect starts within one frame of where it was captured, measured on each beat's clean clip (a sound that starts while another is still ringing has no onset of its own, and is reported as masked)
+- no title on screen in the last 0.5 s of any beat (the titled clip against the clean one; a beat that ends on the end card is exempt)
+
+It also writes `trailer-<format>-sheet.png`, a contact sheet at 2 fps with timestamps, and lists every audio file in the cut, so the rights to each can be checked before publishing.
+
+## The config
+
+`trailer.config.mjs` in the frontend `export default`s an object. Paths are relative to the frontend.
+
+```js
+export default {
+  // Where the pages come from: a module that builds the showcase (it exports
+  // buildShowcase(), returning { distDir }), or a running site with { url }.
+  // A running site's data can change between takes, so shots aren't repeatable.
+  showcase: { build: './scripts/showcase/build.mjs', index: 'showcase.html', query: { sound: 1 } },
+
+  // Canned answers, first match wins; a key ending in * is a prefix. A value
+  // is JSON, or a function of the URL that returns it.
+  api: { '/api/matches': { matches: [] }, '/api/*': {} },
+
+  sounds: {
+    bundled: 'public',                    // where /sounds/x.mp3 lives on disk
+    // Optional: paths answered from the live site, files cached in tmp/trailer-sounds.
+    live: { origin: 'https://example.com', paths: ['/api/sounds', '/soundboard/'] },
+    ignore: ['/music-'],                  // URL patterns not captured (music)
+  },
+
+  // Set up every page: CSS to add, and an init script (runs before the app).
+  page: { css: '.chat { visibility: hidden; }', init: () => localStorage.setItem('sound', 'on') },
+  // unlock: async page => …,             // default: a key press unlocks Web Audio
+
+  titles: {
+    css: './trailer-titles.css',          // the app's fonts and colours
+    endCard: { logo: '/images/logo.png', lines: ['What it is', 'Free · No account needed'], url: 'example.com' },
+    leaveBefore: 0.8,                     // seconds a title leaves before its cut
+  },
+
+  music: {
+    level: 0.7,                           // under the effects; apps often play 0.5
+    fade: 1.5,                            // crossfade, seconds
+    tracks: { battle: 'public/sounds/theme.mp3', lobby: async ({ live }) => 'public/sounds/lobby.mp3' },
+    plan: { hook: 'battle', dragon: 'battle', end: 'lobby' },   // beat → track, or null
+    plans: { quiet: { hook: null, dragon: 'lobby', end: 'lobby' } },
+  },
+
+  formats: { wide: { page: [1280, 720], out: [1920, 1080] }, tall: { page: [432, 768], out: [1080, 1920] } },
+  fps: 30,
+  settle: 1500,                           // ms the page runs before a beat starts
+  check: { maxSeconds: 30 },
+
+  beats: [
+    { name: 'hook', view: 'battle-start', query: 'chat=on', css: '…', settle: 500,
+      play: async ({ page, cam, setView, drag, fire, ease, tall }) => { /* … */ } },
+  ],
+};
+```
+
+A beat's `play` gets:
+
+| | |
+|---|---|
+| `cam.hold(ms)` | Film for `ms` |
+| `cam.focus(selectors, { ms, pad, top, right, bottom, ease })` | Frame the union of the matching boxes over `ms` (0 cuts), with `pad` all round and room on one side for words, as fractions of its size, fitted to the format |
+| `cam.punch(selectors, opts)` | A fast focus (260 ms, ease out) |
+| `cam.look(rect, ms, ease)` | Frame a rect of the page |
+| `cam.shake(ms, px)` | Shake the frame, fading out |
+| `cam.move(from, to, ms)` | Move the pointer, filming as it goes |
+| `cam.title({ kicker, line, place })` | A title from this frame: `place` is `side`, `band`, `top`, `bottom` or `{ wide, tall }` |
+| `cam.untitle()`, `cam.endCard()` | Send the title out; bring the end card in |
+| `cam.mark(name)` | Note a moment for the cut (`hush` stops the music) |
+| `cam.boxOf(selectors)`, `cam.tall` | Where things are; whether the format is tall |
+| `setView(name)` | Switch the showcase to another fixture without reloading |
+| `drag(from, to, { ms, hold })` | Press `from` and carry it onto `to`, filming |
+| `fire(name, ...args)` | Call an app-defined trigger, `window[name](...args)`, on cue |
+| `ease` | `inOut`, `out`, `linear` |
+| `page` | The Playwright page |
+
+## The showcase's two hooks
+
+Behind query flags, so the showcase stays quiet for screenshots:
+
+- `?sound=1` mounts the app's own sound hooks, so it plays what it would.
+- An app-defined trigger on `window` (Posh Nosh: `window.__say(text, from)`) fires an event on cue rather than on a timer from page load. A beat calls it with `fire('__say', 'Hello', '1')`.
+
+## How it works
+
+**Filmed a frame at a time.** Headless Chromium's video recording and screencast both capture at CSS pixels and ignore `deviceScaleFactor`, so 1080p comes out blurry. Instead the page's clock is installed and paused (`pauseAt`, retried further ahead when a busy page has passed it). Before each frame, timers run forward one frame and every `document.getAnimations()` entry is paused at its time, or finished once past its end so its events fire.
+
+**The camera is a crop.** Each frame is `Page.captureScreenshot` over CDP with a clip and `scale = (outWidth + 0.5) / clipWidth` (without the half pixel Chromium rounds a pixel short). Chromium re-rasterises at that scale, so a 3× push is sharp, and the page is never transformed, so drags and hit-testing still work. A cut counts as done on the frame it's called, so a move straight after it starts from the cut.
+
+**Titles are a second page**, transparent and the size of the output ([`engine/titles.html`](engine/titles.html), themed by the app's CSS), stepped the same way, screenshotted with `omitBackground` and overlaid on the encoded clean clip, never on raw frames.
+
+**Sound is captured, not placed.** An init script tags each `Response.arrayBuffer` with its URL, carries the tag through `decodeAudioData` to the `AudioBuffer`, and records `AudioBufferSourceNode.start(when)` with its scheduled delay. Each frame the recorder drains the list and notes the frame. Chromium runs with `--autoplay-policy=no-user-gesture-required`, and a key press unlocks the app's audio as a first tap would.
+
+**The cut.** `amix` takes its timeline from its first input, so that's `anullsrc` for the whole length; every input is delayed and resampled from 0. The mix is rendered to 32-bit float WAV and then muxed. Each music track is brought to −16 LUFS with one measured gain; the trailer is brought to −14 LUFS with one measured gain and limited at 0.63 (about 4 dB of headroom for the AAC encode). `loudnorm`'s dynamic mode ducked the music after every hit and isn't used.
+
+## Rules learned the hard way
+
+**Pacing.** Each title stays up, fully landed, about 2 s. A moment the viewer has to follow (a dialog, a choice, its result) gets 2–3 s, with its title held until the result is on screen. Titles leave 0.8 s before their cut (built in).
+
+**Camera.** End a shot on the framing the next opens with. A push of more than about 1.5× takes at least 0.9 s with easing. Keep the pointer off anything with a hover state. Hide the app's own heading when a title replaces it. Frame an element after its entrance animation has finished, or its box is wrong.
+
+**Story.** Every shot is the same session at a later moment, built from one fixture function. Each state change gets a fixture with the data the server would really send: sounds come from the difference between two states, so a missing log line is a missing sound.
+
+**Words.** Where nothing important is, never on the subject or the controls. In the product's voice, short enough to read twice in 2 s.
+
+**Sound.** Music starts on the first frame (`cut` warns otherwise). Music sits higher under the effects than in the app. Check the source files: one of Posh Nosh's uploaded sounds was clipped in the file itself.
+
+## Before publishing
+
+- Rights to every piece of music and every sound in the cut, for advertising (`check` lists them).
+- The end card names only what is live and doesn't call paid content free.
+- Re-film after the last visual change.
+
+## Development
+
+```bash
+bundle exec rspec          # the Belt layer
+bundle exec rubocop
+cd engine && npm test      # the engine's pure parts (node:test)
+```
+
+See [AGENTS.md](AGENTS.md).

data/engine/bin/trailer.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// The engine's command line. Belt runs it as `belt trailer …`; any other site
+// can run it directly with node.
+//
+//   trailer.mjs film  [--app DIR] [--only beat,beat] [--format wide|tall|both] [--clean] [--keep-frames] [--sounds bundled]
+//   trailer.mjs cut   [--app DIR] [--format …] [--music PLAN] [--sounds bundled]
+//   trailer.mjs check [--app DIR] [--format …] [--music PLAN]
+//
+// --app is the directory holding trailer.config.mjs and the package.json
+// whose Playwright is used (default: the current directory). --config picks
+// another config file there; --out another output directory.
+import { film } from '../lib/film.mjs';
+import { cut } from '../lib/cut.mjs';
+import { check } from '../lib/check.mjs';
+import { parse } from '../lib/args.mjs';
+
+const USAGE = `Usage: trailer.mjs <film|cut|check> [options]
+
+  film   Film each beat: <beat>-<format>.mp4, -clean.mp4 (no titles) and .json (sounds, marks)
+  cut    Join the beats with their effects and the music: trailer-<format>.mp4
+  check  Measure a cut (sync, loudness, peak, length, titles) and write a contact sheet
+
+Options:
+  --app DIR            The app's frontend directory (default: .)
+  --config FILE        Config file in it (default: trailer.config.mjs)
+  --out DIR            Output directory (default: the config's out, tmp/trailer)
+  --only a,b           film: just these beats
+  --format NAME        wide, tall, both (default) or a list
+  --clean              film: delete those beats' old clips, leftover frames and cached live sounds first
+  --keep-frames        film: keep the frame images
+  --music PLAN         cut/check: a named plan from music.plans (default: music.plan)
+  --sounds bundled     film/cut: the app's bundled sound files, not the live site's
+`;
+
+try {
+  const { command, opts } = parse(process.argv.slice(2));
+  const app = opts.app || process.cwd();
+  if (command === 'film') await film(app, opts);
+  else if (command === 'cut') await cut(app, opts);
+  else if (command === 'check') process.exitCode = (await check(app, opts)) ? 0 : 1;
+  else { process.stdout.write(USAGE); process.exitCode = command && !['help', '--help', '-h'].includes(command) ? 1 : 0; }
+} catch (error) {
+  console.error(`Error: ${process.env.TRAILER_DEBUG ? error.stack : error.message}`);
+  process.exitCode = 1;
+}

data/engine/lib/args.mjs

@@ -0,0 +1,18 @@
+// The command line's options, as the engine's functions take them.
+export function parse(argv) {
+  const [command, ...rest] = argv;
+  const opts = {};
+  const flags = { '--clean': 'clean', '--keep-frames': 'keepFrames' };
+  const values = { '--app': 'app', '--config': 'config', '--out': 'out', '--only': 'only', '--format': 'format', '--music': 'music', '--sounds': 'sounds' };
+  for (let i = 0; i < rest.length; i += 1) {
+    const [flag, inline] = rest[i].split(/=(.*)/s);
+    if (flags[flag]) { opts[flags[flag]] = true; continue; }
+    if (!values[flag]) throw new Error(`unknown option ${rest[i]}`);
+    const value = inline ?? rest[(i += 1)];
+    if (value == null) throw new Error(`${flag} needs a value`);
+    opts[values[flag]] = value;
+  }
+  if (opts.only) opts.only = opts.only.split(',').map(s => s.trim()).filter(Boolean);
+  if (opts.sounds && opts.sounds !== 'bundled' && opts.sounds !== 'live') throw new Error('--sounds is bundled or live');
+  return { command, opts };
+}

data/engine/lib/camera.mjs

@@ -0,0 +1,140 @@
+// The camera is a crop. Each frame Chromium paints just the part of the page
+// the camera is looking at (Page.captureScreenshot over CDP with a clip and a
+// scale), at the size of the finished video. Chromium re-rasterises at that
+// scale, so a 3× push-in stays sharp, and the page itself is never
+// transformed, so drags and hit-testing still work where the pointer is.
+import fs from 'node:fs';
+import path from 'node:path';
+import { step } from './clock.mjs';
+import { inOut, out, lerp } from './ease.mjs';
+
+// Grows a rect to the frame's aspect around its centre, kept inside the page.
+export function fitRect({ x, y, w, h }, page) {
+  const aspect = page.width / page.height;
+  const cx = x + w / 2;
+  const cy = y + h / 2;
+  if (w / h > aspect) h = w / aspect; else w = h * aspect;
+  if (w > page.width) { w = page.width; h = page.height; }
+  return {
+    x: Math.min(Math.max(cx - w / 2, 0), page.width - w),
+    y: Math.min(Math.max(cy - h / 2, 0), page.height - h),
+    w,
+    h,
+  };
+}
+
+// A rect around `box` with `pad` (a fraction of its size) all round, and room
+// on one side for words: `top`, `right` and `bottom` are fractions of its
+// size to add there.
+export function roomAround(box, { pad = 0.08, top = 0, right = 0, bottom = 0 } = {}) {
+  const px = box.w * pad;
+  const py = box.h * pad;
+  const r = { x: box.x - px, y: box.y - py, w: box.w + px * 2, h: box.h + py * 2 };
+  r.y -= r.h * top;
+  r.h += r.h * (top + bottom);
+  r.w += r.w * right;
+  return r;
+}
+
+// A camera on one page, filming into `dir` as numbered JPEGs. Every `hold`,
+// `move` and `shoot` adds frames; `look`, `focus` and `punch` move the frame;
+// `title`, `untitle` and `endCard` are cues for the titles page.
+export async function camera(page, { fps, format, dir }) {
+  const cdp = await page.context().newCDPSession(page);
+  const frameMs = 1000 / fps;
+  const [W, H] = format.page;
+  const size = { width: W, height: H };
+  let now = 0;
+  let count = 0;
+  let pan = { from: { x: 0, y: 0, w: W, h: H }, to: { x: 0, y: 0, w: W, h: H }, at: 0, ms: 1, ease: inOut };
+  let shaking = null;
+  const cues = [];
+  const sounds = [];
+  const marks = {};
+
+  const where = () => {
+    // A cut (ms 1) is already there, even on the frame it was called, so a
+    // move that follows it on the same frame starts from where it cut to.
+    // Before this, a shot could flash the wide view for a frame.
+    const k = pan.ms <= 1 ? 1 : Math.min(1, (now - pan.at) / pan.ms);
+    const e = pan.ease(k);
+    const { from, to } = pan;
+    return { x: lerp(from.x, to.x, e), y: lerp(from.y, to.y, e), w: lerp(from.w, to.w, e), h: lerp(from.h, to.h, e) };
+  };
+
+  const shoot = async () => {
+    now += frameMs;
+    await step(page, now, frameMs);
+    const v = where();
+    if (shaking && now < shaking.until) {
+      const fade = 1 - (now - shaking.at) / (shaking.until - shaking.at);
+      v.x = Math.min(Math.max(v.x + Math.sin(now * 0.09) * shaking.px * fade, 0), W - v.w);
+      v.y = Math.min(Math.max(v.y + Math.cos(now * 0.13) * shaking.px * fade, 0), H - v.h);
+    }
+    // Half a pixel over, or Chromium rounds the picture a pixel short.
+    const scale = (format.out[0] + 0.5) / v.w;
+    const { data } = await cdp.send('Page.captureScreenshot', {
+      format: 'jpeg', quality: 94, clip: { x: v.x, y: v.y, width: v.w, height: v.h, scale },
+    });
+    fs.writeFileSync(path.join(dir, `${String(count).padStart(5, '0')}.jpg`), Buffer.from(data, 'base64'));
+    // What the app started playing this frame (see listen() in sound.mjs).
+    for (const { url, delay } of await page.evaluate(() => (window.__heard || []).splice(0))) {
+      sounds.push({ at: count / fps + delay, url });
+    }
+    count += 1;
+  };
+
+  // The union of every box matching these selectors, or null.
+  const boxOf = async selectors => {
+    const boxes = [];
+    for (const selector of [selectors].flat()) {
+      for (const el of await page.locator(selector).all()) {
+        const b = await el.boundingBox();
+        if (b && b.width && b.height) boxes.push(b);
+      }
+    }
+    if (!boxes.length) return null;
+    const x = Math.min(...boxes.map(b => b.x));
+    const y = Math.min(...boxes.map(b => b.y));
+    return { x, y, w: Math.max(...boxes.map(b => b.x + b.width)) - x, h: Math.max(...boxes.map(b => b.y + b.height)) - y };
+  };
+
+  const cam = {
+    shoot,
+    async hold(ms) { for (let t = 0; t < ms; t += frameMs) await shoot(); },
+    // The pointer from `from` to `to` over `ms`, a frame per step.
+    async move(from, to, ms) {
+      const steps = Math.max(1, Math.round(ms / frameMs));
+      for (let i = 1; i <= steps; i += 1) {
+        const e = inOut(i / steps);
+        await page.mouse.move(lerp(from.x, to.x, e), lerp(from.y, to.y, e));
+        await shoot();
+      }
+    },
+    // Frame a rect of the page over `ms` (0 cuts).
+    look(rect, ms = 0, ease = inOut) {
+      pan = { from: where(), to: fitRect(rect, size), at: now, ms: Math.max(ms, 1), ease };
+    },
+    // Frame whatever matches `selectors`; see roomAround for the options.
+    // Frame an element after its entrance animation has finished, or its box
+    // is the wrong size.
+    async focus(selectors, { ms = 0, ease = inOut, ...room } = {}) {
+      const box = await boxOf(selectors);
+      if (box) cam.look(roomAround(box, room), ms, ease);
+    },
+    punch(selectors, opts) { return cam.focus(selectors, { ms: 260, ease: out, ...opts }); },
+    shake(ms, px) { shaking = { at: now, until: now + ms, px }; },
+    title(title) { cues.push({ frame: count, show: title }); },
+    untitle() { cues.push({ frame: count, hide: true }); },
+    endCard() { cues.push({ frame: count, end: true }); },
+    // A moment the cut needs to know about, e.g. 'hush' where the music stops.
+    mark(name) { marks[name] = Number((count / fps).toFixed(3)); },
+    boxOf,
+    get frames() { return count; },
+    tall: H > W,
+    cues,
+    sounds,
+    marks,
+  };
+  return cam;
+}