Source: @hyperframes/core, @hyperframes/engine, @hyperframes/player, @hyperframes/producer, @hyperframes/studio, @hyperframes/lint, @hyperframes/parsers, @hyperframes/shader-transitions, @hyperframes/studio-server — HeyGen HyperFrames docs
Beneath the hyperframes CLI is a monorepo of focused npm packages. @hyperframes/parsers is the dependency-free base (GSAP + HTML parse/write); @hyperframes/core builds on it (types, runtime, compiler, generators, frame adapters); @hyperframes/engine captures frames; @hyperframes/producer is the full HTML-to-video pipeline; @hyperframes/studio is the visual editor, backed by @hyperframes/studio-server; @hyperframes/lint is the shared validation gate; @hyperframes/shader-transitions adds GPU scene transitions; @hyperframes/player embeds a finished composition in any web page; and @hyperframes/sdk, @hyperframes/aws-lambda, and @hyperframes/gcp-cloud-run cover programmatic editing and self-hosted cloud rendering. 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 all 13 packages and when to use each. The docs now list 13 packages; this article expanded from the original six. ^[inferred] For the framework overview, see the hub, HeyGen Hyperframes.
Key Takeaways
- 13 packages, one dependency graph.
parsersis the dependency-free base;corebuilds on it;enginebuilds oncore;producerwrapsengine;studio/playerembed the core runtime;studio-serverbacks the editor;lintandshader-transitionsare shared libraries;sdkis the programmatic editing engine;aws-lambda/gcp-cloud-runare self-hosted cloud render backends; and the CLI sits on top — and the CLI is all most users need. ^[inferred: the dependency ordering is reconstructed from each package’s “depends on / builds on” statements across the docs] @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.@hyperframes/parsers— the standalone GSAP + HTML parser/writer suite, with zero@hyperframes/*dependencies; the base every other package builds on. Owns the acorn + recast GSAP AST round-trip, the HTML composition parser, deterministichf-idstamping, and spring-ease generation. Most users get it transitively viacore.@hyperframes/lint— the composition linter extracted fromcoreinto its own package; the single source of truth for bothhyperframes lintand the render-time gate.lintProject(dir)/lintHyperframeHtml(html)/shouldBlockRender(), plus anode:-free/browserentry.@hyperframes/shader-transitions— WebGL GPU scene-to-scene transitions (domain warp, whip pan, glitch, iris, light leak, etc.) driven from a GSAP timeline; the shader library behind the catalog’s distortion transition blocks. Falls back to CSS/normal playback when WebGL is unavailable.@hyperframes/studio-server— the studio preview/editor backend, a mountable Hono API extracted fromcore.createStudioApi(adapter)serves project files, bundled preview HTML, thumbnails, and source-mutation helpers. Embed it only when wiring studio into your own server.@hyperframes/sdk— the programmatic editing engine: edit composition structure (elements, timing, animations) in code. Reach for it when you generate or mutate compositions from an app or agent rather than rendering or embedding. See HyperFrames SDK Authentication for the deep dive.@hyperframes/aws-lambdaand@hyperframes/gcp-cloud-run— self-hosted cloud render backends that run the producer pipeline serverlessly on your own AWS Lambda or GCP Cloud Run infrastructure. ^[inferred: the role split — Lambda vs Cloud Run as the two named cloud targets — is taken from the package list; deployment specifics live in the deployment article] See HyperFrames Cloud Deployment for the deep dive.
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/parsers | GSAP + HTML parse/write, hf-ids, spring-ease | — (zero @hyperframes/* deps) | Rarely (transitive via core) |
@hyperframes/core | Types, generators, runtime, compiler, GSAP adapter | parsers | 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/studio-server | Studio preview/editor backend (Hono API) | parsers | Only to embed the backend |
@hyperframes/player | Embeddable web component | core runtime | To embed compositions |
@hyperframes/lint | Composition linter + render gate | parsers | For programmatic linting |
@hyperframes/shader-transitions | WebGL GPU scene transitions | GSAP, WebGL | For shader transitions |
@hyperframes/sdk | Programmatic composition editing engine | core ^[inferred] | For programmatic editing |
@hyperframes/aws-lambda | Self-hosted Lambda render backend | producer ^[inferred] | For self-hosted cloud render |
@hyperframes/gcp-cloud-run | Self-hosted Cloud Run render backend | producer ^[inferred] | For self-hosted cloud render |
The CLI is documented separately in HyperFrames Quickstart & CLI; this article covers the libraries beneath it. @hyperframes/sdk and the two cloud backends have their own deep dives (SDK Authentication, Cloud Deployment); the sections below cover the rest in dependency order.
@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.
@hyperframes/parsers — the dependency-free base
npm install @hyperframes/parsersThe standalone GSAP + HTML parser/writer suite, extracted from core. It has no @hyperframes/* dependencies, so it is the base every other package builds on (core, lint, studio-server, and the CLI all depend on it). It owns the GSAP animation parser/writer (both acorn and recast implementations), the HTML composition parser, hf-id stamping, and spring-ease generation.
- Subpath exports for tree-shaking —
@hyperframes/parsers(HTML parser, GSAP serialize/validate, hf-ids, shared types),/gsap-parser-acorn(browser-safe read path),/gsap-writer-acorn(mutation helpers),/gsap-parser-recast(legacy),/gsap-constants(SUPPORTED_PROPS,SUPPORTED_EASES,PROPERTY_GROUPS),/spring-ease,/hf-ids,/slideshow(parseSlideshowManifest/resolveSlideshow),/composition(pure browser-safe primitives),/asset-paths(Node-only path rewriting). Importing/hf-idsdoes not pull in the GSAP AST machinery (recast/babel/acorn). - HTML round-trip —
parseHtml(html)→ParsedHtml(elements,gsapScript,styles,resolution,keyframes);extractCompositionMetadata,validateCompositionHtml; element editsupdateElementInHtml/addElementToHtml/removeElementFromHtml. - GSAP AST round-trip —
parseGsapScriptAcorn(script)→ParsedGsap; writer helpers (updateAnimationInScript,addAnimationToScript,removeAnimationFromScript,updateKeyframeInScript,addKeyframeToScript,shiftPositionsInScript,scalePositionsInScript) mutate the script text while preserving unrelated code. High-level helpersserializeGsapAnimations,validateCompositionGsap,keyframesToGsapAnimations/gsapAnimationsToKeyframesare on the main entry. - hf-ids —
ensureHfIds(html)/mintHfId()stamp deterministic element identity for stable diffing and editing.
Use it when you build tooling that touches the parsing layer but doesn’t need core’s runtime, compiler, or generators. Most users get the parser API transitively through core, which re-exports what it needs.
@hyperframes/lint — the validation gate
npm install @hyperframes/lintThe composition linter extracted from core into a dedicated package, and the single source of truth for linting: both the CLI’s hyperframes lint and the render-time render-gate consume the same rule engine. It builds on @hyperframes/parsers. The payoff is running validation as a library — an agent harness, CI step, or editor plugin imports it directly instead of shelling out to npx hyperframes lint and parsing stdout.
- Single entry point —
lintHyperframeHtml(html, opts)(single composition; returns{ ok, errorCount, warningCount, findings }),lintProject(dir)(walks the index + sub-compositions, returnsProjectLintResultwithtotalErrors/totalWarnings/results[]),lintMediaUrls(findings), andshouldBlockRender(result)to gate a render. - Browser entry —
@hyperframes/lint/browserruns the rule engine fully client-side with zeronode:builtins (verified at build time); exposes everything that operates on an HTML string (lintHyperframeHtml,lintMediaUrls,shouldBlockRender).lintProjectwalks a directory and is Node-only — import it from the main entry. - Back-compat —
@hyperframes/core/lintstill resolves via a re-export stub; new code should import from@hyperframes/lint. - What it catches — missing timeline registration (
window.__timelines), unmuted video (autoplay failures), missingclass="clip"on timed visible elements, deprecated attribute names, missing dimensions (data-width/data-height), invaliddata-startreferences to nonexistent clip IDs.
Use it when you gate a render on lint findings, lint a composition from Node, or surface findings in your own UI or CI annotations. For the failure list and fixes see HyperFrames Common Mistakes.
@hyperframes/shader-transitions — GPU scene transitions
npm install @hyperframes/shader-transitionsGPU-accelerated scene-to-scene transitions: it captures scene samples, uploads them as WebGL textures, and drives fragment-shader compositing from a GSAP timeline. This is the shader library behind the catalog’s distortion transition blocks. A browser global build is also available from jsDelivr (dist/index.global.js). If WebGL is unavailable, it falls back to normal timeline playback without shader compositing.
- Exports —
init(config)(creates or augments a GSAP timeline with shader transitions),SHADER_NAMES(typed list for validation/UI pickers),isHtmlInCanvasCaptureSupported(),installPageSideCompositor()(render-mode compositor used by the producer path),isPageSideCompositingSupported(). - Config —
HyperShaderConfig={ bgColor, accentColor?, scenes[], transitions[], timeline?, compositionId?, previewCaptureFps? }; eachTransitionConfig={ time, shader?, duration?, ease? }.shaderis optional — omit it for a CSS fallback transition at that point. - 14 shaders —
domain-warp,ridged-burn,whip-pan,sdf-iris,ripple-waves,gravitational-lens,cinematic-zoom,chromatic-split,glitch,swirl-vortex,thermal-distortion,flash-through-white,cross-warp-morph,light-leak. - Preview vs render — browser previews pre-capture transition samples and cache snapshots in IndexedDB (keyed by composition ID, scene DOM/style signatures, timing, FPS, scale, dimensions). Producer renders instead use a deterministic page-side compositor so capture stays seek-driven and independent of wall-clock playback.
Use it when you add shader-based scene transitions, attach GPU transitions to an existing timeline, or build a transition picker around the shader registry. To render a composition that includes them, use the producer or CLI; the transition blocks themselves live in the 109-block catalog.
@hyperframes/studio-server — the editor backend
npm install @hyperframes/studio-serverThe HTTP backend that powers studio preview and editing — project routes, file serving, preview bundling, thumbnails, and source-mutation helpers — extracted from @hyperframes/core/studio-api so an embedder can mount the studio backend without depending on core’s full surface (and so core no longer ships a web server it doesn’t need at render time). It builds on @hyperframes/parsers.
createStudioApi(adapter)returns a Hono app you mount into any server. You supply aStudioApiAdapter(listProjects,resolveProject,bundle,lint,runtimeUrl) — the seam between framework-agnostic route logic and your storage/bundling/lint implementation. The CLI supplies a filesystem-backed adapter; you can back it with anything.- Subpath exports —
/screenshot-clip(element screenshot-clip geometry),/manual-edits-render-script,/studio-motion-render-script,/draft-markers(draft gesture-marker attributes),/finite-mutation(finite-mutation safety checks). - Helpers —
createProjectSignature(per-project cache key),isSafePath(path-traversal guard),walkDir,getMimeType,buildSubCompositionHtml,getElementScreenshotClip; typesResolvedProject,RenderJobState,LintResult,ScreenshotClip. - Back-compat —
@hyperframes/core/studio-apistill resolves via a re-export stub.
Use it when you mount the studio preview/editing API into an existing Node/Hono server, serve project files and bundled preview HTML to a custom frontend, or drive source mutations from your own tooling. npx hyperframes preview and @hyperframes/studio wire it up for you otherwise.
@hyperframes/sdk — programmatic editing engine
npm install @hyperframes/sdkThe programmatic editing engine for HyperFrames compositions — edit composition structure (elements, timing, animations) in code rather than rendering or embedding. Reach for it when an app or AI agent generates or mutates compositions programmatically. ^[inferred: role summarized from the package list and the shader-transitions docs, which point to sdk as the “edit composition structure programmatically” package; the SDK’s own API surface and auth flow are covered in its dedicated article, not re-derived here]
Use it when you build a programmatic editing workflow. The authentication flow, client setup, and full API are documented in HyperFrames SDK Authentication.
@hyperframes/aws-lambda and @hyperframes/gcp-cloud-run — self-hosted cloud render
npm install @hyperframes/aws-lambda
npm install @hyperframes/gcp-cloud-runThe two self-hosted cloud render backends — they run the producer pipeline serverlessly on your own infrastructure: @hyperframes/aws-lambda targets AWS Lambda (also fronted by the CLI’s hyperframes lambda deploy / render / progress / destroy / policies commands), and @hyperframes/gcp-cloud-run targets Google Cloud Run. ^[inferred: the two named cloud targets and the producer-on-serverless framing come from the package list and the CLI’s lambda subcommands; per-provider setup, IAM, and cost are in the deployment article]
Use them when you want to render at scale on your own AWS or GCP account instead of locally or through HeyGen’s hosted path. Setup, deployment commands, IAM/permissions, and the local-vs-Lambda-vs-hosted decision live in HyperFrames Cloud Deployment.
Try It
- Lint in CI without the full CLI:
import { lintProject } from '@hyperframes/lint', thenif (shouldBlockRender(await lintProject('./comp'))) process.exit(1). (@hyperframes/core/lintstill works via a re-export stub.) - Add a GPU scene transition:
import { init } from '@hyperframes/shader-transitions', theninit({ bgColor: '#0a0a0a', scenes: ['a','b'], transitions: [{ time: 3, shader: 'domain-warp' }] })and register the returned timeline onwindow.__timelines. - Mount the studio backend in your own server:
import { createStudioApi } from '@hyperframes/studio-server', supply aStudioApiAdapter, thenapp.route('/api', createStudioApi(adapter)). - 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').