HyperFrames

What It Does

HyperFrames is HeyGen's open-source framework for turning HTML, CSS, and seekable animation into deterministic MP4 video, plus a pack of 20 agent skills that teach coding agents the surrounding production workflow. A composition is an HTML file whose DOM declares timing with data-attributes; the local render pipeline seeks each frame in headless Chrome and encodes with FFmpeg, so the same input is meant to produce the same video every time. The skills split into a router (/hyperframes, a state machine that resumes project state, runs an intent interview, and picks a workflow), 10 creation workflows (product launch video, PR-to-video, captions, talking-head recut, music-to-video, slideshow, motion graphics, explainer, general video, Remotion porting), and 9 domain skills covering the composition contract, animation, keyframes, creative direction, media sourcing, audio mixing, the CLI, the registry, and Figma import. The audience is developers and content teams who want their coding agent to produce short-form video as a buildable, checkable artifact, with optional cloud rendering for scale.

The Good

The core claim is true in the strictest sense: renders are byte-identical. I scaffolded a project, added two animated clips with GSAP, and rendered a 4-second video. The CLI captured 120 of 120 frames in headless Chrome, encoded with FFmpeg, self-validated the artifact, and wrote a 166.1KB MP4 in 10.5 seconds (30.1s wall time including npx and browser startup). ffprobe confirmed H.264, 1920x1080, 30fps, duration 4.000000. I then rendered the identical input a second time and compared: both files are 170,120 bytes with md5 b66813f0cdc07aff2c9d77e6584bb747. Determinism here is not marketing language; it is a reproducible property an agent or CI pipeline can assert on.

The skills are tested artifacts, which almost no skill pack does. A fresh clone with zero npm install runs npm run test:skills (plain node --test over 68 test modules) and gets 466 of 466 passing in 13 seconds, covering real behavior: packet validation atomicity, frame padding, approved-video geometry rejection, icon-font classification, and CSS sanitization around hoisted videos. The repo also carries a skills-manifest.json with a hash and file count per skill, and a CI check (scripts/check-skill-mirror.mjs) that enforces the .claude/skills and .agents/skills delivery directories stay byte-identical so one agent host cannot silently ship a stale skill.

The CLI loop catches authoring mistakes with actionable diagnostics. After I pointed window.__timelines at a nonexistent composition id, check exited 1 with a timeline_id_mismatch rule, the offending file and element, the timestamp, and the exact two-way fix. The check pipeline also runs WCAG AA contrast validation (7 of 7 text checks on my test composition) and motion diagnostics, which is a level of care beyond any video skill reviewed here.

Release engineering at a maturity most skill repos never reach. 158 per-release notes files in releases/, 100+ git tags, npm hyperframes 0.7.109 exactly matching the latest GitHub release v0.7.109 (2026-08-14), 53 contributors, pushed the morning of this review, and 13 CI workflows including CodeQL, regression, preview-regression, windows-render, and a canary sunset workflow. The scaffold itself pins hyperframes@0.7.109 in package.json scripts for reproducible renders and stamps both AGENTS.md and CLAUDE.md into new projects. Roughly 298K lines of non-test TypeScript across 14 packages back the skills.

The router skill is a real state machine, not a keyword table. The /hyperframes SKILL.md (112 lines) dispatches on project state first (Remotion port, existing project operation, existing edit, BRIEF.md present, resumable project, fresh creation), then routes fresh creations through a 10-priority table matched on deliverable rather than file type, and defines an upgrade protocol for version pins including revert-on-failed-check behavior. Domain skills use progressive disclosure properly: media-use keeps 8 reference files (resolve, treatments, recipes, grading, audio, memory) behind a 96-line entry point.

The Bad

The default install path for the skills CLI ships a broken, stale router. npx skills add heygen-com/hyperframes --skill hyperframes without --full-depth fetches the skills.sh registry blob, which currently serves a variant of the router SKILL.md that predates the July 20 route-once refactor, with the entire references/ directory missing. That stale SKILL.md itself instructs the agent to read references/brief-contract.md, a file that does not exist in the install. The README warns the blob "lags main by hours," but a month-old router with its references stripped is a structural gap, not lag, and the broken variant is what the plain documented command installs. With --full-depth the install is byte-identical to main and complete, so the fix is known and available.

Hermes and OpenClaw are supported in practice and absent from the docs. The README names Claude Code, Cursor, Gemini CLI, and Codex; grep finds zero mentions of Hermes or OpenClaw in the README or any of the 20 SKILL.md files. Meanwhile the skills CLI installs for hermes-agent fine (I verified it lands in the project-level ./.hermes/skills with full content when using --full-depth), and a CI workflow (sync-skills-to-clawhub.yml) publishes every changed skill to ClawHub at clawhub.ai/heygen-com with automatic patch-version bumps. Two working OpenClaw-ecosystem distribution paths exist and neither is mentioned in the README.

Telemetry is on by default. The first CLI invocation prints a notice that anonymous usage data is collected (file paths and composition content excluded, account-linked if you sign in to HeyGen) with hyperframes telemetry disable as the opt-out. The disclosure is honest and the data scope is scoped, but a quickstart reader who never runs the CLI interactively would not know, and the README quickstart does not mention it.

