@hyperframes/producer 0.8.206 → 0.8.208

package/dist/renderRequest.d.ts

@@ -37,6 +37,9 @@ export interface RenderRequestOptions {
     entryFile?: string;
     crf?: number;
     videoBitrate?: string;
+    keyframeIntervalSeconds?: number;
+    maxBitrate?: string;
+    bufferSize?: string;
     videoFrameFormat?: VideoFrameFormat;
     hdrMode?: RenderConfig["hdrMode"];
     pageMotionBlur?: RenderConfig["pageMotionBlur"];

package/dist/server.d.ts

@@ -47,6 +47,9 @@ interface RenderInput {
     maxRenderMs?: number;
     crf?: number;
     videoBitrate?: string;
+    keyframeIntervalSeconds?: number;
+    maxBitrate?: string;
+    bufferSize?: string;
     useGpu: boolean;
     debug: boolean;
     strictness: RenderConfig["strictness"];

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

@@ -32,7 +32,7 @@ export interface AssembleResult {
     fileSize: number;
 }
 export type AssembleChunkPaths = readonly (string | readonly string[])[];
-type CfrRateControlSource = Partial<Pick<LockedRenderConfig, "quality" | "crf" | "bitrate">>;
+type CfrRateControlSource = Partial<Pick<LockedRenderConfig, "quality" | "crf" | "bitrate" | "maxBitrate" | "bufferSize" | "keyframeIntervalFrames">>;
 export declare function cfrRateControlArgs(locked: CfrRateControlSource): string[];
 /**
  * Assemble the chunk outputs into a single deliverable.

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

@@ -47,6 +47,12 @@ export interface DistributedRenderConfig extends Pick<RenderRequestOptions, "pag
     crf?: number;
     /** Target video bitrate (e.g. `"10M"`); mutually exclusive with `crf`. */
     bitrate?: string;
+    /** Longest gap between keyframes, in seconds (mp4). Chunk joins add keyframes, so this is a maximum. */
+    keyframeIntervalSeconds?: number;
+    /** Peak bitrate cap (mp4), per chunk. */
+    maxBitrate?: string;
+    /** Rate-cap buffer; defaults to twice `maxBitrate`. */
+    bufferSize?: string;
     /**
      * Source-video frame extraction format. Defaults to `"auto"`, matching the
      * in-process renderer: alpha/alpha-capable sources extract as PNG, other

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

@@ -156,6 +156,8 @@ export declare function shouldRetryChunkCaptureWithScreenshot(error: unknown): b
  */
 export declare function runCaptureWithScreenshotFallback<T>(input: {
     forceScreenshot: boolean;
+    /** A failure that is not capture's (the probe's own) is never retried. */
+    canRetry?: () => boolean | Promise<boolean>;
     run: (forceScreenshot: boolean) => Promise<T>;
     resetForScreenshotRetry: () => Promise<void> | void;
     onFallback?: (error: unknown) => void;

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

@@ -0,0 +1,22 @@
+/** Delivery encoder options: their fail-fast gate and the one resolved value every encoder path spreads. */
+import type { Fps } from "@hyperframes/core";
+export interface DeliveryEncoderConfig {
+    format?: string;
+    fps: Fps;
+    hlsSegmentSeconds?: number;
+    keyframeIntervalSeconds?: number;
+    maxBitrate?: string;
+    bufferSize?: string;
+}
+/** The `EncoderOptions` fields the delivery config sets, ready to spread into any encoder input. */
+export interface DeliveryEncoderOptions {
+    maxBitrate?: string;
+    bufferSize?: string;
+    lockGopForChunkConcat: boolean;
+    gopSize: number | undefined;
+}
+/** Reject what the encoders cannot honor, before any frame is captured. */
+export declare function validateDeliveryEncoderConfig(config: DeliveryEncoderConfig): void;
+/** A chunk starts on a keyframe, so its GOP is the chunk, or the interval when that is shorter. */
+export declare function chunkGopFrames(framesInChunk: number, intervalFrames?: number): number;
+export declare function resolveDeliveryEncoderOptions(config: DeliveryEncoderConfig): DeliveryEncoderOptions;

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

@@ -11,7 +11,7 @@
  * the orchestrator hands it to the encoder as
  * `lockGopForChunkConcat: true, gopSize`.
  */
-import { type Fps } from "@hyperframes/core";
+import type { Fps } from "@hyperframes/core";
 /** ffmpeg's own `-hls_time` default is 2 s; 4 s is the VOD consumer's ask. */
 export declare const DEFAULT_HLS_SEGMENT_SECONDS = 4;
 export interface HlsRenderConfig {

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

@@ -28,6 +28,9 @@ export interface SegmentPlanHashInput {
     preset: string;
     quality: number | undefined;
     bitrate: string | undefined;
+    maxBitrate: string | undefined;
+    bufferSize: string | undefined;
+    gopSize: number | undefined;
     pixelFormat: string | undefined;
     imageFormat: string;
     /** Hardware encoder or not: h264_nvenc and libx264 both report codec "h264" but produce different bytes. */

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

@@ -40,6 +40,7 @@ import { type HdrPerfCollector } from "../hdrPerf.js";
 import type { HdrDiagnostics, ProgressCallback, RenderJob } from "../../renderOrchestrator.js";
 import { type CompositionMetadata } from "../shared.js";
 import type { HdrLayeredCapturePlan } from "../capturePlan.js";
+import type { DeliveryEncoderOptions } from "../deliveryEncoder.js";
 export interface CaptureHdrStageInput {
     job: RenderJob;
     cfg: EngineConfig;
@@ -66,6 +67,7 @@ export interface CaptureHdrStageInput {
     preset: ReturnType<typeof getEncoderPreset>;
     effectiveQuality: number;
     effectiveBitrate: string | undefined;
+    deliveryEncoder: DeliveryEncoderOptions;
     fileServer: FileServerHandle;
     buildCaptureOptions: () => CaptureOptions;
     createRenderVideoFrameInjector: () => BeforeCaptureHook | null;

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

@@ -88,6 +88,7 @@ export interface CaptureStageInput {
     interleaveFrames?: boolean;
     /** Each capture attempt opens one, so a stalled attempt is retried by the ladders below. */
     openAttempt?: OpenStallAttempt;
+    verifyFirstSession?: (session: CaptureSession) => Promise<void>;
 }
 export interface CaptureStageResult {
     /** Final worker count after any adaptive retry. */

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

@@ -71,6 +71,8 @@ export interface EncodeStageInput {
     preset: ReturnType<typeof getEncoderPreset>;
     effectiveQuality: number;
     effectiveBitrate: string | undefined;
+    maxBitrate?: string;
+    bufferSize?: string;
     /** Producer config — enables the chunked-concat encoder when on. */
     enableChunkedEncode: boolean;
     chunkedEncodeSize: number;

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

@@ -117,7 +117,7 @@ export declare class VideoExtractionStageError extends Error {
      * validating and applying policy to it.
      */
     readonly publicMetadata: Readonly<Record<string, unknown>>;
-    constructor(code: VideoExtractionStageErrorCode, retryable: boolean, failures: readonly VideoExtractionStageFailureSummary[], extractionFailure?: ExtractionFailureMetadataV1);
+    constructor(code: VideoExtractionStageErrorCode, retryable: boolean, failures: readonly VideoExtractionStageFailureSummary[], extractionFailure?: ExtractionFailureMetadataV1, ffmpegReason?: string);
 }
 export declare function assertVideoExtractionSucceeded(result: ExtractionResult): void;
 export declare function buildHdrProbeStageError(failures: readonly Pick<ReturnType<typeof classifyVideoExtractionError>, "kind" | "retryable">[]): VideoExtractionStageError;

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

@@ -35,6 +35,9 @@ export interface LockedRenderConfig extends Pick<RenderRequestOptions, "pageMoti
     preset: string;
     crf?: number;
     bitrate?: string;
+    maxBitrate?: string;
+    bufferSize?: string;
+    keyframeIntervalFrames?: number;
     /**
      * VP9-only: new WebM plans persist the resolved libvpx-vp9 `-cpu-used`
      * value so distributed workers reproduce the controller's speed/quality

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

@@ -88,9 +88,8 @@ export declare function hasScriptedAudioVolumeAutomation(html: string, audioCoun
  */
 export declare function hasAutoStartVideos(html: string): boolean;
 /**
- * Variable-bound image/audio/video sources are resolved by the browser runtime, not
- * the static compiler. Probe them whenever the current render overrides the
- * referenced variable so media extraction follows the resolved row value.
+ * Variable-bound sources are resolved by the browser runtime, not the static compiler. Probe them whenever the
+ * element's variable has a value (the render's, its mount's `data-variable-values`, a declared default).
  */
 export declare function hasVariableBoundMedia(html: string, variables: Record<string, unknown> | undefined): boolean;
 /**

package/dist/services/renderOrchestrator.d.ts

@@ -101,6 +101,12 @@ export interface RenderConfig {
     crf?: number;
     /** Target video bitrate (e.g. "10M"). Mutually exclusive with `crf`. */
     videoBitrate?: string;
+    /** Keyframe every N seconds (mp4). A maximum where chunks join, as on Lambda. */
+    keyframeIntervalSeconds?: number;
+    /** Peak bitrate cap (e.g. "8M", mp4) alongside CRF. */
+    maxBitrate?: string;
+    /** Rate-cap buffer; defaults to twice `maxBitrate`. */
+    bufferSize?: string;
     /**
      * Source-video frame extraction format. Defaults to `"auto"`, which preserves
      * the historical behavior: alpha/alpha-capable sources extract as PNG, all
@@ -604,6 +610,7 @@ export declare function executeDiskCaptureWithAdaptiveRetry(options: {
     /** Mutated in place: the workers' page-error console lines, for the render's error count. */
     pageErrorLines?: string[];
     openAttempt?: OpenStallAttempt;
+    verifyFirstSession?: (session: CaptureSession) => Promise<void>;
 }): Promise<CaptureAttemptSummary[]>;
 export type RenderConfigInput = Omit<RenderConfig, "fps"> & {
     fps: FpsInput;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.8.206",
+  "version": "0.8.208",
   "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.206",
-    "@hyperframes/parsers": "0.8.206",
-    "@hyperframes/lint": "0.8.206",
-    "@hyperframes/studio-server": "0.8.206",
-    "@hyperframes/engine": "0.8.206"
+    "@hyperframes/core": "0.8.208",
+    "@hyperframes/lint": "0.8.208",
+    "@hyperframes/parsers": "0.8.208",
+    "@hyperframes/studio-server": "0.8.208",
+    "@hyperframes/engine": "0.8.208"
   },
   "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.206"
+    "@hyperframes/aws-lambda": "0.8.208"
   },
   "engines": {
     "node": ">=22"