@hyperframes/engine 0.1.0

package/src/services/videoFrameInjector.ts

@@ -0,0 +1,113 @@
+/**
+ * Video Frame Injector
+ *
+ * Creates a BeforeCaptureHook that replaces native <video> elements with
+ * pre-extracted frame images during rendering. This is the Hyperframes-specific
+ * video handling strategy — OSS users with different video pipelines can
+ * provide their own hook or skip video injection entirely.
+ */
+
+import { type Page } from "puppeteer-core";
+import { promises as fs } from "fs";
+import { type FrameLookupTable } from "./videoFrameExtractor.js";
+import { injectVideoFramesBatch, syncVideoFrameVisibility } from "./screenshotService.js";
+import { type BeforeCaptureHook } from "./frameCapture.js";
+import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
+
+function createFrameDataUriCache(cacheLimit: number) {
+  const cache = new Map<string, string>();
+  const inFlight = new Map<string, Promise<string>>();
+
+  function remember(framePath: string, dataUri: string): string {
+    if (cache.has(framePath)) {
+      cache.delete(framePath);
+    }
+    cache.set(framePath, dataUri);
+    if (cache.size > cacheLimit) {
+      const oldestKey = cache.keys().next().value;
+      if (oldestKey) {
+        cache.delete(oldestKey);
+      }
+    }
+    return dataUri;
+  }
+
+  async function get(framePath: string): Promise<string> {
+    const cached = cache.get(framePath);
+    if (cached) {
+      remember(framePath, cached);
+      return cached;
+    }
+
+    const existing = inFlight.get(framePath);
+    if (existing) {
+      return existing;
+    }
+
+    const pending = fs
+      .readFile(framePath)
+      .then((frameData) => {
+        const mimeType = framePath.endsWith(".png") ? "image/png" : "image/jpeg";
+        const dataUri = `data:${mimeType};base64,${frameData.toString("base64")}`;
+        return remember(framePath, dataUri);
+      })
+      .finally(() => {
+        inFlight.delete(framePath);
+      });
+    inFlight.set(framePath, pending);
+    return pending;
+  }
+
+  return { get };
+}
+
+/**
+ * Creates a BeforeCaptureHook that injects pre-extracted video frames
+ * into the page, replacing native <video> elements with frame images.
+ */
+export function createVideoFrameInjector(
+  frameLookup: FrameLookupTable | null,
+  config?: Partial<Pick<EngineConfig, "frameDataUriCacheLimit">>,
+): BeforeCaptureHook | null {
+  if (!frameLookup) return null;
+
+  const cacheLimit = Math.max(32, config?.frameDataUriCacheLimit ?? DEFAULT_CONFIG.frameDataUriCacheLimit);
+  const frameCache = createFrameDataUriCache(cacheLimit);
+  const lastInjectedFrameByVideo = new Map<string, number>();
+
+  return async (page: Page, time: number) => {
+    const activePayloads = frameLookup.getActiveFramePayloads(time);
+
+    const updates: Array<{ videoId: string; dataUri: string; frameIndex: number }> = [];
+    const activeIds = new Set<string>();
+    if (activePayloads.size > 0) {
+      const pendingReads: Array<Promise<{ videoId: string; dataUri: string; frameIndex: number }>> = [];
+      for (const [videoId, payload] of activePayloads) {
+        activeIds.add(videoId);
+        const lastFrameIndex = lastInjectedFrameByVideo.get(videoId);
+        if (lastFrameIndex === payload.frameIndex) continue;
+        pendingReads.push(
+          frameCache.get(payload.framePath).then((dataUri) => ({ videoId, dataUri, frameIndex: payload.frameIndex })),
+        );
+      }
+      updates.push(...(await Promise.all(pendingReads)));
+    }
+
+    for (const videoId of Array.from(lastInjectedFrameByVideo.keys())) {
+      if (!activeIds.has(videoId)) {
+        lastInjectedFrameByVideo.delete(videoId);
+      }
+    }
+
+    await syncVideoFrameVisibility(page, Array.from(activeIds));
+    if (updates.length > 0) {
+      await injectVideoFramesBatch(
+        page,
+        updates.map((u) => ({ videoId: u.videoId, dataUri: u.dataUri })),
+      );
+      for (const update of updates) {
+        lastInjectedFrameByVideo.set(update.videoId, update.frameIndex);
+      }
+    }
+  };
+}

