@hyperframes/producer 0.8.205 → 0.8.207

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/animatedGifPrep.d.ts

@@ -30,6 +30,12 @@ export interface PrepareAnimatedGifInputsResult {
     preparedAssets: Map<string, string>;
     preparedGifs: PreparedAnimatedGif[];
 }
+export declare function splitUrlSuffix(src: string): {
+    basePath: string;
+    suffix: string;
+};
+export declare function normalizeRelPath(path: string): string;
+export declare function resolveLocalImageSourcePath(src: string, options: Pick<PrepareAnimatedGifInputsOptions, "projectDir" | "downloadDir" | "sourceAssets">): string | null;
 export declare function buildAnimatedGifTranscodeArgs(input: {
     inputPath: string;
     outputPath: string;

package/dist/services/assetMediaType.d.ts

@@ -15,6 +15,7 @@ export declare class AssetMediaTypeMismatchError extends Error {
     readonly mismatches: readonly AssetMediaTypeMismatch[];
     constructor(mismatches: readonly AssetMediaTypeMismatch[]);
 }
+export declare function mediaProfileMatchesElementType(expected: AssetElementMediaType, profile: MediaProbeProfile): boolean;
 export declare function assertAssetMediaTypeProfile(expected: AssetElementMediaType, profile: MediaProbeProfile, elementIdentity: string): void;
 interface CompositionMediaAssets {
     videos: readonly VideoElement[];

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/heifImagePrep.d.ts

@@ -0,0 +1,69 @@
+export declare const HEIF_IMAGE_CONVERSION_FAILED: "HEIF_IMAGE_CONVERSION_FAILED";
+export declare class HeifImageConversionError extends Error {
+    readonly code: "HEIF_IMAGE_CONVERSION_FAILED";
+    readonly owner: "user";
+    readonly retryable: false;
+    constructor(label: string, reason: string);
+}
+/** The host's ffmpeg or ffprobe cannot do the job; a different photo would not help. */
+export declare class HeifToolUnavailableError extends Error {
+    readonly code: "HEIF_TOOL_UNAVAILABLE";
+    readonly owner: "system";
+    readonly retryable: false;
+    constructor(label: string, reason: string);
+}
+export interface HeifTranscodeRequest {
+    inputPath: string;
+    outputPath: string;
+    timeoutMs?: number;
+}
+export interface PrepareHeifImageInputsOptions {
+    projectDir: string;
+    downloadDir: string;
+    outputDir?: string;
+    outputSrcPrefix?: string;
+    cacheDir?: string;
+    sourceAssets?: Map<string, string>;
+    timeoutMs?: number;
+    transcode?: (input: HeifTranscodeRequest) => Promise<void>;
+    /** Leaves an image whose conversion failed as authored and reports it, instead of throwing. */
+    onFailure?: (error: HeifImageConversionError | HeifToolUnavailableError) => void;
+}
+export interface PreparedHeifImage {
+    sourceSrc: string;
+    outputSrc: string;
+    outputPath: string;
+}
+export interface PrepareHeifImageInputsResult {
+    html: string;
+    preparedAssets: Map<string, string>;
+    preparedImages: PreparedHeifImage[];
+}
+/** True when the leading bytes are a HEIF file by its `ftyp` brands, and not an AVIF one. */
+export declare function isHeifBytes(head: Uint8Array): boolean;
+export interface ProbedStream {
+    width?: number;
+    height?: number;
+    coded_width?: number;
+    coded_height?: number;
+    horizontal_offset?: number;
+    vertical_offset?: number;
+    subcomponents?: {
+        stream_index: number;
+        tile_horizontal_offset: number;
+        tile_vertical_offset: number;
+    }[];
+}
+export interface ProbeJson {
+    streams?: ProbedStream[];
+    stream_groups?: {
+        components?: ProbedStream[];
+        disposition?: {
+            default?: number;
+        };
+    }[];
+}
+/** The primary item's grid: the group ffmpeg marks default, so an auxiliary grid listed first is skipped. */
+export declare function primaryGrid(probed: ProbeJson): ProbedStream | undefined;
+export declare function convertHeifToJpeg(request: HeifTranscodeRequest): Promise<void>;
+export declare function prepareHeifImageInputs(html: string, options: PrepareHeifImageInputsOptions): Promise<PrepareHeifImageInputsResult>;

package/dist/services/heifRotation.d.ts

@@ -0,0 +1,2 @@
+/** Counter-clockwise degrees of the primary item's `irot` property; 0 when none or unreadable. */
+export declare function readHeifPrimaryRotation(buf: Buffer): 0 | 90 | 180 | 270;

package/dist/services/htmlCompiler.d.ts

@@ -175,10 +175,7 @@ export interface CompileForRenderOptions {
     allowSystemFontCapture?: boolean;
     /** Caller cancellation propagated through compile-time font fetches. */
     abortSignal?: AbortSignal;
-    /**
-     * Optional persistent cache directory for prep-time animated GIF → WebM
-     * transcodes. When omitted, the render's downloadDir is used.
-     */
+    /** Persistent cache directory for the animated GIF and HEIC prep transcodes; defaults to downloadDir. */
     animatedGifCacheDir?: string;
     /** FFmpeg timeout for animated GIF transcodes. */
     ffmpegProcessTimeout?: number;

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

package/package.json

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