Files
hyperframes/packages/engine
miga-heygenandMiguel Ángel 6fcf2308b6 fix(render): gate pre-frame retry on loopback connection loss
Address review findings on the streaming interruption recovery.

Classifier (engine): walk the error cause chain (depth 5, including
AggregateError members) so undici's "fetch failed" wrapper and a
dual-stack localhost AggregateError classify by the errno they carry.
Recognise the loopback spellings Node, Bun and Chrome emit: unbracketed
"::1", "[::1]", "127.0.0.1" and "localhost" with ETIMEDOUT, ECONNREFUSED
or ECONNRESET, and Chrome's ERR_TIMED_OUT, ERR_CONNECTION_TIMED_OUT,
ERR_CONNECTION_REFUSED, ERR_CONNECTION_RESET, ERR_CONNECTION_CLOSED and
ERR_EMPTY_RESPONSE. Normalise the IPv6 host to "::1". Export
isLoopbackConnectionLoss, LoopbackConnectionLoss and
CaptureEndpointDiagnostic.

Endpoint provenance: CaptureStageError now forwards the classified
endpoint, so the orchestrator's re-classification (which early-returns
the stage error) sees the real host and port instead of always logging
an unknown owner.

Retry gate: replace `transient_browser && workerCount === 1` with
resolvePreFrameLoopbackLoss in the new render/preFrameRecovery module.
Only a failure that names a loopback endpoint, on exactly one worker,
with zero frames written, qualifies. Target closed, Page crashed, a
browser that cannot launch or a runtime that never becomes ready fail
immediately as before the widening; a SIGTERM-killed Chrome cannot hide
behind same-host retry work. recoverPreFrameFileServer owns the health
log and the restart-on-unhealthy decision so both are unit-testable.

File server: one createRenderFileServer factory for probe discovery,
frame capture and the pre-frame restart. A rejected body.cancel() no
longer marks a healthy server unhealthy; the probe error carries the
errno (ECONNREFUSED on Node, ConnectionRefused on Bun).

Audio: share canRetryMixLocally and resolveAutomationRerun between the
grouped and ungrouped mixes so retryable failures (external
interruption, managed deadline/inactivity, missing FFmpeg) never trigger
a compatibility or automation-degradation rerun, an interruption landing
on the rerun is reported instead of discarded, and a cancelled group
submix uses the canonical cancelled/user classification.

Tests pin each guard: dropping endpoint forwarding, deleting the restart
block, workerCount >= 1, dropping the zero-frame gate, forcing the
identity-header check true, removing the bare ::1 pattern, removing the
cause walk, reverting the ungrouped audio guard and discarding the rerun
interruption each turn a test red.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
2026-09-14 17:51:28 +00:00
..
2026-09-14 12:41:47 -04:00
2026-03-21 22:43:56 -07: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