@odori/cli 0.0.2

package/src/render.ts

@@ -0,0 +1,627 @@
+import {spawn} from "node:child_process";
+import type {Writable} from "node:stream";
+import {copyFile, mkdir, rm, writeFile} from "node:fs/promises";
+import {cpus} from "node:os";
+import {dirname, join, resolve} from "node:path";
+import {chromium, type Browser, type Page} from "playwright-core";
+import type {ManifestAudioCue} from "odori";
+import {buildAudioFilter, resolveCueFile, type MixInput} from "./audio-mix";
+import {chunkFrames, planChunks, type FrameChunk} from "./chunks";
+import {chunkKey, readChunkRecord, signaturesMatch, useChunkRecord, writeChunkRecord} from "./chunk-cache";
+import {type ResolvedConfig} from "./config";
+import {installBrowser, installFfmpeg, resolveBrowser, resolveFfmpeg} from "./binaries";
+import {FORMATS, type VideoFormat} from "./formats";
+import {log} from "./log";
+
+export type RenderTarget = {
+  videoId: string;
+  width: number;
+  height: number;
+  fps: number;
+  durationInFrames: number;
+  input?: Record<string, unknown>;
+  prepared?: unknown;
+  audio?: ManifestAudioCue[];
+  targetLufs?: number;
+  scenes?: Array<{id: string; start: number; durationInFrames: number}>;
+};
+
+const encodeParam = (value: unknown) => Buffer.from(JSON.stringify(value), "utf8").toString("base64");
+
+const renderUrl = (origin: string, target: RenderTarget, frame: number) => {
+  const params = new URLSearchParams({render: "1", video: target.videoId, frame: String(frame)});
+  if (target.input) params.set("input", encodeParam(target.input));
+  if (target.prepared !== undefined) params.set("prepared", encodeParam(target.prepared));
+  return `${origin}/?${params.toString()}`;
+};
+
+export type RenderPage = {browser: Browser; page: Page; errors: string[]};
+
+/** Open one video in render mode and wait for its first frame to mount. */
+export const openRenderPage = async (
+  origin: string,
+  target: RenderTarget,
+  config: ResolvedConfig,
+): Promise<RenderPage> => {
+  const executablePath = await browserExecutable(config);
+  const browser = await chromium.launch({executablePath, headless: true});
+  const page = await browser.newPage({
+    viewport: {width: target.width, height: target.height},
+    deviceScaleFactor: 1,
+  });
+  // Collected for the whole session, not just for the mount, so an exception
+  // thrown at frame 200 cannot produce a quietly wrong file.
+  const errors: string[] = [];
+  page.on("pageerror", (error) => errors.push(error.message));
+  await page.goto(renderUrl(origin, target, 0), {waitUntil: "networkidle"});
+  try {
+    await page.locator('[data-odori-frame="0"]').waitFor({timeout: 20000});
+  } catch {
+    await browser.close();
+    throw new Error(`The video did not mount.${errors.length ? ` ${errors.join(" ")}` : ""}`);
+  }
+  await page.evaluate(() => document.fonts.ready);
+  return {browser, page, errors};
+};
+
+/** Seek through the readiness handshake instead of guessing with timeouts. */
+export const seekTo = async (page: Page, frame: number) => {
+  await page.evaluate((next) => window.__ODORI_SET_FRAME__?.(next), frame);
+  await page.locator(`[data-odori-frame="${frame}"]`).waitFor({timeout: 20000});
+};
+
+export const readTimeline = async (page: Page) =>
+  page.evaluate(() => window.__ODORI_TIMELINE__ ?? {scenes: [], durationInFrames: 0});
+
+export const readAudio = async (page: Page) =>
+  page.evaluate(() => window.__ODORI_AUDIO__ ?? {cues: [], durationInFrames: 0});
+
+/**
+ * A cheap hash of the rendered scene, evaluated as source so no bundler helper
+ * leaks into the page. Motion is a pure function of the frame, so two frames
+ * with the same signature are the same picture.
+ */
+const SIGNATURE_SCRIPT = `(() => {
+  var root = document.querySelector("[data-odori-video]");
+  if (!root) return "";
+  var markup = root.outerHTML;
+  var hash = 2166136261;
+  for (var index = 0; index < markup.length; index += 1) {
+    hash ^= markup.charCodeAt(index);
+    hash = (hash + ((hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24))) >>> 0;
+  }
+  return hash.toString(16) + ":" + markup.length;
+})()`;
+
+/**
+ * Signatures for a run of frames, computed inside the page.
+ *
+ * Probing a cached chunk only needs to know whether the pictures changed, and
+ * a round trip per frame costs nearly as much as capturing one. This walks the
+ * frames in the page and returns the whole run in a single call.
+ */
+const PROBE_SCRIPT = `(async (frames) => {
+  var signature = function () {
+    var root = document.querySelector("[data-odori-video]");
+    if (!root) return "";
+    var markup = root.outerHTML;
+    var hash = 2166136261;
+    for (var index = 0; index < markup.length; index += 1) {
+      hash ^= markup.charCodeAt(index);
+      hash = (hash + ((hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24))) >>> 0;
+    }
+    return hash.toString(16) + ":" + markup.length;
+  };
+  var settled = function (frame) {
+    return new Promise(function (done, fail) {
+      var started = Date.now();
+      var check = function () {
+        var root = document.querySelector("[data-odori-frame]");
+        if (root && root.getAttribute("data-odori-frame") === String(frame)) {
+          done(undefined);
+          return;
+        }
+        if (Date.now() - started > 20000) {
+          fail(new Error("Timed out waiting for frame " + frame));
+          return;
+        }
+        requestAnimationFrame(check);
+      };
+      requestAnimationFrame(check);
+    });
+  };
+  var out = [];
+  for (var index = 0; index < frames.length; index += 1) {
+    window.__ODORI_SET_FRAME__(frames[index]);
+    await settled(frames[index]);
+    out.push(signature());
+  }
+  return out;
+})`;
+
+export const probeSignatures = async (page: Page, frames: number[]): Promise<string[]> => {
+  const signatures: string[] = [];
+  // Batched so one evaluate cannot run long enough to look like a hang.
+  for (let index = 0; index < frames.length; index += 60) {
+    const batch = frames.slice(index, index + 60);
+    const result = (await page.evaluate(`(${PROBE_SCRIPT})(${JSON.stringify(batch)})`)) as string[];
+    signatures.push(...result);
+  }
+  return signatures;
+};
+
+const run = (command: string, args: string[], signal?: AbortSignal) =>
+  new Promise<void>((resolveRun, rejectRun) => {
+    if (signal?.aborted) {
+      rejectRun(new Error("Render cancelled."));
+      return;
+    }
+    const child = spawn(command, args, {stdio: ["ignore", "ignore", "pipe"]});
+    let stderr = "";
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString();
+    });
+    const onAbort = () => child.kill("SIGTERM");
+    signal?.addEventListener("abort", onAbort, {once: true});
+    child.on("error", rejectRun);
+    child.on("exit", (code) => {
+      signal?.removeEventListener("abort", onAbort);
+      if (signal?.aborted) rejectRun(new Error("Render cancelled."));
+      else if (code === 0) resolveRun();
+      else rejectRun(new Error(`${command} exited with ${code}: ${stderr.slice(-800)}`));
+    });
+  });
+
+/**
+ * The Chrome this render will use, downloading the pinned build the first time
+ * a machine needs it. A render that waits ninety seconds once is better than a
+ * render that silently uses a different browser than the last one did.
+ */
+const browserExecutable = async (config: ResolvedConfig): Promise<string> => {
+  const resolved = await resolveBrowser(config);
+  if (resolved) return resolved.path;
+
+  log.detail("Downloading the pinned Chrome build. This happens once per machine.");
+  try {
+    return await installBrowser();
+  } catch (error) {
+    throw new Error(
+      `No Chrome available and the managed build could not be downloaded: ${(error as Error).message}\n` +
+        'Run "odori install" when you have a connection, or set chromePath in odori.config.ts.',
+    );
+  }
+};
+
+/**
+ * The FFmpeg this render will use. Same contract as the browser: managed and
+ * pinned by default, fetched once, overridable for a machine that has to use
+ * its own build.
+ */
+export const ffmpegExecutable = async (config: ResolvedConfig): Promise<string> => {
+  const resolved = await resolveFfmpeg(config);
+  if (resolved) return resolved.path;
+
+  log.detail("Downloading the pinned FFmpeg build. This happens once per machine.");
+  try {
+    return await installFfmpeg();
+  } catch (error) {
+    throw new Error(
+      `No FFmpeg available and the managed build could not be downloaded: ${(error as Error).message}\n` +
+        'Run "odori install" when you have a connection, or set ffmpegPath in odori.config.ts.',
+    );
+  }
+};
+
+/** Kept for callers that only want to know an encoder exists. */
+export const ensureFfmpeg = async (config: ResolvedConfig) => {
+  await ffmpegExecutable(config);
+};
+
+export const renderStill = async (
+  origin: string,
+  target: RenderTarget,
+  frame: number,
+  output: string,
+  config: ResolvedConfig,
+): Promise<string> => {
+  const {browser, page, errors} = await openRenderPage(origin, target, config);
+  try {
+    await mkdir(dirname(output), {recursive: true});
+    await seekTo(page, frame);
+    await page.screenshot({path: output});
+    if (errors.length > 0) log.warn(`The page reported an error while rendering: ${errors[0]}`);
+    return output;
+  } finally {
+    await browser.close();
+  }
+};
+
+export const defaultConcurrency = (): number => Math.max(1, Math.min(4, cpus().length - 2));
+
+type CaptureStats = {captured: number; reused: number; cachedChunks: number};
+
+/** Write to a pipe with backpressure, so a slow encoder cannot balloon memory. */
+const writeFrame = (stdin: Writable, frame: Buffer) =>
+  new Promise<void>((resolveWrite, rejectWrite) => {
+    if (stdin.write(frame)) {
+      resolveWrite();
+      return;
+    }
+    stdin.once("drain", resolveWrite);
+    stdin.once("error", rejectWrite);
+  });
+
+/**
+ * Encode one chunk from a stream of PNG buffers.
+ *
+ * Frames never touch the disk, which removes a write and a read per frame and
+ * makes a truncated file structurally impossible: the encoder receives exactly
+ * the frames the capture produced, in order.
+ */
+/**
+ * Where a numbered sequence goes. `out/cut.png` becomes `out/cut/00001.png`,
+ * so one export is one directory and a second export does not interleave with
+ * the first.
+ */
+const sequencePattern = (output: string): string => {
+  const dot = output.lastIndexOf(".");
+  const stem = dot > 0 ? output.slice(0, dot) : output;
+  const extension = dot > 0 ? output.slice(dot) : ".png";
+  return join(stem, `%05d${extension}`);
+};
+
+const openChunkEncoder = (
+  ffmpeg: string,
+  file: string,
+  fps: number,
+  preset: string,
+  format: VideoFormat,
+  signal?: AbortSignal,
+) => {
+  const child = spawn(
+    ffmpeg,
+    ["-y", "-f", "image2pipe", "-framerate", String(fps), "-i", "pipe:0", ...format.args(preset), file],
+    {stdio: ["pipe", "ignore", "pipe"]},
+  );
+
+  let stderr = "";
+  child.stderr?.on("data", (chunk: Buffer) => {
+    stderr += chunk.toString();
+  });
+  const onAbort = () => child.kill("SIGTERM");
+  signal?.addEventListener("abort", onAbort, {once: true});
+
+  const done = new Promise<void>((resolveDone, rejectDone) => {
+    child.on("error", rejectDone);
+    child.on("exit", (code) => {
+      signal?.removeEventListener("abort", onAbort);
+      if (signal?.aborted) rejectDone(new Error("Render cancelled."));
+      else if (code === 0) resolveDone();
+      else rejectDone(new Error(`ffmpeg exited with ${code}: ${stderr.slice(-800)}`));
+    });
+  });
+
+  return {child, done};
+};
+
+type LaneOptions = {
+  skipUnchanged: boolean;
+  signal?: AbortSignal;
+  preset: string;
+  format: VideoFormat;
+  /** The resolved encoder, so a lane never guesses at what is on PATH. */
+  ffmpeg: string;
+  workDir: string;
+  onFrame: () => void;
+  chunkFile: (chunk: FrameChunk) => string;
+  cacheIdentity?: (chunk: FrameChunk) => Parameters<typeof chunkKey>[0];
+};
+
+/**
+ * Capture one lane of chunks in a dedicated browser process.
+ *
+ * Screenshots are serialized per browser, so a lane owns a browser rather than
+ * a tab. A frame that fails is retried once on a fresh page, because frames are
+ * independent and losing a whole render to one timeout is a bad trade.
+ */
+const captureLane = async (
+  origin: string,
+  target: RenderTarget,
+  config: ResolvedConfig,
+  lane: FrameChunk[],
+  stats: CaptureStats,
+  options: LaneOptions,
+): Promise<void> => {
+  let session = await openRenderPage(origin, target, config);
+  const errors = session.errors;
+
+  const reopen = async () => {
+    await session.browser.close().catch(() => undefined);
+    session = await openRenderPage(origin, target, config);
+    session.errors.push(...errors);
+  };
+
+  const signatureOf = async () => (await session.page.evaluate(SIGNATURE_SCRIPT)) as string;
+
+  try {
+    for (const chunk of lane) {
+      if (options.signal?.aborted) throw new Error("Render cancelled.");
+      const frames = chunkFrames(chunk);
+      const identity = options.cacheIdentity?.(chunk);
+      const key = identity ? chunkKey(identity) : null;
+
+      // A cached chunk is reused only when every frame still looks the same,
+      // which is what makes the cache exact rather than hopeful.
+      if (key) {
+        const record = await readChunkRecord(config, key);
+        if (record) {
+          const observed = await probeSignatures(session.page, frames);
+          if (signaturesMatch(record.signatures, observed)) {
+            await useChunkRecord(config, key, options.chunkFile(chunk));
+            stats.cachedChunks += 1;
+            stats.captured += frames.length;
+            stats.reused += frames.length;
+            for (const _frame of frames) options.onFrame();
+            continue;
+          }
+        }
+      }
+
+      const file = options.chunkFile(chunk);
+      const encoder = openChunkEncoder(options.ffmpeg, file, target.fps, options.preset, options.format, options.signal);
+      const signatures: string[] = [];
+      let previousSignature: string | null = null;
+      let previousFrame: Buffer | null = null;
+      let written = 0;
+
+      try {
+        for (const frame of frames) {
+          if (options.signal?.aborted) throw new Error("Render cancelled.");
+
+          for (let attempt = 0; ; attempt += 1) {
+            try {
+              await seekTo(session.page, frame);
+              const signature = await signatureOf();
+              let image: Buffer;
+              if (options.skipUnchanged && previousFrame && signature === previousSignature) {
+                // The picture did not change, so the previous bytes still hold.
+                image = previousFrame;
+                stats.reused += 1;
+              } else {
+                image = await session.page.screenshot();
+              }
+              await writeFrame(encoder.child.stdin!, image);
+              signatures.push(signature);
+              previousSignature = signature;
+              previousFrame = image;
+              written += 1;
+              break;
+            } catch (error) {
+              if (options.signal?.aborted) throw new Error("Render cancelled.");
+              if (attempt >= 1) throw error;
+              log.detail(`Frame ${frame} failed, retrying on a fresh page.`);
+              await reopen();
+              previousSignature = null;
+              previousFrame = null;
+            }
+          }
+
+          stats.captured += 1;
+          options.onFrame();
+        }
+
+        encoder.child.stdin?.end();
+        await encoder.done;
+
+        if (written !== frames.length) {
+          throw new Error(`Chunk ${chunk.index} wrote ${written} of ${frames.length} frames.`);
+        }
+        if (key) await writeChunkRecord(config, key, signatures, file);
+      } catch (error) {
+        encoder.child.kill("SIGTERM");
+        throw error;
+      }
+    }
+  } finally {
+    await session.browser.close().catch(() => undefined);
+    if (session.errors.length > 0) {
+      throw new Error(`The page reported an error during capture: ${session.errors.slice(0, 3).join(" ")}`);
+    }
+  }
+};
+
+export type RenderProgress = (progress: number, stage: "rendering" | "encoding") => void;
+
+export type RenderTimings = {
+  captureMs: number;
+  encodeMs: number;
+  frames: number;
+  reusedFrames: number;
+  cachedChunks: number;
+  chunks: number;
+  concurrency: number;
+};
+
+export type RenderOptions = {
+  concurrency?: number;
+  preset?: string;
+  /** Container and codec. Defaults to H.264 in MP4. */
+  format?: VideoFormat;
+  skipUnchangedFrames?: boolean;
+  /** Reuse encoded chunks whose frames still look identical. */
+  cache?: boolean;
+  signal?: AbortSignal;
+  /** Where frames and chunk files are written. Defaults to the generated directory. */
+  workDir?: string;
+  onTimings?: (timings: RenderTimings) => void;
+};
+
+
+
+export const renderMovie = async (
+  origin: string,
+  target: RenderTarget,
+  output: string,
+  config: ResolvedConfig,
+  onProgress?: RenderProgress,
+  options: RenderOptions = {},
+): Promise<string> => {
+  // Both binaries are resolved before a single frame is captured: a download
+  // that starts an hour into a render is a render that failed an hour ago.
+  const ffmpeg = await ffmpegExecutable(config);
+  const browserPath = await browserExecutable(config);
+  // Cached frames belong to the browser that drew them.
+  const renderer = (await resolveBrowser(config))?.version ?? browserPath;
+
+  const requested = Math.max(1, Math.min(options.concurrency ?? config.concurrency ?? defaultConcurrency(), 16));
+  const preset = options.preset ?? config.preset ?? "medium";
+  const format = options.format ?? FORMATS.mp4;
+  // A palette or a still sequence is computed across the whole animation, so
+  // it cannot be assembled from independently encoded chunks. One lane, one
+  // pass: slower, and the only way the output is correct.
+  const chunkable = format.chunked;
+  const skipUnchanged = options.skipUnchangedFrames ?? config.skipUnchangedFrames ?? true;
+  const cache = options.cache ?? config.cacheChunks ?? true;
+
+  // Chunk files live in the project rather than the OS temp directory, so a
+  // killed render leaves something attributable and inspectable behind.
+  const work =
+    options.workDir ??
+    resolve(config.root, config.outDir, "frames", `${target.videoId.split("/").join("-")}-${Date.now().toString(36)}`);
+  await mkdir(work, {recursive: true});
+
+  const concurrency = chunkable ? requested : 1;
+  const {chunks, lanes} = planChunks({
+    durationInFrames: target.durationInFrames,
+    scenes: target.scenes,
+    concurrency,
+  });
+
+  const chunkFile = (chunk: FrameChunk) =>
+    join(work, `chunk-${String(chunk.index).padStart(4, "0")}${chunkable ? format.extension : ".mkv"}`);
+  const stats: CaptureStats = {captured: 0, reused: 0, cachedChunks: 0};
+  let succeeded = false;
+
+  try {
+    await mkdir(dirname(output), {recursive: true});
+
+    const captureStart = performance.now();
+    await Promise.all(
+      lanes.map((lane) =>
+        captureLane(origin, target, config, lane, stats, {
+          skipUnchanged,
+          signal: options.signal,
+          preset,
+          format,
+          ffmpeg,
+          workDir: work,
+          chunkFile,
+          cacheIdentity: cache
+            ? (chunk) => ({
+                videoId: target.videoId,
+                chunk,
+                renderer,
+                format: format.name,
+                width: target.width,
+                height: target.height,
+                fps: target.fps,
+                preset,
+                input: target.input,
+              })
+            : undefined,
+          onFrame: () => onProgress?.(stats.captured / Math.max(1, target.durationInFrames), "rendering"),
+        }),
+      ),
+    );
+    // Encoding happened inside capture, so what remains is joining and sound.
+    const captureMs = performance.now() - captureStart;
+    onProgress?.(1, "encoding");
+
+    const mixInputs: MixInput[] = (target.audio ?? [])
+      .map((cue) => {
+        const file = resolveCueFile(config, cue.src);
+        if (!file) log.warn(`Skipping audio cue ${cue.src}: only project-local files can be encoded.`);
+        return file ? {file, cue} : null;
+      })
+      .filter((item): item is MixInput => item !== null);
+
+    const muxStart = performance.now();
+    const ordered = chunks.map(chunkFile);
+    const silent = join(work, `video${chunkable ? format.extension : ".mkv"}`);
+
+    if (ordered.length === 1) {
+      await copyFile(ordered[0], silent);
+    } else {
+      const list = join(work, "chunks.txt");
+      await writeFile(list, ordered.map((file) => `file '${file.split("'").join("'\\''")}'`).join("\n"), "utf8");
+      await run(ffmpeg, ["-y", "-f", "concat", "-safe", "0", "-i", list, "-c", "copy", silent], options.signal);
+    }
+
+    // A format that cannot be chunked was captured losslessly and is encoded
+    // here in one pass, where a palette or a sequence can see every frame.
+    if (!chunkable) {
+      // A sequence is many files. Given one path it writes beside it, using
+      // the name as the directory, rather than overwriting a single frame 270
+      // times and reporting success.
+      const destination = format.name === "png" && !output.includes("%") ? sequencePattern(output) : output;
+      if (destination !== output) await mkdir(dirname(destination), {recursive: true});
+      await run(ffmpeg, ["-y", "-i", silent, ...format.args(preset), destination], options.signal);
+      if (mixInputs.length > 0) {
+        log.detail(`${format.name} carries no audio track; ${mixInputs.length} cue(s) were not mixed in.`);
+      }
+    } else if (mixInputs.length === 0 || !format.audio) {
+      const faststart = format.extension === ".mp4" || format.extension === ".mov";
+      await run(
+        ffmpeg,
+        ["-y", "-i", silent, "-c", "copy", ...(faststart ? ["-movflags", "+faststart"] : []), output],
+        options.signal,
+      );
+    } else {
+      const {filter, label} = buildAudioFilter(mixInputs, {
+        fps: target.fps,
+        durationInFrames: target.durationInFrames,
+        targetLufs: target.targetLufs ?? -14,
+      });
+      const args = ["-y", "-i", silent];
+      for (const {cue, file} of mixInputs) args.push(...(cue.loop ? ["-stream_loop", "-1"] : []), "-i", file);
+      args.push(
+        "-filter_complex",
+        filter,
+        "-map",
+        "0:v",
+        "-map",
+        label,
+        "-c:v",
+        "copy",
+        // WebM cannot carry AAC; every other container here can.
+        "-c:a",
+        format.extension === ".webm" ? "libopus" : "aac",
+        "-b:a",
+        "192k",
+        "-ar",
+        "48000",
+        "-shortest",
+        ...(format.extension === ".mp4" || format.extension === ".mov" ? ["-movflags", "+faststart"] : []),
+        output,
+      );
+      await run(ffmpeg, args, options.signal);
+    }
+
+    options.onTimings?.({
+      captureMs: Math.round(captureMs),
+      encodeMs: Math.round(performance.now() - muxStart),
+      frames: target.durationInFrames,
+      reusedFrames: stats.reused,
+      cachedChunks: stats.cachedChunks,
+      chunks: chunks.length,
+      concurrency: lanes.length,
+    });
+    succeeded = true;
+    return output;
+  } finally {
+    // Keep the working directory when something went wrong: it is the only
+    // record of which chunks landed.
+    if (succeeded && !options.workDir) await rm(work, {recursive: true, force: true});
+    else if (!succeeded) log.detail(`Chunks left for inspection in ${work}`);
+  }
+};