Heavy repo, and one oversized skill. The shallow clone is 250MB (the full repo is around 400MB, and development clones need git-lfs for about 240MB of golden-test MP4s). The talking-head-recut SKILL.md is 1,210 lines, well past the few-hundred-line norm that keeps context cheap; the repo's own July 20 refactor was explicitly about cutting per-run context cost, so this one is an outlier against its own design goal.

Minor rough edges. The embedded skills picker suggests --yes (-y) and --global (-g) flags that hyperframes skills update itself rejects as unknown (its real flags are --json, --dir, --source). Non-interactive init without an example fails by design but only tells you after the fact. And a clip whose timing extends past the composition end passed check with zero issues in my probe, which the engine may well clamp intentionally, but the linter is silent about it either way.

Smoke Test Results

Tested on the macOS host (aarch64, macOS 26.5.2), Node v24.13.1, FFmpeg 8.0.1, with a headless Chrome already present in the local puppeteer cache. The repo was cloned shallow (250MB, 6,820 files) and all install tests ran in isolated HOME directories or throwaway cwds.

Run A. Fresh clone, no dependencies installed

$ git clone --depth 1 --filter=blob:none https://github.com/heygen-com/hyperframes.git

✅ 250MB clone, 6,820 files, Apache-2.0 LICENSE at root

$ npm run test:skills

✅ 466/466 tests pass in 13.1s with zero node_modules present

$ npx -y hyperframes@latest --version

✅ 0.7.109, matching the latest GitHub release tag

$ npx -y hyperframes@latest init demo-video --example blank

✅ scaffold with version-pinned scripts plus AGENTS.md and CLAUDE.md stamped in

Pass rate: 4 of 4. The skill pack is testable and the CLI usable with no install step at all.

Full fresh log →

Run B. With deps preinstalled (Node 24, FFmpeg, headless Chrome): render plus install paths

$ npm run check

✅ 0 issues across 9 samples, 7/7 WCAG AA contrast checks, motion clean

$ npm run render

✅ 120/120 frames, MP4 written (166.1KB, 4.0s video, 10.5s render), artifact validated

$ HOME= npx -y hyperframes@latest skills update < /dev/null

✅ installs the 9-skill core set into ~/.claude/skills and ~/.agents/skills, exit 0

$ npx -y skills add heygen-com/hyperframes --skill hyperframes --agent hermes-agent --copy --yes

❌ installs, but the registry-blob copy is a stale variant with references/ missing

$ npx -y skills add heygen-com/hyperframes --skill hyperframes --agent hermes-agent --full-depth --copy --yes

✅ byte-identical to main, references/ included

Pass rate: 4 of 5. The badge number. Everything on the happy path works first try; the failure is the default non-full-depth registry install, which is the one variant the README's own quickstart shows first.

Full with-deps log →

Run C. Functional verification

$ ffprobe -v error -show_entries format=duration,size:stream=codec_name,width,height,r_frame_rate renders/demo-video_2026-08-17_12-04-47.mp4

✅ h264, 1920x1080, 30/1 fps, duration 4.000000, size 170120

$ npx -y hyperframes@0.7.109 render && md5 -q renders/*.mp4

✅ run 1 and run 2 md5 identical (b66813f0cdc07aff2c9d77e6584bb747), byte-identical output

$ npx -y hyperframes@latest check # after pointing window.__timelines at a bad id

✅ exit 1, timeline_id_mismatch with file, element, timestamp, and exact fix text

Functional pass rate: 3 of 3.

Full functional log →

What the runs tell you

The engine and the skills do what they claim on a local machine with no paid service, and the determinism claim survives a byte-level comparison. The one broken path is distribution, not function: how you install the skills decides whether you get a complete router or a stale one, and the default command gets the stale one.

Setup Walkthrough

1. Install the skills: npx hyperframes skills update (installs the 9-skill core set for Claude Code and Codex-style .agents hosts). For all 20 skills or a specific one, use npx skills add heygen-com/hyperframes --all --full-depth; keep --full-depth.
2. Scaffold a project: npx hyperframes init my-video --example blank, then cd my-video.
3. Edit index.html: add clips with class="clip", data-start, data-duration, data-track-index, and register a paused GSAP timeline on window.__timelines keyed by your data-composition-id.
4. Validate: npm run check (lint, runtime, layout, motion, contrast).
5. Render: npm run render writes an MP4 into renders/ with a timestamped filename.
6. If you want the telemetry off: npx hyperframes telemetry disable.

Requirements: Node 22 or newer and FFmpeg on PATH. A headless Chrome is needed for rendering; my host had one in the puppeteer cache already, so first-run browser provisioning on a clean machine was not exercised. Cloud, Lambda, and Cloud Run rendering all need accounts or credentials and were not tested.

Alternatives

1. Remotion: the established React-based renderer HyperFrames explicitly positions against. Prefer it if your team already lives in React and JSX; note its source-available license has company-size thresholds, where HyperFrames is Apache-2.0 with no commercial limits.
2. calesthio/OpenMontage: the agentic video studio GearScope reviewed at 4.5/5 (12 pipelines, 121 tools, 66 providers). Prefer it when you want multi-provider generation (TTS, images, models) orchestrated for you; prefer HyperFrames when you want a local deterministic engine you can run offline.
3. Hand-rolled Puppeteer plus FFmpeg: what this project replaces. Fine for a one-off 50-line script; you lose the composition contract, the linter, the check gates, and every skill that teaches an agent the workflow.