@hyperframes/engine 0.6.119 → 0.6.120

package/src/services/chunkEncoder.types.ts

@@ -1,60 +0,0 @@
-import type { HdrTransfer } from "../utils/hdr.js";
-import type { Fps } from "@hyperframes/core";
-
-export interface EncoderOptions {
-  /** Frame rate as an exact rational; see `Fps` in @hyperframes/core. */
-  fps: Fps;
-  width: number;
-  height: number;
-  codec?: "h264" | "h265" | "vp9" | "prores";
-  preset?: string;
-  quality?: number;
-  bitrate?: string;
-  pixelFormat?: string;
-  /** libvpx-vp9 -cpu-used value. Defaults to the engine VP9 setting. */
-  vp9CpuUsed?: number;
-  useGpu?: boolean;
-  hdr?: { transfer: HdrTransfer };
-  /**
-   * When `true`, force closed-GOP encoding with a keyframe at every
-   * `gopSize` boundary so the resulting chunk file can be losslessly
-   * concatenated (`ffmpeg -f concat -c copy`) with sibling chunks.
-   *
-   * Default `false`: GOP placement is left to libx264/libx265 defaults
-   * (open-GOP, scenecut-driven keyframes), preserving the in-process
-   * renderer's byte-identical output.
-   *
-   * Honored by the SW libx264 / libx265 / libvpx-vp9 paths. GPU encoders
-   * and ProRes ignore the flag — GPU concat-copy is a separate story and
-   * ProRes is intra-only (every frame is already a keyframe, so no
-   * closed-GOP forcing is needed).
-   *
-   * For libvpx-vp9, closed-GOP also forces `-auto-alt-ref 0` so the
-   * boundary frame between chunks remains independently decodable —
-   * libvpx-vp9's default alt-ref frames can land anywhere in the GOP
-   * for compression and break concat-copy seams.
-   */
-  lockGopForChunkConcat?: boolean;
-  /**
-   * Required when `lockGopForChunkConcat` is `true`. Number of frames per
-   * GOP — set to `chunkSize` so every chunk starts on an IDR keyframe and
-   * concat-copy boundaries land on independently-decodable frames.
-   */
-  gopSize?: number;
-}
-
-export interface EncodeResult {
-  success: boolean;
-  outputPath: string;
-  durationMs: number;
-  framesEncoded: number;
-  fileSize: number;
-  error?: string;
-}
-
-export interface MuxResult {
-  success: boolean;
-  outputPath: string;
-  durationMs: number;
-  error?: string;
-}

package/src/services/extractionCache.test.ts

