hyperframes

---
name: hyperframes
description: "Use when authoring video compositions as plain HTML and rendering them to MP4 with HyperFrames — agent-first, no React, no build step. CLI: npx hyperframes init / preview / render / lint."
source: https://github.com/heygen-com/hyperframes
generated: 2026-05-07T20:57:33.432Z
category: tool
audience: creators
---

## Tutorials

- https://skillmake.xyz/v/hyperframes.mp4

## When to use

- Programmatic MP4 generation from HTML for agent-driven video pipelines
- Deterministic, reproducible video rendering in CI (no React, no bundler)
- Authoring compositions with data-start / data-duration / data-track-index timing on plain HTML
- Adding pre-built motion blocks (GSAP, Lottie, CSS, Three.js) via the catalog

## Key concepts

### HTML composition

A composition is a single HTML file. Each element carries data-start, data-duration, and data-track-index attributes (in seconds and integer track index). HyperFrames captures the headless-Chrome page and encodes frames to MP4. No React, no JSX, no build — plain HTML and CSS.

### CLI commands

init scaffolds a new project, preview live-reloads in headless Chrome while authoring, render encodes the composition to MP4, lint validates timing structure and catches overlapping or malformed data-* attributes.

### Frame adapter

Pattern for plugging in motion engines — GSAP, Lottie, CSS animations, Web Animations API, Three.js. Each adapter integrates with the deterministic frame loop so animations advance per-frame, not per-wall-clock-second.

### Catalog blocks

Reusable composition fragments installed via `npx hyperframes add <block-name>` — pre-built motion patterns like animated titles, parallax scenes, lower-thirds. Keeps repeated patterns out of every project.

### Determinism

Same HTML always produces the same MP4. The renderer drives time per-frame, not Date.now()/Math.random()-based, so output is reproducible in CI. Non-deterministic JS must be seeded or avoided.

## API reference

```
npx hyperframes init my-video
```

Scaffold a new HyperFrames project — creates a composition HTML file, package config, and example timing attributes.

```
npx hyperframes preview
```

Live-reload the composition in headless Chrome. Use during authoring to iterate on timing and visuals.

```
npx hyperframes render
```

Render the composition to MP4. Deterministic — same HTML always produces the same video, suitable for CI pipelines.

```
npx hyperframes lint
```

Validate composition structure and timing attributes. Catches missing data-start / data-duration, overlapping tracks, malformed adapter usage.

```
npx hyperframes add <block-name>
```

Install a catalog block (reusable motion component) into the current project.

```
npx skills add heygen-com/hyperframes
```

Register HyperFrames-specific agent skills (composition authoring, CLI helpers) into your agent's skill library.

```
Timing data attributes
```

Per-element timing on HTML elements within a composition. data-start in seconds, data-duration in seconds, data-track-index for layering.

```
<div data-start="0" data-duration="2" data-track-index="0">
  Title appears at 0s for 2s on track 0
</div>
```

## Gotchas

- Renders are fully deterministic — non-deterministic JS (Math.random, Date.now, network fetches at render time) will break frame-stable output unless seeded.
- Each composition runs in headless Chrome; APIs needing a real GPU/audio context may need a software fallback.
- Animations must advance via the frame loop or a frame adapter; pure setInterval/setTimeout-driven animation will desync from the rendered timeline.
- data-* timing is authoritative — overlap or contradictions across tracks won't crash the renderer but will produce a confusing MP4. Run lint.

---
Generated by SkillMake from https://github.com/heygen-com/hyperframes on 2026-05-07T20:57:33.432Z.
Verify against source before relying on details.

File: ~/.claude/skills/hyperframes/SKILL.md