Skip to main content
The core package provides the foundational types, HTML parsing/generation, runtime, and composition linter that all other Hyperframes packages build on. If you are building tooling, writing a custom integration, or extending Hyperframes itself, this is the package you need. 
npm install @hyperframes/core

​
When to Use

Most users do not need to install @hyperframes/core directly. The CLI, producer, and studio packages all depend on core internally. You only need it if you are doing one of the things listed below.
Use @hyperframes/core when you need to:
  • Lint compositions programmatically (CI pipelines, editor plugins)
  • Parse HTML compositions into structured TypeScript objects
  • Generate composition HTML from data (e.g., from an API or AI agent)
  • Access the Hyperframes type system for your own tooling
  • Embed the Hyperframes runtime in a custom player
Use a different package if you want to:
  • Preview compositions in the browser — use the CLI (npx hyperframes dev) or studio
  • Render compositions to MP4 — use the CLI (npx hyperframes render) or producer
  • Capture frames from a headless browser — use the engine

​
What’s Inside

ModuleDescription
core.typesTypeScript types for compositions, clips, timelines, and render config
parsers/HTML-to-composition parsing — turns an HTML string into a typed Composition object
generators/Composition-to-HTML generation — turns a Composition object back into HTML
runtime/The Hyperframes runtime that manages playback, seeking, and clip lifecycle
lint/Composition linter with rules for structural correctness
adapters/Frame Adapter types and the built-in GSAP adapter
templates/HTML composition templates used by hyperframes init

​
Linter

The composition linter checks for structural issues that would cause rendering failures or unexpected behavior. You can run it from the CLI with npx hyperframes lint, or call it programmatically: 
import { lintHyperframeHtml } from '@hyperframes/core';

const html = `
<div id="root" data-composition-id="root"
     data-start="0" data-width="1920" data-height="1080">
  <video id="clip-1" data-start="0" data-track-index="0"
         src="intro.mp4"></video>
</div>
`;

const issues = lintHyperframeHtml(html);
// => [{ rule: "unmuted-video", message: "Video element 'clip-1' should have the 'muted' attribute ...", severity: "warning" }]
Detected issues include:
  • Missing timeline registration (window.__timelines)
  • Unmuted video elements (causes autoplay failures)
  • Missing class="clip" on timed visible elements
  • Deprecated attribute names
  • Missing composition dimensions (data-width, data-height)
  • Invalid data-start references to nonexistent clip IDs
For a full list of what the linter catches and how to fix each issue, see Common Mistakes and Troubleshooting.

​
Types

Import the core types for use in your own tooling or integrations: 
import type {
  Composition,
  Clip,
  RenderConfig,
  FrameAdapterContext,
} from '@hyperframes/core';

// Example: define a render configuration
const config: RenderConfig = {
  fps: 30,
  width: 1920,
  height: 1080,
  quality: 'standard',
};

// Example: work with a parsed composition
function getClipCount(composition: Composition): number {
  return composition.clips.length;
}

​
Parsing and Generating HTML

Round-trip between HTML and structured data: 
import { parseHyperframeHtml, generateHyperframeHtml } from '@hyperframes/core';

// Parse HTML into a Composition object
const composition = parseHyperframeHtml(htmlString);
console.log(composition.id);       // "root"
console.log(composition.width);    // 1920
console.log(composition.clips);    // [{ id: "clip-1", start: 0, ... }, ...]

// Generate HTML from a Composition object
const html = generateHyperframeHtml(composition);
This is especially useful for AI agents that generate video programmatically — they can construct a Composition object in code and then serialize it to HTML for rendering.

​
Runtime Builds

The runtime is the JavaScript that runs inside the browser (or headless Chrome) to manage clip lifecycle, media playback, and timeline synchronization. It is built in two formats:
  • hyperframe.runtime.iife.js — injected into browser iframes for preview playback
  • hyperframe.runtime.mjs — for Node.js tooling and tests
Build the runtime from source: 
bun run --filter @hyperframes/core build:hyperframes-runtime
You should not need to build the runtime yourself unless you are developing the Hyperframes framework itself. The CLI and producer packages bundle the runtime automatically.

​
Frame Adapters

The core package defines the Frame Adapter interface — the abstraction that lets Hyperframes work with any animation runtime. The built-in GSAP adapter lives here: 
import type { FrameAdapterContext } from '@hyperframes/core';

// Every adapter must answer: "what should the screen look like at this time?"
// See the Frame Adapters concept page for the full API.

CLI

The easiest way to create, preview, lint, and render compositions.

Engine

Low-level frame capture pipeline that uses core types and runtime.

Producer

Full rendering pipeline built on top of core and engine.

Studio

Visual composition editor that embeds the core runtime for preview.