@vibeo/renderer 0.1.0

package/src/frame-range.ts

@@ -0,0 +1,81 @@
+import type { FrameRange } from "./types.js";
+
+/**
+ * Parse a frame range string like "10-50" or "25" into a [start, end] tuple.
+ * Returns null if the input is null or empty.
+ */
+export function parseFrameRange(
+  input: string | null,
+  durationInFrames: number,
+): FrameRange | null {
+  if (input === null || input.trim() === "") {
+    return null;
+  }
+
+  const trimmed = input.trim();
+
+  if (trimmed.includes("-")) {
+    const [startStr, endStr] = trimmed.split("-");
+    const start = parseInt(startStr!, 10);
+    const end = parseInt(endStr!, 10);
+
+    if (isNaN(start) || isNaN(end)) {
+      throw new Error(`Invalid frame range: "${input}". Expected format: "start-end"`);
+    }
+
+    validateFrameRange([start, end], durationInFrames);
+    return [start, end];
+  }
+
+  const singleFrame = parseInt(trimmed, 10);
+  if (isNaN(singleFrame)) {
+    throw new Error(`Invalid frame range: "${input}". Expected a number or "start-end"`);
+  }
+
+  validateFrameRange([singleFrame, singleFrame], durationInFrames);
+  return [singleFrame, singleFrame];
+}
+
+/**
+ * Get the real frame range to render, accounting for optional user-specified range.
+ */
+export function getRealFrameRange(
+  durationInFrames: number,
+  frameRange: FrameRange | null,
+): FrameRange {
+  if (frameRange === null) {
+    return [0, durationInFrames - 1];
+  }
+  return frameRange;
+}
+
+/**
+ * Validate that a frame range is within bounds and well-formed.
+ */
+export function validateFrameRange(
+  range: FrameRange,
+  durationInFrames: number,
+): void {
+  const [start, end] = range;
+
+  if (!Number.isInteger(start) || !Number.isInteger(end)) {
+    throw new Error(`Frame range values must be integers. Got [${start}, ${end}]`);
+  }
+
+  if (start < 0) {
+    throw new Error(`Frame range start must be >= 0. Got ${start}`);
+  }
+
+  if (end < start) {
+    throw new Error(
+      `Frame range end (${end}) must be >= start (${start})`,
+    );
+  }
+
+  if (end >= durationInFrames) {
+    throw new Error(
+      `Frame range end (${end}) exceeds duration (${durationInFrames} frames). ` +
+        `Max allowed end frame is ${durationInFrames - 1}`,
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+// Types
+export type {
+  RenderConfig,
+  RenderProgress,
+  Codec,
+  ImageFormat,
+  FrameRange,
+  StitchOptions,
+  AudioMuxOptions,
+  BundleResult,
+} from "./types.js";
+
+// Browser lifecycle
+export { launchBrowser, closeBrowser, createPage } from "./browser.js";
+
+// Bundler
+export { bundle } from "./bundler.js";
+
+// Frame navigation
+export { seekToFrame, loadBundle } from "./seek-to-frame.js";
+
+// Frame capture
+export { captureFrame } from "./capture-frame.js";
+
+// Frame range utilities
+export { parseFrameRange, getRealFrameRange, validateFrameRange } from "./frame-range.js";
+
+// FFmpeg stitching
+export { stitchFrames, getContainerExt } from "./stitch-frames.js";
+export { stitchAudio } from "./stitch-audio.js";
+
+// Parallel rendering
+export { parallelRender } from "./parallel-render.js";
+
+// Full render orchestration
+export { renderComposition } from "./render-composition.js";

package/src/parallel-render.ts

@@ -0,0 +1,134 @@
+import type { Browser } from "playwright";
+import type { FrameRange, ImageFormat, RenderProgress } from "./types.js";
+import { createPage } from "./browser.js";
+import { seekToFrame, loadBundle } from "./seek-to-frame.js";
+import { captureFrame } from "./capture-frame.js";
+
+interface ParallelRenderOptions {
+  browser: Browser;
+  bundleUrl: string;
+  compositionId: string;
+  frameRange: FrameRange;
+  outputDir: string;
+  width: number;
+  height: number;
+  concurrency: number;
+  imageFormat: ImageFormat;
+  quality?: number;
+  onProgress?: (progress: RenderProgress) => void;
+}
+
+/**
+ * Split a frame range into N roughly-equal chunks.
+ */
+function splitFrameRange(range: FrameRange, chunks: number): FrameRange[] {
+  const [start, end] = range;
+  const totalFrames = end - start + 1;
+  const framesPerChunk = Math.ceil(totalFrames / chunks);
+  const ranges: FrameRange[] = [];
+
+  for (let i = 0; i < chunks; i++) {
+    const chunkStart = start + i * framesPerChunk;
+    const chunkEnd = Math.min(chunkStart + framesPerChunk - 1, end);
+    if (chunkStart > end) break;
+    ranges.push([chunkStart, chunkEnd]);
+  }
+
+  return ranges;
+}
+
+/**
+ * Render a chunk of frames using a single browser page.
+ */
+async function renderChunk(
+  browser: Browser,
+  bundleUrl: string,
+  compositionId: string,
+  frameRange: FrameRange,
+  outputDir: string,
+  width: number,
+  height: number,
+  imageFormat: ImageFormat,
+  quality: number | undefined,
+  onFrameRendered: () => void,
+): Promise<void> {
+  const page = await createPage(browser, width, height);
+
+  try {
+    await loadBundle(page, bundleUrl);
+
+    const [start, end] = frameRange;
+    for (let frame = start; frame <= end; frame++) {
+      await seekToFrame(page, frame, compositionId);
+      await captureFrame(page, outputDir, frame, { imageFormat, quality });
+      onFrameRendered();
+    }
+  } finally {
+    await page.close();
+  }
+}
+
+/**
+ * Distribute frame rendering across multiple browser tabs in parallel.
+ * Opens N pages, each rendering a chunk of the frame range.
+ */
+export async function parallelRender(
+  options: ParallelRenderOptions,
+): Promise<void> {
+  const {
+    browser,
+    bundleUrl,
+    compositionId,
+    frameRange,
+    outputDir,
+    width,
+    height,
+    concurrency,
+    imageFormat,
+    quality,
+    onProgress,
+  } = options;
+
+  const [start, end] = frameRange;
+  const totalFrames = end - start + 1;
+  const effectiveConcurrency = Math.min(concurrency, totalFrames);
+  const chunks = splitFrameRange(frameRange, effectiveConcurrency);
+
+  let framesRendered = 0;
+  const startTime = Date.now();
+
+  const onFrameRendered = () => {
+    framesRendered++;
+    if (onProgress) {
+      const elapsed = Date.now() - startTime;
+      const msPerFrame = elapsed / framesRendered;
+      const remaining = totalFrames - framesRendered;
+      const etaMs = remaining > 0 ? msPerFrame * remaining : 0;
+
+      onProgress({
+        framesRendered,
+        totalFrames,
+        percent: framesRendered / totalFrames,
+        etaMs: framesRendered > 0 ? etaMs : null,
+      });
+    }
+  };
+
+  // Render all chunks in parallel
+  await Promise.all(
+    chunks.map((chunk) =>
+      renderChunk(
+        browser,
+        bundleUrl,
+        compositionId,
+        chunk,
+        outputDir,
+        width,
+        height,
+        imageFormat,
+        quality,
+        onFrameRendered,
+      ),
+    ),
+  );
+}

package/src/render-composition.ts

@@ -0,0 +1,144 @@
+import { mkdtemp, rm, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { availableParallelism } from "node:os";
+import type { RenderConfig, RenderProgress } from "./types.js";
+import { bundle } from "./bundler.js";
+import { launchBrowser, closeBrowser } from "./browser.js";
+import { getRealFrameRange } from "./frame-range.js";
+import { parallelRender } from "./parallel-render.js";
+import { stitchFrames } from "./stitch-frames.js";
+import { stitchAudio } from "./stitch-audio.js";
+
+interface CompositionInfo {
+  width: number;
+  height: number;
+  fps: number;
+  durationInFrames: number;
+}
+
+/**
+ * Orchestrate a full composition render:
+ * 1. Bundle the entry point
+ * 2. Launch headless browser
+ * 3. Render frames in parallel across browser tabs
+ * 4. Stitch frames into video with FFmpeg
+ * 5. Mux audio if present
+ * 6. Cleanup temp files
+ */
+export async function renderComposition(
+  config: RenderConfig,
+  compositionInfo: CompositionInfo,
+): Promise<string> {
+  const {
+    entry,
+    compositionId,
+    outputPath,
+    codec,
+    imageFormat,
+    quality,
+    frameRange: userFrameRange,
+    concurrency,
+    pixelFormat,
+    onProgress,
+  } = config;
+
+  const fps = config.fps ?? compositionInfo.fps;
+  const { width, height, durationInFrames } = compositionInfo;
+
+  const frameRange = getRealFrameRange(durationInFrames, userFrameRange);
+  const totalFrames = frameRange[1] - frameRange[0] + 1;
+
+  // Create temp directories
+  const framesDir = await mkdtemp(join(tmpdir(), "vibeo-frames-"));
+
+  // Ensure output directory exists
+  await mkdir(dirname(outputPath), { recursive: true });
+
+  let bundleResult: Awaited<ReturnType<typeof bundle>> | null = null;
+
+  try {
+    // Step 1: Bundle
+    const reportStage = (stage: string) => {
+      if (onProgress) {
+        onProgress({
+          framesRendered: 0,
+          totalFrames,
+          percent: 0,
+          etaMs: null,
+        });
+      }
+    };
+
+    reportStage("bundling");
+    bundleResult = await bundle(entry);
+
+    // Step 2: Launch browser
+    reportStage("launching browser");
+    const browser = await launchBrowser();
+
+    // Step 3: Render frames in parallel
+    const effectiveConcurrency =
+      concurrency > 0 ? concurrency : Math.max(1, Math.floor(availableParallelism() / 2));
+
+    await parallelRender({
+      browser,
+      bundleUrl: bundleResult.url,
+      compositionId,
+      frameRange,
+      outputDir: framesDir,
+      width,
+      height,
+      concurrency: effectiveConcurrency,
+      imageFormat,
+      quality,
+      onProgress,
+    });
+
+    // Step 4: Stitch frames into video
+    const videoPath = join(
+      framesDir,
+      `stitched.${codec === "vp9" ? "webm" : codec === "prores" ? "mov" : "mp4"}`,
+    );
+
+    await stitchFrames({
+      framesDir,
+      outputPath: videoPath,
+      fps,
+      codec,
+      imageFormat,
+      pixelFormat,
+      quality,
+      width,
+      height,
+    });
+
+    // Step 5: Mux audio (if audio assets exist)
+    // For now, just copy the video to the output path if no audio
+    // Audio assets would be collected from the composition at render time
+    const finalPath = await stitchAudio({
+      videoPath,
+      audioPaths: [], // Audio collection will be implemented per-composition
+      outputPath,
+    });
+
+    // Report completion
+    if (onProgress) {
+      onProgress({
+        framesRendered: totalFrames,
+        totalFrames,
+        percent: 1,
+        etaMs: 0,
+      });
+    }
+
+    return finalPath;
+  } finally {
+    // Step 6: Cleanup
+    await closeBrowser();
+    if (bundleResult) {
+      await bundleResult.cleanup();
+    }
+    await rm(framesDir, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/src/seek-to-frame.ts

@@ -0,0 +1,89 @@
+import type { Page } from "playwright";
+
+/**
+ * Navigate the headless browser page to render a specific frame.
+ *
+ * 1. Call window.vibeo_setFrame(frame, compositionId) to update the React tree.
+ * 2. Wait for React render to complete (poll for window.vibeo_ready flag).
+ * 3. Wait for all fonts to load.
+ * 4. Wait for any pending delayRender handles to resolve.
+ */
+export async function seekToFrame(
+  page: Page,
+  frame: number,
+  compositionId: string,
+): Promise<void> {
+  // Set the frame via the global bridge function
+  await page.evaluate(
+    ({ frame, compositionId }) => {
+      const win = window as typeof window & {
+        vibeo_setFrame?: (frame: number, compositionId: string) => void;
+      };
+      if (typeof win.vibeo_setFrame === "function") {
+        win.vibeo_setFrame(frame, compositionId);
+      } else {
+        throw new Error(
+          "window.vibeo_setFrame is not defined. " +
+            "Make sure the bundle registers this function.",
+        );
+      }
+    },
+    { frame, compositionId },
+  );
+
+  // Wait for React to finish rendering and all delays to resolve
+  await page.evaluate(() => {
+    return new Promise<void>((resolve, reject) => {
+      const timeout = 30_000;
+      const start = Date.now();
+
+      function poll() {
+        const win = window as typeof window & {
+          vibeo_ready?: boolean;
+          vibeo_pendingDelays?: number;
+        };
+
+        if (Date.now() - start > timeout) {
+          reject(new Error("Timed out waiting for frame render"));
+          return;
+        }
+
+        const ready = win.vibeo_ready === true;
+        const noPendingDelays =
+          win.vibeo_pendingDelays === undefined || win.vibeo_pendingDelays === 0;
+
+        if (ready && noPendingDelays) {
+          resolve();
+        } else {
+          requestAnimationFrame(poll);
+        }
+      }
+
+      poll();
+    });
+  });
+
+  // Wait for all fonts to be ready
+  await page.evaluate(() => document.fonts.ready);
+}
+
+/**
+ * Load the bundled app in the browser page.
+ */
+export async function loadBundle(
+  page: Page,
+  url: string,
+): Promise<void> {
+  await page.goto(url, { waitUntil: "networkidle" });
+
+  // Wait for the vibeo_setFrame bridge to be available
+  await page.waitForFunction(
+    () => {
+      const win = window as typeof window & {
+        vibeo_setFrame?: unknown;
+      };
+      return typeof win.vibeo_setFrame === "function";
+    },
+    { timeout: 30_000 },
+  );
+}

package/src/stitch-audio.ts

@@ -0,0 +1,79 @@
+import { spawn } from "node:child_process";
+import type { AudioMuxOptions } from "./types.js";
+
+/**
+ * Mux audio tracks into a video file using FFmpeg.
+ * If multiple audio files are provided, they are mixed together.
+ */
+export async function stitchAudio(options: AudioMuxOptions): Promise<string> {
+  const { videoPath, audioPaths, outputPath } = options;
+
+  if (audioPaths.length === 0) {
+    // No audio to mux — just copy the video
+    return videoPath;
+  }
+
+  const args: string[] = ["-y"];
+
+  // Input: video
+  args.push("-i", videoPath);
+
+  // Input: each audio track
+  for (const audioPath of audioPaths) {
+    args.push("-i", audioPath);
+  }
+
+  if (audioPaths.length === 1) {
+    // Simple case: one audio track, just mux
+    args.push(
+      "-c:v", "copy",
+      "-c:a", "aac",
+      "-b:a", "192k",
+      "-shortest",
+      outputPath,
+    );
+  } else {
+    // Multiple audio tracks: use amix filter to mix them
+    const filterInputs = audioPaths.map((_, i) => `[${i + 1}:a]`).join("");
+    const filter = `${filterInputs}amix=inputs=${audioPaths.length}:duration=longest:dropout_transition=0[aout]`;
+
+    args.push(
+      "-filter_complex", filter,
+      "-map", "0:v",
+      "-map", "[aout]",
+      "-c:v", "copy",
+      "-c:a", "aac",
+      "-b:a", "192k",
+      "-shortest",
+      outputPath,
+    );
+  }
+
+  return runFfmpeg(args);
+}
+
+function runFfmpeg(args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("ffmpeg", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stderr = "";
+
+    proc.stderr.on("data", (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    proc.on("close", (code) => {
+      if (code === 0) {
+        resolve(args[args.length - 1]!);
+      } else {
+        reject(new Error(`FFmpeg exited with code ${code}:\n${stderr}`));
+      }
+    });
+
+    proc.on("error", (err) => {
+      reject(new Error(`Failed to spawn FFmpeg: ${err.message}`));
+    });
+  });
+}

package/src/stitch-frames.ts

@@ -0,0 +1,95 @@
+import { spawn } from "node:child_process";
+import type { StitchOptions } from "./types.js";
+
+/**
+ * Get the FFmpeg codec arguments for the given codec.
+ */
+function getCodecArgs(codec: string, quality: number): string[] {
+  switch (codec) {
+    case "h264":
+      return ["-c:v", "libx264", "-crf", String(quality), "-preset", "fast", "-pix_fmt", "yuv420p"];
+    case "h265":
+      return ["-c:v", "libx265", "-crf", String(quality), "-preset", "fast", "-pix_fmt", "yuv420p"];
+    case "vp9":
+      return ["-c:v", "libvpx-vp9", "-crf", String(quality), "-b:v", "0", "-pix_fmt", "yuv420p"];
+    case "prores":
+      return ["-c:v", "prores_ks", "-profile:v", String(Math.min(quality, 5)), "-pix_fmt", "yuva444p10le"];
+    default:
+      throw new Error(`Unsupported codec: ${codec}`);
+  }
+}
+
+/**
+ * Get the output container format for the given codec.
+ */
+function getContainerExt(codec: string): string {
+  switch (codec) {
+    case "vp9":
+      return "webm";
+    case "prores":
+      return "mov";
+    default:
+      return "mp4";
+  }
+}
+
+/**
+ * Stitch a sequence of frame images into a video using FFmpeg.
+ */
+export async function stitchFrames(options: StitchOptions): Promise<string> {
+  const {
+    framesDir,
+    outputPath,
+    fps,
+    codec,
+    imageFormat,
+    quality,
+  } = options;
+
+  const ext = imageFormat === "jpeg" ? "jpg" : "png";
+  const inputPattern = `${framesDir}/frame-%06d.${ext}`;
+  const codecArgs = getCodecArgs(codec, quality);
+
+  const args = [
+    "-y",
+    "-framerate", String(fps),
+    "-i", inputPattern,
+    ...codecArgs,
+    "-r", String(fps),
+    outputPath,
+  ];
+
+  return runFfmpeg(args);
+}
+
+/**
+ * Run an FFmpeg command and return the output path.
+ */
+function runFfmpeg(args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("ffmpeg", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stderr = "";
+
+    proc.stderr.on("data", (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    proc.on("close", (code) => {
+      if (code === 0) {
+        // The output path is the last argument
+        resolve(args[args.length - 1]!);
+      } else {
+        reject(new Error(`FFmpeg exited with code ${code}:\n${stderr}`));
+      }
+    });
+
+    proc.on("error", (err) => {
+      reject(new Error(`Failed to spawn FFmpeg: ${err.message}`));
+    });
+  });
+}
+
+export { getContainerExt };