package/src/types.ts

@@ -0,0 +1,91 @@
+/**
+ * @hyperframes/engine — Protocol Types
+ *
+ * The engine's page contract. Any web page that wants to be rendered
+ * as video must expose `window.__hf` implementing the HfProtocol interface.
+ */
+
+// ── Seek Protocol ──────────────────────────────────────────────────────────────
+
+/**
+ * Declares a media element the engine should handle.
+ *
+ * Headless Chrome in BeginFrame mode cannot play <video> or produce audio.
+ * The engine pre-extracts video frames and audio tracks from declared media
+ * elements and handles injection/mixing automatically.
+ */
+export interface HfMediaElement {
+  /** DOM id of the <video> or <audio> element */
+  elementId: string;
+  /** Source file path or URL */
+  src: string;
+  /** When in the composition this element appears (seconds) */
+  startTime: number;
+  /** When in the composition this element disappears (seconds) */
+  endTime: number;
+  /** Offset into the source file (seconds, default: 0) */
+  mediaOffset?: number;
+  /** Audio volume 0-1 (default: 1) */
+  volume?: number;
+  /** Whether this element has audio that should be extracted */
+  hasAudio?: boolean;
+}
+
+/**
+ * The seek protocol. The only contract between the engine and a page.
+ *
+ * The engine reads `duration` to calculate total frames, calls `seek(time)`
+ * before each frame capture, and uses `media` (if provided) to handle
+ * video frame injection and audio mixing.
+ *
+ * The engine does NOT care what animation framework drives the page.
+ * GSAP, Framer Motion, CSS animations, Three.js — anything works as long
+ * as `seek()` produces deterministic visual output for a given time.
+ */
+export interface HfProtocol {
+  /** Total duration of the composition in seconds */
+  duration: number;
+  /** Seek to a specific time. Must produce deterministic visual output. */
+  seek(time: number): void;
+  /** Optional: media elements the engine should handle */
+  media?: HfMediaElement[];
+}
+
+// ── Capture Types ──────────────────────────────────────────────────────────────
+
+export interface CaptureOptions {
+  width: number;
+  height: number;
+  fps: number;
+  format?: "jpeg" | "png";
+  quality?: number;
+  deviceScaleFactor?: number;
+}
+
+export interface CaptureResult {
+  frameIndex: number;
+  time: number;
+  path: string;
+  captureTimeMs: number;
+}
+
+export interface CaptureBufferResult {
+  buffer: Buffer;
+  captureTimeMs: number;
+}
+
+export interface CapturePerfSummary {
+  frames: number;
+  avgTotalMs: number;
+  avgSeekMs: number;
+  avgBeforeCaptureMs: number;
+  avgScreenshotMs: number;
+}
+
+// ── Global Augmentation ────────────────────────────────────────────────────────
+
+declare global {
+  interface Window {
+    __hf?: HfProtocol;
+  }
+}

package/src/utils/ffprobe.ts

