@homie-rocks/studio 0.51.4 → 0.51.6

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

@@ -0,0 +1,170 @@
+/**
+ * Honest frames and the page's own sound, shared by capture-game.mjs (a game's big screen) and record-page.mjs
+ * (any page, driven by a script):
+ *
+ *   startScreencast   the compositor's own frame stream (CDP Page.startScreencast): every frame kept as a JPEG
+ *                     with the time Chrome presented it.
+ *   constantRate      those frames onto a constant frame rate: output frame k shows the newest frame presented by
+ *                     t0 + k/fps. A frame the page did not paint in time is HELD (and counted), never invented: no
+ *                     interpolation, no blending.
+ *   TapReader         tap.js's copy of what a frame sends to its speaker (WebAudio), stamped with the audio clock.
+ *   fitAudio          that sound laid onto the picture's clock (a straight-line fit of the audio clock to the page's).
+ *   encodeMp4         H.264 (+ AAC when there was sound), limited-range BT.709 (converted and tagged), faststart.
+ *   BT709_TAIL        the end of a filter chain that makes a picture limited-range BT.709 yuv420p, and says so
+ *   BT709_FLAGS       the encoder flags that carry those tags into the file
+ *   frameSegments     an edit's segments as whole frames, each cut on the frame nearest its time
+ */
+import { spawnSync } from 'node:child_process';
+import { closeSync, openSync, readFileSync, rmSync, writeFileSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Start keeping every frame the compositor presents; `stop()` ends it. `frames` fills as they arrive. */
+export async function startScreencast(page, { dir, width, height, quality = 88 }) {
+  const frames = [];
+  const cdp = await page.createCDPSession();
+  cdp.on('Page.screencastFrame', (e) => {
+    const file = join(dir, `${String(frames.length).padStart(6, '0')}.jpg`);
+    writeFileSync(file, Buffer.from(e.data, 'base64'));
+    frames.push({ file, t: e.metadata.timestamp });
+    cdp.send('Page.screencastFrameAck', { sessionId: e.sessionId }).catch(() => {});
+  });
+  await cdp.send('Page.startScreencast', { format: 'jpeg', quality, maxWidth: width, maxHeight: height, everyNthFrame: 1 });
+  return { frames, stop: () => cdp.send('Page.stopScreencast').catch(() => {}) };
+}
+
+/**
+ * Frames (each `{ file, t }`, t in epoch seconds) onto a constant frame rate. `until` (epoch seconds) holds the last
+ * frame to that time: a page that did not change at the end still lasts as long as it was recorded.
+ */
+export function constantRate(frames, fps, { until = null } = {}) {
+  const sorted = [...frames].sort((a, b) => a.t - b.t);
+  const t0 = sorted[0].t;
+  const end = Math.max(sorted.at(-1).t, until ?? 0);
+  const total = Math.floor((end - t0) * fps);
+  const list = [];
+  let j = 0; let held = 0; let last = -1;
+  for (let k = 0; k < total; k++) {
+    const t = t0 + k / fps;
+    while (j + 1 < sorted.length && sorted[j + 1].t <= t + 1e-4) j++;
+    if (j === last) held++;
+    last = j;
+    list.push(sorted[j].file);
+  }
+  return { t0, total, list, held, distinct: new Set(list).size, frames: sorted };
+}
+
+/** An ffconcat list: each output frame for exactly 1/fps. */
+export function writeConcat(file, list, fps) {
+  writeFileSync(file, `ffconcat version 1.0\n${list.map((f) => `file '${f}'\nduration ${(1 / fps).toFixed(6)}`).join('\n')}\nfile '${list.at(-1)}'\n`);
+  return file;
+}
+
+/** Drains tap.js in one frame (window.__homieTap) into a raw 16-bit stereo file, with the audio clock's samples. */
+export class TapReader {
+  constructor(pcmFile) {
+    this.pcmFile = pcmFile;
+    this.fd = openSync(pcmFile, 'w');
+    this.pulls = []; this.clock = []; this.frames = 0; this.rate = null;
+  }
+
+  async poll(frame) {
+    const got = await frame.evaluate(() => ({ runs: window.__homieTap ? window.__homieTap.take() : [], c: window.__homieTap ? window.__homieTap.clock() : null }));
+    if (got.c) { this.clock.push(got.c); this.rate = got.c.rate ?? this.rate; }
+    for (const r of got.runs) {
+      this.pulls.push({ ctxFrame: r.f, fileFrame: this.frames, frames: r.frames });
+      writeSync(this.fd, Buffer.from(r.b64, 'base64'));
+      this.frames += r.frames;
+    }
+  }
+
+  close() { try { closeSync(this.fd); } catch { /* closed */ } }
+}
+
+/**
+ * The tap's sound onto the picture's clock, written as raw s16le stereo at the context's rate (`out`). Fits
+ * epoch(ms) = a + b * contextTime from the output timestamps (or the context clock against the wall when there are
+ * too few). Returns null when there was no sound to fit.
+ */
+export function fitAudio(tap, { t0, total, fps, out }) {
+  if (!(tap.frames > 0 && tap.rate)) return null;
+  const pts = tap.clock.filter((c) => c.ot && c.state === 'running').map((c) => c.ot);
+  const use = pts.length >= 8 ? pts : tap.clock.filter((c) => c.now != null).map((c) => [c.now, c.wall]);
+  const n = use.length; const mx = use.reduce((s, p) => s + p[0], 0) / n; const my = use.reduce((s, p) => s + p[1], 0) / n;
+  let sxy = 0; let sxx = 0; for (const [x, y] of use) { sxy += (x - mx) * (y - my); sxx += (x - mx) ** 2; }
+  // The audio clock runs at real time (a sound card drifts by parts per million). A straight line fitted over a short
+  // span of jittery timestamps can be percents off (measured: 1037.9 ms per second from 14 samples over 3.5 s), which
+  // walks the sound away from the picture; then only the offset is fitted (the median, which ignores outliers).
+  const span = use.length ? Math.max(...use.map((p) => p[0])) - Math.min(...use.map((p) => p[0])) : 0;
+  const line = sxx ? sxy / sxx : null;
+  const trust = line !== null && span >= 20 && Math.abs(line - 1000) < 2;
+  const b = trust ? line : 1000;
+  const offsets = use.map(([x, y]) => y - b * x).sort((p, q) => p - q);
+  const a = trust ? my - b * mx : offsets[Math.floor(offsets.length / 2)];
+  const raw = readFileSync(tap.pcmFile);
+  const src = new Int16Array(raw.buffer, raw.byteOffset, Math.floor(raw.byteLength / 2));
+  const outFrames = Math.round((total / fps) * tap.rate);
+  const dst = new Int16Array(outFrames * 2);
+  let filled = 0;
+  const pulls = [...tap.pulls].sort((x, y) => x.ctxFrame - y.ctxFrame);
+  let q = -1;
+  for (let i = 0; i < outFrames; i++) {
+    const epochMs = (t0 + i / tap.rate) * 1000;
+    const ctxT = (epochMs - a) / b;
+    const F = Math.round(ctxT * tap.rate);
+    while (q + 1 < pulls.length && pulls[q + 1].ctxFrame <= F) q++;
+    const p = q >= 0 ? pulls[q] : null;
+    if (!p || F - p.ctxFrame >= p.frames) continue;
+    const at = p.fileFrame + (F - p.ctxFrame);
+    dst[i * 2] = src[at * 2]; dst[i * 2 + 1] = src[at * 2 + 1]; filled++;
+  }
+  let peak = 0; for (let i = 0; i < dst.length; i++) peak = Math.max(peak, Math.abs(dst[i]));
+  writeFileSync(out, Buffer.from(dst.buffer));
+  const audio = { rate: tap.rate, seconds: +(outFrames / tap.rate).toFixed(3), covered: +(filled / Math.max(1, outFrames)).toFixed(3), peakDb: peak ? +(20 * Math.log10(peak / 32767)).toFixed(1) : null, fitMsPerS: +b.toFixed(3), fit: trust ? 'line' : 'offset', samples: use.length, raw: out };
+  if (!peak) audio.note = 'the page made no sound while it was recorded';
+  return audio;
+}
+
+/**
+ * The last filters of every picture this skill encodes: limited-range ("tv") BT.709 in yuv420p, with the frames
+ * tagged so. A frame that comes from a JPEG (every captured frame does) is FULL range with BT.601 coefficients.
+ * `format=yuv420p` alone changes neither: the encoder then writes a full-range file that ffprobe calls yuvj420p,
+ * with no primaries and no transfer tag, and a phone that assumes limited range shows it washed out or crushed.
+ * `-colorspace bt709` on the encoder only relabels the matrix without converting it. So: scale converts the
+ * range and the matrix from what the frame says it is, format picks the layout, setparams writes the tags.
+ */
+export const BT709_TAIL = 'scale=out_range=tv:out_color_matrix=bt709,format=yuv420p,setparams=range=tv:color_primaries=bt709:color_trc=bt709:colorspace=bt709';
+export const BT709_FLAGS = ['-pix_fmt', 'yuv420p', '-color_range', 'tv', '-color_primaries', 'bt709', '-color_trc', 'bt709', '-colorspace', 'bt709'];
+
+/**
+ * An edit's segments as whole frames. Each cut is put on the frame nearest its time in the music, and a segment
+ * is the frames between two cuts: 1.875 s at 30 fps is 56.25 frames, so the segments run 56, 56, 57, 56 … and
+ * no cut is ever more than half a frame from its beat.
+ *
+ * Trimming each segment by its duration instead (what this did before) rounds every segment by itself: nine
+ * 1.875 s segments came out a quarter of a frame short each, and the cuts walked away from a bed that plays at
+ * its own speed, up to five frames by the end of a trailer.
+ */
+export function frameSegments(segments, fps) {
+  let t = 0; let done = 0;
+  return segments.map((s) => {
+    t += s.dur;
+    const end = Math.round(t * fps + 1e-6);
+    const frames = Math.max(1, end - done);
+    const out = { startFrame: done, frames, at: t - s.dur };
+    done += frames;
+    return out;
+  });
+}
+
+/** The film: the concat list's frames at `fps`, scaled to w x h, with the fitted sound when it had any. */
+export function encodeMp4({ concat, audio, fps, width, height, seconds, out, crf = 16 }) {
+  const sound = audio?.peakDb != null;
+  const args = ['-hide_banner', '-loglevel', 'error', '-y', '-f', 'concat', '-safe', '0', '-i', concat];
+  if (sound) args.push('-f', 's16le', '-ar', String(audio.rate), '-ac', '2', '-i', audio.raw);
+  args.push('-map', '0:v', ...(sound ? ['-map', '1:a', '-c:a', 'aac', '-b:a', '256k', '-ar', '48000'] : []),
+    '-vf', `fps=${fps},scale=${width}:${height}:flags=lanczos,${BT709_TAIL}`, '-c:v', 'libx264', '-preset', 'medium', '-crf', String(crf), '-r', String(fps),
+    ...BT709_FLAGS, '-movflags', '+faststart', '-t', seconds.toFixed(3), out);
+  const r = spawnSync('ffmpeg', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  if (audio?.raw) rmSync(audio.raw, { force: true });
+  return { ok: r.status === 0, why: r.status === 0 ? null : (r.stderr ?? '').trim().split('\n').pop() };
+}

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

@@ -0,0 +1,159 @@
+/**
+ * The sound of a film that was rendered frame by frame, rebuilt offline.
+ *
+ * A page stepped on a virtual clock (record-fixed.mjs) has no speaker worth recording: its audio clock
+ * runs at the wall's speed while the picture runs at the film's. What it has is the capture log the sound
+ * player keeps when a recorder asks (sound.js: window.__homieSoundCapture): every sound it scheduled, with
+ * the file, the gain, the rate, the pan, the loop and the time. This mixes those events again, from the
+ * game's own files, onto the film's clock:
+ *
+ *   start   the file decoded (ffmpeg), resampled by its playback rate, panned, faded in, looped
+ *   stop    a hard cut, a straight fade, or the exponential fall of setTargetAtTime (time constant fade / 3)
+ *   duck    the music bus down to `to` (time constant 15 ms) and back after `seconds` (120 ms)
+ *   levels  the master, effect and music faders (and mute), smoothed as the player smooths them
+ *
+ * Out: three stereo buffers at 48 kHz: `sfx`, `music` (after the duck and its fader) and `mix`, so an
+ * edit can keep the music running under shots whose own effects are cut with the picture.
+ *
+ * What it is NOT: a recording. The player's safety compressor (threshold -6 dB, ratio 8) is stood in for
+ * by a peak limiter at -1 dBFS that only acts when the sum goes over; anything the game plays outside
+ * the log (its own oscillators, an <audio> element, speech synthesis) is not in the mix at all.
+ */
+import { run } from '../../../music/scripts/lib/audio.mjs';
+import { dbToGain, limit } from '../../../sound/scripts/lib/synth.mjs';
+
+export const MIX_RATE = 48000;
+
+/** A sound file as float stereo at 48 kHz, with how many channels the file really has (a mono file pans differently). */
+export function decodeFile(file) {
+  const p = run('ffprobe', ['-v', 'error', '-select_streams', 'a:0', '-show_entries', 'stream=channels', '-of', 'csv=p=0', file]);
+  const channels = Number(String(p.stdout).trim()) || 2;
+  const out = run('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-i', file, '-vn', '-ac', '2', '-ar', String(MIX_RATE), '-f', 'f32le', '-']);
+  if (out.code !== 0) throw new Error(`ffmpeg could not decode ${file}: ${out.stderr.trim().split('\n').pop()}`);
+  const b = out.stdout;
+  const all = new Float32Array(b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength - (b.byteLength % 8)));
+  const n = all.length / 2;
+  const L = new Float32Array(n); const R = new Float32Array(n);
+  for (let i = 0; i < n; i++) { L[i] = all[2 * i]; R[i] = all[2 * i + 1]; }
+  return { L, R, channels };
+}
+
+/** A fader the player moves with setTargetAtTime: a list of { at (s), to, tc (s) } read as one smoothed curve. */
+function fader(moves, n, first = 1) {
+  const out = new Float32Array(n);
+  const list = [...moves].sort((a, b) => a.at - b.at);
+  let v = first; let target = first; let k = 0; let coef = 0;
+  for (let i = 0; i < n; i++) {
+    const t = i / MIX_RATE;
+    while (k < list.length && list[k].at <= t) { target = list[k].to; coef = 1 - Math.exp(-1 / (Math.max(1e-4, list[k].tc) * MIX_RATE)); k++; }
+    v += (target - v) * coef;
+    out[i] = v;
+  }
+  return out;
+}
+
+/**
+ * Mix a capture log. `events` have `t` in SECONDS on the film's clock (the recorder converts them);
+ * `fileFor(url)` gives the local copy of a file, or null. Returns { sfx, music, mix, report }.
+ */
+export function remix(events, { seconds, fileFor, decode = decodeFile }) {
+  const n = Math.max(1, Math.round(seconds * MIX_RATE));
+  const sfx = { L: new Float32Array(n), R: new Float32Array(n) };
+  const music = { L: new Float32Array(n), R: new Float32Array(n) };
+  const cache = new Map();
+  const missing = new Set();
+  const stops = new Map();
+  for (const e of events) if (e.type === 'stop' && e.id != null && !stops.has(e.id)) stops.set(e.id, e);
+  let placed = 0; let dropped = 0;
+  for (const e of events) {
+    if (e.type === 'drop') { dropped++; continue; }
+    if (e.type !== 'start') continue;
+    const file = fileFor(e.url);
+    if (!file) { missing.add(e.url); continue; }
+    if (!cache.has(file)) { try { cache.set(file, decode(file)); } catch { cache.set(file, null); } }
+    const src = cache.get(file);
+    if (!src || !src.L.length) { missing.add(e.url); continue; }
+    const bus = e.bus === 'music' ? music : sfx;
+    const from = e.t + (e.delay ?? 0);
+    const rate = Number(e.rate) > 0 ? Number(e.rate) : 1;
+    const gain = Number(e.gain ?? 1);
+    // The player's panner: a mono file is placed between the speakers at equal power; a stereo one has the far
+    // channel folded into the near one. With no pan there is no panner, and a mono file plays in both at full level.
+    const pan = Math.max(-1, Math.min(1, Number(e.pan) || 0));
+    let ll = 1; let lr = 0; let rl = 0; let rr = 1;
+    if (pan !== 0 && src.channels === 1) { const x = ((pan + 1) / 2) * (Math.PI / 2); ll = Math.cos(x); rr = Math.sin(x); lr = 0; rl = 0; }
+    else if (pan < 0) { const x = (pan + 1) * (Math.PI / 2); ll = 1; lr = Math.cos(x); rl = 0; rr = Math.sin(x); }
+    else if (pan > 0) { const x = pan * (Math.PI / 2); ll = Math.cos(x); lr = 0; rl = Math.sin(x); rr = 1; }
+    const stop = stops.get(e.id) ?? null;
+    const stopAt = stop ? stop.t + (stop.delay ?? 0) : Infinity;
+    const fade = stop ? Math.max(0, Number(stop.fade) || 0) : 0;
+    const endAt = !stop ? Infinity : stop.curve === 'target' ? stopAt + fade + 0.1 : stop.curve === 'linear' ? stopAt + fade : stopAt;
+    const fadeIn = Math.max(0, Number(e.fadeIn) || 0);
+    const len = src.L.length;
+    const i0 = Math.max(0, Math.round(from * MIX_RATE));
+    for (let i = i0; i < n; i++) {
+      const t = i / MIX_RATE;
+      if (t >= endAt) break;
+      let pos = (i - from * MIX_RATE) * rate;
+      if (pos < 0) continue;
+      if (e.loop) pos %= len; else if (pos >= len - 1) break;
+      const a = Math.floor(pos); const f = pos - a; const b = e.loop ? (a + 1) % len : a + 1;
+      let g = gain;
+      if (fadeIn > 0 && t - from < fadeIn) g *= (t - from) / fadeIn;
+      if (t >= stopAt) {
+        if (stop.curve === 'linear') g *= Math.max(0, 1 - (t - stopAt) / Math.max(1e-4, fade));
+        else if (stop.curve === 'target') g *= Math.exp(-(t - stopAt) / Math.max(1e-4, fade / 3));
+      }
+      const l = (src.L[a] + (src.L[b] - src.L[a]) * f) * g;
+      const r = (src.R[a] + (src.R[b] - src.R[a]) * f) * g;
+      if (src.channels === 1 && pan !== 0) { bus.L[i] += l * ll; bus.R[i] += l * rr; } else { bus.L[i] += l * ll + r * lr; bus.R[i] += l * rl + r * rr; }
+    }
+    placed++;
+  }
+  // The faders, as the player moves them. Before the first `levels` event the player's own defaults hold.
+  const lv = events.filter((e) => e.type === 'levels');
+  const first = lv[0] ?? { master: 1, sfx: 1, music: 0.7, muted: false };
+  const master = fader(lv.map((e) => ({ at: e.t, to: e.muted ? 0 : e.master, tc: 0.02 })), n, first.muted ? 0 : first.master);
+  const sfxG = fader(lv.map((e) => ({ at: e.t, to: e.sfx, tc: 0.02 })), n, first.sfx);
+  const musG = fader(lv.map((e) => ({ at: e.t, to: e.music, tc: 0.05 })), n, first.music);
+  const duck = fader(events.filter((e) => e.type === 'duck').flatMap((e) => [{ at: e.t, to: e.to, tc: 0.015 }, { at: e.t + e.seconds, to: 1, tc: 0.12 }]), n, 1);
+  const mix = { L: new Float32Array(n), R: new Float32Array(n) };
+  for (let i = 0; i < n; i++) {
+    const s = sfxG[i] * master[i]; const m = musG[i] * duck[i] * master[i];
+    sfx.L[i] *= s; sfx.R[i] *= s; music.L[i] *= m; music.R[i] *= m;
+    mix.L[i] = sfx.L[i] + music.L[i]; mix.R[i] = sfx.R[i] + music.R[i];
+  }
+  let peak = 0; for (let i = 0; i < n; i++) { const p = Math.max(Math.abs(mix.L[i]), Math.abs(mix.R[i])); if (p > peak) peak = p; }
+  const ceiling = dbToGain(-1);
+  const limited = peak > ceiling;
+  if (limited) limit(mix, { ceiling, releaseMs: 150 });
+  return {
+    sfx, music, mix,
+    report: {
+      seconds: n / MIX_RATE, placed, dropped, files: cache.size, missing: [...missing],
+      peakDb: peak > 0 ? +(20 * Math.log10(peak)).toFixed(1) : null, limited,
+      note: 'Rebuilt from the game\'s own sound files and its log of what it scheduled; the player\'s compressor is stood in for by a peak limiter at -1 dBFS. Sound the game makes outside the log is not here.',
+    },
+  };
+}
+
+/**
+ * Where the highlights are, by what the game played: each effect's start counts, a rare sound more than a
+ * common one (one win outweighs fifty footsteps), a louder one more than a quiet one. Returns a score for
+ * every tenth of a second (the same grid as the picture's motion), and the events by tenth.
+ */
+export function eventScores(events, seconds) {
+  const n = Math.max(1, Math.ceil(seconds * 10));
+  const scores = new Float32Array(n);
+  const names = Array.from({ length: n }, () => []);
+  const starts = events.filter((e) => e.type === 'start' && e.bus !== 'music');
+  const count = new Map();
+  for (const e of starts) count.set(e.name, (count.get(e.name) ?? 0) + 1);
+  for (const e of starts) {
+    const k = Math.floor((e.t + (e.delay ?? 0)) * 10);
+    if (k < 0 || k >= n) continue;
+    scores[k] += Math.min(1.5, Math.max(0.2, Number(e.gain ?? 1))) / Math.sqrt(count.get(e.name));
+    names[k].push(e.name);
+  }
+  return { scores, names };
+}

