belt-trailer 0.1.0

data/engine/lib/check.mjs

@@ -0,0 +1,134 @@
+// Passes or fails a cut by measurement, and writes a contact sheet with
+// timestamps for a person to look at. Each format's trailer must:
+//   - have audio from 0 that lasts as long as the video (±0.05 s)
+//   - sit at the target loudness (−14 LUFS ±1) with true peak below −1 dBFS
+//   - be no longer than the limit (30 s, an App Store preview)
+// and each beat's clips must:
+//   - sound every captured effect within one frame of the frame it was
+//     captured on (measured on the clean clip, which has no music)
+//   - have no title left on screen in the last 0.5 s
+import fs from 'node:fs';
+import path from 'node:path';
+import { ffmpeg, loudness, measure, onsets, probe } from './ffmpeg.mjs';
+import { loadConfig, outDir, pickFormats } from './config.mjs';
+
+const TOLERANCE = 0.05;
+const CLEAR_AT_END = 0.5;
+// Titled and clean clips differ only by the titles and the second encode;
+// above this PSNR (dB) over the last half second, no title is on screen.
+const SAME_PICTURE_DB = 38;
+
+// Stretches of sound in a clip, from silencedetect's report.
+export function soundSpans(report, length) {
+  const starts = [...report.matchAll(/silence_start: (-?[\d.]+)/g)].map(m => Number(m[1]));
+  const ends = [...report.matchAll(/silence_end: (-?[\d.]+)/g)].map(m => Number(m[1]));
+  const spans = [];
+  let from = starts.length && starts[0] <= 0.001 ? null : 0;
+  for (const event of [...starts.map(at => ({ at, start: true })), ...ends.map(at => ({ at, start: false }))].sort((a, b) => a.at - b.at)) {
+    if (event.start && from != null) { spans.push([from, event.at]); from = null; }
+    if (!event.start) from = event.at;
+  }
+  if (from != null) spans.push([from, length]);
+  return spans;
+}
+
+// Whether each captured sound starts in the clip where the JSON says, give
+// or take a frame. The expected start is the capture time plus the file's own
+// lead-in silence. A sound that starts while another is still ringing has no
+// onset of its own to find, and is counted as masked rather than failed.
+export function matchSounds(sounds, spans, frame) {
+  return sounds.map(s => {
+    if (s.lead == null) return { ...s, result: 'silent' };
+    const expected = s.at + s.lead;
+    const hit = spans.find(([from]) => Math.abs(from - expected) <= frame + 1e-3);
+    if (hit) return { ...s, expected, found: hit[0], result: 'ok' };
+    const inside = spans.find(([from, to]) => from < expected - frame && to > expected);
+    if (inside) return { ...s, expected, result: 'masked' };
+    const nearest = spans.map(([from]) => from).sort((a, b) => Math.abs(a - expected) - Math.abs(b - expected))[0];
+    return { ...s, expected, found: nearest, result: 'off' };
+  });
+}
+
+function contactSheet(video, seconds, format, out) {
+  const tall = format.out[1] > format.out[0];
+  const columns = tall ? 10 : 8;
+  const rows = Math.max(1, Math.ceil((seconds * 2) / columns));
+  ffmpeg(['-i', video, '-vf',
+    `fps=2,scale=${tall ? 160 : 240}:-2,drawtext=text='%{pts\\:hms}':x=4:y=4:fontsize=16:fontcolor=yellow:box=1:boxcolor=black@0.5,tile=${columns}x${rows}`,
+    '-frames:v', '1', '-update', '1', out]);
+}
+
+export async function check(appDir, opts = {}) {
+  const config = await loadConfig(appDir, opts.config);
+  const dir = outDir(config, opts.out);
+  const frame = 1 / config.fps;
+  const leadCache = new Map();
+  const leadOf = file => {
+    if (!leadCache.has(file)) leadCache.set(file, fs.existsSync(file) ? (onsets(file)[0] ?? null) : null);
+    return leadCache.get(file);
+  };
+  let pass = true;
+  const line = (ok, text) => { if (ok === false) pass = false; console.log(`  ${ok === false ? '✗' : ok === true ? '✓' : '·'} ${text}`); };
+
+  for (const format of pickFormats(config, opts.format)) {
+    const suffix = opts.music && opts.music !== 'default' ? `-${opts.music}` : '';
+    const video = path.join(dir, `trailer-${format.name}${suffix}.mp4`);
+    console.log(`\n${path.relative(process.cwd(), video)}`);
+    if (!fs.existsSync(video)) { line(false, `missing: run belt trailer cut --format ${format.name}`); continue; }
+
+    const { streams, format: container } = probe(video);
+    const v = streams.find(s => s.codec_type === 'video');
+    const a = streams.find(s => s.codec_type === 'audio');
+    const length = Number(v?.duration ?? container.duration);
+    if (!a) line(false, 'no audio');
+    else {
+      const start = Number(a.start_time);
+      line(Math.abs(start) <= TOLERANCE, `audio starts at ${start.toFixed(3)} s (0 ±${TOLERANCE})`);
+      line(Math.abs(Number(a.duration) - length) <= TOLERANCE, `audio ${Number(a.duration).toFixed(3)} s, video ${length.toFixed(3)} s (±${TOLERANCE})`);
+    }
+    const { integrated, truePeak } = loudness(video);
+    const { loudness: target, tolerance, truePeak: ceiling, maxSeconds } = config.check;
+    line(Math.abs(integrated - target) <= tolerance, `loudness ${integrated} LUFS (${target} ±${tolerance})`);
+    line(truePeak < ceiling, `true peak ${truePeak} dBFS (below ${ceiling})`);
+    line(length <= maxSeconds + frame / 2, `${length.toFixed(2)} s long (at most ${maxSeconds})`);
+
+    for (const { name } of config.beats) {
+      const meta = path.join(dir, `${name}-${format.name}.json`);
+      const clean = path.join(dir, `${name}-${format.name}-clean.mp4`);
+      const titled = path.join(dir, `${name}-${format.name}.mp4`);
+      if (!fs.existsSync(meta) || !fs.existsSync(clean)) { line(false, `${name}: clips missing`); continue; }
+      const beat = JSON.parse(fs.readFileSync(meta, 'utf8'));
+
+      const report = measure(['-i', clean, '-af', 'highpass=f=200,silencedetect=n=-40dB:d=0.05']);
+      const sounds = beat.sounds.map(s => ({ ...s, lead: leadOf(path.resolve(config.appDir, s.file)) }));
+      const matched = matchSounds(sounds, soundSpans(report, beat.seconds), frame);
+      const off = matched.filter(m => m.result === 'off');
+      const masked = matched.filter(m => m.result === 'masked').length;
+      const counts = `${matched.filter(m => m.result === 'ok').length}/${matched.length} on their frame${masked ? `, ${masked} under another sound` : ''}`;
+      line(off.length === 0, `${name}: effects ${counts}`);
+      for (const m of off) {
+        console.log(`      ${m.file} expected at ${m.expected.toFixed(3)} s, nearest onset ${m.found == null ? 'none' : `${m.found.toFixed(3)} s`}`);
+      }
+
+      if (beat.endCard) line(null, `${name}: ends on the end card`);
+      else if (fs.existsSync(titled)) {
+        const from = Math.max(0, beat.seconds - CLEAR_AT_END);
+        const psnr = measure(['-ss', String(from), '-i', titled, '-ss', String(from), '-i', clean, '-lavfi', '[0:v][1:v]psnr']);
+        const avg = psnr.match(/average:(\S+)/)?.[1];
+        const db = avg === 'inf' ? Infinity : Number(avg);
+        line(db >= SAME_PICTURE_DB, `${name}: no title in the last ${CLEAR_AT_END} s (PSNR ${avg} dB against the clean clip)`);
+      }
+    }
+
+    const sheet = video.replace(/\.mp4$/, '-sheet.png');
+    contactSheet(video, length, format, sheet);
+    console.log(`  contact sheet: ${path.relative(process.cwd(), sheet)}`);
+    const manifest = video.replace(/\.mp4$/, '.json');
+    if (fs.existsSync(manifest)) {
+      const files = [...new Set(JSON.parse(fs.readFileSync(manifest, 'utf8')).sources.map(s => `${s.kind}: ${s.file}`))].sort();
+      console.log(`  audio in the cut (check the rights to each before publishing):\n${files.map(f => `    ${f}`).join('\n') || '    none'}`);
+    }
+  }
+  console.log(pass ? '\nPASS' : '\nFAIL');
+  return pass;
+}