@@ -0,0 +1,192 @@
+import { spawn } from "child_process";
+
+const videoMetadataCache = new Map<string, Promise<VideoMetadata>>();
+const audioMetadataCache = new Map<string, Promise<AudioMetadata>>();
+
+export interface VideoMetadata {
+  durationSeconds: number;
+  width: number;
+  height: number;
+  fps: number;
+  videoCodec: string;
+  hasAudio: boolean;
+}
+
+export interface AudioMetadata {
+  durationSeconds: number;
+  sampleRate: number;
+  channels: number;
+  audioCodec: string;
+  bitrate?: number;
+}
+
+interface FFProbeStream {
+  codec_type: string;
+  codec_name?: string;
+  width?: number;
+  height?: number;
+  r_frame_rate?: string;
+  avg_frame_rate?: string;
+  sample_rate?: string;
+  channels?: number;
+}
+
+interface FFProbeFormat {
+  duration?: string;
+  bit_rate?: string;
+}
+
+interface FFProbeOutput {
+  streams: FFProbeStream[];
+  format: FFProbeFormat;
+}
+
+function parseFrameRate(frameRateStr: string | undefined): number {
+  if (!frameRateStr) return 0;
+  const parts = frameRateStr.split("/");
+  if (parts.length === 2) {
+    const num = parseFloat(parts[0] ?? "");
+    const den = parseFloat(parts[1] ?? "");
+    if (den !== 0) return Math.round((num / den) * 100) / 100;
+  }
+  return parseFloat(frameRateStr) || 0;
+}
+
+export async function extractVideoMetadata(filePath: string): Promise<VideoMetadata> {
+  const cached = videoMetadataCache.get(filePath);
+  if (cached) {
+    return cached;
+  }
+
+  const probePromise = new Promise<VideoMetadata>((resolve, reject) => {
+    const args = ["-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", filePath];
+
+    const ffprobe = spawn("ffprobe", args);
+    let stdout = "";
+    let stderr = "";
+
+    ffprobe.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+    ffprobe.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    ffprobe.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(`[FFmpeg] ffprobe exited with code ${code}: ${stderr}`));
+        return;
+      }
+
+      try {
+        const output: FFProbeOutput = JSON.parse(stdout);
+        const videoStream = output.streams.find((s) => s.codec_type === "video");
+        if (!videoStream) {
+          reject(new Error("[FFmpeg] No video stream found"));
+          return;
+        }
+
+        const hasAudio = output.streams.some((s) => s.codec_type === "audio");
+        const fps = parseFrameRate(videoStream.avg_frame_rate) || parseFrameRate(videoStream.r_frame_rate);
+        const durationSeconds = output.format.duration ? parseFloat(output.format.duration) : 0;
+
+        const metadata: VideoMetadata = {
+          durationSeconds,
+          width: videoStream.width || 0,
+          height: videoStream.height || 0,
+          fps,
+          videoCodec: videoStream.codec_name || "unknown",
+          hasAudio,
+        };
+        resolve(metadata);
+      } catch (parseError: unknown) {
+        reject(new Error(`[FFmpeg] Failed to parse ffprobe output: ${parseError instanceof Error ? parseError.message : parseError}`));
+      }
+    });
+
+    ffprobe.on("error", (err) => {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        reject(new Error("[FFmpeg] ffprobe not found. Please install FFmpeg."));
+      } else {
+        reject(err);
+      }
+    });
+  });
+  videoMetadataCache.set(filePath, probePromise);
+  probePromise.catch(() => {
+    if (videoMetadataCache.get(filePath) === probePromise) {
+      videoMetadataCache.delete(filePath);
+    }
+  });
+  return probePromise;
+}
+
+export async function extractAudioMetadata(filePath: string): Promise<AudioMetadata> {
+  const cached = audioMetadataCache.get(filePath);
+  if (cached) {
+    return cached;
+  }
+
+  const probePromise = new Promise<AudioMetadata>((resolve, reject) => {
+    const args = ["-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", filePath];
+
+    const ffprobe = spawn("ffprobe", args);
+    let stdout = "";
+    let stderr = "";
+
+    ffprobe.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+    ffprobe.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    ffprobe.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(`[FFmpeg] ffprobe exited with code ${code}: ${stderr}`));
+        return;
+      }
+
+      try {
+        const output: FFProbeOutput = JSON.parse(stdout);
+        const audioStream = output.streams.find((s) => s.codec_type === "audio");
+        if (!audioStream) {
+          reject(new Error("[FFmpeg] No audio stream found"));
+          return;
+        }
+
+        const durationSeconds = output.format.duration ? parseFloat(output.format.duration) : 0;
+
+        const metadata: AudioMetadata = {
+          durationSeconds,
+          sampleRate: audioStream.sample_rate ? parseInt(audioStream.sample_rate) : 44100,
+          channels: audioStream.channels || 2,
+          audioCodec: audioStream.codec_name || "unknown",
+          bitrate: output.format.bit_rate ? parseInt(output.format.bit_rate) : undefined,
+        };
+        resolve(metadata);
+      } catch (parseError: unknown) {
+        reject(
+          new Error(
+            `[FFmpeg] Failed to parse ffprobe output: ${parseError instanceof Error ? parseError.message : parseError}`,
+          ),
+        );
+      }
+    });
+
+    ffprobe.on("error", (err) => {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        reject(new Error("[FFmpeg] ffprobe not found. Please install FFmpeg."));
+      } else {
+        reject(err);
+      }
+    });
+  });
+  audioMetadataCache.set(filePath, probePromise);
+  probePromise.catch(() => {
+    if (audioMetadataCache.get(filePath) === probePromise) {
+      audioMetadataCache.delete(filePath);
+    }
+  });
+  return probePromise;
+}

