@crievo/omni 0.0.0-stage → 0.1.0

package/tools/build-motion.mjs

@@ -0,0 +1,437 @@
+#!/usr/bin/env node
+/* ============================================================================
+   Builds each scene's final HTML from motion/src/<id>.html, with the beat
+   times already computed, and optionally renders.
+
+     node tools/build-motion.mjs videos/<slug>                 HTML only
+     node tools/build-motion.mjs videos/<slug> --stills        + a still per scene
+     node tools/build-motion.mjs videos/<slug> --sheets        + contact sheet at the beats
+     node tools/build-motion.mjs videos/<slug> --transitions   + a sheet for each cut between scenes
+     node tools/build-motion.mjs videos/<slug> --render        + final MP4 (needs real timing;
+                                                               waits for the machine queue turn)
+     node tools/build-motion.mjs videos/<slug> --scene c02     only that scene (and its two cuts); the
+                                                               neighbours are built into temporary files, so
+                                                               scenes composed in parallel never overwrite
+                                                               each other's HTML
+
+   The source scene never writes seconds for a beat. It uses the beat variable:
+
+     <div data-anim style="animation-name:rise; --start:var(--b-barra-jev);">
+     <div data-anim style="animation-name:rise; --start:calc(var(--b-titulo) + 120ms);">
+
+   (based on templates/scene.html) and this script injects before </head>:
+
+     <style id="omnivideo-beats">:root{ --b-titulo:0.4s; --b-barra-jev:5.767s; --scene-dur:7.6s;
+       --scene-start:12.4s; --video-dur:41.2s; }</style>
+     <script id="omnivideo-data">window.OMNIVIDEO = { scene, start, duration, total_duration, provisional, beats, lines, video }</script>
+
+   GSAP and Motion read window.OMNIVIDEO.beats to position the paused timeline.
+   `video` is the overview of every scene in video seconds (beats, lines and
+   words): what a continuous composition uses, drawn once in _common.html and
+   positioned at OMNIVIDEO.start + t.
+
+   Legacy names (scene sources written before the English rename) keep
+   working: the PT keys of OMNIVIDEO (cena, inicio, duracao, duracao_total,
+   provisorio, falas[{texto, inicio, fim, palavras}], video{duracao_total,
+   cenas}), --cena-dur / --cena-inicio, <!-- omnivideo:comum -->,
+   motion/src/_comum.html and [data-continua].
+
+   Continuity between scenes:
+   - `--scene-start` is the video second where the scene starts. Background and
+     camera that cross the cut move in video time
+     (`--start:calc(0s - var(--scene-start))`), not scene time; otherwise they
+     restart at every cut.
+   - motion/src/_common.html, if present, replaces <!-- omnivideo:common -->
+     in every scene: the same background, same code, across the whole video.
+     motion/src/_common.<id>.html (a scene's own part, written by that scene
+     when the composition runs in parallel) is pasted right after it, in scene
+     order, so no two scenes edit the same file.
+   - --transitions draws each cut (the outgoing scene at the cut instant | the
+     incoming one at its first frame | both overlaid) and, if the scene
+     declares `transition: { continues: [...] }`, measures the
+     [data-continues] on both sides.
+   ============================================================================ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, renameSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, resolve, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { loadVideo, beatTime } from "./timing.mjs";
+import { turn } from "./job-queue.mjs";
+import { keepPrevious } from "./history.mjs";
+import { CODE_ROOT, DATA_ROOT as ROOT } from "./lib/paths.mjs";
+
+const CFG = JSON.parse(readFileSync(join(ROOT, "omnivideo.config.json"), "utf8"));
+
+const args = process.argv.slice(2);
+const dir = resolve(args[0] ?? "");
+const flag = n => args.includes(`--${n}`);
+const onlyScene = args.includes("--scene") ? args[args.indexOf("--scene") + 1] : null;
+if (!args[0] || !existsSync(join(dir, "scenes.json"))) {
+  console.error(
+    "uso: node tools/build-motion.mjs videos/<slug> [--stills] [--sheets] [--transitions] [--render] [--scene cNN]",
+  );
+  process.exit(2);
+}
+
+let video = loadVideo(dir);
+function requireRealTiming() {
+  if (flag("render") && video.provisional) {
+    console.error(
+      "erro: o render final precisa do tempo real da voz. Rode antes:\n" +
+        "  omnivideo.py voice → omnivideo.py timing  (e omnivideo.py captions, para beats em palavras)",
+    );
+    process.exit(1);
+  }
+}
+requireRealTiming();
+/* the final render takes the machine: wait for the queue turn (tools/job-queue.mjs)
+   and reload scenes.json, which may have changed while waiting */
+if (flag("render")) {
+  await turn("render", dir);
+  video = loadVideo(dir);
+  requireRealTiming();
+}
+const { w, h, fps } = video.format;
+const HOLD = 0.6;
+const TOL_PX = 2; /* a continuing element may not jump more than this at the cut */
+const MARKER = "<!-- omnivideo:common -->";
+const selected = id => !onlyScene || onlyScene === id;
+
+function render(...a) {
+  const r = spawnSync(
+    "node",
+    [
+      resolve(CODE_ROOT, CFG.motion.render ?? "tools/render.mjs"),
+      ...a,
+      "--w",
+      String(w),
+      "--h",
+      String(h),
+      "--jobs",
+      String(CFG.motion.jobs ?? 3),
+    ],
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  if (r.status !== 0) throw new Error(r.stderr.toString() || `render.mjs saiu com ${r.status}`);
+  return r.stdout.toString();
+}
+
+/* _comum.html = legacy name of _common.html. The scenes' own parts
+   (_common.<id>.html, parallel composition) follow it in scene order. */
+const commonFile = ["_common.html", "_comum.html"].map(f => join(dir, "motion", "src", f)).find(existsSync) ?? null;
+const commonParts = [
+  ...(commonFile ? [commonFile] : []),
+  ...video.scenes.map(s => join(dir, "motion", "src", `_common.${s.id}.html`)).filter(existsSync),
+];
+const common = commonParts.length
+  ? commonParts
+      .map(
+        (f, i) =>
+          (i ? `<!-- omnivideo:common · motion/src/${f.split("/").at(-1)} -->\n` : "") + readFileSync(f, "utf8"),
+      )
+      .join("\n")
+  : null;
+const commonName = commonParts.length ? `motion/src/${commonParts[0].split("/").at(-1)}` : null;
+
+/* Overview of the whole video in VIDEO seconds (beats, lines and words), for
+   the continuous composition: a system that carries from scene to scene is
+   drawn once, in video time, and each scene renders its own window. */
+const abs = (c, s) => +(c.start + s).toFixed(4);
+const overview = {
+  total_duration: video.total_duration,
+  scenes: video.scenes.map(c => ({
+    id: c.id,
+    start: c.start,
+    duration: c.duration,
+    beats: Object.fromEntries((c.beats ?? []).map(b => [b.element, abs(c, beatTime(c, b))])),
+    lines: (c.lines ?? []).map(l => ({
+      id: l.id,
+      text: l.text,
+      start: abs(c, l.start),
+      end: abs(c, l.end),
+      words: l.words?.map(p => ({ w: p.w, s: abs(c, l.start + p.s), e: abs(c, l.start + p.e) })) ?? null,
+    })),
+  })),
+};
+
+/* PT aliases on the same objects, so scene code written before the rename keeps
+   working (same values; `beats` is the same in both) */
+const LEGACY_ALIASES =
+  "(o=>{const l=x=>Object.assign(x,{texto:x.text,inicio:x.start,fim:x.end,palavras:x.words});" +
+  "o.lines.forEach(l);o.video.scenes.forEach(s=>{s.lines.forEach(l);Object.assign(s,{inicio:s.start,duracao:s.duration,falas:s.lines})});" +
+  "Object.assign(o.video,{duracao_total:o.video.total_duration,cenas:o.video.scenes});" +
+  "Object.assign(o,{cena:o.scene,inicio:o.start,duracao:o.duration,duracao_total:o.total_duration,provisorio:o.provisional,falas:o.lines})})(window.OMNIVIDEO);";
+
+/* --- 1. HTML of every scene -------------------------------------------------
+   It is just text, and keeps the injected times consistent between neighbours:
+   the transitions compare the two. Stills, sheets and render are for the
+   selected one. With --scene, only the selected scene's HTML is written in
+   place; its neighbours (for the cuts) go to temporary files next to it, which
+   keeps relative asset paths and never touches a scene another call may be
+   composing or rendering at the same moment. */
+const built = {};
+const scratch = [];
+const sceneIndex = Object.fromEntries(video.scenes.map((s, i) => [s.id, i]));
+const neighbour = id =>
+  onlyScene != null && id !== onlyScene && Math.abs(sceneIndex[id] - (sceneIndex[onlyScene] ?? -9)) === 1;
+for (const scene of video.scenes) {
+  if (onlyScene && !selected(scene.id) && !neighbour(scene.id)) continue;
+  const src = join(dir, "motion", "src", `${scene.id}.html`);
+  if (!existsSync(src)) {
+    if (selected(scene.id)) {
+      console.error(`${scene.id}: falta ${src}`);
+      process.exitCode = 1;
+    }
+    continue;
+  }
+
+  const beats = {};
+  const report = [];
+  for (const beat of scene.beats ?? []) {
+    const t = beatTime(scene, beat);
+    beats[beat.element] = t;
+    const source =
+      beat.enters_with && !video.provisional
+        ? beat.enters_with
+        : beat.enters_with
+          ? `${beat.enters_with} (estimado)`
+          : "provisório";
+    const slack = scene.duration - t;
+    report.push(
+      `   ${beat.element.padEnd(18)} ${t.toFixed(2).padStart(6)}s  ${source}${slack < HOLD + 0.6 ? "  ⚠ pouco tempo até o fim da cena" : ""}`,
+    );
+  }
+
+  const vars = Object.entries(beats)
+    .map(([k, t]) => `--b-${k}:${t}s;`)
+    .join(" ");
+  const data = {
+    scene: scene.id,
+    start: scene.start,
+    duration: scene.duration,
+    total_duration: video.total_duration,
+    provisional: video.provisional,
+    beats,
+    lines: (scene.lines ?? []).map(l => ({
+      id: l.id,
+      text: l.text,
+      start: l.start,
+      end: l.end,
+      words: l.words ?? null,
+    })),
+    video: overview,
+  };
+  const injection =
+    `<style id="omnivideo-beats">:root{ ${vars} --scene-dur:${scene.duration}s; --scene-start:${scene.start}s; --video-dur:${video.total_duration}s;` +
+    ` --cena-dur:${scene.duration}s; --cena-inicio:${scene.start}s; }</style>\n` +
+    `<script id="omnivideo-data">window.OMNIVIDEO = ${JSON.stringify(data)};\n${LEGACY_ALIASES}</script>\n`;
+
+  let html = readFileSync(src, "utf8");
+  if (!html.includes("</head>")) throw new Error(`${src}: sem </head>`);
+  html = html.replace(
+    /<style id="omnivideo-beats">[\s\S]*?<\/style>\n?|<script id="omnivideo-(?:data|dados)">[\s\S]*?<\/script>\n?/g,
+    "",
+  );
+  /* replace with a function: line text or code containing `$&` doesn't become a pattern */
+  html = html.replace("</head>", () => `${injection}</head>`);
+  if (common) {
+    /* only the marker alone on its line: quoted in a comment, it doesn't count.
+       omnivideo:comum = legacy marker */
+    const markerLine = /^[ \t]*<!-- omnivideo:(?:common|comum) -->[ \t]*$/m;
+    if (markerLine.test(html))
+      html = html.replace(markerLine, () => `<!-- omnivideo:common · ${commonName} -->\n${common}`);
+    else if (selected(scene.id))
+      console.warn(`${scene.id}: ⚠ existe ${commonName}, mas a cena não tem ${MARKER} sozinho numa linha`);
+  }
+  /* Components (templates/components/<name>/<name>.js) are pasted in, so the built
+     scene is one self-contained file. Marker alone on its line:
+       <!-- omnivideo:component voiceavatar -->   the component's code
+       <!-- omnivideo:envelope -->                window.VOICE_ENVELOPE of THIS scene (voice-envelope.mjs),
+                                                  null while the scene has no voice yet: the orb idles */
+  html = html.replace(/^[ \t]*<!-- omnivideo:component ([\w-]+) -->[ \t]*$/gm, (_, name) => {
+    const file = join(CODE_ROOT, "templates", "components", name, `${name}.js`);
+    if (!existsSync(file)) {
+      console.warn(`${scene.id}: ⚠ componente "${name}" não existe em ${file}`);
+      return `<!-- omnivideo:component ${name} · não encontrado -->`;
+    }
+    const code = readFileSync(file, "utf8");
+    /* a literal closing tag anywhere in the code, comments included, ends the inline script */
+    if (/<\/script/i.test(code)) throw new Error(`${file}: contém "</script" e quebraria o <script> inline`);
+    return `<!-- omnivideo:component ${name} -->\n<script>\n${code}</script>`;
+  });
+  html = html.replace(/^[ \t]*<!-- omnivideo:envelope -->[ \t]*$/m, () => {
+    const r = spawnSync("node", [join(CODE_ROOT, "tools", "voice-envelope.mjs"), "--scene", dir, scene.id], {
+      maxBuffer: 1 << 28,
+    });
+    const env = r.status === 0 ? r.stdout.toString().trim() : "null";
+    if (r.status !== 0 && selected(scene.id) && !video.provisional)
+      console.warn(
+        `${scene.id}: ⚠ sem envelope de voz (${r.stderr.toString().trim()}); o orbe fica só em movimento ocioso`,
+      );
+    return `<!-- omnivideo:envelope -->\n<script>window.VOICE_ENVELOPE = ${env};</script>`;
+  });
+  const finalOut = join(dir, scene.html ?? `motion/${scene.id}.html`);
+  const out = neighbour(scene.id) ? join(dirname(finalOut), `.${scene.id}.neighbour-${process.pid}.html`) : finalOut;
+  if (out !== finalOut) scratch.push(out);
+  writeFileSync(out, html);
+  built[scene.id] = { out, beats };
+
+  if (selected(scene.id)) {
+    console.log(
+      `${scene.id} · ${scene.duration.toFixed(2)}s a partir de ${scene.start.toFixed(2)}s${video.provisional ? " (provisório)" : ""} → ${out}`,
+    );
+    report.forEach(l => console.log(l));
+  }
+}
+
+/* --- 2. stills, sheets and render of the selected scene --------------------- */
+mkdirSync(join(dir, "motion", "stills"), { recursive: true });
+const ok = [];
+for (const scene of video.scenes) {
+  if (!selected(scene.id) || !built[scene.id]) continue;
+  const { out, beats } = built[scene.id];
+  const times = Object.values(beats).sort((a, b) => a - b);
+  const composition =
+    flag("stills") || flag("sheets")
+      ? keepPrevious(dir, "composition", scene.id, [
+          `motion/stills/${scene.id}.png`,
+          `motion/stills/${scene.id}-sheet.png`,
+        ])
+      : null;
+  if (flag("stills")) {
+    const t = Math.min((times.at(-1) ?? 0) + HOLD + 0.6, scene.duration - 1 / fps);
+    const png = join(dir, "motion", "stills", `${scene.id}.png`);
+    render(out, "--still", png, "--at", t.toFixed(3));
+    console.log(`${scene.id} · still em ${t.toFixed(2)}s → ${png}`);
+  }
+  if (flag("sheets")) {
+    const marks = [0, ...times.map(t => t + 0.3), scene.duration - 1 / fps]
+      .map(t => Math.min(Math.max(t, 0), scene.duration - 1 / fps))
+      .filter((t, i, a) => a.indexOf(t) === i)
+      .sort((a, b) => a - b);
+    const png = join(dir, "motion", "stills", `${scene.id}-sheet.png`);
+    render(out, "--sheet", png, "--at", marks.map(t => t.toFixed(2)).join(","));
+    console.log(`${scene.id} · folha em ${marks.map(t => t.toFixed(1)).join(", ")}s → ${png}`);
+  }
+  composition?.close();
+  if (flag("render")) {
+    const mp4 = join(dir, scene.mp4 ?? `motion/${scene.id}.mp4`);
+    const previousRender = keepPrevious(dir, "render", scene.id, [
+      scene.mp4 ?? `motion/${scene.id}.mp4`,
+      `motion/${scene.id}.render.json`,
+    ]);
+    render(out, mp4, "--dur", String(scene.duration), "--fps", String(fps));
+    /* a scene with its background in video time depends on its own start: if an
+       earlier scene changes duration, this one must render again. status and
+       assemble compare this record with scenes.json. */
+    const videoTime = /var\(--(?:scene-start|cena-inicio)|OMNIVIDEO\??\.(?:start|inicio)/.test(
+      readFileSync(out, "utf8"),
+    );
+    writeFileSync(
+      join(dir, "motion", `${scene.id}.render.json`),
+      JSON.stringify({ start: scene.start, duration: scene.duration, video_time: videoTime }) + "\n",
+    );
+    previousRender.close();
+    console.log(`${scene.id} · render → ${mp4}${videoTime ? " (fundo no tempo do vídeo)" : ""}`);
+  }
+  ok.push(scene.id);
+}
+
+/* --- 3. transitions ----------------------------------------------------------
+   The outgoing scene is captured at t = duration, the cut instant: the frame
+   that would come after its last one. If nothing jumps, the incoming one at
+   t = 0 matches it in everything that continues, and the overlay comes out sharp. */
+const MEASUREMENTS = "MEASUREMENTS ";
+function readMeasurements(renderOut) {
+  const line = renderOut.split("\n").find(l => l.startsWith(MEASUREMENTS));
+  return line ? JSON.parse(line.slice(MEASUREMENTS.length)) : [];
+}
+
+/* Three panels, always in this order: outgoing | incoming | both at 50 %.
+   No labels: this machine's ffmpeg has no drawtext. */
+function transitionSheet(pngA, pngB, out) {
+  const width = w >= h ? 640 : 360;
+  const graph =
+    `[0]split[a0][a1];[1]split[b0][b1];[a1][b1]blend=all_mode=average[m];` +
+    `[a0]scale=${width}:-2,pad=iw+8:ih:0:0:white[A];[b0]scale=${width}:-2,pad=iw+8:ih:0:0:white[B];[m]scale=${width}:-2[M];` +
+    `[A][B][M]hstack=inputs=3,pad=iw+16:ih+16:8:8:white`;
+  const r = spawnSync(
+    "ffmpeg",
+    ["-y", "-loglevel", "error", "-i", pngA, "-i", pngB, "-filter_complex", graph, "-frames:v", "1", out],
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  if (r.status !== 0) throw new Error(`ffmpeg (folha de passagem): ${r.stderr}`);
+}
+
+function transitionKind(p) {
+  if (p == null || p === "cut") return { kind: "corte seco", continues: [] };
+  if (Array.isArray(p?.continues) && p.continues.length)
+    return { kind: `continua: ${p.continues.join(", ")}`, continues: p.continues };
+  /* { sound } without continues: hard cut with an effect at the cut (sound.mjs) */
+  if (p && typeof p === "object" && p.sound && p.continues == null) return { kind: "corte seco", continues: [] };
+  return {
+    kind: `⚠ passagem inválida (${JSON.stringify(p)}); use "cut", { "continues": [...] } ou { "sound": ... }`,
+    continues: [],
+  };
+}
+
+if (flag("transitions")) {
+  const tmp = join(tmpdir(), `transitions-${process.pid}`);
+  mkdirSync(tmp, { recursive: true });
+  try {
+    for (let i = 1; i < video.scenes.length; i++) {
+      const a = video.scenes[i - 1],
+        b = video.scenes[i];
+      if (onlyScene && onlyScene !== a.id && onlyScene !== b.id) continue;
+      if (!built[a.id] || !built[b.id]) {
+        console.warn(`${a.id} → ${b.id}: falta o HTML de uma das duas`);
+        continue;
+      }
+      const { kind, continues } = transitionKind(b.transition);
+      /* on a hard cut what matters is the outgoing scene's real last frame; when
+         it continues, the cut instant (in a continuous composition it is
+         already the next one's first frame) */
+      const tA = continues.length ? a.duration : Math.max(0, a.duration - 1 / fps);
+      const pngA = join(tmp, `${a.id}.png`),
+        pngB = join(tmp, `${b.id}.png`);
+      const ma = readMeasurements(render(built[a.id].out, "--still", pngA, "--at", tA.toFixed(4), "--measure"));
+      const mb = readMeasurements(render(built[b.id].out, "--still", pngB, "--at", "0", "--measure"));
+      const png = join(dir, "motion", "stills", `transition-${a.id}-${b.id}.png`);
+      const previousCut = keepPrevious(dir, "composition", `transition-${a.id}-${b.id}`, [
+        `motion/stills/transition-${a.id}-${b.id}.png`,
+      ]);
+      /* rendered aside and renamed: two scene calls running in parallel share this cut */
+      const pngTmp = join(dirname(png), `.transition-${a.id}-${b.id}-${process.pid}.png`);
+      transitionSheet(pngA, pngB, pngTmp);
+      renameSync(pngTmp, png);
+      previousCut.close();
+
+      console.log(`${a.id} → ${b.id} · ${kind} → ${png}`);
+      for (const name of continues) {
+        const x = ma.find(m => m.name === name),
+          y = mb.find(m => m.name === name);
+        if (!x || !y) {
+          console.log(
+            `   ${name.padEnd(18)} ⚠ falta [data-continues="${name}"] em ${[!x && a.id, !y && b.id].filter(Boolean).join(" e ")}`,
+          );
+          process.exitCode = 1;
+          continue;
+        }
+        const d = Math.max(Math.abs(x.x - y.x), Math.abs(x.y - y.y), Math.abs(x.w - y.w), Math.abs(x.h - y.h));
+        const dOp = Math.abs(x.opacity - y.opacity);
+        const jumps = d > TOL_PX || dOp > 0.05;
+        console.log(
+          `   ${name.padEnd(18)} desvio ${d.toFixed(1)} px · opacidade ${x.opacity.toFixed(2)} → ${y.opacity.toFixed(2)}` +
+            (jumps ? "  ⚠ pula no corte" : "  ok"),
+        );
+        if (jumps) process.exitCode = 1;
+      }
+    }
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+for (const f of scratch) rmSync(f, { force: true });
+if (!ok.length) process.exitCode = 1;

package/tools/captions.mjs

@@ -0,0 +1,246 @@
+/* ============================================================================
+   Burned-in captions: where they come from and where they sit. Used by
+   assemble.mjs (render) and by the studio (preview), so both see the same HTML.
+
+   Each caption in captions.srt gets an id `<line>.<n>` (the n-th caption of
+   that line; a caption never spans two lines) and its scene.
+
+   The position lives in `captions` in scenes.json, on three levels, each one
+   over the previous:
+
+     "captions": {
+       "platform": "all",                safe area: shorts, tiktok, reels, all (9:16) · youtube (16:9)
+       "anchor": "bottom-center",        3×3 grid: top|middle|bottom - left|center|right
+       "x": 0, "y": 0,                   offset in frame px (+x right, +y down)
+       "style": "shadow",                shadow | pill (default in the config's captions.style)
+       "safe": { "bottom": 0.12 },       this video's safe area tweak, per side (fraction of the frame)
+       "color": "#ffd400",               text color
+       "background": "#000000", "background_opacity": 0.7,  pill: background color and opacity
+       "outline": 4, "outline_color": "#000000",            text outline: width (frame px) and color
+       "shadow_color": "#000000", "shadow_opacity": 0.5,    shadow: color, opacity,
+       "shadow_blur": 12, "shadow_x": 0, "shadow_y": 6      blur and offset (frame px)
+       "scenes":     { "c04": { "anchor": "top-center", "y": 40 } },
+       "individual": { "f03.2": { "x": -30 }, "f04.1": { "hidden": true } }
+     }
+
+   The anchor pins the caption box to the edge (or center) of the safe area;
+   the offset moves from there. A caption may go outside the safe area: only
+   the frame limits it, and what goes past is flagged (`outside`, with side and
+   px). Each platform's safe area is in the config's `captions.safe_area`, as a
+   fraction of the frame; `all` is the most restrictive on each side. `safe` in
+   scenes.json overrides only the sides it lists, for that video.
+
+   `hidden: true` on an individual caption turns it off: it stays in
+   captions.srt, but assemble doesn't burn it (captionsOf flags `hidden`, and
+   assemble drops it). Without the key, the caption shows.
+
+   A caption's text can be edited in the UI: the new one goes straight to
+   captions.srt (that's what assemble and Premiere read), and `captions.texts`
+   keeps the swap so the next generation doesn't lose it:
+
+     "texts": { "f03.2": { "text": "de 70 a 500 ms", "original": "de 70 a 500 milissegundos" } }
+
+   `original` is what the line generated. `omnivideo.py captions` puts the
+   edited text back on the caption of the same line that still generates the
+   same `original`; if the line changed and no longer does, the edit is
+   dropped, with a warning.
+
+   Color, outline and shadow follow the same three levels as the position
+   (video → scene → caption): a key absent from every level gets the style's
+   default (`styleDefaults`). Touching any shadow key replaces the style's
+   shadow with a single layer, with the five values.
+   ============================================================================ */
+
+import { readFileSync, existsSync, writeFileSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { CODE_ROOT, DATA_ROOT as ROOT } from "./lib/paths.mjs";
+
+const CFG = JSON.parse(readFileSync(join(ROOT, "omnivideo.config.json"), "utf8"));
+
+export const ROWS = ["top", "middle", "bottom"];
+export const COLUMNS = ["left", "center", "right"];
+export const ANCHORS = ROWS.flatMap(r => COLUMNS.map(c => `${r}-${c}`));
+export const STYLES = ["pill", "shadow"];
+export const SIDES = ["top", "bottom", "left", "right"];
+
+/* color, outline and shadow: key → { type, range } (color as #rrggbb; the rest, a number) */
+export const STYLE_KEYS = [
+  "color",
+  "background",
+  "background_opacity",
+  "outline",
+  "outline_color",
+  "shadow_color",
+  "shadow_opacity",
+  "shadow_blur",
+  "shadow_x",
+  "shadow_y",
+];
+export const STYLE_LIMITS = {
+  background_opacity: [0, 1, 2],
+  outline: [0, 40, 0],
+  shadow_opacity: [0, 1, 2],
+  shadow_blur: [0, 100, 0],
+  shadow_x: [-100, 100, 0],
+  shadow_y: [-100, 100, 0] /* [min, max, decimals] */,
+};
+export const STYLE_COLORS = ["color", "background", "outline_color", "shadow_color"];
+
+/* what each style draws untouched, in frame px (same as the template's CSS) */
+export function styleDefaults(format) {
+  const body = ((aspectOf(format) === "16:9" ? 2.4 : 4.4) / 100) * format.w;
+  const vw = n => Math.round((n / 100) * format.w);
+  const common = {
+    background: "#ffffff",
+    background_opacity: 0.9,
+    outline: 0,
+    outline_color: "#000000",
+    shadow_color: "#000000",
+    shadow_x: 0,
+  };
+  return {
+    pill: { ...common, color: "#111111", shadow_opacity: 0.18, shadow_blur: vw(2.4), shadow_y: vw(0.4) },
+    shadow: {
+      ...common,
+      color: "#ffffff",
+      shadow_opacity: 0.55,
+      shadow_blur: Math.round(0.12 * body),
+      shadow_y: Math.round(0.04 * body),
+    },
+  };
+}
+
+export const aspectOf = format => format.aspect ?? (format.w < format.h ? "9:16" : "16:9");
+
+/* a caption's character limit (past it, the template breaks into two lines) */
+export const maxChars = format => CFG.captions?.max_chars?.[aspectOf(format)] ?? null;
+
+/* the format's safe areas, plus `all` (the largest inset on each side) */
+export function safeAreas(format) {
+  const table = { ...(CFG.captions?.safe_area?.[aspectOf(format)] ?? {}) };
+  const vals = Object.values(table);
+  if (vals.length > 1) table.all = Object.fromEntries(SIDES.map(s => [s, Math.max(...vals.map(v => v[s] ?? 0))]));
+  return table;
+}
+
+/* the video's position with the config defaults underneath */
+export function positionOf(video) {
+  const defaults = {
+    platform: "all",
+    anchor: "bottom-center",
+    x: 0,
+    y: 0,
+    style: CFG.captions?.style ?? "shadow",
+    ...(CFG.captions?.default_position ?? {}),
+  };
+  const p = { ...defaults, ...(video.captions ?? {}) };
+  const safes = safeAreas(video.format);
+  if (!safes[p.platform]) p.platform = Object.keys(safes)[0] ?? "all";
+  return p;
+}
+
+const srtTime = s => {
+  const [h, m, r] = s.trim().replace(",", ".").split(":");
+  return +h * 3600 + +m * 60 + +r;
+};
+
+export function readSrt(file) {
+  return readFileSync(file, "utf8")
+    .replace(/\r/g, "")
+    .split(/\n\s*\n/)
+    .flatMap(block => {
+      const rows = block.trim().split("\n");
+      const i = rows.findIndex(l => l.includes("-->"));
+      if (i < 0) return [];
+      const [a, b] = rows[i].split("-->");
+      const text = rows
+        .slice(i + 1)
+        .join(" ")
+        .trim();
+      return text ? [{ s: srtTime(a), e: srtTime(b), text }] : [];
+    });
+}
+
+/* replaces the text of the `index`-th caption (readSrt order), leaving the rest of the file untouched */
+export function replaceSrtText(file, index, text) {
+  let k = -1;
+  const blocks = readFileSync(file, "utf8")
+    .replace(/\r/g, "")
+    .split(/\n\s*\n/)
+    .map(block => {
+      const rows = block.trim().split("\n");
+      const i = rows.findIndex(l => l.includes("-->"));
+      if (
+        i < 0 ||
+        !rows
+          .slice(i + 1)
+          .join(" ")
+          .trim()
+      )
+        return block.trim();
+      k += 1;
+      return k === index ? [...rows.slice(0, i + 1), text].join("\n") : block.trim();
+    });
+  if (index > k) throw new Error(`o captions.srt não tem a legenda ${index + 1}`);
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, blocks.filter(Boolean).join("\n\n") + "\n");
+  renameSync(tmp, file);
+}
+
+/* [{ id, scene, line, s, e, text }] in video time; `video` comes from loadVideo() */
+export function captionsOf(dir, video) {
+  const file = join(dir, "captions.srt");
+  if (!existsSync(file)) return [];
+  const lines = video.scenes.flatMap(sc =>
+    (sc.lines ?? []).map(l => ({ id: l.id, scene: sc.id, a: sc.start + l.start, b: sc.start + l.end })),
+  );
+  const count = {};
+  return readSrt(file).map((cue, k) => {
+    const mid = (cue.s + cue.e) / 2;
+    const l =
+      lines.find(x => mid >= x.a - 0.05 && mid <= x.b + 0.05) ??
+      lines.reduce((m, x) => (Math.abs((x.a + x.b) / 2 - mid) < Math.abs((m.a + m.b) / 2 - mid) ? x : m), lines[0]);
+    const scene = l?.scene ?? video.scenes.find(sc => mid >= sc.start && mid < sc.start + sc.duration)?.id ?? null;
+    const base = l?.id ?? `l${k + 1}`;
+    count[base] = (count[base] ?? 0) + 1;
+    const id = l ? `${base}.${count[base]}` : base;
+    /* edited in the UI: `original` is what the line generated */
+    const ed = video.captions?.texts?.[id];
+    return {
+      id,
+      scene,
+      line: l?.id ?? null,
+      s: +cue.s.toFixed(3),
+      e: +cue.e.toFixed(3),
+      text: cue.text,
+      hidden: video.captions?.individual?.[id]?.hidden === true,
+      ...(ed?.text === cue.text && ed.original ? { original: ed.original } : {}),
+    };
+  });
+}
+
+/* templates/captions.html with the data, the position and the video's _captions.css */
+export function captionsHtml(dir, video, captions = captionsOf(dir, video)) {
+  const pos = positionOf(video);
+  const { w, h } = video.format;
+  const cssFile = join(dir, "motion", "src", "_captions.css");
+  const css = existsSync(cssFile) ? readFileSync(cssFile, "utf8") : "";
+  const data = {
+    w,
+    h,
+    safes: safeAreas(video.format),
+    position: pos,
+    keys: ["anchor", "x", "y", ...STYLE_KEYS],
+    defaults: styleDefaults(video.format),
+    captions,
+  };
+  const json = JSON.stringify(data).replace(/</g, "\\u003c");
+  const html = readFileSync(join(CODE_ROOT, "templates", "captions.html"), "utf8")
+    .replace(
+      '<html lang="pt-BR">',
+      `<html lang="pt-BR" data-format="${aspectOf(video.format)}" data-style="${pos.style}">`,
+    )
+    .replace(/\/\*omnivideo:data\*\/\{[\s\S]*?\};/, () => `${json};`)
+    .replace("/*omnivideo:video-style*/", () => css);
+  return { html, pos, css: !!css };
+}