Skip to content

Commit 54d0af5

Browse files
feat(engine): render sets a keyframe interval and a peak bitrate cap (#6444)
* feat(engine): encoders cap peak bitrate and place keyframes on a set interval * style(engine): shorten the rate-cap comment * style(engine): drop the doc lines the comment ratchet flagged * feat(producer): mp4 renders honour a keyframe interval and a peak bitrate cap on every encoder path * style(producer): shorten the delivery encoder file headers * style(producer): drop a comment line from the segment manifest * style(producer): shorten the integration test header * test: delivery encoder tests follow the ffprobe argv contract and run in the integration lane * feat: the render request, server and Lambda plan carry the keyframe interval and peak bitrate cap * fix(studio): the Studio render route passes the keyframe interval and bitrate cap to the encoder * chore(studio-server): drop a comment the helper's name already says * feat(cli): render and lambda render take --keyframe-interval, --max-bitrate and --buffer-size
1 parent 95e3930 commit 54d0af5

50 files changed

Lines changed: 1101 additions & 38 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/guides/rendering.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,18 @@ MOV is an alpha-preserving editing intermediate and always uses the fixed
143143
ProRes 4444 profile. `--crf` and `--video-bitrate` do not map to that profile
144144
and are rejected for MOV; choose MP4 or WebM when you need those controls.
145145

146+
For delivery to a player or platform, an MP4 render can also set how often a
147+
keyframe lands and how high the bitrate may peak. `--keyframe-interval 2` puts a
148+
keyframe at least every two seconds. `--max-bitrate 8M` caps the peak while the
149+
quality target still decides the rest, and `--buffer-size` (default twice the cap)
150+
sets the window the cap is measured over. Left out, the encode is unchanged.
151+
On Lambda the interval is a maximum, because joining chunks adds keyframes, and
152+
the cap holds per chunk, so a join can burst up to one buffer.
153+
154+
```bash
155+
npx hyperframes render --keyframe-interval 2 --max-bitrate 8M --output delivery.mp4
156+
```
157+
146158
```bash
147159
# Faster review version
148160
npx hyperframes render --quality draft --output review.mp4

‎docs/packages/cli.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1496,6 +1496,9 @@ Quality and file size:
14961496
| ---------------------- | --------------- | -------------------------------------------------------------------------------------------------------- |
14971497
| `--crf` | from `--quality`| Override MP4/WebM encoder CRF, 0–51. Lower is better quality. Not with `--video-bitrate`; rejected for MOV. |
14981498
| `--video-bitrate` | from `--quality`| Target MP4/WebM bitrate, e.g. `10M` or `5000k`. Not with `--crf`; rejected for MOV. |
1499+
| `--keyframe-interval` | encoder default | MP4 only. A keyframe at least every N seconds, e.g. `2`, so a player can seek or switch rendition at that spacing. |
1500+
| `--max-bitrate` | uncapped | MP4 only. Peak video bitrate cap, e.g. `8M`, held alongside the `--crf` or `--quality` target rather than replacing it. |
1501+
| `--buffer-size` | 2 × `--max-bitrate` | MP4 only. Buffer the cap is measured over, e.g. `16M`. Needs `--max-bitrate`. |
14991502
| `--vp9-cpu-used` | encoder default | libvpx-vp9 speed/quality trade-off for WebM, -8 to 8. Env: `PRODUCER_VP9_CPU_USED`. |
15001503
| `--gif-loop` | `0` | GIF loop count, `0` for forever. Range 0–65535, `--format gif` only. |
15011504
| `--hls-segment-seconds`| `4` | HLS target segment length in whole seconds, 1–60. `--format hls` only. Also fixes the encoder GOP so every segment starts on a keyframe. |
@@ -2277,6 +2280,9 @@ And these drive `render` and `render-batch`:
22772280
| `--chunk-size` | auto | Frames per chunk. By default each chunk is sized to finish inside the Lambda timeout |
22782281
| `--max-parallel-chunks` | auto | Chunks per render. By default one wave across the deploy's `--concurrency` (or 90% of the account's unreserved concurrency), widened when a chunk would outrun the Lambda timeout |
22792282
| `--target-chunk-frames` | — | Ceiling on frames per chunk. The planner adds chunks — up to `--max-parallel-chunks` — to stay under it, and short videos still collapse to fewer. Ignored when `--chunk-size` is set. |
2283+
| `--keyframe-interval` | — | MP4 only. Longest gap between keyframes, in seconds. Chunk joins add keyframes, so this is a maximum; with a chunk shorter than the interval the chunk length wins. |
2284+
| `--max-bitrate` | — | MP4 only. Peak video bitrate cap, e.g. `8M`. Each chunk is capped on its own, so a join between two chunks can burst up to one `--buffer-size`. |
2285+
| `--buffer-size` | 2 × `--max-bitrate` | MP4 only. Buffer for the cap, e.g. `16M`. Needs `--max-bitrate`. |
22802286
| `--variables` | — | JSON object reaching every chunk worker as `window.__hfVariables` |
22812287
| `--variables-file` | — | Read those from a JSON file |
22822288
| `--strict-variables` | off | Fail instead of warn on an undeclared or mistyped key |

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import { parseOutputResolutionFlag } from "../utils/parseOutputResolution.js";
1616
import type { Example } from "./_examples.js";
1717
import type { VideoArch } from "./lambda/videoImage.js";
1818
import { c } from "../ui/colors.js";
19+
import { deliveryFlagArgs, parseDeliveryFlags } from "../utils/deliveryFlags.js";
1920
import { defaultCloudFps } from "../utils/compositionFps.js";
2021
import { isMissingPackageError, missingPackageMessage } from "../utils/missingPackage.js";
2122

@@ -153,6 +154,7 @@ export default defineCommand({
153154
format: { type: "string", description: "mp4 | mov | png-sequence | webm (default: mp4)" },
154155
codec: { type: "string", description: "h264 | h265 (mp4 only)" },
155156
quality: { type: "string", description: "draft | standard | high" },
157+
...deliveryFlagArgs,
156158
"chunk-size": {
157159
type: "string",
158160
description:
@@ -340,6 +342,7 @@ export default defineCommand({
340342
format: parseFormat(args.format),
341343
codec: parseCodec(args.codec),
342344
quality: parseQuality(args.quality),
345+
...parseDeliveryFlags(args),
343346
chunkSize: parsePositiveInt(args["chunk-size"], "--chunk-size"),
344347
maxParallelChunks: parsePositiveInt(args["max-parallel-chunks"], "--max-parallel-chunks"),
345348
targetChunkFrames: parsePositiveInt(args["target-chunk-frames"], "--target-chunk-frames"),
@@ -397,6 +400,7 @@ export default defineCommand({
397400
format: parseFormat(args.format),
398401
codec: parseCodec(args.codec),
399402
quality: parseQuality(args.quality),
403+
...parseDeliveryFlags(args),
400404
chunkSize: parsePositiveInt(args["chunk-size"], "--chunk-size"),
401405
maxParallelChunks: parsePositiveInt(args["max-parallel-chunks"], "--max-parallel-chunks"),
402406
targetChunkFrames: parsePositiveInt(args["target-chunk-frames"], "--target-chunk-frames"),

‎packages/cli/src/commands/lambda/render-batch.test.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,12 @@ describe("buildLambdaBatchRenderConfig — aspect-agnostic wire threading", () =
168168
expect(config.outputResolutionAspectAgnostic).toBeUndefined();
169169
});
170170

171+
it("sends the delivery options to every batch entry", () => {
172+
expect(
173+
buildLambdaBatchRenderConfig({ ...baseArgs, keyframeIntervalSeconds: 2, maxBitrate: "8M" }),
174+
).toMatchObject({ keyframeIntervalSeconds: 2, maxBitrate: "8M" });
175+
});
176+
171177
it("hands the deploy's reserved concurrency to the planner", () => {
172178
expect(buildLambdaBatchRenderConfig(baseArgs, 64).workerConcurrency).toBe(64);
173179
});

‎packages/cli/src/commands/lambda/render-batch.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ import { normalizeErrorMessage } from "../../utils/errorMessage.js";
4141
import { resolveOutputResolutionFromSize } from "./_dimensions.js";
4242
import { runWithConcurrencyLimit } from "../../utils/concurrency.js";
4343
import { requireStack } from "./state.js";
44+
import type { DeliveryFlagValues } from "../../utils/deliveryFlags.js";
4445

4546
// Dynamic-import the SDK so tsup keeps it out of the static-import head of
4647
// the CLI bundle. See sites.ts loadSDK() for the full rationale.
@@ -49,7 +50,7 @@ async function loadSDK(): Promise<typeof import("@hyperframes/aws-lambda/sdk")>
4950
}
5051

5152
/** Arguments accepted by `hyperframes lambda render-batch`. */
52-
export interface RenderBatchArgs {
53+
export interface RenderBatchArgs extends DeliveryFlagValues {
5354
projectDir: string;
5455
stackName: string;
5556
/** Path to the JSONL batch file. Each line is a {@link BatchEntry}. */
@@ -361,6 +362,9 @@ export function buildLambdaBatchRenderConfig(
361362
chunkSize: args.chunkSize,
362363
maxParallelChunks: args.maxParallelChunks,
363364
targetChunkFrames: args.targetChunkFrames,
365+
keyframeIntervalSeconds: args.keyframeIntervalSeconds,
366+
maxBitrate: args.maxBitrate,
367+
bufferSize: args.bufferSize,
364368
workerConcurrency,
365369
runtimeCap: "lambda",
366370
};

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,21 @@ describe("buildLambdaRenderConfig — aspect-agnostic wire threading", () => {
5151
expect(config.outputResolutionAspectAgnostic).toBeUndefined();
5252
});
5353

54+
it("sends the delivery options on the wire and nothing when they are unset", () => {
55+
const config = buildLambdaRenderConfig(
56+
{ ...BASE_ARGS, keyframeIntervalSeconds: 2, maxBitrate: "8M", bufferSize: "12M" },
57+
undefined,
58+
);
59+
expect(config).toMatchObject({
60+
keyframeIntervalSeconds: 2,
61+
maxBitrate: "8M",
62+
bufferSize: "12M",
63+
});
64+
expect(
65+
JSON.parse(JSON.stringify(buildLambdaRenderConfig(BASE_ARGS, undefined))),
66+
).not.toHaveProperty("maxBitrate");
67+
});
68+
5469
it("carries variables verbatim through the wire config", () => {
5570
const config = buildLambdaRenderConfig(BASE_ARGS, { alice: "hello" });
5671
expect(config.variables).toEqual({ alice: "hello" });

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import type {
1313
} from "@hyperframes/aws-lambda/sdk";
1414
import type { CanvasResolution, DistributedFps } from "@hyperframes/core";
1515
import { c } from "../../ui/colors.js";
16+
import type { DeliveryFlagValues } from "../../utils/deliveryFlags.js";
1617
import {
1718
reportVariableIssues,
1819
resolveVariablesArg,
@@ -27,7 +28,7 @@ async function loadSDK(): Promise<typeof import("@hyperframes/aws-lambda/sdk")>
2728
return import("@hyperframes/aws-lambda/sdk");
2829
}
2930

30-
export interface RenderArgs {
31+
export interface RenderArgs extends DeliveryFlagValues {
3132
projectDir: string;
3233
stackName: string;
3334
siteId?: string;
@@ -255,6 +256,9 @@ export function buildLambdaRenderConfig(
255256
chunkSize: args.chunkSize,
256257
maxParallelChunks: args.maxParallelChunks,
257258
targetChunkFrames: args.targetChunkFrames,
259+
keyframeIntervalSeconds: args.keyframeIntervalSeconds,
260+
maxBitrate: args.maxBitrate,
261+
bufferSize: args.bufferSize,
258262
workerConcurrency,
259263
runtimeCap: "lambda",
260264
variables,

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import type { Example } from "./_examples.js";
66
import { mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync, rmSync } from "node:fs";
77
import { createRenderPlan, resolveBrowserGpuForCli, type RenderFormat } from "./render/plan.js";
88
import { seedProjectAuthoringSkill } from "../utils/projectConfig.js";
9+
import { deliveryFlagArgs } from "../utils/deliveryFlags.js";
910
import type { CatalogUsage } from "../utils/catalogUsage.js";
1011
import { presentRenderPlan } from "./render/present.js";
1112
import { executeRenderPlan, renderLintContinuationHint, runRenderLint } from "./render/execute.js";
@@ -261,6 +262,7 @@ export default defineCommand({
261262
description:
262263
"Target MP4/WebM video bitrate such as 10M. Mutually exclusive with --crf; unsupported for MOV.",
263264
},
265+
...deliveryFlagArgs,
264266
"vp9-cpu-used": {
265267
type: "string",
266268
description:
@@ -516,6 +518,9 @@ export interface RenderOptions {
516518
crf?: number;
517519
vp9CpuUsed?: number;
518520
videoBitrate?: string;
521+
keyframeIntervalSeconds?: number;
522+
maxBitrate?: string;
523+
bufferSize?: string;
519524
videoFrameFormat?: VideoFrameFormat;
520525
pageMotionBlur?: "off";
521526
quiet: boolean;
@@ -846,6 +851,9 @@ async function renderDocker(
846851
crf: options.crf,
847852
vp9CpuUsed: options.vp9CpuUsed,
848853
videoBitrate: options.videoBitrate,
854+
keyframeIntervalSeconds: options.keyframeIntervalSeconds,
855+
maxBitrate: options.maxBitrate,
856+
bufferSize: options.bufferSize,
849857
videoFrameFormat: options.videoFrameFormat,
850858
pageMotionBlur: options.pageMotionBlur,
851859
quiet: options.quiet,
@@ -1125,6 +1133,9 @@ async function executeLocalRender(
11251133
hdrMode: options.hdrMode,
11261134
crf: options.crf,
11271135
videoBitrate: options.videoBitrate,
1136+
keyframeIntervalSeconds: options.keyframeIntervalSeconds,
1137+
maxBitrate: options.maxBitrate,
1138+
bufferSize: options.bufferSize,
11281139
videoFrameFormat: options.videoFrameFormat,
11291140
pageMotionBlur: options.pageMotionBlur,
11301141
variables: options.variables,

‎packages/cli/src/commands/render/execute.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,9 @@ export function renderOptionsFromPlan(
152152
crf: plan.crf,
153153
vp9CpuUsed: plan.vp9CpuUsed,
154154
videoBitrate: plan.videoBitrate,
155+
keyframeIntervalSeconds: plan.keyframeIntervalSeconds,
156+
maxBitrate: plan.maxBitrate,
157+
bufferSize: plan.bufferSize,
155158
videoFrameFormat: plan.videoFrameFormat,
156159
pageMotionBlur: plan.pageMotionBlur,
157160
quiet: plan.quiet,
@@ -357,6 +360,9 @@ export function batchRowRenderOptions(
357360
crf: plan.crf,
358361
vp9CpuUsed: plan.vp9CpuUsed,
359362
videoBitrate: plan.videoBitrate,
363+
keyframeIntervalSeconds: plan.keyframeIntervalSeconds,
364+
maxBitrate: plan.maxBitrate,
365+
bufferSize: plan.bufferSize,
360366
videoFrameFormat: plan.videoFrameFormat,
361367
pageMotionBlur: plan.pageMotionBlur,
362368
quiet: batchQuiet,

‎packages/cli/src/commands/render/plan.test.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,19 @@ describe("createRenderPlan", () => {
222222
).toBe("10M");
223223
});
224224

225+
it("carries the delivery options into the plan for MP4 and refuses them for other formats", () => {
226+
const flags = { "keyframe-interval": "2", "max-bitrate": "8M", "buffer-size": "12M" };
227+
expect(createRenderPlan({ dir: projectDir, format: "mp4", ...flags })).toMatchObject({
228+
keyframeIntervalSeconds: 2,
229+
maxBitrate: "8M",
230+
bufferSize: "12M",
231+
});
232+
expect(createRenderPlan({ dir: projectDir }).maxBitrate).toBeUndefined();
233+
for (const format of ["webm", "mov", "gif", "hls"]) {
234+
expect(() => createRenderPlan({ dir: projectDir, format, ...flags })).toThrow(CliUsageError);
235+
}
236+
});
237+
225238
it("rejects batch and single-render variables before execution", () => {
226239
expect(() =>
227240
createRenderPlan({ dir: projectDir, batch: "rows.json", variables: '{"name":"Ada"}' }),

0 commit comments

Comments
 (0)