mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-14 18:01:20 +08:00
Miguel Angel Simon Sierra
4a04b9381b
`bindMediaMetadataListeners` set `preload="auto"` and called `load()` on every `<video>`/`<audio>` in the document, unconditionally, with no window check and no distinct-source check. Every clip in a composition was told to buffer its full source before the playhead was consulted at all. Media is now fetched as the playhead approaches it. A clip whose window overlaps ten seconds ahead or two behind is raised to `preload="auto"` and loaded; the rest stay unfetched, except clips with no authored `data-duration`, held at `metadata` because their window can only come from the source. One `load()` per distinct source, so seven clips on one file are one fetch rather than seven. Half the fix has to happen at parse time. Setting `preload` at DOMContentLoaded loses the race against the resource-selection task the parser already queued: deferring only at init left 30 of the fixture's 56 elements already fetching, deferring as each element is parsed left 1. So the media registry's MutationObserver is installed from the runtime entry, at script evaluation, and marks each new element `preload="none"` unless the author asked for `preload` or `autoplay` itself. Render capture is exempt on both render signals and keeps the eager fetch: it screenshots whatever the browser has decoded when the frame is taken, so an unbuffered element there is a silent or black export. Studio's asset overlay asked whether *every* media element was buffered — an invariant this deliberately breaks, which held the overlay for its full 10 s cap and polled the document 100 times getting there. It now asks only about elements the runtime promoted. Open window of the runtime-cost gate, on the same machine and session: each media source fetched 8.0x before, 2.38x after (64 requests to 19). Of the 19, five come from the preview iframe (63 before) and fourteen from the Studio document, which U5 owns — the 1.2x budget is not reachable until that half lands.
@hyperframes/core
Types, parsers, generators, compiler, linter, runtime, and frame adapters for the Hyperframes video framework.
Install
npm install @hyperframes/core
Most users don't need to install core directly — the CLI, producer, and studio packages depend on it internally.
What's inside
| Module | Description |
|---|---|
| Types | TimelineElement, CompositionSpec, Asset, canvas dimensions, defaults |
| Parsers | parseHtml — extract timeline elements from HTML; parseGsapScript — parse GSAP animations |
| Generators | generateHyperframesHtml — produce valid Hyperframes HTML from a composition spec |
| Compiler | compileTimingAttrs — resolve data-start / data-duration into absolute times |
| Linter | lintHyperframeHtml — validate Hyperframes HTML (missing attributes, overlapping tracks, etc.) |
| Runtime | IIFE script injected into the browser — manages seek, media playback, and the window.__hf protocol |
| Frame Adapters | Pluggable animation drivers (GSAP, Lottie, CSS, or custom) |
Frame Adapters
A frame adapter tells the engine how to seek your animation to a specific frame:
import { createGSAPFrameAdapter } from "@hyperframes/core";
const adapter = createGSAPFrameAdapter({
getTimeline: () => gsap.timeline(),
compositionId: "my-video",
});
Implement FrameAdapter for custom animation runtimes:
import type { FrameAdapter } from "@hyperframes/core";
const myAdapter: FrameAdapter = {
id: "my-adapter",
getDurationFrames: () => 300,
seekFrame: (frame) => {
/* seek your animation */
},
};
Parsing and generating HTML
import { parseHtml, generateHyperframesHtml } from "@hyperframes/core";
const { elements, metadata } = parseHtml(htmlString);
const html = generateHyperframesHtml(spec);
Linting
import { lintHyperframeHtml } from "@hyperframes/core/lint";
const result = lintHyperframeHtml(htmlString);
// result.findings: { severity, message, elementId }[]
Documentation
Full documentation: hyperframes.heygen.com/packages/core
Related packages
@hyperframes/engine— rendering engine that drives the browser@hyperframes/producer— full render pipeline (capture + encode)hyperframes— CLI