Skip to content

Commit 504ec2b

Browse files
feat(cli): lambda deploy renders on arm64 by default; --video-arch x86_64 keeps x86 (#6073)
* feat(aws-lambda): price arm64 chunk invocations at the arm64 rate getRenderProgress takes chunkArchitecture, the architecture of the function that renders chunks. RenderChunk invocations are priced at its per GB-second rate, both inline and from a Distributed Map's output; plan, audio and assemble stay at the x86 rate. * feat(cli): render chunks on an arm64 function with lambda deploy --video-arch --video-arch arm64 pushes the arm64 video function image to the stack's own ECR repository and deploys the template with VideoImageUri set to its digest. Outside a checkout the image is the one the installed adapter pins; inside a checkout it must come from HYPERFRAMES_LAMBDA_VIDEO_IMAGE, built from that checkout. The default stays x86_64, which always sends an empty VideoImageUri so a redeploy drops a video function rather than keeping it. destroy deletes the repository, render and progress price chunks at the arm64 rate, and policies lists the ECR actions. * fix(cli): push the video image only to an ECR repository this stack tagged * fix(cli): price the plan at the video function's rate now that it runs there * feat(cli): lambda deploy renders on arm64 by default; --video-arch x86_64 keeps x86 * refactor(cli): drop two doc comments the names already carry
1 parent e85f56e commit 504ec2b

19 files changed

Lines changed: 592 additions & 68 deletions

‎docs/deploy/aws-lambda.mdx‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ The Lambda handler is a thin dispatch: parse the Step Functions event, download
4747
| AWS credentials | The CLI and the deploy step both call AWS APIs. | Env vars, `~/.aws/credentials`, SSO, or IMDS — any chain the AWS SDK for JavaScript v3 would resolve. |
4848
| AWS SAM CLI | `hyperframes lambda deploy/destroy` shells out to `sam deploy`/`sam delete`. | [Install guide](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) |
4949
| Lambda adapter | The published CLI loads the AWS adapter only for Lambda commands. Each release pins a prebuilt Lambda handler ZIP (a GitHub release asset); `lambda deploy` downloads it, checks its SHA-256 and deploys it with the adapter's SAM template. No repo checkout needed. | `npm install -g @hyperframes/aws-lambda` alongside the CLI, at the same version |
50-
| HyperFrames repo checkout (optional) | Inside a checkout, or with `HYPERFRAMES_REPO_ROOT` pointing at one, `lambda deploy` builds the handler ZIP from source instead (needs `bun`). Use it to deploy unreleased changes, `--chrome-source=chrome-headless-shell`, or an adapter release older than the prebuilt handler. | `git clone https://github.com/heygen-com/hyperframes`, and `npm install -g bun` or [bun.sh](https://bun.sh) |
50+
| HyperFrames repo checkout (optional) | Inside a checkout, or with `HYPERFRAMES_REPO_ROOT` pointing at one, `lambda deploy` builds the handler ZIP from source instead (needs `bun`). Use it to deploy unreleased changes, `--chrome-source=chrome-headless-shell`, or an adapter release older than the prebuilt handler. A checkout deploy on arm64 also needs the video image built from that checkout (`HYPERFRAMES_LAMBDA_VIDEO_IMAGE`), or `--video-arch x86_64`. | `git clone https://github.com/heygen-com/hyperframes`, and `npm install -g bun` or [bun.sh](https://bun.sh) |
5151

5252
## Three deployment paths
5353

@@ -102,6 +102,10 @@ The `siteId` is content-addressed via a SHA-256 of the project tree. A site is a
102102

103103
The stack's bucket expires objects under `cas/sha256/` 30 days after they were last written (the `ExpireSharedContent` lifecycle rule). Each render or `sites create` that reuses a file at least 7 days old rewrites it in place, so files in use never expire. If a site's files did expire, `lambda render --site-id` re-uploads them from the project directory, if its copies still match. Otherwise, or when `renderToLambda` gets a `siteHandle` but no `projectDir`, the render stops with `SITE_FILES_MISSING` before starting; run `sites create` again to restore them.
104104

105+
#### Upgrading from a version that deployed x86 only
106+
107+
`lambda deploy` now runs the plan and the render chunks on an arm64 container-image function by default; audio and assemble stay on the x86 function. Redeploying an existing stack without `--video-arch` moves it to arm64 and adds the `<stack>-video` ECR repository. To keep a stack on x86, pass `--video-arch x86_64` on every deploy. `--chrome-source chrome-headless-shell` also needs `--video-arch x86_64`, because the arm64 image bundles sparticuz Chrome only.
108+
105109
#### Upgrading from a version before shared content storage
106110

107111
- **Redeploy the stack before upgrading the CLI or SDK that starts renders.** A stack from an earlier version cannot read `files.json` sites. The CLI and `renderToLambda` check the state machine first and stop with `STACK_TOO_OLD` before uploading anything; run `hyperframes lambda deploy` (or redeploy your SAM template or CDK construct from the same version) and render again.
@@ -231,6 +235,8 @@ If progress doesn't advance for >10 minutes, check the Step Functions execution
231235

232236
The render bucket is created with CloudFormation `Retain` on delete — `hyperframes lambda destroy` (or `sam delete`) tears the function + state machine down but the bucket survives. This is intentional: it protects final-rendered MP4s from being lost when you re-deploy. To fully reclaim storage, empty + delete the bucket via the AWS console / `aws s3 rb`.
233237

238+
A stack deployed on arm64 (the default) also has an ECR repository, `<stack>-video`, holding the video function's image. `hyperframes lambda destroy` deletes it after the stack.
239+
234240
### `STACK_TOO_OLD`
235241

236242
The stack was deployed by an earlier version that cannot read this version's sites. Redeploy it (`hyperframes lambda deploy`), then render again. See [Upgrading](#upgrading-from-a-version-before-shared-content-storage).

‎docs/packages/cli.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2207,6 +2207,7 @@ deploy:
22072207
| `--concurrency` | none | Lambda reserved concurrency. Without it, a new stack reserves none and each render runs up to 90% of the account's unreserved concurrency; a redeploy keeps the stack's current reservation; `none` removes it |
22082208
| `--memory` | `10240` | Lambda memory in MB |
22092209
| `--chrome-source` | `sparticuz` | `sparticuz` or `chrome-headless-shell` |
2210+
| `--video-arch` | `arm64` | `arm64` runs the plan and the chunks on an arm64 container-image function, pushed to an ECR repository named `<stack>-video`; audio and assemble stay on x86. Needs `sparticuz`. `x86_64` runs everything on the x86 function |
22102211
| `--skip-build` | off | Reuse the existing `handler.zip` |
22112212

22122213
And these drive `render` and `render-batch`:

‎packages/aws-lambda/src/sdk/costAccounting.test.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,15 @@ describe("computeRenderCost", () => {
1919
expect(result.breakdown.stepFunctionsUsd).toBe(0);
2020
});
2121

22+
it("prices arm64 invocations at the arm64 rate", () => {
23+
// 10 GiB × 6 s = 60 GB-s × $0.0000133334 = $0.0008.
24+
const result = computeRenderCost(
25+
[{ billedDurationMs: 6_000, memorySizeMb: 10_240, estimated: false, architecture: "arm64" }],
26+
0,
27+
);
28+
expect(result.breakdown.lambdaUsd).toBeCloseTo(0.0008, 4);
29+
});
30+
2231
it("sums multiple Lambda invocations", () => {
2332
const invs: BilledLambdaInvocation[] = [
2433
{ billedDurationMs: 1_000, memorySizeMb: 1_024, estimated: false }, // 1 GB-s

‎packages/aws-lambda/src/sdk/costAccounting.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,9 @@
1717
* raw number.
1818
*/
1919

20-
/** On-demand Lambda price, us-east-1, x86_64, on-demand: USD per GB-second. */
21-
const LAMBDA_USD_PER_GB_SECOND = 0.0000166667;
20+
/** On-demand Lambda price, us-east-1: USD per GB-second, by function architecture. */
21+
const LAMBDA_USD_PER_GB_SECOND = { x86_64: 0.0000166667, arm64: 0.0000133334 } as const;
22+
export type LambdaArchitecture = keyof typeof LAMBDA_USD_PER_GB_SECOND;
2223
/** Step Functions Standard Workflows, us-east-1: USD per state transition. */
2324
const SFN_USD_PER_TRANSITION = 0.000025;
2425

@@ -30,6 +31,8 @@ export interface BilledLambdaInvocation {
3031
memorySizeMb: number;
3132
/** `true` if the event payload did NOT carry a billed duration and we fell back to `Duration` or a constant. */
3233
estimated: boolean;
34+
/** Architecture of the invoked function; x86_64 when omitted. */
35+
architecture?: LambdaArchitecture;
3336
}
3437

3538
/** Result of {@link computeRenderCost}. */
@@ -63,7 +66,7 @@ export function computeRenderCost(
6366
let anyEstimated = false;
6467
for (const inv of lambdaInvocations) {
6568
const gbSeconds = (inv.memorySizeMb / 1024) * (inv.billedDurationMs / 1000);
66-
lambdaUsd += gbSeconds * LAMBDA_USD_PER_GB_SECOND;
69+
lambdaUsd += gbSeconds * LAMBDA_USD_PER_GB_SECOND[inv.architecture ?? "x86_64"];
6770
if (inv.estimated) anyEstimated = true;
6871
}
6972
const stepFunctionsUsd = stateTransitions * SFN_USD_PER_TRANSITION;

‎packages/aws-lambda/src/sdk/getRenderProgress.test.ts‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -275,6 +275,36 @@ describe("getRenderProgress", () => {
275275
expect(progress.costs.breakdown.lambdaUsd).toBeCloseTo(0.001, 4);
276276
});
277277

278+
it("prices the plan and chunk invocations at the video function's architecture", async () => {
279+
const sfn = new FakeSFN();
280+
sfn.historyPages = [
281+
[
282+
stateEntered("Plan"),
283+
taskSucceeded({ Action: "plan", TotalFrames: 30, DurationMs: 100_000 }),
284+
stateEntered("RenderChunk"),
285+
taskSucceeded({ Action: "renderChunk", FramesEncoded: 30, DurationMs: 4_000 }),
286+
stateEntered("Assemble"),
287+
taskSucceeded({ Action: "assemble", DurationMs: 2_000 }),
288+
],
289+
];
290+
const progress = await getRenderProgress({
291+
executionArn: "arn",
292+
defaultMemorySizeMb: 10_240,
293+
videoArchitecture: "arm64",
294+
sfn: sfn as unknown as SFNClient,
295+
});
296+
const billed = (ms: number) => ({
297+
billedDurationMs: ms,
298+
memorySizeMb: 10_240,
299+
estimated: false,
300+
});
301+
const arm64 = (ms: number) => ({ ...billed(ms), architecture: "arm64" as const });
302+
const expected = [arm64(100_000), arm64(4_000), billed(2_000)];
303+
expect(progress.costs.breakdown.lambdaUsd).toBe(
304+
computeRenderCost(expected, 0).breakdown.lambdaUsd,
305+
);
306+
});
307+
278308
it("captures Lambda failures with the enclosing state name", async () => {
279309
const sfn = new FakeSFN();
280310
const failed: HistoryEvent = {
@@ -451,6 +481,43 @@ describe("getRenderProgress", () => {
451481
expect(p.costs.breakdown.lambdaUsd).toBe(computeRenderCost(billed, 0).breakdown.lambdaUsd);
452482
});
453483

484+
it("prices the plan and chunks at the arm64 rate when an arm64 video function runs them", async () => {
485+
const sfn = new FakeSFN();
486+
const chunks = Array.from({ length: CHUNKS }, (_, i) => ({
487+
ChunkIndex: i,
488+
FramesEncoded: 16,
489+
DurationMs: 4000,
490+
}));
491+
sfn.historyPages = [
492+
[
493+
...parentUntilMapRun(3600),
494+
{
495+
type: "MapStateExited",
496+
id: 1,
497+
timestamp: new Date(),
498+
stateExitedEventDetails: {
499+
name: "RenderChunksV2",
500+
output: JSON.stringify({ Chunks: chunks }),
501+
},
502+
} as HistoryEvent,
503+
],
504+
];
505+
const p = await getRenderProgress({
506+
executionArn: "arn:x",
507+
videoArchitecture: "arm64",
508+
sfn: sfn as unknown as SFNClient,
509+
});
510+
const plan = { billedDurationMs: 1000, memorySizeMb: 10240, estimated: false };
511+
const chunk = { billedDurationMs: 4000, memorySizeMb: 10240, estimated: false };
512+
const onArm = (inv: typeof plan) => ({ ...inv, architecture: "arm64" as const });
513+
const arm64 = [onArm(plan), ...chunks.map(() => onArm(chunk))];
514+
const allX86 = [plan, ...chunks.map(() => chunk)];
515+
expect(p.costs.breakdown.lambdaUsd).toBe(computeRenderCost(arm64, 0).breakdown.lambdaUsd);
516+
expect(p.costs.breakdown.lambdaUsd).toBeLessThan(
517+
computeRenderCost(allX86, 0).breakdown.lambdaUsd,
518+
);
519+
});
520+
454521
it("surfaces a failed chunk's own error, reading only failed children", async () => {
455522
const statuses = Array.from({ length: CHUNKS }, (_, i) =>
456523
i === 7 ? "FAILED" : i < 100 ? "SUCCEEDED" : "ABORTED",

‎packages/aws-lambda/src/sdk/getRenderProgress.ts‎

Lines changed: 55 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ import {
3232
import {
3333
type BilledLambdaInvocation,
3434
computeRenderCost,
35+
type LambdaArchitecture,
3536
type RenderCost,
3637
} from "./costAccounting.js";
3738

@@ -45,6 +46,8 @@ export interface GetRenderProgressOptions {
4546
* `LambdaMemoryMb` parameter the stack was deployed with.
4647
*/
4748
defaultMemorySizeMb?: number;
49+
/** Architecture of the stack's video function, which runs the plan and the chunks: `arm64` when it has one. */
50+
videoArchitecture?: LambdaArchitecture;
4851
region?: string;
4952
/** Test injection seam. */
5053
sfn?: SFNClient;
@@ -113,10 +116,10 @@ export async function getRenderProgress(opts: GetRenderProgressOptions): Promise
113116
const endedAt = describe.stopDate?.toISOString() ?? null;
114117

115118
const history = await loadFullHistory(sfn, opts.executionArn);
116-
const summary = summarizeHistory(history, memoryMb);
119+
const summary = summarizeHistory(history, memoryMb, opts.videoArchitecture);
117120
const mapRun = findChunkMapRun(history);
118121
const warnings: string[] = [];
119-
if (mapRun?.exited) addChunkResults(summary, mapRun.output, memoryMb);
122+
if (mapRun?.exited) addChunkResults(summary, mapRun.output, memoryMb, opts.videoArchitecture);
120123
else if (mapRun) {
121124
await addRunningMapRun(sfn, mapRun.arn, summary, memoryMb).catch((err: unknown) => {
122125
if ((err as { name?: unknown } | null)?.name !== "AccessDeniedException") throw err;
@@ -194,17 +197,17 @@ function findChunkMapRun(events: HistoryEvent[]): ChunkMapRun | null {
194197
}
195198

196199
/** Exact chunk frames and cost from the chunk results the Map's output carries. */
197-
function addChunkResults(summary: HistorySummary, mapOutput: string | undefined, memoryMb: number) {
200+
function addChunkResults(
201+
summary: HistorySummary,
202+
mapOutput: string | undefined,
203+
memoryMb: number,
204+
architecture: LambdaArchitecture | undefined,
205+
) {
198206
const chunks = (parseJson(mapOutput) as { Chunks?: unknown } | null)?.Chunks;
199207
for (const chunk of Array.isArray(chunks) ? chunks : []) {
200208
summary.lambdasInvoked++;
201209
summary.stateTransitions++;
202-
const billedDurationMs = inferBilledMs(chunk);
203-
summary.lambdaInvocations.push({
204-
billedDurationMs,
205-
memorySizeMb: memoryMb,
206-
estimated: billedDurationMs === 0,
207-
});
210+
summary.lambdaInvocations.push(billedInvocation(chunk, memoryMb, architecture));
208211
applyPayloadFrameCounts(chunk, "RenderChunk", (delta) => {
209212
summary.framesRendered += delta;
210213
});
@@ -267,7 +270,11 @@ interface HistorySummary {
267270
* invocations = `LambdaFunctionScheduled` count. Frame totals come from
268271
* the success-payload of each Lambda invocation.
269272
*/
270-
function summarizeHistory(events: HistoryEvent[], memoryMb: number): HistorySummary {
273+
function summarizeHistory(
274+
events: HistoryEvent[],
275+
memoryMb: number,
276+
videoArchitecture?: LambdaArchitecture,
277+
): HistorySummary {
271278
let framesRendered = 0;
272279
let totalFrames: number | null = null;
273280
let lambdasInvoked = 0;
@@ -314,12 +321,13 @@ function summarizeHistory(events: HistoryEvent[], memoryMb: number): HistorySumm
314321
if (ev.taskSucceededEventDetails?.resourceType !== "lambda") break;
315322
const wrapped = parseJson(ev.taskSucceededEventDetails?.output);
316323
const payload = unwrapLambdaPayload(wrapped);
317-
const billedDurationMs = inferBilledMs(payload);
318-
lambdaInvocations.push({
319-
billedDurationMs,
320-
memorySizeMb: memoryMb,
321-
estimated: billedDurationMs === 0,
322-
});
324+
lambdaInvocations.push(
325+
billedInvocation(
326+
payload,
327+
memoryMb,
328+
stateArchitecture(currentLambdaState, videoArchitecture),
329+
),
330+
);
323331
applyPayloadFrameCounts(payload, currentLambdaState, (delta) => {
324332
framesRendered += delta;
325333
});
@@ -331,12 +339,13 @@ function summarizeHistory(events: HistoryEvent[], memoryMb: number): HistorySumm
331339
}
332340
case "LambdaFunctionSucceeded": {
333341
const payload = parseJson(ev.lambdaFunctionSucceededEventDetails?.output);
334-
const billedDurationMs = inferBilledMs(payload);
335-
lambdaInvocations.push({
336-
billedDurationMs,
337-
memorySizeMb: memoryMb,
338-
estimated: billedDurationMs === 0,
339-
});
342+
lambdaInvocations.push(
343+
billedInvocation(
344+
payload,
345+
memoryMb,
346+
stateArchitecture(currentLambdaState, videoArchitecture),
347+
),
348+
);
340349
applyPayloadFrameCounts(payload, currentLambdaState, (delta) => {
341350
framesRendered += delta;
342351
});
@@ -477,6 +486,30 @@ function isAssembleState(name: string | null | undefined): boolean {
477486
* on `LambdaFunctionSucceeded` (the dedicated `BilledDuration` field
478487
* is in CloudWatch Metrics, not the SFN history payload).
479488
*/
489+
function billedInvocation(
490+
payload: unknown,
491+
memoryMb: number,
492+
architecture: LambdaArchitecture | undefined,
493+
): BilledLambdaInvocation {
494+
const billedDurationMs = inferBilledMs(payload);
495+
return {
496+
billedDurationMs,
497+
memorySizeMb: memoryMb,
498+
estimated: billedDurationMs === 0,
499+
architecture,
500+
};
501+
}
502+
503+
/** The video function runs the plan and the chunks; audio and assemble run on the render function. */
504+
function stateArchitecture(
505+
state: string | null,
506+
videoArchitecture: LambdaArchitecture | undefined,
507+
): LambdaArchitecture | undefined {
508+
return state === "Plan" || state === "PlanV2" || isRenderChunkState(state)
509+
? videoArchitecture
510+
: undefined;
511+
}
512+
480513
function inferBilledMs(payload: unknown): number {
481514
if (!payload || typeof payload !== "object") return 0;
482515
const obj = payload as Record<string, unknown>;

‎packages/cli/src/commands/lambda.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import type { DistributedFormat } from "@hyperframes/aws-lambda/sdk";
1414
import { type CanvasResolution, DISTRIBUTED_FPS, isDistributedFps } from "@hyperframes/core";
1515
import { parseOutputResolutionFlag } from "../utils/parseOutputResolution.js";
1616
import type { Example } from "./_examples.js";
17+
import type { VideoArch } from "./lambda/videoImage.js";
1718
import { c } from "../ui/colors.js";
1819
import { defaultCloudFps } from "../utils/compositionFps.js";
1920
import { isMissingPackageError, missingPackageMessage } from "../utils/missingPackage.js";
@@ -120,6 +121,11 @@ export default defineCommand({
120121
description: "sparticuz | chrome-headless-shell (default: sparticuz)",
121122
},
122123
memory: { type: "string", description: "Lambda memory MB (default: 10240)" },
124+
"video-arch": {
125+
type: "string",
126+
description:
127+
"arm64 | x86_64: where the plan and chunks run; arm64 adds a container-image function (default: arm64)",
128+
},
123129
"skip-build": { type: "boolean", description: "Reuse existing handler.zip (deploy)" },
124130

125131
// sites / render
@@ -258,6 +264,7 @@ export default defineCommand({
258264
reservedConcurrency: parseReservedConcurrency(args.concurrency),
259265
chromeSource: parseChromeSource(args["chrome-source"]),
260266
lambdaMemoryMb: parsePositiveInt(args.memory, "--memory"),
267+
videoArch: parseVideoArch(args["video-arch"]),
261268
skipBuild: Boolean(args["skip-build"]),
262269
});
263270
return;
@@ -483,6 +490,9 @@ const parseQuality = (raw: unknown): (typeof QUALITIES)[number] | undefined =>
483490
parseEnum(raw, QUALITIES, "[lambda render] --quality", undefined);
484491
const parseChromeSource = (raw: unknown): (typeof CHROME_SOURCES)[number] =>
485492
parseEnum(raw, CHROME_SOURCES, "[lambda deploy] --chrome-source", "sparticuz")!;
493+
const VIDEO_ARCHS = ["x86_64", "arm64"] as const satisfies readonly VideoArch[];
494+
const parseVideoArch = (raw: unknown): (typeof VIDEO_ARCHS)[number] | undefined =>
495+
parseEnum(raw, VIDEO_ARCHS, "[lambda deploy] --video-arch", undefined);
486496

487497
/**
488498
* Lambda flavor of the shared {@link parseOutputResolutionFlag} — same wire

0 commit comments

Comments
 (0)