Sandbox::https://hyperframes.heygen.com/packages/core

@hyperframes/core contains the shared composition model and browser runtime used across HyperFrames. Most people should use the CLI, Studio, or SDK. Install Core directly when you are generating composition HTML, compiling projects, building tooling around the shared types, or embedding the runtime.

npm install @hyperframes/core

Main surfaces

Need	Import
Types, generators, and common utilities	`@hyperframes/core`
Timing compilation and project bundling	`@hyperframes/core/compiler`
Variable declarations and validation	`@hyperframes/core/variables`
Composition contract helpers	`@hyperframes/core/composition-contract`
Prebuilt browser runtime	`@hyperframes/core/runtime`

The standalone Parsers and Linter packages own those concerns for new integrations. Core retains compatibility re-exports for some older imports.

Types

import type {
  CanvasResolution,
  CompositionSpec,
  CompositionVariable,
  TimelineCompositionElement,
  TimelineElement,
  TimelineMediaElement,
  TimelineTextElement,
} from "@hyperframes/core";

Composition variables support string, number, color, boolean, enum, font, and image values.

Parse or generate HTML

Core re-exports the common parsing helpers:

import { extractCompositionMetadata, parseHtml } from "@hyperframes/core";

const parsed = parseHtml(html);
const metadata = extractCompositionMetadata(html);

console.log(metadata.compositionId, metadata.compositionDuration, metadata.variables);

Generate a complete composition from TimelineElement data:

import { generateHyperframesHtml } from "@hyperframes/core";

const html = generateHyperframesHtml(elements, 6, {
  compositionId: "product-intro",
  resolution: "landscape",
  animations,
  styles,
});

The second argument is the requested duration in seconds. Pass a stable compositionId when output must be reproducible. Composition generators require trusted authors for code-bearing inputs. styles and generateHyperframesStyles preserve authored CSS, which can load external resources. animations may contain __raw: values that are emitted as JavaScript; includeScripts: true includes executable timeline code. serializeGsapAnimations also accepts raw preamble, postamble, and a code-bearing timelineVar. Never fill these inputs with untrusted data. Attribute encoding and closing-tag containment are not a sandbox; render untrusted compositions in an appropriately isolated execution environment and never serve them on a privileged origin. Text content retains the supported inline-formatting sanitizer contract. The clip parser intentionally flattens inner formatting to text, so parse/generate is not a lossless replacement for editing the source HTML.

Read and validate variables

Inside a composition script, getVariables() reads declared defaults plus the values supplied for the current preview or render:

import { getVariables } from "@hyperframes/core";

const { title } = getVariables<{ title: string }>();

In Node tooling, validate a values object against declarations parsed from the composition:

import { formatVariableValidationIssue, validateVariables } from "@hyperframes/core";

const issues = validateVariables({ title: "Launch day" }, metadata.variables);

for (const issue of issues) {
  console.warn(formatVariableValidationIssue(issue));
}

Compile a project

Use the compiler entry when your integration needs resolved media timing or a single bundled document.

import { bundleToSingleHtml, compileHtml } from "@hyperframes/core/compiler";

const compiled = await compileHtml(rawHtml, "./project", async (mediaPath) =>
  probeDuration(mediaPath),
);

const bundled = await bundleToSingleHtml("./project", {
  entryFile: "index.html",
});

Bundling preserves data URLs and commas inside image srcset URLs on <img> and <source> elements. Eligible local candidates are inlined by default; with inlineAssets: false, they stay as paths relative to the project root, including when the entry file is in a subdirectory. Width and density descriptors are preserved. Mounted scenes resolve their srcset candidates from the scene’s own directory when the files exist there, with project-root paths as the fallback. Local stylesheet @import rules keep each occurrence’s media condition and cascade position, even when several imports reference the same file. Circular imports stop at a stylesheet already being expanded. Repeated imports add copies of the stylesheet to the bundle, which can increase its size. Inlined local assets drop cache-busting queries and keep fragments. For example, image.png?v=2#sprite becomes a data URL ending in #sprite. With inlineAssets: false, both the query and fragment stay on the file URL. The compiler also exposes lower-level timing helpers such as compileTimingAttrs(), injectDurations(), and extractResolvedMedia().

Check the static contract

import { validateHyperframeHtmlContract } from "@hyperframes/core/compiler";

const result = await validateHyperframeHtmlContract(html);

if (!result.isValid) {
  console.error(result.missingKeys);
}

For the full composition lint result, use @hyperframes/lint or run npx hyperframes lint.

Build a frame adapter

Frame adapters make an animation runtime seekable by frame. Core includes the GSAP adapter:

import { createGSAPFrameAdapter } from "@hyperframes/core";

const adapter = createGSAPFrameAdapter({
  id: "product-intro",
  fps: 30,
  timeline,
});

await adapter.init?.({
  compositionId: "product-intro",
  fps: 30,
  width: 1920,
  height: 1080,
});

await adapter.seekFrame(42);

Composition schema

Learn the HTML contract that Core reads and writes.

@hyperframes/parsers

Work directly with HTML and GSAP parsing.

@hyperframes/lint

Validate composition HTML in your own tooling.

@hyperframes/producer

Turn a project into a finished video from Node.js.

Start here

Command line

SDK guides

SDK reference

Composition, design & animation

Composition reference

Rendering paths

Cloud infrastructure

Advanced rendering

Packages

Agent setup

Contributing & community

@hyperframes/core

Main surfaces

Types

Parse or generate HTML

Read and validate variables

Compile a project

Check the static contract

Build a frame adapter

Composition schema

@hyperframes/parsers

@hyperframes/lint

@hyperframes/producer

​Main surfaces

​Types

​Parse or generate HTML

​Read and validate variables

​Compile a project

​Check the static contract

​Build a frame adapter

​Related topics

Composition schema

@hyperframes/parsers

@hyperframes/lint

@hyperframes/producer

Main surfaces

Types

Parse or generate HTML

Read and validate variables

Compile a project

Check the static contract

Build a frame adapter

Related topics