easycaptionkit 0.0.0-stage → 0.1.1

package/skills/easycaptionkit/scripts/lib/cues.js

@@ -0,0 +1,317 @@
+"use strict";
+
+// Words into captions. A caption (a cue) is a run of words shown together,
+// at most `lines` lines of at most `maxChars` columns each. The cuts are
+// chosen over the whole text at once, by dynamic programming: a cue ends
+// best where a sentence ends, next best at a comma or a pause, and worst in
+// the middle of a phrase; a pause inside a cue costs, and so do cues that
+// are too short to read or too long to hold.
+
+const { width, characters, join, spaced, endsSentence, endsClause } = require("./text");
+
+const MAX_WORDS = 40;
+const PARTICLE = /^(?:は|が|を|に|で|と|も|へ|や|の|から|まで|より|けど|ので)$/u;
+const NO_LINE_START = /^(?:[ぁぃぅぇぉっゃゅょゎァィゥェォッャュョヮーゝゞヽヾ]|(?:は|が|を|に|で|と|も|へ|や|の|ね|よ)$)/u;
+// Reading speed people can follow, in characters a second, and the limit
+// past which a cue counts as fast (Netflix's for adult English programmes).
+const COMFORT_CPS = 17;
+const FAST_CPS = 20;
+
+// Japanese: a line or a caption does not start with a particle or a small
+// kana, and does not split a word the segmenter cut in two: kanji from the
+// kana that ends it (高|く) or the polite お and ご from what follows them
+// (お|兄さん).
+function badBreak(before, after) {
+  if (NO_LINE_START.test(after)) return true;
+  if (/\p{Script=Han}$/u.test(before) && /^\p{Script=Hiragana}/u.test(after)) return true;
+  return /^[おご]$/u.test(before) && /^\p{Script=Han}/u.test(after);
+}
+
+// Each word measured once: its columns, whether a space comes before it,
+// and what kind of break comes after it. A run of words then measures as
+// a difference of sums, without joining any text.
+function measure(texts) {
+  const n = texts.length;
+  const at = new Float64Array(n + 1);
+  const gap = new Uint8Array(n);
+  for (let k = 0; k < n; k++) {
+    gap[k] = k > 0 && spaced(texts[k - 1], texts[k]) ? 1 : 0;
+    at[k + 1] = at[k] + gap[k] + width(texts[k]);
+  }
+  const sentence = texts.map(endsSentence);
+  const clause = texts.map(endsClause);
+  const particle = texts.map((t) => PARTICLE.test(t));
+  const bad = texts.map((t, k) => k > 0 && badBreak(texts[k - 1], t));
+  const bads = new Uint32Array(n + 1);
+  for (let k = 0; k < n; k++) bads[k + 1] = bads[k] + (bad[k] ? 1 : 0);
+  return {
+    texts,
+    sentence,
+    clause,
+    particle,
+    bad,
+    // Columns of words i..j-1 on one line.
+    span: (i, j) => at[j] - at[i] - gap[i],
+    // Bad places to break between words i..j-1.
+    badInside: (i, j) => (j - i > 1 ? bads[j] - bads[i + 1] : 0),
+  };
+}
+
+// Whether words i..j-1 fit on `lines` lines of `maxChars` columns: filling
+// each line as far as it goes uses the fewest lines.
+function fits(m, i, j, lines, maxChars) {
+  let used = 1;
+  let start = i;
+  for (let k = i + 1; k <= j; k++) {
+    if (m.span(start, k) <= maxChars) continue;
+    if (k - 1 === start) return false;
+    used++;
+    start = k - 1;
+    if (used > lines || m.span(start, k) > maxChars) return false;
+  }
+  return true;
+}
+
+// The best cuts for words i..j-1 on at most `lines` lines: [] when they fit
+// on one, null when they do not fit at all; otherwise as few lines as fit,
+// balanced, and broken after punctuation when that costs little.
+function bestCuts(m, i, j, lines, maxChars) {
+  if (m.span(i, j) <= maxChars) return [];
+  if (lines < 2 || j - i < 2) return null;
+  let best = null;
+  const breakCost = (cut) => {
+    let cost = 0;
+    if (m.sentence[cut - 1]) cost -= 12;
+    else if (m.clause[cut - 1]) cost -= 8;
+    // A particle ends a phrase, which is a good place to break.
+    if (m.bad[cut]) cost += 30;
+    else if (m.particle[cut - 1]) cost -= 6;
+    return cost;
+  };
+  const score = (widths, cuts) => {
+    let cost = Math.max(...widths) - Math.min(...widths);
+    // A top line longer than the one under it reads worse than the other way.
+    for (let k = 0; k + 1 < widths.length; k++) if (widths[k] > widths[k + 1]) cost += 0.3 * (widths[k] - widths[k + 1]);
+    for (const cut of cuts) cost += breakCost(cut);
+    cost += widths.length * 50;
+    if (!best || cost < best.cost) best = { cost, cuts };
+  };
+  for (let a = i + 1; a < j; a++) {
+    const first = m.span(i, a);
+    if (first > maxChars) break;
+    const rest = m.span(a, j);
+    if (rest <= maxChars) score([first, rest], [a]);
+    if (lines < 3) continue;
+    for (let b = a + 1; b < j; b++) {
+      const second = m.span(a, b);
+      if (second > maxChars) break;
+      const third = m.span(b, j);
+      if (third <= maxChars) score([first, second, third], [a, b]);
+    }
+  }
+  return best ? best.cuts : null;
+}
+
+function linesAt(m, i, j, cuts) {
+  const bounds = [i, ...cuts, j];
+  return bounds.slice(1).map((end, k) => join(m.texts.slice(bounds[k], end)));
+}
+
+// The best way to set words on at most `lines` lines of `maxChars`
+// columns, or null when they do not fit. One line when they fit on one;
+// otherwise as few lines as fit, balanced, and broken after punctuation
+// when that costs little.
+function layout(texts, lines, maxChars) {
+  const m = measure(texts);
+  const cuts = bestCuts(m, 0, texts.length, lines, maxChars);
+  return cuts ? linesAt(m, 0, texts.length, cuts) : null;
+}
+
+// What a cue made of words[i..j) costs, the cut after it included.
+function cueCost(words, m, i, j, { maxChars, lines, blockEnd }) {
+  const last = words[j - 1];
+  const next = j < words.length ? words[j] : null;
+  let cost = 1;
+  if (next && !blockEnd) {
+    const pause = next.start - last.end;
+    if (m.sentence[j - 1]) cost += 0;
+    else if (m.clause[j - 1]) cost += pause > 0.25 ? 0.5 : 1.5;
+    else if (m.particle[j - 1]) cost += pause > 0.25 ? 1 : 2.5;
+    else if (pause >= 0.5) cost += 1.5;
+    else if (pause >= 0.25) cost += 3;
+    else cost += 6;
+    if (m.bad[j]) cost += 8;
+    if (next.seg !== last.seg && next.seg >= 0) cost -= 0.8;
+  }
+  for (let k = i; k < j - 1; k++) {
+    if (m.sentence[k]) cost += 2.5;
+    const pause = words[k + 1].start - words[k].end;
+    if (pause >= 0.7) cost += 4;
+    else if (pause >= 0.4) cost += 1.5;
+  }
+  const fill = m.span(i, j) / (lines * maxChars);
+  cost += 2 * (1 - Math.min(1, fill)) ** 2;
+  const duration = last.end - words[i].start;
+  if (duration < 0.7 && next && !blockEnd && !m.sentence[j - 1]) cost += 2;
+  return cost;
+}
+
+// Cuts one block of words (never joined with the next) into cues.
+function cutBlock(words, m, from, to, options) {
+  const { maxChars, lines, maxDuration } = options;
+  const n = to - from;
+  const best = new Array(n + 1).fill(Infinity);
+  const back = new Array(n + 1).fill(-1);
+  best[0] = 0;
+  for (let j = 1; j <= n; j++) {
+    for (let i = j - 1; i >= Math.max(0, j - MAX_WORDS); i--) {
+      const single = j - i === 1;
+      if (!single && !fits(m, from + i, from + j, lines, maxChars)) break;
+      const duration = words[from + j - 1].end - words[from + i].start;
+      if (duration > maxDuration && !single) break;
+      let cost = best[i] + cueCost(words, m, from + i, from + j, { maxChars, lines, blockEnd: from + j === to });
+      // A cue whose next one comes on as it does would never show.
+      if (from + j < to && words[from + j].start <= words[from + i].start) cost += 100;
+      // A caption whose lines can only break in a bad place costs as much
+      // as a bad cut between captions.
+      if (!single && m.badInside(from + i, from + j)) {
+        const cuts = bestCuts(m, from + i, from + j, lines, maxChars);
+        if (cuts && cuts.some((cut) => m.bad[cut])) cost += 8;
+      }
+      if (cost < best[j]) {
+        best[j] = cost;
+        back[j] = i;
+      }
+    }
+  }
+  const cuts = [];
+  for (let j = n; j > 0; j = back[j]) cuts.unshift([from + back[j], from + j]);
+  return cuts;
+}
+
+// Cues from words. options: { maxChars, lines, maxDuration, hard, duration }
+// where hard says segments are never joined, and duration (the video's
+// length) is where the last cue has to end.
+function buildCues(words, options) {
+  const opts = { maxDuration: 7, ...options };
+  const blocks = [];
+  let start = 0;
+  for (let k = 1; k <= words.length; k++) {
+    const gap = k < words.length ? words[k].start - words[k - 1].end : 0;
+    // Segments that come on at the same moment, like two steps of a demo
+    // at one time, are shown together: apart, the first would never show.
+    const segment = opts.hard && words[k] && words[k].seg !== words[k - 1].seg && words[k].start > words[start].start;
+    const boundary = k === words.length || segment || gap > 2.5;
+    if (boundary) {
+      blocks.push([start, k]);
+      start = k;
+    }
+  }
+  const m = measure(words.map((w) => w.text));
+  const cues = [];
+  for (const [from, to] of blocks) {
+    for (const [i, j] of cutBlock(words, m, from, to, opts)) {
+      const cuts = bestCuts(m, i, j, opts.lines, opts.maxChars) || [];
+      const lines = linesAt(m, i, j, cuts);
+      // cuts: where each line after the first starts, so the lines can be
+      // set again word by word without joining any text.
+      cues.push({ first: i, last: j - 1, start: words[i].start, end: words[j - 1].end, spoken: words[j - 1].end, lines, cuts, text: lines.join(" ") });
+    }
+  }
+  time(cues, opts);
+  cues.forEach((cue, i) => {
+    cue.n = i + 1;
+    cue.chars = characters(cue.lines.join("\n"));
+    cue.cps = cue.end > cue.start ? cue.chars / (cue.end - cue.start) : Infinity;
+    cue.wide = cue.lines.some((line) => width(line) > opts.maxChars);
+  });
+  return cues;
+}
+
+// When each cue shows. It comes on with its first word. A short gap to the
+// next cue is closed so the captions do not blink; a cue too short to read
+// is held longer where there is room; after the last word of a cue that
+// nothing follows soon, it stays a little. A cue the next one would
+// replace as it comes on still shows for a moment, and the next one comes
+// on after it: no cue ends where it starts.
+const BRIEF = 0.2;
+function time(cues, { duration = Infinity }) {
+  for (let i = 0; i < cues.length; i++) {
+    const cue = cues[i];
+    const next = cues[i + 1];
+    const until = Math.min(next ? next.start : Infinity, duration);
+    const want = Math.max(0.9, characters(cue.text) / COMFORT_CPS);
+    let end = Math.min(Math.max(cue.spoken + 0.4, cue.start + want), cue.spoken + 1.2);
+    if (next && next.start - end < 0.3) end = next.start;
+    cue.end = Math.max(cue.start, Math.min(end, until));
+    if (cue.end <= cue.start) {
+      cue.end = Math.min(cue.start + BRIEF, Math.max(duration, cue.start + 0.001));
+      if (next && next.start < cue.end) next.start = cue.end;
+    }
+  }
+}
+
+// A cue's lines as words: { t: the text, s: whether a space comes before
+// it, i: its place in the cue }. A cue made without its cuts has them
+// found again from its lines.
+function cueLines(cue, words) {
+  let cuts = cue.cuts;
+  if (!cuts) {
+    cuts = [];
+    let k = cue.first;
+    for (const line of cue.lines.slice(0, -1)) {
+      let built = "";
+      while (k <= cue.last && built.length < line.length) built = join([built, words[k++].text].filter(Boolean));
+      cuts.push(k);
+    }
+  }
+  const bounds = [cue.first, ...cuts, cue.last + 1];
+  return bounds.slice(1).map((end, n) => {
+    const line = [];
+    for (let k = bounds[n]; k < end; k++) line.push({ t: words[k].text, s: k > bounds[n] && spaced(words[k - 1].text, words[k].text), i: k - cue.first });
+    return line;
+  });
+}
+
+// The states a karaoke or word style shows, in time order: { from, to,
+// cue, word } where word is the index in the cue of the word that is lit,
+// or shown alone; -1 for the whole cue unlit. Between cues nothing shows.
+function states(cues, words, style) {
+  const out = [];
+  for (const [c, cue] of cues.entries()) {
+    if (style === "line") {
+      out.push({ from: cue.start, to: cue.end, cue: c, word: -1 });
+      continue;
+    }
+    const count = cue.last - cue.first + 1;
+    for (let k = 0; k < count; k++) {
+      const w = words[cue.first + k];
+      const from = k === 0 ? cue.start : Math.max(cue.start, w.start);
+      let to = k + 1 < count ? Math.max(from, words[cue.first + k + 1].start) : cue.end;
+      // A word shown alone does not stay up through a long pause.
+      if (style === "word" && to - w.end > 1.0) to = Math.max(from + 0.1, w.end + 1.0);
+      to = Math.min(to, cue.end);
+      if (to - from > 0.0005) out.push({ from, to, cue: c, word: k });
+    }
+  }
+  return out;
+}
+
+// Reading speed over all cues: the fastest, the median and the cues past
+// FAST_CPS, slowest last.
+function readingSpeed(cues) {
+  const speeds = cues.map((c) => c.cps).filter(Number.isFinite).sort((a, b) => a - b);
+  const median = speeds.length ? speeds[Math.floor(speeds.length / 2)] : 0;
+  const fast = cues.filter((c) => c.cps > FAST_CPS).sort((a, b) => b.cps - a.cps);
+  return {
+    limit: FAST_CPS,
+    comfort: COMFORT_CPS,
+    fastest: speeds.length ? round(speeds[speeds.length - 1], 1) : 0,
+    median: round(median, 1),
+    fast: fast.map((c) => ({ n: c.n, start: round(c.start, 3), end: round(c.end, 3), cps: round(c.cps, 1), text: c.text })),
+  };
+}
+
+const round = (value, places) => Math.round(value * 10 ** places) / 10 ** places;
+
+module.exports = { buildCues, layout, states, cueLines, readingSpeed, badBreak, FAST_CPS, COMFORT_CPS };

