@hyperframes/producer 0.8.181 → 0.8.184

package/dist/services/distributed/assemble.d.ts

@@ -68,6 +68,7 @@ export declare function assemble(planDir: string, chunkOutputs: AssembleChunkPat
      */
     cfr?: boolean;
 }): Promise<AssembleResult>;
-/** Chunks that carry their audio are stitched under one index, the same bytes as the S3 stitch. */
+/** Chunks carrying audio, or with it as a separate file, stitch under one index like S3's. */
 export declare function chunksAreStitchedMp4(planDir: string, cfr: boolean): boolean;
+export declare function stitchesSeparateAudio(planDir: string): boolean;
 export {};

package/dist/services/distributed/chunkFrames.d.ts

@@ -1,4 +1,4 @@
-import { type BeforeCaptureHook, BROWSER_GPU_NOT_SOFTWARE, type CaptureOptions, type EngineConfig, type ExtractedFrames, type FrameLookupTable } from "@hyperframes/engine";
+import { type BeforeCaptureHook, BROWSER_GPU_NOT_SOFTWARE, type CaptureOptions, type EngineConfig, type ExtractedFrames, type FrameLookupTable, type ShownBox } from "@hyperframes/engine";
 import type { LockedRenderConfig } from "../render/stages/freezePlan.js";
 import type { PlanV2RemoteSources } from "./planV2.js";
 import { type DistributedFormat, INVALID_VIDEO_METADATA, type PlanVideosJson } from "./shared.js";
@@ -39,6 +39,10 @@ export declare function buildChunkCaptureOptions(input: {
     videoMetadataHints?: CaptureOptions["videoMetadataHints"];
 }): CaptureOptions;
 /** Extracts the given frames of deferred videos under the names a full extraction gives them. */
