@hyperframes/producer 0.8.180 → 0.8.183

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/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

@@ -0,0 +1,8 @@
+/**
+ * The true peak one `ebur128=peak=true` pass over the whole file reports, measured in parallel
+ * 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;
+}): 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

@@ -37,7 +37,7 @@
 import { type BeforeCaptureHook, type CaptureOptions, type CapturePerfSummary, type CaptureSession, type EngineConfig } 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;
@@ -121,8 +121,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 +135,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/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.180",
+  "version": "0.8.183",
   "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/engine": "0.8.180",
-    "@hyperframes/lint": "0.8.180",
-    "@hyperframes/parsers": "0.8.180",
-    "@hyperframes/core": "0.8.180",
-    "@hyperframes/studio-server": "0.8.180"
+    "@hyperframes/core": "0.8.183",
+    "@hyperframes/engine": "0.8.183",
+    "@hyperframes/parsers": "0.8.183",
+    "@hyperframes/studio-server": "0.8.183",
+    "@hyperframes/lint": "0.8.183"
   },
   "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.180"
+    "@hyperframes/aws-lambda": "0.8.183"
   },
   "engines": {
     "node": ">=22"