mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-14 18:01:20 +08:00
Miguel Ángel
718c67b387
* fix(core): escape NUL delimiters in HFMASK mask token and restore regex Raw 0x00 bytes in the maskInertRegions token and restore regex made timingCompiler.ts binary to git and shipped raw NULs into dist/cli.js. Bun's transpiler (<= 1.3.11) corrupts raw NULs in regex literals into literal backslash-uFFFD text, so restore never matched: every masked <style>/<script> region was dropped, the player never initialized, and bunx renders produced blank white frames showing HFMASK tokens. Use \u0000 escapes instead, which survive any transpile layer, and add a byte-level regression test (behavior is identical under Node, so only a byte check catches this). Fixes the first half of #2139. * fix(cli): use NTFS junctions for studio project links on Windows linkProjectIntoStudioData called symlinkSync(dir, path, "dir"), which needs Developer Mode or elevation on Windows, so preview and dev in local-studio mode died with EPERM for default-configured users. Junctions need no privilege, work for directories, and keep the live write-back the studio depends on (a copy fallback would decouple the studio from the real project). Covers both preview and dev, which share the helper. Fixes the second half of #2139.
@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