mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-17 23:47:33 +00:00
Every seek rebuilt the media cache with a full-document
`querySelectorAll("video, audio")` and then evaluated relative time,
held-tail math and `isActive` for every clip in the composition. On the
gate fixture a single scrub drag issued 42 of those scans inside the
preview iframe.
The element list is now a registry rebuilt only when a mutation adds or
removes media. Pending mutation records are drained synchronously at read
time, so a sub-composition injected and seeked in the same task still
renders with its media rather than lagging a microtask behind.
The per-tick loop visits a transition set — clips in window now, plus the
ones that were in window last tick. Departures are the reason it is a
union and not a point query: the playhead crosses a clip's `end` between
frames, and the tick that has to pause the clip is the one where it is
already out of window. Nothing else pauses it (`hardSyncAllMedia` only
assigns `currentTime`), so a missed departure is audio running past its
clip edge for the rest of an exported video. An element first seen out of
window is checked once, which keeps an authored `autoplay` element from
starting unattended.
Scrub window of the runtime-cost gate: 51 full-document media queries
before, 12 after; the media-sync scan itself drops from 42 to 1. The
remaining 12 belong to the duration probes, `bindMediaMetadataListeners`
(U6) and three player-side call sites.
@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