Files
hyperframes/packages/core
Miguel Angel Simon Sierra 95fb938f2f perf(runtime): scale media sync with the active window, not the document
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.
2026-08-03 21:56:02 -07:00
..
2026-08-02 21:57:19 -07:00

@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