Render HeyGen HyperFrames videos with ak:hyperframes

Use ak:hyperframes to turn an HTML composition annotated with data-composition-id, data-start, data-width, and data-height attributes into a local MP4 through the published hyperframes CLI. It fits short vertical or social clips, product-launch loops, and motion graphics whose source of truth is HTML markup instead of a React component tree or a timeline editor.

Choose HeyGen HyperFrames rendering

Use ak:hyperframes when

• The composition is authored as HTML with HyperFrames timing attributes.
• You want a scaffolded project, browser preview, lint gate, and MP4 render from one CLI, without wiring the HeyGen source into your project.
• The target is a short vertical or social video, product-launch clip, or promo loop that reads naturally as HTML.
• You need an optional cloud render path through a HeyGen API key while the local render still works without one.

Choose another workflow when

• The composition is naturally a React component tree with frame math or captions. Use ak:remotion.
• You want a template-driven HTML wrapper with Studio editing rather than the HyperFrames composition contract. Use ak:html-video.
• You only need transcode, trim, thumbnail, HLS or DASH, or batch FFmpeg work. Use ak:media-processing.
• The task is to route across every installed video or motion Skill. Use the installed motion-graphics router when it is present.

Prepare the engine and composition brief

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the current runtime and scope.
• Define aspect ratio, duration, source assets, target resolution, output path, whether local or cloud rendering is required, and whether the clip is a draft or a polished export.
• Make Node.js 22 or newer available, put FFmpeg on PATH, and set HEYGEN_API_KEY only when you plan to use the cloud render path.
• Run the bundled prerequisite verifier (node scripts/verify-prereqs.mjs) before scaffolding a composition; prefer the JSON output when a runtime consumes the result.
• Pin the CLI version. Every invocation in this Skill uses hyperframes@0.7.99; bump the pin in one place when upgrading and never fall back to an unpinned npx -y hyperframes ... in scripts or docs.

Create a bounded HyperFrames project

/ak:hyperframes "Scaffold a 6-second 1080x1920 draft product-launch loop under ./assets/videos/launch/, preview locally, lint before rendering, and render an MP4 to ./assets/videos/launch/launch.mp4 without contacting the HeyGen cloud endpoint"

/ak:hyperframes "Scaffold a 6-second 1080x1920 draft product-launch loop under ./assets/videos/launch/, preview locally, lint before rendering, and render an MP4 to ./assets/videos/launch/launch.mp4 without contacting the HeyGen cloud endpoint"

$ak:hyperframes "Scaffold a 6-second 1080x1920 draft product-launch loop under ./assets/videos/launch/, preview locally, lint before rendering, and render an MP4 to ./assets/videos/launch/launch.mp4 without contacting the HeyGen cloud endpoint"

Use the live CLI workflow

Always run lint before render. Most render failures come from malformed data-start or data-composition-id attributes that the lint stage catches before Chromium and FFmpeg pay the full render cost.

Observe the render stages

1. The Skill pins the video brief. Aspect, duration, source assets, output path, local versus cloud render, and publication boundary are captured.
2. It verifies the engine. Node, FFmpeg, the pinned hyperframes CLI, and (when cloud rendering) the HeyGen API key are checked.
3. It scaffolds a composition. init creates a project directory with an HTML skeleton and the HyperFrames timing-attribute contract.
4. You edit the HTML composition. Root elements carry data-composition-id, data-start, data-width, and data-height attributes that describe layout and timing.
5. It previews in a browser. The returned dev-server URL is checked for layout, typography, missing assets, motion, timing, console failures, and network use.
6. It lints the composition. Timing and composition-id issues surface before rendering.
7. It renders through Chromium and FFmpeg. Local rendering encodes the MP4 at the explicit output path; cloud rendering hands the composition to HeyGen and returns a remote artifact reference.
8. It probes the artifact. ffprobe must report nonzero duration and expected dimensions before the export is treated as complete.

Control code, network, process, and storage effects

• npx -y hyperframes@0.7.99 resolves the pinned package from the public registry. Confirm the pin, review upstream changes before bumping it, and do not fall back to an unpinned invocation in scripts or docs.
• The scaffolded dev server binds a local port during preview. Bind and expose it only as intended, stop it after use, and do not treat the page as safe on a shared network.
• Local rendering starts Chromium and FFmpeg and can consume heavy CPU, memory, disk, temporary files, and time. Test a short draft first.
• Cloud rendering sends the composition to HeyGen. Only use it when you have permission to submit the source assets, and when the HEYGEN_API_KEY is stored per your project's secret policy.
• HTML compositions, fonts, images, and scripts can make external requests. Record or block network effects when privacy or reproducibility matters.
• Confirm rights for images, logos, copy, fonts, audio, and templates. The Skill does not grant publication or redistribution rights.
• The workflow writes project state, preview files, lint reports, and MP4 output. It does not commit, upload, publish, or deploy them without separate authority.

Verify the video and evidence

A complete result should include:

• Node, FFmpeg, and (when cloud rendering) HeyGen API-key verification.
• Pinned CLI version (hyperframes@0.7.99) and any documented deviation.
• Scaffolded composition name, HTML source, and used timing attributes.
• Preview URL, visual review notes, lint report, render command, and MP4 path (or cloud job reference).
• ffprobe evidence for duration, dimensions, streams, format, and file size.
• Local port, network access, storage, rights, privacy, or publication limitations that remain.

Stable and beta package the same ak:hyperframes wrapper. The release does not pin an upstream HeyGen source revision, prove a published HeyGen build, or guarantee cross-runtime cloud-render parity.

Troubleshoot and interpret limits