mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* fix(engine): extraction-time video downloads get the not-media check A video src that is still remote at frame extraction is downloaded again and then probed. That copy now gets the checks other media downloads get before anything reads it as media: - the not-media sniff, so an HTML, XML or JSON body (including a DASH manifest) is refused with the existing NotMediaPayloadError, classified as invalid_media; - on a render service (PRODUCER_RESTRICT_PAGE_NETWORK), the same -format_whitelist an https input gets, so a playlist, manifest or concat list fails to open whatever its bytes say, and no file it names is read. Real mp4, mov and webm downloads extract the same frames as before. * fix(engine): the download format check stops when the render is cancelled * fix(engine): the not-media sniff keeps mp4 files whose box size reads as text An ISO BMFF file opens with a 4-byte box size and a box type. A size of 60 is the byte `<`, so after the leading NULs were skipped a valid mp4 with a 60-byte ftyp was refused as a text document. The sniff now recognises an mp4/mov box header (size 0, 1 or at least 8, then ftyp, styp, moov, moof, mdat, free, skip, wide, sidx or pdin) before it skips NULs. HTML, XML, JSON and playlist refusals are unchanged. * fix(engine): the mp4 exception in the not-media sniff needs a box that fits the file The sniff only skips its document check for an mp4/mov opening when the first box is ftyp or styp, its declared size (including a 64-bit size) fits the file length, and the next box header, when the sniff window holds it, is a known media box that also fits. A document that only spells a box header falls through to the document and playlist checks as before. * fix(engine): the not-media sniff keeps mp4 files with leading padding or extension boxes An mp4 or QuickTime file may open with free, skip, wide, uuid, pdin, moov, mdat or moof as well as ftyp or styp, and may carry any box type after it. The sniff now accepts any of those first boxes, then walks every box header the sniff window holds: each needs a printable four-character type and a size that fits the file. A document that only spells a box header still falls through to the document and playlist checks.
@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