mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* fix(engine): the media playlist check reads HLS lines and attributes as ffmpeg does The folder check now finds every name ffmpeg's hls demuxer would open: - lines end at CR, LF or NUL, and a line is also read cut at ffmpeg's 4095-byte limit; - URI attributes are split like ff_parse_key_value: quoted or bare values, with backslash escapes removed; - leading ID3v2 tags are skipped before the playlist signature, and a file behind more than 16 of them is refused. Each refused shape is checked against ffprobe 8 in the test: ffprobe opens the outside file, and playlistLeavesItsFolder now refuses the list. * fix(cli): snapshot never hands FFmpeg a project video that is a document or an escaping playlist `hyperframes snapshot` decodes held project videos with FFmpeg and FFprobe. It now runs the engine's media check first: a file that is a document, or an HLS or ffconcat list naming files outside its folder (under any extension), is skipped with a "not media" warning and never reaches FFprobe or FFmpeg. Real clips and HLS lists of segments beside them snapshot as before. * fix(engine): playlist check reads lines as bytes and refuses unreadable nested lists - Playlist text is read as latin1, one character per byte, so a line is cut at 4095 bytes exactly where ffmpeg cuts it, even when it holds bytes that are not UTF-8. Nested names are opened by those same bytes. - A nested name that exists but cannot be read is refused; a name that does not exist, or is too long to exist, is still kept. - Each name is checked once, each file is opened once (ID3 header and head in one read), and each file's verdict is reused within a call: 100k segments naming one file drop from seconds to tens of milliseconds. * perf(cli): snapshot checks each project video once and warns once when it is refused * test(engine): the ffprobe playlist proof ends its options with -- before the input * chore(engine): raise the packed size budget to 500000 bytes The byte-exact HLS playlist parser adds about 6 KB to the packed engine (496647 in CI against a 490452 budget). * fix(engine): media inspection never waits on a FIFO or device The document sniff and the playlist walk open with O_RDONLY|O_NONBLOCK where the platform has it, fstat the descriptor, and refuse anything that is not a regular file before reading; a folder still fails as it did. A FIFO with no writer, as a media source or named in a list, is refused at once. * fix(cli): snapshot inspects project videos within the probe deadline and its cleanup scope The held-video hints are gathered inside the capture's cleanup scope, and every media inspection gives up after the same 30 s limit as the FFprobe call it guards, treating the file as not media.
@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