mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-16 22:58:02 +00:00
The first adaptive script after the carve. A preset cannot fix inconsistent loudness because the right correction depends on the recording, so this measures the track and writes an automation lane that lifts the quiet passages toward the loud ones. It is NOT loudness normalisation and does not claim to be. Platform targets (-14 LUFS and friends) are ITU-R BS.1770 — K-weighted and gated — and this is plain windowed RMS. It is named for what it does. The lane rides a `gain` node, not the track's volume lane. Volume is 0..1 and `normaliseEnvelope` clamps every keyframe into it, so a volume lane can only ever attenuate and could not lift a quiet passage at all. The tests drove a real design change. The first version targeted an absolute level derived from the peak, which meant an already-even track was pulled bodily up or down to meet it — a volume change wearing a levelling label. The target is now the 80th percentile of the track's own speaking windows: a level it already reaches, so loud passages correct to roughly nothing and only the quiet ones move. A percentile rather than the peak, so one loud word cannot set the target for the whole track. Silence is left alone; lifting a pause only lifts the room with it. Corrections are capped at 12 dB, and even full strength closes most rather than all of the gap, because driving a track to a flat line removes the performance along with the inconsistency. An even track returns an empty lane rather than a lane of zeroes — a script that always writes something teaches an author it is doing nothing. Falsified against four mutations. Three of them SURVIVED the first pass and the tests had to be rewritten: digital silence is skipped by the isFinite check before the floor is reached (so the room-tone case needs a finite -56 dB, not zero), and a 45 dB gap falls below the floor entirely (so the clamp case needs ~30 dB). A test that cannot fail is not a test. Core 1704 -> 1720. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@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