@crievo/omni 0.0.0-stage → 0.1.1

package/tools/soundtrack.mjs

@@ -0,0 +1,217 @@
+/* ============================================================================
+   Clips: where each piece of animation (a scene's MP4) and of voice (a line's
+   WAV) shows up in the video.
+
+   The voice owns time: the scene starts at `scene.start` and lasts
+   `scene.duration`; the line sits at `scene.start + line.start`. The studio
+   editor lets you change that without redoing anything, through clips:
+
+     scene.clips  [{ from, to, offset, speed? }]   pieces of the scene MP4
+     line.clips   [{ from, to, offset, speed? }]   pieces of the line WAV
+
+   `from`/`to` are seconds inside the file; `offset` is how far the piece moves
+   from its own place (negative = earlier). `speed` (0.5 to 2, default 1) plays
+   the piece faster: it lasts (to − from) / speed in the video, starting at the
+   same place, and what came after stays put (the gap holds the last frame, or
+   is silent). The voice keeps its pitch (atempo). The razor splits a clip in two;
+   deleting a clip removes the piece; dragging changes `offset`. Without
+   `clips`, the whole file is one clip (for a scene, with the old
+   `video_offset`, if any).
+
+   Beat and transition effects move with the animation piece they fall in;
+   captions and ducking move with the voice piece.
+
+   Image on a single track, like an editor: where two pieces overlap, the one
+   that started last shows; in a gap, the last frame of the piece that ended
+   before holds (or the first frame of the first one, before everything).
+
+   assemble.mjs and sound.mjs use this; so does the studio screen. Times in
+   scenes.json seconds (without the range cuts).
+   ============================================================================ */
+
+const EPS = 1e-6;
+/* `video_em` = legacy name of `video_offset` */
+export const videoOffset = scene => Number(scene?.video_offset ?? scene?.video_em) || 0;
+
+export const CLIP_SPEED = [0.5, 2];
+/* a clip's speed, inside the range (1 when absent) */
+export const clipSpeed = c => {
+  const v = Number(c?.speed);
+  return Number.isFinite(v) && v > 0 ? Math.min(CLIP_SPEED[1], Math.max(CLIP_SPEED[0], v)) : 1;
+};
+/* how long the piece lasts in the video */
+export const clipLength = c => (c.to - c.from) / clipSpeed(c);
+/* `speed` only when it isn't 1, so an untouched clip stays { from, to, offset } */
+const normal = c => {
+  const v = clipSpeed(c);
+  return { from: +c.from, to: +c.to, offset: Number(c.offset) || 0, ...(v !== 1 ? { speed: v } : {}) };
+};
+export const lineDuration = l => l.dur ?? l.end - l.start;
+
+export function videoClips(scene) {
+  return Array.isArray(scene.clips)
+    ? scene.clips.map(normal)
+    : [{ from: 0, to: scene.duration, offset: videoOffset(scene) }];
+}
+export function lineClips(line) {
+  return Array.isArray(line.clips) ? line.clips.map(normal) : [{ from: 0, to: lineDuration(line), offset: 0 }];
+}
+
+/* the arrangement was edited: some clip moved, cut or deleted */
+const isDefault = (clips, dur) =>
+  clips.length === 1 &&
+  Math.abs(clips[0].from) < EPS &&
+  Math.abs(clips[0].to - dur) < 1e-3 &&
+  !clips[0].offset &&
+  clipSpeed(clips[0]) === 1;
+export const videoEdited = scenes => scenes.some(c => !isDefault(videoClips(c), c.duration));
+export const voiceEdited = scenes =>
+  scenes.some(c => (c.lines ?? []).some(l => !isDefault(lineClips(l), lineDuration(l))));
+
+/* every animation piece: { i (scene), k (clip), from, to, offset, speed, start and end (in the video) } */
+export function videoPieces(scenes) {
+  return scenes.flatMap((c, i) =>
+    videoClips(c).map((cl, k) => ({
+      i,
+      k,
+      from: cl.from,
+      to: cl.to,
+      offset: cl.offset,
+      speed: clipSpeed(cl),
+      start: c.start + cl.from + cl.offset,
+      end: c.start + cl.from + cl.offset + clipLength(cl),
+    })),
+  );
+}
+/* every voice piece: { scene, line, k, from, to, offset, speed, start } */
+export function voicePieces(scenes) {
+  return scenes.flatMap(c =>
+    (c.lines ?? []).flatMap(l =>
+      lineClips(l).map((cl, k) => ({
+        scene: c,
+        line: l,
+        k,
+        from: cl.from,
+        to: cl.to,
+        offset: cl.offset,
+        speed: clipSpeed(cl),
+        start: c.start + l.start + cl.from + cl.offset,
+      })),
+    ),
+  );
+}
+
+/* the instant, in the video, of a `local` point of the scene's animation (null: fell in a deleted piece) */
+export function animationInstant(scene, local) {
+  const cl = videoClips(scene).find(x => local >= x.from - EPS && local < x.to + EPS);
+  return cl ? scene.start + cl.from + cl.offset + (local - cl.from) / clipSpeed(cl) : null;
+}
+/* the start of the scene's animation in the video (the scene change): the first piece's */
+export function animationStart(scene) {
+  const cl = videoClips(scene).sort((a, b) => a.from - b.from)[0];
+  return cl ? scene.start + cl.from + cl.offset : null;
+}
+/* a span [a, b] inside the line, in the video: one piece per clip that holds it (the rest was deleted) */
+export function voiceSpans(scene, line, a, b) {
+  const base = scene.start + line.start;
+  return lineClips(line).flatMap(cl => {
+    const from = Math.max(a, cl.from),
+      to = Math.min(b, cl.to);
+    const at = x => base + cl.from + cl.offset + (x - cl.from) / clipSpeed(cl);
+    return to > from + EPS ? [[at(from), at(to)]] : [];
+  });
+}
+
+/* what shows at instant t: { i (scene), local (second inside the MP4), frozen, speed (how fast the
+   MP4 runs there) } */
+export function frameAt(scenes, t) {
+  const pieces = videoPieces(scenes);
+  if (!pieces.length) return { i: 0, local: 0, frozen: true, speed: 1 };
+  let covering = null;
+  for (const p of pieces) if (p.start <= t && t < p.end && (!covering || p.start >= covering.start)) covering = p;
+  if (covering)
+    return {
+      i: covering.i,
+      local: covering.from + (t - covering.start) * covering.speed,
+      frozen: false,
+      speed: covering.speed,
+    };
+  /* gap: the last frame of the piece that ended last before t */
+  let ended = null;
+  for (const p of pieces) if (p.end <= t && (!ended || p.end >= ended.end)) ended = p;
+  if (ended) return { i: ended.i, local: ended.to - 1e-3, frozen: true, speed: 1 };
+  /* before all of them: the first frame of the one that starts first */
+  const first = pieces.reduce((m, p) => (p.start < m.start ? p : m));
+  return { i: first.i, local: first.from, frozen: true, speed: 1 };
+}
+
+/* the whole track in frames: [{ i, from, frames, since, frozen, speed }], `from` and `since`
+   in frames (in the video and inside the scene MP4); frozen repeats frame `since`; a running
+   segment takes frames × speed frames of the MP4 */
+export function videoTrack(scenes, total, fps) {
+  const q = s => Math.round(s * fps);
+  const end = q(total);
+  const marks = new Set([0, end]);
+  for (const p of videoPieces(scenes)) {
+    for (const m of [q(p.start), q(p.end)]) if (m > 0 && m < end) marks.add(m);
+  }
+  const points = [...marks].sort((a, b) => a - b);
+  const segs = [];
+  for (let k = 0; k < points.length - 1; k++) {
+    const a = points[k],
+      b = points[k + 1];
+    const v = frameAt(scenes, (a + 0.5) / fps);
+    const nq = q(scenes[v.i].duration);
+    /* the MP4 frame at the start of the segment */
+    const since = Math.max(
+      0,
+      Math.min(
+        nq - 1,
+        v.frozen ? Math.floor(v.local * fps + EPS) : Math.round((v.local - (0.5 * v.speed) / fps) * fps),
+      ),
+    );
+    const last = segs.at(-1);
+    /* join with the previous one when it is the same scene running at the same speed, or the same frozen frame */
+    if (
+      last &&
+      last.i === v.i &&
+      last.frozen === v.frozen &&
+      last.speed === v.speed &&
+      (v.frozen ? last.since === since : Math.abs(last.since + last.frames * last.speed - since) < 1 + EPS)
+    )
+      last.frames += b - a;
+    else segs.push({ i: v.i, from: a, frames: b - a, since, frozen: v.frozen, speed: v.speed });
+  }
+  return segs;
+}
+
+/* --- validate what the screen sends --------------------------------------------
+   clips sorted, inside the file, not overlapping in the file; `step` snaps
+   (1/fps for animation, 1 ms for voice); `offset` from -30 to 30 s */
+export function sanitizeClips(clips, dur, step) {
+  if (!Array.isArray(clips)) throw new Error("clips: tem de ser uma lista");
+  const a = s => Math.round(s / step) * step;
+  const list = clips
+    .map(c => {
+      const from = a(Math.max(0, Math.min(dur, Number(c?.from)))),
+        to = a(Math.max(0, Math.min(dur, Number(c?.to))));
+      const offset = Number(c?.offset ?? 0);
+      if (![from, to, offset].every(Number.isFinite)) throw new Error(`clip inválido: ${JSON.stringify(c)}`);
+      if (Math.abs(offset) > 30) throw new Error(`clip: offset de -30 a 30 segundos; veio ${offset}`);
+      const speed = c?.speed == null ? 1 : Number(c.speed);
+      if (!(speed >= CLIP_SPEED[0] && speed <= CLIP_SPEED[1]))
+        throw new Error(`clip: velocidade de ${CLIP_SPEED[0] * 100}% a ${CLIP_SPEED[1] * 100}%; veio ${c?.speed}`);
+      return { from, to, offset: a(offset), speed: Math.round(speed * 100) / 100 };
+    })
+    .filter(c => c.to - c.from >= step - EPS)
+    .sort((x, y) => x.from - y.from);
+  for (let k = 1; k < list.length; k++) if (list[k].from < list[k - 1].to - EPS) list[k].from = list[k - 1].to;
+  return list
+    .filter(c => c.to - c.from >= step - EPS)
+    .map(c => ({
+      from: +c.from.toFixed(4),
+      to: +c.to.toFixed(4),
+      offset: +c.offset.toFixed(4),
+      ...(c.speed !== 1 ? { speed: c.speed } : {}),
+    }));
+}

