Jonathon's AI Wiki

HeyGen Hyperframes

14 min read

Source: Hyperframes GitHub repo, Hyperframes prompting guide, raw/HyperFrames_-_Code_Your_Videos_in_HTML_No_Timeline_Required_HeyGen.md (HeyGen Level Up series, 2026-05-22)

Hyperframes is HeyGen’s open-source video rendering framework (Apache 2.0, 2.6k stars) where video compositions are written as plain HTML with data-* attributes and rendered to MP4 via Puppeteer + FFmpeg. It’s the composition layer — motion graphics, captions, transitions, TTS, and layout, authored by an AI agent. The framework ships installable skills (npx skills add heygen-com/hyperframes) that teach Claude Code, Cursor, Codex, and Gemini CLI the composition rules so the agent gets HTML, timelines, and GSAP easing right on the first prompt.

Key Takeaways

  • Tagline: “Write HTML. Render video. Built for agents.” Compositions are plain HTML with data-start / data-duration / data-track-index attributes — no proprietary DSL, no React components.
  • Three slash commands installed by one command. npx skills add heygen-com/hyperframes registers /hyperframes (composition), /hyperframes-cli (init/lint/preview/render/transcribe/tts), and /gsap (animation API) into Claude Code / Cursor / Codex / Gemini CLI.
  • Non-interactive CLI by design. npx hyperframes init | preview | render is agent-friendly — no prompts, no TTY interaction, deterministic outputs (identical inputs → identical outputs) for automated pipelines.
  • Frame Adapter pattern. Supports multiple animation runtimes side-by-side: GSAP, Lottie, CSS animations, Three.js. One composition can mix them.
  • Six-package monorepo. hyperframes (CLI), @hyperframes/core (types/parsers/runtime), @hyperframes/engine (Puppeteer + FFmpeg capture), @hyperframes/producer (full pipeline), @hyperframes/studio (browser editor), @hyperframes/player (embeddable web component).
  • Two prompt shapes for agents. Cold start — describe duration, aspect ratio, mood, key elements from scratch. Warm start — feed a URL / PDF / CSV / transcript and ask for synthesis (e.g., “turn this changelog into a 30s release announcement”).
  • Natural-language easing vocabulary. smooth, snappy, bouncy, springy, dramatic, dreamy map to GSAP eases (power2.out, power4.out, back.out, elastic.out, expo.out, sine.inOut). Timing shorthand: fast 0.2s / medium 0.4s / slow 0.6s / cinematic 1–2s.
  • Caption tone presets. Hype, Corporate, Tutorial, Storytelling, Social — each defines typography, animation, and size ranges. Per-word styling is supported (“make brand names larger with accent color”).
  • Local Kokoro TTS, no API key. Voices bucketed by content type (product demo / tutorial / marketing). Requestable in natural language: “British male voice at 1.1× speed.”
  • Seven technical rules the skill enforces automatically. Register timelines on window.__timelines, videos must be muted (audio in separate <audio> elements), no Math.random(), synchronous timeline construction (no async/await in GSAP setup), timed elements need class="clip", entrance animations on every scene, scene-to-scene transitions.
  • 50+ prebuilt blocks. Shader transitions, social overlays, data visualizations, cinematic effects — npx hyperframes add, browsable at hyperframes.heygen.com/catalog.
  • Node.js ≥ 22 + FFmpeg. Those are the only runtime dependencies.
  • Apache 2.0. Forkable, self-hostable, commercial use permitted.
  • frame.md templates + design.md→frame.md tooling (2026-06-09). [X signal — HeyGen / @liu8in 2026-06-09] HeyGen open-sourced 10 frame.md templates to uplevel compositions, plus a free tool that generates a frame.md from a design.md (getdesign.md). The showcased workflow is design-system-first: take a brand’s design.md, convert to frame.md, then have the agent build the full ad — the Ollama promo demo ran Claude Code → HyperFrames → HeyGen MCP/CLI → rendered ad. (Source: raw/x-bookmarks-recent-digest-2026-06-09.md, raw/x-bookmark-2064073876817268908.md.)
  • Now an official @claudeai connector (2026-06-09). [X signal — HeyGen] HyperFrames is now an official Claude connector, running as an MCP inside Claude so the agent turns dense docs/answers into video where you work (“docs get skimmed, video gets understood”). Productizes the Claude Code → HyperFrames pipeline as a first-class claude.ai connector (see Claude connectors). (Source: raw/x-bookmarks-recent-digest-2026-06-10.md.)

