Files
hyperframes/packages/engine
James RussoandClaude Opus 5.5 84799bdc59 fix: take helper programs only from install locations, never the project folder (#7524)
* fix(cli,parsers): take helper programs only from install locations, never the project folder

FFmpeg, FFprobe, whisper-cli, parakeet-mlx, Python and system Chrome are now
found through one shared rule: an absolute PATH entry outside the working
directory, or a fixed install dir. A relative PATH entry and any folder
inside the working directory are skipped, on every platform. Windows walks
PATH itself instead of asking `where`, which lists the working directory
first.

FFmpeg discovery no longer falls back to `.hyperframes/bin` or to an
installer package in the project's node_modules; an installer package
installed next to HyperFrames still works. The env overrides are unchanged.
The CLI skill reference stops suggesting the project-local folder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(cli): give the PATH-lookup tests a fixed PATH on Windows

Windows now walks PATH instead of running `where`, so tests that faked
`where` output found the runner's real python and cmake. Both tests now set
PATH to a temp folder holding only the programs they expect.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: report a missing helper program instead of running it by bare name

When no trusted FFmpeg or FFprobe is found, the engine, the producer's
probes and Studio's waveform, peak and audio-track helpers now report
"not found" with the HYPERFRAMES_FFMPEG_PATH / HYPERFRAMES_FFPROBE_PATH hint
instead of handing the bare name to the OS lookup. Callers that degraded
on a missing binary still do: runFfmpeg returns a spawn_error result, the
GPU and version probes report none, and Studio's audio helpers fail soft.

The Lambda handler names its bundled ffmpeg and ffprobe by path, since
they live under the task root, which is the working directory.

brew, git and cmake for the whisper.cpp install, and the clipboard tool
for `hyperframes add`, run by the absolute path the trusted lookup
approved. The media-use engine gets a PATH holding only trusted folders.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(engine): fail a missing FFmpeg the way a failed spawn always has

Throwing from getFfmpegBinary turned every caller's missing-binary path
into a synchronous throw: the streaming encoder's "failure result, not a
throw" contract broke, and unit lanes that run without FFmpeg crashed at
module load. With no trusted copy the getters now return an absolute path
inside HyperFrames' own install that is never created, named for the
override to set. Spawning it fails with ENOENT exactly as before, and the
OS still never looks the bare name up. The call-site guards and fixture
changes that the throw needed are reverted.

The whisper install tests match git and cmake by name and skip the brew
case on Windows, where the lookup walks the real PATH.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(engine): pin the found FFmpeg before the HDR test looks it up as macOS on Windows

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 09:46:52 +00:00
..
2026-11-11 06:32:08 +00:00

@hyperframes/engine

Seekable web-page-to-video rendering engine built on Puppeteer and FFmpeg.

Framework-agnostic: works with GSAP, Lottie, Three.js, CSS animations, or any web content that implements the window.__hf seek protocol.

Install

npm install @hyperframes/engine

Requirements: Node.js >= 22, Chrome/Chromium (auto-downloaded by Puppeteer), FFmpeg

What it does

The engine opens your HTML composition in a headless Chrome instance, seeks frame-by-frame using Chrome's HeadlessExperimental.beginFrame API, captures screenshots, and encodes them into video with FFmpeg.

Key services

Service Description
browserManager Launches and pools headless Chrome instances (chrome-headless-shell)
frameCapture Manages capture sessions — seek, screenshot, buffer lifecycle
screenshotService BeginFrame-based capture with CDP (Chrome DevTools Protocol)
chunkEncoder FFmpeg encoding with chunked concat, GPU detection, faststart
streamingEncoder Pipe frames to FFmpeg in real time (no intermediate PNGs on disk)
audioMixer Parse <audio> elements and mix audio tracks via FFmpeg
videoFrameExtractor Extract frames from <video> elements for compositing
parallelCoordinator Split frame ranges across worker processes
fileServer Serve local HTML files to the browser via Hono

Usage

import {
  acquireBrowser,
  createCaptureSession,
  initializeSession,
  captureFrame,
  closeCaptureSession,
} from "@hyperframes/engine";

// 1. Launch browser
const browserLease = await acquireBrowser({ captureMode: "beginFrame" });

// 2. Open a capture session
const session = createCaptureSession({
  browser: browserLease.browser,
  url: "http://localhost:3000/my-composition.html",
  width: 1920,
  height: 1080,
  fps: 30,
});
await initializeSession(session);

// 3. Capture frames
for (let i = 0; i < totalFrames; i++) {
  await captureFrame(session, i, `/tmp/frames/frame-${i}.png`);
}

// 4. Clean up
await closeCaptureSession(session);
await browserLease.release();

Most users should use @hyperframes/producer or the hyperframes CLI instead of calling the engine directly.

Documentation

Full documentation: hyperframes.heygen.com/packages/engine