package/src/utils/gpuEncoder.ts

@@ -0,0 +1,58 @@
+/**
+ * GPU Encoder Detection
+ *
+ * Shared GPU encoder detection and naming utilities used by both
+ * chunkEncoder and streamingEncoder services.
+ */
+
+import { spawn } from "child_process";
+
+export type GpuEncoder = "nvenc" | "videotoolbox" | "vaapi" | "qsv" | null;
+
+export async function detectGpuEncoder(): Promise<GpuEncoder> {
+  return new Promise((resolve) => {
+    const ffmpeg = spawn("ffmpeg", ["-encoders"], {
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stdout = "";
+
+    ffmpeg.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+
+    ffmpeg.on("close", () => {
+      if (stdout.includes("h264_nvenc")) resolve("nvenc");
+      else if (stdout.includes("h264_videotoolbox")) resolve("videotoolbox");
+      else if (stdout.includes("h264_vaapi")) resolve("vaapi");
+      else if (stdout.includes("h264_qsv")) resolve("qsv");
+      else resolve(null);
+    });
+
+    ffmpeg.on("error", () => resolve(null));
+  });
+}
+
+let cachedGpuEncoder: GpuEncoder | undefined = undefined;
+
+export async function getCachedGpuEncoder(): Promise<GpuEncoder> {
+  if (cachedGpuEncoder === undefined) {
+    cachedGpuEncoder = await detectGpuEncoder();
+  }
+  return cachedGpuEncoder;
+}
+
+export function getGpuEncoderName(encoder: GpuEncoder, codec: "h264" | "h265"): string {
+  if (!encoder) return codec === "h264" ? "libx264" : "libx265";
+  switch (encoder) {
+    case "nvenc":
+      return codec === "h264" ? "h264_nvenc" : "hevc_nvenc";
+    case "videotoolbox":
+      return codec === "h264" ? "h264_videotoolbox" : "hevc_videotoolbox";
+    case "vaapi":
+      return codec === "h264" ? "h264_vaapi" : "hevc_vaapi";
+    case "qsv":
+      return codec === "h264" ? "h264_qsv" : "hevc_qsv";
+    default:
+      return codec === "h264" ? "libx264" : "libx265";
+  }
+}

package/src/utils/parityContract.ts

@@ -0,0 +1,35 @@
+export const MEDIA_VISUAL_STYLE_PROPERTIES = [
+  "width",
+  "height",
+  "top",
+  "left",
+  "right",
+  "bottom",
+  "inset",
+  "object-fit",
+  "object-position",
+  "z-index",
+  "opacity",
+  "visibility",
+  "filter",
+  "mix-blend-mode",
+  "backdrop-filter",
+  "border-radius",
+  "overflow",
+  "clip-path",
+  "mask",
+  "mask-image",
+  "mask-size",
+  "mask-position",
+  "mask-repeat",
+  "transform",
+  "transform-origin",
+  "box-sizing",
+] as const;
+
+export function quantizeTimeToFrame(timeSeconds: number, fps: number): number {
+  const safeFps = Number.isFinite(fps) && fps > 0 ? fps : 30;
+  const safeTime = Number.isFinite(timeSeconds) && timeSeconds > 0 ? timeSeconds : 0;
+  const frameIndex = Math.floor(safeTime * safeFps + 1e-9);
+  return frameIndex / safeFps;
+}

package/src/utils/runFfmpeg.ts

@@ -0,0 +1,81 @@
+/**
+ * Shared FFmpeg process runner.
+ *
+ * Extracts the repeated spawn-stderr-timeout-abort-close-error pattern
+ * that appears across audioMixer and chunkEncoder into a single helper.
+ */
+
+import { spawn } from "child_process";
+
+export interface RunFfmpegOptions {
+  signal?: AbortSignal;
+  timeout?: number;
+  onStderr?: (line: string) => void;
+}
+
+export interface RunFfmpegResult {
+  success: boolean;
+  exitCode: number | null;
+  stderr: string;
+  durationMs: number;
+}
+
+const DEFAULT_TIMEOUT = 300_000;
+
+export async function runFfmpeg(args: string[], opts?: RunFfmpegOptions): Promise<RunFfmpegResult> {
+  const startMs = Date.now();
+  const signal = opts?.signal;
+  const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+  const onStderr = opts?.onStderr;
+
+  return new Promise<RunFfmpegResult>((resolve) => {
+    const ffmpeg = spawn("ffmpeg", args);
+    let stderr = "";
+
+    const onAbort = () => {
+      ffmpeg.kill("SIGTERM");
+    };
+
+    if (signal) {
+      if (signal.aborted) {
+        ffmpeg.kill("SIGTERM");
+      } else {
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+    }
+
+    const timer = setTimeout(() => {
+      ffmpeg.kill("SIGTERM");
+    }, timeout);
+
+    ffmpeg.stderr.on("data", (data: Buffer) => {
+      const chunk = data.toString();
+      stderr += chunk;
+      if (onStderr) {
+        onStderr(chunk);
+      }
+    });
+
+    ffmpeg.on("close", (code) => {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener("abort", onAbort);
+      resolve({
+        success: !signal?.aborted && code === 0,
+        exitCode: code,
+        stderr,
+        durationMs: Date.now() - startMs,
+      });
+    });
+
+    ffmpeg.on("error", (err) => {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener("abort", onAbort);
+      resolve({
+        success: false,
+        exitCode: null,
+        stderr: err.message,
+        durationMs: Date.now() - startMs,
+      });
+    });
+  });
+}

package/src/utils/urlDownloader.ts

@@ -0,0 +1,78 @@
+import { createWriteStream, existsSync, mkdirSync } from "fs";
+import { createHash } from "crypto";
+import { join, extname } from "path";
+import { Readable } from "stream";
+import { finished } from "stream/promises";
+
+const downloadPathCache = new Map<string, string>();
+const inFlightDownloads = new Map<string, Promise<string>>();
+
+function getFilenameFromUrl(url: string): string {
+  const hash = createHash("md5").update(url).digest("hex").slice(0, 12);
+  const urlObj = new URL(url);
+  const ext = extname(urlObj.pathname) || ".mp4";
+  return `download_${hash}${ext}`;
+}
+
+export async function downloadToTemp(url: string, destDir: string, timeoutMs: number = 300000): Promise<string> {
+  const cachedPath = downloadPathCache.get(url);
+  if (cachedPath && existsSync(cachedPath)) {
+    return cachedPath;
+  }
+  const inFlight = inFlightDownloads.get(url);
+  if (inFlight) {
+    return inFlight;
+  }
+
+  if (!existsSync(destDir)) {
+    mkdirSync(destDir, { recursive: true });
+  }
+
+  const filename = getFilenameFromUrl(url);
+  const localPath = join(destDir, filename);
+
+  if (existsSync(localPath)) {
+    downloadPathCache.set(url, localPath);
+    return localPath;
+  }
+
+  const downloadPromise = (async () => {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+      const response = await fetch(url, { signal: controller.signal });
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+
+      if (!response.body) {
+        throw new Error("Response body is empty");
+      }
+
+      const fileStream = createWriteStream(localPath);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const readableStream = Readable.fromWeb(response.body as any);
+      await finished(readableStream.pipe(fileStream));
+
+      downloadPathCache.set(url, localPath);
+      return localPath;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (message.includes("aborted")) {
+        throw new Error(`[URLDownloader] Download timeout after ${timeoutMs / 1000}s: ${url}`);
+      }
+      throw new Error(`[URLDownloader] Download failed: ${message}`);
+    } finally {
+      inFlightDownloads.delete(url);
+    }
+  })();
+  inFlightDownloads.set(url, downloadPromise);
+  return downloadPromise;
+}
+
+export function isHttpUrl(path: string): boolean {
+  return path.startsWith("http://") || path.startsWith("https://");
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/**/*.test.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+  },
+});