Why It Matters

  • Closes the agent-authoring gap for motion graphics. Generating motion graphics from prompts has historically required hand-rolling prompt patterns against a React-based framework. Hyperframes ships that as an official skill with enforced conventions — the agent gets the rules before it writes the first line.
  • HTML is a more portable target than React. Every team member can read a Hyperframes composition without understanding component state or JSX. Lowers the review bar for non-engineering collaborators.
  • Deterministic rendering is a scheduled-agent-friendly contract. Same HTML + assets → same MP4. That’s what you need to wire video rendering into a scheduled agent: no flaky replays, no “why is this frame different.”
  • Non-interactive CLI fits the Claude Code / subagent model. A subagent can run npx hyperframes render without a human in the loop — contrast with tools that require clicking through a UI.

Implementation

Tool/Service: HeyGen Hyperframes (open source, github.com/heygen-com/hyperframes, Apache 2.0)

Setup (agent workflow, recommended):

  1. In the project directory, run:

    npx skills add heygen-com/hyperframes

    This installs the /hyperframes, /hyperframes-cli, and /gsap skills into Claude Code.

  2. Scaffold a new video project:

    npx hyperframes init my-video
cd my-video

  3. Open the project in Claude Code. Prompt with the slash command explicitly — e.g.

    /hyperframes Create a 10-second product intro, 9:16 vertical, warm grain analog mood, fade-in title over a dark background, lower third at 0:03 with tagline, Kokoro af_heart voiceover reading the script.

  4. Preview live in a browser while iterating:

    npx hyperframes preview

  5. Iterate with small targeted prompts — “make the title 2x bigger,” “swap to dark mode,” “move the captions up.” Avoid re-specifying from scratch.

  6. Final render:

    npx hyperframes render --output final.mp4

Setup (manual, no agent): Steps 2, 4, 6 work standalone — but you write the HTML by hand. The agent path is the intended one.

Cost:

  • Hyperframes itself: free (Apache 2.0). ^[inferred — pricing not on the GitHub or prompting-guide pages]
  • Rendering compute: your local machine (Puppeteer + FFmpeg). ^[inferred]
  • Kokoro TTS: free, runs locally, no API key.

Integration notes:

  • Node.js ≥ 22 and FFmpeg are required. Expect a one-time install bump on older dev boxes.
  • Works with Claude Code, Cursor, Gemini CLI per the repo; Codex works per the prompting guide.
  • Deterministic rendering means compositions can be version-controlled and re-rendered from any commit — useful for asset refresh cycles.
  • The @hyperframes/player web component is the path for embedding a live-previewable composition in a browser-based review tool. ^[inferred]
  • Plain-HTML output should be much easier for non-engineering reviewers to comment on line-by-line than Remotion’s React tree.

Prompting Patterns Worth Stealing

Applicable to any motion-graphics workflow even if you don’t adopt Hyperframes:

  • Natural-language easing vocabulary (smooth, snappy, bouncy, etc.) is a clean abstraction for briefing any motion tool. Works for Remotion and After Effects agents too.
  • Caption tone presets (Hype / Corporate / Tutorial / Storytelling / Social) are a useful axis for any content-tone rubric.
  • Energy-based transition picker (Calm / Medium / High) is a more intuitive control than naming specific transition types. Rules out slow crossfades that read as generic when you want “high energy.”
  • Audio-reactive intensity guidance — 3–6% for text, 10–30% for backgrounds — is concrete and testable. Worth cribbing for any audio-driven motion work.

Update — May 2026 (V2 capabilities, per Jay / Robo Nuggets walkthrough)

Source: Claude + Hyperframes V2 automates video editing like never before — NEW Skill (Jay, Robo Nuggets, May 6 2026).

Hyperframes V2 ships four capability extensions the original prompting guide didn’t cover:

  • Subtitles — automatic subtitle layer with style presets matching the existing caption-tone vocabulary.
  • Floating card animations — composable card overlays with entrance + dwell + exit timings (similar to broadcast lower-thirds).
  • Smooth animations + motion graphics — automatically applied; the agent gets motion-graphics-as-default rather than as opt-in element.
  • 3D assets — visually-striking 3D elements composable into 2D HTML compositions.

Hyperframes runs across coding agents. Jay confirms the skill works equally well across Claude Code, Hermes Agent, and Open Claude — same SKILL.md, same primitives, swap the runtime. Validates the cross-runtime SKILL.md design pattern from skills applied at the third-party level.

Adoption signals. HeyGen team has been “actively shipping a lot of updates” — Hyperframes for Hermes, hyperframes.dev community website, all of HeyGen’s own promotional videos using Hyperframes. Robo Nuggets ships its own Hyperframes helper skill that pre-loads installation + best-use-cases context for any agent.