@@ -1,199 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-
-import {
-  COMPLETE_SENTINEL,
-  FRAME_FILENAME_PREFIX,
-  SCHEMA_PREFIX,
-  cacheEntryDirName,
-  computeCacheKey,
-  ensureCacheEntryDir,
-  lookupCacheEntry,
-  markCacheEntryComplete,
-  readKeyStat,
-  type CacheKeyInput,
-} from "./extractionCache.js";
-
-const keyFor = (videoPath: string, overrides: Partial<CacheKeyInput> = {}): CacheKeyInput => {
-  const stat = readKeyStat(videoPath);
-  if (!stat) throw new Error(`keyFor fixture missing on disk: ${videoPath}`);
-  return {
-    videoPath,
-    mtimeMs: stat.mtimeMs,
-    size: stat.size,
-    mediaStart: 0,
-    duration: 3,
-    fps: 30,
-    format: "jpg",
-    ...overrides,
-  };
-};
-
-describe("extractionCache constants", () => {
-  it("exposes the v2 schema prefix", () => {
-    expect(SCHEMA_PREFIX).toBe("hfcache-v2-");
-  });
-
-  it("exposes the frame filename prefix shared with the extractor", () => {
-    expect(FRAME_FILENAME_PREFIX).toBe("frame_");
-  });
-
-  it("uses a dotfile sentinel so ls-without-A hides it", () => {
-    expect(COMPLETE_SENTINEL.startsWith(".")).toBe(true);
-  });
-});
-
-describe("computeCacheKey", () => {
-  let tmpRoot: string;
-  let sourceFile: string;
-
-  beforeEach(() => {
-    tmpRoot = mkdtempSync(join(tmpdir(), "hf-extract-cache-test-"));
-    sourceFile = join(tmpRoot, "clip.mp4");
-    writeFileSync(sourceFile, "fake-video-bytes", "utf-8");
-  });
-
-  afterEach(() => {
-    if (existsSync(tmpRoot)) rmSync(tmpRoot, { recursive: true, force: true });
-  });
-
-  const base = (videoPath: string): CacheKeyInput => keyFor(videoPath);
-
-  it("returns the same key for identical inputs", () => {
-    const a = computeCacheKey(base(sourceFile));
-    const b = computeCacheKey(base(sourceFile));
-    expect(a).toBe(b);
-  });
-
-  it("produces a 64-char hex SHA-256 digest", () => {
-    const key = computeCacheKey(base(sourceFile));
-    expect(key).toMatch(/^[0-9a-f]{64}$/);
-  });
-
-  it("changes when path changes (moved files re-extract)", () => {
-    const other = join(tmpRoot, "other.mp4");
-    writeFileSync(other, "fake-video-bytes", "utf-8");
-    const a = computeCacheKey(base(sourceFile));
-    const b = computeCacheKey(base(other));
-    expect(a).not.toBe(b);
-  });
-
-  it("changes when mediaStart changes", () => {
-    const a = computeCacheKey(base(sourceFile));
-    const b = computeCacheKey({ ...base(sourceFile), mediaStart: 1 });
-    expect(a).not.toBe(b);
-  });
-
-  it("changes when duration changes", () => {
-    const a = computeCacheKey(base(sourceFile));
-    const b = computeCacheKey({ ...base(sourceFile), duration: 5 });
-    expect(a).not.toBe(b);
-  });
-
-  it("changes when fps changes (different frame count invalidates key)", () => {
-    const a = computeCacheKey(base(sourceFile));
-    const b = computeCacheKey({ ...base(sourceFile), fps: 60 });
-    expect(a).not.toBe(b);
-  });
-
-  it("changes when format changes", () => {
-    const a = computeCacheKey(base(sourceFile));
-    const b = computeCacheKey({ ...base(sourceFile), format: "png" });
-    expect(a).not.toBe(b);
-  });
-
-  it("normalizes non-finite duration so Infinity doesn't produce unstable keys", () => {
-    const a = computeCacheKey({ ...base(sourceFile), duration: Infinity });
-    const b = computeCacheKey({ ...base(sourceFile), duration: Infinity });
-    expect(a).toBe(b);
-  });
-
-  it("changes when file content changes (mtime+size bump)", () => {
-    const before = computeCacheKey(base(sourceFile));
-    // Force an mtime change by waiting 5ms then overwriting with different bytes.
-    // 5ms is well above the Linux mtime resolution (typically nanoseconds) and
-    // below any Windows cache coherency window. Using a longer sleep pads against
-    // coarse filesystem mtime granularity without slowing the suite.
-    const start = Date.now();
-    while (Date.now() - start < 5) {
-      /* spin */
-    }
-    writeFileSync(sourceFile, "different-bytes-longer-than-before", "utf-8");
-    const after = computeCacheKey(base(sourceFile));
-    expect(after).not.toBe(before);
-  });
-
-  it("readKeyStat returns null for a missing source (callers skip the cache)", () => {
-    // Previously readKeyStat returned a `{mtimeMs: 0, size: 0}` sentinel for
-    // missing files; two unrelated missing paths then shared the same cache
-    // key tuple and polluted the cache. The contract now returns null so
-    // callers can explicitly skip the cache path and let the extractor
-    // surface the real file-not-found error.
-    const missing = join(tmpRoot, "does-not-exist.mp4");
-    expect(readKeyStat(missing)).toBeNull();
-  });
-});
-
-describe("cacheEntryDirName", () => {
-  it("prefixes with the schema and truncates to 16 hex chars", () => {
-    const full = "a".repeat(64);
-    expect(cacheEntryDirName(full)).toBe(`${SCHEMA_PREFIX}${"a".repeat(16)}`);
-  });
-});
-
-describe("lookupCacheEntry / markCacheEntryComplete", () => {
-  let tmpRoot: string;
-  let sourceFile: string;
-
-  beforeEach(() => {
-    tmpRoot = mkdtempSync(join(tmpdir(), "hf-extract-cache-test-"));
-    sourceFile = join(tmpRoot, "clip.mp4");
-    writeFileSync(sourceFile, "fake-video-bytes", "utf-8");
-  });
-
-  afterEach(() => {
-    if (existsSync(tmpRoot)) rmSync(tmpRoot, { recursive: true, force: true });
-  });
-
-  const base = (videoPath: string): CacheKeyInput => keyFor(videoPath);
-
-  it("misses on an empty cache root", () => {
-    const lookup = lookupCacheEntry(tmpRoot, base(sourceFile));
-    expect(lookup.hit).toBe(false);
-    expect(lookup.entry.dir.startsWith(tmpRoot)).toBe(true);
-  });
-
-  it("hits after ensureCacheEntryDir + markCacheEntryComplete", () => {
-    const first = lookupCacheEntry(tmpRoot, base(sourceFile));
-    ensureCacheEntryDir(first.entry);
-    markCacheEntryComplete(first.entry);
-
-    const second = lookupCacheEntry(tmpRoot, base(sourceFile));
-    expect(second.hit).toBe(true);
-    expect(second.entry.dir).toBe(first.entry.dir);
-  });
-
-  it("treats an in-progress dir without the sentinel as a miss", () => {
-    const lookup = lookupCacheEntry(tmpRoot, base(sourceFile));
-    ensureCacheEntryDir(lookup.entry);
-    // Simulate abandoned extraction — frames written but sentinel never marked.
-    writeFileSync(join(lookup.entry.dir, "frame_00001.jpg"), "x", "utf-8");
-    const again = lookupCacheEntry(tmpRoot, base(sourceFile));
-    expect(again.hit).toBe(false);
-  });
-
-  it("places entries under the cache root, not the source parent", () => {
-    const subroot = join(tmpRoot, "cache-root");
-    mkdirSync(subroot, { recursive: true });
-    const lookup = lookupCacheEntry(subroot, base(sourceFile));
-    expect(lookup.entry.dir.startsWith(subroot)).toBe(true);
-  });
-
-  it("uses the same directory for identical inputs across lookups", () => {
-    const a = lookupCacheEntry(tmpRoot, base(sourceFile));
-    const b = lookupCacheEntry(tmpRoot, base(sourceFile));
-    expect(a.entry.dir).toBe(b.entry.dir);
-  });
-});