data/engine/lib/clock.mjs

@@ -0,0 +1,38 @@
+// The page's clock, stopped, and moved on a frame at a time.
+//
+// Headless Chromium's recordVideo and its CDP screencast both capture at CSS
+// pixels and ignore deviceScaleFactor, so 1080p comes out blurry. Instead the
+// page's clock is installed and paused, and before each frame every timer and
+// every animation is moved on by exactly one frame, so a clip runs at the
+// app's real speed however long a frame takes to capture.
+
+// Stops the page's installed clock, which runs at wall speed until paused.
+// The pause has to be set a little ahead of the page's time, and a busy page
+// can run past it before the call lands ("Cannot fast-forward to the past"),
+// so it tries again further ahead.
+export async function freeze(page) {
+  for (let ahead = 250; ; ahead *= 2) {
+    try {
+      await page.clock.pauseAt(await page.evaluate(() => Date.now()) + ahead);
+      return;
+    } catch (error) {
+      if (ahead > 8000 || !/past/.test(error.message)) throw error;
+    }
+  }
+}
+
+// Moves every timer and animation on the page to `now` ms of filming. Each
+// animation keeps the time it was first seen at; one past its end is
+// finished, so its animationend events fire.
+export async function step(page, now, frameMs) {
+  await page.clock.runFor(frameMs);
+  await page.evaluate(t => {
+    const seen = (window.__filmed ||= new WeakMap());
+    for (const a of document.getAnimations()) {
+      if (!seen.has(a)) seen.set(a, t - (a.currentTime ?? 0));
+      const at = t - seen.get(a);
+      if (at >= a.effect.getComputedTiming().endTime) a.finish();
+      else { a.pause(); a.currentTime = at; }
+    }
+  }, now);
+}

