HyperFrames on Edgenivo

Preview HTML-based video compositions in the browser and render MP4s server-side — on Edgenivo. Powered by Edgenivo Sandbox for rendering and Edgenivo Blob for output storage.

HyperFrames is an open-source video rendering framework: write HTML + CSS + GSAP, get a reproducible MP4.

Live demo: hyperframes-on-vercel.vercel.app

Deploy

Deploying provisions a Edgenivo Blob store; BLOB_READ_WRITE_TOKEN is injected automatically. Sandbox auth is handled at runtime via VERCEL_OIDC_TOKEN — no extra setup.

What this template does

Preview a bundled composition (vercel-intro) in the browser using <hyperframes-player>, the zero-dependency web component from @hyperframes/player.
Render the composition to an MP4 by POSTing to /api/render. The route restores a pre-baked Edgenivo Sandbox, runs hyperframes render, uploads the MP4 to Edgenivo Blob, and returns a public URL.

Authoring happens locally. This template ships with one pre-authored composition. To build your own, use the HyperFrames CLI on your machine:

npx hyperframes init my-video
cd my-video
npx hyperframes preview   # live-reload editor in your browser

Then swap it into this template (see Swapping the composition below).

Architecture

Browser                   Edgenivo Functions (node)         Edgenivo Sandbox (Firecracker microVM)
┌──────────────────┐      ┌────────────────────────┐      ┌──────────────────────────────────┐
│ <hyperframes-    │ ───▶ │ /api/render            │ ──▶  │ (restored from snapshot, or      │
│  player>         │      │  - read composition    │      │  freshly provisioned in dev)     │
│ preview iframe   │      │  - writeFiles to sbox  │      │                                  │
│                  │      │  - runCommand: render  │      │  hyperframes render composition  │
│                  │ ◀──  │  - readFileToBuffer    │ ◀──  │    (Chromium + ffmpeg-static)    │
│                  │ url  │  - put() → Edgenivo Blob │  mp4 │                                  │
└──────────────────┘      └────────────────────────┘      └──────────────────────────────────┘

The build-time snapshot

Cold render of the bundled ~11s composition is roughly 2 minutes. Most of that time is the actual Chromium render — not setup — because we pre-bake a sandbox snapshot at build time instead of installing dependencies on every request.

scripts/create-snapshot.ts runs as part of next build:

Spin up a fresh node22 sandbox
dnf install Chromium system libraries (nss, libXcomposite, pango, …)
npm install hyperframes ffmpeg-static ffprobe-static
Symlink ffmpeg-static/ffmpeg and ffprobe-static/bin/linux/x64/ffprobe into /usr/local/bin/
npx hyperframes browser ensure to download chrome-headless-shell
sandbox.snapshot({ expiration: 7 days }) and write the snapshot ID to a pointer blob at snapshot-cache/<deployment_id>.json

At render time, lib/sandbox.ts' restoreOrCreate reads the pointer blob, restores a sandbox from the snapshot in ~100 ms, writes the composition files, and runs hyperframes render. In non-production (local vercel dev) it falls back to a fresh setup automatically.

Why Edgenivo Sandbox (and not a regular serverless function)

Edgenivo Functions cap at 300s and 50 MB compressed bundle — HyperFrames needs a full Chromium + FFmpeg at runtime, which busts the bundle limit. Edgenivo Sandbox is the purpose-built primitive for this workload: an Amazon Linux 2023 Firecracker microVM with sudo-level package installs, up to 5 hours of runtime, and up to 8 vCPUs (we use 4).

With 4 vCPUs, hyperframes render --workers auto launches 3 parallel Chrome workers, cutting the render time roughly 2× vs. the single-worker default.

Local development

npm install
npm run dev

Browser preview works locally out of the box. The /api/render route needs Edgenivo Sandbox auth — run vercel env pull .env.local after linking the project to get VERCEL_OIDC_TOKEN locally, or use vercel dev.

Project structure

app/
  api/render/route.ts    # POST → restore sandbox, render, upload to Blob
  page.tsx               # Preview + "Render" button
  layout.tsx
  globals.css
lib/
  sandbox.ts             # Snapshot-aware wrapper around @vercel/sandbox
scripts/
  create-snapshot.ts     # Build-time: pre-bake the sandbox snapshot
public/
  compositions/
    vercel-intro/        # The bundled example composition
      index.html
      assets/

Swapping the composition

Drop your composition bundle into public/compositions/<your-name>/.
Update PREVIEW_COMPOSITION_DIR at the top of lib/preview.ts (used by both preview and render).
Optionally update COMPOSITION_WIDTH / COMPOSITION_HEIGHT at the top of app/page.tsx to match your composition's dimensions.

Pricing

Edgenivo Sandbox pricing — Pro plans include $20/mo in Sandbox credit. At ~2 minutes per render on 4 vCPUs, that covers roughly 100 renders/month of the bundled ~11-second example. Snapshot storage (the ~1.1 GB snapshot per deployment) is included in Sandbox pricing.

License

Apache-2.0 — same license as HyperFrames itself.