package/skills/easycaptionkit/scripts/lib/draw.js

@@ -0,0 +1,288 @@
+"use strict";
+
+// The pictures to look at: sheet.png, a frame of the captioned video for
+// each caption, and safe-zones.png, a frame under each place's buttons and
+// text, drawn where each app puts them, with the margins the captions keep
+// out of. Chrome lays them out; without Chrome, ffmpeg draws plainer ones.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { pathToFileURL } = require("node:url");
+const { launch, openPage, evaluate } = require("./chrome");
+const { frameAt, run, whyFailed } = require("./ffmpeg");
+const { writeApng } = require("./apng");
+const { clock } = require("./report");
+const esc = (text) => String(text).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+// The cues the sheet shows: all of them up to `most`, else spread evenly.
+function sheetCues(cues, most = 24) {
+  if (cues.length <= most) return cues;
+  const picked = [];
+  for (let i = 0; i < most; i++) picked.push(cues[Math.round((i * (cues.length - 1)) / (most - 1))]);
+  return [...new Set(picked)];
+}
+
+// When a cue is best seen: the middle of its spoken words.
+const momentOf = (cue) => Math.max(cue.start, Math.min(cue.end - 0.02, (cue.start + Math.max(cue.start + 0.05, cue.spoken)) / 2));
+
+// The frame of captioned.mp4 to show a cue with, from the times of its
+// frames: { seek, time }, the time of the frame that shows the cue nearest
+// its moment, and a time a moment before it to seek to, which lands on
+// it. Where no frame shows the cue, the one on screen at its moment.
+// Without the times, the moment itself, and the first frame after it.
+function shotOf(cue, times = []) {
+  const moment = momentOf(cue);
+  if (!times.length) return { seek: moment, time: moment };
+  // The first frame at or after t, as its index.
+  const at = (t) => {
+    let lo = 0;
+    let hi = times.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (times[mid] >= t - 0.0005) hi = mid;
+      else lo = mid + 1;
+    }
+    return lo;
+  };
+  const from = at(cue.start);
+  const to = at(cue.end);
+  let pick;
+  if (to > from) {
+    const i = Math.min(Math.max(at(moment), from), to - 1);
+    pick = i > from && moment - times[i - 1] < times[i] - moment ? i - 1 : i;
+  } else pick = Math.max(0, at(moment + 0.001) - 1);
+  return { seek: Math.max(0, times[pick] - 0.0005), time: times[pick] };
+}
+
+// Up to four ffmpeg runs at a time. Once one fails, no other starts.
+async function inPool(items, worker, size = 4) {
+  const out = new Array(items.length);
+  let next = 0;
+  let failed = false;
+  await Promise.all(
+    Array.from({ length: Math.min(size, items.length) }, async () => {
+      while (next < items.length && !failed) {
+        const i = next++;
+        try {
+          out[i] = await worker(items[i], i);
+        } catch (err) {
+          failed = true;
+          throw err;
+        }
+      }
+    }),
+  );
+  return out;
+}
+
+// ─── shapes of each app's buttons, in shares of its screen ────────────────
+
+// dot: a round button; bar: a line of text; band: a strip of controls.
+const UI = {
+  tiktok: [
+    ["bar", 0.3, 0.05, 0.16, 0.014], ["bar", 0.54, 0.05, 0.16, 0.014], ["dot", 0.93, 0.057, 0.03],
+    ["dot", 0.915, 0.49, 0.05], ["dot", 0.915, 0.575, 0.04], ["dot", 0.915, 0.645, 0.04], ["dot", 0.915, 0.715, 0.04], ["dot", 0.915, 0.785, 0.04], ["dot", 0.915, 0.87, 0.045],
+    ["bar", 0.04, 0.8, 0.3, 0.018], ["bar", 0.04, 0.83, 0.64, 0.013], ["bar", 0.04, 0.852, 0.5, 0.013], ["bar", 0.04, 0.88, 0.42, 0.013],
+    ["band", 0, 0.935, 1, 0.065],
+  ],
+  reels: [
+    ["bar", 0.05, 0.05, 0.18, 0.018], ["dot", 0.93, 0.058, 0.03],
+    ["dot", 0.92, 0.62, 0.04], ["dot", 0.92, 0.69, 0.04], ["dot", 0.92, 0.76, 0.04], ["dot", 0.92, 0.83, 0.035], ["dot", 0.92, 0.895, 0.04],
+    ["dot", 0.07, 0.8, 0.04], ["bar", 0.13, 0.79, 0.25, 0.018], ["bar", 0.04, 0.835, 0.66, 0.013], ["bar", 0.04, 0.858, 0.48, 0.013], ["bar", 0.04, 0.89, 0.4, 0.013],
+    ["band", 0, 0.935, 1, 0.065],
+  ],
+  shorts: [
+    ["dot", 0.82, 0.055, 0.03], ["dot", 0.93, 0.055, 0.03],
+    ["dot", 0.915, 0.55, 0.045], ["dot", 0.915, 0.625, 0.045], ["dot", 0.915, 0.7, 0.045], ["dot", 0.915, 0.775, 0.045], ["dot", 0.915, 0.85, 0.04],
+    ["dot", 0.07, 0.8, 0.04], ["bar", 0.13, 0.79, 0.22, 0.018], ["bar", 0.38, 0.787, 0.18, 0.026], ["bar", 0.04, 0.835, 0.66, 0.013], ["bar", 0.04, 0.858, 0.45, 0.013],
+    ["band", 0, 0.935, 1, 0.065],
+  ],
+  youtube: [["bar", 0.03, 0.04, 0.4, 0.04], ["band", 0, 0.885, 1, 0.115], ["bar", 0.02, 0.895, 0.96, 0.008]],
+  x: [["bar", 0.03, 0.9, 0.09, 0.055], ["dot", 0.95, 0.93, 0.05]],
+  "x-square": [["bar", 0.03, 0.935, 0.09, 0.04], ["dot", 0.95, 0.955, 0.04]],
+  "x-vertical": [["bar", 0.04, 0.8, 0.5, 0.014], ["bar", 0.04, 0.83, 0.7, 0.012], ["band", 0, 0.9, 1, 0.1]],
+  linkedin: [["band", 0, 0.88, 1, 0.12], ["bar", 0.15, 0.93, 0.6, 0.012]],
+  "linkedin-square": [["band", 0, 0.926, 1, 0.074], ["bar", 0.15, 0.955, 0.6, 0.012]],
+  "linkedin-vertical": [["dot", 0.9, 0.62, 0.045], ["dot", 0.9, 0.7, 0.045], ["dot", 0.9, 0.78, 0.045], ["bar", 0.04, 0.8, 0.55, 0.014], ["bar", 0.04, 0.83, 0.62, 0.012], ["band", 0, 0.92, 1, 0.08]],
+  square: [["dot", 0.06, 0.955, 0.04], ["dot", 0.94, 0.955, 0.04]],
+};
+
+// Each shape of a kind as a rectangle in a box of w by h: { x, y, w, h }.
+function uiRects(kind, w, h) {
+  return (UI[kind] || []).map(([type, x, y, a, b]) => (type === "dot" ? { x: x * w - (a * w) / 2, y: y * h - (a * w) / 2, w: a * w, h: a * w } : { x: x * w, y: y * h, w: a * w, h: b * h }));
+}
+
+function uiShapes(kind, box) {
+  return (UI[kind] || [])
+    .map(([type, x, y, a, b]) => {
+      if (type === "dot") {
+        const d = a * box.w;
+        return `<div class="ui dot" style="left:${box.x + x * box.w - d / 2}px;top:${box.y + y * box.h - d / 2}px;width:${d}px;height:${d}px"></div>`;
+      }
+      return `<div class="ui ${type}" style="left:${box.x + x * box.w}px;top:${box.y + y * box.h}px;width:${a * box.w}px;height:${b * box.h}px"></div>`;
+    })
+    .join("");
+}
+
+// One panel: the frame where the app shows it, the app's buttons over it,
+// the margins tinted and the space the captions may use outlined.
+function panel(zone, frame, video, height) {
+  if (zone.screen) {
+    const s = height / zone.screen.height;
+    const w = zone.screen.width * s;
+    const v = zone.screen.video;
+    const m = zone.reference.margins;
+    const box = { x: 0, y: 0, w, h: height };
+    const col = zone.reference.column;
+    const safe = { x: m.left * s, y: m.top * s, w: (zone.screen.width - m.left - m.right) * s, h: (zone.screen.height - m.top - m.bottom) * s };
+    return {
+      width: w,
+      html: `<div class="phone" style="width:${w}px;height:${height}px">
+        <img src="${frame}" style="left:${v.x * s}px;top:${v.y * s}px;width:${v.width * s}px;height:${v.height * s}px">
+        ${uiShapes(zone.ui, box)}
+        <div class="margin" style="left:0;top:0;width:${w}px;height:${m.top * s}px"></div>
+        <div class="margin" style="left:0;top:${height - m.bottom * s}px;width:${w}px;height:${m.bottom * s}px"></div>
+        <div class="margin" style="left:0;top:${m.top * s}px;width:${m.left * s}px;height:${safe.h}px"></div>
+        <div class="margin" style="left:${w - m.right * s}px;top:${m.top * s}px;width:${m.right * s}px;height:${safe.h}px"></div>
+        ${col ? `<div class="margin" style="left:${w - col.width * s}px;top:${col.from * s}px;width:${(col.width - m.right) * s}px;height:${Math.max(0, height - m.bottom * s - col.from * s)}px"></div>` : ""}
+        <div class="safe" style="left:${safe.x}px;top:${safe.y}px;width:${safe.w}px;height:${safe.h}px"></div>
+      </div>`,
+    };
+  }
+  const scale = Math.min(height / video.height, (height * 1.25) / video.width);
+  const w = video.width * scale;
+  const h = video.height * scale;
+  const m = zone.margins;
+  const box = { x: 0, y: 0, w, h };
+  return {
+    width: w,
+    html: `<div class="frame" style="width:${w}px;height:${h}px;margin-top:${(height - h) / 2}px">
+      <img src="${frame}" style="left:0;top:0;width:${w}px;height:${h}px">
+      ${uiShapes(zone.ui, box)}
+      <div class="margin" style="left:0;top:0;width:${w}px;height:${m.top * scale}px"></div>
+      <div class="margin" style="left:0;top:${h - m.bottom * scale}px;width:${w}px;height:${m.bottom * scale}px"></div>
+      <div class="margin" style="left:0;top:${m.top * scale}px;width:${m.left * scale}px;height:${h - (m.top + m.bottom) * scale}px"></div>
+      <div class="margin" style="left:${w - m.right * scale}px;top:${m.top * scale}px;width:${m.right * scale}px;height:${h - (m.top + m.bottom) * scale}px"></div>
+      <div class="safe" style="left:${m.left * scale}px;top:${m.top * scale}px;width:${w - (m.left + m.right) * scale}px;height:${h - (m.top + m.bottom) * scale}px"></div>
+    </div>`,
+  };
+}
+
+function marginsText(zone) {
+  const r = zone.reference;
+  const m = r.margins;
+  const column = r.column ? `, buttons ${r.column.width} px wide from ${r.column.from} px down` : "";
+  return `Top ${m.top}, bottom ${m.bottom}, left ${m.left}, right ${m.right} px of a ${r.width}x${r.height} ${zone.screen ? "screen" : "frame"}${column}.`;
+}
+
+const PAGE_CSS = `
+html, body { margin: 0; background: #15161a; color: #e9e7e1; font: 15px/1.4 "Helvetica Neue", Arial, "Liberation Sans", sans-serif; }
+.wrap { display: inline-flex; gap: 36px; padding: 32px; align-items: flex-start; }
+.cell { display: flex; flex-direction: column; gap: 12px; }
+.phone, .frame { position: relative; overflow: hidden; background: #000; }
+.phone { border-radius: 26px; box-shadow: 0 0 0 6px #2b2c31; }
+.frame { box-shadow: 0 0 0 2px #2b2c31; }
+img { position: absolute; display: block; }
+.ui { position: absolute; background: rgba(255, 255, 255, 0.78); box-shadow: 0 0 0 1.5px rgba(0, 0, 0, 0.55); }
+.ui.dot { border-radius: 50%; }
+.ui.bar { border-radius: 99px; }
+.ui.band { background: rgba(20, 20, 22, 0.72); box-shadow: none; }
+.margin { position: absolute; background: repeating-linear-gradient(135deg, rgba(255, 45, 45, 0.38) 0 6px, rgba(255, 45, 45, 0.12) 6px 12px); }
+.safe { position: absolute; outline: 2px dashed #7cff9b; outline-offset: -1px; }
+h2 { margin: 0; font-size: 18px; }
+p { margin: 0; color: #b9b6ad; font-size: 13px; }
+.note { padding: 0 32px 28px; color: #b9b6ad; font-size: 13px; max-width: 1400px; }
+.sheet { display: grid; gap: 14px; padding: 24px; }
+.shot { position: relative; }
+.shot img { position: static; display: block; }
+.shot b { position: absolute; left: 6px; top: 6px; background: rgba(0, 0, 0, 0.72); color: #fff; padding: 2px 7px; border-radius: 6px; font-size: 13px; }`;
+
+async function screenshotPage(html, file, dir, { width = 1600, height = 900 } = {}) {
+  const page = path.join(dir, `${path.basename(file, ".png")}-page.html`);
+  fs.writeFileSync(page, html);
+  const browser = await launch({ width, height });
+  try {
+    const tab = await openPage(browser, page, { width, height });
+    await evaluate(tab, "Promise.all([...document.images].map((i) => i.decode().catch(() => {}))).then(() => true)");
+    const size = await evaluate(tab, "({ w: Math.ceil(document.querySelector('.root').getBoundingClientRect().width), h: Math.ceil(document.querySelector('.root').getBoundingClientRect().height) })");
+    await tab.call("Emulation.setDeviceMetricsOverride", { width: Math.max(320, size.w), height: Math.max(200, size.h), deviceScaleFactor: 1, mobile: false });
+    const { data } = await tab.call("Page.captureScreenshot", { format: "png", captureBeyondViewport: true, clip: { x: 0, y: 0, width: size.w, height: size.h, scale: 1 } });
+    fs.writeFileSync(file, Buffer.from(data, "base64"));
+  } finally {
+    await browser.close();
+  }
+}
+
+// safe-zones.png: one frame of the captioned video under each place's
+// buttons, one that shows the caption that reaches widest. `times` are the
+// frames' times. The frames go to Chrome as PNG, converted to RGB with
+// captioned.mp4's own matrix: a JPEG is read as BT.601, and ffmpeg writes
+// the BT.709 picture of an HD video into one as it is, so its colors and
+// the lit word's came out shifted. `frameTags` are burn's, for frameAt:
+// a PNG of an SDR video names no primaries or transfer, which Chrome
+// would convert its colors by.
+async function safeZonesPng({ bins, video, output, zones, cue, times = [], file, dir, frameTags = {} }) {
+  const frame = await frameAt(bins, output, shotOf(cue, times).seek, path.join(dir, "zone-frame.png"), { width: Math.min(1080, video.width), ...frameTags });
+  const url = pathToFileURL(frame).href;
+  const cells = zones.map((zone) => {
+    const p = panel(zone, url, video, 640);
+    return `<div class="cell" style="width:${Math.max(p.width, 300)}px">${p.html}
+      <h2>${esc(zone.name)}</h2><p>${esc(marginsText(zone))}</p><p>From ${esc(zone.source)}, read ${esc(zone.read)}.</p>${zone.note ? `<p>${esc(zone.note)}</p>` : ""}</div>`;
+  });
+  const html = `<!doctype html><html><head><meta charset="utf-8"><style>${PAGE_CSS}</style></head><body><div class="root" style="display:inline-block">
+    <div class="wrap">${cells.join("")}</div>
+    <div class="note">Red: the margins each app covers with its buttons and text. Dashed green: where text is safe. The buttons are drawn roughly where each app puts them. Apps change their screens: check one post on a phone.</div>
+  </div></body></html>`;
+  await screenshotPage(html, file, dir);
+}
+
+// sheet.png: a frame of the captioned video for each caption, one that
+// shows it, with its number and the frame's time.
+async function sheetPng({ bins, video, output, cues, times = [], file, dir, frameTags = {} }) {
+  const picked = sheetCues(cues);
+  const shots = picked.map((cue) => shotOf(cue, times));
+  const thumb = video.width >= video.height ? 400 : 240;
+  const frames = await inPool(picked, (cue, i) => frameAt(bins, output, shots[i].seek, path.join(dir, `sheet-${String(i + 1).padStart(3, "0")}.png`), { width: thumb, ...frameTags }));
+  const columns = video.width >= video.height ? 4 : 6;
+  const cells = picked.map((cue, i) => `<div class="shot"><img src="${pathToFileURL(frames[i]).href}" width="${thumb}"><b>${cue.n} · ${clock(shots[i].time)}</b></div>`);
+  const html = `<!doctype html><html><head><meta charset="utf-8"><style>${PAGE_CSS}</style></head><body>
+    <div class="root sheet" style="display:inline-grid;grid-template-columns:repeat(${Math.min(columns, picked.length)}, ${thumb}px)">${cells.join("")}</div></body></html>`;
+  await screenshotPage(html, file, dir);
+  return picked.length;
+}
+
+// Without Chrome: the sheet as ffmpeg's tile of frames, and each place's
+// margins tinted over one frame with drawbox, side by side.
+async function plainPictures({ bins, video, output, cues, times = [], zones, cue, sheetFile, zonesFile, dir, frameTags = {} }) {
+  const picked = sheetCues(cues);
+  const thumb = video.width >= video.height ? 400 : 240;
+  const frames = await inPool(picked, (c, i) => frameAt(bins, output, shotOf(c, times).seek, path.join(dir, `sheet-${String(i + 1).padStart(3, "0")}.png`), { width: thumb, ...frameTags }));
+  const columns = Math.min(video.width >= video.height ? 4 : 6, frames.length);
+  const rows = Math.ceil(frames.length / columns);
+  // The frames as one animated PNG, read by its name from its folder, as
+  // the captions' states are.
+  const strip = path.join(dir, "sheet.apng");
+  writeApng(strip, frames.map((png) => ({ png, ms: 1000 })));
+  let r = await run(bins.ffmpeg, ["-hide_banner", "-nostdin", "-y", "-loglevel", "error", "-f", "apng", "-i", path.basename(strip), "-vf", `tile=${columns}x${rows}:padding=12:margin=12:color=0x15161a`, "-frames:v", "1", "-update", "1", path.resolve(sheetFile)], { cwd: dir });
+  if (r.code !== 0) throw new Error(`ffmpeg could not make sheet.png: ${whyFailed(r)}`);
+  const frame = await frameAt(bins, output, shotOf(cue, times).seek, path.join(dir, "zone-frame.png"), { width: 0, ...frameTags });
+  const inputs = [];
+  const parts = [];
+  zones.forEach((zone, i) => {
+    const m = zone.margins;
+    const box = (x, y, w, h) => `drawbox=x=${Math.round(x)}:y=${Math.round(y)}:w=${Math.max(1, Math.round(w))}:h=${Math.max(1, Math.round(h))}:color=red@0.25:t=fill`;
+    const W = video.out.width;
+    const H = video.out.height;
+    const boxes = [box(0, 0, W, m.top), box(0, H - m.bottom, W, m.bottom), box(0, m.top, m.left, H - m.top - m.bottom), box(W - m.right, m.top, m.right, H - m.top - m.bottom)];
+    if (zone.column) boxes.push(box(W - zone.column.width, zone.column.from, zone.column.width, Math.max(1, H - m.bottom - zone.column.from)));
+    boxes.push(`drawbox=x=${Math.round(m.left)}:y=${Math.round(m.top)}:w=${Math.round(W - m.left - m.right)}:h=${Math.round(H - m.top - m.bottom)}:color=0x7cff9b:t=4`);
+    inputs.push(...(frame.includes("%") ? ["-pattern_type", "none"] : []), "-i", frame);
+    parts.push(`[${i}:v]${boxes.join(",")},scale=-2:640,pad=iw+24:ih+24:12:12:color=0x15161a[p${i}]`);
+  });
+  const graph = zones.length > 1 ? `${parts.join(";")};${zones.map((_, i) => `[p${i}]`).join("")}hstack=inputs=${zones.length}[out]` : `${parts[0]};[p0]null[out]`;
+  r = await run(bins.ffmpeg, ["-hide_banner", "-nostdin", "-y", "-loglevel", "error", ...inputs, "-filter_complex", graph, "-map", "[out]", "-frames:v", "1", "-update", "1", zonesFile]);
+  if (r.code !== 0) throw new Error(`ffmpeg could not make safe-zones.png: ${whyFailed(r)}`);
+  return picked.length;
+}
+
+module.exports = { safeZonesPng, sheetPng, plainPictures, sheetCues, momentOf, shotOf, marginsText, uiRects, UI };