package/tools/thumbnail.mjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+/* ============================================================================
+   Thumbnail of a video in HTML + SVG + CSS, on request. Four slots:
+   v1, v2 and v3 are three drawn ideas; v4 follows the user's instruction.
+
+     node tools/thumbnail.mjs videos/<slug> size         aspect and pixels of this video's thumbnail
+     node tools/thumbnail.mjs videos/<slug> draw         three different ideas for v1, v2 and v3
+     node tools/thumbnail.mjs videos/<slug> render [vN,…] thumbnail/vN.html → vN.png (default: the ones that exist)
+     node tools/thumbnail.mjs videos/<slug> snapshot v2  copies v2.html and v2.png to history/ before changing it
+     node tools/thumbnail.mjs videos/<slug> choose v2    the selected one becomes thumbnail/thumbnail.png, the cover
+                                                         that publish.mjs sends (choose none removes it)
+     node tools/thumbnail.mjs videos/<slug> status       thumbnail/thumbnail.json
+
+   Claude creates the versions (skill av-thumbnail), in the video's style;
+   this tool is the mechanical part: the right size for the video's aspect,
+   the idea draw, the PNG of each HTML and the record in
+   thumbnail/thumbnail.json. Rendering some doesn't delete the others: the
+   random ones and the manual one are requested and redone separately.
+
+   Size from the aspect in scenes.json:
+     16:9  → 1280×720   (what YouTube asks for)
+     9:16  → 1080×1920  (Shorts, Reels, TikTok)
+     other → the video's own format
+
+   Each HTML is a still, self-contained image (no JS needed, no external
+   files): the tool adds the ready signal that render.mjs waits for, so the
+   source only has to load. `<title>` becomes the version name and
+   `<meta name="description">` its idea, in thumbnail.json and in the UI.
+
+   thumbnail/request.json belongs to the UI (studio/api/services/thumbnail.ts):
+     { "random": { "at": "…" } | null,
+       "manual": { "at": "…", "instruction": "…" } | null,
+       "changes": { "v2": { "at": "…", "instruction": "…" } } }
+   The v4 instruction and the change requested for each version go from it into thumbnail.json.
+
+   Nothing here is sent to the platforms: publish.mjs does not upload the cover.
+   ============================================================================ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, renameSync, rmSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, resolve } from "node:path";
+import { keepPrevious } from "./history.mjs";
+import { CODE_ROOT, DATA_ROOT as ROOT } from "./lib/paths.mjs";
+
+const RENDER = join(CODE_ROOT, "tools", "render.mjs");
+const RANDOM = ["v1", "v2", "v3"];
+const MANUAL = "v4";
+const IDS = [...RANDOM, MANUAL];
+
+/* where the three random ones start from; the draw changes on every request (PT: shown to Claude) */
+const IDEAS = [
+  ["tipografia", "uma palavra ou número enorme, o resto some"],
+  ["ilustração", "um objeto ou diagrama em SVG como herói, texto mínimo"],
+  ["contraste", "antes/depois, certo/errado, duas metades"],
+  ["pergunta", "o gancho do roteiro como pergunta curta, com um símbolo"],
+  ["dado", "o número do vídeo como painel: placar, medidor, contador"],
+  ["cena", 'o herói da cena "wow" redesenhado grande, recortado de perto'],
+  ["metáfora", "um objeto do dia a dia que explica a tese sem palavras"],
+];
+
+function fail(msg) {
+  console.error(`erro: ${msg}`);
+  process.exit(1);
+}
+const readJson = file => {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+};
+function writeJson(file, data) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n");
+  renameSync(tmp, file);
+}
+
+const [target, cmd = "status", ...rest] = process.argv.slice(2);
+if (!target) fail("uso: thumbnail.mjs videos/<slug> size|draw|render [vN,…]|snapshot <vN>|choose <vN>|status");
+const VIDEO_DIR = resolve(target);
+const scenes = readJson(join(VIDEO_DIR, "scenes.json"));
+if (!scenes) fail(`${target} não tem scenes.json`);
+const DIR = join(VIDEO_DIR, "thumbnail");
+const JSON_FILE = join(DIR, "thumbnail.json");
+
+function size() {
+  const f = scenes.format;
+  if (!f) fail("o scenes.json não tem format");
+  const aspect = f.aspect ?? `${f.w}:${f.h}`;
+  if (aspect === "16:9") return { aspect, w: 1280, h: 720 };
+  if (aspect === "9:16") return { aspect, w: 1080, h: 1920 };
+  return { aspect, w: f.w, h: f.h };
+}
+
+function draw() {
+  const bag = [...IDEAS];
+  for (let i = bag.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [bag[i], bag[j]] = [bag[j], bag[i]];
+  }
+  bag.slice(0, 3).forEach(([name, how], i) => console.log(`${RANDOM[i]}: ${name} (${how})`));
+}
+
+/* request.json from before this split ({ at, request }, older { em, pedido }) was the three's */
+function requests() {
+  const p = readJson(join(DIR, "request.json"));
+  if (p && ("at" in p || "em" in p)) return { random: { at: p.at ?? p.em }, manual: null, changes: {} };
+  return { random: p?.random ?? null, manual: p?.manual ?? null, changes: p?.changes ?? {} };
+}
+
+const attribute = (html, re) => {
+  const m = re.exec(html);
+  return m ? m[1].replace(/\s+/g, " ").trim() : null;
+};
+
+/* The ready signal render waits for, after measuring the content box:
+   the union of the visible leaves (an <svg> counts whole), without what covers
+   the whole frame (background, texture). It becomes a [data-continues] that
+   render.mjs --measure returns. */
+const READY = `<script>document.fonts.ready.then(()=>{
+  const W=innerWidth,H=innerHeight;let x0=W,y0=H,x1=0,y1=0;
+  for(const e of document.body.querySelectorAll("*")){
+    const tag=e.tagName.toLowerCase();
+    if(["script","style","link","meta"].includes(tag))continue;
+    if(tag!=="svg"&&e.closest("svg"))continue;
+    if(tag!=="svg"&&e.children.length)continue;
+    const cs=getComputedStyle(e);if(cs.visibility==="hidden"||+cs.opacity===0)continue;
+    const r=e.getBoundingClientRect();if(r.width<1||r.height<1)continue;
+    if(r.width>=.9*W&&r.height>=.9*H)continue;
+    x0=Math.min(x0,Math.max(0,r.left));y0=Math.min(y0,Math.max(0,r.top));
+    x1=Math.max(x1,Math.min(W,r.right));y1=Math.max(y1,Math.min(H,r.bottom));
+  }
+  if(x1>x0&&y1>y0){const m=document.createElement("div");m.dataset.continues="content";
+    Object.assign(m.style,{position:"fixed",left:x0+"px",top:y0+"px",width:(x1-x0)+"px",height:(y1-y0)+"px",pointerEvents:"none"});
+    document.body.appendChild(m);}
+  window.__ready=true;
+})</script>`;
+
+/* 9:16 has the content centred in x and y (the profile grid crops through the middle) */
+const MEASUREMENTS = "MEASUREMENTS ";
+function offCenter(stdout, t) {
+  if (t.h <= t.w) return null;
+  const line = (stdout ?? "").split("\n").find(l => l.startsWith(MEASUREMENTS));
+  const box = line ? JSON.parse(line.slice(MEASUREMENTS.length)).find(m => m.name === "content") : null;
+  if (!box) return null;
+  const dx = (box.x + box.w / 2) / t.w - 0.5,
+    dy = (box.y + box.h / 2) / t.h - 0.5;
+  const pct = n => `${Math.round(Math.abs(n) * 100)}%`;
+  const errors = [
+    Math.abs(dx) > 0.05 ? `${pct(dx)} para a ${dx < 0 ? "esquerda" : "direita"}` : null,
+    Math.abs(dy) > 0.06 ? `${pct(dy)} para ${dy < 0 ? "cima" : "baixo"}` : null,
+  ].filter(Boolean);
+  return errors.length ? `conteúdo fora do centro em 9:16 (${errors.join(", ")}): centre em x e y` : null;
+}
+
+function render(list) {
+  const t = size();
+  const requested = list ? list.split(",").filter(Boolean) : IDS;
+  const invalid = requested.filter(id => !IDS.includes(id));
+  if (invalid.length) fail(`versão inválida: ${invalid.join(", ")} (use ${IDS.join(", ")})`);
+  const present = requested.filter(id => existsSync(join(DIR, `${id}.html`)));
+  if (!present.length) fail(`escreva thumbnail/${requested.join(".html, ")}.html antes (${t.w}×${t.h}, ${t.aspect})`);
+  const missing = requested.filter(id => list && !present.includes(id));
+  if (missing.length) console.warn(`aviso: sem HTML para ${missing.join(", ")}`);
+
+  const previous = readJson(JSON_FILE);
+  /* the format changed (video redone in another aspect): the old versions are no use */
+  const same = previous?.format?.w === t.w && previous?.format?.h === t.h;
+  const versions = new Map((same ? (previous.versions ?? []) : []).map(v => [v.id, v]));
+  const { manual, changes } = requests();
+  for (const id of present) {
+    const html = readFileSync(join(DIR, `${id}.html`), "utf8");
+    const png = join(DIR, `${id}.png`);
+    /* the previous image goes to history/thumbnail/<vN>/ (the HTML was already rewritten) */
+    const kept = keepPrevious(VIDEO_DIR, "thumbnail", id, [`thumbnail/${id}.png`]);
+
+    /* side copy, with the ready signal render waits for, so the font
+       loads without the scene having to remember it */
+    const temp = join(DIR, `.render-${id}.html`);
+    writeFileSync(temp, /<\/body>/i.test(html) ? html.replace(/<\/body>/i, `${READY}</body>`) : html + READY);
+    const r = spawnSync(
+      "node",
+      [RENDER, temp, "--still", png, "--at", "0", "--w", String(t.w), "--h", String(t.h), "--measure"],
+      { encoding: "utf8" },
+    );
+    rmSync(temp, { force: true });
+    if (r.status !== 0)
+      fail(`${id}: o render saiu com ${r.status}\n${(r.stderr || r.stdout || "").trim().slice(-600)}`);
+    kept.close();
+    const off = offCenter(r.stdout, t);
+    if (off) console.warn(`aviso: ${id}: ${off}`);
+
+    versions.set(id, {
+      id,
+      name: attribute(html, /<title[^>]*>([^<]*)<\/title>/i) ?? id,
+      /* `descricao` is the legacy meta name */
+      description: attribute(html, /<meta\s+name=["'](?:description|descricao)["']\s+content=["']([^"']*)["']/i),
+      html: `thumbnail/${id}.html`,
+      png: `thumbnail/${id}.png`,
+      generated_at: new Date().toISOString(),
+      ...(id === MANUAL ? { instruction: manual?.instruction ?? null } : {}),
+      /* what was asked to change in this version (the UI shows it); gone when it is redone from scratch */
+      ...(changes[id] ? { change: changes[id] } : {}),
+    });
+    console.log(`${id}: thumbnail/${id}.png (${t.w}×${t.h})`);
+  }
+
+  /* the selected one only drops if its image changed: it goes to history */
+  let selected = same ? (previous?.selected ?? null) : null;
+  const final = join(DIR, "thumbnail.png");
+  if (!selected || present.includes(selected)) {
+    if (existsSync(final)) {
+      keepPrevious(VIDEO_DIR, "thumbnail", "final", ["thumbnail/thumbnail.png"]).close();
+      rmSync(final, { force: true });
+    }
+    selected = null;
+  }
+  writeJson(JSON_FILE, {
+    format: t,
+    generated_at: new Date().toISOString(),
+    versions: IDS.map(id => versions.get(id)).filter(Boolean),
+    selected,
+    ...(selected && previous?.selected_at ? { selected_at: previous.selected_at } : {}),
+  });
+  console.log(
+    `${present.length} versão(ões) renderizada(s) · escolha com: node tools/thumbnail.mjs ${target} choose <${IDS.join("|")}>`,
+  );
+}
+
+/* before changing a version: the current HTML and PNG go to history/thumbnail/<vN>/ */
+function snapshot(id) {
+  if (!IDS.includes(id)) fail(`versão inválida: ${id || "(vazia)"} (use ${IDS.join(", ")})`);
+  if (!existsSync(join(DIR, `${id}.html`))) fail(`thumbnail/${id}.html não existe`);
+  keepPrevious(VIDEO_DIR, "thumbnail", id, [`thumbnail/${id}.html`, `thumbnail/${id}.png`]).close({ keep: true });
+  console.log(`${id}: versão de agora guardada em history/thumbnail/${id}/`);
+}
+
+function choose(id) {
+  const data = readJson(JSON_FILE);
+  if (id === "none") {
+    const final = join(DIR, "thumbnail.png");
+    if (existsSync(final)) {
+      keepPrevious(VIDEO_DIR, "thumbnail", "final", ["thumbnail/thumbnail.png"]).close();
+      rmSync(final, { force: true });
+    }
+    if (data) {
+      delete data.selected_at;
+      writeJson(JSON_FILE, { ...data, selected: null });
+    }
+    console.log("nenhuma thumbnail selecionada: a publicação usa um quadro do vídeo");
+    return;
+  }
+  if (!IDS.includes(id)) fail(`versão inválida: ${id || "(vazia)"} (use ${IDS.join(", ")} ou none)`);
+  if (!data?.versions?.some(v => v.id === id)) fail(`a versão ${id} ainda não foi renderizada`);
+  const source = join(DIR, `${id}.png`);
+  if (!existsSync(source)) fail(`thumbnail/${id}.png não existe: renderize de novo`);
+  const final = join(DIR, "thumbnail.png");
+  keepPrevious(VIDEO_DIR, "thumbnail", "final", ["thumbnail/thumbnail.png"]).close();
+  copyFileSync(source, final);
+  writeJson(JSON_FILE, { ...data, selected: id, selected_at: new Date().toISOString() });
+  console.log(`${id} é a thumbnail do vídeo: thumbnail/thumbnail.png`);
+}
+
+mkdirSync(DIR, { recursive: true });
+if (cmd === "size") console.log(JSON.stringify(size()));
+else if (cmd === "draw") draw();
+else if (cmd === "render") render(rest[0]);
+else if (cmd === "snapshot") snapshot(rest[0]);
+else if (cmd === "choose") choose(rest[0]);
+else if (cmd === "status") console.log(JSON.stringify(readJson(JSON_FILE) ?? { versions: [], size: size() }, null, 2));
+else fail(`comando desconhecido: ${cmd}`);

package/tools/timing.mjs

@@ -0,0 +1,108 @@
+/* ============================================================================
+   Time references in scenes.json → seconds inside the scene.
+
+   Each video's build.mjs uses this to place every motion beat exactly where
+   the voice says the word:
+
+     import { loadVideo, beatTime } from "../../../tools/timing.mjs";
+     const video = loadVideo(new URL("..", import.meta.url).pathname);
+     for (const scene of video.scenes) {
+       for (const beat of scene.beats) {
+         const t = beatTime(scene, beat);               // seconds in the scene
+       }
+     }
+
+   Accepted forms:
+     2.4                        number, passed through
+     "c01f2"                    line start
+     "c01f2:end"                line end (legacy ":fim" also accepted)
+     "c01f2:milissegundos"      start of the word's first occurrence
+     "c01f2:token#2"            second occurrence
+     "c01f2:end-0.3"            any form above with an offset (+/-)
+
+   Before `omnivideo.py timing` runs, the line has no audio yet: its time is
+   estimated from the config's average pace and `video.provisional` is true.
+   Good for stills and contact sheets; the final render requires real timing.
+   ============================================================================ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DATA_ROOT as ROOT } from "./lib/paths.mjs";
+
+const CFG = JSON.parse(readFileSync(join(ROOT, "omnivideo.config.json"), "utf8"));
+
+const norm = w =>
+  w
+    .toLowerCase()
+    .normalize("NFC")
+    .replace(/[^\p{L}\p{N}]/gu, "");
+
+export function loadVideo(videoDir) {
+  const video = JSON.parse(readFileSync(join(videoDir, "scenes.json"), "utf8"));
+  const { lead_in, pause_between_lines, final_hold, words_per_second } = CFG.timing;
+  video.provisional = false;
+  let clock = 0;
+  for (const scene of video.scenes) {
+    let cursor = scene.lead_in ?? lead_in;
+    for (const line of scene.lines ?? []) {
+      if (line.start == null) {
+        /* with audio (the voice generated before `timing`), the duration is real */
+        video.provisional = true;
+        const n = line.text.split(/\s+/).length;
+        line.start = cursor;
+        line.end = cursor + (line.dur ?? n / words_per_second);
+      }
+      cursor = line.end + pause_between_lines;
+    }
+    /* without `timing` run (including no lines yet) duration and start are
+       estimated too */
+    if (scene.duration == null) {
+      video.provisional = true;
+      const end = scene.lines?.length ? scene.lines.at(-1).end : 0;
+      scene.duration = Math.max(end + (scene.hold ?? final_hold), scene.min_duration ?? 0);
+    }
+    if (scene.start == null) {
+      video.provisional = true;
+      scene.start = clock;
+    }
+    clock = scene.start + scene.duration;
+  }
+  video.total_duration ??= clock;
+  return video;
+}
+
+/* A beat is born in composition with only `t` (provisional
+   seconds, for the still and the contact sheet). Narration ties each beat to a
+   line or word in `enters_with`, and from then on that rules. */
+export function beatTime(scene, beat) {
+  if (beat.enters_with != null) return resolveTime(scene, beat.enters_with);
+  if (beat.t != null) return beat.t;
+  throw new Error(`${scene.id}: beat ${beat.element} sem enters_with nem t`);
+}
+
+export function resolveTime(scene, ref) {
+  if (typeof ref === "number") return ref;
+  const m = /^([^:+-]+)(?::([^+\-#]+)(?:#(\d+))?)?([+-]\d+(?:\.\d+)?)?$/.exec(String(ref).trim());
+  if (!m) throw new Error(`referência de tempo inválida: ${ref}`);
+  const [, lineId, target, occurrence, offset] = m;
+  const line = (scene.lines ?? []).find(l => l.id === lineId);
+  if (!line) throw new Error(`${scene.id}: fala ${lineId} não existe`);
+
+  let t;
+  if (!target) t = line.start;
+  else if (target === "end" || target === "fim")
+    t = line.end; // ":fim" = legacy alias
+  else if (line.words) {
+    const hits = line.words.filter(p => norm(p.w) === norm(target));
+    const hit = hits[(+occurrence || 1) - 1];
+    if (!hit) throw new Error(`${scene.id}: “${target}” não aparece na fala ${lineId}`);
+    t = line.start + hit.s;
+  } else {
+    /* no word timing yet: proportional to the position in the text */
+    const words = line.text.split(/\s+/);
+    const idx = words.findIndex(p => norm(p) === norm(target));
+    if (idx < 0) throw new Error(`${scene.id}: “${target}” não aparece na fala ${lineId}`);
+    t = line.start + ((line.end - line.start) * idx) / words.length;
+  }
+  return Math.round((t + (offset ? +offset : 0)) * 1000) / 1000;
+}