@crievo/omni 0.0.0-stage → 0.1.0

package/tools/editor.mjs

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+/* ============================================================================
+   Editor pela linha de comando: o que a timeline do studio (etapa Editor) faz
+   na mão, para o Claude fazer pelo chat de edição (skill av-editor). Grava no
+   scenes.json com as mesmas regras da tela (tools/cuts.mjs, tools/soundtrack.mjs)
+   e guarda a versão anterior em history/editor/. Não renderiza: depois de
+   editar, `node tools/assemble.mjs videos/<slug>` refaz o export.
+
+     node tools/editor.mjs show videos/<slug> [--json]
+         a timeline: cenas e falas com os clips (posição no vídeo), o texto e as
+         palavras com tempo, os beats com som, a cama e os cortes de área
+     node tools/editor.mjs silences videos/<slug> [--min 0.6]
+         as pausas da voz maiores que --min (s), entre palavras, já tirando o
+         que está cortado
+     node tools/editor.mjs cut videos/<slug> --from 12.3 --to 13.1
+         corte de área: o trecho sai do export e o resto emenda
+     node tools/editor.mjs cut-silences videos/<slug> [--min 0.6] [--padding 0.15]
+         corta cada pausa maior que --min, deixando --padding de respiro de cada lado
+     node tools/editor.mjs uncut videos/<slug> <n|all>
+         desfaz o corte n (a ordem do `show`) ou todos
+     node tools/editor.mjs speed videos/<slug> <100–150>
+         velocidade do export (%): imagem, voz e efeitos aceleram juntos; a música de
+         fundo (cama) não: ela fica isolada, tanto da velocidade quanto dos cortes
+     node tools/editor.mjs speed videos/<slug> <50–200> <cena|fala>[:k] | bed
+         velocidade só do clip k (1, 2…; padrão 1) de uma cena ou fala, ou só da música
+         de fundo: o clip dura menos e começa no mesmo lugar (a voz não muda de tom)
+     node tools/editor.mjs split videos/<slug> <cena|fala> <t>
+         quebra o clip da cena (c02) ou da fala (c02f1) que está em t, em dois
+     node tools/editor.mjs move videos/<slug> <cena|fala>[:k] <offset> [--add]
+         põe o clip k (1, 2…; padrão 1) a `offset` segundos do lugar dele; --add soma
+     node tools/editor.mjs delete videos/<slug> <cena|fala>:k
+         tira o clip k (a imagem para no último quadro do anterior; a voz fica muda)
+     node tools/editor.mjs restore videos/<slug> <cena|fala|all>
+         volta o clip inteiro, no lugar
+
+   Tempos em segundos do vídeo sem cortes (o do scenes.json). Com --edited,
+   os tempos que você passa são os da timeline já cortada (o que o usuário vê
+   no editor, e o tempo do export).
+   ============================================================================ */
+/* (the header above is printed as the usage text, so it stays in Portuguese) */
+
+import { readFileSync, writeFileSync, renameSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadVideo, beatTime } from "./timing.mjs";
+import { normalizeCuts, removedDuration, toEdited, toOriginal, isCut } from "./cuts.mjs";
+import {
+  videoClips,
+  lineClips,
+  voiceSpans,
+  animationInstant,
+  lineDuration,
+  clipLength,
+  clipSpeed,
+  CLIP_SPEED,
+} from "./soundtrack.mjs";
+import { applyClips, sanitizeBed, sanitizeSpeed } from "./sound.mjs";
+import { keepPrevious } from "./history.mjs";
+
+const args = process.argv.slice(2);
+const [cmd, dirArg] = args;
+const flag = n => args.includes(`--${n}`);
+const option = n => {
+  const i = args.indexOf(`--${n}`);
+  return i < 0 ? undefined : args[i + 1];
+};
+const positionals = args
+  .slice(2)
+  .filter(
+    (a, i, l) =>
+      !a.startsWith("--") &&
+      !(i > 0 && l[i - 1].startsWith("--") && ["from", "to", "min", "padding"].includes(l[i - 1].slice(2))),
+  );
+function fail(msg) {
+  console.error(`erro: ${msg}`);
+  process.exit(1);
+}
+if (!cmd || !dirArg || !existsSync(join(resolve(dirArg), "scenes.json"))) {
+  const source = readFileSync(fileURLToPath(import.meta.url), "utf8").split("\n");
+  console.log(
+    source
+      .slice(
+        1,
+        source.findIndex((l, i) => i > 1 && l.includes("=====*/")),
+      )
+      .join("\n"),
+  );
+  process.exit(2);
+}
+
+const dir = resolve(dirArg);
+const file = join(dir, "scenes.json");
+const raw = JSON.parse(readFileSync(file, "utf8"));
+const video = loadVideo(dir);
+const { fps } = video.format;
+const total = video.total_duration;
+let cuts = normalizeCuts(video.cuts, total, fps);
+const ed = t => toEdited(t, cuts);
+/* time from the command line → scenes.json time */
+const input = s => {
+  const n = Number(s);
+  if (!Number.isFinite(n)) fail(`tempo inválido: ${s}`);
+  return flag("edited") ? toOriginal(n, cuts) : n;
+};
+const mmss = s => `${Math.floor(s / 60)}:${(s % 60).toFixed(2).padStart(5, "0")}`;
+const when = s => `${s.toFixed(2)}s${cuts.length ? ` (${mmss(ed(s))} no editor)` : ` (${mmss(s)})`}`;
+
+/* scene (c02) or line (c02f1) */
+function target(id) {
+  for (const scene of video.scenes) {
+    if (scene.id === id)
+      return { kind: "video", id, scene, base: scene.start, clips: videoClips(scene), step: 1 / fps };
+    const line = (scene.lines ?? []).find(l => l.id === id);
+    if (line)
+      return { kind: "voice", id, scene, line, base: scene.start + line.start, clips: lineClips(line), step: 0.001 };
+  }
+  fail(`não existe cena nem fala "${id}" (veja: node tools/editor.mjs show ${dirArg})`);
+}
+const idAndK = s => {
+  const [id, k] = String(s ?? "").split(":");
+  return { id, k: k ? Number(k) - 1 : 0 };
+};
+
+function save(summary) {
+  const previous = keepPrevious(dir, "editor", null, ["scenes.json"]);
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(raw, null, 2) + "\n");
+  renameSync(tmp, file);
+  previous.close();
+  console.log(summary);
+  console.log("gravado no scenes.json; o export muda com: node tools/assemble.mjs " + dirArg);
+}
+
+/* new clips of a scene or line, validated as the screen validates, copied into scenes.json */
+function newClips(a, clips) {
+  const draft = a.kind === "video" ? { scene_clips: { [a.id]: clips } } : { line_clips: { [a.id]: clips } };
+  try {
+    applyClips(video, draft);
+  } catch (e) {
+    fail(e.message);
+  }
+  const rawScene = raw.scenes.find(c => c.id === a.scene.id);
+  const vs = video.scenes.find(c => c.id === a.scene.id);
+  if (a.kind === "video") {
+    /* video_em = legacy name of video_offset */
+    for (const k of ["clips", "video_offset", "video_em"]) {
+      if (k in vs) rawScene[k] = vs[k];
+      else delete rawScene[k];
+    }
+  } else {
+    const rawLine = rawScene.lines.find(l => l.id === a.id),
+      vl = vs.lines.find(l => l.id === a.id);
+    if ("clips" in vl) rawLine.clips = vl.clips;
+    else delete rawLine.clips;
+  }
+}
+
+function saveCuts(next) {
+  const n = normalizeCuts(next, total, fps);
+  if (total - removedDuration(n) < 0.5) fail("os cortes tirariam o vídeo inteiro");
+  if (n.length) raw.cuts = n;
+  else delete raw.cuts;
+  cuts = n;
+}
+
+/* the spoken words, in video time, already where the voice clips put them */
+function words() {
+  const out = [];
+  for (const scene of video.scenes)
+    for (const l of scene.lines ?? []) {
+      for (const p of l.words ?? [])
+        for (const [s, e] of voiceSpans(scene, l, p.s, p.e)) out.push({ line: l.id, w: p.w, s, e });
+    }
+  return out.sort((a, b) => a.s - b.s);
+}
+
+function silences(min) {
+  const ps = words().filter(p => !isCut((p.s + p.e) / 2, cuts));
+  const out = [];
+  for (let i = 1; i < ps.length; i++) {
+    const a = ps[i - 1].e,
+      b = ps[i].s;
+    if (b - a < min) continue;
+    /* whatever was already cut in there doesn't count */
+    const free = b - a - cuts.reduce((s, c) => s + Math.max(0, Math.min(b, c.to) - Math.max(a, c.from)), 0);
+    if (free >= min) out.push({ from: a, to: b, dur: free, before: ps[i - 1], after: ps[i] });
+  }
+  return out;
+}
+
+switch (cmd) {
+  case "show": {
+    const data = {
+      format: video.format,
+      total,
+      total_edited: +(total - removedDuration(cuts)).toFixed(3),
+      speed: sanitizeSpeed(raw.speed),
+      provisional: video.provisional,
+      cuts: cuts.map((c, i) => ({ n: i + 1, ...c, in_editor: +ed(c.from).toFixed(3) })),
+      scenes: video.scenes.map(c => ({
+        id: c.id,
+        title: c.title,
+        start: c.start,
+        duration: c.duration,
+        html: c.html,
+        mp4: c.mp4,
+        clips: videoClips(c).map((cl, k) => ({
+          k: k + 1,
+          ...cl,
+          in_video: [
+            +(c.start + cl.from + cl.offset).toFixed(3),
+            +(c.start + cl.from + cl.offset + clipLength(cl)).toFixed(3),
+          ],
+        })),
+        beats: (c.beats ?? []).map(b => {
+          let t = null;
+          try {
+            t = animationInstant(c, beatTime(c, b));
+          } catch {
+            /* no timing */
+          }
+          return { element: b.element, t: t == null ? null : +t.toFixed(3), sound: b.sound ?? null };
+        }),
+        lines: (c.lines ?? []).map(l => ({
+          id: l.id,
+          text: l.text,
+          dur: lineDuration(l),
+          clips: lineClips(l).map((cl, k) => ({
+            k: k + 1,
+            ...cl,
+            in_video: [
+              +(c.start + l.start + cl.from + cl.offset).toFixed(3),
+              +(c.start + l.start + cl.from + cl.offset + clipLength(cl)).toFixed(3),
+            ],
+          })),
+        })),
+      })),
+      bed: video.bed ?? null,
+      words: words().map(p => ({ ...p, s: +p.s.toFixed(3), e: +p.e.toFixed(3) })),
+    };
+    if (flag("json")) {
+      console.log(JSON.stringify(data, null, 1));
+      break;
+    }
+    console.log(
+      `${video.format.w}×${video.format.h} @ ${fps} · ${total.toFixed(2)}s${cuts.length ? ` · ${data.total_edited.toFixed(2)}s com os cortes` : ""}${video.provisional ? " · tempos provisórios" : ""}`,
+    );
+    for (const c of data.scenes) {
+      console.log(
+        `\n${c.id} ${c.title ?? ""} · ${c.start.toFixed(2)}–${(c.start + c.duration).toFixed(2)}s · ${c.html ?? ""}`,
+      );
+      for (const cl of c.clips)
+        console.log(
+          `  animação ${c.id}:${cl.k}  MP4 ${cl.from.toFixed(2)}–${cl.to.toFixed(2)}  no vídeo ${when(cl.in_video[0])} → ${cl.in_video[1].toFixed(2)}s${cl.offset ? `  offset ${cl.offset > 0 ? "+" : ""}${cl.offset}` : ""}${cl.speed ? `  ${Math.round(cl.speed * 100)}%` : ""}`,
+        );
+      if (!c.clips.length) console.log("  animação apagada");
+      for (const l of c.lines) {
+        console.log(`  fala ${l.id} "${l.text}"`);
+        for (const cl of l.clips)
+          console.log(
+            `    voz ${l.id}:${cl.k}  áudio ${cl.from.toFixed(2)}–${cl.to.toFixed(2)}  no vídeo ${when(cl.in_video[0])} → ${cl.in_video[1].toFixed(2)}s${cl.offset ? `  offset ${cl.offset > 0 ? "+" : ""}${cl.offset}` : ""}${cl.speed ? `  ${Math.round(cl.speed * 100)}%` : ""}`,
+          );
+      }
+      for (const b of c.beats.filter(b => b.sound))
+        console.log(
+          `  beat ${b.element} ${b.t == null ? "(num pedaço apagado)" : when(b.t)} · som ${JSON.stringify(b.sound)}`,
+        );
+    }
+    if (data.bed) console.log(`\ncama: ${JSON.stringify(data.bed)}`);
+    console.log(
+      cuts.length
+        ? `\ncortes de área:\n${data.cuts.map(c => `  ${c.n}. ${c.from.toFixed(2)}–${c.to.toFixed(2)}s (${(c.to - c.from).toFixed(2)}s, em ${mmss(c.in_editor)} no editor)`).join("\n")}`
+        : "\nsem cortes de área",
+    );
+    console.log(`\npalavras (tempo do vídeo):\n${data.words.map(p => `${p.s.toFixed(2)} ${p.w}`).join(" · ")}`);
+    break;
+  }
+  case "silences": {
+    const min = Number(option("min") ?? 0.6);
+    const l = silences(min);
+    if (!l.length) {
+      console.log(`nenhuma pausa maior que ${min}s`);
+      break;
+    }
+    for (const p of l)
+      console.log(
+        `${p.from.toFixed(2)}–${p.to.toFixed(2)}s (${p.dur.toFixed(2)}s, em ${mmss(ed(p.from))} no editor)  "${p.before.w}" … "${p.after.w}"  ${p.before.line === p.after.line ? `dentro de ${p.before.line}` : `${p.before.line} → ${p.after.line}`}`,
+      );
+    console.log(`${l.length} pausa(s), ${l.reduce((s, p) => s + p.dur, 0).toFixed(2)}s no total`);
+    break;
+  }
+  case "cut": {
+    const from = input(option("from")),
+      to = input(option("to"));
+    if (!(to > from)) fail("--to tem de ser depois de --from");
+    saveCuts([...cuts, { from, to }]);
+    save(
+      `cortado ${from.toFixed(2)}–${to.toFixed(2)}s (${(to - from).toFixed(2)}s) · ${cuts.length} corte(s), ${removedDuration(cuts).toFixed(2)}s fora`,
+    );
+    break;
+  }
+  case "speed": {
+    if (positionals[0] == null) fail("diga a velocidade em % (100 a 150)");
+    /* only one clip, or only the background music */
+    if (positionals[1] != null) {
+      const pct = Number(positionals[0]);
+      const [lo, hi] = CLIP_SPEED.map(x => x * 100);
+      if (!(pct >= lo && pct <= hi)) fail(`velocidade de um clip ou da música: ${lo} a ${hi}%`);
+      if (positionals[1] === "bed") {
+        if (!raw.bed) fail("o vídeo não tem música de fundo");
+        const bed = typeof raw.bed === "string" ? { name: raw.bed } : { ...raw.bed };
+        bed.speed = pct / 100;
+        try {
+          raw.bed = sanitizeBed(dir, bed, total);
+        } catch (e) {
+          fail(e.message);
+        }
+        save(`música de fundo a ${pct}%`);
+        break;
+      }
+      const { id, k } = idAndK(positionals[1]);
+      const a = target(id);
+      if (!a.clips[k]) fail(`${id} não tem o clip ${k + 1}`);
+      newClips(
+        a,
+        a.clips.map((c, i) => (i === k ? { ...c, speed: pct / 100 } : c)),
+      );
+      const c = { ...a.clips[k], speed: pct / 100 };
+      save(`${id}:${k + 1} a ${pct}%: dura ${clipLength(c).toFixed(2)}s em vez de ${(c.to - c.from).toFixed(2)}s`);
+      break;
+    }
+    const v = sanitizeSpeed(positionals[0]);
+    raw.speed = v;
+    save(`velocidade do export: ${Math.round(v * 100)}% (${(total / v - removedDuration(cuts) / v).toFixed(2)}s)`);
+    break;
+  }
+  case "cut-silences": {
+    const min = Number(option("min") ?? 0.6),
+      padding = Number(option("padding") ?? 0.15);
+    const next = silences(min)
+      .map(p => ({ from: p.from + padding, to: p.to - padding }))
+      .filter(c => c.to - c.from >= 2 / fps);
+    if (!next.length) {
+      console.log(`nenhuma pausa maior que ${min}s para cortar`);
+      break;
+    }
+    const before = removedDuration(cuts);
+    saveCuts([...cuts, ...next]);
+    save(
+      `${next.length} pausa(s) cortada(s), deixando ${padding}s de cada lado: ${(removedDuration(cuts) - before).toFixed(2)}s a menos (${(total - removedDuration(cuts)).toFixed(2)}s no total)`,
+    );
+    break;
+  }
+  case "uncut": {
+    const q = positionals[0];
+    if (q === "all") saveCuts([]);
+    else {
+      const i = Number(q) - 1;
+      if (!cuts[i]) fail(`não existe o corte ${q} (veja: show)`);
+      saveCuts(cuts.filter((_, j) => j !== i));
+    }
+    save(`${q === "all" ? "todos os cortes desfeitos" : `corte ${q} desfeito`} · ${cuts.length} corte(s)`);
+    break;
+  }
+  case "split": {
+    const a = target(positionals[0]);
+    const t = input(positionals[1]);
+    const k = a.clips.findIndex(c => t > a.base + c.from + c.offset && t < a.base + c.from + c.offset + clipLength(c));
+    if (k < 0) fail(`nenhum clip de ${a.id} passa por ${t.toFixed(2)}s`);
+    const c = a.clips[k];
+    /* the point in the file: a sped clip covers speed seconds of it per second of video */
+    const local = Math.round((c.from + (t - (a.base + c.from + c.offset)) * clipSpeed(c)) / a.step) * a.step;
+    if (local - c.from < a.step || c.to - local < a.step) fail("ponto colado na borda do clip");
+    newClips(a, [...a.clips.slice(0, k), { ...c, to: local }, { ...c, from: local }, ...a.clips.slice(k + 1)]);
+    save(`${a.id}:${k + 1} quebrado em ${t.toFixed(2)}s: agora ${a.id}:${k + 1} e ${a.id}:${k + 2}`);
+    break;
+  }
+  case "move": {
+    const { id, k } = idAndK(positionals[0]);
+    const a = target(id);
+    if (!a.clips[k]) fail(`${id} não tem o clip ${k + 1}`);
+    const n = Number(positionals[1]);
+    if (!Number.isFinite(n)) fail("diga quanto: move <id>[:k] <segundos>");
+    const offset = flag("add") ? a.clips[k].offset + n : n;
+    newClips(
+      a,
+      a.clips.map((c, i) => (i === k ? { ...c, offset } : c)),
+    );
+    save(`${id}:${k + 1} a ${offset > 0 ? "+" : ""}${offset.toFixed(3)}s do lugar`);
+    break;
+  }
+  case "delete": {
+    const { id, k } = idAndK(positionals[0]);
+    const a = target(id);
+    if (!a.clips[k]) fail(`${id} não tem o clip ${k + 1}`);
+    newClips(
+      a,
+      a.clips.filter((_, i) => i !== k),
+    );
+    save(
+      `${id}:${k + 1} apagado (${a.clips[k].from.toFixed(2)}–${a.clips[k].to.toFixed(2)}s do ${a.kind === "video" ? "MP4" : "áudio"})`,
+    );
+    break;
+  }
+  case "restore": {
+    const q = positionals[0];
+    const ids = q === "all" ? video.scenes.flatMap(c => [c.id, ...(c.lines ?? []).map(l => l.id)]) : [q];
+    for (const id of ids) {
+      const a = target(id);
+      newClips(a, [{ from: 0, to: a.kind === "video" ? a.scene.duration : lineDuration(a.line), offset: 0 }]);
+    }
+    save(`${q === "all" ? "todas as cenas e falas" : q} de volta inteiras, no lugar`);
+    break;
+  }
+  default:
+    fail(
+      `comando desconhecido: ${cmd} (show, silences, cut, cut-silences, uncut, speed, split, move, delete, restore)`,
+    );
+}

