hyperframes

HyperFrames

What you are

You are the HyperFrames integration and engineering contract navigation, not another animation style. HyperFrames deterministically renders HTML, CSS, media, and seekable animations into MP4, and can serve as the production foundation for code-mv-render, data videos, or product videos.

• Upstream:https://github.com/heygen-com/hyperframes
• Official docs:https://hyperframes.heygen.com/introduction
• Engineering and rendering spec:references/composition-contract.md

This directory does not vendor the HyperFrames engine or official Skills. For actual production, install the upstream CLI/plugin and prioritize reading upstream /hyperframes and /hyperframes-cli; this directory is only responsible for quick location and integration.

When to use

Requirement	Decision
Multiple compositions, media tracks, subtitles, variable batching, unified local/cloud export	Choose HyperFrames
Want to continue editing HTML video timelines in Studio	Choose HyperFrames
Already have a self-contained Canvas short and only need lightweight frame-by-frame export	Can stay with code-mv-render, don't migrate just for the sake of migrating
Only want one hand-drawn/typographic style	Look at opus-video-skills or lemo-opuscarfirst, then decide the foundation
Only need to scan existing MP4	Use video-qa-frameproof, no HyperFrames needed

Core workflow

Step 1 — Install and determine project boundaries

Requires Node.js 22+, FFmpeg; local Chrome is diagnosed/installed by upstream tools. Agent projects can install core Skills:

npx hyperframes skills update
npx hyperframes init my-video

Claude Code can also use the upstream versioned plugin:

claude plugin marketplace add heygen-com/hyperframes
claude plugin install hyperframes@hyperframes

Do not init directly in this navigation directory; enter the user's actual video project. When reusing existing visual blocks, use the upstream registry/catalog first and do not rewrite existing components by hand. If the project already has a renderer, assess migration cost first and do not force a change of foundation.

Step 2 — Express video with composition and timeline

Root index.html mounts scenes,compositions/ stores reusable scenes,assets/ stores local assets. Each composition registers a paused GSAP timeline, which the renderer seeks; do not play()。

• Root data-duration is the final video length;.clip uses data-start / data-duration to express the visible window.
• Scene host, scene root, and timeline key use the same composition id; scene file content goes inside <template> .
• Within a scene use fromTo to ensure reverse seeking can rebuild; do not embed scene timelines into the root timeline again.
• Animations, media, fonts, and network resources must be deterministically readable before export. Offline projects should prefer local resources and retain licenses.

Step 3 — Check and actually look at the frames

npx hyperframes lint
npx hyperframes check --json
npx hyperframes snapshot
npx hyperframes preview

lint is used during authoring,check --json is the runtime/layout/contrast gate; "0 samples" cannot count as a completed check. Review each snapshot one by one, covering every scene, key action, transition, and ending. If the user needs to confirm a preview, stop at the user's pace; if the user authorizes direct completion, continue to export.

Step 4 — Render and review the final video

npx hyperframes render --quality draft --output out-draft.mp4
npx hyperframes render --quality delivery --output out.mp4
ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1 out.mp4

Before delivery, confirm that the file is non-empty and the duration matches the root data-duration, and inspect the decoded frames and audio track of the final MP4. When reproducible containers, variable batching, or Lambda/Cloud Run are needed, use the corresponding upstream commands; cloud/online assets, transcription, or TTS must not be called a fully offline workflow.

Hard constraints

• Do not read wall-clock-driven frames, and do not let animations depend on timers playing naturally, cross-frame state, or unseeded random numbers.
• Do not use real-time screen recording as a substitute for deterministic frame-by-frame rendering.
• check passing does not equal visual acceptance; you must still open the images to inspect them, and re-check the final encoded file.
• Do not use layout-exemption attributes to conceal real occlusion; apply precise exemptions only to the minimal nodes that are intentionally designed.
• HyperFrames is a general-purpose tool; do not write it as exclusive to Opus 5.5 or as something that must be run by it.

Sources and licensing

Upstream is Apache-2.0. Third-party blocks, fonts, media, generation services, and user assets are each subject to their own terms. Preview images come from upstream documentation; attribution and paths are in this directory README.md。