feat(producer): optional targetChunkFrames to bound per-chunk frames (#1332)

* feat(producer): optional targetChunkFrames to bound per-chunk frames

* feat(cli): expose --target-chunk-frames on lambda + cloudrun render; document it

packages/cli/src/commands/cloudrun.ts

@@ -144,6 +144,11 @@ export default defineCommand({
     quality: { type: "string", description: "draft | standard | high" },
     "chunk-size": { type: "string", description: "Frames per chunk" },
     "max-parallel-chunks": { type: "string", description: "Max concurrent chunks" },
+    "target-chunk-frames": {
+      type: "string",
+      description:
+        "Cap per-chunk frames; auto-adds chunks (up to --max-parallel-chunks) to keep each under this. Ignored if --chunk-size is set.",
+    },
     "output-resolution": {
       type: "string",
       description:
@@ -781,6 +786,7 @@ function buildRenderConfig(
     quality: parseQuality(args.quality),
     chunkSize: parsePositiveInt(args["chunk-size"], "--chunk-size"),
     maxParallelChunks: parsePositiveInt(args["max-parallel-chunks"], "--max-parallel-chunks"),
+    targetChunkFrames: parsePositiveInt(args["target-chunk-frames"], "--target-chunk-frames"),
     outputResolution: parseOutputResolution(args["output-resolution"]),
     variables,
   });

packages/cli/src/commands/lambda.ts

@@ -133,6 +133,11 @@ export default defineCommand({
     quality: { type: "string", description: "draft | standard | high" },
     "chunk-size": { type: "string", description: "Frames per chunk (default: 240)" },
     "max-parallel-chunks": { type: "string", description: "Max concurrent chunks (default: 16)" },
+    "target-chunk-frames": {
+      type: "string",
+      description:
+        "Cap per-chunk frames; auto-adds chunks (up to --max-parallel-chunks) to keep each under this. Ignored if --chunk-size is set.",
+    },
     "execution-name": {
       type: "string",
       description: "Step Functions execution name (default: hf-render-<uuid>)",
@@ -311,6 +316,7 @@ export default defineCommand({
           quality: parseQuality(args.quality),
           chunkSize: parsePositiveInt(args["chunk-size"], "--chunk-size"),
           maxParallelChunks: parsePositiveInt(args["max-parallel-chunks"], "--max-parallel-chunks"),
+          targetChunkFrames: parsePositiveInt(args["target-chunk-frames"], "--target-chunk-frames"),
           executionName: args["execution-name"] as string | undefined,
           outputKey: args["output-key"] as string | undefined,
           variables: args.variables as string | undefined,
@@ -363,6 +369,7 @@ export default defineCommand({
           quality: parseQuality(args.quality),
           chunkSize: parsePositiveInt(args["chunk-size"], "--chunk-size"),
           maxParallelChunks: parsePositiveInt(args["max-parallel-chunks"], "--max-parallel-chunks"),
+          targetChunkFrames: parsePositiveInt(args["target-chunk-frames"], "--target-chunk-frames"),
           maxConcurrent: parsePositiveInt(args["max-concurrent"], "--max-concurrent"),
           strictVariables: Boolean(args["strict-variables"]),
           dryRun: Boolean(args["dry-run"]),

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

@@ -69,6 +69,7 @@ export interface RenderBatchArgs {
   quality?: "draft" | "standard" | "high";
   chunkSize?: number;
   maxParallelChunks?: number;
+  targetChunkFrames?: number;
   /**
    * Maximum in-flight Step Functions starts at any moment. Caps fan-out
    * so a 10 000-entry batch doesn't try to spawn 10 000 executions
@@ -217,6 +218,7 @@ export async function runRenderBatch(args: RenderBatchArgs): Promise<void> {
     quality: args.quality,
     chunkSize: args.chunkSize,
     maxParallelChunks: args.maxParallelChunks,
+    targetChunkFrames: args.targetChunkFrames,
     runtimeCap: "lambda",
   };
 

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

@@ -47,6 +47,7 @@ export interface RenderArgs {
   quality?: "draft" | "standard" | "high";
   chunkSize?: number;
   maxParallelChunks?: number;
+  targetChunkFrames?: number;
   executionName?: string;
   outputKey?: string;
   /** Inline JSON for `--variables '{...}'`. Mutually exclusive with `variablesFile`. */
@@ -123,6 +124,7 @@ export async function runRender(args: RenderArgs): Promise<void> {
     quality: args.quality,
     chunkSize: args.chunkSize,
     maxParallelChunks: args.maxParallelChunks,
+    targetChunkFrames: args.targetChunkFrames,
     runtimeCap: "lambda",
     variables,
   };