@docyrus/animaguru 0.13.0 → 0.15.0

package/templates/video/scripts/audio-tools.mjs

@@ -0,0 +1,241 @@
+/** Shared helpers for audio:vo, audio:music and audio:mix: the bundled ffmpeg, PCM decoding and small DSP routines. */
+import { execFile, spawn } from "node:child_process";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+let binaries;
+
+/** The ffmpeg/ffprobe builds installed with the workspace; loaded lazily so the pure helpers import anywhere. */
+export async function audioBinaries() {
+  if (!binaries) {
+    const [{ default: ffmpeg }, { default: ffprobe }] = await Promise.all([import("@ffmpeg-installer/ffmpeg"), import("@ffprobe-installer/ffprobe")]);
+    binaries = { ffmpeg: ffmpeg.path, ffprobe: ffprobe.path };
+  }
+  return binaries;
+}
+
+export async function ffmpeg(args) {
+  const { ffmpeg: binary } = await audioBinaries();
+  try { return await run(binary, ["-hide_banner", "-nostdin", ...args], { maxBuffer: 64 * 1024 * 1024 }); }
+  catch (error) { throw new Error(`ffmpeg failed: ${String(error.stderr ?? error.message).trim().split("\n").slice(-3).join(" ")}`); }
+}
+
+export async function mediaDuration(file) {
+  const { ffprobe } = await audioBinaries();
+  const { stdout } = await run(ffprobe, ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", file]);
+  const duration = Number(stdout);
+  if (!Number.isFinite(duration)) throw new Error(`Could not read the duration of ${file}.`);
+  return duration;
+}
+
+/** Decodes any audio file to mono Float32 samples at the given rate. */
+export async function decodePcm(file, sampleRate = 22050) {
+  const { ffmpeg: binary } = await audioBinaries();
+  return new Promise((resolve, reject) => {
+    const child = spawn(binary, ["-v", "error", "-nostdin", "-i", file, "-ac", "1", "-ar", String(sampleRate), "-f", "f32le", "pipe:1"], { stdio: ["ignore", "pipe", "pipe"] });
+    const chunks = []; let errors = "";
+    child.stdout.on("data", (chunk) => chunks.push(chunk));
+    child.stderr.on("data", (chunk) => { errors += chunk; });
+    child.once("error", reject);
+    child.once("close", (code) => {
+      if (code !== 0) { reject(new Error(`Could not decode ${file}: ${errors.trim().split("\n").at(-1) ?? `exit ${code}`}`)); return; }
+      const bytes = Buffer.concat(chunks), pcm = new Float32Array(Math.floor(bytes.length / 4));
+      new Uint8Array(pcm.buffer).set(bytes.subarray(0, pcm.length * 4));
+      resolve(pcm);
+    });
+  });
+}
+
+/** EBU R128 measurement with ffmpeg's loudnorm; returns the measured values its second pass needs. */
+export async function measureLoudness(file, { i = -14, tp = -2, lra = 9, filter = "" } = {}) {
+  const { stderr } = await ffmpeg(["-nostats", "-i", file, "-af", `${filter ? `${filter},` : ""}loudnorm=I=${i}:TP=${tp}:LRA=${lra}:print_format=json`, "-f", "null", "-"]);
+  const json = stderr.match(/\{\s*"input_i"[\s\S]*?\}/)?.[0];
+  if (!json) throw new Error(`Loudness could not be measured for ${file}.`);
+  const values = JSON.parse(json);
+  return { integrated: Number(values.input_i), truePeak: Number(values.input_tp), range: Number(values.input_lra), threshold: Number(values.input_thresh), offset: Number(values.target_offset) };
+}
+
+export async function readJson(file, fallback) {
+  try { return JSON.parse(await readFile(file, "utf8")); }
+  catch (error) { if (error.code === "ENOENT" && fallback !== undefined) return fallback; throw error.code === "ENOENT" ? new Error(`Missing ${file}.`) : error; }
+}
+export const writeJson = (file, value) => writeFile(file, JSON.stringify(value, null, 2) + "\n");
+
+/** Resolves a path written in a config file, relative to the animation folder, and keeps it inside that folder. */
+export function projectPath(projectRoot, relative, label = "path") {
+  if (typeof relative !== "string" || !relative.trim()) throw new Error(`Set ${label} to a path relative to the animation folder.`);
+  const resolved = path.resolve(projectRoot, relative);
+  if (resolved !== projectRoot && !resolved.startsWith(projectRoot + path.sep)) throw new Error(`${label} must stay inside the animation folder: ${relative}`);
+  return resolved;
+}
+
+/** Parses `--name value` flags; booleans are flags without a value. */
+export function parseFlags(args, spec) {
+  const flags = {};
+  for (let index = 0; index < args.length; index++) {
+    const name = args[index].replace(/^--/, "");
+    if (!args[index].startsWith("--") || !(name in spec)) throw new Error(`Unknown option ${args[index]}. Options: ${Object.keys(spec).map((key) => `--${key}`).join(", ")}`);
+    if (spec[name] === "boolean") { flags[name] = true; continue; }
+    const value = args[++index];
+    if (value === undefined) throw new Error(`Pass a value after --${name}.`);
+    if (spec[name] === "number") { flags[name] = Number(value); if (!Number.isFinite(flags[name])) throw new Error(`--${name} must be a number.`); }
+    else flags[name] = value;
+  }
+  return flags;
+}
+
+export const round = (value, digits = 3) => Math.round(value * 10 ** digits) / 10 ** digits;
+export const dbToGain = (db) => 10 ** (db / 20);
+
+/** Peak level in dBFS of short windows (default 10 ms), like ffmpeg's silencedetect which compares sample peaks. */
+export function peakLevels(pcm, sampleRate, hopSeconds = 0.01) {
+  const hop = Math.max(1, Math.round(hopSeconds * sampleRate)), count = Math.ceil(pcm.length / hop);
+  const levels = new Float32Array(count);
+  for (let frame = 0; frame < count; frame++) {
+    let peak = 0;
+    for (let index = frame * hop, end = Math.min(pcm.length, index + hop); index < end; index++) { const value = Math.abs(pcm[index]); if (value > peak) peak = value; }
+    levels[frame] = peak > 0 ? 20 * Math.log10(peak) : -120;
+  }
+  return { levels, hop: hop / sampleRate };
+}
+
+/** Speech regions separated by silences of at least `minSilence` seconds below `noiseDb`, in source seconds. */
+export function detectPhrases(pcm, sampleRate, { noiseDb = -38, minSilence = 0.12, minPhrase = 0.04 } = {}) {
+  const { levels, hop } = peakLevels(pcm, sampleRate);
+  const runs = [];
+  let start = -1;
+  for (let frame = 0; frame <= levels.length; frame++) {
+    const voiced = frame < levels.length && levels[frame] >= noiseDb;
+    if (voiced && start < 0) start = frame;
+    if (!voiced && start >= 0) { runs.push({ start: start * hop, end: frame * hop }); start = -1; }
+  }
+  const merged = [];
+  for (const phrase of runs) {
+    const previous = merged.at(-1);
+    if (previous && phrase.start - previous.end < minSilence) previous.end = phrase.end;
+    else merged.push({ ...phrase });
+  }
+  const duration = pcm.length / sampleRate;
+  return merged.filter((phrase) => phrase.end - phrase.start >= minPhrase).map((phrase) => ({ start: round(phrase.start), end: round(Math.min(duration, phrase.end)) }));
+}
+
+/** In-place radix-2 FFT magnitudes of Hann-windowed frames; returns a function reused for every frame. */
+export function createSpectrum(size) {
+  const levels = Math.log2(size);
+  if (!Number.isInteger(levels)) throw new Error("FFT size must be a power of two.");
+  const half = size / 2, cos = new Float64Array(half), sin = new Float64Array(half), reverse = new Uint32Array(size);
+  for (let index = 0; index < half; index++) { cos[index] = Math.cos(2 * Math.PI * index / size); sin[index] = Math.sin(2 * Math.PI * index / size); }
+  for (let index = 0; index < size; index++) { let value = 0; for (let bit = 0; bit < levels; bit++) value = (value << 1) | ((index >>> bit) & 1); reverse[index] = value; }
+  const window = Float64Array.from({ length: size }, (_, index) => 0.5 - 0.5 * Math.cos(2 * Math.PI * index / size));
+  const re = new Float64Array(size), im = new Float64Array(size), magnitudes = new Float64Array(half + 1);
+  return (samples, offset = 0) => {
+    for (let index = 0; index < size; index++) { const position = offset + index; re[reverse[index]] = (position >= 0 && position < samples.length ? samples[position] : 0) * window[index]; im[reverse[index]] = 0; }
+    for (let span = 2; span <= size; span <<= 1) {
+      const step = size / span, middle = span >> 1;
+      for (let base = 0; base < size; base += span) {
+        for (let offsetIndex = 0; offsetIndex < middle; offsetIndex++) {
+          const twiddle = offsetIndex * step, a = base + offsetIndex, b = a + middle;
+          const tr = re[b] * cos[twiddle] + im[b] * sin[twiddle], ti = im[b] * cos[twiddle] - re[b] * sin[twiddle];
+          re[b] = re[a] - tr; im[b] = im[a] - ti; re[a] += tr; im[a] += ti;
+        }
+      }
+    }
+    for (let bin = 0; bin <= half; bin++) magnitudes[bin] = Math.hypot(re[bin], im[bin]);
+    return magnitudes;
+  };
+}
+
+/** Spectral flux (all bands and the 40–160 Hz kick band) and RMS per frame; frame times are window centres. */
+export function onsetEnvelope(pcm, sampleRate, { size = 1024, hop = 512 } = {}) {
+  const spectrum = createSpectrum(size), count = Math.max(1, Math.floor((pcm.length - size) / hop) + 1);
+  const flux = new Float64Array(count), low = new Float64Array(count), rms = new Float64Array(count);
+  const binHz = sampleRate / size, lowFrom = Math.ceil(40 / binHz), lowTo = Math.floor(160 / binHz);
+  let previous = null, previousLow = 0;
+  for (let frame = 0; frame < count; frame++) {
+    const offset = frame * hop, magnitudes = spectrum(pcm, offset);
+    let energy = 0;
+    for (let index = offset; index < offset + size && index < pcm.length; index++) energy += pcm[index] * pcm[index];
+    rms[frame] = Math.sqrt(energy / size);
+    let lowSum = 0;
+    for (let bin = lowFrom; bin <= lowTo; bin++) lowSum += magnitudes[bin];
+    if (previous) {
+      let total = 0;
+      for (let bin = 1; bin < magnitudes.length; bin++) { const rise = Math.log1p(magnitudes[bin]) - previous[bin]; if (rise > 0) total += rise; }
+      flux[frame] = total; low[frame] = Math.max(0, lowSum - previousLow);
+    } else previous = new Float64Array(magnitudes.length);
+    for (let bin = 0; bin < magnitudes.length; bin++) previous[bin] = Math.log1p(magnitudes[bin]);
+    previousLow = lowSum;
+  }
+  return { flux, low, rms, fps: sampleRate / hop, offset: size / 2 / sampleRate };
+}
+
+/** Linear interpolation of an envelope at fractional frame positions. */
+export function sampleAt(values, position) {
+  if (position <= 0) return values[0] ?? 0;
+  if (position >= values.length - 1) return values[values.length - 1] ?? 0;
+  const index = Math.floor(position), fraction = position - index;
+  return values[index] * (1 - fraction) + values[index + 1] * fraction;
+}
+
+/**
+ * Tempo from the onset envelope's autocorrelation (70–180 BPM), refined with a beat-grid search for period and phase.
+ * A candidate beat is scored with the correlation at one, two and four beats, so syncopations at 1.5 beats
+ * (which the plain autocorrelation peak often prefers) lose to the bar-level pulse.
+ */
+export function detectBeats(envelope, fps, offset = 0, { minBpm = 70, maxBpm = 180 } = {}) {
+  const mean = envelope.reduce((sum, value) => sum + value, 0) / envelope.length;
+  const centred = Float64Array.from(envelope, (value) => value - mean);
+  const memo = new Map();
+  const correlation = (lag) => {
+    if (lag >= centred.length - 1) return 0;
+    if (!memo.has(lag)) { let sum = 0; for (let index = lag; index < centred.length; index++) sum += centred[index] * centred[index - lag]; memo.set(lag, sum / (centred.length - lag)); }
+    return memo.get(lag);
+  };
+  const zero = correlation(0) || 1;
+  const at = (lag) => { const whole = Math.floor(lag), fraction = lag - whole; return ((1 - fraction) * correlation(whole) + fraction * correlation(whole + 1)) / zero; };
+  let coarse = 0.5, best = -Infinity;
+  for (let bpm = maxBpm; bpm >= minBpm; bpm -= 0.05) {
+    const lag = fps * 60 / bpm;
+    if (4 * lag > centred.length / 2) break;
+    const value = at(lag) + at(2 * lag) + at(4 * lag);
+    if (value > best) { best = value; coarse = lag / fps; }
+  }
+  // A small period error drifts the grid over a long bed, so search period and phase together.
+  const duration = envelope.length / fps;
+  const gridScore = (period, phase) => { let sum = 0; for (let time = phase; time < duration; time += period) sum += sampleAt(envelope, (time - offset) * fps); return sum; };
+  let period = coarse, phase = 0, score = -Infinity;
+  for (let step = -60; step <= 60; step++) {
+    const candidate = coarse * (1 + step * 0.0002);
+    for (let index = 0; index < 64; index++) {
+      const shift = candidate * index / 64, value = gridScore(candidate, shift);
+      if (value > score) { score = value; period = candidate; phase = shift; }
+    }
+  }
+  for (let index = -8; index <= 8; index++) {
+    const shift = phase + period * index / 512, value = gridScore(period, shift);
+    if (shift >= 0 && value > score) { score = value; phase = shift; }
+  }
+  return { bpm: 60 / period, period, phase };
+}
+
+/** 12-bin pitch-class profile of each window (80–2000 Hz), from a 4096-point STFT. */
+export function chromaFrames(pcm, sampleRate, { size = 4096, hop = 2048 } = {}) {
+  const spectrum = createSpectrum(size), count = Math.max(1, Math.floor((pcm.length - size) / hop) + 1), binHz = sampleRate / size;
+  const classes = new Int8Array(size / 2 + 1).fill(-1);
+  for (let bin = 1; bin <= size / 2; bin++) { const hz = bin * binHz; if (hz >= 80 && hz <= 2000) classes[bin] = ((Math.round(12 * Math.log2(hz / 440)) % 12) + 12) % 12; }
+  const frames = [];
+  for (let frame = 0; frame < count; frame++) {
+    const magnitudes = spectrum(pcm, frame * hop), chroma = new Float64Array(12);
+    for (let bin = 1; bin < magnitudes.length; bin++) if (classes[bin] >= 0) chroma[classes[bin]] += magnitudes[bin];
+    frames.push({ time: (frame * hop + size / 2) / sampleRate, chroma });
+  }
+  return frames;
+}
+
+export function cosine(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let index = 0; index < a.length; index++) { dot += a[index] * b[index]; na += a[index] * a[index]; nb += b[index] * b[index]; }
+  return na && nb ? dot / Math.sqrt(na * nb) : 0;
+}

