Files
hyperframes/packages/core
Miguel Angel Simon Sierra d302bc0f44 fix(audio): carry authoring gain above unity into preview and render
`HTMLMediaElement.volume` is spec-clamped to [0,1], so both timeline probes
lost a clip's authored gain the moment it also carried a fade: the probe
seeded the element at the clamped value and every sample read back at or
below 0 dB, and the mixer prefers probed keyframes over the static volume.
Both probes now shadow the accessor for their own duration and forward the
clamped value to the native setter, so the authored gain survives while
nothing outside the probe ever sees an illegal volume.

Measured on one 6 s composition, first 4 s: unity -32.8 LUFS, boosted -27.0,
boosted-with-fade -32.8 before and -27.0 after — +5.8 dB, exactly the gain
the clip was authored at.

Collapse the other owners of the same decision, each of which kept preview
and render disagreeing on their own: the Web Audio master gain had two
writers, so unmuting discarded the user's volume; the user's volume was
applied twice, once per clip and once on the master; and the control bridge
wrote `el.volume` for clips the transport already owned, which the next tick
read back as the clip's author gain. `<video data-has-audio>` is never
scheduled as a buffer source, so it now routes through a media-element gain
node — but only while the audio context is running, since routing into a
suspended graph would silence audio the native path is playing.
2026-08-17 14:19:31 -04: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