+export declare function shownDeferredFrameIndexes(planVideos: PlanVideosJson, frames: Iterable<number>, fps: {
+    num: number;
+    den: number;
+}): Map<string, Set<number>>;
 export declare function extractDeferredVideoFramesForChunk(input: {
     planDir: string;
     planVideos: PlanVideosJson;
@@ -50,4 +54,5 @@ export declare function extractDeferredVideoFramesForChunk(input: {
     outputRoot: string;
     cfg: Pick<EngineConfig, "ffmpegProcessTimeout">;
     remoteSources?: PlanV2RemoteSources;
+    shownBoxes?: ReadonlyMap<string, ShownBox>;
 }): Promise<ExtractedFrames[]>;

package/dist/services/distributed/mp4Stitch.d.ts

@@ -31,9 +31,9 @@ export interface TrackTable {
 }
 /** Each track's sample tables, expanded to one entry per sample (and per chunk). */
 export declare function readTracks(moov: Buffer): TrackTable[];
-export declare function buildStitchedHeader(layouts: readonly Mp4Layout[]): Buffer;
+export declare function buildStitchedHeader(layouts: readonly Mp4Layout[], audio?: Mp4Layout): Buffer;
 export declare function fileRange(path: string): ReadRange;
-/** Local join: the stitched header, then each chunk's mdat payload in order. Like the ffmpeg
- * join, it writes in a work folder beside `outputPath` and renames only a finished file there. */
-export declare function writeStitchedMp4(chunkPaths: readonly string[], outputPath: string): Promise<void>;
+/** Local join: the header, then `audioPath`'s and each chunk's payload. Like the ffmpeg join, it
+ * writes in a work folder beside `outputPath` and renames only a finished file there. */
+export declare function writeStitchedMp4(chunkPaths: readonly string[], outputPath: string, audioPath?: string): Promise<void>;
 export {};

package/dist/services/distributed/plan.d.ts

@@ -211,6 +211,8 @@ export interface BuildLocalExecutionPlanOptions {
     readonly chunksCarryAudio?: boolean;
     /** With `chunksCarryAudio`, also write each chunk's audio packets to their own file. Plan v2 only. */
     readonly sliceChunkAudio?: boolean;
+    /** Leave the audio to {@link buildPlanAudio}; chunks render video only. mp4 without `cfr` only. */
+    readonly deferAudio?: boolean;
 }
 export interface RemoteProjectFile {
     readonly url: string;
@@ -401,7 +403,16 @@ export declare function resolveDistributedEngineConfig(config: DistributedRender
  * Build the shared local execution representation used by both transport
  * protocols. See the module docstring for the directory layout.
  */
+/** Whether the plan leaves its audio to {@link buildPlanAudio}. */
+export declare function plansSeparateAudio(config: Pick<DistributedRenderConfig, "format" | "cfr">, options: Pick<BuildLocalExecutionPlanOptions, "deferAudio">): boolean;
 export declare function buildLocalExecutionPlan(projectDir: string, config: DistributedRenderConfig, executionPlanDir: string, options?: Readonly<BuildLocalExecutionPlanOptions>): Promise<LocalExecutionPlan>;
+/**
+ * The audio of a plan made with `deferAudio`: the mix and true-peak hold that plan would have
+ * made, written to `outputPath` (on `workRoot`'s filesystem) at exactly the video's length.
+ */
+export declare function buildPlanAudio(projectDir: string, config: DistributedRenderConfig, workRoot: string, outputPath: string, options?: Pick<BuildLocalExecutionPlanOptions, "remoteFiles">): Promise<{
+    hasAudio: boolean;
+}>;
 /**
  * Legacy v1 transport wrapper around {@link buildLocalExecutionPlan}.
  *

package/dist/services/distributed/planV2.d.ts

@@ -91,6 +91,7 @@ export interface PlanV2WithPublisherOptions {
     /** See {@link BuildLocalExecutionPlanOptions.remoteFiles}; needs a publisher with `referenceStoredBlob`. */
     readonly remoteFiles?: BuildLocalExecutionPlanOptions["remoteFiles"];
     readonly chunksCarryAudio?: boolean;
+    readonly deferAudio?: boolean;
 }
 export interface PlanV2MaterializationResult {
     readonly planDir: string;

package/dist/services/distributed/projectHash.d.ts

@@ -22,9 +22,6 @@ export declare function listSiteFiles(projectDir: string): string[];
  * same-bytes rename still yields a fresh id. We trim to 16 chars because the
  * full 64 isn't useful in an object key for legibility. Pass `files` when the
  * caller already listed them, so the hashed set is the shipped set.
- *
- * Reads are synchronous: project trees are typically tens of MB at most
- * (HTML/CSS/JS plus a few composition assets), so the simpler shape wins over
- * a streaming pipeline.
+ * Files are read in fixed-size chunks, so no file is ever held whole in memory.
  */
 export declare function hashProjectDir(projectDir: string, files?: readonly string[]): string;

package/dist/services/distributed/renderChunk.d.ts

@@ -73,7 +73,7 @@ export interface ChunkResult {
     sessionBootMs: number;
     captureStageMs: number;
     encodeStageMs: number;
-    /** Capture workers used for this chunk (`calculateOptimalWorkers` result). */
+    /** Capture workers used for this chunk (`resolveChunkCaptureWorkers` result). */
     workers: number;
     /**
      * Effective engine mode used by every worker, after any browser fallback.
@@ -110,11 +110,18 @@ export interface RenderChunkOptions {
      * whole slice.
      */
     frameRange?: ChunkFrameRange;
+    /**
+     * Capture browsers the runtime can host. Raises the machine-wide sizing up to
+     * this many, one browser per 20 frames; never lowers it.
+     */
+    maxCaptureWorkers?: number;
 }
+/** Capture browsers for a chunk: the machine-wide sizing, raised by the runtime's budget. */
+export declare function resolveChunkCaptureWorkers(framesInChunk: number, machineSized: number, maxCaptureWorkers: number | undefined): number;
 /** The frames a chunk renders: its slice, or a validated sub-range of it. */
 export declare function resolveChunkFrameRange(slice: ChunkSliceJson, chunkIndex: number, frameRange: ChunkFrameRange | undefined): ChunkFrameRange;
 /** Compatibility-safe adapter seam for built-in or injected chunk renderers. */
-export type ChunkRenderer = (planDir: string, chunkIndex: number, outputChunkPath: string) => Promise<ChunkResult>;
+export type ChunkRenderer = (planDir: string, chunkIndex: number, outputChunkPath: string, options?: RenderChunkOptions) => Promise<ChunkResult>;
 interface DistributedCaptureSessionDependencies {
     createCaptureSession: typeof createCaptureSession;
     assertSwiftShader: typeof assertSwiftShader;

package/dist/services/render/artifactTransaction.d.ts

@@ -22,6 +22,8 @@ export interface ArtifactTransactionFileSystem {
 export interface ArtifactDurationProbeResult {
     durationSeconds: number;
     frames?: number;
+    width?: number;
+    height?: number;
 }
 /**
  * Pluggable probe used by `ArtifactTransaction.validate()` when the caller
@@ -60,6 +62,9 @@ export interface ArtifactValidationExpectation {
     expectedDurationSeconds: number;
     fps?: number;
     expectedFrames?: number;
+    /** The output size the render was asked for; a route that ignores it must not publish. */
+    expectedWidth?: number;
+    expectedHeight?: number;
     toleranceSeconds?: number;
     /** Path relative to the staging directory to run the duration probe against. */
     probeTarget?: string;
@@ -84,6 +89,8 @@ export declare function buildArtifactExpectation(input: {
     durationSeconds: number;
     fps: number;
     expectedFrames: number | undefined;
+    width?: number;
+    height?: number;
 }): ArtifactValidationExpectation | undefined;
 /**
  * Stages a render beside its final destination and promotes only a validated

package/dist/services/render/audioPadTrim.d.ts

@@ -54,12 +54,16 @@ export interface PadTrimAudioInput {
     probeVideoFrameInfo?: (videoPath: string) => Promise<ProbeVideoFrameInfo>;
     probeAudioInfo?: (audioPath: string, signal?: AbortSignal) => Promise<AudioProbeInfo>;
     probeAudioTruePeakDbfs?: (audioPath: string, signal?: AbortSignal) => Promise<number>;
-    runFfmpeg?: (args: string[]) => Promise<{
-        success: boolean;
-        error?: string;
-        failureReason?: "external_interruption";
-    }>;
+    runFfmpeg?: (args: string[]) => Promise<StepResult>;
+    encodeAac?: AacEncoder;
 }
+interface StepResult {
+    success: boolean;
+    error?: string;
+    failureReason?: "external_interruption";
+}
+/** Encodes `filter` applied to `inputPath` as AAC of exactly `durationSeconds`. */
+type AacEncoder = (inputPath: string, outputPath: string, durationSeconds: number, filter: string) => Promise<StepResult>;
 export type PadTrimOperation = "pad" | "trim" | "copy";
 export interface PadTrimAudioResult {
     success: boolean;
@@ -77,19 +81,21 @@ export interface PadTrimAudioResult {
     /** dB the true-peak limiter lowered the whole mix by; absent when it did not engage. */
     audioLoweredDb?: number;
 }
-export type PadTrimAudioStepKind = "copy" | "trim" | "normalize";
-export interface PadTrimAudioStep {
-    kind: PadTrimAudioStepKind;
+export type PadTrimAudioStep = {
+    kind: "copy";
     args: string[];
-}
+} | {
+    kind: "trim" | "normalize";
+    filter: string;
+};
 export interface PadTrimAudioPlan {
     operation: PadTrimOperation;
     steps: PadTrimAudioStep[];
     cleanupPaths: string[];
 }
 /**
- * Pure helper: decide the pad/trim operation and build the ffmpeg argv
- * sequence that materializes it. Exported separately so unit tests can pin
+ * Pure helper: decide the pad/trim operation and the steps that
+ * materialize it. Exported separately so unit tests can pin
  * every branch without spawning ffmpeg.
  *
  *   - `sourceDuration < targetDuration` → pad with `apad` to the exact target
@@ -102,10 +108,6 @@ export interface PadTrimAudioPlan {
  *     run ffmpeg with `-c:a copy` to materialize the output path.
  */
 export declare function buildPadTrimAudioPlan(audioPath: string, outputPath: string, sourceDurationSeconds: number, targetDurationSeconds: number): PadTrimAudioPlan;
-export declare function buildPadTrimAudioArgs(audioPath: string, outputPath: string, sourceDurationSeconds: number, targetDurationSeconds: number): {
-    args: string[];
-    operation: PadTrimOperation;
-};
 /**
  * Pad or trim the mixed audio so its exact duration matches `frameCount / fps`
  * for the assembled video.
@@ -117,6 +119,8 @@ export declare function padOrTrimAudioToVideoFrameCount(input: PadTrimAudioInput
  */
 export declare function constrainAacTruePeak(input: {
     audioPath: string;
+    /** The PCM `audioPath` was encoded from: a correction re-encodes it instead of decoding the AAC. */
+    sourcePath?: string;
     targetDurationSeconds: number;
     signal?: AbortSignal;
     timeoutMs?: number;
@@ -128,3 +132,4 @@ export declare function constrainAacTruePeak(input: {
 }>;
 export declare function defaultProbeVideoFrameInfo(videoPath: string, signal?: AbortSignal): Promise<ProbeVideoFrameInfo>;
 export declare function runFfprobeJson<T>(args: string[], signal?: AbortSignal): Promise<T>;
+export {};

package/dist/services/render/audioTruePeak.d.ts

@@ -1,12 +1,8 @@
 /**
  * The true peak one `ebur128=peak=true` pass over the whole file reports, measured in parallel
- * segments when the length is known and the rate is 48 kHz: the same digit, not an estimate.
+ * segments when the file is 48 kHz with a known length: the same digit, not an estimate.
  */
 export declare function measureTruePeakDbfs(audioPath: string, options: {
     timeoutMs: number;
     signal?: AbortSignal;
-    segments?: {
-        durationSeconds: number;
-        sampleRate: number;
-    };
 }): Promise<number>;

package/dist/services/render/perfSummary.d.ts

@@ -50,6 +50,8 @@ export declare function roundDb(value: number | undefined): number | undefined;
 export interface DrawElementPerfInput {
     compileGate?: string;
     clampReason?: string;
+    /** Engine init-time gate the pre-capture probe hit; its session may be closed before capture. */
+    probeGateReason?: string;
     workerInversion?: "inverted" | "reverted";
     /** Auto-resolved worker count before the inversion pinned it to 1 (set only when the inversion fired). */
     preInversionWorkers?: number;

package/dist/services/render/stages/audioStage.d.ts

@@ -34,6 +34,8 @@ export interface AudioStageInput {
     audios: CompositionMetadata["audios"];
     masterFxChain?: string;
     urlByAbsentLocalPath?: ReadonlyMap<string, string>;
+    /** Keep the float mix the AAC was encoded from here, for a later re-encode from it. */
+    keepEncoderInputAt?: string;
     abortSignal: AbortSignal | undefined;
     assertNotAborted: () => void;
     /** Where a per-track failure's detail goes. Optional so tests need not pass one. */

package/dist/services/render/stages/captureStage.d.ts

@@ -34,10 +34,10 @@
  * `safeCleanup`, `sampleDirectoryBytes`, etc.) into a shared module so
  * the stages can import them without reaching back into the orchestrator.
  */
-import { type BeforeCaptureHook, type CaptureOptions, type CapturePerfSummary, type CaptureSession, type EngineConfig } from "@hyperframes/engine";
+import { type BeforeCaptureHook, type CaptureOptions, type CapturePerfSummary, type CaptureSession, type EngineConfig, type LandedFrame } from "@hyperframes/engine";
 import type { FileServerHandle } from "../../fileServer.js";
 import type { ProducerLogger } from "../../../logger.js";
-import { type CaptureAttemptSummary, type ProgressCallback, type RenderJob } from "../../renderOrchestrator.js";
+import { type CaptureAttemptSummary, type ProgressCallback, type RenderConfig, type RenderJob } from "../../renderOrchestrator.js";
 import type { SdrDiskCapturePlan } from "../capturePlan.js";
 export interface CaptureStageInput {
     fileServer: FileServerHandle;
@@ -87,6 +87,7 @@ export interface CaptureStageInput {
         startFrame: number;
         endFrame: number;
     };
+    onFrameLanded?: (frame: LandedFrame) => void;
 }
 export interface CaptureStageResult {
     /** Final worker count after any adaptive retry. */
@@ -121,8 +122,13 @@ export type DiskCaptureHeadroom = {
 };
 /** Shared 90% disk gate used by both fallback planning and disk execution. */
 export declare function inspectDiskCaptureHeadroom(framesDir: string, totalFrames: number, captureOptions: CaptureOptions, freeDiskBytes?: (path: string) => number | null): DiskCaptureHeadroom;
-export declare function diskCaptureShortfallError(needBytes: number, freeBytes: number, framesDir: string, basis: "estimate" | "measured"): Error;
-export declare function assertDiskCaptureHeadroom(framesDir: string, totalFrames: number, captureOptions: CaptureOptions, freeDiskBytes?: (path: string) => number | null): void;
+/**
+ * Why this render stores frames and what would take it off disk. `--workers 1`
+ * is offered only when a one-worker run of the same render would stream.
+ */
+export declare function diskCaptureRemedy(cfg: EngineConfig, outputFormat: NonNullable<RenderConfig["format"]>, durationSeconds: number, workerCount: number): string;
+export declare function diskCaptureShortfallError(needBytes: number, freeBytes: number, framesDir: string, basis: "estimate" | "measured", remedy: string): Error;
+export declare function assertDiskCaptureHeadroom(framesDir: string, totalFrames: number, captureOptions: CaptureOptions, remedy: string, freeDiskBytes?: (path: string) => number | null): void;
 /** Frame bytes written so far: the merged frames dir plus every capture attempt's worker dirs. */
 export declare function measureCaptureFrameBytes(workDir: string, framesDir: string): number;
 /** Per-frame callback: after the sample frames, throws if the projected remainder exceeds 90% of free space. */
@@ -130,6 +136,7 @@ export declare function createDiskCaptureProjection(input: {
     framesDir: string;
     totalFrames: number;
     measureBytes: () => number;
+    remedy: string;
     freeDiskBytes?: (path: string) => number | null;
 }): (capturedFrames: number) => void;
 export declare function runCaptureStage(input: CaptureStageInput): Promise<CaptureStageResult>;

package/dist/services/render/stages/encodeStage.d.ts

@@ -26,8 +26,12 @@
  *     branch + same args.
  *   - `Encoding failed: <err>` throws on the encoder's
  *     `success: false`.
+ *
+ * `encodeWhileCapturing` runs the same mp4 encode during multi-worker disk
+ * capture, feeding frames in order as they land, and falls back to this
+ * stage's encode if it fails.
  */
-import { getEncoderPreset, type EngineConfig } from "@hyperframes/engine";
+import { getEncoderPreset, type EngineConfig, type LandedFrame } from "@hyperframes/engine";
 import type { ProducerLogger } from "../../../logger.js";
 import type { ProgressCallback, RenderJob } from "../../renderOrchestrator.js";
 export interface EncodeStageInput {
@@ -71,7 +75,7 @@ export interface EncodeStageInput {
     enableChunkedEncode: boolean;
     chunkedEncodeSize: number;
     /** Already-resolved engine config from the orchestrator; direct callers fall back below. */
-    engineConfig?: Pick<EngineConfig, "ffmpegEncodeTimeout" | "vp9CpuUsed">;
+    engineConfig?: Pick<EngineConfig, "ffmpegEncodeTimeout" | "vp9CpuUsed"> & Partial<Pick<EngineConfig, "ffmpegStreamingTimeout">>;
     abortSignal: AbortSignal | undefined;
     assertNotAborted: () => void;
     onProgress?: ProgressCallback;
@@ -97,4 +101,24 @@ export interface EncodeStageResult {
     /** Wall-clock ms for the encode (or png-copy) phase. */
     encodeMs: number;
 }
+/**
+ * Software libx264 from JPEG only: the streaming encoder then runs the disk encoder's
+ * arguments (same bytes). Needs a core the capture workers leave free.
+ */
+export declare function canEncodeWhileCapturing(input: EncodeStageInput, workerCount: number, cpuCount: number): boolean;
+export interface EncodeWhileCapturing {
+    /** A worker finished writing this frame. */
+    onFrameLanded: (frame: LandedFrame) => void;
+    /** Capture succeeded and every frame is in `framesDir`: encode the rest. */
+    finish: () => Promise<EncodeStageResult>;
+    /** Capture failed: stop the encoder and wait for it to exit. */
+    abort: () => Promise<void>;
+    /** Frames handed to the encoder so far. */
+    readonly framesFed: number;
+}
+/**
+ * Feeds frames 0, 1, 2… to the encoder as each lands; capture never waits on it.
+ * On failure `finish` re-runs `runEncodeStage` on the same frames.
+ */
+export declare function encodeWhileCapturing(input: EncodeStageInput, totalFrames: number): EncodeWhileCapturing;
 export declare function runEncodeStage(input: EncodeStageInput): Promise<EncodeStageResult>;

package/dist/services/render/stages/freezePlan.d.ts

@@ -70,6 +70,7 @@ export interface LockedRenderConfig {
      */
     variables?: Record<string, unknown>;
     chunksCarryAudio?: true;
+    separateAudio?: true;
 }
 export interface CompositionMetadataJson {
     durationSeconds: number;

package/dist/services/renderOrchestrator.d.ts

@@ -1152,8 +1152,8 @@ export declare function closeOrphanedProbeForRetry(probe: CaptureSession, closer
  */
 export declare function resolveParallelCaptureMode(args: {
     platform: NodeJS.Platform;
-    /** A chrome-headless-shell binary was resolved for this render. */
-    headlessShell: boolean;
+    /** The chrome-headless-shell binary resolved for this render, if any. */
+    headlessShellPath: string | undefined;
     forceScreenshot: boolean;
     deviceScaleFactor?: number;
 }): "screenshot" | "beginframe";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.8.181",
+  "version": "0.8.184",
   "description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
   "repository": {
     "type": "git",
@@ -35,11 +35,11 @@
     "postcss": "^8.4.0",
     "puppeteer": "^25.2.1",
     "puppeteer-core": "^25.2.1",
-    "@hyperframes/core": "0.8.181",
-    "@hyperframes/lint": "0.8.181",
-    "@hyperframes/engine": "0.8.181",
-    "@hyperframes/parsers": "0.8.181",
-    "@hyperframes/studio-server": "0.8.181"
+    "@hyperframes/core": "0.8.184",
+    "@hyperframes/engine": "0.8.184",
+    "@hyperframes/lint": "0.8.184",
+    "@hyperframes/parsers": "0.8.184",
+    "@hyperframes/studio-server": "0.8.184"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",
@@ -48,7 +48,7 @@
     "tsx": "^4.21.0",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11",
-    "@hyperframes/aws-lambda": "0.8.181"
+    "@hyperframes/aws-lambda": "0.8.184"
   },
   "engines": {
     "node": ">=22"