Use-case framing from Jay: podcast intros, promotional announcement videos one-shot from a prompt, branded explainer assets — all via talking to the agent with no code review needed.

Practical walkthrough — Robo Nuggets, May 2026

Source: Hyperframes + Claude AI… Goodbye Video Editor Forever (Robo Nuggets channel, mid-May 2026 — raw/Hyperframes_+_Claude_AI..._Goodbye_Video_Editor_Forever.md).

Hands-on walkthrough by a non-developer-positioning creator. Adds operator-level detail the prior coverage didn’t pin down:

  • Two install routes confirmed. Either point Claude Code at the Hyperframes GitHub repo with the prompt “I want to use HyperFrames in this project. Here is the repository. Set up everything needed so I can create, preview and render videos” — Claude reads the repo, installs dependencies, prepares the environment. Or paste a one-line skill install command directly into the Claude Code text area. Both end at the same state; the repo-pointer route is preferred when the agent should also document the setup decisions.
  • Workspace convention. Author keeps a dedicated AI projects/ parent folder, one subfolder per project. Reduces context bleed between agent runs and gives Claude an unambiguous CWD per render.
  • Two preview surfaces, two purposes. (a) Preview directly inside the Claude desktop application — fast, in-conversation. (b) Preview in a browser via local server (npx hyperframes preview) — author’s preferred for iteration. The browser surface is what enables the iterate-while-watching pattern.
  • Two render routes, both deterministic. (a) Prompt Claude to "render this as a video file and save it to the project folder" — Claude drives the CLI, drops the MP4 into CWD. (b) Open the preview in the browser, hit the Renders button in the Hyperframes browser UI, pick MP4/MOV/WebP + quality, download. Same outputs either route.
  • Refinement is prompt-only, no timeline UI. “Make the title 2x bigger,” “slow down the animation,” “add a subtle glow” — every refinement is described in natural language and applied to the existing composition. No keyframes, no easing-curve dragging.
  • Source-to-video pattern. The “warm start” pattern from the prompting guide works on real assets: the author feeds a HeyGen Video Agent product page + asks for “a short cinematic explainer video based on this page… maintain a dark premium design style” — Hyperframes produces a structured visual explanation grounded in the page’s actual content.
  • Cost framing. Tutorial ships a clean 10-second cinematic intro for “the time it took to brew tea” — author’s anchor for the workflow’s cycle time vs the “few hours” it would take a video editor. Closes the agent-authored-motion-graphics value gap with a concrete number.

The walkthrough is the cleanest operator-level reference for the Claude Code + Hyperframes path as of May 2026; pair it with the prompting guide (linked above) for the underlying compositional vocabulary.

HeyGen Level Up series — 2026-05-22 first-party positioning

HeyGen’s own Level Up series episode (raw/HyperFrames_-_Code_Your_Videos_in_HTML_No_Timeline_Required_HeyGen.md) makes the official tagline explicit: “If you can describe it, you can render it.” Beyond the URL-to-video skill (invoke the website to Hyperframes skill on a URL), prompt-to-video, and PDF-source patterns covered above, the episode foregrounds a use case the prior coverage didn’t lead with — branded motion graphics composited directly over existing A-roll footage: drop in the footage, write a prompt, and Hyperframes generates the overlays, timing, and animation structure on top of the source video. Reinforces that Hyperframes targets both fully-generated compositions and post-production augmentation of existing material.

Update — June 2026 (Hermes-driven demo + newer registry blocks)

Source: raw/Hermes_Agent_+_HyperFrames_-_Free_Open-Source_AI_Tools_to_Create_Amazing_Videos.md (On Chain AI Garage / Tombi Studio, 2026-06-03) — a hands-on walkthrough driving the Hyperframes skill through Hermes Agent across five escalating builds (slides→video, a reusable Shorts template, website→promo, repo→architecture explainer, HTML-canvas VFX). It confirms documented features (warm-start from URL, reusable templates, cross-runtime including Hermes) and surfaces newer registry blocks not previously inventoried:

  • New registry blocks (creator-reported; verify against the live catalog). A GitHub-repo → architecture-explainer block; social-native editorial blocks (fake X-post card, Reddit / YouTube embeds, a YouTube-subscribe lower-third CTA); and HTML-canvas VFX blocks (UI-shatter-into-glass, rotating 3D-phone reveal, liquid backgrounds, device-frame iPhone/Mac modules). These partially answer this article’s catalog-contents open question — point the agent at the HTML-canvas docs directly when composing VFX.
  • Template-driven Shorts automation. A saved Hyperframes template lets you swap only the transcript to regenerate a fully-restyled short — cron-able for a 24/7 shorts pipeline (the same shape as the Hermes multi-agent triage pipeline’s “make an explainer video” fulfillment path, by the same maintainer).
  • Why drive it from Hermes vs Claude Code / Codex (creator’s framing). Running Hyperframes inside Hermes Agent lets the skill tap the agent’s other skills, memories, and project files, and supports unattended cron-driven rendering; Hermes shows a live studio preview on localhost (a scene-timeline mini-studio) and caught a real asset-render bug pre-export. Reported timing: ~9 min for a 16:9 slide-deck → video conversion. (Block names are auto-caption-sourced; confirm against the current catalog before relying on exact identifiers.)

