@hyperframes/producer 0.8.209 → 0.8.210

package/dist/index.js

@@ -847,9 +847,26 @@ function resolveHlsEncoderGopLock(outputFormat, fps, segmentSeconds) {
 }
 
 // src/services/render/deliveryEncoder.ts
-import { appendRateCapArgs, keyframeIntervalToGopSize as keyframeIntervalToGopSize2 } from "@hyperframes/engine";
+import {
+  PRORES_PROFILE_NAMES,
+  appendRateCapArgs,
+  isProresProfile,
+  keyframeIntervalToGopSize as keyframeIntervalToGopSize2
+} from "@hyperframes/engine";
+function validateProresProfile(format, proresProfile) {
+  if (proresProfile === void 0) return;
+  if (!isProresProfile(proresProfile)) {
+    throw new Error(
+      `proresProfile must be one of ${PRORES_PROFILE_NAMES.join(", ")}; got ${JSON.stringify(proresProfile)}`
+    );
+  }
+  if (format !== void 0 && format !== "mov") {
+    throw new Error(`proresProfile applies to mov renders, not ${format}`);
+  }
+}
 function validateDeliveryEncoderConfig(config) {
-  const { keyframeIntervalSeconds, maxBitrate, bufferSize, format } = config;
+  const { keyframeIntervalSeconds, maxBitrate, bufferSize, format, proresProfile } = config;
+  validateProresProfile(format, proresProfile);
   if (keyframeIntervalSeconds === void 0 && maxBitrate === void 0 && bufferSize === void 0)
     return;
   if (keyframeIntervalSeconds !== void 0) {
@@ -3230,14 +3247,15 @@ async function extractHdrVideoFrames(args) {
       }
       first.release();
       if (video.loop) (await windows.lease(totalFrames - 1))?.release();
+      const held = holdFirstFrameUntilStreamStarts(windows, firstTick);
       out.set(videoId, {
         dir: frameDir,
-        windows,
+        windows: held,
         width: dims.width,
         height: dims.height,
         frameSize,
         get frameCount() {
-          return windows.totalFrames;
+          return held.totalFrames;
         },
         scratch: Buffer.allocUnsafe(frameSize),
         loop: video.loop,
@@ -3266,9 +3284,18 @@ function hdrWindowFfmpegArgs(a) {
   if (trim > 0) filters.push(`trim=start_frame=${trim}`);
   return [
     ...["-ss", (a.mediaStart + seekFrame / a.fps).toFixed(6), "-i", a.srcPath],
-    ...["-vf", filters.join(","), "-frames:v", String(a.frames)]
+    ...["-vf", filters.join(","), "-frames:v", String(a.frames), "-fps_mode", "passthrough"]
   ];
 }
+function holdFirstFrameUntilStreamStarts(windows, firstTick) {
+  return {
+    get totalFrames() {
+      return firstTick + windows.totalFrames;
+    },
+    lease: (frameIndex) => windows.lease(Math.max(0, frameIndex - firstTick)),
+    close: () => windows.close()
+  };
+}
 function decodeHdrImageBuffers(args) {
   const { log, hdrImageSrcPaths, prep, hdrDiagnostics } = args;
   const out = /* @__PURE__ */ new Map();
@@ -4834,6 +4861,12 @@ function logHdrResolution(input, hdrMode, effectiveHdr, forcedHdrWithoutSources)
     `[Render] HDR ${reason}, output: ${effectiveHdr.transfer.toUpperCase()} (BT.2020, 10-bit H.265)`
   );
 }
+function formatCarriesHdr(format) {
+  return format === "mp4";
+}
+function rendersSdrOnly(config) {
+  return config.hdrMode === "force-sdr" || !formatCarriesHdr(config.format ?? "mp4");
+}
 function resolveEffectiveHdrMode(input) {
   const hdrMode = input.hdrMode ?? "auto";
   const videoColorSpaces = (input.extractionResult?.extracted ?? []).map(
@@ -4855,7 +4888,7 @@ function resolveEffectiveHdrMode(input) {
   } else if (info?.hasHdr && info.dominantTransfer) {
     effectiveHdr = { transfer: info.dominantTransfer };
   }
-  if (effectiveHdr && input.outputFormat !== "mp4") {
+  if (effectiveHdr && !formatCarriesHdr(input.outputFormat)) {
     input.log.warn(formatDowngradeWarning(input.outputFormat, forcedHdrWithoutSources));
     effectiveHdr = void 0;
   }
@@ -9477,7 +9510,7 @@ async function runExtractVideosStage(input) {
         fps: job.config.fps,
         outputDir: join18(compiledDir, "__hyperframes_video_frames"),
         format: job.config.videoFrameFormat ?? "auto",
-        toneMapHdrToSdr: job.config.hdrMode === "force-sdr",
+        toneMapHdrToSdr: rendersSdrOnly(job.config),
         timelineEnd: composition.duration,
         maxTransientRetries: extractionPolicy.maxTransientRetries,
         collectProbeFailures: extractionPolicy.failureMode === "enforce",
@@ -14061,7 +14094,12 @@ async function executeRenderPipeline(input) {
     });
     const encoderHdr = hasHdrContent ? effectiveHdr : void 0;
     const presetFormat = outputFormat === "webm" || outputFormat === "mov" ? outputFormat : "mp4";
-    const preset = getEncoderPreset3(job.config.quality, presetFormat, encoderHdr);
+    const preset = getEncoderPreset3(
+      job.config.quality,
+      presetFormat,
+      encoderHdr,
+      job.config.proresProfile
+    );
     if (job.config.crf != null && job.config.videoBitrate) {
       log.warn(
         `[Render] Both crf=${job.config.crf} and videoBitrate=${job.config.videoBitrate} were set. These are mutually exclusive; honoring crf and ignoring videoBitrate. Set only one to silence this warning.`
@@ -14876,6 +14914,7 @@ async function executeRenderPipeline(input) {
 
 // src/renderRequest.ts
 import {
+  PRORES_PROFILE_NAMES as PRORES_PROFILE_NAMES2,
   isVideoFrameFormat as isVideoFrameFormat2,
   resolveConfig as resolveConfig4,
   validateEngineConfigSnapshot as validateEngineConfigSnapshot2
@@ -16893,6 +16932,8 @@ function buildLockedRenderConfig(input) {
     closedGop: true,
     forceKeyframes: "n=0",
     pixelFormat,
+    // Omitted for the default so existing 4444 plans keep their planHash.
+    ...config.proresProfile && config.proresProfile !== "4444" ? { proresProfile: config.proresProfile } : {},
     chunkSize: input.effectiveChunkSize,
     chunkCount: input.chunkCount,
     runtimeEnv: input.runtimeEnv,
@@ -16914,7 +16955,11 @@ function resolveEncoderTriple(config) {
       `[plan] DistributedRenderConfig.codec is only valid for format="mp4"; received codec=${JSON.stringify(config.codec)} with format=${JSON.stringify(config.format)}. Omit codec for non-mp4 formats: mov is always ProRes 4444, webm is always libvpx-vp9, and png-sequence has no encoder.`
     );
   }
-  return resolveNonMp4EncoderTriple(config.format, config.quality ?? "standard");
+  return resolveNonMp4EncoderTriple(
+    config.format,
+    config.quality ?? "standard",
+    config.proresProfile
+  );
 }
 function resolveMp4EncoderTriple(codec) {
   const c = codec ?? "h264";
@@ -16928,9 +16973,10 @@ function resolveMp4EncoderTriple(codec) {
   }
   return { encoder: "libx264-software", pixelFormat: "yuv420p", preset: "medium" };
 }
-function resolveNonMp4EncoderTriple(format, quality) {
+function resolveNonMp4EncoderTriple(format, quality, proresProfile) {
   if (format === "mov") {
-    return { encoder: "prores-software", pixelFormat: "yuva444p10le", preset: "4444" };
+    const { pixelFormat, preset } = getEncoderPreset4(quality, "mov", void 0, proresProfile);
+    return { encoder: "prores-software", pixelFormat, preset };
   }
   if (format === "webm") {
     const enginePreset = getEncoderPreset4(quality, "webm");
@@ -17585,6 +17631,18 @@ function validateDistributedRenderConfig(config) {
       error instanceof Error ? error.message : String(error)
     );
   }
+  try {
+    validateDeliveryEncoderConfig({
+      format: config.format,
+      fps: { num: config.fps, den: 1 },
+      proresProfile: config.proresProfile
+    });
+  } catch (error) {
+    throw new InvalidConfigError(
+      "config.proresProfile",
+      error instanceof Error ? error.message : String(error)
+    );
+  }
   if (config.chunkSize !== void 0) {
     if (!Number.isInteger(config.chunkSize) || config.chunkSize < 1) {
       throw new InvalidConfigError(
@@ -17824,6 +17882,7 @@ function assertRequestOptionScalars(options) {
   for (const field of ["entryFile", "videoBitrate", "maxBitrate", "bufferSize"]) {
     assertOptionalString(options, field);
   }
+  assertOptionalEnum(options, "proresProfile", PRORES_PROFILE_NAMES2);
   assertOptionalEnum(options, "strictness", ["strict", "best-effort"]);
   assertOptionalEnum(options, "hdrMode", ["auto", "force-hdr", "force-sdr"]);
   assertOptionalEnum(options, "pageMotionBlur", ["off"]);
@@ -17925,6 +17984,7 @@ function distributedConfigFromRequest(request, runtime = {}) {
     pageMotionBlur: options.pageMotionBlur,
     bitrate: options.videoBitrate,
     keyframeIntervalSeconds: options.keyframeIntervalSeconds,
+    proresProfile: options.proresProfile,
     maxBitrate: options.maxBitrate,
     bufferSize: options.bufferSize,
     videoFrameFormat: options.videoFrameFormat,
@@ -17975,6 +18035,7 @@ function renderRequestFromDistributedConfig(input) {
     ...optionalProperty("pageMotionBlur", config.pageMotionBlur),
     ...optionalProperty("videoBitrate", config.bitrate),
     ...optionalProperty("keyframeIntervalSeconds", config.keyframeIntervalSeconds),
+    ...optionalProperty("proresProfile", config.proresProfile),
     ...optionalProperty("maxBitrate", config.maxBitrate),
     ...optionalProperty("bufferSize", config.bufferSize),
     ...optionalProperty("videoFrameFormat", config.videoFrameFormat),
@@ -20597,7 +20658,12 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
       const isPngSequence = plan2.dimensions.format === "png-sequence";
       outputKind = isPngSequence ? "frame-dir" : "file";
       const presetFormat = isPngSequence ? "mp4" : plan2.dimensions.format;
-      const basePreset = getEncoderPreset6(job.config.quality, presetFormat, void 0);
+      const basePreset = getEncoderPreset6(
+        job.config.quality,
+        presetFormat,
+        void 0,
+        encoder.proresProfile
+      );
       const preset = resolvePresetForLockedEncoder(basePreset, encoder.encoder);
       const effectiveQuality = encoder.crf ?? preset.quality;
       const effectiveBitrate = encoder.crf != null ? void 0 : encoder.bitrate;

package/dist/public-server.js

@@ -868,9 +868,26 @@ function resolveHlsEncoderGopLock(outputFormat, fps, segmentSeconds) {
 }
 
 // src/services/render/deliveryEncoder.ts
-import { appendRateCapArgs, keyframeIntervalToGopSize as keyframeIntervalToGopSize2 } from "@hyperframes/engine";
+import {
+  PRORES_PROFILE_NAMES,
+  appendRateCapArgs,
+  isProresProfile,
+  keyframeIntervalToGopSize as keyframeIntervalToGopSize2
+} from "@hyperframes/engine";
+function validateProresProfile(format, proresProfile) {
+  if (proresProfile === void 0) return;
+  if (!isProresProfile(proresProfile)) {
+    throw new Error(
+      `proresProfile must be one of ${PRORES_PROFILE_NAMES.join(", ")}; got ${JSON.stringify(proresProfile)}`
+    );
+  }
+  if (format !== void 0 && format !== "mov") {
+    throw new Error(`proresProfile applies to mov renders, not ${format}`);
+  }
+}
 function validateDeliveryEncoderConfig(config) {
-  const { keyframeIntervalSeconds, maxBitrate, bufferSize, format } = config;
+  const { keyframeIntervalSeconds, maxBitrate, bufferSize, format, proresProfile } = config;
+  validateProresProfile(format, proresProfile);
   if (keyframeIntervalSeconds === void 0 && maxBitrate === void 0 && bufferSize === void 0)
     return;
   if (keyframeIntervalSeconds !== void 0) {
@@ -3247,14 +3264,15 @@ async function extractHdrVideoFrames(args) {
       }
       first.release();
       if (video.loop) (await windows.lease(totalFrames - 1))?.release();
+      const held = holdFirstFrameUntilStreamStarts(windows, firstTick);
       out.set(videoId, {
         dir: frameDir,
-        windows,
+        windows: held,
         width: dims.width,
         height: dims.height,
         frameSize,
         get frameCount() {
-          return windows.totalFrames;
+          return held.totalFrames;
         },
         scratch: Buffer.allocUnsafe(frameSize),
         loop: video.loop,
@@ -3283,9 +3301,18 @@ function hdrWindowFfmpegArgs(a) {
   if (trim > 0) filters.push(`trim=start_frame=${trim}`);
   return [
     ...["-ss", (a.mediaStart + seekFrame / a.fps).toFixed(6), "-i", a.srcPath],
-    ...["-vf", filters.join(","), "-frames:v", String(a.frames)]
+    ...["-vf", filters.join(","), "-frames:v", String(a.frames), "-fps_mode", "passthrough"]
   ];
 }
+function holdFirstFrameUntilStreamStarts(windows, firstTick) {
+  return {
+    get totalFrames() {
+      return firstTick + windows.totalFrames;
+    },
+    lease: (frameIndex) => windows.lease(Math.max(0, frameIndex - firstTick)),
+    close: () => windows.close()
+  };
+}
 function decodeHdrImageBuffers(args) {
   const { log, hdrImageSrcPaths, prep, hdrDiagnostics } = args;
   const out = /* @__PURE__ */ new Map();
@@ -4851,6 +4878,12 @@ function logHdrResolution(input, hdrMode, effectiveHdr, forcedHdrWithoutSources)
     `[Render] HDR ${reason}, output: ${effectiveHdr.transfer.toUpperCase()} (BT.2020, 10-bit H.265)`
   );
 }
+function formatCarriesHdr(format) {
+  return format === "mp4";
+}
+function rendersSdrOnly(config) {
+  return config.hdrMode === "force-sdr" || !formatCarriesHdr(config.format ?? "mp4");
+}
 function resolveEffectiveHdrMode(input) {
   const hdrMode = input.hdrMode ?? "auto";
   const videoColorSpaces = (input.extractionResult?.extracted ?? []).map(
@@ -4872,7 +4905,7 @@ function resolveEffectiveHdrMode(input) {
   } else if (info?.hasHdr && info.dominantTransfer) {
     effectiveHdr = { transfer: info.dominantTransfer };
   }
-  if (effectiveHdr && input.outputFormat !== "mp4") {
+  if (effectiveHdr && !formatCarriesHdr(input.outputFormat)) {
     input.log.warn(formatDowngradeWarning(input.outputFormat, forcedHdrWithoutSources));
     effectiveHdr = void 0;
   }
@@ -9458,7 +9491,7 @@ async function runExtractVideosStage(input) {
         fps: job.config.fps,
         outputDir: join18(compiledDir, "__hyperframes_video_frames"),
         format: job.config.videoFrameFormat ?? "auto",
-        toneMapHdrToSdr: job.config.hdrMode === "force-sdr",
+        toneMapHdrToSdr: rendersSdrOnly(job.config),
         timelineEnd: composition.duration,
         maxTransientRetries: extractionPolicy.maxTransientRetries,
         collectProbeFailures: extractionPolicy.failureMode === "enforce",
@@ -14042,7 +14075,12 @@ async function executeRenderPipeline(input) {
     });
     const encoderHdr = hasHdrContent ? effectiveHdr : void 0;
     const presetFormat = outputFormat === "webm" || outputFormat === "mov" ? outputFormat : "mp4";
-    const preset = getEncoderPreset3(job.config.quality, presetFormat, encoderHdr);
+    const preset = getEncoderPreset3(
+      job.config.quality,
+      presetFormat,
+      encoderHdr,
+      job.config.proresProfile
+    );
     if (job.config.crf != null && job.config.videoBitrate) {
       log.warn(
         `[Render] Both crf=${job.config.crf} and videoBitrate=${job.config.videoBitrate} were set. These are mutually exclusive; honoring crf and ignoring videoBitrate. Set only one to silence this warning.`
@@ -15072,6 +15110,7 @@ import { parseEncoderOptions } from "@hyperframes/studio-server/encoder-options"
 
 // src/renderRequest.ts
 import {
+  PRORES_PROFILE_NAMES as PRORES_PROFILE_NAMES2,
   isVideoFrameFormat as isVideoFrameFormat2,
   resolveConfig as resolveConfig4,
   validateEngineConfigSnapshot as validateEngineConfigSnapshot2
@@ -15354,6 +15393,7 @@ function assertRequestOptionScalars(options) {
   for (const field of ["entryFile", "videoBitrate", "maxBitrate", "bufferSize"]) {
     assertOptionalString(options, field);
   }
+  assertOptionalEnum(options, "proresProfile", PRORES_PROFILE_NAMES2);
   assertOptionalEnum(options, "strictness", ["strict", "best-effort"]);
   assertOptionalEnum(options, "hdrMode", ["auto", "force-hdr", "force-sdr"]);
   assertOptionalEnum(options, "pageMotionBlur", ["off"]);

package/dist/renderRequest.d.ts

@@ -1,4 +1,4 @@
-import { type EngineConfig, type VideoFrameFormat } from "@hyperframes/engine";
+import { type EngineConfig, type ProresProfile, type VideoFrameFormat } from "@hyperframes/engine";
 import { type CanvasResolution, type Fps } from "@hyperframes/core";
 import type { ProducerLogger } from "./logger.js";
 import type { RenderConfig } from "./services/renderOrchestrator.js";
@@ -38,6 +38,7 @@ export interface RenderRequestOptions {
     crf?: number;
     videoBitrate?: string;
     keyframeIntervalSeconds?: number;
+    proresProfile?: ProresProfile;
     maxBitrate?: string;
     bufferSize?: string;
     videoFrameFormat?: VideoFrameFormat;

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

@@ -1,5 +1,5 @@
 import { type CanvasResolution, type DistributedFps } from "@hyperframes/core";
-import { type EngineConfig, type VideoFrameFormat, type AudioProcessingFailure } from "@hyperframes/engine";
+import { type EngineConfig, type VideoFrameFormat, type ProresProfile, type AudioProcessingFailure } from "@hyperframes/engine";
 import { type ProducerLogger } from "../../logger.js";
 import { type RenderJob, type RenderStrictness } from "../renderOrchestrator.js";
 import { type ChunkSliceJson, type PlanFileDigests } from "../render/stages/freezePlan.js";
@@ -49,6 +49,8 @@ export interface DistributedRenderConfig extends Pick<RenderRequestOptions, "pag
     bitrate?: string;
     /** Longest gap between keyframes, in seconds (mp4). Chunk joins add keyframes, so this is a maximum. */
     keyframeIntervalSeconds?: number;
+    /** ProRes profile for `format: "mov"`; the 422 profiles have no alpha. Defaults to `4444`. */
+    proresProfile?: ProresProfile;
     /** Peak bitrate cap (mp4), per chunk. */
     maxBitrate?: string;
     /** Rate-cap buffer; defaults to twice `maxBitrate`. */

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

@@ -7,6 +7,7 @@ export interface DeliveryEncoderConfig {
     keyframeIntervalSeconds?: number;
     maxBitrate?: string;
     bufferSize?: string;
+    proresProfile?: string;
 }
 /** The `EncoderOptions` fields the delivery config sets, ready to spread into any encoder input. */
 export interface DeliveryEncoderOptions {

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

@@ -34,5 +34,6 @@ export declare function findRenderHdrAutoPromotionTrigger(input: {
     }[];
     nativeHdrImageIds: ReadonlySet<string>;
 }): string | undefined;
+export declare function rendersSdrOnly(config: Pick<RenderConfig, "hdrMode" | "format">): boolean;
 export declare function resolveEffectiveHdrMode(input: HdrModeInput): EffectiveHdr;
 export {};

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

@@ -10,6 +10,7 @@
  * has in memory.
  */
 import type { Fps } from "@hyperframes/core";
+import type { ProresProfile } from "@hyperframes/engine";
 import type { RenderRequestOptions } from "../../../renderRequest.js";
 import { type PlanDimensions } from "./planHash.js";
 /**
@@ -32,6 +33,7 @@ export interface LockedRenderConfig extends Pick<RenderRequestOptions, "pageMoti
      */
     quality: "draft" | "standard" | "high";
     ffmpegVersion: string;
+    proresProfile?: ProresProfile;
     preset: string;
     crf?: number;
     bitrate?: string;

package/dist/services/renderOrchestrator.d.ts

@@ -1,5 +1,5 @@
 import { type CanvasResolution, type Fps, type FpsInput, type HfVfxCapture } from "@hyperframes/core";
-import { type EngineConfig, type ExtractionPhaseBreakdown, type VideoFrameFormat, type CaptureOptions, type CaptureVideoMetadataHint, type CaptureSession, type BeforeCaptureHook, type ParallelProgress, type WorkerTask, type CapturePerfSummary, type CaptureWarning, type SubTimelineWaitOutcome, type WorkerSizing, type StaticVerificationOutcome, type CaptureFailureKind, type MotionBlurOptions } from "@hyperframes/engine";
+import { type EngineConfig, type ExtractionPhaseBreakdown, type VideoFrameFormat, type CaptureOptions, type CaptureVideoMetadataHint, type CaptureSession, type BeforeCaptureHook, type ProresProfile, type ParallelProgress, type WorkerTask, type CapturePerfSummary, type CaptureWarning, type SubTimelineWaitOutcome, type WorkerSizing, type StaticVerificationOutcome, type CaptureFailureKind, type MotionBlurOptions } from "@hyperframes/engine";
 import { type ProducerLogger } from "../logger.js";
 import { type RenderOutputFormat } from "./render/renderFormat.js";
 import { type RenderCaptureObservability, type RenderObservabilitySummary, type OpenStallAttempt, type StageStallRule } from "./render/observability.js";
@@ -103,6 +103,8 @@ export interface RenderConfig {
     videoBitrate?: string;
     /** Keyframe every N seconds (mp4). A maximum where chunks join, as on Lambda. */
     keyframeIntervalSeconds?: number;
+    /** MOV only: ProRes profile. Default `4444` keeps alpha; the 422 profiles drop it. */
+    proresProfile?: ProresProfile;
     /** Peak bitrate cap (e.g. "8M", mp4) alongside CRF. */
     maxBitrate?: string;
     /** Rate-cap buffer; defaults to twice `maxBitrate`. */

package/package.json

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