package/tools/epidemic-capture.js

@@ -0,0 +1,54 @@
+/* ============================================================================
+   Effect capture on Epidemic Sound, to paste into Claude in Chrome's
+   javascript_tool with an effects search open
+   (https://www.epidemicsound.com/sound-effects/search/?term=<term>).
+
+   `node tools/sound.mjs capture [n]` prints this code with N replaced.
+
+   The player plays each preview through an <audio> that is not in the page:
+   neither the extension's Network tab nor performance.getEntries() show the
+   MP3. What works is intercepting the media element's `src`: each play writes
+   the URL https://audiocdn.epidemicsound.com/lqmp3/<id>.mp3 there, which
+   `sound.mjs download` takes to the video's folder.
+
+   Take a screenshot of the tab first: the list only mounts with the tab painted,
+   and running in a background tab hangs javascript_tool. Waits for the list (up to 10 s), plays the first N results one by one, pauses
+   at the end and returns [{ title, duration, url }]. A result without url: the play
+   did not respond within 3 s. Empty list: the page did not load or changed layout
+   (each result is a [data-testid=track-row] with a "Play <title>" button).
+   ============================================================================ */
+const N = __N__;
+if (!window.__sfxHook) {
+  const d = Object.getOwnPropertyDescriptor(HTMLMediaElement.prototype, "src");
+  Object.defineProperty(HTMLMediaElement.prototype, "src", {
+    configurable: true,
+    get() {
+      return d.get.call(this);
+    },
+    set(v) {
+      if (/audiocdn\.epidemicsound\.com\/lqmp3\//.test(v)) window.__sfxLast = String(v);
+      d.set.call(this, v);
+    },
+  });
+  window.__sfxHook = true;
+}
+const wait = ms => new Promise(r => setTimeout(r, ms));
+/* the list arrives a few seconds after the page */
+for (let i = 0; i < 100 && !document.querySelector('[data-testid="track-row"] button[aria-label^="Play "]'); i++)
+  await wait(100);
+/* whatever is playing is labeled "Pause …": pause it before starting */
+document.querySelector('[data-testid="track-row"] button[aria-label^="Pause "]')?.click();
+await wait(200);
+const found = [];
+for (const row of [...document.querySelectorAll('[data-testid="track-row"]')].slice(0, N)) {
+  const b = row.querySelector('button[aria-label^="Play "]');
+  if (!b) continue;
+  /* the label becomes "Pause …" after play: read it before clicking */
+  const title = b.getAttribute("aria-label").replace(/^Play /, "");
+  window.__sfxLast = null;
+  b.click();
+  for (let i = 0; i < 30 && !window.__sfxLast; i++) await wait(100);
+  found.push({ title, duration: row.innerText.match(/\b\d+:\d{2}\b/)?.[0] ?? null, url: window.__sfxLast });
+}
+document.querySelector('[data-testid="track-row"] button[aria-label^="Pause "]')?.click();
+found;

package/tools/fanout.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/* ============================================================================
+   The fan-out guard from the command line (tools/lib/fanout.mjs explains why).
+
+     node tools/fanout.mjs claim   videos/<slug> <kind> cNN [--run R]
+         a fork takes its scene before writing anything. Exit 3 = refused: the
+         scene is someone else's (another run, or already started): stop.
+         Without --run (a scene call made alone), prints the run it created.
+     node tools/fanout.mjs done    videos/<slug> <kind> cNN --run R
+     node tools/fanout.mjs release videos/<slug> <kind> cNN[,cMM]
+         frees scenes whose fork died, so `plan` hands them out again
+     node tools/fanout.mjs status  videos/<slug> [<kind>]
+
+   kind: compose (stage 3), wireframe (stage 2), narration (stage 4). The plans
+   are `compose.mjs plan`, `wireframe.mjs plan` and `narrate.mjs plan`.
+   ============================================================================ */
+
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { KINDS, FanoutError, claim, done, release, busy } from "./lib/fanout.mjs";
+
+const [cmd, target, kind, ids, ...rest] = process.argv.slice(2);
+const opt = n => {
+  const i = rest.indexOf(`--${n}`);
+  return i < 0 ? null : rest[i + 1];
+};
+const usage = () => {
+  console.error(
+    "uso: node tools/fanout.mjs claim videos/<slug> <tipo> cNN [--run R]\n" +
+      "     node tools/fanout.mjs done videos/<slug> <tipo> cNN --run R\n" +
+      "     node tools/fanout.mjs release videos/<slug> <tipo> cNN[,cMM]\n" +
+      `     node tools/fanout.mjs status videos/<slug> [<tipo>]   (tipos: ${KINDS.join(", ")})`,
+  );
+  process.exit(2);
+};
+if (!cmd || !target) usage();
+const dir = resolve(target);
+if (!existsSync(join(dir, "scenes.json"))) {
+  console.error(`erro: falta ${join(dir, "scenes.json")}`);
+  process.exit(2);
+}
+
+try {
+  if (cmd === "claim") {
+    if (!kind || !ids) usage();
+    const run = await claim(dir, kind, ids, opt("run"));
+    console.log(
+      `${ids}: sua (rodada ${run})${opt("run") ? "" : `. No fim: fanout.mjs done ${target} ${kind} ${ids} --run ${run}`}`,
+    );
+  } else if (cmd === "done") {
+    if (!kind || !ids || !opt("run")) usage();
+    await done(dir, kind, ids, opt("run"));
+    console.log(`${ids}: concluída (rodada ${opt("run")})`);
+  } else if (cmd === "release") {
+    if (!kind || !ids) usage();
+    const freed = await release(dir, kind, ids.split(",").filter(Boolean));
+    console.log(freed.length ? `liberadas: ${freed.join(" ")}` : "nada a liberar");
+  } else if (cmd === "status") {
+    for (const k of kind ? [kind] : KINDS) {
+      const held = busy(dir, k);
+      console.log(
+        `${k}: ${held.length ? held.map(b => `${b.id} ${b.state === "started" ? "rodando" : "na fila"} (rodada ${b.run}, ${b.age_min} min)`).join(", ") : "nada em andamento"}`,
+      );
+    }
+  } else usage();
+} catch (e) {
+  console.error(`erro: ${e.message}`);
+  process.exit(e instanceof FanoutError ? e.code : 1);
+}

package/tools/history.mjs

@@ -0,0 +1,70 @@
+/* ============================================================================
+   Previous versions of results. Before a tool overwrites a result (a
+   scene's still and sheet, render, sound, assembly), the version that was
+   there is copied, with its original mtime, to
+
+     videos/<slug>/history/<stage>/[<key>/]<file stamp>/
+
+   If the new result comes out identical, the copy is discarded: only what
+   changed is kept. The `history.versions` most recent of each result are kept
+   (config, default 5). The studio shows the versions in each stage's drawer and
+   links each one to the queue run that produced it by the file's time.
+
+     const previous = keepPrevious(dir, "render", "c04", ["motion/c04.mp4", "motion/c04.render.json"]);
+     ...write the new result...
+     previous.close();
+
+   The Python counterpart is tools/history.py (voice and captions).
+   ============================================================================ */
+
+import { existsSync, mkdirSync, copyFileSync, statSync, utimesSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join, basename } from "node:path";
+import { DATA_ROOT as ROOT } from "./lib/paths.mjs";
+
+const CFG = JSON.parse(readFileSync(join(ROOT, "omnivideo.config.json"), "utf8"));
+const VERSIONS = CFG.history?.versions ?? 5;
+
+const digest = file => createHash("sha1").update(readFileSync(file)).digest("hex");
+
+export function keepPrevious(dir, stage, key, files) {
+  const existing = files.filter(f => existsSync(join(dir, f)));
+  if (!existing.length) return { close() {} };
+  const base = join(dir, "history", stage, ...(key ? [key] : []));
+  const mtime = Math.max(...existing.map(f => statSync(join(dir, f)).mtimeMs));
+  const snapDir = join(base, new Date(mtime).toISOString().replace(/[:.]/g, "-"));
+  const before = Object.fromEntries(existing.map(f => [f, digest(join(dir, f))]));
+  /* already kept (a previous run died before closing): leave it as is */
+  const isNew = !existsSync(snapDir);
+  if (isNew) {
+    mkdirSync(snapDir, { recursive: true });
+    for (const f of existing) {
+      const dest = join(snapDir, basename(f));
+      copyFileSync(join(dir, f), dest);
+      const st = statSync(join(dir, f));
+      utimesSync(dest, st.atime, st.mtime);
+    }
+  }
+  return {
+    /* keep: the copy is the starting point of a change; stays even if the original didn't change */
+    close({ keep = false } = {}) {
+      const same = existing.every(f => existsSync(join(dir, f)) && digest(join(dir, f)) === before[f]);
+      if (same && isNew && !keep) rmSync(snapDir, { recursive: true, force: true });
+      prune(base);
+    },
+  };
+}
+
+/* the stamp is ISO: alphabetical order is time order */
+function prune(base) {
+  let versions;
+  try {
+    versions = readdirSync(base)
+      .filter(n => /^\d{4}-/.test(n))
+      .sort();
+  } catch {
+    return;
+  }
+  for (const v of versions.slice(0, Math.max(0, versions.length - VERSIONS)))
+    rmSync(join(base, v), { recursive: true, force: true });
+}

package/tools/history.py

@@ -0,0 +1,61 @@
+"""Previous versions of results: the Python twin of tools/history.mjs (voice and captions).
+
+    with keep_previous(dir, "voice", "c01f1", ["voice/c01f1.wav", "voice/c01f1.json"]):
+        ...write the new result...
+
+The version that was there goes, with its original mtime, to
+history/<stage>/[<key>/]<stamp>/. If the new result comes out identical (or the
+tool fails before writing), the copy is discarded. The most recent
+`history.versions` are kept (config, default 5).
+"""
+
+import hashlib
+import json
+import shutil
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+
+from omni_paths import DATA_ROOT as ROOT
+
+VERSIONS = json.loads((ROOT / "omnivideo.config.json").read_text()).get("history", {}).get("versions", 5)
+
+
+def digest(path):
+    return hashlib.sha1(path.read_bytes()).hexdigest()
+
+
+def prune(base):
+    """The stamp is ISO: alphabetical order is time order."""
+    if not base.is_dir():
+        return
+    versions = sorted(p for p in base.iterdir() if p.name[:4].isdigit())
+    for old in versions[: max(0, len(versions) - VERSIONS)]:
+        shutil.rmtree(old, ignore_errors=True)
+
+
+@contextmanager
+def keep_previous(dir, stage, key, files):
+    dir = Path(dir)
+    existing = [f for f in files if (dir / f).exists()]
+    if not existing:
+        yield
+        return
+    base = dir / "history" / stage / (key or "")
+    mtime = max((dir / f).stat().st_mtime for f in existing)
+    stamp = datetime.fromtimestamp(mtime, timezone.utc).isoformat(timespec="milliseconds")
+    snapshot = base / stamp.replace("+00:00", "Z").replace(":", "-").replace(".", "-")
+    before = {f: digest(dir / f) for f in existing}
+    # already kept (a previous run died before closing): leave it as is
+    new = not snapshot.exists()
+    if new:
+        snapshot.mkdir(parents=True)
+        for f in existing:
+            shutil.copy2(dir / f, snapshot / Path(f).name)
+    try:
+        yield
+    finally:
+        same = all((dir / f).exists() and digest(dir / f) == before[f] for f in existing)
+        if same and new:
+            shutil.rmtree(snapshot, ignore_errors=True)
+        prune(base)