* feat(engine): decouple transparent background from png capture format PNG capture used to imply a cleared page background. A new CaptureOptions.transparentBackground lets lossless opaque PNG capture (4:4:4 MP4 output) keep the page background. Absent, it still follows format === "png", so alpha output and motion blur are unchanged. Opaque PNG skips drawElement, whose verification and worker-encode paths are JPEG-only. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(engine): add 4:4:4 chroma option to getEncoderPreset getEncoderPreset takes an optional chromaSubsampling ("420" by default). "444" returns yuv444p for SDR MP4, so libx264 encodes the High 4:4:4 Predictive profile and odd sizes need no even padding. WebM, MOV and HDR presets ignore it. The ChromaSubsampling type is exported for the producer. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(producer): chromaSubsampling render option with lossless png capture RenderConfig.chromaSubsampling ("420" by default) opts an SDR MP4 render into 4:4:4. "444" encodes libx264 yuv444p and captures every frame as opaque PNG: Chrome's quality-100 JPEG is already 4:2:0 on beginFrame and screenshot capture, and drawElement can fall back to screenshot mid-render, so PNG is the only capture that keeps the colour. drawElement is turned off for these renders. The probe and main capture options share resolveCaptureSurface, so they cannot disagree on format, quality or background. Formats other than mp4, GPU encoding and HDR output are rejected before any work starts, auto-detected HDR sources fail before capture, and distributed requests refuse 444. The default render is unchanged. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(producer,studio-server): accept chromaSubsampling on render routes The shared parseEncoderOptions validates chromaSubsampling and answers 400 for "444" with a non-mp4 format, gpu, or force-hdr, so a request that would come back 4:2:0 never starts a render. The Studio render route, both Studio adapters and the producer HTTP server forward it. The producer server also refuses "444" with outputDynamicRange "hdr", which parseEncoderOptions cannot see. No Studio UI control; the option is route-level like crf and hdrMode. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(cli): add --chroma-subsampling flag `hyperframes render --chroma-subsampling 444` opts an SDR MP4 render into full-resolution chroma (yuv444p with lossless PNG capture). The default stays 420. The plan rejects 444 with a non-mp4 format, --gpu or --hdr before anything renders, with a usage error that names the conflicting flag. The value reaches the local render request and, only when it is 444, the Docker argv, so default Docker invocations are unchanged. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: document 4:4:4 chroma subsampling Add a "4:4:4 masters" section to the rendering guide: when to use --chroma-subsampling 444, why it captures PNG, the measured chroma gain (large for text and UI, none for footage and gradients), its limits, and a player compatibility table to be filled in from testing. Document the flag in the CLI reference, the built-in rendering docs and the hyperframes-cli skill reference (with the regenerated skills manifest), and the chromaSubsampling option in the producer docs. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: add 4:4:4 player compatibility results Fill the 4:4:4 compatibility table from testing H.264 High 4:4:4 Predictive output. Chrome 155, Edge 155, VLC 3.0, Safari on iOS 26.6 and Safari 26.6 on macOS play it, and so does AVFoundation on macOS 26.6, the framework QuickTime Player plays through. Firefox 157 on Windows and both Windows media players do not. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: note the measured render cost of 4:4:4 output Replace the vague "slower capture" note with measured numbers: a text and UI composition rendered in about twice the default time, full-frame footage in about three and a half times, because PNG encoding cost grows with image detail. Refs #5555 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(producer): reject chromaSubsampling 444 in distributed render config Distributed configs have no chroma field and validateDistributedRenderConfig ignored unknown keys, so a JS caller passing chromaSubsampling: "444" to the Lambda or Cloud Run SDK got a 4:2:0 file with no error. Reject it, and make the rendering guide say so precisely. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(producer): check a 444 render reaches the encoder as yuv444p Every helper had tests, but nothing checked the orchestrator passes chromaSubsampling through, so dropping it from the encoder preset or capture surface would turn 444 renders back into 4:2:0 with all tests green. Render a small fixture with "444" and with the default and check pix_fmt with ffprobe. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(producer): move the 444 drawElement gate into a helper Keeps runCompileStage under the fallow complexity threshold. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore: keep comment share at or below the merge-base comment-ratchet failed on 11 files this PR touched. Keep the 4:4:4 rationale once in chromaSubsampling.ts, move the distributed-render reason into its error message, and cut the rest. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(producer): check a 444 render captures full-resolution chroma The encoder check alone passes when chromaSubsampling is dropped from the capture surface: frames are captured as JPEG and encoded yuv444p with 4:2:0 colour. Put a red/blue edge at an odd x, inside a 4:2:0 chroma pair, and require the two pixels to differ in Cb. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(producer): trim the chromaSubsampling.ts header to the package comment share Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix: finish switching to capturesAlpha from #6262 The merge that adopted main's transparent / capturesAlpha left these files uncommitted, so resolveCaptureSurface still returned transparentBackground. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(engine): use transparent / capturesAlpha from #6262 main added CaptureOptions.transparent and capturesAlpha (#6262), which do what this PR's transparentBackground did. Use them, keep the PNG check in drawElementWorkerEncodeEligible, and re-pin test-classification.mjs and the skills manifest against current main. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(producer): cut the 4:4:4 comment blocks to one to three lines The reasoning lives in the PR description with the measurements. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor: reconcile 4:4:4 chroma with latest main Keep main's video-layer capture overrides, template entry resolution, ProRes profile parsing and blur-differential tests alongside the chroma option, and fold the encoder sub-parsers into one loop. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore: keep main's compile-stage tests and regenerate the skills manifest Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@hyperframes/aws-lambda
AWS Lambda adapter for HyperFrames distributed rendering. Ships three things together:
- The Lambda handler that wraps the OSS
plan/renderChunk/assembleprimitives behind a single dispatch boundary Step Functions can drive (src/handler.ts). - A client-side SDK —
renderToLambda,getRenderProgress,deploySite, plusvalidateDistributedRenderConfigandcomputeRenderCost(src/sdk/). - An
aws-cdk-libL2 construct (HyperframesRenderStack) that provisions the same topology asexamples/aws-lambda/template.yamlinside an adopter's own CDK app (src/cdk/).
The handler ZIP and the SAM template still drive a maintainer-run real-AWS smoke flow; the SDK + CDK are the supported public surface for adopters.
Architecture
┌──────────────────────────────────────────────────────────────────┐
│ Step Functions state machine │
│ Plan → Map(N) RenderChunk → Assemble │
└──────────────────────────────────────────────────────────────────┘
│ dispatches by event.Action
▼
┌──────────────────────────────────────────────────────────────────┐
│ One Lambda function (this package's `dist/handler.zip`) │
│ handler.mjs │
│ ├─ Action="plan" → @hyperframes/producer/distributed │
│ ├─ Action="renderChunk" → @hyperframes/producer/distributed │
│ └─ Action="assemble" → @hyperframes/producer/distributed │
│ bin/ffmpeg — ffmpeg-static │
│ node_modules/@sparticuz/chromium/ — Lambda-optimised Chromium │
└──────────────────────────────────────────────────────────────────┘
│ pure functions over local paths
▼
┌──────────────────────────────────────────────────────────────────┐
│ S3 bucket — Plan v2 manifest/blobs + chunks + output │
└──────────────────────────────────────────────────────────────────┘
The handler downloads inputs from S3 into /tmp, calls the OSS primitive,
uploads outputs back to S3, and returns a small JSON result that fits
inside Step Functions' history budget (under 200 bytes per chunk).
Plan transport
Plan v2 is the only supported distributed plan transport.
renderToLambda sends PlanProtocol: "v2" without requiring a protocol
option:
await renderToLambda({
// ...bucket, state machine, project, and config...
});
V2 never overloads PlanS3Uri. The planner returns
PlanV2ManifestS3Uri and PlanV2ArtifactS3Prefix; chunk workers fetch
only manifest-selected chunk artifacts, while the assembler fetches its
own metadata and audio subset. Blobs are immutable SHA-256-addressed
objects, verified on upload and download, and the manifest is published
last. Unknown protocols and digest mismatches are terminal Step Functions
errors.
Upgrade order
This default changes application behavior and requires a coordinated
infrastructure upgrade. Before upgrading an application that calls
renderToLambda:
- Pause new renders and let existing Step Functions executions drain.
- Redeploy the Lambda handler and SAM template or CDK construct from the same new package version.
- Resume renders, then upgrade the application/SDK dependency.
A site is a sites/<id>/files.json file list that an older stack cannot
read. Before it uploads anything,
renderToLambda reads the state machine definition
(states:DescribeStateMachine) and fails with STACK_TOO_OLD when the
stack predates that format. If infrastructure cannot be redeployed first,
keep the application on its previous package version until the redeploy is
complete. Site ids from earlier versions keep working after the redeploy:
when sites/<id>/files.json is missing, the render uses that site's
project.tar.gz.
Chrome runtime
The package supports two Chromium sources:
| Source | Default | Size | When to pick it |
|---|---|---|---|
@sparticuz/chromium |
yes | ~70 MiB compressed | Lambda. Decompresses into /tmp at runtime; the rest of the ecosystem already uses it for headless-Chrome-in-Lambda. |
Bundled chrome-headless-shell |
no | ~140 MiB | Fallback. Used if @sparticuz/chromium ever drops HeadlessExperimental.beginFrame support. |
Pick the source at build time:
bun run --cwd packages/aws-lambda build:zip
bun run --cwd packages/aws-lambda build:zip -- --source=chrome-headless-shell
The handler reads HYPERFRAMES_LAMBDA_CHROME_SOURCE at boot. The build
script sets that env var via Lambda function configuration in
examples/aws-lambda/template.yaml.
BeginFrame regression guard
HyperFrames' renderer drives Chrome via the CDP
HeadlessExperimental.beginFrame command — same path the K8s deploy uses.
The Lambda adapter assumes that @sparticuz/chromium's
chrome-headless-shell build honours BeginFrame. To prove it (and re-prove
it on every release), the package ships a Docker probe:
# Build the Lambda-like container and run the probe.
bun run --cwd packages/aws-lambda probe:beginframe:docker
The probe boots @sparticuz/chromium inside
public.ecr.aws/lambda/nodejs:22 and asserts CDP beginFrame with
screenshot: true returns a PNG buffer. Exit code 0 = green; non-zero =
fall back to bundling chrome-headless-shell directly via --source=chrome-headless-shell.
Building the ZIP
bun install # at the monorepo root
bun run --cwd packages/aws-lambda build:zip # → packages/aws-lambda/dist/handler.zip
bun run --cwd packages/aws-lambda verify:zip-size # CI gate
The build script bundles src/handler.ts via esbuild, stages
@sparticuz/chromium and puppeteer-core under node_modules/, copies
ffmpeg-static into bin/, and zips the result. The unzipped layout is
designed to extract cleanly into Lambda's /var/task/.
verify:zip-size enforces:
- Unzipped ≤ 248 MiB (in-house budget; Lambda hard ceiling is 250 MiB unzipped — AWS docs label this "250 MB" but use binary mebibytes)
- Zipped ≤ 150 MiB (in-house budget; Lambda has no hard zipped cap for S3-deployed functions)
CI fails the PR if either is exceeded.
Running tests
bun run --cwd packages/aws-lambda test # unit tests (no Chrome)
bun run --cwd packages/aws-lambda probe:beginframe # local probe (Linux only)
Using the SDK
After deploying the stack (via the SAM template, CDK construct below, or your own CFN of choice), drive renders from Node:
import { deploySite, getRenderProgress, renderToLambda } from "@hyperframes/aws-lambda";
// One-time upload per project version.
const site = await deploySite({
projectDir: "./my-composition",
bucketName: "hyperframes-render-bucket",
});
// Start a render. Returns immediately — does NOT poll.
const handle = await renderToLambda({
siteHandle: site,
bucketName: site.bucketName,
stateMachineArn: "arn:aws:states:us-east-1:123:stateMachine:hyperframes-render",
config: {
fps: 30,
width: 1920,
height: 1080,
format: "mp4",
chunkSize: 240,
maxParallelChunks: 16,
runtimeCap: "lambda",
},
});
// Poll progress + cost on your own cadence.
const progress = await getRenderProgress({ executionArn: handle.executionArn });
console.log(progress.overallProgress, progress.costs.displayCost);
if (progress.status === "SUCCEEDED" && progress.outputFile) {
console.log("Render landed at", progress.outputFile.s3Uri);
}
renderToLambda validates the config client-side via
validateDistributedRenderConfig and throws a typed InvalidConfigError
before the Step Functions execution starts, so shape errors surface
synchronously instead of as opaque ExecutionFailed results.
getRenderProgress reports an approximate per-render cost
(accruedSoFarUsd plus a formatted displayCost) derived from Lambda
billed-duration × memory × the us-east-1 on-demand rate plus the Step
Functions transition price. The math is documented in
src/sdk/costAccounting.ts; numbers are best-effort and exclude S3
transfer.
Using the CDK construct
import { App, Stack } from "aws-cdk-lib";
import { HyperframesRenderStack } from "@hyperframes/aws-lambda/cdk";
const app = new App();
const stack = new Stack(app, "MyApp");
const render = new HyperframesRenderStack(stack, "Render", {
// optional: reservedConcurrency: 8,
// optional: lambdaMemoryMb: 10240,
// optional: chromeSource: "sparticuz",
});
// Re-export so an adopter app can wire dashboards / SNS topics.
new CfnOutput(stack, "RenderBucketName", { value: render.bucket.bucketName });
new CfnOutput(stack, "StateMachineArn", { value: render.stateMachine.stateMachineArn });
aws-cdk-lib and constructs are optional peer dependencies: SDK-only
consumers don't pull them at runtime. The construct itself imports from
@hyperframes/aws-lambda/cdk.
What's still ahead
hyperframes lambdaCLI (deploy / sites create / render / progress / destroy) — PR 6.5.- IAM bootstrap subcommand (
policies role | user | validate) — PR 6.9. - Lambda-local regression harness (
--mode=lambda-local) — PR 6.6. - Adopter-facing migration guide — PR 6.8.