mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* fix(engine): a gpu-less linux host falls back from drawElement instead of hanging self-verify
On a GPU-less Linux headless shell asked for browserGpuMode "hardware", Chrome has
GPU args and no GPU, so getContext("webgl") returns null. detectGpuBackend read that
as { isSwiftShader: false }, the SwiftShader gate let drawElement engage on a
BeginFrame-launched browser, and self-verify on its truth page then stalled until
the render failed after about 300 s, with no fallback.
drawElementGate now decides the init-time fallback, each with a named deGateReason:
- swiftshader: any software GL (SwiftShader, llvmpipe, lavapipe, softpipe, Microsoft
Basic Render Driver), from one shared token list. Detection on real GPUs is unchanged.
- webgl_unavailable: no WebGL context could be created (null, or getContext throws).
- beginframe_no_self_verify: the browser was launched for BeginFrame. Its self-verify
truth page has no BeginFrame driver, so drawElement frames could not be checked, and
a Linux host with a GPU would stall the same way. HF_FORCE_DRAWELEMENT bypasses only
this gate.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(producer): windowed frames runs drawElement through self-verify and a recycle
Adds a drawElement case to the windowed-frames integration test: drawElement capture,
self-verify through the on-demand hook, and a browser recycle. It covers that hook
only on a macOS or Windows host with a GPU. Linux always gates drawElement away
(headless-shell launches for BeginFrame, which has no self-verify), and so does any
host with no GPU; there the case asserts the named gate fallback (swiftshader,
webgl_unavailable or beginframe_no_self_verify) and prints that drawElement did not
run. HF_TEST_REQUIRE_DRAWELEMENT=1 turns that fallback into a failure, for the hosts
that are meant to run it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@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
Related packages
@hyperframes/core— types, parsers, frame adapters@hyperframes/producer— high-level render pipeline built on this enginehyperframes— CLI