package/guides/video/scripts/qa.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * qa.mjs: check a finished video file before anyone sees it, from the decoded file itself (an
+ * encoder that exits 0 has not proved the picture is there).
+ *
+ *   node qa.mjs <video.mp4> [--kind trailer|clip|music-video] [--max-mb 25] [--json]
+ *
+ * It decodes every frame (errors are counted), reads the streams (codec, size, frame rate, pixel
+ * format, BT.709 colour tags), checks the file starts playing before it has downloaded (faststart:
+ * the moov atom before the media data), finds black stretches and frozen stretches, measures the
+ * loudness and true peak, finds silent stretches, and checks the size against the studio site's
+ * 25 MiB file limit. PASS, WARN or FAIL, each with the fix.
+ */
+import { spawnSync } from 'node:child_process';
+import { closeSync, existsSync, openSync, readSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const argv = process.argv.slice(2);
+const flags = new Map(); const pos = [];
+for (let i = 0; i < argv.length; i++) { const a = argv[i]; if (a.startsWith('--')) { const v = argv[i + 1]; if (v === undefined || v.startsWith('--')) flags.set(a.slice(2), true); else { flags.set(a.slice(2), v); i++; } } else pos.push(a); }
+
+const run = (cmd, args) => spawnSync(cmd, args, { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+
+/** Top-level MP4 atoms in order (enough to see whether moov comes before mdat). */
+function atoms(file) {
+  const fd = openSync(file, 'r');
+  const size = statSync(file).size;
+  const out = [];
+  try {
+    let at = 0;
+    const head = Buffer.alloc(16);
+    while (at + 8 <= size && out.length < 64) {
+      readSync(fd, head, 0, 16, at);
+      let len = head.readUInt32BE(0);
+      const type = head.toString('latin1', 4, 8);
+      if (len === 1) len = Number(head.readBigUInt64BE(8));
+      else if (len === 0) len = size - at;
+      if (len < 8) break;
+      out.push(type);
+      at += len;
+    }
+  } finally { closeSync(fd); }
+  return out;
+}
+
+export function qa(file, { kind = 'trailer', maxMb = 25 } = {}) {
+  if (!existsSync(file)) throw new Error(`no such file: ${file}`);
+  const fails = []; const warns = [];
+  const pr = run('ffprobe', ['-v', 'error', '-show_entries', 'format=duration,size,format_name:stream=codec_type,codec_name,width,height,r_frame_rate,avg_frame_rate,pix_fmt,color_primaries,color_transfer,color_space,sample_rate,channels', '-of', 'json', file]);
+  if (pr.status !== 0) throw new Error(`ffprobe could not read it: ${pr.stderr.trim().split('\n').pop()}`);
+  const j = JSON.parse(pr.stdout);
+  const v = (j.streams ?? []).find((s) => s.codec_type === 'video');
+  const a = (j.streams ?? []).find((s) => s.codec_type === 'audio');
+  const duration = Number(j.format?.duration ?? 0);
+  const mb = +(Number(j.format?.size ?? statSync(file).size) / 1024 / 1024).toFixed(2);
+  if (!v) fails.push('no video stream');
+  const [fn, fd] = String(v?.avg_frame_rate ?? v?.r_frame_rate ?? '0/1').split('/').map(Number);
+  const fps = fd ? +(fn / fd).toFixed(3) : null;
+  if (v && v.codec_name !== 'h264') warns.push(`video codec ${v.codec_name}: H.264 plays on every phone and in every browser`);
+  if (v && v.pix_fmt !== 'yuv420p') fails.push(`pixel format ${v.pix_fmt}: Safari and many phones need yuv420p${/^yuvj/.test(String(v.pix_fmt)) ? ' in limited range; this file is FULL range, which -pix_fmt alone does not change: convert it (scale=out_range=tv:out_color_matrix=bt709,format=yuv420p, with -color_range tv), as `cut` does' : ' (-pix_fmt yuv420p)'}`);
+  if (v && (v.width % 2 || v.height % 2)) fails.push(`odd frame size ${v.width}x${v.height}: H.264 needs even sizes`);
+  if (v && (v.color_primaries !== 'bt709' || v.color_transfer !== 'bt709' || v.color_space !== 'bt709')) warns.push(`colour tags ${v.color_primaries ?? 'unset'}/${v.color_transfer ?? 'unset'}/${v.color_space ?? 'unset'}: tag BT.709 (-colorspace bt709 -color_primaries bt709 -color_trc bt709) or players guess and the colours shift`);
+  const ratio = v ? v.width / v.height : null;
+  const shape = ratio === null ? null : Math.abs(ratio - 16 / 9) < 0.02 ? '16:9' : Math.abs(ratio - 9 / 16) < 0.02 ? '9:16' : Math.abs(ratio - 1) < 0.02 ? '1:1' : `${v.width}x${v.height}`;
+  if (shape && !['16:9', '9:16', '1:1'].includes(shape)) warns.push(`frame ${shape}: deliver 16:9 (1920x1080) and, for vertical feeds, 9:16 (1080x1920)`);
+  if (fps !== null && (fps < 23.9 || fps > 60.1)) warns.push(`${fps} fps: deliver 24, 25, 30 or 60`);
+  const at = atoms(file);
+  const moov = at.indexOf('moov'); const mdat = at.indexOf('mdat');
+  const faststart = moov >= 0 && (mdat < 0 || moov < mdat);
+  if (!faststart) fails.push('not faststart (the index is at the end): a phone downloads the whole file before playing; re-mux with -movflags +faststart');
+  if (mb > maxMb) fails.push(`${mb} MB is over the ${maxMb} MB a studio site serves itself: a lower bitrate, or the studio's storage`);
+  // A full decode: every frame, every error counted.
+  const dec = run('ffmpeg', ['-hide_banner', '-v', 'error', '-i', file, '-f', 'null', '-']);
+  const decodeErrors = String(dec.stderr).split('\n').filter(Boolean);
+  if (decodeErrors.length) fails.push(`${decodeErrors.length} decode error(s), first: ${decodeErrors[0].slice(0, 160)}`);
+  // Black and frozen stretches, silence, loudness: one pass.
+  const filters = ['-vf', 'blackdetect=d=0.4:pix_th=0.08,freezedetect=n=0.002:d=1.5'];
+  const af = a ? ['-af', 'ebur128=peak=true,silencedetect=n=-50dB:d=1.0'] : [];
+  const det = run('ffmpeg', ['-hide_banner', '-nostats', '-i', file, ...filters, ...af, '-f', 'null', '-']);
+  const text = String(det.stderr);
+  const blacks = [...text.matchAll(/black_start:([\d.]+) black_end:([\d.]+) black_duration:([\d.]+)/g)].map((m) => ({ from: +m[1], to: +m[2], seconds: +m[3] }));
+  const freezes = []; let fStart = null;
+  for (const line of text.split('\n')) {
+    const s = /freeze_start: ([\d.]+)/.exec(line); if (s) fStart = +s[1];
+    const e = /freeze_end: ([\d.]+)/.exec(line); if (e && fStart !== null) { freezes.push({ from: fStart, to: +e[1], seconds: +(+e[1] - fStart).toFixed(2) }); fStart = null; }
+  }
+  if (fStart !== null) freezes.push({ from: fStart, to: duration, seconds: +(duration - fStart).toFixed(2) });
+  const silences = [...text.matchAll(/silence_start: ([\d.]+)[\s\S]*?silence_end: ([\d.]+) \| silence_duration: ([\d.]+)/g)].map((m) => ({ from: +m[1], to: +m[2], seconds: +m[3] }));
+  const sum = text.slice(text.lastIndexOf('Summary:'));
+  const lufs = /I:\s+(-?[\d.]+) LUFS/.exec(sum); const tp = /Peak:\s+(-?[\d.]+) dBFS/.exec(sum);
+  const loud = { lufs: lufs ? Number(lufs[1]) : null, truePeakDb: tp ? Number(tp[1]) : null };
+  // A fade from or to black at the very ends is a choice; black in the middle is a hole.
+  const midBlack = blacks.filter((b) => b.from > 0.3 && b.to < duration - 0.3);
+  if (midBlack.length) warns.push(`${midBlack.length} black stretch(es) inside it, first at ${midBlack[0].from}s for ${midBlack[0].seconds}s: a capture that lost the picture, or a cut to nothing`);
+  if (blacks.some((b) => b.seconds > duration * 0.5)) fails.push('more than half of it is black');
+  const longFreeze = freezes.filter((f) => f.seconds >= (kind === 'music-video' ? 3 : 1.5));
+  if (longFreeze.length) warns.push(`${longFreeze.length} frozen stretch(es), first at ${longFreeze[0].from}s for ${longFreeze[0].seconds}s: held frames from a capture that could not keep up, or a still left too long (a card is fine: check it is one)`);
+  if (!a) warns.push('no sound: a trailer without sound loses most of its effect; a muted social clip needs captions instead');
+  else {
+    if (loud.lufs !== null && (loud.lufs < -18 || loud.lufs > -10)) warns.push(`loudness ${loud.lufs} LUFS: deliver about -14 LUFS for the web and social`);
+    if (loud.truePeakDb !== null && loud.truePeakDb > -1) warns.push(`true peak ${loud.truePeakDb} dBTP: keep it under -1 dBTP or it clips after the platform re-encodes it`);
+    const midSilence = silences.filter((s) => s.from > 0.5 && s.to < duration - 0.5);
+    if (midSilence.length) warns.push(`${midSilence.length} silent stretch(es), first at ${midSilence[0].from}s for ${midSilence[0].seconds}s`);
+  }
+  const verdict = fails.length ? 'FAIL' : warns.length ? 'WARN' : 'PASS';
+  return {
+    ok: !fails.length, command: 'qa', verdict, file, seconds: +duration.toFixed(3), mb, shape, fps,
+    video: v ? { codec: v.codec_name, size: `${v.width}x${v.height}`, pixFmt: v.pix_fmt, colour: `${v.color_primaries ?? '-'}/${v.color_transfer ?? '-'}/${v.color_space ?? '-'}` } : null,
+    audio: a ? { codec: a.codec_name, rate: Number(a.sample_rate), channels: a.channels, ...loud } : null,
+    faststart, decodeErrors: decodeErrors.length, blacks, freezes, silences: silences.slice(0, 10),
+    fails, warnings: warns,
+    look: 'QA is not a review: open the contact sheet (video.mjs sheet) and watch it once, start to end, before anyone else does',
+  };
+}
+
+if (process.argv[1]?.endsWith('qa.mjs')) {
+  try {
+    const file = resolve(String(pos[0] ?? ''));
+    const r = qa(file, { kind: String(flags.get('kind') ?? 'trailer'), maxMb: Number(flags.get('max-mb') ?? 25) });
+    if (flags.has('json')) process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+    else process.stdout.write(`${r.verdict}: ${r.file} (${r.seconds}s, ${r.shape}, ${r.fps} fps, ${r.mb} MB${r.audio ? `, ${r.audio.lufs} LUFS, ${r.audio.truePeakDb} dBTP` : ''})\n${[...r.fails.map((f) => `  FAIL  ${f}`), ...r.warnings.map((w) => `  WARN  ${w}`)].join('\n')}\n`);
+    if (!r.ok) process.exitCode = 1;
+  } catch (error) {
+    process.stdout.write(`qa: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}