Source: @hyperframes/core, @hyperframes/engine, @hyperframes/player, @hyperframes/producer, @hyperframes/studio — HeyGen HyperFrames docs
Beneath the hyperframes CLI is a monorepo of focused npm packages. @hyperframes/core is the foundation (types, HTML parse/generate, runtime, linter, compiler, frame adapters); @hyperframes/engine captures frames; @hyperframes/producer is the full HTML-to-video pipeline; @hyperframes/studio is the visual editor; @hyperframes/player embeds a finished composition in any web page. Most people only ever touch the CLI (HyperFrames Quickstart & CLI) — you reach for a package directly only when building tooling, a custom render pipeline, or embedding. This is the deep-dive on the six libraries and when to use each. For the framework overview, see the hub, HeyGen Hyperframes.
Key Takeaways
- Six packages, one dependency graph.
coreis the foundation everything builds on;enginebuilds oncore;producerwrapsengine;studioandplayerembed the core runtime; the CLI sits on top — and the CLI is all most users need. @hyperframes/core— the type system, HTML parse/generate round-trip, the composition linter, a compiler (timing resolver, bundler, static guard), the browser runtime, and the built-in GSAP frame adapter. Reach for it for CI linting, programmatic HTML generation (from an API or AI agent), or a custom player.@hyperframes/engine— the seek-and-capture engine using Chrome’sHeadlessExperimental.beginFrame. Session-based capture API, FFmpeg encoding helpers, HDR APIs, and thewindow.__hfprotocol (any page implementing it can be captured). This is the layer that makes rendering deterministic.@hyperframes/producer— the complete HTML→video pipeline: engine capture + FFmpeg encode + audio mixing + readiness gates + WebM alpha + HDR + Docker. Two-stepcreateRenderJob/executeRenderJobAPI, a built-in HTTP render server, a pluggable logger, and regression + benchmark harnesses.@hyperframes/studio— the browser visual editor (React components, hooks, Tailwind preset) with live preview, timeline view/editing, player controls, and hot reload.npx hyperframes previewlaunches it for you; install it only to embed the editor in your own app.@hyperframes/player— an embeddable<hyperframes-player>web component, zero dependencies, 3KB gzipped. Drop a composition into any page (CDN or npm) with a<video>-like attribute set and JS API. This is the embedding primitive.
The package graph
| Package | Role | Depends on | Most users need it? |
|---|---|---|---|
hyperframes (CLI) | Create / preview / lint / render from the terminal | producer, engine, studio, core | Yes — the default surface |
@hyperframes/core | Types, parse/generate, runtime, linter, compiler, GSAP adapter | — (foundation) | Only for tooling |
@hyperframes/engine | Seekable frame capture (BeginFrame) | core | Rarely |
@hyperframes/producer | Full HTML→video pipeline + render server | engine, core | For Node render services |
@hyperframes/studio | Visual editor (React) | core | Only to embed the editor |
@hyperframes/player | Embeddable web component | core runtime | To embed compositions |
The CLI is documented separately in HyperFrames Quickstart & CLI; this article covers the five libraries beneath it.
@hyperframes/core — the foundation
npm install @hyperframes/coreFour entry points: @hyperframes/core (types, parsers, generators, adapters, runtime utilities), @hyperframes/core/lint (linter), @hyperframes/core/compiler (timing compiler, HTML compiler, bundler, static guard), @hyperframes/core/runtime (pre-built IIFE for browser injection).
- Type system —
TimelineElement,TimelineMediaElement/TimelineTextElement/TimelineCompositionElement,CompositionSpec,CompositionVariable,CanvasResolution(landscape/portrait/landscape-4k/portrait-4k/square/square-4k),Orientation(16:9/9:16), plus type guards and theCANVAS_DIMENSIONS/DEFAULT_DURATIONSconstants. - Parse / generate round-trip —
parseHtml(html)→ structuredParsedHtml;generateHyperframesHtml(elements, opts)back to HTML;extractCompositionMetadata,getVariables<T>()(resolves declared defaults + CLI overrides + per-instancedata-variable-values), andvalidateVariablesagainst the declared schema. Element edits:updateElementInHtml/addElementToHtml/removeElementFromHtml. - Linter —
lintHyperframeHtml(html, opts)returns{ ok, errorCount, warningCount, findings }; the same engine behindnpx hyperframes lint, callable in CI or editor plugins. - Compiler —
compileTimingAttrs(browser-safe),compileHtml(Node, probes media durations),bundleToSingleHtml, andvalidateHyperframeHtmlContract(static guard with failure reasons likemissing_composition_id,missing_timeline_registry). - Frame adapters — defines the Frame Adapter interface and ships
createGSAPFrameAdapter({ id, fps, timeline }). See HyperFrames Core Concepts for the adapter model.
Use it when you lint programmatically, parse/generate compositions from data (an API or AI agent), or embed the runtime in a custom player. Most users don’t — the CLI, producer, and studio depend on it internally.
@hyperframes/engine — deterministic capture
npm install @hyperframes/engineThe low-level seek-and-capture engine, fundamentally different from screen recording: it starts chrome-headless-shell (controlled via the Chrome DevTools Protocol), injects the runtime, calls renderSeek(time) for every frame independently (no wall clock), and captures the compositor output via HeadlessExperimental.beginFrame.
- Session API —
createCaptureSession({ fps, width, height })→initializeSession(session, indexHtml)→getCompositionDuration→captureFrame/captureFrameToBufferper frame →closeCaptureSession. - Encoding helpers —
getEncoderPreset(quality, format)(h264 for MP4, VP9yuva420pfor WebM alpha),encodeFramesFromDir,muxVideoWithAudio,applyFaststart,spawnStreamingEncoder, anddetectGpuEncoder→nvenc/videotoolbox/vaapi/qsv/amf. - HDR APIs — color-space classification (
isHdrColorSpace,detectTransfer,analyzeCompositionHdr,getHdrEncoderColorParams) plus an advanced WebGPU readback path that requires headed Chrome with--enable-unsafe-webgpu. - The
window.__hfprotocol —{ duration, seek(time), media? }. Any page that implements it can be captured — you are not limited to HyperFrames compositions.
The seek contract is the heart of it: renderSeek(time) pauses all GSAP timelines, seeks every timeline to the exact timestamp, updates all media, and mounts/unmounts clips by data-start/data-duration — so each frame is a complete, independent snapshot. Use it when building a custom pipeline or capturing frames (thumbnails, sprite sheets) without encoding; otherwise use the producer or CLI.
@hyperframes/producer — the render pipeline
npm install @hyperframes/producerCombines engine capture with FFmpeg encoding for the complete HTML→video pipeline: reads index.html + sub-compositions, injects the runtime, polls window.__playerReady/window.__renderReady so all assets load before capture, captures via BeginFrame, encodes, and mixes audio (applying data-volume/data-media-start).
- Two-step API:
createRenderJob({ fps, quality, format, workers, useGpu })thenexecuteRenderJob(job, projectDir, outputPath). - WebM alpha (
format: 'webm') — PNG capture, transparent page background via CDP, VP9yuva420p, Opus audio. - HDR (
hdr: true) — probes sources for BT.2020/PQ/HLG; emits H.265 10-bit BT.2020 + HDR10 metadata (MP4 only; MOV/WebM fall back to SDR). - HTTP render server —
startServer({ port })exposesPOST /render,POST /render/stream(SSE),POST /lint,GET /health,GET /outputs/:token; lower-levelcreateProducerAppreturns a Hono app. - Ops — auto-detected GPU encoders, a pluggable
ProducerLogger(inject Pino/Winston), a Docker regression harness against golden baselines, andnpx hyperframes benchmark.
Use it when you render from Node (a backend service or CI), build a custom render service, or run visual regression tests. For Docker determinism and the full render-flag surface see HyperFrames Rendering.
@hyperframes/studio — the visual editor
npm install @hyperframes/studioThe browser-based visual editor — npx hyperframes preview launches it automatically, so install the package directly only to embed the editor in your own app. Exports React components, hooks, and a Tailwind preset (peer deps: React 18/19, react-dom 18/19, zustand 4/5).
- Components —
NLELayout/NLEPreview/CompositionBreadcrumb(layout),Player/PlayerControls/Timeline/PreviewPanel/AgentActivityTrack(player + timeline, incl. an agent-workflow activity track),SourceEditor(CodeMirror)/PropertyPanel/FileTree, andStudioApp(the whole app). - Hooks —
useTimelinePlayer(play/pause/seek/step),usePlayerStore(Zustand),useCodeEditor,useElementPicker. - Features — live preview in an iframe running the real runtime, a timeline view (clips as bars positioned by
data-start/data-duration, higher rows in front), move/trim timeline editing that persists back into the HTML, frame-step player controls, and hot reload that keeps the playback position. - Architecture — iframe preview +
postMessageruntime bridge +@hyperframes/coreparsing for the timeline + a Vite file watcher for HMR.
Like the preview itself, the studio’s visual output matches render exactly; playback smoothness depends on hardware (stutter in preview with a clean MP4 is expected).
@hyperframes/player — embedding compositions
npm install @hyperframes/playerThe embedding primitive: a <hyperframes-player> custom element that plays a composition anywhere — any framework or plain HTML — with zero dependencies, 3KB gzipped.
Via CDN:
<script type="module" src="https://cdn.jsdelivr.net/npm/@hyperframes/player/dist/index.js"></script>
<hyperframes-player src="composition.html" controls></hyperframes-player>Via npm:
import '@hyperframes/player';<hyperframes-player src="composition.html" width="1920" height="1080" controls></hyperframes-player>Attributes: src (required), width (1920), height (1080), controls (false), autoplay (false), loop (false), muted (true — required for autoplay in most browsers), poster, and playback-rate (1). The JavaScript API mirrors the native <video> element (play/pause, currentTime, duration). ^[The exact JS method/event names were stripped by the docs extraction; the element name, attributes, and <video>-like API are reconstructed from the page’s prose + attribute table — confirm specifics against the live page.]
Use it when you embed a composition in a website, dashboard, docs, or product demo — the lightweight alternative to rendering an MP4 and serving a video file.
Try It
- Lint in CI without the full CLI:
import { lintHyperframeHtml } from '@hyperframes/core/lint'and fail the build onresult.errorCount > 0. - Embed a composition:
npm install @hyperframes/player, then drop<hyperframes-player src="composition.html" controls>into any page (or load it from the CDN as above). - Run a render service:
import { startServer } from '@hyperframes/producer/server'; await startServer({ port: 8080 })andPOST /renderwith a composition. - Render programmatically:
createRenderJob({ fps: 30, quality: 'standard' })thenexecuteRenderJob(job, './my-video', './out.mp4').