HyperFrames: Rendering Deterministic MP4 Video From Plain HTML

Table of Contents

Why This Repo, Why Now

Checking github.com/trending today, the top repository is heygen-com/hyperframes, described by its maintainers as an open-source framework for “turning HTML, CSS, media, and seekable animations into deterministic MP4 videos.” Instead of authoring video through a proprietary timeline editor or a React-based framework, HyperFrames treats a video composition as a plain index.html file with data-* timing attributes — something both humans and AI coding agents can write and reason about directly.

The project’s trending spike lines up with a fast-moving release cadence: the repository is currently on tag v0.8.30, iterating rapidly toward a 1.0. HyperFrames is developed and used in production at HeyGen, with the README listing community adopters such as tldraw and TanStack in ADOPTERS.md. Its core hook for the current AI-agent tooling wave is a set of 20 published “skills” that teach Claude Code, Cursor, Gemini CLI, Codex, and other agents the specific production loop for building a video: plan, write valid HTML, wire seekable animations, add media, lint, preview, and render. That combination — HTML-native authoring plus first-class agent skills — is almost certainly what’s driving today’s trending position. As always, a trending spot reflects visibility and momentum, not a verdict on quality, security, or production-readiness; those are checked independently below.

What the Technology Actually Is

Per the README and repository structure, HyperFrames is a TypeScript monorepo built and scripted with Bun, distributed as a set of npm packages under the Apache 2.0 license. The rendering pipeline itself seeks each frame of a composition in headless Chrome (Puppeteer) and encodes the result with FFmpeg, so the same HTML input deterministically produces the same output video — a property the maintainers highlight as useful for CI, regression tests, and automated rendering pipelines.

Key architectural pieces, per the documented package layout:

• hyperframes (CLI) — scaffolds (init), previews with live reload, lints, inspects (compositions, doctor, info), and renders (render) local video projects.
• @hyperframes/core — types, parsers, generators, linter, runtime, and the “frame adapters” that connect a composition to different animation runtimes.
• @hyperframes/engine — the seekable page-to-video capture engine built on Puppeteer and FFmpeg.
• @hyperframes/producer — the full rendering pipeline: capture, encode, and audio mixing.
• @hyperframes/studio — a browser-based composition editor UI.
• @hyperframes/player — an embeddable <hyperframes-player> web component.
• @hyperframes/shader-transitions — WebGL shader transitions usable inside compositions.
• @hyperframes/aws-lambda — an SDK and deployment surface for distributed, cloud-based rendering on AWS Lambda.

At a high level: a composition is an HTML document where elements carry class="clip" plus data-start/data-duration/data-track-index attributes; animation is wired through an adapter (GSAP, CSS, Lottie, Three.js, Anime.js, WAAPI, or a custom runtime). The CLI’s preview server renders that HTML live in a browser, and the render pipeline drives headless Chrome frame-by-frame, capturing and encoding through FFmpeg — no bundler or build step is required to play the raw index.html in a browser.

Purpose and Use Cases

The primary purpose is turning a design or script into a rendered video without requiring a video-editing tool or a React build pipeline. Per the README’s “What You Can Build” and stack sections:

• Product and marketing teams generating launch videos, feature announcements, and site-tour explainers from a design brief.
• Developer-relations and engineering teams turning GitHub pull requests into changelog or feature-reveal videos via the documented /pr-to-video skill, which reads the PR through the gh CLI.
• Data and analytics teams building animated charts, data visualizations, and map animations from the reusable Catalog blocks.
• Content and social teams producing kinetic-caption social clips, motion graphics, and music-synced videos.
• Platform engineers wiring automated, agent-driven content pipelines — e.g., generating a batch of on-brand videos in CI using the deterministic renderer and the AWS Lambda distributed-rendering path.

It is explicitly positioned against Remotion: both render with headless Chrome and FFmpeg, but Remotion’s authoring model is React components under a source-available license, while HyperFrames’ bet is plain HTML/CSS under Apache 2.0, with no per-render fees or commercial-use thresholds documented.

Installation

Per the project’s README and the hyperframes CLI package README.

Prerequisites

• Node.js >= 22
• FFmpeg installed and available
• (Optional, for agent workflows) an AI coding agent that supports skills — Claude Code, Cursor, Gemini CLI, or Codex

Recommended: install the CLI

npm install -g hyperframes

Or invoke it directly without a global install:

npx hyperframes <command>

Minimal getting-started example

npx hyperframes init my-video
cd my-video
npx hyperframes preview      # preview in browser with live reload
npx hyperframes render       # render to MP4

Alternative: install agent skills

For teams working through an AI coding agent rather than the raw CLI, the README documents:

npx skills add heygen-com/hyperframes

Agents and non-interactive runs are told to use npx hyperframes skills update instead, since the interactive picker in skills add can lag behind main by hours.

Cloning the full monorepo (contributors)

The repository uses Git LFS for golden regression-test video baselines (~240 MB). The README documents installing Git LFS first (brew install git-lfs, apt install git-lfs, or winget install GitHub.GitLFS, then git lfs install), or skipping that content entirely for a source-only clone:

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/heygen-com/hyperframes.git

