mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
Vance IngallsandClaude Opus 4.6
116e6aa8e0
* feat(skills): add audio visualizer effect with extraction script Adds reactive audio visualization patterns for HyperFrames: Script: extract-audio-data.py pre-extracts per-frame RMS amplitude and frequency band data via ffmpeg. Uses a 4096-sample FFT window for clean frequency resolution and per-band normalization across the full track so treble activity is visible alongside louder bass. Patterns: spectrum bars, mirrored waveform, pulsing circle, circular visualizer, background glow — all Canvas 2D driven from the GSAP timeline via tl.call() at each frame. Includes smoothing helper, band count guide, band ordering rules (horizontal: low-left high-right), and combining patterns section. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * refactor(skills): replace prescriptive examples with data model + motion principles Removes five hardcoded draw functions that would get copy-pasted verbatim. Replaces with: - Clear data model docs (what rms and bands mean, how to index) - Rendering approach setup for Canvas 2D, WebGL/Three.js, and DOM - Motion principles (smoothing, value mapping, what makes it feel good) - Spatial mapping conventions (low-left/high-right, etc) The LLM invents the visualization; the skill teaches the data contract and motion constraints. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(skills): off-by-one in band slicing, add data loading, fix trigger - Fix exclusive slice end: high_bin clamped to n_bins (not n_bins-1) so the last FFT bin in each band is included - Add data loading section to skill doc (inline and fetch patterns) - Fix example JSON to show frame 0 at time 0.0 - Update description to trigger when audio is analyzed and music detected Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * refactor(skills): require numpy, fix bugs, clean up skill doc Script rewrite: - numpy is now required (pure-Python DFT was unusable for real files) - Use np.frombuffer instead of struct.unpack (~10x less memory) - Precompute Hann window and band edges (were recalculated every frame) - Extract SAMPLE_RATE as module-level constant - Clamp band bins to prevent max() on empty slice - Validate --fps and --bands inputs Skill doc fixes: - Fix fetch loading example (was null ref on sync for-loop) - Remove redundant Canvas 2D section (was duplicate of Step 3) - Fix opening line (said "Canvas 2D" but doc covers 3 approaches) - Fix undefined W/H in example Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Hyperframes
Write HTML. Render video. Built for agents.
Hyperframes is an open-source video rendering framework that lets you create, preview, and render HTML-based video compositions — with first-class support for AI agents via MCP.
Why Hyperframes?
- HTML-native — AI agents already speak HTML. No React required.
- Frame Adapter pattern — bring your own animation runtime (GSAP, Lottie, CSS, Three.js).
- Deterministic rendering — same input = identical output. Built for automated pipelines.
- AI-first design — not a bolted-on afterthought.
Quick Start
npx hyperframes init my-video
cd my-video
Then open the project with your AI coding agent (Claude Code, Cursor, etc.) — it has HyperFrames skills installed and knows how to create and edit compositions.
npx hyperframes preview # preview in browser (live reload)
npx hyperframes render # render to MP4
Requirements: Node.js >= 22, FFmpeg
Documentation
Full documentation at hyperframes.heygen.com — start with the Quickstart, then explore guides, concepts, API reference, and package docs.
How It Works
Define your video as HTML with data attributes:
<div id="stage" data-composition-id="my-video" data-start="0" data-width="1920" data-height="1080">
<video
id="clip-1"
data-start="0"
data-duration="5"
data-track="0"
src="intro.mp4"
muted
playsinline
></video>
<img id="overlay" data-start="2" data-duration="3" data-track="1" src="logo.png" />
<audio
id="bg-music"
data-start="0"
data-duration="9"
data-track="2"
data-volume="0.5"
src="music.wav"
></audio>
</div>
Preview instantly in the browser. Render to MP4 locally. Let AI agents compose videos using tools they already understand.
Packages
| Package | Description |
|---|---|
hyperframes |
CLI — create, preview, lint, and render compositions |
@hyperframes/core |
Types, parsers, generators, linter, runtime, frame adapters |
@hyperframes/engine |
Seekable page-to-video capture engine (Puppeteer + FFmpeg) |
@hyperframes/producer |
Full rendering pipeline (capture + encode + audio mix) |
@hyperframes/studio |
Browser-based composition editor UI |
AI Agent Skills
HyperFrames ships skills that teach AI coding agents (Claude Code, Gemini CLI, Codex, Cursor) how to write correct compositions and GSAP animations. Use these instead of writing from scratch — they encode framework-specific patterns that generic docs don't cover.
Install via CLI (recommended)
# Install all skills (HyperFrames + GSAP) — runs automatically during `hyperframes init`
npx hyperframes skills
# Or install to a specific agent
npx hyperframes skills --claude
npx hyperframes skills --cursor
Or via npx skills add
# HyperFrames skills (hyperframes-compose, hyperframes-captions)
npx skills add heygen-com/hyperframes
# GSAP skills (gsap-core, gsap-timeline, gsap-scrolltrigger, gsap-plugins, gsap-performance, gsap-utils, gsap-react, gsap-frameworks)
npx skills add greensock/gsap-skills
Installed Skills
| Source | Skills | What they teach |
|---|---|---|
| HyperFrames | hyperframes-compose, hyperframes-captions |
HTML composition structure, class="clip" rules, data-* attributes, timeline registration, rendering constraints |
| GSAP | gsap-core, gsap-timeline, gsap-performance, gsap-plugins, gsap-scrolltrigger, gsap-utils, gsap-react, gsap-frameworks |
Core API, timeline sequencing, ScrollTrigger, plugin usage, performance best practices |
In Claude Code, invoke with /hyperframes-compose, /hyperframes-captions, /gsap-core, etc.
Contributing
See CONTRIBUTING.md for guidelines on how to contribute.
License
See LICENSE for details.