Render HeyGen HyperFrames videos with ak:hyperframes

Use ak:hyperframes to turn an HTML composition annotated with HyperFrames data-* timing 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 and check gates, 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 HeyGen credentials while the local render still works without them.

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-to-MP4 engine with Studio editing rather than the HyperFrames composition contract. The Skill's bundled nexu-io/html-video reference covers that alternative; use it only when its template catalog or an existing install fits the request better.
• 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 and FFprobe on PATH, and make a headless Chrome available (hyperframes browser ensure finds or downloads one). Configure HeyGen credentials (HEYGEN_API_KEY or hyperframes auth login) only when you plan to use the cloud render path.
• Run the bundled prerequisite verifier (node scripts/verify-prereqs.mjs) before scaffolding a composition. It checks Node, FFmpeg, and FFprobe; prefer the --json output when a runtime consumes the result.
• Pin the CLI version. Every invocation in this Skill uses hyperframes@0.8.77; 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, pass check 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, pass check 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, pass check before rendering, and render an MP4 to ./assets/videos/launch/launch.mp4 without contacting the HeyGen cloud endpoint"

Use the live CLI workflow

Always pass check before render; check reruns lint. Most render failures come from malformed data-start, data-duration, or data-composition-id attributes, or a missing timeline registration, that lint and check catch before Chrome and FFmpeg pay the full render cost. validate, inspect, and layout are deprecated aliases of check.

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, FFprobe, headless Chrome, the pinned hyperframes CLI, and (when cloud rendering) HeyGen credentials 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. The root carries data-composition-id, data-start="0", data-width, data-height, and usually data-duration; each timed clip carries id, data-start, and data-duration.
5. It previews in Studio. The returned URL is checked for layout, typography, missing assets, motion, timing, console failures, and network use. Only previews started for this task are stopped.
6. It lints and checks the composition. Timing, composition-id, runtime, layout, and contrast issues surface before rendering.
7. It renders through Chrome 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.8.77 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 preview server binds a local port during preview. Bind and expose it only as intended, stop it after use (--stop), and do not treat the page as safe on a shared network.
• Local rendering starts Chrome 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 store HeyGen credentials 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 and check 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, FFprobe, and (when cloud rendering) HeyGen credential verification.
• Pinned CLI version (hyperframes@0.8.77) and any documented deviation.
• Scaffolded composition name, HTML source, and used timing attributes.
• Preview URL, visual review notes, lint and check reports, 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.

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