data/engine/lib/config.mjs

@@ -0,0 +1,97 @@
+// An app's trailer.config.mjs, with the defaults filled in. Nothing here
+// knows about Belt: the app is a directory with a package.json (for its own
+// Playwright) and a config file.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+export const DEFAULTS = {
+  fps: 30,
+  out: 'tmp/trailer',
+  // Wide is YouTube, store pages and the site; tall is Shorts, Reels and
+  // TikTok, laid out as the app is on a phone.
+  formats: {
+    wide: { page: [1280, 720], out: [1920, 1080] },
+    tall: { page: [432, 768], out: [1080, 1920] },
+  },
+  // How long the page's own clock runs before a beat starts filming (fonts,
+  // art, entrance animations), and how long the app gets to load its sounds
+  // once audio is unlocked.
+  settle: 1500,
+  soundLoad: 1500,
+  titles: { css: null, endCard: null, leaveBefore: 0.8 },
+  sounds: { bundled: 'public', live: null, ignore: [], cache: 'tmp/trailer-sounds' },
+  music: { level: 0.7, fade: 1.5, loudness: -16, plan: {}, plans: {}, tracks: {} },
+  mix: { loudness: -14, limit: 0.63 },
+  check: { maxSeconds: 30, loudness: -14, tolerance: 1, truePeak: -1 },
+};
+
+// Loads `file` (relative to `appDir`) and fills in the defaults.
+export async function loadConfig(appDir, file = 'trailer.config.mjs') {
+  const full = path.resolve(appDir, file);
+  if (!fs.existsSync(full)) throw new Error(`No ${path.relative(process.cwd(), full)}: run \`belt generate trailer\` first`);
+  const { default: raw } = await import(pathToFileURL(full).href);
+  return normalize(raw, appDir);
+}
+
+export function normalize(raw, appDir) {
+  if (!raw || typeof raw !== 'object') throw new Error('trailer.config.mjs must `export default` an object');
+  const config = {
+    ...DEFAULTS,
+    ...raw,
+    appDir: path.resolve(appDir),
+    formats: raw.formats || DEFAULTS.formats,
+    titles: { ...DEFAULTS.titles, ...raw.titles },
+    sounds: { ...DEFAULTS.sounds, ...raw.sounds },
+    music: { ...DEFAULTS.music, ...raw.music },
+    mix: { ...DEFAULTS.mix, ...raw.mix },
+    check: { ...DEFAULTS.check, ...raw.check },
+  };
+  if (!config.showcase || !(config.showcase.build || config.showcase.url)) {
+    throw new Error('trailer.config.mjs needs showcase: { build } (a module that builds the showcase) or showcase: { url }');
+  }
+  if (!Array.isArray(config.beats) || !config.beats.length) throw new Error('trailer.config.mjs has no beats');
+  const names = new Set();
+  for (const beat of config.beats) {
+    if (!beat.name || typeof beat.play !== 'function') throw new Error('every beat needs a name and a play function');
+    if (names.has(beat.name)) throw new Error(`two beats are called ${beat.name}`);
+    names.add(beat.name);
+  }
+  return config;
+}
+
+// The formats asked for: 'both' (every configured format), one name, or a
+// comma-separated list.
+export function pickFormats(config, wanted = 'both') {
+  const all = Object.entries(config.formats).map(([name, f]) => ({ name, ...f }));
+  if (!wanted || wanted === 'both' || wanted === 'all') return all;
+  const names = wanted.split(',');
+  const unknown = names.filter(n => !config.formats[n]);
+  if (unknown.length) throw new Error(`no format called ${unknown.join(', ')} (have ${Object.keys(config.formats).join(', ')})`);
+  return all.filter(f => names.includes(f.name));
+}
+
+// The beats asked for with --only, in storyboard order.
+export function pickBeats(config, only) {
+  if (!only) return config.beats;
+  const unknown = only.filter(n => !config.beats.some(b => b.name === n));
+  if (unknown.length) throw new Error(`no beat called ${unknown.join(', ')} (have ${config.beats.map(b => b.name).join(', ')})`);
+  return config.beats.filter(b => only.includes(b.name));
+}
+
+// A module from the app's own node_modules (its Playwright, its Vite), so the
+// engine runs from the gem's directory and is never copied into the app.
+export function requireFromApp(appDir, name) {
+  const require = createRequire(path.join(appDir, 'package.json'));
+  try {
+    return require(name);
+  } catch (error) {
+    if (error.code === 'MODULE_NOT_FOUND') {
+      throw new Error(`${name} isn't installed in ${appDir}: npm install -D ${name}${name === 'playwright' ? ' && npx playwright install chromium' : ''}`);
+    }
+    throw error;
+  }
+}
+
+export const outDir = (config, override) => path.resolve(config.appDir, override || config.out);