Update — June 2026 (HeyGen MCP avatar generation → HyperFrames, one agentic pipeline)

Source: raw/How_To_Build_Full_AI_Videos_with_AI_Agents_HeyGen_+_Hyperframes_Workflow.md (YouTube 9yx8Ja1gztI, 2026-06) — adds the avatar front-end the composition-focused coverage above lacks: generating the talking-head with HeyGen’s MCP server and chaining it into a HyperFrames composition in a single Claude Code prompt. (Creator reports the HyperFrames repo at ~15k stars as of June 2026, up from 2.6k at this article’s creation.)

  • Connect HeyGen as an MCP server once, machine-wide. A single terminal command with the -S user flag registers the HeyGen MCP across every project (not per-repo). Then in Claude Code, /mcp → OAuth browser sign-in to your existing HeyGen account — no API key, no extra credits (it draws on your current HeyGen plan). The same HeyGen MCP also works in Codex, Cursor, and Gemini CLI. Requires a paid Claude + paid HeyGen account.
  • Install both skill packs by prompt, not by hand. Point Claude at the two GitHub repos: “Take a look at these two GitHub repos and install the skill packs from each… read the readmes to find the right install commands and run them.” The HeyGen skill pack teaches Claude to call HeyGen (scenes, timing, avatar selection, voice matching); the HyperFrames skill pack teaches composition authoring (title cards, lower thirds, GSAP, shader transitions).
  • Two IDs to grab first: an avatar look ID and a voice ID from the HeyGen dashboard (hover the avatar → three-dot → copy look ID; Voices tab → three-dot → get voice ID), or have Claude list avatars/voices by name. Each avatar exposes the motion engines it supports (name one only if supported; the demo leaves it on the default).
  • The one-prompt pipeline. A single prompt (e.g. “make a 30-second video about X, use my avatar [look ID] and voice [ID], build a HyperFrames composition with a title card, a sidebar that shows each tool logo when I mention it, captions synced to the audio, and an outro card; render the final”) drives the whole chain: Claude writes the script in your voice → calls HeyGen via MCP (passing the look + voice IDs) to render the avatar → grabs the transcript itself for word-level timestamps (unprompted — a background skill, to sync captions + logo reveals) → auto-fetches the rendered video into the project folder → authors the HyperFrames composition → renders the final. No app-juggling, no manual download.
  • Iteration is conversational; reformatting is one prompt. Drop real logo files into the project folder and say “use these instead of the ones you generated”; recolor captions (“electric blue with a subtle drop shadow”). Re-target the same content to 9×16 vertical for Reels/TikTok in one prompt (reframe or swap the avatar, adjust lower thirds). PDF → explainer works end-to-end too: feed a quarterly-report PDF and ask for a 60-second marketing explainer (avatar in a rounded frame on most slides, tall vertical layout on data-heavy ones) — Claude pulls the metrics from the PDF and writes the narration.

Try It

  1. In a throwaway project directory: npx skills add heygen-com/hyperframes and npx hyperframes init smoke-test. Confirm the three slash commands appear in Claude Code. Render a 5s greeting from a cold-start prompt.
  2. Try the warm-start pattern on any source: feed a blog post, ask for a 45s pitch video.
  3. Read the prompting guide in full once — the caption/tone and easing tables are the highest-value cribs even outside Hyperframes itself.

Open Questions

  • Is hyperframes.heygen.com a hosted service, or just marketing + docs? The repo implies local rendering only; a hosted tier would change the cost model.
  • Does the /hyperframes skill play nicely alongside other Claude Code skill ecosystems (design skills, wiki skills)? No known conflicts, but an install-time test is warranted.
  • What’s the render performance vs Remotion on the same hardware for a ~30s composition? Switching decision may hinge on this.
  • Catalog contents: what prebuilt blocks exist by default, and at what vertical coverage? Not inventoried during this ingest.

Graph View

Backlinks