@crievo/omni 0.0.0-stage → 0.1.0

package/tools/assemble.mjs

@@ -0,0 +1,942 @@
+#!/usr/bin/env node
+/* ============================================================================
+   Assembly and export with ffmpeg: the whole video, ready to upload.
+
+     node tools/assemble.mjs videos/<slug>               assembles and exports export/<slug>.mp4
+     node tools/assemble.mjs videos/<slug> --sheet       only the captions sheet over the scenes (no video)
+     --captions | --no-captions   burns the captions or not (default: burns, unless
+                                  `captions_in_motion: true` in scenes.json)
+
+   Speed (`speed` at the root of scenes.json, 1 to 1.5, set in the studio editor): after the base
+   export at 100% (export/<slug>.mp4, the one the editor shows), a second pass writes
+   export/<slug>-speed-110.mp4 and assembly.json points to it (that's what publish uploads).
+   The picture and the voice (with the effects) speed up together, voice without changing pitch;
+   the bed does not (see below). No speed: the base export is the deliverable.
+
+   Area cuts (`cuts` in scenes.json, the cut tool in the studio editor;
+   tools/cuts.mjs): the ranges leave the export at the end, with image,
+   captions and sound already assembled, and the rest is joined (10 ms sound
+   fade at each join). Voice, render and sound/ don't change: cutting a
+   silence is just assembling again. assembly.json keeps the export's cuts.
+   The bed (background music) is isolated: neither the cuts nor the speed touch it. It plays
+   straight through on the final timeline, at its own pace, ducked by the voice where the voice
+   now is (tools/sound.mjs, finalClock).
+
+   Shifted animation (`scene.video_offset`, dragged in the editor;
+   tools/soundtrack.mjs): each scene's image enters at `scene.start +
+   video_offset`, on a single track (the one that started last covers; in a
+   gap, it holds the last frame). The voice doesn't move; beat effects move
+   with the animation.
+
+   What goes in, at the times scenes.json already has:
+   - V: the scene MP4s joined, each at its `scene.start`;
+   - captions: captions.srt drawn in HTML (templates/captions.html, plus the
+     video's motion/src/_captions.css, if any), one transparent PNG per
+     caption, overlaid from its start to its end. The position (platform
+     safe area, 3×3 grid anchor, x/y; video → scene → caption) is
+     `captions` in scenes.json, the same the studio edits (tools/captions.mjs);
+   - A: each line at `scene.start + line.start`, the beat and transition
+     effects and the bed from sound.mjs (already at the level relative to the
+     voice and with ducking applied), mixed and normalized in two passes to
+     `assembly.lufs` (YouTube: −14 LUFS).
+
+   Writes export/<slug>.mp4, export/<slug>-sheet.png (one frame per scene,
+   from the MP4 itself) and export/assembly.json. Refuses to start if
+   anything is missing: scene MP4 with wrong duration, line without audio or
+   position, missing captions.srt, effect that doesn't exist. Premiere is
+   optional (premiere.mjs assemble, to edit by hand).
+
+   Waits for its turn in the machine queue (tools/job-queue.mjs).
+   ============================================================================ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, readdirSync, statSync, utimesSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+import { loadVideo } from "./timing.mjs";
+import { prepareSound, planSound, finalClock, sanitizeSpeed, mixGraph, lineInputs } from "./sound.mjs";
+import { turn } from "./job-queue.mjs";
+import { isNarrated } from "./lib/narration.mjs";
+import { keepPrevious } from "./history.mjs";
+import { captionsOf, captionsHtml } from "./captions.mjs";
+import { normalizeCuts, keptSegments, removedDuration, toEdited } from "./cuts.mjs";
+import {
+  videoTrack,
+  videoEdited,
+  voiceEdited,
+  animationStart,
+  videoClips,
+  lineClips,
+  voiceSpans,
+} from "./soundtrack.mjs";
+import { CODE_ROOT, DATA_ROOT as ROOT } from "./lib/paths.mjs";
+
+const CFG = JSON.parse(readFileSync(join(ROOT, "omnivideo.config.json"), "utf8"));
+const A = { lufs: -14, peak_db: -1, lra: 11, crf: 17, audio_kbps: 320, ...(CFG.assembly ?? {}) };
+const RATE = 48000;
+
+const args = process.argv.slice(2);
+const has = n => args.includes(`--${n}`);
+const dir = resolve(args[0] ?? "");
+/* "Sem narração e voz": no voice, no captions, and the sound is not leveled (only effects and the bed) */
+const SILENT = !isNarrated(dir);
+function fail(msg) {
+  console.error(`erro: ${msg}`);
+  process.exit(1);
+}
+if (!args[0] || !existsSync(join(dir, "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);
+}
+function run(bin, a, label = bin) {
+  const r = spawnSync(bin, a, { encoding: "utf8", maxBuffer: 1 << 26 });
+  if (r.status !== 0) fail(`${label}: ${(r.stderr || r.stdout).slice(-800)}`);
+  return r;
+}
+
+function duration(file) {
+  const r = spawnSync("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", file], {
+    encoding: "utf8",
+  });
+  return r.status === 0 ? +r.stdout.trim() : null;
+}
+
+/* before the editor owned the speed, the export panel kept it in assembly.json: a video that
+   never chose one in the editor (no `speed` in scenes.json) keeps that one */
+function legacySpeed() {
+  try {
+    return JSON.parse(readFileSync(join(dir, "export", "assembly.json"), "utf8")).speed;
+  } catch {
+    return undefined;
+  }
+}
+
+/* --- what must exist first ------------------------------------------------ */
+function check(video, withCaptions) {
+  const { fps } = video.format;
+  const problems = [];
+  for (const scene of video.scenes) {
+    const mp4 = join(dir, scene.mp4 ?? `motion/${scene.id}.mp4`);
+    if (scene.duration == null) problems.push(`${scene.id}: sem duração — rode omnivideo.py timing`);
+    else if (!existsSync(mp4))
+      problems.push(`${scene.id}: ${scene.mp4} não existe — renderize (build-motion.mjs --render)`);
+    else {
+      const d = duration(mp4);
+      if (d == null || Math.abs(d - scene.duration) > 1.5 / fps)
+        problems.push(
+          `${scene.id}: ${scene.mp4} tem ${d?.toFixed(3)}s, a cena pede ${scene.duration}s — renderize de novo`,
+        );
+      const reg = join(dir, "motion", `${scene.id}.render.json`);
+      const r = existsSync(reg) ? JSON.parse(readFileSync(reg, "utf8")) : null;
+      if (r?.video_time && Math.abs(r.start - scene.start) > 1e-3) {
+        problems.push(
+          `${scene.id}: renderizada começando em ${r.start}s, agora começa em ${scene.start}s; o fundo anda no tempo do vídeo e pularia no corte — renderize de novo`,
+        );
+      }
+    }
+    for (const line of scene.lines ?? []) {
+      if (!line.wav || !existsSync(join(dir, line.wav)))
+        problems.push(`${line.id}: sem áudio — rode omnivideo.py voice`);
+      if (line.start == null) problems.push(`${line.id}: sem posição — rode omnivideo.py timing`);
+    }
+  }
+  if (!SILENT && !existsSync(join(dir, "captions.srt")))
+    problems.push("captions.srt não existe — rode omnivideo.py captions");
+  if (withCaptions && !existsSync(join(CODE_ROOT, "templates", "captions.html")))
+    problems.push("templates/captions.html não existe");
+  if (problems.length) fail("a montagem não pode começar:\n  " + problems.join("\n  "));
+}
+
+/* --- captions --------------------------------------------------------------------- */
+/* captions.html (tools/captions.mjs: data, position and the video's _captions.css); one
+   transparent PNG per caption */
+function captionFrames(video, captions) {
+  const { w, h } = video.format;
+  const capDir = join(dir, "captions");
+  rmSync(join(capDir, "frames"), { recursive: true, force: true });
+  mkdirSync(capDir, { recursive: true });
+  const { html, pos, css } = captionsHtml(dir, video, captions);
+  const file = join(capDir, "captions.html");
+  writeFileSync(file, html);
+  const mids = captions.map(c => +((c.s + c.e) / 2).toFixed(4));
+  run(
+    "node",
+    [
+      join(CODE_ROOT, "tools", "render.mjs"),
+      file,
+      "--frames",
+      join(capDir, "frames"),
+      "--at",
+      mids.join(","),
+      "--w",
+      String(w),
+      "--h",
+      String(h),
+      "--alpha",
+    ],
+    "render da legenda",
+  );
+  const pngs = readdirSync(join(capDir, "frames"))
+    .filter(f => f.endsWith(".png"))
+    .sort()
+    .map(f => join(capDir, "frames", f));
+  if (pngs.length !== captions.length) fail(`a legenda rendeu ${pngs.length} quadros para ${captions.length} legendas`);
+  return { pngs, style: pos.style, platform: pos.platform, anchor: pos.anchor, css };
+}
+
+/* caption track as a slideshow: a transparent PNG in the gaps, each caption
+   from the frame where it starts to the frame where it ends (on the fps grid) */
+function captionTrack(captions, pngs, total, fps, w, h, tmp) {
+  const empty = join(tmp, "empty.png");
+  run("ffmpeg", [
+    "-y",
+    "-loglevel",
+    "error",
+    "-f",
+    "lavfi",
+    "-i",
+    `color=c=black@0:s=${w}x${h},format=rgba`,
+    "-frames:v",
+    "1",
+    empty,
+  ]);
+  const end = Math.round(total * fps);
+  const rows = ["ffconcat version 1.0"];
+  const add = (file, frames) => {
+    if (frames > 0) rows.push(`file '${file}'`, `duration ${(frames / fps).toFixed(6)}`);
+  };
+  let cursor = 0;
+  captions.forEach((c, i) => {
+    const a = Math.max(cursor, Math.round(c.s * fps));
+    const b = Math.min(end, Math.round(c.e * fps));
+    if (b <= a) return;
+    add(empty, a - cursor);
+    add(pngs[i], b - a);
+    cursor = b;
+  });
+  add(empty, end - cursor);
+  /* concat ignores the last entry's duration: repeat the file */
+  rows.push(`file '${rows.at(-2).slice(6, -1)}'`);
+  const list = join(tmp, "captions.ffconcat");
+  writeFileSync(list, rows.join("\n") + "\n");
+  return list;
+}
+
+/* --- audio ------------------------------------------------------------------------ */
+const PCM = ["-c:a", "pcm_s16le"];
+
+/* voice and effects in scenes.json time, without the bed and without leveling: it is what the
+   cuts and the speed act on (the bed is isolated, see exportAudio) */
+function premix(video, sound, total, tmp) {
+  const inputs = [];
+  for (const scene of video.scenes)
+    for (const l of scene.lines ?? []) inputs.push(...lineInputs(scene, l, join(dir, l.wav)));
+  for (const it of sound.items) inputs.push({ file: it.file, t: it.start });
+  const mixed = join(tmp, "premix.wav");
+  if (!inputs.length) {
+    run("ffmpeg", [
+      "-y",
+      "-loglevel",
+      "error",
+      "-f",
+      "lavfi",
+      "-i",
+      `anullsrc=r=${RATE}:cl=stereo`,
+      "-t",
+      String(total),
+      ...PCM,
+      mixed,
+    ]);
+    return mixed;
+  }
+  run(
+    "ffmpeg",
+    [
+      "-y",
+      "-loglevel",
+      "error",
+      ...inputs.flatMap(e => ["-i", e.file]),
+      "-filter_complex",
+      mixGraph(inputs, total),
+      "-t",
+      String(total),
+      "-ar",
+      String(RATE),
+      ...PCM,
+      mixed,
+    ],
+    "mixagem",
+  );
+  return mixed;
+}
+
+/* The export's sound: the premix with the cuts closed and the speed applied (atempo, no pitch
+   change), then the bed on top (already made for this speed by sound.mjs: it enters at its own
+   second of the final timeline, whole, never cut or sped up), then loudnorm. `tag` names the files. */
+function exportAudio(premixFile, bed, { cuts, total, speed, finalDur, tmp, tag }) {
+  let edited = premixFile;
+  if (cuts.length || speed !== 1) {
+    edited = join(tmp, `edited-${tag}.wav`);
+    const g =
+      (cuts.length ? cutsAudio("[0:a]", keptSegments(cuts, total)) : "[0:a]anull[a]") +
+      (speed !== 1 ? `;[a]atempo=${speed},aresample=${RATE}[s]` : "");
+    run(
+      "ffmpeg",
+      [
+        "-y",
+        "-loglevel",
+        "error",
+        "-i",
+        premixFile,
+        "-filter_complex",
+        g,
+        "-map",
+        speed !== 1 ? "[s]" : "[a]",
+        "-ar",
+        String(RATE),
+        ...PCM,
+        edited,
+      ],
+      "cortes e velocidade do áudio",
+    );
+  }
+  let mixed = edited;
+  if (bed) {
+    mixed = join(tmp, `mixed-${tag}.wav`);
+    const inputs = [
+      { file: edited, t: 0 },
+      { file: bed.file, t: bed.start },
+    ];
+    run(
+      "ffmpeg",
+      [
+        "-y",
+        "-loglevel",
+        "error",
+        ...inputs.flatMap(e => ["-i", e.file]),
+        "-filter_complex",
+        mixGraph(inputs, finalDur),
+        "-t",
+        String(finalDur),
+        "-ar",
+        String(RATE),
+        ...PCM,
+        mixed,
+      ],
+      "cama",
+    );
+  }
+  /* a silent video's sound is only effects: loudnorm would raise them to the platform level, as if they were
+     a voice. With a bed (music) it levels the whole, as always. */
+  if (SILENT && !bed) return { mix: mixed, measured: null };
+  return normalize(mixed, finalDur, tmp, tag);
+}
+
+/* loudnorm in two passes: the first measures, the second applies linearly (no pumping) */
+function normalize(mixed, total, tmp, tag) {
+  const target = `I=${A.lufs}:TP=${A.peak_db}:LRA=${A.lra}`;
+  const parseReport = r => JSON.parse(r.stderr.slice(r.stderr.lastIndexOf("{"), r.stderr.lastIndexOf("}") + 1));
+  const m = parseReport(
+    run(
+      "ffmpeg",
+      ["-hide_banner", "-nostats", "-i", mixed, "-af", `loudnorm=${target}:print_format=json`, "-f", "null", "-"],
+      "loudnorm (medir)",
+    ),
+  );
+  if (!Number.isFinite(+m.input_i)) return { mix: mixed, measured: null };
+  const norm = join(tmp, `audio-${tag}.wav`);
+  /* linear when possible; if the gain would clip the peak, loudnorm itself falls back to dynamic and says so in the report */
+  const n = parseReport(
+    run(
+      "ffmpeg",
+      [
+        "-y",
+        "-hide_banner",
+        "-nostats",
+        "-i",
+        mixed,
+        "-af",
+        `loudnorm=${target}:measured_I=${m.input_i}:measured_TP=${m.input_tp}:measured_LRA=${m.input_lra}:measured_thresh=${m.input_thresh}:offset=${m.target_offset}:linear=true:print_format=json,aresample=${RATE}`,
+        "-t",
+        String(total),
+        ...PCM,
+        norm,
+      ],
+      "loudnorm (aplicar)",
+    ),
+  );
+  return {
+    mix: norm,
+    measured: {
+      before_lufs: +m.input_i,
+      before_peak_db: +m.input_tp,
+      after_lufs: +n.output_i,
+      after_peak_db: +n.output_tp,
+      lra: +n.output_lra,
+      mode: n.normalization_type,
+    },
+  };
+}
+
+/* --- sheet: one frame per scene, at a moment with a caption when there is one ------------- */
+function moments(video, captions) {
+  const { fps } = video.format;
+  const last = Math.round(video.total_duration * fps) - 1;
+  return video.scenes.map(sc => {
+    const c = captions.find(x => x.e > sc.start + 0.1 && x.s < sc.start + sc.duration - 0.1);
+    const t = c ? (Math.max(c.s, sc.start) + Math.min(c.e, sc.start + sc.duration)) / 2 : sc.start + sc.duration / 2;
+    return { scene: sc, t: Math.min(Math.floor(t * fps + 1e-6), last) / fps, caption: c ? captions.indexOf(c) : -1 };
+  });
+}
+
+function sheet(frames, out) {
+  const cols = Math.min(3, frames.length),
+    rows = Math.ceil(frames.length / cols);
+  const framesDir = dirname(frames[0]);
+  run(
+    "ffmpeg",
+    [
+      "-y",
+      "-loglevel",
+      "error",
+      "-framerate",
+      "1",
+      "-i",
+      join(framesDir, "f%03d.png"),
+      "-vf",
+      `scale=540:-1,tile=${cols}x${rows}:padding=8:margin=8:color=white`,
+      "-frames:v",
+      "1",
+      out,
+    ],
+    "folha",
+  );
+}
+
+/* --- cuts: the kept ranges, joined -------------------------------------
+   trim/atrim of each range and concat. The picture and the sound (the premix: voice and
+   effects, never the bed) are cut apart; the sound gets a short fade at each join so the cut
+   doesn't click. Each returns a graph ending in [v] / [a]. */
+const CUT_FADE = 0.01;
+function cutsVideo(vIn, segs) {
+  const n = segs.length;
+  const g = [`${vIn}split=${n}${segs.map((_, i) => `[vs${i}]`).join("")}`];
+  segs.forEach(([a, b], i) =>
+    g.push(`[vs${i}]trim=start=${a.toFixed(4)}:end=${b.toFixed(4)},setpts=PTS-STARTPTS[v${i}]`),
+  );
+  g.push(`${segs.map((_, i) => `[v${i}]`).join("")}concat=n=${n}:v=1:a=0[v]`);
+  return g.join(";");
+}
+function cutsAudio(aIn, segs) {
+  const n = segs.length;
+  const g = [`${aIn}asplit=${n}${segs.map((_, i) => `[as${i}]`).join("")}`];
+  segs.forEach(([a, b], i) => {
+    const d = b - a,
+      f = Math.min(CUT_FADE, d / 3);
+    const fades = [
+      i > 0 ? `afade=t=in:d=${f.toFixed(4)}` : "",
+      i < n - 1 ? `afade=t=out:st=${(d - f).toFixed(4)}:d=${f.toFixed(4)}` : "",
+    ].filter(Boolean);
+    g.push(
+      `[as${i}]atrim=start=${a.toFixed(4)}:end=${b.toFixed(4)},asetpts=PTS-STARTPTS${fades.length ? `,${fades.join(",")}` : ""}[a${i}]`,
+    );
+  });
+  g.push(`${segs.map((_, i) => `[a${i}]`).join("")}concat=n=${n}:v=0:a=1[a]`);
+  return g.join(";");
+}
+
+/* --- speed: a second pass over the base export ----------------------------------------
+   The picture (captions burned in) comes from the base export: setpts speeds up the frames and
+   fps brings them back to the video rate (drops frames). The sound is not the base's: it is
+   built again for this speed (exportAudio: voice and effects through atempo, the isolated bed
+   on top), so the bed keeps its tempo. */
+const COLOR = "setparams=color_primaries=bt709:color_trc=bt709:colorspace=bt709:range=tv";
+
+const pct = v => Math.round(v * 100);
+
+/* assembly.json with the speed applied: writes export/<slug>-speed-<pct>.mp4 from the base and
+   removes versions at other speeds; 1 keeps the base as the deliverable. `audioFile`: the
+   sound built for `v` */
+function withSpeed(m, v, audioFile) {
+  const baseRel = m.base_mp4 ?? m.mp4;
+  const baseDuration = m.base_duration ?? m.duration;
+  const exp = join(dir, "export");
+  const slug = baseRel
+    .split("/")
+    .pop()
+    .replace(/\.mp4$/, "");
+  const prefix = `${slug}-speed-`;
+  let rel = null,
+    d = null;
+  if (v !== 1) {
+    rel = `export/${prefix}${pct(v)}.mp4`;
+    const out = join(dir, rel);
+    run(
+      "ffmpeg",
+      [
+        "-y",
+        "-loglevel",
+        "error",
+        "-i",
+        join(dir, baseRel),
+        "-i",
+        audioFile,
+        "-filter_complex",
+        `[0:v]setpts=PTS/${v},fps=${m.fps},format=yuv420p,${COLOR}[v]`,
+        "-map",
+        "[v]",
+        "-map",
+        "1:a",
+        "-c:a",
+        "aac",
+        "-b:a",
+        `${A.audio_kbps}k`,
+        "-ar",
+        String(RATE),
+        "-c:v",
+        "libx264",
+        "-crf",
+        String(A.crf),
+        "-preset",
+        "slow",
+        "-t",
+        String(baseDuration / v),
+        "-movflags",
+        "+faststart",
+        out,
+      ],
+      "acelerar",
+    );
+    d = duration(out);
+  }
+  for (const n of readdirSync(exp)) {
+    if (n.startsWith(prefix) && n.endsWith(".mp4") && `export/${n}` !== rel) rmSync(join(exp, n));
+  }
+  const { base_mp4, base_duration, speed, speed_at, ...rest } = m;
+  if (v === 1) return { ...rest, mp4: baseRel, duration: baseDuration };
+  const warnings = [...(rest.warnings ?? [])];
+  const expected = baseDuration / v;
+  if (d == null || Math.abs(d - expected) > 2 / m.fps)
+    warnings.push(`o MP4 a ${pct(v)}% tem ${d?.toFixed(3)}s, devia ter ${expected.toFixed(3)}s`);
+  return {
+    ...rest,
+    mp4: rel,
+    duration: d,
+    base_mp4: baseRel,
+    base_duration: baseDuration,
+    speed: v,
+    speed_at: new Date().toISOString(),
+    warnings,
+  };
+}
+
+/* `keepMtime`: the file time stays the assembly's, which is what status
+   compares scenes, voice and captions against to say the export is outdated */
+function writeAssembly(file, m, keepMtime) {
+  const st = keepMtime && existsSync(file) ? statSync(file) : null;
+  writeFileSync(file, JSON.stringify(m, null, 2) + "\n");
+  if (st) utimesSync(file, st.atime, st.mtime);
+}
+
+/* ============================================================================ */
+const only = { sheet: has("sheet") };
+let video = loadVideo(dir);
+const decideCaptions = v => (SILENT || has("no-captions") ? false : has("captions") ? true : !v.captions_in_motion);
+check(video, decideCaptions(video));
+await turn("assembly", dir);
+video = loadVideo(dir);
+const withCaptions = decideCaptions(video);
+check(video, withCaptions);
+
+const { w, h, fps } = video.format;
+const total = video.total_duration;
+const cuts = normalizeCuts(video.cuts, total, fps);
+const finalTotal = total - removedDuration(cuts);
+/* the editor's speed (scenes.json `speed`, 1 to 1.5): a second pass after the base export */
+const speed = sanitizeSpeed(video.speed ?? legacySpeed());
+if (finalTotal < 1 / fps)
+  fail("os cortes tiram o vídeo inteiro: desfaça algum no editor do studio (ou em `cuts` no scenes.json)");
+const allCaptions = captionsOf(dir, video);
+/* `captions.individual.<id>.hidden`: turned off in the UI. With the voice in clips (editor), each caption
+   moves with the voice piece it falls in (the largest, if it spans a blade cut); in a deleted piece,
+   it's dropped */
+const captions = allCaptions
+  .filter(c => !c.hidden)
+  .flatMap(c => {
+    if (!voiceEdited(video.scenes) || !c.line) return [c];
+    const scene = video.scenes.find(sc => (sc.lines ?? []).some(l => l.id === c.line));
+    const line = scene?.lines.find(x => x.id === c.line);
+    if (!line) return [c];
+    const base = scene.start + line.start;
+    const pieces = voiceSpans(scene, line, c.s - base, c.e - base);
+    if (!pieces.length) return [];
+    const [s, e] = pieces.reduce((m, p) => (p[1] - p[0] > m[1] - m[0] ? p : m));
+    return [{ ...c, s: +s.toFixed(3), e: +e.toFixed(3) }];
+  })
+  .sort((a, b) => a.s - b.s);
+if (captions.length < allCaptions.length)
+  console.log(`legenda: ${allCaptions.length - captions.length} desligada(s) não entra(m) no vídeo`);
+const tmp = join(tmpdir(), `assemble-${process.pid}`);
+mkdirSync(tmp, { recursive: true });
+const exp = join(dir, "export");
+mkdirSync(exp, { recursive: true });
+const slug = video.slug ?? dir.split("/").pop();
+
+const cap = withCaptions ? captionFrames(video, captions) : null;
+const marks = moments(video, captions);
+
+/* --- sheet only: captions over each scene's frame, without assembling the video -------------- */
+if (only.sheet) {
+  if (!cap)
+    fail("--sheet mostra a legenda queimada; este vídeo não queima legenda (use --captions para ver mesmo assim)");
+  const frames = marks.map((m, i) => {
+    const png = join(tmp, `f${String(i).padStart(3, "0")}.png`);
+    const sceneMp4 = join(dir, m.scene.mp4 ?? `motion/${m.scene.id}.mp4`);
+    const local = Math.min(m.scene.duration - 1 / fps, Math.max(0, m.t - (animationStart(m.scene) ?? m.scene.start)));
+    const ins = ["-ss", local.toFixed(4), "-i", sceneMp4, ...(m.caption >= 0 ? ["-i", cap.pngs[m.caption]] : [])];
+    run(
+      "ffmpeg",
+      [
+        "-y",
+        "-loglevel",
+        "error",
+        ...ins,
+        ...(m.caption >= 0 ? ["-filter_complex", "[0:v][1:v]overlay=0:0"] : []),
+        "-frames:v",
+        "1",
+        png,
+      ],
+      "quadro",
+    );
+    return png;
+  });
+  const out = join(exp, `${slug}-captions-sheet.png`);
+  sheet(frames, out);
+  rmSync(tmp, { recursive: true, force: true });
+  console.log(
+    `folha da legenda (${cap.style}, safe area ${cap.platform}, ${cap.anchor}${cap.css ? ", + _captions.css" : ""}, ${captions.length} legendas): ${out}`,
+  );
+  console.log(`quadros: ${marks.map(m => `${m.scene.id} ${m.t.toFixed(2)}s`).join(" · ")}`);
+  console.log(`a camada inteira abre no navegador: ${join(dir, "captions", "captions.html")}?t=<segundos>`);
+  process.exit(0);
+}
+
+const previous = keepPrevious(dir, "assembly", null, [
+  `export/${slug}.mp4`,
+  `export/${slug}-sheet.png`,
+  "export/assembly.json",
+]);
+
+/* --- V: scenes joined ----------------------------------------------------------- */
+const motion = join(tmp, "motion.mp4");
+const sceneMp4 = sc => join(dir, sc.mp4 ?? `motion/${sc.id}.mp4`);
+if (!videoEdited(video.scenes)) {
+  writeFileSync(join(tmp, "scenes.txt"), video.scenes.map(sc => `file '${sceneMp4(sc)}'`).join("\n") + "\n");
+  run(
+    "ffmpeg",
+    ["-y", "-loglevel", "error", "-f", "concat", "-safe", "0", "-i", join(tmp, "scenes.txt"), "-c", "copy", motion],
+    "emendar cenas",
+  );
+} else {
+  /* shifted animation: each track segment is a piece of a scene, running or frozen on a frame */
+  const segs = videoTrack(video.scenes, total, fps);
+  const uses = video.scenes.map((_, i) => segs.filter(sg => sg.i === i).length);
+  const g = [];
+  const labels = video.scenes.map((_, i) => {
+    if (!uses[i]) return [];
+    if (uses[i] === 1) return [`[${i}:v]`];
+    g.push(`[${i}:v]split=${uses[i]}${Array.from({ length: uses[i] }, (_, k) => `[c${i}_${k}]`).join("")}`);
+    return Array.from({ length: uses[i] }, (_, k) => `[c${i}_${k}]`);
+  });
+  segs.forEach((sg, k) => {
+    const input = labels[sg.i].shift();
+    g.push(
+      sg.frozen
+        ? `${input}trim=start_frame=${sg.since}:end_frame=${sg.since + 1},setpts=PTS-STARTPTS,tpad=stop=${sg.frames - 1}:stop_mode=clone[t${k}]`
+        : sg.speed === 1
+          ? `${input}trim=start_frame=${sg.since}:end_frame=${sg.since + sg.frames},setpts=PTS-STARTPTS[t${k}]`
+          : /* a sped piece: frames × speed frames of the MP4 squeezed into `frames` (fps evens them out) */
+            `${input}trim=start_frame=${sg.since}:end_frame=${sg.since + Math.max(1, Math.round(sg.frames * sg.speed))},setpts=(PTS-STARTPTS)/${sg.speed},fps=${fps},tpad=stop=${sg.frames}:stop_mode=clone,trim=end_frame=${sg.frames},setpts=PTS-STARTPTS[t${k}]`,
+    );
+  });
+  g.push(
+    `${segs.map((_, k) => `[t${k}]`).join("")}concat=n=${segs.length}:v=1:a=0,fps=${fps},format=yuv420p,${COLOR}[v]`,
+  );
+  const used = video.scenes.map((sc, i) => (uses[i] ? sceneMp4(sc) : null));
+  /* a fully covered scene doesn't go in; the input index stays the scene's */
+  run(
+    "ffmpeg",
+    [
+      "-y",
+      "-loglevel",
+      "error",
+      ...used.flatMap(a => ["-i", a ?? sceneMp4(video.scenes[0])]),
+      "-filter_complex",
+      g.join(";"),
+      "-map",
+      "[v]",
+      "-c:v",
+      "libx264",
+      "-crf",
+      "12",
+      "-preset",
+      "fast",
+      "-t",
+      String(total),
+      motion,
+    ],
+    "trilha de animação",
+  );
+  console.log(
+    `animação nos clips do editor: ${video.scenes
+      .map(
+        sc =>
+          `${sc.id} ${
+            videoClips(sc)
+              .map(
+                cl =>
+                  `${cl.from.toFixed(2)}–${cl.to.toFixed(2)}${cl.offset ? ` ${cl.offset > 0 ? "+" : ""}${cl.offset.toFixed(2)}s` : ""}${cl.speed ? ` ${Math.round(cl.speed * 100)}%` : ""}`,
+              )
+              .join(", ") || "apagada"
+          }`,
+      )
+      .join(" · ")}`,
+  );
+}
+
+/* --- A: lines and effects ----------------------------------------------------------- */
+let sound;
+try {
+  /* the base export is at 100%: the bed is made for that (the speed pass makes its own) */
+  sound = prepareSound(dir, { preview: false, log: () => {}, speed: 1 });
+} catch (e) {
+  fail(e.message);
+}
+const premixFile = premix(video, sound, total, tmp);
+const { mix: mixFile, measured } = exportAudio(premixFile, sound.bed, {
+  cuts,
+  total,
+  speed: 1,
+  finalDur: finalTotal,
+  tmp,
+  tag: "base",
+});
+
+/* --- final ------------------------------------------------------------------------ */
+const mp4 = join(exp, `${slug}.mp4`);
+const audioOut = ["-c:a", "aac", "-b:a", `${A.audio_kbps}k`, "-ar", String(RATE)];
+if (cap) {
+  const list = captionTrack(captions, cap.pngs, total, fps, w, h, tmp);
+  /* captions enter as yuva with the scenes' bt709 matrix: without it ffmpeg converts
+     in bt601 and the pill's white drifts to another tone */
+  const graph =
+    `[1:v]fps=${fps},scale=out_color_matrix=bt709:out_range=tv,format=yuva420p[cap];` +
+    `[0:v][cap]overlay=0:0:eof_action=pass:format=yuv420,format=yuv420p,${COLOR}${cuts.length ? "[vb];" + cutsVideo("[vb]", keptSegments(cuts, total)) : "[v]"}`;
+  run(
+    "ffmpeg",
+    [
+      "-y",
+      "-loglevel",
+      "error",
+      "-i",
+      motion,
+      "-f",
+      "concat",
+      "-safe",
+      "0",
+      "-i",
+      list,
+      "-i",
+      mixFile,
+      "-filter_complex",
+      graph,
+      "-map",
+      "[v]",
+      "-map",
+      "2:a",
+      "-c:v",
+      "libx264",
+      "-crf",
+      String(A.crf),
+      "-preset",
+      "slow",
+      ...audioOut,
+      "-t",
+      String(finalTotal),
+      "-movflags",
+      "+faststart",
+      mp4,
+    ],
+    "exportar",
+  );
+} else if (cuts.length) {
+  const graph = `[0:v]format=yuv420p,${COLOR}[vb];` + cutsVideo("[vb]", keptSegments(cuts, total));
+  run(
+    "ffmpeg",
+    [
+      "-y",
+      "-loglevel",
+      "error",
+      "-i",
+      motion,
+      "-i",
+      mixFile,
+      "-filter_complex",
+      graph,
+      "-map",
+      "[v]",
+      "-map",
+      "1:a",
+      "-c:v",
+      "libx264",
+      "-crf",
+      String(A.crf),
+      "-preset",
+      "slow",
+      ...audioOut,
+      "-t",
+      String(finalTotal),
+      "-movflags",
+      "+faststart",
+      mp4,
+    ],
+    "exportar",
+  );
+} else {
+  run(
+    "ffmpeg",
+    [
+      "-y",
+      "-loglevel",
+      "error",
+      "-i",
+      motion,
+      "-i",
+      mixFile,
+      "-map",
+      "0:v",
+      "-map",
+      "1:a",
+      "-c:v",
+      "copy",
+      ...audioOut,
+      "-t",
+      String(total),
+      "-movflags",
+      "+faststart",
+      mp4,
+    ],
+    "exportar",
+  );
+}
+
+/* --- check ------------------------------------------------------------------ */
+const d = duration(mp4);
+const warnings = [...sound.warnings.map(a => `efeito: ${a}`)];
+if (d == null || Math.abs(d - finalTotal) > 1.5 / fps)
+  warnings.push(
+    `o MP4 tem ${d?.toFixed(3)}s, o vídeo pede ${finalTotal.toFixed(3)}s${cuts.length ? ` (${total.toFixed(3)}s menos os cortes)` : ""}`,
+  );
+/* with cuts, each scene's frame moves to export time (inside a cut, the cut point) */
+const lastFrame = (Math.round(finalTotal * fps) - 1) / fps;
+marks.forEach(m => {
+  if (cuts.length) m.t = Math.min(lastFrame, Math.round(toEdited(m.t, cuts) * fps) / fps);
+});
+const frames = marks.map((m, i) => {
+  const png = join(tmp, `f${String(i).padStart(3, "0")}.png`);
+  run("ffmpeg", ["-y", "-loglevel", "error", "-ss", m.t.toFixed(4), "-i", mp4, "-frames:v", "1", png], "quadro");
+  return png;
+});
+const sheetFile = join(exp, `${slug}-sheet.png`);
+sheet(frames, sheetFile);
+
+const lineCount = video.scenes.reduce((n, sc) => n + (sc.lines?.length ?? 0), 0);
+let assembly = {
+  mp4: `export/${slug}.mp4`,
+  sheet: `export/${slug}-sheet.png`,
+  duration: d,
+  w,
+  h,
+  fps,
+  scenes: video.scenes.length,
+  lines: lineCount,
+  effects: sound.items.length,
+  bed: sound.bed?.name ?? null,
+  captions: cap
+    ? {
+        burned: true,
+        style: cap.style,
+        platform: cap.platform,
+        anchor: cap.anchor,
+        video_css: cap.css,
+        count: captions.length,
+      }
+    : {
+        burned: false,
+        reason: SILENT ? "no_narration" : video.captions_in_motion ? "captions_in_motion" : "--no-captions",
+      },
+  audio: {
+    target_lufs: A.lufs,
+    peak_db: A.peak_db,
+    ...(measured ?? { no_sound: !sound.items.length && !sound.bed, ...(SILENT ? { silent: true } : {}) }),
+  },
+  sheet_frames: marks.map(m => ({ scene: m.scene.id, t: m.t })),
+  ...(cuts.length ? { cuts, uncut_duration: total, removed_s: +removedDuration(cuts).toFixed(4) } : {}),
+  ...(videoEdited(video.scenes)
+    ? { scene_clips: Object.fromEntries(video.scenes.map(sc => [sc.id, videoClips(sc)])) }
+    : {}),
+  ...(voiceEdited(video.scenes)
+    ? { line_clips: Object.fromEntries(video.scenes.flatMap(sc => (sc.lines ?? []).map(l => [l.id, lineClips(l)]))) }
+    : {}),
+  warnings,
+  assembled_at: new Date().toISOString(),
+};
+/* the speed pass: the sheet stays the base's (the same frames, just earlier). The sound is built
+   again for this speed, with the bed made for it (only the bed: no scene's effects) */
+let spedAudio = null;
+if (speed !== 1) {
+  const bedAtSpeed = planSound(dir, video, {
+    outDir: join(tmp, "sound-speed"),
+    scenes: new Set(),
+    clock: finalClock(video, speed),
+  }).bed;
+  spedAudio = exportAudio(premixFile, bedAtSpeed, {
+    cuts,
+    total,
+    speed,
+    finalDur: finalTotal / speed,
+    tmp,
+    tag: "speed",
+  }).mix;
+}
+assembly = withSpeed(assembly, speed, spedAudio);
+writeAssembly(join(exp, "assembly.json"), assembly, false);
+previous.close();
+rmSync(tmp, { recursive: true, force: true });
+
+console.log(`exportado: ${mp4} (${d?.toFixed(2)}s, ${w}×${h} @ ${fps})`);
+if (cuts.length)
+  console.log(
+    `cortes: ${cuts.length} trecho(s), ${removedDuration(cuts).toFixed(2)}s fora (${total.toFixed(2)}s → ${finalTotal.toFixed(2)}s): ${cuts.map(c => `${c.from.toFixed(2)}–${c.to.toFixed(2)}`).join(" · ")}`,
+  );
+if (speed !== 1)
+  console.log(`velocidade ${pct(speed)}% reaplicada: ${join(dir, assembly.mp4)} (${assembly.duration?.toFixed(2)}s)`);
+console.log(
+  `V: ${video.scenes.length} cenas · A: ${lineCount} falas + ${sound.items.length} efeitos${sound.bed ? " + cama" : ""} · ` +
+    `legenda ${cap ? `queimada (${cap.style}, ${cap.platform}, ${cap.anchor}, ${captions.length})` : video.captions_in_motion ? "no motion" : "não queimada"}`,
+);
+if (measured)
+  console.log(
+    `áudio: ${measured.before_lufs} → ${measured.after_lufs} LUFS (alvo ${A.lufs}), pico ${measured.after_peak_db} dBTP, ${measured.mode}`,
+  );
+console.log(`folha: ${sheetFile} (${marks.map(m => `${m.scene.id} ${m.t.toFixed(2)}s`).join(" · ")})`);
+assembly.warnings.forEach(a => console.log(`⚠ ${a}`));