data/engine/lib/cut.mjs

@@ -0,0 +1,169 @@
+// Joins the filmed beats in storyboard order and lays the sound under them:
+// every effect where the app played it, ringing on past its own beat, and the
+// music by the plan. Writes trailer-<format>.mp4 and trailer-<format>.json
+// (where each beat starts, and every audio file in the cut).
+import fs from 'node:fs';
+import path from 'node:path';
+import { ffmpeg, loudness } from './ffmpeg.mjs';
+import { loadConfig, outDir, pickFormats } from './config.mjs';
+import { liveSounds } from './sound.mjs';
+
+// Runs of beats under the same music track. A beat's 'hush' mark stops its
+// music there (the moment of a win, say), and the rest of that beat is silent.
+export function planRuns(beats) {
+  const runs = [];
+  for (const beat of beats) {
+    const last = runs[runs.length - 1];
+    const end = beat.start + (beat.hush ?? beat.seconds);
+    if (last && last.track === beat.track && !last.hushed) last.end = end;
+    else runs.push({ track: beat.track, start: beat.start, end });
+    if (beat.hush != null) {
+      runs[runs.length - 1].hushed = true;
+      runs.push({ track: null, start: end, end: beat.start + beat.seconds });
+    }
+  }
+  return runs;
+}
+
+// How one music run sits in the mix, in seconds. From one track to the next
+// the crossfade ends on the cut, so the new track is all there when its beat
+// lands; out of silence it comes in quickly, on the cut. Into the next track
+// it fades out over the crossfade before the cut; into silence it fades after
+// it; at the end of the trailer, over the last two seconds.
+export function runEnvelope(runs, i, total, fade) {
+  const run = runs[i];
+  const fromMusic = Boolean(runs[i - 1]?.track);
+  const intoMusic = Boolean(runs[i + 1]?.track);
+  const begin = fromMusic ? Math.max(run.start - fade, 0) : run.start;
+  const last = run.end >= total - 1e-6;
+  return {
+    begin,
+    fadeIn: fromMusic ? run.start - begin : 0.3,
+    stop: last ? total : intoMusic ? run.end : run.end + fade,
+    fadeOut: last ? 2 : fade,
+    outAt: Math.max((intoMusic ? run.end - fade : last ? total - 2 : run.end) - begin, 0),
+  };
+}
+
+// The music plan to cut with: the default `music.plan`, or a named one from
+// `music.plans`.
+export function pickPlan(config, name) {
+  if (!name || name === 'default') return config.music.plan;
+  const plan = config.music.plans?.[name];
+  if (!plan) throw new Error(`no music plan called ${name} (have default${Object.keys(config.music.plans || {}).map(n => `, ${n}`).join('')})`);
+  return plan;
+}
+
+// The file a track plays: a path in the app, or a function given the live
+// sounds (or null) that returns one.
+async function trackFile(config, live, name) {
+  const track = config.music.tracks[name];
+  if (!track) throw new Error(`the music plan names a track called ${name}, but music.tracks has no ${name}`);
+  const file = typeof track === 'function' ? await track({ live }) : track;
+  return path.resolve(config.appDir, file);
+}
+
+export async function cut(appDir, opts = {}) {
+  const config = await loadConfig(appDir, opts.config);
+  const dir = outDir(config, opts.out);
+  const plan = pickPlan(config, opts.music);
+  const live = liveSounds(config, { bundled: opts.sounds === 'bundled' });
+  const { fade, level } = config.music;
+  const written = [];
+
+  for (const format of pickFormats(config, opts.format)) {
+    let t = 0;
+    const beats = config.beats.map(({ name }) => {
+      const file = path.join(dir, `${name}-${format.name}.mp4`);
+      const meta = path.join(dir, `${name}-${format.name}.json`);
+      if (!fs.existsSync(file) || !fs.existsSync(meta)) {
+        throw new Error(`${path.relative(process.cwd(), file)} is missing: film it first (belt trailer film --only ${name} --format ${format.name})`);
+      }
+      const { seconds, sounds, marks = {} } = JSON.parse(fs.readFileSync(meta, 'utf8'));
+      const beat = { name, track: plan[name] ?? null, file, start: t, seconds, sounds, hush: marks.hush };
+      t += seconds;
+      return beat;
+    });
+    const total = t;
+    const runs = planRuns(beats);
+    if (!runs[0].track) console.warn(`  ! no music under ${beats[0].name}: a silent cold open reads as a broken video`);
+
+    const inputs = [];
+    const parts = [];
+    const sources = [];
+    // Input 0 is the video; sound n is input n + 1.
+    const add = file => { inputs.push(file); return inputs.length; };
+    const ms = s => Math.round(s * 1000);
+
+    for (const [i, run] of runs.entries()) {
+      if (!run.track) continue;
+      const file = await trackFile(config, live, run.track);
+      const n = add(file);
+      sources.push({ kind: 'music', track: run.track, file: path.relative(config.appDir, file), at: Number(run.start.toFixed(3)) });
+      const e = runEnvelope(runs, i, total, fade);
+      // Each track brought to the same loudness by one measured gain, so the
+      // tracks sit level with each other; a leveller working as it goes
+      // would duck them after every hit.
+      const gain = config.music.loudness - (loudness(file).integrated ?? config.music.loudness);
+      parts.push(`[${n}:a]aformat=sample_rates=48000:channel_layouts=stereo,volume=${gain.toFixed(2)}dB,`
+        + `atrim=0:${(e.stop - e.begin).toFixed(3)},asetpts=PTS-STARTPTS,afade=t=in:d=${e.fadeIn.toFixed(3)},`
+        + `afade=t=out:st=${e.outAt.toFixed(3)}:d=${e.fadeOut},volume=${level},`
+        + `adelay=${ms(e.begin)}|${ms(e.begin)},aresample=async=1:first_pts=0[m${n}]`);
+    }
+
+    for (const beat of beats) {
+      for (const sound of beat.sounds) {
+        const file = path.resolve(config.appDir, sound.file);
+        if (!fs.existsSync(file)) { console.warn(`  ! ${sound.file} (${beat.name}) isn't on disk; left out`); continue; }
+        const n = add(file);
+        const at = ms(beat.start + sound.at);
+        sources.push({ kind: 'effect', beat: beat.name, file: sound.file, at: Number((beat.start + sound.at).toFixed(3)) });
+        parts.push(`[${n}:a]aformat=sample_rates=48000:channel_layouts=stereo,adelay=${at}|${at},aresample=async=1:first_pts=0[m${n}]`);
+      }
+    }
+
+    const work = fs.mkdtempSync(path.join(dir, '.cut-'));
+    try {
+      const list = path.join(work, 'list.txt');
+      fs.writeFileSync(list, beats.map(b => `file '${b.file.replace(/'/g, "'\\''")}'`).join('\n'));
+      const video = path.join(work, 'video.mp4');
+      ffmpeg(['-f', 'concat', '-safe', '0', '-i', list, '-an', '-c', 'copy', video]);
+
+      // amix takes its timeline from its first input, so that is silence
+      // from 0 for the whole trailer: with music first, everything before
+      // the music came in was dropped and the rest landed late. Each input
+      // is delayed and resampled from 0, the mix rendered to 32-bit float
+      // WAV (no start time to drift, and stacked sounds over full scale
+      // aren't clipped before the limiter), and then muxed.
+      const labels = parts.map(p => p.match(/\[m\d+\]$/)[0]).join('');
+      const anchor = `anullsrc=r=48000:cl=stereo,atrim=0:${total.toFixed(6)}[anchor]`;
+      const mix = `[anchor]${labels}amix=inputs=${parts.length + 1}:normalize=0:duration=first[mix]`;
+      const raw = path.join(work, 'raw.wav');
+      ffmpeg(['-i', video, ...inputs.flatMap(file => ['-i', file]),
+        '-filter_complex', [anchor, ...parts, mix].join(';'), '-map', '[mix]', '-c:a', 'pcm_f32le', raw]);
+      // Levelled with one gain for the whole trailer, measured first:
+      // loudnorm's dynamic mode turned the music down for seconds after
+      // every loud hit. The limiter holds peaks about 4 dB down, room for
+      // the AAC encode to overshoot on a harsh sound.
+      const measured = loudness(raw).integrated;
+      const gain = Number.isFinite(measured) ? config.mix.loudness - measured : 0;
+      const wav = path.join(work, 'sound.wav');
+      ffmpeg(['-i', raw, '-af', `volume=${gain.toFixed(2)}dB,alimiter=limit=${config.mix.limit}:level=false`, wav]);
+      const suffix = opts.music && opts.music !== 'default' ? `-${opts.music}` : '';
+      const out = path.join(dir, `trailer-${format.name}${suffix}.mp4`);
+      // Exactly as long as the beats: -shortest against a mix a fraction of a
+      // millisecond short dropped the last frames.
+      ffmpeg(['-i', video, '-i', wav, '-map', '0:v', '-map', '1:a', '-c:v', 'copy', '-c:a', 'aac', '-b:a', '192k', '-t', total.toFixed(6), out]);
+      fs.writeFileSync(out.replace(/\.mp4$/, '.json'), `${JSON.stringify({
+        format: format.name, music: opts.music || 'default', seconds: Number(total.toFixed(3)),
+        beats: beats.map(b => ({ name: b.name, start: Number(b.start.toFixed(3)), seconds: b.seconds, track: b.track })),
+        sources,
+      }, null, 2)}\n`);
+      console.log(`${path.relative(process.cwd(), out)}  ${total.toFixed(1)} s`);
+      written.push(out);
+    } finally {
+      fs.rmSync(work, { recursive: true, force: true });
+    }
+  }
+  return written;
+}

