mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-02 03:36:52 +00:00
Miguel Ángel
81f60dbc98
* fix(engine): exports no longer fail on a video clip outside the composition's length A clip that starts at or after the composition's end (or ends before 0) is never on screen, so extraction skips it. Its timeline window stayed as authored, so the frame-coverage gate still expected its full length and aborted the render with "captured 0 of expected N frames". Such a clip now leaves extraction with an empty window, the same way a partly visible clip is already trimmed to its visible part, so it owes no frames. * fix(producer): drop clips outside the timeline before extraction, cloud renders included The previous commit marked such a clip with end = start, but the window resolver reads a zero-length slot as "use the source's natural length", and the distributed plan still required an extracted entry for every declared clip. Instead, the extract stage (shared by in-process and distributed renders) removes clips that lie entirely outside [0, duration) from the composition before probing and extraction, using one engine predicate that the extractor's own early skip also uses, so a clip ending before 0 is no longer downloaded or probed either. * fix(engine): keep natural-length clips when dropping clips outside the timeline A clip with no authored end carries end 0 (script-created media, or a src set from a script), which the window resolver reads as "natural source length". The outside-the-timeline check treated it as ending at 0 and dropped it, so the clip froze on its first frame. Only an authored end (after the start) at or before 0 now counts as before the timeline. * fix(producer): only drop clips that start at or after the composition's end A clip with no authored length carries end 0, the same value as an authored end at 0, so "ends at or before 0" cannot be told apart from "natural length" and a script-created clip with a negative start was dropped and froze. Clips entirely before 0 keep main's behaviour; the filter now only drops clips starting at or after the end, which never reads the end. * test(producer): pin that a clip starting just before the end is still extracted
@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