ak:hyperframes
Wrap HeyGen's hyperframes CLI
for HTML-first programmatic video generation. This skill is docs+wrap only —
no vendored HeyGen source, no copied HeyGen agent skills. Every command below
runs the published npm package through npx, pinned to a known-good version.
When to use
- Short vertical/social videos (1080×1920, 9:16) rendered from HTML/CSS.
- Product-launch clips, promo loops, motion graphics authored as HTML composition rather than React components or timeline editors.
- Any task where the composition source of truth is HTML markup with
data-composition-id/data-starttiming attributes (see references/composition-basics.md).
Not a fit for React-first compositions, frame-accurate interpolation curves, or Remotion's audio/caption ecosystem — see also the installed remotion skill for that alternative (React-based programmatic video). Not a fit for pure FFmpeg/ImageMagick encode-only tasks — see also the ak-media-processing skill.
Prerequisites
- Node.js 22+
- FFmpeg on
PATH - Optional: a HeyGen cloud/lambda API key (
HEYGEN_API_KEY) for remote rendering; local rendering works without it.
Run the bundled verifier before starting any render work:
node scripts/verify-prereqs.mjs
# or, for machine-readable output:
node scripts/verify-prereqs.mjs --json
See references/env-and-deps.md for install instructions per platform and the pinned-version verification note.
Pinned CLI version
Every invocation below pins [email protected] — the latest published
version as of 2026-08-07 (npm view hyperframes version). Bump this pin in
one place (this file + references/render-workflow.md) when upgrading; do
not run an unpinned npx -y hyperframes ... in scripts or docs.
Workflow
The standard loop is init → edit HTML → preview → lint → render. Full
concrete invocations for each stage live in
references/render-workflow.md; the short
form:
# 1. Scaffold a new composition project.
npx -y [email protected] init my-composition --resolution portrait
# 2. Edit the generated HTML composition (see composition-basics.md for the
# data-composition-id / data-start / data-width / data-height contract).
# 3. Preview in a local dev server.
npx -y [email protected] preview my-composition
# 4. Lint the composition before rendering (catches malformed timing attrs).
npx -y [email protected] lint my-composition
# 5. Render to MP4.
npx -y [email protected] render my-composition --output ./assets/videos/my-composition.mp4
Always run lint before render — a composition that lints clean fails the
render step far less often than one that skips straight to rendering.
Composition contract
HyperFrames compositions are plain HTML files annotated with
data-composition-id, data-start, data-width, and data-height
attributes on the root element(s). See
references/composition-basics.md for the
full attribute reference and a complete vertical 1080×1920 example.
Reference material
- references/heygen-skills.md — the 25 HeyGen
agent skills this wrapper defers to instead of re-implementing; install
them via
npx -y [email protected] skillswhen deeper HyperFrames-specific expertise (animation, keyframes, captions, product-launch templates, etc.) is needed. - references/composition-basics.md — HTML composition attribute contract with a full vertical-preset example.
- references/render-workflow.md — the full
init → edit → preview → lint → renderflow with every pinned invocation. - references/env-and-deps.md — Node/FFmpeg/API key setup per platform.
Troubleshooting
| Symptom | Action |
|---|---|
command not found: ffmpeg | Run node scripts/verify-prereqs.mjs for the exact remediation for your platform. |
npx hyperframes reports an unknown flag | The pinned version in this file may be behind upstream; run npx -y [email protected] --help to confirm current flags before updating the pin. |
render fails with a blank/short MP4 | Run lint first; most render failures are malformed data-start/data-composition-id attributes caught by lint. |
| Remote/cloud render needed | Set HEYGEN_API_KEY per references/env-and-deps.md, then use hyperframes cloud render (a separate top-level command, not a render flag) — see references/render-workflow.md. |
See also
- The installed remotion skill (
ak-remotion) — React-based programmatic video generation; use it when the composition is naturally a React component tree rather than HTML markup. - The ak-html-video skill — a separate HTML-to-MP4 wrapper
(
nexu-io/html-video) with its own template/Studio workflow; use ak-hyperframes specifically when the task is a HeyGen HyperFrames composition. - The ak-motion-graphics skill — router across all in-repo video/motion skills plus external motion-skills packs.