mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* fix(engine): read PRODUCER_RESTRICT_PAGE_NETWORK's usual spellings and restrict on an unknown value true, 1, yes and on turn the render network restriction on and false, 0, no and off leave it off, in any letter case and with surrounding whitespace. Unset or blank stays off for local renders. Any other value now restricts and logs a warning once, instead of leaving the render browser and ffmpeg URL inputs unrestricted. * fix(producer): on a render service the audio probe reads a composition URL from a downloaded copy With PRODUCER_RESTRICT_PAGE_NETWORK on, a video URL the composition names is fetched through the shared downloader (resolved-address check, pinned connection, per-hop redirect checks) before ffprobe reads it, and skipped if the download is refused. In a distributed audio step the copy lands in the mixer's work folder, so the mix reuses it instead of downloading again. Without the flag the probe reads the URL as before. * fix(engine): on a render service a URL that ffmpeg reads in place must be a self-contained container With PRODUCER_RESTRICT_PAGE_NETWORK on, every https input ffmpeg or ffprobe opens directly (such as a signed storage URL for a project's video or audio sidecar) also gets -format_whitelist with the same self-contained containers the Studio media helpers allow. A playlist, manifest or concat list stored under a media file name can no longer make ffmpeg open other network locations. Local renders are unchanged. * fix(producer): the render-service audio probe skips only refused URLs and downloads once A composition URL is skipped, with one warning, only when the download address rules refuse it. Timeouts, HTTP errors and a cancelled render fail the probe as before. Videos without sound, muted or hidden are not downloaded. The in-process extract stage passes the render's abort signal and the mixer's work folder, so the mix reuses the copy. * fix(producer): unit tests load the orchestrator again; raise the engine size budget audioWorkDir moves to render/shared.ts, so tests that replace the audio stage module still load the orchestrator. The format-whitelist test probe ends its options with -- as the ffprobe argv contract requires. The engine packed size budget rises to 500000 bytes.
151 lines
6.6 KiB
Plaintext
151 lines
6.6 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 handler uses `@sparticuz/chromium` by default, with a build-time fallback for bundling `chrome-headless-shell` directly when needed.
|
|
|
|
### 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>
|