@homie-rocks/studio 0.51.4 → 0.51.5

package/guides/video/scripts/capture-game.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * capture-game.mjs — real gameplay from a studio's own game, for a trailer: the
+ * game's big-screen view (/<id>/tv: a spectator in a live public room) recorded
+ * off a headless GPU Chrome, picture and the game's own
+ * sound on one clock.
+ * A server rules room needs a player to keep ticking; use --view play when
+ * filming an otherwise empty room. A spectator alone does not wake it.
+ *
+ *   node capture-game.mjs --url <site> --game <id> --seconds 60 --out <dir>
+ *        [--view tv|play] [--fps 30] [--width 1920] [--height 1080] [--scale 1] [--settle 4] [--min-free-gb 10]
+ *
+ * Size and speed: --width/--height is the film's size, --fps its frame rate. --scale renders the page smaller
+ * (0.25 to 1: 0.67 is a 1280x720 page for a 1920x1080 film) and scales the frames up to the film's size when it
+ * encodes. A heavy game paints far more frames at a smaller size (measured: 8 frames a second at 1080p, 39 at
+ * 720p), and a frame the page did not paint in time is a held frame. The result says the page's own frame rate;
+ * when it is well under --fps it names a --scale that would paint enough.
+ *
+ * Picture: the compositor's own frame stream (CDP Page.startScreencast), every
+ *          frame kept with the time Chrome presented it, then laid onto a constant
+ *          frame rate (a frame the page did not paint in time is held, and counted).
+ * Sound:   tap.js copies what the game sends to its speaker (WebAudio), stamped
+ *          with the audio clock, which is fitted to the page clock; the browser is
+ *          muted, so nothing plays out loud on this computer.
+ * Out:     <dir>/capture.mp4 (H.264 + AAC when the game made sound), <dir>/capture.json
+ *          (what was captured, frame rates, held frames, the room, the sound). The raw
+ *          frames are deleted once encoded.
+ *
+ * It never presses anything in the game: what it records is the game as it plays.
+ */
+import { mkdirSync, readFileSync, rmSync, statfsSync, writeFileSync } from 'node:fs';
+import { cpus, loadavg } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { launch } from './lib/browser.mjs';
+import { TapReader, constantRate, encodeMp4, fitAudio, startScreencast, writeConcat } from './lib/frames.mjs';
+import { findStudio } from '../../music/scripts/lib/studio.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const argv = process.argv.slice(2);
+const opt = (n, d = null) => { const i = argv.indexOf(`--${n}`); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : d; };
+const URL_ = String(opt('url', '')).replace(/\/+$/, '');
+const GAME = opt('game');
+const SECONDS = Number(opt('seconds', 60));
+const OUT = resolve(String(opt('out', '')));
+const VIEW = opt('view', 'tv');
+const FPS = Number(opt('fps', 30));
+const W = Number(opt('width', 1920)); const H = Number(opt('height', 1080));
+const SCALE = Number(opt('scale', 1));
+// The page's own size: even numbers (the encoder's rule), scaled up to W x H when the film is made.
+const RW = Math.max(2, Math.round((W * SCALE) / 2) * 2); const RH = Math.max(2, Math.round((H * SCALE) / 2) * 2);
+const SETTLE = Number(opt('settle', 4));
+const MIN_FREE_GB = Number(opt('min-free-gb', 10));
+const fail = (m) => { process.stderr.write(`capture-game: ${m}\n`); process.exit(2); };
+if (!/^https?:\/\//.test(URL_)) fail('--url <the studio site: http://127.0.0.1:8787 from npm run dev, or the live site>');
+if (!/^[a-z0-9][a-z0-9-]{0,39}$/.test(String(GAME ?? ''))) fail('--game <id>');
+if (!(SECONDS >= 3 && SECONDS <= 600)) fail('--seconds 3..600');
+if (!(SCALE >= 0.25 && SCALE <= 1)) fail('--scale 0.25..1 (the page renders at that part of --width x --height, and the film is scaled up to it)');
+if (!(FPS >= 1 && FPS <= 60)) fail('--fps 1..60');
+if (!opt('out')) fail('--out <folder> (the video job\'s work/capture folder)');
+const freeGB = () => { try { const f = statfsSync(OUT); return (f.bavail * f.bsize) / 1e9; } catch { return 99; } };
+mkdirSync(OUT, { recursive: true });
+if (freeGB() < MIN_FREE_GB + 2) fail(`only ${freeGB().toFixed(1)} GB free; a capture needs room (stopping below ${MIN_FREE_GB} GB)`);
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const log = (k, v = {}) => process.stderr.write(`${JSON.stringify({ t: +(process.uptime()).toFixed(1), k, ...v })}\n`);
+const TAP = readFileSync(join(HERE, 'tap.js'), 'utf8');
+const root = findStudio(OUT) ?? findStudio();
+
+const frameDir = join(OUT, 'frames');
+rmSync(frameDir, { recursive: true, force: true });
+mkdirSync(frameDir, { recursive: true });
+let frames = []; // { file, t } t = presentation time (epoch seconds)
+const pcmFile = join(OUT, 'game-audio.s16le');
+const tap = new TapReader(pcmFile);
+const report = { ran: new Date().toISOString(), url: `${URL_}/${GAME}/${VIEW}`, seconds: SECONDS, fps: FPS, size: [W, H], ...(SCALE !== 1 ? { scale: SCALE, rendered: [RW, RH] } : {}), notes: [] };
+
+const { browser, close, pid } = await launch(root, { width: RW, height: RH, extra: ['--autoplay-policy=no-user-gesture-required', '--mute-audio'] });
+log('browser', { pid });
+const stop = async (why) => { log('stop', { why }); tap.close(); await close(); process.exit(3); };
+process.on('SIGINT', () => stop('SIGINT'));
+process.on('SIGTERM', () => stop('SIGTERM'));
+
+try {
+  const page = await browser.newPage();
+  await page.setViewport({ width: RW, height: RH, deviceScaleFactor: 1 });
+  await page.evaluateOnNewDocument(TAP);
+  const errors = [];
+  page.on('pageerror', (e) => { if (errors.length < 30) errors.push(String(e.message).slice(0, 200)); });
+  const target = VIEW === 'play' ? `${URL_}/${GAME}/play?hand=desk&name=Camera` : `${URL_}/${GAME}/tv`;
+  await page.goto(target, { waitUntil: 'domcontentloaded', timeout: 60_000 });
+  // The shell's own furniture (status chip, join card, results card) is not the game.
+  await page.addStyleTag({ content: '[data-chip],[data-join],[data-screen],[data-results],[data-room-ui],[data-toast]{display:none!important} *{cursor:none!important}' });
+  let game = null;
+  for (let i = 0; i < 200 && !game; i++) {
+    for (const f of page.frames()) if (/\/__game\//.test(f.url()) && !f.isDetached()) game = f;
+    if (!game) await sleep(150);
+  }
+  if (!game) throw new Error('the game frame never loaded');
+  // A static/older imported game need not publish a netplay probe. Its module
+  // still finishes loading before complete; rules games publish their probe there.
+  await game.waitForFunction(() => document.readyState === 'complete', { timeout: 30000 });
+  report.room = await page.evaluate(() => window.__shell?.room ?? null).catch(() => null);
+  const rulesBefore = await game.evaluate(() => { const p = window.__homieNet?.probe; return typeof p?.hosted === 'function' ? { hosted: p.hosted(), tick: p.tick?.() } : null; }).catch(() => null);
+  await sleep(SETTLE * 1000);
+  if (VIEW === 'tv' && rulesBefore?.hosted === 'server') {
+    const tick = await game.evaluate(() => window.__homieNet?.probe?.tick?.()).catch(() => null);
+    if (!(tick > rulesBefore.tick)) throw new Error('The server room is paused: a TV is not a participant. Keep a real player open in this same room, or capture with --view play, then record again.');
+  }
+  await page.keyboard.press('Shift').catch(() => {}); // a first gesture, for games that start their sound on one
+  const tapStart = await game.evaluate(() => window.__homieTap?.start?.() ?? null).catch(() => null);
+  report.tap = tapStart;
+  log('ready', { room: report.room, tap: tapStart });
+
+  const cast = await startScreencast(page, { dir: frameDir, width: RW, height: RH });
+  frames = cast.frames;
+  const until = Date.now() + SECONDS * 1000 + 600;
+  let lastLog = 0;
+  while (Date.now() < until) {
+    try { await tap.poll(game); } catch (error) { report.notes.push(`poll: ${String(error.message).slice(0, 120)}`); }
+    if (Date.now() - lastLog > 10_000) { lastLog = Date.now(); log('recording', { frames: frames.length, audioS: tap.rate ? +(tap.frames / tap.rate).toFixed(1) : 0, freeGB: +freeGB().toFixed(1) }); }
+    if (freeGB() < MIN_FREE_GB) { report.notes.push('stopped early: disk low'); break; }
+    await sleep(250);
+  }
+  await cast.stop();
+  await sleep(300);
+  report.errors = errors;
+} catch (error) {
+  report.failed = String(error.stack ?? error);
+} finally {
+  tap.close();
+  await close();
+}
+
+if (report.failed || frames.length < 10) {
+  writeFileSync(join(OUT, 'capture.json'), JSON.stringify({ ...report, frames: frames.length }, null, 1));
+  rmSync(frameDir, { recursive: true, force: true });
+  fail(report.failed ? `capture failed: ${report.failed.split('\n')[0]}` : `the page painted only ${frames.length} frames`);
+}
+
+/* ---- picture onto a constant frame rate: output frame k shows the newest frame presented by t0 + k/fps (lib/frames.mjs) */
+const cfr = constantRate(frames, FPS);
+const { t0, total, list, held, distinct } = cfr;
+const concat = writeConcat(join(OUT, 'frames.txt'), list, FPS);
+
+/* ---- sound onto the same clock: fit epoch(ms) = a + b * contextTime from the output timestamps */
+const audio = fitAudio(tap, { t0, total, fps: FPS, out: join(OUT, 'game-audio.raw') });
+if (audio && !audio.peakDb) audio.note = 'the game made no sound while it was recorded';
+rmSync(pcmFile, { force: true });
+
+const mp4 = join(OUT, 'capture.mp4');
+const enc = encodeMp4({ concat, audio, fps: FPS, width: W, height: H, seconds: total / FPS, out: mp4 });
+rmSync(frameDir, { recursive: true, force: true });
+rmSync(concat, { force: true });
+if (audio) delete audio.raw;
+if (!enc.ok) fail(`encode failed: ${enc.why}`);
+const spanS = cfr.frames.at(-1).t - t0;
+const sourceFps = +(frames.length / spanS).toFixed(1);
+// Too few frames from the page: a smaller page paints more (the frame count grows about with the pixels saved).
+let advice = null;
+if (sourceFps < FPS * 0.75) {
+  // Below half size a film is too soft to scale up, and a page that slow is a busy computer as much as a heavy game.
+  const want = Math.max(0.5, Math.min(1, +(SCALE * Math.sqrt(Math.max(0.05, sourceFps / FPS))).toFixed(2)));
+  const load = +(loadavg()[0] / Math.max(1, cpus().length)).toFixed(1);
+  advice = `the page painted ${sourceFps} frames a second for a ${FPS} fps film (${held} frames held)${load > 1.5 ? `, on a busy computer (load ${load} a core)` : ''}: `
+    + (want < SCALE ? `capture again with --scale ${want} (a ${Math.round(W * want)}x${Math.round(H * want)} page, scaled up)${load > 1.5 ? ' when it is quieter' : ''}, or a lower --fps` : `capture with a lower --fps${load > 1.5 ? ', or when the computer is quieter' : ''}`);
+}
+const result = {
+  ...report, mode: 'live', file: 'capture.mp4', seconds: +(total / FPS).toFixed(3), outputFrames: total, sourceFrames: frames.length,
+  sourceFps, distinctFramesUsed: distinct, heldFrames: held, audio, ...(advice ? { advice } : {}),
+  honesty: 'Recorded from the game in a live public room, with no scripted gameplay or drawn overlay. Any bots shown are the game\'s own bots.',
+};
+writeFileSync(join(OUT, 'capture.json'), `${JSON.stringify(result, null, 1)}\n`);
+process.stdout.write(`${JSON.stringify({ ok: true, file: mp4, seconds: result.seconds, sourceFps: result.sourceFps, heldFrames: held, ...(advice ? { advice } : {}), audio: audio ? { seconds: audio.seconds, peakDb: audio.peakDb, covered: audio.covered } : null })}\n`);
+process.exit(0);

package/guides/video/scripts/clock.js

@@ -0,0 +1,136 @@
+/*
+ * clock.js: one virtual clock for a page that is being rendered frame by frame (record-fixed.mjs).
+ * Injected ahead of the page's own scripts (puppeteer evaluateOnNewDocument), into every frame.
+ *
+ * A film at 30 frames a second needs the page to be exactly 1/30 s older in each frame, however
+ * long the frame took to draw and to copy. So time in the page stops being the wall's: it moves
+ * only when the recorder calls window.__homieClock.step(ms), and then everything that tells the
+ * page the time agrees:
+ *
+ *   performance.now()                 the virtual time, in ms, from 0 when the document began
+ *   Date.now(), new Date()            the wall time the document began at, plus the virtual time
+ *   requestAnimationFrame             called once a step, with the virtual time
+ *   setTimeout / setInterval          fired in order, each at its own virtual time, inside the step
+ *   CSS animations and transitions,   paused and set to their place by the virtual time every step
+ *   element.animate() (Web Animations)  (document.getAnimations()), finished when they reach their end
+ *
+ * A countdown driven by setInterval, a callout that fades with a CSS animation and a game loop on
+ * requestAnimationFrame therefore stay in step with one another: with only some of them virtual,
+ * a one-second callout is over between two frames and never appears in the film.
+ *
+ * NOT on this clock, because the page cannot reach them or they are not time the page reads:
+ *   - AudioContext.currentTime and anything scheduled on it (the sound is rebuilt from a log)
+ *   - <video> and <audio> elements, which play at their own rate
+ *   - Web Workers and worklets (their timers and performance.now are their own)
+ *   - event.timeStamp, document.timeline.currentTime, performance.timeOrigin
+ *   - the network: a server keeps real time, so a page fed by one sees it run fast or slow
+ *   - an animation the page itself paused before the clock first saw it is left alone
+ *
+ * Nothing here draws, and nothing changes what a callback does: only when it is called.
+ */
+(function () {
+  'use strict';
+  if (window.__homieClock) return;
+  const real = {
+    raf: window.requestAnimationFrame.bind(window),
+    setTimeout: window.setTimeout.bind(window),
+    clearTimeout: window.clearTimeout.bind(window),
+    Date: window.Date,
+  };
+  const epoch = real.Date.now();
+  let now = 0; // virtual ms since this document began
+  let seq = 1;
+  const timers = new Map(); // id -> { at, fn, args, every }
+  let rafs = new Map(); // id -> fn
+  const anims = new WeakMap(); // Animation -> { t0, ours }
+  const errors = [];
+  const guard = (fn, args) => { try { fn(...args); } catch (e) { if (errors.length < 20) errors.push(String(e && e.message || e)); real.setTimeout(() => { throw e; }, 0); } };
+
+  /* ---- the clocks the page reads */
+  try { Object.defineProperty(performance, 'now', { configurable: true, value: () => now }); } catch (e) { /* frozen */ }
+  // A function, not a class: Date() without `new` is legal and returns a string.
+  function VDate(...a) {
+    if (!new.target) return new real.Date(epoch + now).toString();
+    return Reflect.construct(real.Date, a.length ? a : [epoch + now], new.target);
+  }
+  VDate.prototype = real.Date.prototype;
+  VDate.now = () => epoch + Math.floor(now);
+  VDate.parse = real.Date.parse; VDate.UTC = real.Date.UTC;
+  window.Date = VDate;
+
+  /* ---- timers */
+  const addTimer = (fn, ms, args, every) => {
+    const id = seq++;
+    const wait = Math.max(0, Number(ms) || 0);
+    timers.set(id, { at: now + wait, fn: typeof fn === 'function' ? fn : () => (0, eval)(String(fn)), args, every: every ? Math.max(1, wait) : 0 });
+    return id;
+  };
+  window.setTimeout = (fn, ms, ...args) => addTimer(fn, ms, args, false);
+  window.setInterval = (fn, ms, ...args) => addTimer(fn, ms, args, true);
+  window.clearTimeout = window.clearInterval = (id) => { timers.delete(id); };
+  window.requestAnimationFrame = (fn) => { const id = seq++; rafs.set(id, fn); return id; };
+  window.cancelAnimationFrame = (id) => { rafs.delete(id); };
+
+  /** Run every timer due by `to`, each at its own time, earliest first (a timer set by a timer runs in the same step when it is due). */
+  function runTimers(to) {
+    for (let guardCount = 0; guardCount < 20000; guardCount++) {
+      let next = null; let nextId = 0;
+      for (const [id, t] of timers) if (t.at <= to && (next === null || t.at < next.at || (t.at === next.at && id < nextId))) { next = t; nextId = id; }
+      if (!next) break;
+      if (next.at > now) now = next.at;
+      if (next.every) next.at += next.every; else timers.delete(nextId);
+      guard(next.fn, next.args);
+    }
+    now = to;
+  }
+
+  /** Every animation in the document, at its place by the virtual clock. */
+  function runAnimations() {
+    let list = [];
+    try { list = document.getAnimations(); } catch (e) { return 0; }
+    for (const a of list) {
+      let s = anims.get(a);
+      if (!s) {
+        // First sight: one the page paused itself stays the page's; a running one becomes ours from where it is.
+        s = { ours: a.playState !== 'paused', t0: now - (Number(a.currentTime) || 0) / (a.playbackRate || 1) };
+        anims.set(a, s);
+        if (s.ours) { try { a.pause(); } catch (e) { s.ours = false; } }
+      }
+      if (!s.ours) continue;
+      const at = (now - s.t0) * (a.playbackRate || 1);
+      let end = Infinity;
+      try { end = a.effect ? a.effect.getComputedTiming().endTime : Infinity; } catch (e) { /* no effect */ }
+      try {
+        if (Number(end) <= at) { a.finish(); anims.delete(a); } else a.currentTime = at;
+      } catch (e) { /* an animation that cannot be sought is left where it is */ }
+    }
+    return list.length;
+  }
+
+  /**
+   * One frame: the clock moves on by `ms`, the timers due in it fire, then the frame callbacks, then
+   * the animations are placed. All of it inside a real animation frame of the browser, and the promise
+   * resolves a real frame later, so what was drawn has been presented when the recorder copies it.
+   */
+  function step(ms) {
+    return new Promise((done) => {
+      let ran = false;
+      const run = () => {
+        if (ran) return; ran = true;
+        const to = now + Math.max(0, Number(ms) || 0);
+        runTimers(to);
+        const due = rafs; rafs = new Map();
+        for (const fn of due.values()) guard(fn, [now]);
+        const n = runAnimations();
+        let settled = false;
+        const finish = () => { if (settled) return; settled = true; done({ now, timers: timers.size, frames: due.size, animations: n, errors: errors.splice(0) }); };
+        real.raf(() => finish());
+        real.setTimeout(finish, 250); // a frame the browser is not painting (hidden, off screen) has no animation frames
+      };
+      real.raf(run);
+      real.setTimeout(run, 250);
+    });
+  }
+
+  window.__homieClock = { step, get now() { return now; }, epoch, virtual: true };
+})();

package/guides/video/scripts/drawover/film.js

@@ -0,0 +1,58 @@
+/*
+ * film.js — every frame is a pure function of time: renderAt(t) draws the frame at
+ * t seconds and returns it as a JPEG data URL, so `video.mjs film render` can shoot
+ * it frame-exactly in a headless browser, and any frame can be re-rendered alone.
+ *
+ * Inputs (served from the video's folder):
+ *   film/shots.json  the shot list on the song's bar grid (at, dur, base frames, where the subject is, the type)
+ *   grid.json        the song's beats, bars and sung words (video.mjs grid)
+ *   work/frames/<id>/f00001.jpg …  a generated clip's frames at 24 fps (video.mjs film frames)
+ * The look itself is look.js: change it, not this file.
+ */
+import { drawBase, drawType } from './look.js';
+
+const params = new URLSearchParams(location.search);
+const MODE = params.get('mode') === 'v' ? 'v' : 'h';
+const W = MODE === 'v' ? 1080 : 1920;
+const H = MODE === 'v' ? 1920 : 1080;
+const canvas = document.getElementById('c');
+canvas.width = W; canvas.height = H;
+const ctx = canvas.getContext('2d', { willReadFrequently: true });
+let SHOTS = null; let GRID = null;
+const cache = new Map();
+
+function image(src) {
+  if (cache.has(src)) return cache.get(src);
+  const p = new Promise((ok) => { const i = new Image(); i.onload = () => ok(i); i.onerror = () => ok(null); i.src = src; });
+  cache.set(src, p);
+  if (cache.size > 96) cache.delete(cache.keys().next().value);
+  return p;
+}
+
+export async function boot() {
+  SHOTS = await (await fetch('./shots.json', { cache: 'no-store' })).json();
+  GRID = await (await fetch('../grid.json', { cache: 'no-store' })).json().catch(() => ({ beats: [], words: [] }));
+  await document.fonts?.ready;
+}
+
+/** Deterministic noise: the same t and seed always give the same number. */
+export const rand = (seed) => { const x = Math.sin(seed * 127.1 + 311.7) * 43758.5453; return x - Math.floor(x); };
+
+window.renderAt = async (t) => {
+  const shot = SHOTS.shots.find((s) => t >= s.at && t < s.at + s.dur) ?? SHOTS.shots[SHOTS.shots.length - 1];
+  const local = t - shot.at + (shot.baseStart ?? 0);
+  let img = null;
+  if (shot.base) {
+    const n = Math.max(1, Math.floor(local * 24 + 1e-6) + 1);
+    img = await image(`../${shot.base}/f${String(n).padStart(5, '0')}.jpg`);
+    for (let k = n - 1; !img && k >= 1 && k > n - 48; k--) img = await image(`../${shot.base}/f${String(k).padStart(5, '0')}.jpg`); // past the clip's end: hold its last frame
+  }
+  const songT = t + (SHOTS.songStart ?? 0);
+  const beats = GRID.beats ?? [];
+  let beatPhase = 1;
+  for (let i = beats.length - 1; i >= 0; i--) if (beats[i] <= songT) { beatPhase = Math.min(1, (songT - beats[i]) / (GRID.beat || 0.5)); break; }
+  const env = { t, songT, W, H, mode: MODE, shot, palette: SHOTS.palette, font: SHOTS.font, beatPhase, words: GRID.words ?? [], rand };
+  drawBase(ctx, img, env);
+  drawType(ctx, env);
+  return canvas.toDataURL('image/jpeg', 0.92);
+};

package/guides/video/scripts/drawover/index.html

@@ -0,0 +1,9 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>film</title>
+<style>html,body{margin:0;background:#000;overflow:hidden}canvas{display:block}</style></head>
+<body><canvas id="c"></canvas>
+<script type="module">
+import { boot } from './film.js';
+boot().then(() => { window.READY = true; }).catch((e) => { window.FAIL = String(e && e.stack || e); });
+</script>
+</body></html>

package/guides/video/scripts/drawover/look.js

@@ -0,0 +1,115 @@
+/*
+ * look.js — the look of the film. A starting point, meant to be changed for every
+ * video: a two-ink print (paper, ink, and an accent) where the generated clip is the
+ * motion underneath and the drawing is what you see, plus kinetic lyric type.
+ *
+ * drawBase(ctx, img, env): the picture. env: { t, songT, W, H, mode, shot, palette, beatPhase, words, rand }.
+ * drawType(ctx, env): the words. Big and present for shots marked "big", quiet for "quiet", none for "none".
+ */
+const SCREEN = 9; // halftone cell, px
+let small = null;
+
+export function drawBase(ctx, img, env) {
+  const { W, H, palette, shot, rand } = env;
+  ctx.globalCompositeOperation = 'source-over';
+  ctx.fillStyle = palette.paper;
+  ctx.fillRect(0, 0, W, H);
+  if (!img) return;
+  // Cover the frame, keeping the subject (shot.focus, 0..1) in view; a small push on each beat.
+  const bump = 1 + 0.018 * Math.max(0, 1 - env.beatPhase * 4);
+  const s = Math.max(W / img.width, H / img.height) * bump;
+  const [fx, fy] = shot.focus ?? [0.5, 0.5];
+  const dw = img.width * s; const dh = img.height * s;
+  const dx = Math.min(0, Math.max(W - dw, W / 2 - fx * dw));
+  const dy = Math.min(0, Math.max(H - dh, H / 2 - fy * dh));
+  // The hand: the plate shifts a little, twelve times a second (the "boil").
+  const tick = Math.floor(env.t * 12);
+  const jx = (rand(tick) - 0.5) * 3; const jy = (rand(tick + 99) - 0.5) * 3;
+  // Line work: the base in grey, multiplied onto the paper.
+  ctx.save();
+  ctx.filter = 'grayscale(1) contrast(1.6) brightness(1.08)';
+  ctx.globalAlpha = 0.5;
+  ctx.globalCompositeOperation = 'multiply';
+  ctx.drawImage(img, dx + jx, dy + jy, dw, dh);
+  ctx.restore();
+  // Ink: halftone dots sized by how dark each cell is.
+  const cw = Math.ceil(W / SCREEN); const chh = Math.ceil(H / SCREEN);
+  if (!small || small.width !== cw) { small = document.createElement('canvas'); small.width = cw; small.height = chh; }
+  const sc = small.getContext('2d', { willReadFrequently: true });
+  sc.filter = 'contrast(1.3)';
+  sc.drawImage(img, dx / SCREEN, dy / SCREEN, dw / SCREEN, dh / SCREEN);
+  const px = sc.getImageData(0, 0, cw, chh).data;
+  // Two screens: the ink prints the dark, the accent prints warm light (red well above blue),
+  // on a grid offset by half a cell and misregistered a little from the ink, like a second pass.
+  const plate = (colour, amount, ox0, oy0) => {
+    ctx.fillStyle = colour;
+    ctx.beginPath();
+    for (let y = 0; y < chh; y++) {
+      for (let x = 0; x < cw; x++) {
+        const r = amount(px, (y * cw + x) * 4) * SCREEN * 0.62;
+        if (r < 0.6) continue;
+        const cx = x * SCREEN + (y % 2) * SCREEN * 0.5 + ox0; const cy = y * SCREEN + SCREEN / 2 + oy0;
+        ctx.moveTo(cx + r, cy);
+        ctx.arc(cx, cy, r, 0, Math.PI * 2);
+      }
+    }
+    ctx.fill();
+  };
+  ctx.globalCompositeOperation = 'multiply';
+  plate(palette.ink, (p, i) => 1 - (0.3 * p[i] + 0.59 * p[i + 1] + 0.11 * p[i + 2]) / 255, jx, jy);
+  const mx = (rand(tick + 5) - 0.5) * 3 + SCREEN / 3; const my = (rand(tick + 17) - 0.5) * 3 + SCREEN / 3;
+  plate(palette.accent, (p, i) => Math.max(0, Math.min(1, (p[i] - p[i + 2] - 40) / 140)), mx, my);
+  ctx.globalCompositeOperation = 'source-over';
+  // Paper tooth: fixed to the card, not to time.
+  ctx.fillStyle = 'rgba(0,0,0,0.035)';
+  for (let i = 0; i < 1400; i++) ctx.fillRect(rand(i) * W, rand(i + 7) * H, 1 + rand(i + 3) * 2, 1);
+}
+
+/** The line being sung at songT, and its words up to now. */
+function lineAt(words, songT) {
+  if (!words.length) return null;
+  let i = words.findIndex((w) => w.s > songT);
+  if (i < 0) i = words.length;
+  const past = words.slice(0, i);
+  if (!past.length) return null;
+  const last = past[past.length - 1];
+  if (songT - last.e > 1.2) return null;
+  // A line: the words since the last pause of 0.45 s or more.
+  let k = past.length - 1;
+  while (k > 0 && past[k].s - past[k - 1].e < 0.45) k--;
+  return past.slice(k);
+}
+
+export function drawType(ctx, env) {
+  const { W, H, palette, shot, songT, words, font } = env;
+  if (shot.type === 'none') return;
+  const line = lineAt(words, songT);
+  if (!line) return;
+  const big = shot.type === 'big';
+  const size = big ? (env.mode === 'v' ? 150 : 170) : (env.mode === 'v' ? 64 : 58);
+  const left = shot.side !== 'right';
+  const x0 = env.mode === 'v' ? W * 0.08 : (left ? W * 0.06 : W * 0.56);
+  const maxW = env.mode === 'v' ? W * 0.84 : W * 0.38;
+  ctx.save();
+  ctx.font = font.replace('1px', `${size}px`);
+  ctx.textBaseline = 'alphabetic';
+  let x = x0; let y = env.mode === 'v' ? H * 0.2 : (big ? H * 0.28 : H * 0.8);
+  for (const w of line) {
+    const word = big ? w.w.toUpperCase() : w.w;
+    const wWidth = ctx.measureText(`${word} `).width;
+    if (x + wWidth > x0 + maxW && x > x0) { x = x0; y += size * 0.95; }
+    const age = songT - w.s;
+    const pop = big ? 1 + 0.35 * Math.max(0, 1 - age / 0.12) : 1;
+    ctx.save();
+    ctx.translate(x, y);
+    ctx.scale(pop, pop);
+    // The newest word in the accent ink, the rest in ink, all knocked out of a paper box so they read over any picture.
+    const newest = w === line[line.length - 1];
+    if (big) { ctx.fillStyle = palette.paper; ctx.fillRect(-6, -size * 0.82, wWidth - size * 0.18, size * 0.98); }
+    ctx.fillStyle = newest ? palette.accent : palette.ink;
+    ctx.fillText(word, 0, 0);
+    ctx.restore();
+    x += wWidth;
+  }
+  ctx.restore();
+}

package/guides/video/scripts/drawover/shots.json

@@ -0,0 +1,12 @@
+{
+  "fps": 24,
+  "length": 8,
+  "audio": "work/song-cut.wav",
+  "songStart": 0,
+  "palette": { "paper": "#f1ead8", "ink": "#1d1b22", "accent": "#e2462f" },
+  "font": "900 1px ui-sans-serif, system-ui, -apple-system, 'Helvetica Neue', Arial, sans-serif",
+  "shots": [
+    { "at": 0, "dur": 4, "base": "work/frames/shot-01", "baseStart": 0, "focus": [0.62, 0.45], "type": "big", "side": "left" },
+    { "at": 4, "dur": 4, "base": "work/frames/shot-02", "baseStart": 0, "focus": [0.4, 0.5], "type": "quiet", "side": "right" }
+  ]
+}

package/guides/video/scripts/lib/browser.mjs

@@ -0,0 +1,87 @@
+/**
+ * A headless Chrome on the GPU, driven with puppeteer-core from the studio's own
+ * node_modules (it comes with @homie-rocks/studio). A software renderer runs a
+ * WebGL game at about one frame a second and makes it look stuck, so the GPU
+ * flags are not optional.
+ *
+ * On Linux with no GPU (a cloud session, CI) Chrome draws WebGL with SwiftShader (it needs
+ * --enable-unsafe-swiftshader since Chrome 137), and a Chrome for Testing on an Ubuntu that restricts unprivileged
+ * user namespaces (23.10 and later), or a Chrome run as root, starts only without its sandbox: the same rules as
+ * @homie-rocks/studio's own checks (lib/chrome.mjs). Pages are opened in throwaway profiles.
+ */
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export const CHROMES = [
+  process.env.CHROME_PATH,
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/opt/google/chrome/chrome',
+].filter(Boolean);
+
+function noSandboxNeeded() {
+  if (process.platform !== 'linux') return false;
+  if (typeof process.getuid === 'function' && process.getuid() === 0) return true;
+  try { return readFileSync('/proc/sys/kernel/apparmor_restrict_unprivileged_userns', 'utf8').trim() === '1'; } catch { return false; }
+}
+
+export const GPU_FLAGS = process.platform === 'darwin'
+  ? ['--use-angle=metal', '--enable-gpu-rasterization', '--ignore-gpu-blocklist']
+  : ['--enable-gpu-rasterization', '--ignore-gpu-blocklist', '--use-gl=angle', '--enable-unsafe-swiftshader', '--disable-dev-shm-usage', ...(noSandboxNeeded() ? ['--no-sandbox'] : [])];
+
+/** The newest build in a Chrome for Testing cache (`homie-studio chrome install` keeps one in .cache/homie-studio in the home folder). */
+function newestIn(dir, rel) {
+  if (!existsSync(dir)) return null;
+  const builds = readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort((a, b) => b.localeCompare(a, 'en', { numeric: true }));
+  for (const b of builds) for (const r of rel) { const path = join(dir, b, ...r); if (existsSync(path)) return path; }
+  return null;
+}
+
+export function chromePath() {
+  return CHROMES.find((p) => existsSync(p))
+    ?? newestIn(join(homedir(), '.cache', 'homie-studio', 'chrome', 'chrome'), [['chrome-linux64', 'chrome'], ['chrome-mac-arm64', 'Google Chrome for Testing.app', 'Contents', 'MacOS', 'Google Chrome for Testing'], ['chrome-mac-x64', 'Google Chrome for Testing.app', 'Contents', 'MacOS', 'Google Chrome for Testing']])
+    ?? null;
+}
+
+export function loadPuppeteer(root) {
+  const tries = [root ? join(root, 'package.json') : null, join(process.cwd(), 'package.json')].filter(Boolean);
+  for (const from of tries) {
+    try { const m = createRequire(from)('puppeteer-core'); return m.default ?? m; } catch { /* next */ }
+  }
+  return null;
+}
+
+/** Launch; returns { browser, close } where close() also deletes the throwaway profile. */
+export async function launch(root, { width = 1920, height = 1080, extra = [] } = {}) {
+  const exe = chromePath();
+  if (!exe) throw new Error('no Chrome found (set CHROME_PATH to a Chrome or Chromium; on Linux, `npx --no-install homie-studio chrome install` in a studio fetches Chrome for Testing)');
+  const puppeteer = loadPuppeteer(root);
+  if (!puppeteer) throw new Error('puppeteer-core is not installed (it comes with @homie-rocks/studio: run npm install in the studio)');
+  const profile = mkdtempSync(join(tmpdir(), 'homie-video-'));
+  // 150 s for Chrome to start: on a loaded computer a cold start has taken over a minute.
+  const browser = await puppeteer.launch({
+    executablePath: exe, headless: true, userDataDir: profile, timeout: 150_000, protocolTimeout: 180_000,
+    args: [...GPU_FLAGS, `--window-size=${width},${height}`, '--hide-scrollbars', '--no-first-run', '--no-default-browser-check', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--force-color-profile=srgb', ...extra],
+  });
+  const close = async () => {
+    try { await Promise.race([browser.close(), new Promise((r) => setTimeout(r, 8000))]); } catch { /* */ }
+    try { browser.process()?.kill('SIGKILL'); } catch { /* */ }
+    rmSync(profile, { recursive: true, force: true });
+  };
+  return { browser, close, pid: browser.process()?.pid ?? null };
+}
+
+/** Render HTML to a PNG at an exact size (cards, contact sheets): text comes out right with no font setup. */
+export async function htmlToPng(root, html, out, { width, height }) {
+  const { browser, close } = await launch(root, { width, height });
+  try {
+    const page = await browser.newPage();
+    await page.setViewport({ width, height, deviceScaleFactor: 1 });
+    await page.setContent(html, { waitUntil: 'load' });
+    await page.evaluate(() => document.fonts?.ready);
+    await page.screenshot({ path: out, clip: { x: 0, y: 0, width, height } });
+  } finally { await close(); }
+  return out;
+}