# HyperFrames Quickstart

Quick reference for installing the HyperFrames Skill and running its CLI. Full docs: <https://github.com/heygen-com/hyperframes>.

## Prerequisites

- Node.js ≥ 22. Check with `node --version`.
- No global install needed; everything runs through `npx`.

## Two Things Get Installed

| What | Command | Where it lands |
| --- | --- | --- |
| **The Skill** (Claude reads this) | `npx skills add heygen-com/hyperframes` | `.claude/skills/hyperframes/SKILL.md` |
| **The CLI** (renders the MP4) | runs on demand via `npx hyperframes …` | downloaded by npx as needed |

You install the Skill once; Claude then knows when to use HyperFrames. The CLI is invoked through `npx` at render time and does not require a separate install.

## CLI Commands

| Step | Command | What it does |
| --- | --- | --- |
| 1. Preview | `npx hyperframes preview` | Opens the composition in a browser with live reload. |
| 2. Render | `npx hyperframes render` | Writes an MP4 to the project's output directory. |
| 3. Add components (optional) | `npx hyperframes add <component-name>` | Copies a pre-built effect (e.g. `flash-through-white`) into the composition. |

`npx hyperframes init <project-name>` also exists but is **not needed in this workshop** — Claude writes `composition.html` directly into `07-skills/outputs/course-trailer/`.

## Composition Anatomy

A HyperFrames composition is a regular HTML file. Three rules to remember:

1. The root container has `data-composition-id`, `data-width`, `data-height`, and `data-start`.
2. Every visible element (`<img>`, `<video>`, `<audio>`, `<div>` overlay) needs `data-start`, `data-duration`, and `data-track-index`.
3. `data-track-index` controls layer order — lower renders behind higher.

See `composition-reference.html` in this folder for a minimal worked example.

## Common Gotchas

- Image paths in the composition are **relative to the composition file**. With `composition.html` at `07-skills/outputs/course-trailer/composition.html`, the images live at `../../inputs/slide-screenshots/...`.
- Total duration is the latest `(data-start + data-duration)` across all elements; nothing else controls length.
- Browsers block autoplay of `<audio>` without a user gesture — when previewing in browser this is normal, the render output will still include audio.

## When NOT to use HyperFrames

- For anything longer than ~30 seconds — picking individual MP4 frames by hand is faster.
- When you need real video editing (cuts, ramping, color grading) — use a real NLE.
- When the audience needs captions / accessibility — handle those in a separate pass, HyperFrames doesn't generate them.
