HyperFrames Composition Project

Skills — USE THESE FIRST

Always invoke the relevant skill before writing or modifying compositions. Skills encode framework-specific patterns (e.g., window.__timelines registration, data-* attribute semantics, shader-compatible CSS rules) that are NOT in generic web docs. Skipping them produces broken compositions.

Skill	Command	When to use
hyperframes	`/hyperframes`	Creating or editing HTML compositions, captions, TTS, audio-reactive animation, marker highlights
hyperframes-cli	`/hyperframes-cli`	Dev-loop CLI: init, lint, inspect, preview, render, doctor
hyperframes-media	`/hyperframes-media`	Asset preprocessing: tts (Kokoro), transcribe (Whisper), remove-background (u2net)
hyperframes-registry	`/hyperframes-registry`	Installing blocks and components via `hyperframes add`
website-to-hyperframes	`/website-to-hyperframes`	Capturing a URL and turning it into a video — full website-to-video pipeline
tailwind	`/tailwind`	Tailwind v4 browser-runtime styles for projects created with `hyperframes init --tailwind`
gsap	`/gsap`	GSAP animations for HyperFrames — tweens, timelines, easing, performance
animejs	`/animejs`	Anime.js animations registered on `window.__hfAnime`
css-animations	`/css-animations`	CSS keyframes that HyperFrames can pause and seek
lottie	`/lottie`	`lottie-web` and dotLottie players registered on `window.__hfLottie`
three	`/three`	Three.js scenes rendered from HyperFrames `hf-seek` events
waapi	`/waapi`	Web Animations API motion driven through `document.getAnimations()`

Skills not available? Ask the user to run npx hyperframes skills and restart their agent session, or install manually: npx skills add heygen-com/hyperframes.

Commands

npm run dev          # start the preview server (long-running — keep it alive in background)
npm run check        # lint + validate + inspect
npm run render       # render to MP4
npm run publish      # publish and get a shareable link
npx hyperframes lint --verbose  # include info-level findings
npx hyperframes lint --json     # machine-readable output for CI
npx hyperframes docs <topic> # reference docs in terminal

npm run dev is a long-running server, not a one-shot command. It blocks until stopped. In Claude Code, always run it with run_in_background: true. Never run it as a foreground command — it will time out and the server will die, breaking the browser preview.

Documentation

For quick reference, use the local CLI docs command (no network required):

npx hyperframes docs <topic>

Topics: data-attributes, gsap, compositions, rendering, examples, troubleshooting

For full documentation, discover pages via the machine-readable index — do NOT guess URLs:

https://hyperframes.heygen.com/llms.txt

Project Structure

index.html — main composition (root timeline)
compositions/ — sub-compositions referenced via data-composition-src
meta.json — project metadata (id, name)
transcript.json — whisper word-level transcript (if generated)

Linting — ALWAYS RUN AFTER CHANGES

After creating or editing any .html composition, always run the full check before considering the task complete:

npm run check

Fix all errors before presenting the result. Inspect warnings should be reviewed before rendering.

Key Rules

Every timed element needs data-start, data-duration, and data-track-index
Elements with timing MUST have class="clip" — the framework uses this for visibility control

Timelines must be paused and registered on window.__timelines:

window.__timelines = window.__timelines || {};
window.__timelines["composition-id"] = gsap.timeline({ paused: true });

Videos use muted with a separate <audio> element for the audio track
Sub-compositions use data-composition-src="compositions/file.html" to reference other HTML files
Only deterministic logic — no Date.now(), no Math.random(), no network fetches

5.0 KiB Raw Permalink Blame History