package/src/services/extractionCache.ts

@@ -1,216 +0,0 @@
-/**
- * Content-Addressed Extraction Cache
- *
- * Video frame extraction is the single most expensive phase of a render
- * after capture. Repeat renders of the same composition (preview → final,
- * studio iteration) re-extract identical frames from the same source file,
- * burning ffmpeg time that adds no value. This module keys extracted frame
- * bundles on the (path, mtime, size, mediaStart, duration, fps, format)
- * tuple so re-renders resolve to a pre-extracted directory instead of
- * re-invoking ffmpeg.
- *
- * ### Scheme
- *
- * - The key is the SHA-256 of a stable JSON encoding of the tuple above.
- * - Cache entries live under `<rootDir>/<SCHEMA_PREFIX><key[0..16]>/` so
- *   `ls` output and tracing logs stay short. Truncation to 16 hex chars
- *   leaves 64 bits of entropy — collision risk at cache scale is negligible.
- * - A completed entry is marked by writing the `.hf-complete` sentinel file
- *   after all frames are on disk. A dir without the sentinel is treated as
- *   absent (stale/abandoned) and re-extracted into a fresh key (the old dir
- *   is left for external gc — the cache owns keys, not deletion policy).
- *
- * ### Versioning
- *
- * `SCHEMA_PREFIX` bumps when the cache-contents invariant changes (e.g.
- * extraction format, frame layout). Old entries under the previous prefix
- * become inert and can be gc'd by the caller.
- */
-
-import { createHash } from "node:crypto";
-import { mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import type { VideoMetadata } from "../utils/ffprobe.js";
-
-/** Filename prefix for extracted frames. Shared with the extractor. */
-export const FRAME_FILENAME_PREFIX = "frame_";
-
-/** Sentinel filename written after a cache entry is fully populated. */
-export const COMPLETE_SENTINEL = ".hf-complete";
-
-/** Current schema version. Bump when cache-entry layout changes. */
-export const SCHEMA_PREFIX = "hfcache-v2-";
-
-/** Truncated hex chars of SHA-256 used for the entry directory name. */
-const KEY_HEX_CHARS = 16;
-
-export type CacheFrameFormat = "jpg" | "png";
-
-export interface CacheKeyInput {
-  /** Absolute path to the source video file. Part of the key so moved files
-   *  re-extract rather than match by (size, mtime) alone. */
-  videoPath: string;
-  /** Source file modification time in ms (floored). Invalidates the key on edit. */
-  mtimeMs: number;
-  /** Source file size in bytes. Invalidates the key on content change. */
-  size: number;
-  /** Seconds into source the composition starts reading (video.mediaStart). */
-  mediaStart: number;
-  /** Seconds of source the composition uses. Infinity is normalized to -1
-   *  so callers that pass an unresolved "natural duration" still produce a
-   *  stable key across invocations. */
-  duration: number;
-  /** Target output frames-per-second. */
-  fps: number;
-  /** Output image format. */
-  format: CacheFrameFormat;
-}
-
-export interface CacheEntry {
-  /** Absolute path to the cache entry directory. */
-  dir: string;
-  /** Full 64-char SHA-256 hex digest (parent of the truncated key). */
-  keyHash: string;
-}
-
-export interface CacheLookup {
-  /** Cache entry information — always returned even on a miss so the caller
-   *  can extract directly into `dir` then call `markCacheEntryComplete`. */
-  entry: CacheEntry;
-  /** True when the entry exists AND carries the completion sentinel. */
-  hit: boolean;
-}
-
-/**
- * Read `(mtimeMs, size)` for a path. Returns `null` if the file is missing —
- * callers should skip the cache path for that entry so the extractor surfaces
- * the real file-not-found error. Returning a zero-stat sentinel would let two
- * missing files share the same `(0, 0)` tuple and pollute the cache with an
- * orphaned entry.
- */
-export function readKeyStat(videoPath: string): { mtimeMs: number; size: number } | null {
-  try {
-    const stat = statSync(videoPath);
-    return { mtimeMs: Math.floor(stat.mtimeMs), size: stat.size };
-  } catch {
-    return null;
-  }
-}
-
-function canonicalKeyBlob(input: CacheKeyInput): string {
-  const durationForKey = Number.isFinite(input.duration) ? input.duration : -1;
-  return JSON.stringify({
-    p: input.videoPath,
-    m: input.mtimeMs,
-    s: input.size,
-    ms: input.mediaStart,
-    d: durationForKey,
-    f: input.fps,
-    fmt: input.format,
-  });
-}
-
-/**
- * Compute the SHA-256 hex digest for a cache key input.
- */
-export function computeCacheKey(input: CacheKeyInput): string {
-  return createHash("sha256").update(canonicalKeyBlob(input)).digest("hex");
-}
-
-/**
- * Derive the truncated cache-entry directory name from a full key hash.
- * Exposed so tests and the entry dir resolver share one truncation rule.
- */
-export function cacheEntryDirName(keyHash: string): string {
-  return SCHEMA_PREFIX + keyHash.slice(0, KEY_HEX_CHARS);
-}
-
-/**
- * Look up a cache entry by key input. Returns the resolved entry path plus a
- * `hit` flag. On miss, callers should extract frames into `entry.dir`
- * (after calling `ensureCacheEntryDir`) and then call `markCacheEntryComplete`
- * once the extraction succeeds.
- */
-export function lookupCacheEntry(rootDir: string, input: CacheKeyInput): CacheLookup {
-  const keyHash = computeCacheKey(input);
-  const dir = join(rootDir, cacheEntryDirName(keyHash));
-  const complete = existsSync(join(dir, COMPLETE_SENTINEL));
-  return { entry: { dir, keyHash }, hit: complete };
-}
-
-/**
- * Ensure a cache entry's directory exists so the extractor can write into it.
- * Idempotent: `mkdirSync({recursive:true})` is a no-op when the dir exists.
- */
-export function ensureCacheEntryDir(entry: CacheEntry): void {
-  mkdirSync(entry.dir, { recursive: true });
-}
-
-/**
- * Write the completion sentinel so subsequent lookups treat this entry as a
- * hit. Must be called only after every frame has been written.
- *
- * Concurrency: lookup→populate→mark is non-atomic. Two concurrent renders of
- * the same key may both miss, both extract into the same dir, and the later
- * writer's frames win. The result is correct (identical inputs yield identical
- * frames) but wasteful. Acceptable for a single-process render pipeline;
- * anyone running concurrent renders against a shared cache root should front
- * it with an external lock.
- */
-export function markCacheEntryComplete(entry: CacheEntry): void {
-  writeFileSync(join(entry.dir, COMPLETE_SENTINEL), "", "utf-8");
-}
-
-/**
- * Rebuild the in-memory frame index for a cached entry. Called on cache hits
- * so the extractor's caller receives the same `ExtractedFrames` shape it
- * would get from a fresh extraction — without re-running ffmpeg or ffprobe.
- *
- * The `metadata` argument is the `VideoMetadata` probed in the extractor's
- * Phase 2 (pre-preflight). Passing it here avoids an extra ffprobe on the
- * hit path.
- */
-export interface RehydrateOptions {
-  videoId: string;
-  srcPath: string;
-  fps: number;
-  format: CacheFrameFormat;
-  metadata: VideoMetadata;
-}
-
-export interface RehydratedFrames {
-  videoId: string;
-  srcPath: string;
-  outputDir: string;
-  framePattern: string;
-  fps: number;
-  totalFrames: number;
-  metadata: VideoMetadata;
-  framePaths: Map<number, string>;
-}
-
-export function rehydrateCacheEntry(
-  entry: CacheEntry,
-  options: RehydrateOptions,
-): RehydratedFrames {
-  const framePattern = `${FRAME_FILENAME_PREFIX}%05d.${options.format}`;
-  const framePaths = new Map<number, string>();
-  const suffix = `.${options.format}`;
-  const files = readdirSync(entry.dir)
-    .filter((f) => f.startsWith(FRAME_FILENAME_PREFIX) && f.endsWith(suffix))
-    .sort();
-  files.forEach((file, idx) => {
-    framePaths.set(idx, join(entry.dir, file));
-  });
-  return {
-    videoId: options.videoId,
-    srcPath: options.srcPath,
-    outputDir: entry.dir,
-    framePattern,
-    fps: options.fps,
-    totalFrames: framePaths.size,
-    metadata: options.metadata,
-    framePaths,
-  };
-}

package/src/services/fileServer.ts

@@ -1,110 +0,0 @@
-/**
- * File Server
- *
- * Lightweight HTTP server that serves a project directory to headless Chrome.
- * Optionally injects scripts into index.html on-the-fly (e.g. runtime, bridge).
- * Framework-agnostic — the caller decides what scripts to inject.
- */
-
-import { Hono } from "hono";
-import { serve } from "@hono/node-server";
-import { readFileSync, existsSync, statSync } from "node:fs";
-import { join, extname } from "node:path";
-import { injectScriptsIntoHtml } from "@hyperframes/core/compiler";
-
-const MIME_TYPES: Record<string, string> = {
-  ".html": "text/html; charset=utf-8",
-  ".css": "text/css; charset=utf-8",
-  ".js": "application/javascript; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".svg": "image/svg+xml",
-  ".webp": "image/webp",
-  ".mp4": "video/mp4",
-  ".webm": "video/webm",
-  ".mp3": "audio/mpeg",
-  ".wav": "audio/wav",
-  ".ogg": "audio/ogg",
-  ".aac": "audio/aac",
-  ".woff": "font/woff",
-  ".woff2": "font/woff2",
-  ".ttf": "font/ttf",
-  ".otf": "font/otf",
-};
-
-export interface FileServerOptions {
-  projectDir: string;
-  compiledDir?: string;
-  port?: number;
-  /** Scripts injected into <head> of index.html. Default: none. */
-  headScripts?: string[];
-  /** Scripts injected before </body> of index.html. Default: none. */
-  bodyScripts?: string[];
-  /** Strip embedded runtime scripts from HTML before injection. Default: true. */
-  stripEmbeddedRuntime?: boolean;
-}
-
-export interface FileServerHandle {
-  url: string;
-  port: number;
-  close: () => void;
-}
-
-export function createFileServer(options: FileServerOptions): Promise<FileServerHandle> {
-  const { projectDir, compiledDir, port = 0, stripEmbeddedRuntime = true } = options;
-
-  const headScripts = options.headScripts ?? [];
-  const bodyScripts = options.bodyScripts ?? [];
-
-  const app = new Hono();
-
-  app.get("/*", (c) => {
-    let requestPath = c.req.path;
-    if (requestPath === "/") requestPath = "/index.html";
-
-    // Remove leading slash
-    const relativePath = requestPath.replace(/^\//, "");
-    const compiledPath = compiledDir ? join(compiledDir, relativePath) : null;
-    const hasCompiledFile = Boolean(
-      compiledPath && existsSync(compiledPath) && statSync(compiledPath).isFile(),
-    );
-    const filePath = hasCompiledFile ? (compiledPath as string) : join(projectDir, relativePath);
-
-    if (!existsSync(filePath) || !statSync(filePath).isFile()) {
-      return c.text("Not found", 404);
-    }
-
-    const ext = extname(filePath).toLowerCase();
-    const contentType = MIME_TYPES[ext] || "application/octet-stream";
-
-    if (ext === ".html") {
-      const rawHtml = readFileSync(filePath, "utf-8");
-      const html =
-        relativePath === "index.html"
-          ? injectScriptsIntoHtml(rawHtml, headScripts, bodyScripts, stripEmbeddedRuntime)
-          : rawHtml;
-      return c.text(html, 200, { "Content-Type": contentType });
-    }
-
-    const content = readFileSync(filePath);
-    return new Response(content, {
-      status: 200,
-      headers: { "Content-Type": contentType },
-    });
-  });
-
-  return new Promise((resolve) => {
-    const server = serve({ fetch: app.fetch, port }, (info) => {
-      const actualPort = info.port;
-      const url = `http://localhost:${actualPort}`;
-      resolve({
-        url,
-        port: actualPort,
-        close: () => server.close(),
-      });
-    });
-  });
-}