mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-16 22:58:02 +00:00
"Shape One Range" has three controls and no honest way to nominate one of them as the knob that matters. The copy nominated *how much*, which is incoherent: boosting an unspecified frequency means nothing. The range is the first decision, not the second — `plans/audio-fx-ux/README.md` §"The hole in the single-knob rule", where B is named as the answer. So the add menu offers the decision instead of the machine. Five jobs — Tame Boominess, Reduce Mud, Reduce Boxiness, Add Clarity, Soften Harshness — each a peaking filter with its frequency already chosen, low to high, which is the order an author hears them in. Picking the module is picking the range, so one knob is honest rather than a simplification hiding the real choice. `peaking` is no longer offered as itself: two doors to the same effect, one of them the incoherent one, is worse than either alone. Every job is one the preset catalogue already ships, at the settings it ships it with — a test asserts that. The list names the vocabulary the presets were written in rather than inventing a second one beside it, and a job nobody's preset does would be a guess about what authors want. It needs no new node field. `label` already names a node for the work it does, so a job node and a preset node are indistinguishable afterwards — which is right, because they are the same idea. It also dissolves the duplicate-name problem at the root rather than papering it: Clean Voice reads Remove Rumble · Reduce Mud · Even Out Loudness · Add Clarity · Peak Ceiling, and nothing repeats. Underneath it is an ordinary peaking node. Details opens on the same three controls it always had, and the frequency is a starting point rather than a cage. Falsified: offering `peaking` alongside its jobs fails the menu test. Note for the next session: adding a core subpath needs `bun run build` in packages/core, not just the subpath sync. Studio's PropertyPanel tests resolve `@hyperframes/core/*` through the `node` condition, which points at `dist/` — so a new module resolves in the FX tests and fails in those with a "does the file exist?" that looks like a config error. core 1750 passing (112 files), studio 3687 passing / 18 todo.
@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