mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* fix(core): blur quiets discrete callbacks instead of undoing what they wrote #7191 undid the DOM a callback wrote during the blur scan with a mutation journal. That regressed once-guarded and memoized timeline callbacks: the callback ran, its guard flipped, and the journal put the DOM back, so the real seek never wrote it again. Mute GSAP's onStart, onComplete, onReverseComplete and onRepeat for the scan and for eventful pose reads, then restore them. onUpdate keeps firing, so movers driven from it are still found. muteDiscreteCallbacks replaces a callback with a no-op rather than clearing it (hasZeroDurationCallbackTween reads typeof vars.onComplete), walks tween.timeline for staggers and keyframes, and skips an animation already muted because scene timelines nest in the root. The journal (journalDom, landThenUndoDom, putBack) is deleted. The loud rewind through 0 stays. Measured in the spike (mute-spike-report.md, "Probe matrix and fresh worker"): every GSAP pattern matches blur off in label and fire count; 8 of 300 comparisons differ, all the non-GSAP row, against 248 of 300 on main. This supersedes the limit #7191 accepted. Mute and restore over 2002 animations is 0.2 ms. Limits: - A mover that exists only because a muted callback set it up is found only if that callback fired before the scan. A worker starting before the call leaves that mover sharp while a later worker blurs it; positions stay right. - tl.call(() => gsap.to(...)) movers are never found and stay sharp. - A non-GSAP adapter that ignores suppressEvents (adapters/animejs.ts) and writes DOM on a once-only completion shows it early. Pinned by a KNOWN LIMIT test. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> * test(producer): drop the once-guard-label block-start guard that pins a block that cannot fail The guard required a block start in [1, 15], the worker at frame 9, and the comment said it paints on both sides of the call at 16. Its frames after the call (16, 17) sit inside the trail mask at the label, so that block cannot show the bug. The outside-the-trail case on the 7-worker partition is what catches the mutant; the fixture stays in FIXTURE_NAMES. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> * test(engine): split the callbacks matrix in three and share one blur-off run per row The matrix file took 247 s on an idle Mac and timed out at the flake gate's 120 s in all 10 reruns. Each row now compares the arms against one blur-off page painted in order and one fresh page, not a new blur-off page per arm and sequence; the in-order sequence is the first paints of the page that goes back to the first time; rows run their pages together; the paint skips the full-frame PNG that only the pixel tests read. Only the two arms with an onUpdate mover stay (both tiers): they run the scan's mute and the per-frame mute, which the arms without a mover do not. The rows and harness move to __fixtures__/motionBlur/callbackRows.ts and the matrix is split over three files so each run fits the gate. Rows a to y, the three sequences, both tiers, row y and the KNOWN LIMIT test are all kept; no assertion changed. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 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