@odori/cli 0.0.2

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@odori/cli",
+  "version": "0.0.2",
+  "type": "module",
+  "description": "The odori command line: discovery, Studio, component installation, stills, tests, and export jobs.",
+  "license": "Apache-2.0",
+  "bin": {
+    "odori": "./bin/odori.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "studio"
+  ],
+  "dependencies": {
+    "@puppeteer/browsers": "3.2.0",
+    "@vitejs/plugin-react": "5.1.2",
+    "ffmpeg-static": "5.3.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "playwright-core": "1.55.0",
+    "tsx": "4.20.5",
+    "vite": "7.3.0",
+    "odori": "0.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.0",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "19.2.3",
+    "tsup": "^8.5.1",
+    "typescript": "5.9.3",
+    "@odori/registry": "0.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.studio.json",
+    "build": "tsup",
+    "snapshot": "tsx scripts/snapshot.ts",
+    "verify:package": "tsx scripts/verify-package.ts"
+  }
+}

package/src/audio-mix.ts

@@ -0,0 +1,133 @@
+import {existsSync} from "node:fs";
+import {resolve} from "node:path";
+import {duckEnvelope, type ManifestAudioCue, envelopeAtFrame} from "odori";
+import {cueFile} from "./cues";
+import type {ResolvedConfig} from "./config";
+
+export type MixInput = {file: string; cue: ManifestAudioCue};
+
+/**
+ * Resolve a cue source to a local file. Sources are project-relative or
+ * public-relative paths, which is what the dev server and the render worker
+ * both serve.
+ */
+export const resolveCueFile = (config: ResolvedConfig, src: string): string | null => {
+  if (/^https?:\/\//.test(src)) return null;
+  // A generated cue was rendered into the build cache before the mix ran, and
+  // its name carries the hash of the score that produced it.
+  if (src.startsWith("/__odori/cue/")) {
+    const generated = cueFile(config, src);
+    return existsSync(generated) ? generated : null;
+  }
+  const candidates = [
+    resolve(config.root, "public", src.replace(/^\//, "")),
+    resolve(config.root, src.replace(/^\//, "")),
+  ];
+  return candidates.find((candidate) => existsSync(candidate)) ?? null;
+};
+
+/**
+ * Build the FFmpeg audio graph for a track.
+ *
+ * Every cue is trimmed, delayed to its frame, faded, and gained exactly as the
+ * player computes it, then mixed and normalized to the brand's target
+ * loudness. A ducked cue drops only while a non-ducked cue overlaps it, from
+ * the same envelope the player evaluates.
+ */
+/**
+ * Compile a cue's gain and duck envelope into one volume filter.
+ *
+ * The filter runs before `adelay`, so its clock is cue-local seconds. A cue
+ * that is never ducked keeps a constant volume rather than paying for an
+ * expression.
+ */
+export const volumeFilter = (cue: ManifestAudioCue, cues: ManifestAudioCue[], fps: number): string => {
+  // Duck points and authored points are two envelopes over the same window, so
+  // the filter carries every frame either of them turns.
+  const authored = cue.gainPoints ?? [];
+  const frames = [
+    ...new Set([
+      ...duckEnvelope(cue, cues).map((point) => point.frame),
+      ...authored.map((point: {frame: number}) => point.frame),
+    ]),
+  ].sort(
+    (left, right) => left - right,
+  );
+  const duck = duckEnvelope(cue, cues);
+  const points: Array<{seconds: number; value: number}> = frames.map((frame) => ({
+    seconds: (frame - cue.fromFrame) / fps,
+    value: envelopeAtFrame(duck, frame) * (authored.length > 0 ? envelopeAtFrame(authored, frame) : 1) * cue.gain,
+  }));
+  const constant = points.every((point) => point.value === points[0].value);
+  if (constant) return `volume=${(points[0]?.value ?? cue.gain).toFixed(4)}`;
+
+  // Piecewise linear, innermost segment last, matching envelopeAtFrame().
+  let expression = points[points.length - 1].value.toFixed(4);
+  for (let index = points.length - 1; index > 0; index -= 1) {
+    const previous = points[index - 1];
+    const current = points[index];
+    const span = current.seconds - previous.seconds;
+    const segment =
+      span <= 0
+        ? current.value.toFixed(4)
+        : `${previous.value.toFixed(4)}+${(current.value - previous.value).toFixed(4)}*(t-${previous.seconds.toFixed(
+            4,
+          )})/${span.toFixed(4)}`;
+    expression = `if(lt(t,${current.seconds.toFixed(4)}),${segment},${expression})`;
+  }
+  return `volume=volume='${expression}':eval=frame`;
+};
+
+export const buildAudioFilter = (
+  inputs: MixInput[],
+  options: {fps: number; durationInFrames: number; targetLufs: number},
+): {filter: string; label: string} => {
+  const {fps, durationInFrames, targetLufs} = options;
+  const totalSeconds = durationInFrames / fps;
+  const cues = inputs.map(({cue}) => cue);
+  const parts: string[] = [];
+  const labels: string[] = [];
+
+  inputs.forEach(({cue}, index) => {
+    const start = cue.trimStartSeconds;
+    const length = cue.durationInFrames / fps;
+    const delay = Math.round((cue.fromFrame / fps) * 1000);
+    const volume = volumeFilter(cue, cues, fps);
+    const label = `a${index}`;
+    const chain = [
+      // Index 1 is the video input, so audio inputs start at 1.
+      cue.loop ? `aloop=loop=-1:size=2147483647` : null,
+      // Every input is brought to one format before anything else touches it.
+      // Cues are mono, files are usually stereo, and a graph that leaves the
+      // difference to be inferred works on the encoder that happens to be
+      // installed and fails on the pinned one.
+      "aformat=sample_fmts=fltp:sample_rates=48000:channel_layouts=stereo",
+      `atrim=start=${start.toFixed(4)}:duration=${length.toFixed(4)}`,
+      "asetpts=PTS-STARTPTS",
+      cue.fadeInFrames > 0 ? `afade=t=in:st=0:d=${(cue.fadeInFrames / fps).toFixed(4)}` : null,
+      cue.fadeOutFrames > 0
+        ? `afade=t=out:st=${Math.max(0, length - cue.fadeOutFrames / fps).toFixed(4)}:d=${(
+            cue.fadeOutFrames / fps
+          ).toFixed(4)}`
+        : null,
+      volume,
+      delay > 0 ? `adelay=${delay}|${delay}` : null,
+      `apad=whole_dur=${totalSeconds.toFixed(4)}`,
+      `atrim=duration=${totalSeconds.toFixed(4)}`,
+    ]
+      .filter(Boolean)
+      .join(",");
+    parts.push(`[${index + 1}:a]${chain}[${label}]`);
+    labels.push(`[${label}]`);
+  });
+
+  parts.push(
+    `${labels.join("")}amix=inputs=${labels.length}:normalize=0:dropout_transition=0[mixed]`,
+    // loudnorm resamples to its own rate and can drop the layout on the way
+    // out, so the last link states the output format rather than negotiating
+    // it with whatever encoder is downstream.
+    `[mixed]loudnorm=I=${targetLufs}:TP=-1.5:LRA=11,aformat=sample_fmts=fltp:sample_rates=48000:channel_layouts=stereo[audio]`,
+  );
+
+  return {filter: parts.join(";"), label: "[audio]"};
+};

package/src/binaries.ts

@@ -0,0 +1,241 @@
+import {spawn} from "node:child_process";
+import {chmod, mkdir, readFile, writeFile} from "node:fs/promises";
+import {existsSync} from "node:fs";
+import {createRequire} from "node:module";
+import {homedir} from "node:os";
+import {dirname, resolve} from "node:path";
+import {install, computeExecutablePath, Browser, resolveBuildId, detectBrowserPlatform} from "@puppeteer/browsers";
+import {resolveChromePath, type ResolvedConfig} from "./config";
+import {log} from "./log";
+
+/**
+ * The two programs a render actually runs.
+ *
+ * Both are pinned. A video is supposed to be reproducible from its source, and
+ * that promise is only as good as the software that draws and encodes it: a
+ * different Chrome lays out text a fraction differently, and a different
+ * FFmpeg build can be compiled with different defaults. A machine that resolves
+ * "whatever is installed" produces frames that are almost the same, which is
+ * the worst kind of difference — invisible in review, present in the file.
+ *
+ * So Odori manages its own copies, keyed by version, in a cache outside the
+ * project. Local and cloud converge on the same bytes because they download
+ * the same bytes.
+ */
+
+/** Chrome build the runtime is exercised against. Changing it changes frames. */
+export const CHROME_BUILD = "131.0.6778.204";
+
+/** The npm package that carries a static FFmpeg per platform. */
+const FFMPEG_PACKAGE = "ffmpeg-static";
+
+export type BinaryOrigin = "configured" | "environment" | "managed" | "package" | "system";
+
+export type ResolvedBinary = {
+  path: string;
+  origin: BinaryOrigin;
+  /** Pinned version for managed copies; whatever the host has otherwise. */
+  version: string;
+};
+
+/**
+ * Where managed binaries live. Outside the project on purpose: one download
+ * serves every project on the machine, and a `node_modules` wipe does not cost
+ * a 150 MB round trip. `ODORI_CACHE` moves it, which is what a CI cache key or
+ * a Docker layer wants.
+ */
+export const cacheRoot = (): string =>
+  process.env.ODORI_CACHE ?? resolve(process.env.XDG_CACHE_HOME ?? resolve(homedir(), ".cache"), "odori");
+
+const browserCache = () => resolve(cacheRoot(), "browsers");
+const ffmpegCache = () => resolve(cacheRoot(), "ffmpeg", "5.3.0");
+
+const onPath = (command: string, args: string[]): Promise<boolean> =>
+  new Promise((done) => {
+    const child = spawn(command, args, {stdio: "ignore"});
+    child.on("error", () => done(false));
+    child.on("close", (code) => done(code === 0));
+  });
+
+/** The managed Chrome for this platform, whether or not it is downloaded. */
+const managedBrowserPath = (): string | null => {
+  const platform = detectBrowserPlatform();
+  if (!platform) return null;
+  return computeExecutablePath({
+    browser: Browser.CHROMEHEADLESSSHELL,
+    buildId: CHROME_BUILD,
+    cacheDir: browserCache(),
+    platform,
+  });
+};
+
+/**
+ * Chrome, in the order a reader would guess: what the project configured, what
+ * the environment overrode, the managed copy, then whatever the machine has.
+ *
+ * The system fallback is last and deliberate. It keeps a machine that already
+ * has Chrome working with no download, and `odori doctor` says which one was
+ * used so an unexplained difference between two renders has somewhere to start.
+ */
+export const resolveBrowser = async (config: ResolvedConfig): Promise<ResolvedBinary | null> => {
+  if (config.chromePath && existsSync(config.chromePath)) {
+    return {path: config.chromePath, origin: "configured", version: "unknown"};
+  }
+  if (process.env.ODORI_CHROME && existsSync(process.env.ODORI_CHROME)) {
+    return {path: process.env.ODORI_CHROME, origin: "environment", version: "unknown"};
+  }
+  const managed = managedBrowserPath();
+  if (managed && existsSync(managed)) return {path: managed, origin: "managed", version: CHROME_BUILD};
+
+  const system = resolveChromePath();
+  return system ? {path: system, origin: "system", version: "unknown"} : null;
+};
+
+/** The FFmpeg the package manager unpacked, if it ran the package's install. */
+const packagedFfmpeg = (): string | null => {
+  try {
+    const require = createRequire(import.meta.url);
+    const path = require(FFMPEG_PACKAGE) as string | null;
+    return path && existsSync(path) ? path : null;
+  } catch {
+    return null;
+  }
+};
+
+const managedFfmpegPath = () => resolve(ffmpegCache(), process.platform === "win32" ? "ffmpeg.exe" : "ffmpeg");
+
+export const resolveFfmpeg = async (config: ResolvedConfig): Promise<ResolvedBinary | null> => {
+  if (config.ffmpegPath && existsSync(config.ffmpegPath)) {
+    return {path: config.ffmpegPath, origin: "configured", version: "unknown"};
+  }
+  if (process.env.ODORI_FFMPEG && existsSync(process.env.ODORI_FFMPEG)) {
+    return {path: process.env.ODORI_FFMPEG, origin: "environment", version: "unknown"};
+  }
+  const managed = managedFfmpegPath();
+  if (existsSync(managed)) return {path: managed, origin: "managed", version: "5.3.0"};
+
+  const packaged = packagedFfmpeg();
+  if (packaged) return {path: packaged, origin: "package", version: "5.3.0"};
+
+  if (await onPath("ffmpeg", ["-version"])) return {path: "ffmpeg", origin: "system", version: "unknown"};
+  return null;
+};
+
+/**
+ * Download the pinned Chrome if it is not already cached.
+ *
+ * `chrome-headless-shell` rather than full Chrome: it is the build made for
+ * exactly this — rendering frames with no window, no profile, and no updater —
+ * and it is a third of the download.
+ */
+export const installBrowser = async (options: {onProgress?: (fraction: number) => void} = {}): Promise<string> => {
+  const platform = detectBrowserPlatform();
+  if (!platform) {
+    throw new Error(`No managed Chrome build for ${process.platform}/${process.arch}. Set chromePath in odori.config.ts.`);
+  }
+
+  const existing = managedBrowserPath();
+  if (existing && existsSync(existing)) return existing;
+
+  const buildId = await resolveBuildId(Browser.CHROMEHEADLESSSHELL, platform, CHROME_BUILD).catch(() => CHROME_BUILD);
+  const installed = await install({
+    browser: Browser.CHROMEHEADLESSSHELL,
+    buildId,
+    cacheDir: browserCache(),
+    platform,
+    downloadProgressCallback: (downloaded, total) => options.onProgress?.(total ? downloaded / total : 0),
+  });
+  return installed.executablePath;
+};
+
+/**
+ * Download the pinned FFmpeg if it is not already cached.
+ *
+ * The static build is fetched through its own package rather than from a URL
+ * we maintain, so the platform matrix and the checksums stay somebody else's
+ * job. It runs here instead of at install time because package managers now
+ * block install scripts by default, and a binary that only arrives when a
+ * postinstall is allowed is a binary that is missing on half of all machines.
+ */
+export const installFfmpeg = async (): Promise<string> => {
+  const managed = managedFfmpegPath();
+  if (existsSync(managed)) return managed;
+
+  const packaged = packagedFfmpeg();
+  if (packaged) {
+    // Already unpacked by the package manager: copy it into the cache so the
+    // path a manifest records does not depend on a node_modules tree.
+    await mkdir(dirname(managed), {recursive: true});
+    await writeFile(managed, await readFile(packaged));
+    await chmod(managed, 0o755);
+    return managed;
+  }
+
+  const require = createRequire(import.meta.url);
+  const installer = require.resolve(`${FFMPEG_PACKAGE}/install.js`);
+  await mkdir(dirname(managed), {recursive: true});
+
+  await new Promise<void>((done, fail) => {
+    const child = spawn(process.execPath, [installer], {
+      // The package writes to its own directory, which is where it also looks.
+      cwd: dirname(installer),
+      env: {...process.env, FFMPEG_BIN_PATH: managed},
+      stdio: "inherit",
+    });
+    child.on("error", fail);
+    child.on("close", (code) => (code === 0 ? done() : fail(new Error(`FFmpeg download exited with ${code}`))));
+  });
+
+  if (!existsSync(managed)) {
+    const unpacked = packagedFfmpeg();
+    if (!unpacked) throw new Error("FFmpeg downloaded but no binary was produced.");
+    await writeFile(managed, await readFile(unpacked));
+    await chmod(managed, 0o755);
+  }
+  return managed;
+};
+
+/**
+ * What a render will use, as a line of provenance.
+ *
+ * This goes in the manifest. Two renders of the same source that differ are
+ * either a bug or a different toolchain, and without this there is no way to
+ * tell which from the artefacts alone.
+ */
+export const renderToolchain = async (
+  config: ResolvedConfig,
+): Promise<{chrome: string; chromeOrigin: BinaryOrigin | "missing"; ffmpeg: string; ffmpegOrigin: BinaryOrigin | "missing"}> => {
+  const [browser, ffmpeg] = await Promise.all([resolveBrowser(config), resolveFfmpeg(config)]);
+  return {
+    chrome: browser?.version ?? "missing",
+    chromeOrigin: browser?.origin ?? "missing",
+    ffmpeg: ffmpeg?.version ?? "missing",
+    ffmpegOrigin: ffmpeg?.origin ?? "missing",
+  };
+};
+
+/** Fetch everything a render needs, for a Docker layer or a cold CI runner. */
+export const installCommand = async (): Promise<number> => {
+  log.title("odori install");
+
+  let lastReported = -1;
+  const chrome = await installBrowser({
+    onProgress: (fraction) => {
+      const percent = Math.floor(fraction * 100);
+      if (percent >= lastReported + 10) {
+        lastReported = percent;
+        log.progress(`Chrome ${CHROME_BUILD}: ${percent}%`);
+      }
+    },
+  });
+  log.progressDone();
+  log.success(`Chrome ${CHROME_BUILD}`);
+  log.detail(chrome);
+
+  const ffmpeg = await installFfmpeg();
+  log.success("FFmpeg 5.3.0");
+  log.detail(ffmpeg);
+
+  log.detail(`Cached in ${cacheRoot()}. Set ODORI_CACHE to move it.`);
+  return 0;
+};

package/src/brand-file.ts

@@ -0,0 +1,94 @@
+import {readFile, readdir, writeFile} from "node:fs/promises";
+import {existsSync} from "node:fs";
+import {join, relative, resolve} from "node:path";
+import type {ResolvedConfig} from "./config";
+
+export type BrandRegistration = {
+  /** The file that was edited, relative to the project root. */
+  file: string;
+  /** True when the cue was already registered under that name. */
+  already: boolean;
+};
+
+const SOURCE = /\.tsx?$/;
+
+/** Every file under videos/ that defines a brand, nearest the root first. */
+const brandFiles = async (config: ResolvedConfig): Promise<string[]> => {
+  const root = resolve(config.root, config.videosDir);
+  if (!existsSync(root)) return [];
+
+  const found: Array<{file: string; depth: number}> = [];
+  const walk = async (directory: string, depth: number) => {
+    for (const entry of await readdir(directory, {withFileTypes: true})) {
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        // Installed components are not where a brand lives.
+        if (path === resolve(config.root, config.componentsDir)) continue;
+        await walk(path, depth + 1);
+        continue;
+      }
+      if (!SOURCE.test(entry.name)) continue;
+      const source = await readFile(path, "utf8");
+      if (source.includes("defineBrand(")) found.push({file: path, depth});
+    }
+  };
+
+  await walk(root, 0);
+  return found.sort((left, right) => left.depth - right.depth).map((entry) => entry.file);
+};
+
+/**
+ * Register a generated cue in the project's brand.
+ *
+ * A cue that is not in the brand is silent, so installing one and leaving the
+ * wiring to the reader is installing something that does nothing. The edit is
+ * deliberately conservative: it only touches a file that already has an
+ * `audio: {cues: {` block, and it reports what it could not do rather than
+ * rewriting source it does not understand.
+ */
+export const registerCueInBrand = async (
+  config: ResolvedConfig,
+  cue: {name: string; export: string},
+  componentName: string,
+): Promise<BrandRegistration | null> => {
+  for (const file of await brandFiles(config)) {
+    const source = await readFile(file, "utf8");
+    if (source.includes(`"${cue.name}"`) || source.includes(`'${cue.name}'`)) {
+      return {file: relative(config.root, file), already: true};
+    }
+
+    // Two shapes, because both are written by hand and one of them is written
+    // by our own scaffold: a block spread over lines, and `cues: {}` inline.
+    const block = source.match(/(audio:\s*\{[\s\S]*?cues:\s*\{)([\s\S]*?)(\n(\s*)\},)/);
+    const inline = source.match(/(audio:\s*\{[^\n}]*cues:\s*\{)([^\n{}]*)(\})/);
+
+    let withCue: string;
+    if (block) {
+      const indent = `${block[4]}  `;
+      const entry = `\n${indent}"${cue.name}": ${cue.export}(),`;
+      withCue = source.replace(block[0], `${block[1]}${block[2]}${entry}${block[3]}`);
+    } else if (inline) {
+      // An inline block grows in place rather than being reformatted: this
+      // edits somebody's source, and reflowing their file is not the job.
+      const existing = inline[2].trim();
+      const entry = `"${cue.name}": ${cue.export}()`;
+      withCue = source.replace(inline[0], `${inline[1]}${existing ? `${existing.replace(/,$/, "")}, ` : ""}${entry}${inline[3]}`);
+    } else {
+      continue;
+    }
+
+    // The import path is relative to the brand file, which is usually the
+    // layout beside videos/components.
+    const from = resolve(config.root, config.componentsDir, componentName, componentName);
+    const specifier = relative(resolve(file, ".."), from).split("\\").join("/");
+    const importLine = `import {${cue.export}} from "${specifier.startsWith(".") ? specifier : `./${specifier}`}";`;
+    const withImport = withCue.includes(importLine)
+      ? withCue
+      : withCue.replace(/^(import [\s\S]*?;\n)/, `$1${importLine}\n`);
+
+    await writeFile(file, withImport, "utf8");
+    return {file: relative(config.root, file), already: false};
+  }
+
+  return null;
+};

package/src/chunk-cache.ts

@@ -0,0 +1,85 @@
+import {existsSync} from "node:fs";
+import {copyFile, mkdir, readFile, writeFile} from "node:fs/promises";
+import {join, resolve} from "node:path";
+import {hashValue} from "odori";
+import type {ResolvedConfig} from "./config";
+import type {FrameChunk} from "./chunks";
+
+export type ChunkIdentity = {
+  videoId: string;
+  chunk: FrameChunk;
+  width: number;
+  height: number;
+  fps: number;
+  preset: string;
+  /** The browser build that captured the frames. See `chunkKey`. */
+  renderer?: string;
+  /** The codec the chunk was encoded with, which decides what it can join. */
+  format?: string;
+  input?: Record<string, unknown>;
+};
+
+export type ChunkRecord = {key: string; signatures: string[]; createdAt: string};
+
+const cacheDir = (config: ResolvedConfig) => resolve(config.root, config.outDir, "cache", "chunks");
+
+/**
+ * A cache key identifies the slot, not the content.
+ *
+ * Hashing the project source would invalidate every chunk on any edit, which
+ * defeats the purpose. Instead the key covers what decides where a chunk sits
+ * and how it is encoded, and the recorded per-frame signatures decide whether
+ * the pictures are still the same.
+ */
+export const chunkKey = (identity: ChunkIdentity): string =>
+  hashValue({
+    videoId: identity.videoId,
+    // The browser that drew the frames is part of what the frames are. Without
+    // it, upgrading Chrome silently reuses pixels the new build would not have
+    // produced, which is the exact drift the pinned toolchain exists to stop.
+    renderer: identity.renderer ?? null,
+    // A chunk is an encoded file, not a bag of frames: H.264 chunks cannot be
+    // copied into a WebM, so a cache that ignored the codec would hand the
+    // muxer streams it cannot write.
+    format: identity.format ?? null,
+    sceneId: identity.chunk.sceneId ?? null,
+    start: identity.chunk.start,
+    end: identity.chunk.end,
+    width: identity.width,
+    height: identity.height,
+    fps: identity.fps,
+    preset: identity.preset,
+    input: identity.input ?? null,
+  });
+
+export const readChunkRecord = async (config: ResolvedConfig, key: string): Promise<ChunkRecord | null> => {
+  const meta = join(cacheDir(config), `${key}.json`);
+  const media = join(cacheDir(config), `${key}.mp4`);
+  if (!existsSync(meta) || !existsSync(media)) return null;
+  try {
+    return JSON.parse(await readFile(meta, "utf8")) as ChunkRecord;
+  } catch {
+    return null;
+  }
+};
+
+/** Copy a cached chunk into a render's working directory. */
+export const useChunkRecord = async (config: ResolvedConfig, key: string, destination: string): Promise<void> => {
+  await copyFile(join(cacheDir(config), `${key}.mp4`), destination);
+};
+
+export const writeChunkRecord = async (
+  config: ResolvedConfig,
+  key: string,
+  signatures: string[],
+  file: string,
+): Promise<void> => {
+  const directory = cacheDir(config);
+  await mkdir(directory, {recursive: true});
+  await copyFile(file, join(directory, `${key}.mp4`));
+  const record: ChunkRecord = {key, signatures, createdAt: new Date().toISOString()};
+  await writeFile(join(directory, `${key}.json`), `${JSON.stringify(record)}\n`, "utf8");
+};
+
+export const signaturesMatch = (recorded: string[], observed: string[]): boolean =>
+  recorded.length === observed.length && recorded.every((signature, index) => signature === observed[index]);

package/src/chunks.ts

@@ -0,0 +1,78 @@
+export type FrameChunk = {index: number; start: number; end: number; sceneId?: string};
+
+export type ChunkPlan = {chunks: FrameChunk[]; lanes: FrameChunk[][]};
+
+export type PlanOptions = {
+  durationInFrames: number;
+  scenes?: Array<{id: string; start: number; durationInFrames: number}>;
+  concurrency: number;
+  /** Scenes longer than this are split so one long scene cannot own a worker. */
+  maxChunkFrames?: number;
+};
+
+const length = (chunk: FrameChunk) => chunk.end - chunk.start + 1;
+
+/**
+ * Split a timeline into contiguous chunks, then deal them out to workers.
+ *
+ * Chunks follow scene boundaries because a scene is the unit the runtime
+ * already names, which is what lets a chunk be encoded on its own, cached, or
+ * rendered on another machine. Long scenes are split so a single expensive
+ * scene cannot pin one worker while the others idle.
+ */
+export const planChunks = ({
+  durationInFrames,
+  scenes = [],
+  concurrency,
+  maxChunkFrames = 120,
+}: PlanOptions): ChunkPlan => {
+  if (durationInFrames <= 0) return {chunks: [], lanes: []};
+
+  const bounded = Math.max(1, Math.min(concurrency, durationInFrames));
+  const ordered = [...scenes]
+    .filter((scene) => scene.durationInFrames > 0)
+    .sort((left, right) => left.start - right.start);
+
+  const spans: Array<{start: number; end: number; sceneId?: string}> = [];
+  let cursor = 0;
+  for (const scene of ordered) {
+    if (scene.start > cursor) spans.push({start: cursor, end: scene.start - 1});
+    const end = Math.min(durationInFrames - 1, scene.start + scene.durationInFrames - 1);
+    if (end >= scene.start) spans.push({start: scene.start, end, sceneId: scene.id});
+    cursor = end + 1;
+  }
+  if (cursor < durationInFrames) spans.push({start: cursor, end: durationInFrames - 1});
+
+  const chunks: FrameChunk[] = [];
+  for (const span of spans) {
+    // Aim for at least one chunk per worker, so parallelism is not wasted on a
+    // timeline made of one long scene.
+    const target = Math.max(1, Math.min(maxChunkFrames, Math.ceil(durationInFrames / bounded)));
+    const total = span.end - span.start + 1;
+    const pieces = Math.max(1, Math.ceil(total / target));
+    const size = Math.ceil(total / pieces);
+    for (let piece = 0; piece < pieces; piece += 1) {
+      const start = span.start + piece * size;
+      const end = Math.min(span.end, start + size - 1);
+      if (start > end) continue;
+      chunks.push({index: chunks.length, start, end, sceneId: span.sceneId});
+    }
+  }
+
+  // Longest chunk first into the least loaded lane. Simple, and it keeps the
+  // slowest worker close to the average when scene costs differ.
+  const lanes: FrameChunk[][] = Array.from({length: bounded}, () => []);
+  const loads = new Array<number>(bounded).fill(0);
+  for (const chunk of [...chunks].sort((left, right) => length(right) - length(left))) {
+    let lane = 0;
+    for (let index = 1; index < bounded; index += 1) if (loads[index] < loads[lane]) lane = index;
+    lanes[lane].push(chunk);
+    loads[lane] += length(chunk);
+  }
+
+  for (const lane of lanes) lane.sort((left, right) => left.start - right.start);
+  return {chunks, lanes: lanes.filter((lane) => lane.length > 0)};
+};
+
+export const chunkFrames = (chunk: FrameChunk): number[] =>
+  Array.from({length: length(chunk)}, (_, offset) => chunk.start + offset);