Files
hyperframes/packages/engine
Michael WangandClaude Opus 5.5 0e767d620f fix(producer): render-service media probes stay on public HTTPS (#7764)
* fix(producer): inline only public HTTPS scripts, under the download URL policy

The compile step fetched every external `<script src>` with a bare fetch:
any scheme, any host, redirects followed, body size unbounded.

It now fetches through the engine's download policy, the one remote
stylesheets and media already use: HTTPS only, literal and resolved
addresses public, every redirect hop checked again, connect pinned to the
checked address, and at most 16 MiB per script. A new engine helper,
fetchPublicHttpsBytes, returns the raw bytes so integrity metadata is still
checked before decoding; fetchPublicHttpsText now decodes its result.

A script outside the policy keeps its `<script src>` tag, and the capture
browser loads it as before; the log says so at info level instead of
warning that the render may fail. Scripts under the operator's
HYPERFRAMES_GSAP_BASE_URL mirror, which may be loopback HTTP, are still
inlined. An integrity mismatch still fails the render.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(producer): the audio probe skips remote video URLs outside the public HTTPS policy

A video whose remote src compile could not download keeps that URL, and
the probe-only audio pass handed it straight to ffprobe, which fetches any
scheme and host. A src that fails the literal public-HTTPS check (plain
HTTP, loopback, private, link-local or `.internal` hosts) is now skipped,
the same outcome frame extraction already gives it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(producer): the GSAP mirror exception covers only its dist folder

Scripts from the operator's HYPERFRAMES_GSAP_BASE_URL mirror are fetched
outside the public-HTTPS policy, because the mirror may be loopback HTTP.
That exception now covers only plain script file names in the GSAP dist
folder the compiler itself points at, refuses redirects and stops at
16 MiB, like every other inlined script. Any other path on the mirror's
origin follows the public-HTTPS policy and is left for the browser.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(engine): on a render service, https media inputs open only HTTPS

ffmpeg and ffprobe read some https sources in place. An https playlist
or manifest can name segments on any protocol, and the default protocol
list for an https input does not restrict them. With
PRODUCER_RESTRICT_PAGE_NETWORK=true, these inputs now pass
`-protocol_whitelist https,tls,tcp`, so segments and parts they name must
be HTTPS too. Local renders are unchanged.

A new test pins that local project files which are playlists, concat lists
or DASH manifests (with their own extension or named `.mp4`) are probed
and decoded without any request to the URLs they list: ffmpeg limits what
a local file input may open to file, crypto and data, and the concat
demuxer refuses URL entries in safe mode.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 23:25:18 +00:00
..
2026-11-14 18:15:46 -05:00

@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