mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
* fix(aws-lambda): run chrome-headless-shell 158 in the arm64 video image The arm64 video image now installs Chrome for Testing's linux-arm64 chrome-headless-shell 158.0.8127.36, pinned by sha256 and fetched with curl -f, as the whole shell folder. The Lambda Node 22 base has none of the shared libraries the shell links and no fonts, so the image installs them from the base's repository at the same pinned release. The image sets HYPERFRAMES_LAMBDA_CHROME_SOURCE and HYPERFRAMES_LAMBDA_CHROME_PATH itself, and the nested video function no longer passes ChromeSource, which would override them. stage-arm64-image.ts stops fetching the sparticuz arm64 pack and drops the ZIP's x86 sparticuz Chrome instead. The x86 handler ZIP stays on @sparticuz/chromium, bumped from 148.0.0 to 153.0.0. It builds at 258,502,222 bytes unzipped, under Lambda's 262,144,000-byte limit and the 248 MiB in-house gate. Two fixes for --source=chrome-headless-shell: - build-zip.ts staged only the executable, which exits at launch without its ICU data and .pak files. It now stages the whole shell folder at chrome-headless-shell-linux64/. - Nothing set HYPERFRAMES_LAMBDA_CHROME_PATH, which src/chromium.ts requires for that source. The SAM template and the CDK stack now set it to the bundled shell when ChromeSource asks for it. Drops the unused @types/aws-lambda devDependency, which the dead-code audit reports whenever this package's manifest changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * ci(publish): build the Lambda arm64 video image on an ARM runner The video stage now installs Chrome's system libraries with microdnf, so it runs code for arm64. The pack job built that image on ubuntu-latest with no emulation, which it could do only while the stage copied files. A new lambda-video-image job builds it natively on ubuntu-24.04-arm, from the handler zip whose sha256 the zip job reported, and reports the OCI tarball's sha256. Pack downloads that tarball, checks the sha256 against the job's, and pins it as before. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(aws-lambda): fit the comment ratchet and the package size budget chromium.ts loses the two doc lines on BUNDLED_SHELL_DIR and BUNDLED_SHELL_PATH; the names and the SAM template's comment already say what they are. @hyperframes/aws-lambda's unpacked budget goes from 290,508 to 298,000 bytes. The package unpacks to 295,324 bytes, up from the shared chrome-headless-shell staging module the ZIP and image scripts now import and from the README and docs that describe the two Chrome sources. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
151 lines
6.7 KiB
Plaintext
151 lines
6.7 KiB
Plaintext
---
|
|
title: "@hyperframes/aws-lambda"
|
|
description: "AWS Lambda and Step Functions adapter for distributed HyperFrames rendering."
|
|
---
|
|
|
|
The AWS Lambda package runs HyperFrames' distributed render primitives on AWS. It ships the Lambda handler, a Node client SDK, and an optional CDK construct for provisioning the render stack inside an adopter's AWS account.
|
|
|
|
```bash
|
|
npm install @hyperframes/aws-lambda
|
|
```
|
|
|
|
## When to Use
|
|
|
|
**Use `@hyperframes/aws-lambda` when you need to:**
|
|
- Render large compositions on AWS Lambda instead of one local machine
|
|
- Fan out `plan`, `renderChunk`, and `assemble` through Step Functions
|
|
- Store render inputs, intermediate chunks, and outputs in S3
|
|
- Drive renders from CI, a backend service, or a custom CLI
|
|
- Provision the render topology from a CDK app
|
|
|
|
**Use a different package if you want to:**
|
|
- Render locally or inside your own Node process - use the [CLI](/packages/cli) or [producer](/packages/producer)
|
|
- Run the same distributed model on Google Cloud - use [gcp-cloud-run](/packages/gcp-cloud-run)
|
|
- Build or edit composition HTML - use [studio](/packages/studio), [sdk](/packages/sdk), or [core](/packages/core)
|
|
|
|
<Warning>
|
|
This package is deployment glue for AWS infrastructure. It assumes you control an AWS account, S3 bucket, Step Functions state machine, and Lambda runtime configuration.
|
|
</Warning>
|
|
|
|
## Package Exports
|
|
|
|
| Import | Description |
|
|
|--------|-------------|
|
|
| `@hyperframes/aws-lambda` | Handler types, runtime helpers, S3 transport, and client SDK exports |
|
|
| `@hyperframes/aws-lambda/handler` | Lambda handler entry point for Step Functions dispatch |
|
|
| `@hyperframes/aws-lambda/sdk` | Lightweight Node SDK for deploying sites, starting renders, polling progress, and estimating cost |
|
|
| `@hyperframes/aws-lambda/cdk` | Optional CDK construct for provisioning the render bucket, Lambda, and Step Functions stack |
|
|
|
|
`aws-cdk-lib` and `constructs` are optional peer dependencies. SDK-only consumers do not need them unless they import from `@hyperframes/aws-lambda/cdk`.
|
|
|
|
## Architecture
|
|
|
|
The Lambda adapter wraps the distributed producer primitives behind one dispatch boundary:
|
|
|
|
<Steps>
|
|
<Step title="Plan">
|
|
Fetches the project inputs from S3, probes the composition, prepares audio, and publishes the plan artifacts. Plan v2 defers eligible constant-frame-rate SDR video extraction to the chunk workers; variable-frame-rate sources and required HDR color conversions still run during planning.
|
|
</Step>
|
|
<Step title="Render chunks">
|
|
Step Functions fans out chunk jobs. Each Lambda invocation downloads the assets it needs, extracts its deferred video frames, renders one chunk, and uploads the result.
|
|
</Step>
|
|
<Step title="Assemble">
|
|
Downloads all rendered chunks plus audio assets, assembles the final output, and writes the finished file to S3.
|
|
</Step>
|
|
</Steps>
|
|
|
|
All three phases must fit the configured per-invocation Lambda timeout, at most 15 minutes, and the function's temporary storage. Smaller chunks can reduce each worker's extraction and rendering work, but do not divide video extraction that still happens in Plan. See [long-video planning limits](/deploy/aws-lambda#long-video-planning-times-out) for FFmpeg frame-stall timeouts and how to split jobs that cannot fit.
|
|
|
|
The x86 handler ZIP uses `@sparticuz/chromium` by default, with a build-time fallback for bundling `chrome-headless-shell` directly when needed. The arm64 video image runs Chrome for Testing's linux-arm64 `chrome-headless-shell`.
|
|
|
|
### Page network restriction
|
|
|
|
The handler sets `PRODUCER_RESTRICT_PAGE_NETWORK=true` unless the function already sets it, so a rendered page reaches only its own project files and public internet addresses. Loopback, private, link-local and IPv6 addresses are refused for anything the page loads. An asset on a VPC-only host or behind private DNS is missing from the video.
|
|
|
|
Keep it on when you render compositions you did not write. To turn it off, set `PRODUCER_RESTRICT_PAGE_NETWORK=false` in the function's environment. Only `false`, `0`, `no` or `off` turn it off. Any other value keeps it on, and a value the handler does not recognise logs a warning.
|
|
|
|
## Using the SDK
|
|
|
|
After deploying the AWS resources, use the SDK from Node:
|
|
|
|
```typescript
|
|
import { deploySite, getRenderProgress, renderToLambda } from "@hyperframes/aws-lambda/sdk";
|
|
|
|
const site = await deploySite({
|
|
projectDir: "./my-composition",
|
|
bucketName: "hyperframes-render-bucket",
|
|
});
|
|
|
|
const handle = await renderToLambda({
|
|
siteHandle: site,
|
|
bucketName: site.bucketName,
|
|
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hyperframes-render",
|
|
config: {
|
|
fps: 30,
|
|
width: 1920,
|
|
height: 1080,
|
|
format: "mp4",
|
|
chunkSize: 240,
|
|
maxParallelChunks: 16,
|
|
runtimeCap: "lambda",
|
|
},
|
|
});
|
|
|
|
const progress = await getRenderProgress({ executionArn: handle.executionArn });
|
|
console.log(progress.status, progress.overallProgress, progress.costs.displayCost);
|
|
```
|
|
|
|
Plan v2 is the only supported distributed plan transport. Workers fetch
|
|
manifest-selected content-addressed artifacts, and the SDK sends explicit v2
|
|
without requiring a protocol option.
|
|
|
|
<Warning>
|
|
For an existing installation, pause new renders and drain active Step
|
|
Functions executions. Redeploy the Lambda handler and SAM/CDK state machine
|
|
from the same package version before upgrading the application SDK. Older
|
|
infrastructure may lack the Plan v2-only request and locator contract.
|
|
</Warning>
|
|
|
|
`renderToLambda()` validates the distributed render config before starting the Step Functions execution, so invalid dimensions, formats, chunk sizes, or payload sizes fail synchronously.
|
|
|
|
## Using the CDK Construct
|
|
|
|
```typescript
|
|
import { App, Stack } from "aws-cdk-lib";
|
|
import { HyperframesRenderStack } from "@hyperframes/aws-lambda/cdk";
|
|
|
|
const app = new App();
|
|
const stack = new Stack(app, "VideoRender");
|
|
|
|
const render = new HyperframesRenderStack(stack, "HyperframesRender", {
|
|
// reservedConcurrency: 8,
|
|
// lambdaMemoryMb: 10240,
|
|
// chromeSource: "sparticuz",
|
|
});
|
|
|
|
console.log(render.bucket.bucketName, render.stateMachine.stateMachineArn);
|
|
```
|
|
|
|
## Building the Handler ZIP
|
|
|
|
From the monorepo:
|
|
|
|
```bash
|
|
bun install
|
|
bun run --cwd packages/aws-lambda build:zip
|
|
bun run --cwd packages/aws-lambda verify:zip-size
|
|
```
|
|
|
|
The build stages Chromium, Puppeteer, FFmpeg, and the handler bundle into `packages/aws-lambda/dist/handler.zip`. The size verifier keeps the unzipped artifact below Lambda's deployment limit.
|
|
|
|
## Related topics
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="AWS Lambda Deployment" icon="cloud" href="/deploy/aws-lambda">
|
|
End-to-end deployment details and operational notes.
|
|
</Card>
|
|
<Card title="@hyperframes/producer" icon="video" href="/packages/producer">
|
|
The distributed primitives that the Lambda handler executes.
|
|
</Card>
|
|
</CardGroup>
|