package/templates/video/scripts/audio-vo.mjs

@@ -0,0 +1,158 @@
+/**
+ * npm run audio:vo -- [--animation NAME]
+ * Cuts, speeds up and places voiceover takes from production/audio/vo.json; writes production/audio/work/vo-track.wav
+ * and production/audio/timing.json (segment and caption times on the film timeline).
+ */
+import { mkdir, access } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { projectArguments, projectContext } from "./project-context.mjs";
+import { decodePcm, detectPhrases, ffmpeg, parseFlags, projectPath, readJson, round, writeJson } from "./audio-tools.mjs";
+
+const SAMPLE_RATE = 48000;
+
+/** Caption texts for a segment: `captions` as given, or `text` split after sentence punctuation. */
+export function segmentTexts(segment) {
+  if (Array.isArray(segment.captions) && segment.captions.length) {
+    if (segment.captions.some((text) => typeof text !== "string" || !text.trim())) throw new Error(`Segment ${segment.id}: every caption must be non-empty text.`);
+    return segment.captions.map((text) => text.trim());
+  }
+  if (typeof segment.text === "string" && segment.text.trim()) return segment.text.trim().split(/(?<=[.!?:;])\s+/).filter(Boolean);
+  throw new Error(`Segment ${segment.id}: add "captions" (one string per on-screen caption) or "text" (the transcript) so captions can be timed.`);
+}
+
+/**
+ * Chooses caption boundaries among the pauses between phrases: k captions need k−1 pauses, preferring long pauses
+ * near where the text's character count says each caption should end.
+ */
+export function splitCaptions(phrases, texts, { distanceWeight = 0.35 } = {}) {
+  if (!phrases.length) throw new Error("No speech was detected.");
+  const start = phrases[0].start, end = phrases.at(-1).end;
+  if (texts.length === 1) return [{ text: texts[0], start, end }];
+  const pauses = phrases.slice(1).map((phrase, index) => ({ index, start: phrases[index].end, end: phrase.start }));
+  const needed = texts.length - 1;
+  if (pauses.length < needed) throw new Error(`Found ${pauses.length} pause(s) for ${texts.length} captions; merge captions or lower captionSilence.noiseDb/minSeconds.`);
+  const lengths = texts.map((text) => [...text.replace(/\s+/g, " ")].length), total = lengths.reduce((sum, value) => sum + value, 0);
+  const expected = lengths.slice(0, -1).map((_, index) => start + (end - start) * lengths.slice(0, index + 1).reduce((sum, value) => sum + value, 0) / total);
+  const score = (pause, boundary) => (pause.end - pause.start) - distanceWeight * Math.abs((pause.start + pause.end) / 2 - expected[boundary]);
+  // best[b][p]: best total choosing boundaries 0..b with boundary b at pause p (pauses stay in order).
+  const best = Array.from({ length: needed }, () => new Array(pauses.length).fill(-Infinity)), from = Array.from({ length: needed }, () => new Array(pauses.length).fill(-1));
+  for (let p = 0; p < pauses.length; p++) best[0][p] = score(pauses[p], 0);
+  for (let b = 1; b < needed; b++) {
+    for (let p = b; p < pauses.length; p++) {
+      for (let q = b - 1; q < p; q++) {
+        const value = best[b - 1][q] + score(pauses[p], b);
+        if (value > best[b][p]) { best[b][p] = value; from[b][p] = q; }
+      }
+    }
+  }
+  let last = -1, top = -Infinity;
+  for (let p = needed - 1; p < pauses.length; p++) if (best[needed - 1][p] > top) { top = best[needed - 1][p]; last = p; }
+  const chosen = [];
+  for (let b = needed - 1, p = last; b >= 0; p = from[b][p], b--) chosen.unshift(pauses[p]);
+  return texts.map((text, index) => ({ text, start: index ? chosen[index - 1].end : start, end: index < needed ? chosen[index].start : end }));
+}
+
+/**
+ * Places segments on the film timeline. Pauses inside a take keep their sped-up length up to `maxPause` film seconds;
+ * longer ones are cut there, which splits the take into pieces. `start` is when the first word is heard.
+ */
+export function placeVoiceover(segments, { start = 0.25, gap = 0.35, tempo = 1, maxPause = 0.26, padIn = 0.03, padOut = 0.08 } = {}) {
+  if (!(tempo >= 0.5 && tempo <= 2)) throw new Error("tempo must be between 0.5 and 2.");
+  const placed = [], captions = [];
+  let cursor = start, previousEnd = null;
+  for (const segment of segments) {
+    if (!segment.phrases.length) throw new Error(`Segment ${segment.id}: no speech was detected; check the file or lower silence.noiseDb.`);
+    if (previousEnd !== null) cursor = previousEnd + (segment.gapBefore ?? gap);
+    else if (segment.gapBefore) cursor += segment.gapBefore;
+    const pieces = [];
+    let speechStart = cursor;
+    for (const [index, phrase] of segment.phrases.entries()) {
+      const piece = pieces.at(-1);
+      const pause = index ? (phrase.start - segment.phrases[index - 1].end) / tempo : 0;
+      if (piece && pause <= maxPause) { piece.source[1] = phrase.end; continue; }
+      if (piece) speechStart = piece.speech[0] + (piece.source[1] - piece.source[0]) / tempo + maxPause;
+      pieces.push({ source: [phrase.start, phrase.end], speech: [speechStart, 0] });
+    }
+    for (const piece of pieces) {
+      piece.speech[1] = piece.speech[0] + (piece.source[1] - piece.source[0]) / tempo;
+      const lead = Math.min(padIn, piece.source[0], piece.speech[0] * tempo);
+      piece.trim = [piece.source[0] - lead, Math.min(segment.duration ?? Infinity, piece.source[1] + padOut)];
+      piece.at = piece.speech[0] - lead / tempo;
+    }
+    const toFilm = (time) => {
+      const piece = pieces.find((item) => time <= item.source[1] + 1e-6) ?? pieces.at(-1);
+      return piece.speech[0] + (Math.min(Math.max(time, piece.source[0]), piece.source[1]) - piece.source[0]) / tempo;
+    };
+    for (const caption of segment.captions ?? []) captions.push({ start: round(toFilm(caption.start)), end: round(toFilm(caption.end)), text: caption.text, segment: segment.id });
+    previousEnd = pieces.at(-1).speech[1];
+    placed.push({ id: segment.id, source: segment.source, start: round(pieces[0].speech[0]), end: round(previousEnd),
+      pieces: pieces.map((piece) => ({ start: round(piece.speech[0]), end: round(piece.speech[1]), trim: piece.trim.map((value) => round(value)), at: round(piece.at) })) });
+  }
+  return { tempo, segments: placed, captions, voEnd: round(previousEnd ?? start) };
+}
+
+async function existing(...files) {
+  for (const file of files) { try { await access(file); return file; } catch { /* try the next candidate */ } }
+  return null;
+}
+
+async function main() {
+  const root = fileURLToPath(new URL("../", import.meta.url));
+  const selection = projectArguments(process.argv.slice(2));
+  const flags = parseFlags(selection.rest, { config: "string" });
+  const context = await projectContext(root, selection.animation);
+  const base = context.projectRoot, configFile = projectPath(base, flags.config ?? "production/audio/vo.json", "--config");
+  const vo = await readJson(configFile);
+  if (!Array.isArray(vo.segments) || !vo.segments.length) throw new Error(`${path.relative(base, configFile)} needs a "segments" list.`);
+  const duration = Number(vo.duration ?? context.config.duration), tempo = Number(vo.tempo ?? 1);
+  const silence = { noiseDb: vo.silence?.noiseDb ?? -38, minSeconds: vo.silence?.minSeconds ?? 0.12 };
+  const captionSilence = { noiseDb: vo.captionSilence?.noiseDb ?? silence.noiseDb + 6, minSeconds: vo.captionSilence?.minSeconds ?? 0.06 };
+  const segments = [];
+  for (const segment of vo.segments) {
+    if (typeof segment.id !== "string" || !/^[\w.-]{1,80}$/.test(segment.id)) throw new Error("Each segment needs an id of letters, digits, dots, dashes or underscores.");
+    const texts = segmentTexts(segment);
+    const fallback = ["wav", "mp3", "m4a", "ogg"].map((extension) => path.join(base, `production/audio/vo/${segment.id}.${extension}`));
+    const file = segment.file ? projectPath(base, segment.file, `segment ${segment.id} file`) : await existing(...fallback);
+    if (!file || !await existing(file)) throw new Error(`Segment ${segment.id}: audio not found (${segment.file ?? "production/audio/vo/" + segment.id + ".wav"}).`);
+    const pcm = await decodePcm(file, SAMPLE_RATE);
+    const phrases = detectPhrases(pcm, SAMPLE_RATE, { noiseDb: silence.noiseDb, minSilence: silence.minSeconds });
+    const fine = detectPhrases(pcm, SAMPLE_RATE, { noiseDb: captionSilence.noiseDb, minSilence: captionSilence.minSeconds });
+    const usable = fine.length >= texts.length ? fine : phrases;
+    let captions;
+    try { captions = splitCaptions(usable, texts); } catch (error) { throw new Error(`Segment ${segment.id}: ${error.message}`); }
+    // The finer pass only places boundaries between captions; the segment's outer edges follow the trimmed speech.
+    if (phrases.length) { captions[0].start = phrases[0].start; captions.at(-1).end = phrases.at(-1).end; }
+    segments.push({ id: segment.id, file, source: path.relative(base, file).split(path.sep).join("/"), duration: pcm.length / SAMPLE_RATE, phrases, captions, gapBefore: segment.gapBefore });
+  }
+  const timing = placeVoiceover(segments, { start: vo.start ?? 0.25, gap: vo.gap ?? 0.35, tempo, maxPause: vo.maxPause ?? 0.26, padIn: vo.pad?.in ?? 0.03, padOut: vo.pad?.out ?? 0.08 });
+  const lastPiece = timing.segments.at(-1).pieces.at(-1);
+  if (lastPiece.end > duration) throw new Error(`The voiceover runs to ${lastPiece.end.toFixed(2)} s, past the ${duration} s film. Shorten gaps, raise tempo or trim the script.`);
+
+  const inputs = [], filters = [], labels = [];
+  for (const [index, segment] of timing.segments.entries()) {
+    inputs.push("-i", segments[index].file);
+    const parts = segment.pieces.map((_, piece) => `[s${index}p${piece}]`);
+    filters.push(`[${index}:a]aresample=${SAMPLE_RATE},aformat=channel_layouts=mono,asplit=${parts.length}${parts.join("")}`);
+    for (const [pieceIndex, piece] of segment.pieces.entries()) {
+      const label = `[v${labels.length}]`;
+      filters.push(`[s${index}p${pieceIndex}]atrim=${piece.trim[0]}:${piece.trim[1]},asetpts=PTS-STARTPTS,atempo=${tempo},afade=t=in:d=0.015,areverse,afade=t=in:d=0.04,areverse,adelay=${Math.round(piece.at * 1000)}:all=1${label}`);
+      labels.push(label);
+    }
+  }
+  filters.push(`${labels.join("")}amix=inputs=${labels.length}:normalize=0,apad=whole_dur=${duration},atrim=0:${duration}[out]`);
+  const work = path.join(base, "production/audio/work");
+  await mkdir(work, { recursive: true });
+  const track = path.join(work, "vo-track.wav");
+  await ffmpeg(["-y", "-loglevel", "error", ...inputs, "-filter_complex", filters.join(";"), "-map", "[out]", "-ac", "1", "-ar", String(SAMPLE_RATE), "-c:a", "pcm_s16le", track]);
+  const timingFile = path.join(base, "production/audio/timing.json");
+  await writeJson(timingFile, { tempo, start: timing.segments[0].start, segments: timing.segments, captions: timing.captions, voEnd: timing.voEnd });
+
+  const endHold = Number(vo.endHold ?? 3);
+  console.log(`Voiceover: ${timing.segments.length} segments, ${timing.captions.length} captions, tempo ${tempo}, ends at ${timing.voEnd.toFixed(2)} s of ${duration} s.`);
+  for (const segment of timing.segments.slice(0, 24)) console.log(`  ${segment.id.padEnd(18)} ${segment.start.toFixed(2).padStart(6)} → ${segment.end.toFixed(2).padStart(6)}  ${segment.pieces.length} piece(s)`);
+  if (timing.voEnd > duration - endHold) console.log(`Warning: the voiceover ends ${(duration - timing.voEnd).toFixed(2)} s before the film end; endHold asks for ${endHold} s. Tighten gaps or raise tempo.`);
+  console.log(`Wrote ${path.relative(base, track)} and ${path.relative(base, timingFile)}. Bind scene cues to timing.json captions; then run npm run audio:mix.`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/templates/video/scripts/export-mp4.mjs

@@ -10,18 +10,20 @@ import ffprobe from "@ffprobe-installer/ffprobe";
 import { projectArguments, projectContext, publicFile } from "./project-context.mjs";
 import { workspacePlugin } from "./workspace-plugin.mjs";
 import { subtitleCues, toSrt, toVtt } from "./subtitles.mjs";
-import { captureHeadless } from "./headless-browser.mjs";
+import { captureHeadless, takeHeadlessFlag } from "./headless-browser.mjs";
 
 const root = fileURLToPath(new URL("../", import.meta.url));
 const selection = projectArguments(process.argv.slice(2));
 const args = selection.rest;
+// --headless captures in a local headless Chrome instead of waiting for you to open the page.
+const headless = takeHeadlessFlag(args);
 let port = 5196;
 // Captions become subtitle files beside the MP4 unless --burn-captions draws them into the picture, e.g. for social feeds.
 let burnCaptions = false;
 for (let index = 0; index < args.length; index++) {
   if (args[index] === "--burn-captions") burnCaptions = true;
   else if (args[index] === "--port" && /^\d+$/.test(args[index + 1] ?? "")) port = Number(args[++index]);
-  else throw new Error("Usage: npm run export:mp4 -- [--port 5196] [--burn-captions]");
+  else throw new Error("Usage: npm run export:mp4 -- [--animation NAME] [--headless] [--port 5196] [--burn-captions]");
 }
 if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error("Export port must be 1024–65535.");
 const context = await projectContext(root, selection.animation);
@@ -244,7 +246,7 @@ process.once("SIGINT", () => { void cleanup(new Error("Cancelled.")); });
 process.once("SIGTERM", () => { void cleanup(new Error("Cancelled.")); });
 try { await server.listen(); } catch (error) { await cleanup(error); throw error; }
 console.log(`Open this local export page and keep it open until complete:\nhttp://127.0.0.1:${port}${context.route}?capture=1&export=${token}\nOutput: ${destination}\nThe preview can stay open. This capture runs locally without generation credits.`);
-if (process.env.ANIMAGURU_HEADLESS === "1") {
+if (headless) {
   try { await captureHeadless(`http://127.0.0.1:${port}${context.route}?capture=1&export=${token}`, { endpoint: "/__export/finish" }); }
   catch (error) { await cleanup(error); }
 }

package/templates/video/scripts/frames.mjs

@@ -0,0 +1,81 @@
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createServer } from "vite";
+import { projectArguments, projectContext } from "./project-context.mjs";
+import { workspacePlugin } from "./workspace-plugin.mjs";
+import { analyzeLayout, reviewLines } from "./review-analysis.mjs";
+import { waitForPlayer, withPage } from "./headless-browser.mjs";
+
+const usage = "Usage: npm run frames -- [--animation NAME] [--at 1.2,4.5,…] [--every SECONDS] [--count 12] [--width PX] [--columns N] [--no-captions] [--full] [--out DIR]";
+const root = fileURLToPath(new URL("../", import.meta.url));
+const selection = projectArguments(process.argv.slice(2));
+const options = { at: null, every: null, count: 12, width: null, columns: null, captions: true, full: false, out: null };
+for (let index = 0; index < selection.rest.length; index++) {
+  const flag = selection.rest[index], value = selection.rest[index + 1];
+  const number = () => { const parsed = Number(value); if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`${flag} needs a positive number.\n${usage}`); index++; return parsed; };
+  if (flag === "--at") { options.at = String(value ?? "").split(",").map(Number); if (!options.at.length || options.at.some((t) => !Number.isFinite(t) || t < 0)) throw new Error(`--at needs comma-separated seconds.\n${usage}`); index++; }
+  else if (flag === "--every") options.every = number();
+  else if (flag === "--count") options.count = Math.round(number());
+  else if (flag === "--width") options.width = Math.round(number());
+  else if (flag === "--columns") options.columns = Math.round(number());
+  else if (flag === "--no-captions") options.captions = false;
+  else if (flag === "--full") options.full = true;
+  else if (flag === "--out" && value) { options.out = value; index++; }
+  else throw new Error(usage);
+}
+const context = await projectContext(root, selection.animation), config = context.config;
+const last = Math.max(0, config.duration - 1 / config.fps);
+const times = (options.at ?? (options.every
+  ? Array.from({ length: Math.floor(config.duration / options.every) }, (_, i) => (i + 0.5) * options.every)
+  : Array.from({ length: options.count }, (_, i) => (i + 0.5) * config.duration / options.count))).map((t) => Math.min(t, last));
+if (!times.length || times.length > 120) throw new Error("Choose between 1 and 120 frames.");
+const portrait = config.height > config.width;
+const width = options.width ?? (portrait ? 270 : 400), columns = options.columns ?? (portrait ? 4 : 3), perSheet = columns * (portrait ? 3 : 4);
+const output = path.resolve(context.projectRoot, options.out ?? "production/review/frames");
+const server = await createServer({ configFile: false, root, base: "./", publicDir: context.workspace ? false : undefined, clearScreen: false, logLevel: "error",
+  server: { host: "127.0.0.1", port: Number(process.env.ANIMAGURU_FRAMES_PORT ?? 5198), strictPort: false }, plugins: context.workspace ? [workspacePlugin(root, { animation: context.name })] : [] });
+try {
+  await server.listen();
+  const port = server.httpServer.address().port;
+  const result = await withPage(`http://127.0.0.1:${port}${context.route}?capture=1`, async (page, problems) => {
+    await waitForPlayer(page, problems);
+    return page.evaluate(async ({ times, width, columns, perSheet, captions, full }) => {
+      const api = window.animaguru;
+      api.setCaptions(captions);
+      const height = Math.round(api.height * width / api.width), label = 30, pad = 10;
+      const sheets = [], samples = [], frames = [];
+      for (let start = 0; start < times.length; start += perSheet) {
+        const chunk = times.slice(start, start + perSheet), rows = Math.ceil(chunk.length / columns);
+        const sheet = document.createElement("canvas");
+        sheet.width = pad + Math.min(columns, chunk.length) * (width + pad); sheet.height = pad + rows * (height + label + pad);
+        const draw = sheet.getContext("2d");
+        draw.fillStyle = "#ffffff"; draw.fillRect(0, 0, sheet.width, sheet.height);
+        for (const [index, time] of chunk.entries()) {
+          await api.seek(time);
+          const x = pad + (index % columns) * (width + pad), y = pad + Math.floor(index / columns) * (height + label + pad);
+          draw.drawImage(api.canvas, x, y + label, width, height);
+          draw.fillStyle = "#111111"; draw.font = "600 18px system-ui, sans-serif"; draw.fillText(`${time.toFixed(2)}s`, x + 2, y + 21);
+          samples.push({ time, texts: api.texts.map((box) => ({ ...box })) });
+          if (full) frames.push({ time, image: api.canvas.toDataURL("image/jpeg", 0.92) });
+        }
+        sheets.push(sheet.toDataURL("image/png"));
+      }
+      return { sheets, samples, frames };
+    }, { times, width, columns, perSheet, captions: options.captions, full: options.full });
+  }, { viewport: { width: 1280, height: 900 } });
+  await mkdir(output, { recursive: true });
+  // Only this tool's own previous output is replaced.
+  for (const file of await readdir(output)) if (/^(sheet-\d+\.png|frame-[\d.]+s\.jpg)$/.test(file)) await rm(path.join(output, file));
+  const written = [];
+  for (const [index, sheet] of result.sheets.entries()) {
+    const file = path.join(output, `sheet-${String(index + 1).padStart(2, "0")}.png`);
+    await writeFile(file, Buffer.from(sheet.split(",")[1], "base64")); written.push(file);
+  }
+  for (const frame of result.frames) await writeFile(path.join(output, `frame-${frame.time.toFixed(2)}s.jpg`), Buffer.from(frame.image.split(",")[1], "base64"));
+  console.log(`${times.length} frames at ${times.map((t) => t.toFixed(2)).join(", ")} s${options.captions ? "" : " (captions off)"}`);
+  for (const file of written) console.log(`Sheet: ${file}`);
+  if (result.frames.length) console.log(`Full-size frames: ${output}`);
+  const lines = reviewLines({ problems: [], warnings: analyzeLayout(result.samples, config) });
+  console.log(lines.length ? `Layout notes at these times:\n${lines.join("\n")}` : "No layout notes at these times (overlap, safe area, text size, captions).");
+} finally { await server.close(); }

package/templates/video/scripts/headless-browser.mjs

@@ -1,17 +1,90 @@
-/** Uses the same capture page and HTTP protocol as a locally opened browser. */
+import { existsSync } from "node:fs";
+
+const linuxBrowsers = ["/usr/bin/chromium", "/usr/bin/chromium-browser", "/usr/bin/google-chrome", "/usr/bin/google-chrome-stable"];
+const firstLine = (message) => String(message).split("\n").find((line) => line.trim()) ?? String(message);
+
+/** True for --headless (removed from args) or ANIMAGURU_HEADLESS=1. */
+export function takeHeadlessFlag(args) {
+  const index = args.indexOf("--headless");
+  if (index >= 0) args.splice(index, 1);
+  return index >= 0 || process.env.ANIMAGURU_HEADLESS === "1";
+}
+
+/**
+ * Launches headless Chromium for capture, review and frame tools. Tries, in order:
+ * PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH, a system Chromium on Linux, installed Google Chrome or Microsoft Edge,
+ * then a browser installed with `npx playwright install chromium`.
+ */
+export async function launchBrowser() {
+  let chromium;
+  try { ({ chromium } = await import("playwright-core")); }
+  catch { throw new Error("Headless mode needs playwright-core. Run npm install in this workspace."); }
+  const explicit = process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH;
+  const candidates = explicit ? [{ label: explicit, options: { executablePath: explicit } }] : [
+    ...(process.platform === "linux" ? linuxBrowsers.filter((file) => existsSync(file)).map((file) => ({ label: file, options: { executablePath: file } })) : []),
+    { label: "Google Chrome", options: { channel: "chrome" } },
+    { label: "Microsoft Edge", options: { channel: "msedge" } },
+    { label: "Playwright Chromium", options: {} },
+  ];
+  // Containers usually run as root without /dev/shm space; desktop browsers keep their sandbox.
+  const args = ["--autoplay-policy=no-user-gesture-required", ...(process.platform === "linux" ? ["--no-sandbox", "--disable-dev-shm-usage"] : [])];
+  const failures = [];
+  for (const candidate of candidates) {
+    try { return await chromium.launch({ headless: true, args, ...candidate.options }); }
+    catch (error) { failures.push(`${candidate.label}: ${firstLine(error.message)}`); }
+  }
+  throw new Error(`No Chromium-based browser could start for headless mode. Install Google Chrome, set PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH, or run npx playwright install chromium.\n${failures.join("\n")}`);
+}
+
+/** Collects page errors, console errors and failed requests, so a broken film fails with its cause instead of a timeout. */
+function watch(page) {
+  const problems = [];
+  page.on("pageerror", (error) => { problems.push(`Page error: ${error.message}`); console.error(`Page error: ${error.message}`); });
+  page.on("console", (message) => { if (message.type() === "error") problems.push(`Console: ${message.text()}`); });
+  page.on("response", (response) => { if (response.status() >= 400) problems.push(`HTTP ${response.status()} ${new URL(response.url()).pathname}`); });
+  return problems;
+}
+const report = (problems) => problems.length ? `\n${[...new Set(problems)].slice(-8).join("\n")}` : "";
+
+/** Opens a page and closes the browser after `use(page, problems)` settles. */
+export async function withPage(url, use, { viewport = { width: 1280, height: 900 }, timeout = 60_000 } = {}) {
+  const browser = await launchBrowser();
+  try {
+    const page = await browser.newPage({ viewport, deviceScaleFactor: 1 });
+    const problems = watch(page);
+    await page.goto(url, { waitUntil: "domcontentloaded", timeout });
+    return await use(page, problems);
+  } finally { await browser.close(); }
+}
+
+/** Waits for the player's window.animaguru API (after fonts, textures and the first render), or fails with the page's errors. */
+export async function waitForPlayer(page, problems = [], timeout = 120_000) {
+  const handle = await page.waitForFunction(() => window.animaguru?.ready ? "ready" : document.getElementById("status")?.textContent || null, undefined, { timeout, polling: 250 }).catch(() => null);
+  const state = await handle?.jsonValue();
+  if (state !== "ready") throw new Error(`The player did not start${state ? `: ${state}` : ` within ${timeout / 1000} s`}.${report(problems)}`);
+}
+
+/** Uses the same capture page and HTTP protocol as a locally opened browser; stops early when the player reports a failure. */
 export async function captureHeadless(url, { endpoint, timeout = 30 * 60 * 1000 } = {}) {
-  const { chromium } = await import("playwright-core");
-  const browser = await chromium.launch({
-    executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH ?? "/usr/bin/chromium",
-    headless: true, args: ["--no-sandbox", "--disable-dev-shm-usage", "--autoplay-policy=no-user-gesture-required"],
-  });
+  const browser = await launchBrowser();
   try {
     const page = await browser.newPage({ deviceScaleFactor: 1 });
+    const problems = watch(page);
     const finished = page.waitForResponse((response) => new URL(response.url()).pathname === endpoint, { timeout });
-    page.on("pageerror", (error) => console.error(`Capture page: ${error.message}`));
     await page.goto(url, { waitUntil: "domcontentloaded", timeout: 60_000 });
-    const response = await finished;
-    if (!response.ok()) throw new Error(`Capture failed (${response.status()}): ${await response.text()}`);
-    await response.finished();
+    await waitForPlayer(page, problems);
+    let stop;
+    const failed = new Promise((_, reject) => {
+      const poll = setInterval(async () => {
+        const status = await page.evaluate(() => document.getElementById("status")?.textContent || "").catch(() => "");
+        if (status) { clearInterval(poll); reject(new Error(`Capture stopped: ${status}${report(problems)}`)); }
+      }, 1000);
+      stop = () => clearInterval(poll);
+    });
+    try {
+      const response = await Promise.race([finished, failed]);
+      if (!response.ok()) throw new Error(`Capture failed (${response.status()}): ${await response.text()}`);
+      await response.finished();
+    } finally { stop(); }
   } finally { await browser.close(); }
 }