@hyperframes/producer 0.8.181 → 0.8.183

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

@@ -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.181",
+  "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/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.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.181"
+    "@hyperframes/aws-lambda": "0.8.183"
   },
   "engines": {
     "node": ">=22"