The README recommends the global/npx CLI install as the primary path for using HyperFrames; cloning the monorepo is only necessary for contributing to the framework itself.

Quick Verification

Based on the documented CLI commands:

1. Environment check — npx hyperframes doctor checks the local environment for the required dependencies (Chrome, FFmpeg, Node.js) and reports what’s missing.
2. Version/info check — npx hyperframes info prints version and environment info, confirming the CLI installed correctly.
3. Scaffold check — npx hyperframes init my-video should create a runnable starter project.
4. Preview check — npx hyperframes preview should open a live-reloading studio in the browser (default http://localhost:3002), confirming the composition parses and plays.
5. Render check — npx hyperframes render -o output.mp4 completing and producing a playable MP4 confirms the full capture-and-encode pipeline works end to end.
6. Lint check — npx hyperframes lint ./my-composition validates composition HTML and is documented as CI-friendly via its --json output.

Security Review

Verified from the repository itself:

• SECURITY.md documents a private disclosure process via a GitHub Security Advisory, explicitly asking that vulnerabilities not be filed as public issues, with acknowledgment targeted within 48 hours and a fix or mitigation plan within 7 days.
• Per SECURITY.md, only the 0.x version line is currently marked supported, and the stated scope covers all packages under the @hyperframes/* npm scope plus the repository code itself.
• License is Apache 2.0, a permissive license that disclaims warranty and limits contributor liability (see the LICENSE file’s Sections 7–8) — standard terms, not a security guarantee.
• The project has a very active release cadence (tag v0.8.30 at time of writing), suggesting frequent iteration, but pre-1.0 software should still be expected to have breaking changes and unresolved rough edges.
• No published GitHub Security Advisories were found against this repository at the time of writing; absence of advisories is not proof of absence of vulnerabilities.

Security considerations to weigh yourself (not verified as vulnerabilities, just documented factors that matter for this class of tool):

• The rendering pipeline drives headless Chrome to render arbitrary HTML/CSS/JS compositions and pulls in scripts from CDNs (the README’s own example loads GSAP from cdn.jsdelivr.net) — treat any composition sourced from an untrusted party the same way you’d treat any other HTML/JS you didn’t author yourself, since it executes in a real browser engine.
• The CLI’s publish command can upload a project directory to a hosted URL; published projects are private by default, but review what a project directory contains (API keys, local file paths) before publishing, and use --public deliberately.
• The render and benchmark commands drive a bundled Chrome/Chromium installation and FFmpeg locally — evaluate what privileges your CI runner or developer machine grants these processes, particularly if rendering untrusted third-party compositions.
• The distributed rendering path (@hyperframes/aws-lambda) deploys infrastructure into your own AWS account; review the IAM permissions and Lambda configuration it provisions before using it in a shared or production AWS environment.
• As with any framework that recommends npx <package> execution, npx fetches and runs code from the npm registry; pinning a version avoids silently picking up a new, unreviewed release.

Practical recommendations:

• Pin a specific published version of the hyperframes CLI and @hyperframes/* packages rather than always resolving latest via bare npx hyperframes in CI.
• Review any third-party HTML compositions, catalog blocks, or agent-generated compositions before rendering them, since rendering executes arbitrary HTML/JS in headless Chrome.
• Run first evaluations of the CLI, Studio, and any AWS Lambda rendering path in an isolated sandbox or throwaway cloud account before wiring in production credentials.
• Audit IAM permissions granted to the @hyperframes/aws-lambda deployment before using it against a shared AWS account.
• Report suspected vulnerabilities privately through the documented GitHub Security Advisory process rather than as a public issue.

Should You Use It?

Strengths: genuinely HTML-native authoring with no build step required to preview a composition, a deterministic frame-accurate rendering pipeline built for CI/regression use, a permissive Apache 2.0 license with no per-render fees, a documented private vulnerability-disclosure process, and an unusually deliberate agent-skills design (20 published skills plus a router) aimed squarely at the current AI-coding-agent workflow.

Limitations: the project is still pre-1.0 (v0.8.30 at time of writing), so APIs and CLI behavior can still shift between releases; it’s a young enough project that its long-term maintenance track record is not yet established; and, like Remotion, it depends on headless Chrome and FFmpeg as runtime dependencies that must be present and kept up to date wherever it runs.

Good fit for: teams that want agent-generated or CI-generated video (product launches, PR walkthroughs, data visualizations, social clips) without adopting a React-based rendering stack, and developers already using coding agents who want a documented, skill-based production workflow instead of ad hoc prompting.

Evaluate alternatives if: you need a rendering framework with a longer production track record and a mature ecosystem — Remotion is the maintainers’ own documented comparison point — or your team is already standardized on React-based composition authoring and doesn’t need HTML-native, no-build-step compositions.

Primary sources used: GitHub repository · README · CLI package README · SECURITY.md · Security Advisories · LICENSE · Tags