James Russo
b6b6b8ed3b
Two adopter-facing artifacts that close out Phase 6b's user-facing
surface:
- docs/deploy/migrating-to-hyperframes-lambda.mdx — side-by-side
concept mapping for users coming from another one-command-deploy
video renderer. Covers the verb mapping (deploy/render/progress/
destroy/sites/policies), composition format (plain HTML vs JSX),
render config, and a handful of intentional differences (no HDR
in distributed mode, no webm, gpu-mode=software requirement,
fail-closed font fetch, local stack-state files, narrow-after-
first-deploy IAM pattern). Closes with a migration checklist.
Per repo convention, no competitor framework is named anywhere
in the source — adopters self-identify.
- examples/k8s-jobs/Dockerfile.example + README.md — reference
Dockerfile for adopters who want to run distributed renders
outside AWS Lambda. Bakes Node 22 + chrome-headless-shell +
ffmpeg + the producer source. Deliberately not published to
a registry; adopters build it themselves so Chrome / ffmpeg /
producer versions stay pinned to the checkout they audited.
The README documents the typical K8s Jobs orchestration shape
that points adopters at packages/aws-lambda/src/handler.ts as
the reference adapter.
Migration guide registered under the existing Deploy group in
docs.json. .gitignore extended to negate the new examples/k8s-jobs/
path the same way examples/aws-lambda/ is negated.
No source code changes.
K8s / Cloud Run / ECS reference Dockerfile
This directory ships a reference Dockerfile.example for adopters who want to run HyperFrames distributed renders outside AWS Lambda. The image bakes Node 22 + chrome-headless-shell + ffmpeg + the producer source, and works on Kubernetes Jobs, Argo Workflows, Cloud Run Jobs, ECS Fargate, or plain docker run.
We do not publish this image to a registry — the OSS contract is that adopters build it themselves so Chrome / ffmpeg / producer versions stay pinned to the source checkout they audited, not a floating tag we'd have to keep in sync with every release.
Build
From the repo root:
docker build -t hyperframes-chunk-runner:local -f examples/k8s-jobs/Dockerfile.example .
The build pulls chrome-headless-shell via @puppeteer/browsers and installs Debian system packages for the Chromium ABI deps. Expect a ~1.2 GB compressed image; ~3 GB unpacked.
Use
The producer's distributed primitives are pure functions over local paths. Wire them into your orchestrator however you like:
import { plan, renderChunk, assemble } from "@hyperframes/producer/distributed";
// Controller-side: produce a self-contained planDir + content-addressed planHash.
const planResult = await plan(projectDir, config, planDir);
// Worker-side: render one chunk (byte-identical on retry for the same input).
const chunk = await renderChunk(planDir, chunkIndex, outputChunkPath);
// Controller-side: stitch chunks into the final deliverable.
await assemble(planDir, chunkPaths, audioPath, outputPath);
A typical Kubernetes Jobs orchestration:
- Controller runs a one-shot Job that mounts the project directory + calls
plan(). Uploads the resultingplanDir/to your shared storage (S3, GCS, PVC, …). - Per-chunk Jobs (one per chunk index) download the planDir, call
renderChunk(planDir, i, output), upload the output. Argo Workflows'withSequenceis a natural fit. - Assembler Job downloads the planDir + every chunk output, calls
assemble(...), uploads the final mp4 / mov.
The AWS Lambda implementation in packages/aws-lambda/src/handler.ts is one concrete adapter — read it as a reference for the per-activity event shape.
Lambda?
If you want AWS Lambda specifically, use hyperframes lambda deploy instead — it ships a turnkey deployment. See docs/deploy/aws-lambda.mdx.