data/engine/lib/ease.mjs

@@ -0,0 +1,6 @@
+// Easing curves for camera and pointer moves: k runs 0 → 1.
+export const inOut = k => (k < 0.5 ? 4 * k * k * k : 1 - ((-2 * k + 2) ** 3) / 2);
+export const out = k => 1 - (1 - k) ** 3;
+export const linear = k => k;
+
+export const lerp = (a, b, k) => a + (b - a) * k;

data/engine/lib/ffmpeg.mjs

@@ -0,0 +1,46 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+
+export const ffmpeg = args => execFileSync('ffmpeg', ['-y', '-loglevel', 'error', ...args], { maxBuffer: 64 * 1024 * 1024 });
+
+// ffmpeg's report (stderr) for a run that only measures.
+export function measure(args) {
+  const run = spawnSync('ffmpeg', ['-hide_banner', '-nostats', ...args, '-f', 'null', '-'], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  if (run.status !== 0) throw new Error(`ffmpeg ${args.join(' ')}: ${run.stderr.trim().split('\n').pop()}`);
+  return run.stderr;
+}
+
+export function probe(file) {
+  const run = spawnSync('ffprobe', ['-v', 'error', '-show_entries', 'stream=codec_type,start_time,duration,width,height,r_frame_rate',
+    '-show_entries', 'format=duration', '-of', 'json', file], { encoding: 'utf8' });
+  if (run.status !== 0) throw new Error(`ffprobe ${file}: ${run.stderr.trim()}`);
+  return JSON.parse(run.stdout);
+}
+
+// Integrated loudness (LUFS) and true peak (dBTP) as ffmpeg's EBU R128 meter
+// reads them.
+export function loudness(file) {
+  return parseLoudness(measure(['-i', file, '-af', 'ebur128=peak=true']));
+}
+
+export function parseLoudness(report) {
+  const last = re => [...report.matchAll(re)].pop()?.[1];
+  const integrated = last(/^\s+I:\s+(-?[\d.]+|-inf) LUFS/gm);
+  const peak = last(/^\s+Peak:\s+(-?[\d.]+|-inf) dBFS/gm);
+  const num = v => (v == null ? null : v === '-inf' ? -Infinity : Number(v));
+  return { integrated: num(integrated), truePeak: num(peak) };
+}
+
+// Where sound starts after silence, in seconds: each `silence_end`, plus 0
+// when the sound starts on the very first sample.
+export function onsets(file, { start = 0, duration } = {}) {
+  const input = [...(start ? ['-ss', String(start)] : []), ...(duration ? ['-t', String(duration)] : []), '-i', file];
+  return parseOnsets(measure([...input, '-af', 'highpass=f=200,silencedetect=n=-40dB:d=0.05']));
+}
+
+export function parseOnsets(report) {
+  const ends = [...report.matchAll(/silence_end: (-?[\d.]+)/g)].map(m => Number(m[1]));
+  const starts = [...report.matchAll(/silence_start: (-?[\d.]+)/g)].map(m => Number(m[1]));
+  // Silence that starts later than 0 means there was sound from the start.
+  if (!starts.length || starts[0] > 0.001) ends.unshift(0);
+  return ends;
+}

data/engine/lib/film.mjs

@@ -0,0 +1,161 @@
+// Films each beat of the storyboard, in each format, as
+//   <beat>-<format>.mp4        H.264 at the format's output size, with titles
+//   <beat>-<format>-clean.mp4  the same without titles, for an editor
+//   <beat>-<format>.json       the sounds the app played and the beat's marks
+import fs from 'node:fs';
+import path from 'node:path';
+import { camera } from './camera.mjs';
+import { freeze } from './clock.mjs';
+import * as ease from './ease.mjs';
+import { ffmpeg } from './ffmpeg.mjs';
+import { loadConfig, outDir, pickBeats, pickFormats, requireFromApp } from './config.mjs';
+import { beatUrl, prepareShowcase, router } from './showcase.mjs';
+import { fileFor, ignored, listen, liveSounds, mixEffects } from './sound.mjs';
+import { filmTitles } from './titles.mjs';
+
+const centre = box => ({ x: box.x + box.w / 2, y: box.y + box.h / 2 });
+
+// What a beat's play() gets to work with.
+function stage(page, cam, format) {
+  return {
+    page,
+    cam,
+    format,
+    tall: cam.tall,
+    ease,
+    // Switches the showcase to another fixture without reloading, so the
+    // app's components see a state change and animate and play their sounds
+    // as they would on a real update.
+    setView: view => page.evaluate(v => window.__setView(v), view),
+    // Calls an app-defined trigger on the page (window[name](...args)), for
+    // events that should happen on cue rather than on a timer from load.
+    fire: (name, ...args) => page.evaluate(([n, a]) => window[n](...a), [name, args]),
+    // Presses `from`, carries it onto `to` filming as it goes, holds, lets go.
+    async drag(from, to, { ms = 700, hold = 350 } = {}) {
+      const a = await cam.boxOf(from);
+      const b = await cam.boxOf(to);
+      if (!a || !b) throw new Error(`drag: nothing matches ${a ? to : from}`);
+      const start = centre(a);
+      await page.mouse.move(start.x, start.y);
+      await page.mouse.down();
+      await cam.move(start, centre(b), ms);
+      await cam.hold(hold);
+      await page.mouse.up();
+    },
+  };
+}
+
+// Puts the page in the state a beat starts from: the app's own setup, the
+// page's clock stopped, the app settled, its audio unlocked and loaded, and
+// nothing heard before the clip counts.
+async function openBeat(browser, { site, route, config, beat, format }) {
+  const [width, height] = format.page;
+  const page = await browser.newPage({ viewport: { width, height } });
+  await page.route(`${site.origin}/**`, route);
+  await page.addInitScript(listen, ignored(config));
+  const css = [config.page?.css, beat.css].filter(Boolean).join('\n');
+  if (css) {
+    await page.addInitScript(text => {
+      addEventListener('DOMContentLoaded', () => {
+        document.head.append(Object.assign(document.createElement('style'), { textContent: text }));
+      });
+    }, css);
+  }
+  if (config.page?.init) await page.addInitScript(config.page.init, config.page.initArg);
+  await page.clock.install();
+  await page.goto(beatUrl(site, config, beat));
+  await page.waitForLoadState('networkidle').catch(() => {});
+  // The installed clock still runs at wall speed until paused; stopped, it
+  // only moves when the camera moves it.
+  await freeze(page);
+  await page.clock.runFor(beat.settle ?? config.settle);
+  // A key press unlocks the app's audio, as a person's first tap does.
+  if (config.unlock) await config.unlock(page); else await page.keyboard.press('Shift');
+  await page.waitForTimeout(config.soundLoad);
+  await page.evaluate(() => { window.__heard = []; });
+  return page;
+}
+
+const encode = (fps, args, file) => ffmpeg([...args, '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-crf', '14', '-r', String(fps), file]);
+
+const beatFiles = (dir, beat, format) => {
+  const base = path.join(dir, `${beat}-${format}`);
+  return { base, video: `${base}.mp4`, clean: `${base}-clean.mp4`, json: `${base}.json` };
+};
+
+export async function film(appDir, opts = {}) {
+  const config = await loadConfig(appDir, opts.config);
+  const formats = pickFormats(config, opts.format);
+  const beats = pickBeats(config, opts.only);
+  const dir = outDir(config, opts.out);
+  const live = liveSounds(config, { bundled: opts.sounds === 'bundled' });
+
+  if (opts.clean) {
+    for (const f of formats) {
+      for (const b of beats) for (const file of Object.values(beatFiles(dir, b.name, f.name)).slice(1)) fs.rmSync(file, { force: true });
+      fs.rmSync(path.join(dir, `trailer-${f.name}.mp4`), { force: true });
+    }
+    for (const leftover of fs.existsSync(dir) ? fs.readdirSync(dir) : []) {
+      if (leftover.startsWith('.frames-') || leftover.startsWith('.effects-')) fs.rmSync(path.join(dir, leftover), { recursive: true, force: true });
+    }
+    if (live) fs.rmSync(live.cache, { recursive: true, force: true });
+  }
+
+  const site = await prepareShowcase(config);
+  const route = router(site, config, live);
+  fs.mkdirSync(dir, { recursive: true });
+  const { chromium } = requireFromApp(config.appDir, 'playwright');
+  // Headless Chromium has no one to tap the page, and Web Audio waits for a
+  // tap; this lets it start anyway.
+  const browser = await chromium.launch({ args: ['--autoplay-policy=no-user-gesture-required'] });
+  const filmed = [];
+  try {
+    for (const format of formats) {
+      for (const beat of beats) {
+        const page = await openBeat(browser, { site, route, config, beat, format });
+        const files = beatFiles(dir, beat.name, format.name);
+        const frames = path.join(dir, `.frames-${beat.name}-${format.name}`);
+        const titles = `${frames}-titles`;
+        for (const d of [frames, titles]) { fs.rmSync(d, { recursive: true, force: true }); fs.mkdirSync(d, { recursive: true }); }
+
+        const cam = await camera(page, { fps: config.fps, format, dir: frames });
+        await beat.play(stage(page, cam, format));
+        await page.close();
+        if (!cam.frames) throw new Error(`beat ${beat.name} filmed no frames: its play() never called cam.hold, move or shoot`);
+        await filmTitles(browser, { site, route, config, format, cues: cam.cues, frames: cam.frames, dir: titles });
+
+        // The effects the beat played, for the cut to lay across the whole
+        // trailer (a knockout rings on past its own beat), and mixed into the
+        // clips as far as each one runs, for an editor.
+        const seconds = cam.frames / config.fps;
+        const sounds = cam.sounds.map(s => ({ at: Number(s.at.toFixed(3)), file: path.relative(config.appDir, fileFor(config, live, s.url)) }));
+        fs.writeFileSync(files.json, `${JSON.stringify({
+          beat: beat.name, format: format.name, fps: config.fps, frames: cam.frames, seconds,
+          marks: cam.marks, endCard: cam.cues.some(c => c.end), sounds,
+        }, null, 2)}\n`);
+        const effects = path.join(dir, `.effects-${beat.name}-${format.name}.wav`);
+        mixEffects(sounds.map(s => ({ ...s, file: path.resolve(config.appDir, s.file) })), seconds, effects);
+
+        // Cut to exactly the frames filmed: -shortest against an effects track
+        // a fraction of a millisecond short dropped the beat's last frame.
+        const [width, height] = format.out;
+        encode(config.fps, ['-framerate', String(config.fps), '-i', path.join(frames, '%05d.jpg'), '-i', effects,
+          '-vf', `scale=${width}:${height}:flags=lanczos,setsar=1`, '-c:a', 'aac', '-b:a', '192k', '-t', seconds.toFixed(6)], files.clean);
+        // Over the encoded clean clip, never the raw frames: a frame a pixel
+        // off size makes ffmpeg rebuild the overlay part-way and drop the titles.
+        encode(config.fps, ['-i', files.clean, '-framerate', String(config.fps), '-i', path.join(titles, '%05d.png'),
+          '-filter_complex', '[0:v][1:v]overlay=format=auto:eof_action=pass[v]', '-map', '[v]', '-map', '0:a', '-c:a', 'copy'], files.video);
+        fs.rmSync(effects, { force: true });
+        if (!opts.keepFrames) for (const d of [frames, titles]) fs.rmSync(d, { recursive: true, force: true });
+
+        const missing = sounds.filter(s => !fs.existsSync(path.resolve(config.appDir, s.file)));
+        console.log(`${path.relative(process.cwd(), files.video)}  ${cam.frames} frames  ${seconds.toFixed(2)} s  ${sounds.length} sounds`);
+        for (const s of missing) console.warn(`  ! ${s.file} (played at ${s.at} s) isn't on disk, so it's silent in the clip`);
+        filmed.push(files.video);
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+  return filmed;
+}

data/engine/lib/index.mjs

@@ -0,0 +1,5 @@
+// The engine, for a site that drives it from its own script.
+export { film } from './film.mjs';
+export { cut } from './cut.mjs';
+export { check } from './check.mjs';
+export * as ease from './ease.mjs';