@hyperframes/producer 0.8.154 → 0.8.156

package/dist/index.js

@@ -36,7 +36,7 @@ import {
   LOW_MEMORY_TOTAL_MB_THRESHOLD,
   assertConfiguredFfmpegBinariesExist,
   resolveBrowserGpuMode,
-  resolveHeadlessShellPath as resolveHeadlessShellPath2,
+  resolveHeadlessShellPath,
   compositionRequiresWebGpu as compositionRequiresWebGpu2,
   applyConcreteGpuScreenshotClamp,
   explainDrawElementDisabled,
@@ -1837,7 +1837,6 @@ import {
   getCapturePerfSummary as getCapturePerfSummary2,
   initializeSession as initializeSession2,
   prepareCaptureSessionForReuse as prepareCaptureSessionForReuse2,
-  resolveHeadlessShellPath,
   shouldDisableBrowserPoolForParallelWorker,
   spawnStreamingEncoder as spawnStreamingEncoder2
 } from "@hyperframes/engine";
@@ -4081,10 +4080,7 @@ async function openSegmentedSession(input) {
   const videoInjector = input.createRenderVideoFrameInjector();
   const captureOptions = input.buildCaptureOptions();
   const ownBrowser = shouldDisableBrowserPoolForParallelWorker({
-    parallel: (input.workerCount ?? 1) > 1,
-    platform: process.platform,
-    deviceScaleFactor: captureOptions.deviceScaleFactor,
-    headlessShellPath: resolveHeadlessShellPath(captureCfg)
+    parallel: (input.workerCount ?? 1) > 1
   });
   return createCaptureSession2(
     input.fileServer.url,
@@ -4128,6 +4124,14 @@ async function createSegmentWorker(run, id) {
     }
   };
 }
+async function openSegmentWorkersTogether(run, workersToCloseLater) {
+  const opened = await Promise.allSettled(
+    Array.from({ length: run.workerCount }, (_, id) => createSegmentWorker(run, id))
+  );
+  for (const o of opened) if (o.status === "fulfilled") workersToCloseLater.push(o.value);
+  const failure = opened.find((o) => o.status === "rejected");
+  if (failure && failure.status === "rejected") throw failure.reason;
+}
 async function recycleWorkerSession(run, worker, why) {
   run.input.dedupPerfs.push(getCapturePerfSummary2(worker.ctx.session));
   const memory = worker.ctx.session.chromeMemory?.stats();
@@ -4250,7 +4254,7 @@ async function runCaptureSegmentedStage(input) {
   };
   try {
     assertNotAborted();
-    for (let id = 0; id < run.workerCount; id++) workers.push(await createSegmentWorker(run, id));
+    await openSegmentWorkersTogether(run, workers);
     const outcomes = await Promise.allSettled(workers.map((w) => runWorkerLoop(w)));
     for (const worker of workers) dedupPerfs.push(getCapturePerfSummary2(worker.ctx.session));
     const failure = outcomes.find((o) => o.status === "rejected");
@@ -12209,7 +12213,7 @@ async function executeRenderPipeline(input) {
       code: "start_browsers"
     });
     const resolvedBrowserGpuMode = await resolveBrowserGpuMode(cfg.browserGpuMode, {
-      chromePath: resolveHeadlessShellPath2(cfg),
+      chromePath: resolveHeadlessShellPath(cfg),
       browserTimeout: cfg.browserTimeout
     });
     captureForceScreenshot = applyConcreteGpuScreenshotClamp(
@@ -12554,7 +12558,7 @@ async function executeRenderPipeline(input) {
     }
     const parallelCaptureMode = resolveParallelCaptureMode({
       platform: process.platform,
-      headlessShell: resolveHeadlessShellPath2(cfg) !== null,
+      headlessShell: resolveHeadlessShellPath(cfg) !== null,
       forceScreenshot: captureForceScreenshot,
       deviceScaleFactor: captureOptions.deviceScaleFactor
     });
@@ -14241,12 +14245,12 @@ function resolveWorkerEntry2() {
 }
 
 // src/server.ts
-import { isVideoFrameFormat as isVideoFrameFormat3 } from "@hyperframes/engine";
 import {
   parseFps,
   normalizeResolutionFlag,
   isAspectAgnosticResolutionAlias
 } from "@hyperframes/core";
+import { parseEncoderOptions } from "@hyperframes/studio-server/encoder-options";
 var DEFAULT_SERVER_FPS = { num: 30, den: 1 };
 var SAFE_RENDER_ERROR_CODES = /* @__PURE__ */ new Set([
   "ASSET_MEDIA_TYPE_MISMATCH",
@@ -14320,13 +14324,16 @@ function parseRenderOptions(body) {
   const entryFile = nonEmptyString(body.entryFile);
   const format = parseServerFormat(body.format);
   const outputDynamicRange = parseServerOutputDynamicRange(body.outputDynamicRange) ?? fromRenderHdrMode(parseLegacyServerHdrMode(body.hdrMode));
-  const videoFrameFormat = isVideoFrameFormat3(body.videoFrameFormat) ? body.videoFrameFormat : void 0;
+  const encoder = parseEncoderOptions(body, format ?? "mp4");
+  const { crf, videoBitrate, videoFrameFormat } = encoder.ok ? encoder.options : {};
   const { variables, outputResolution, outputResolutionAspectAgnostic } = parseRenderOverrides(body);
   return {
     outputPath,
     fps,
     quality,
     workers,
+    crf,
+    videoBitrate,
     useGpu,
     debug,
     strictness,
@@ -14358,6 +14365,8 @@ function buildRenderJobConfig(input, outputPath, log) {
       quality: input.quality,
       format: input.format ?? "mp4",
       workers: input.workers,
+      crf: input.crf,
+      videoBitrate: input.videoBitrate,
       useGpu: input.useGpu,
       debug: input.debug,
       strictness: input.strictness,
@@ -14379,6 +14388,8 @@ function resolvePreparedRenderOutput(prepared, rendersDir, log) {
   return { input, cleanupProjectDir, absoluteOutputPath };
 }
 function validateRenderOverrides(body) {
+  const encoder = parseEncoderOptions(body, parseServerFormat(body.format) ?? "mp4");
+  if (!encoder.ok) return encoder.error;
   if (body.variables !== void 0 && !isPlainObject2(body.variables)) {
     return 'variables must be a JSON object keyed by variable id (e.g. {"title":"Hello"})';
   }
@@ -17083,12 +17094,20 @@ import {
   appendRenderProvenanceArgs,
   applyFaststart as applyFaststart2,
   describeFfmpegFailure as describeFfmpegFailure2,
+  getEncoderPreset as getEncoderPreset5,
   MIXED_AUDIO_FILENAME as MIXED_AUDIO_FILENAME4,
   muxVideoWithAudio as muxVideoWithAudio2,
   resolveConfig as resolveConfig6,
   runFfmpeg as runFfmpeg5
 } from "@hyperframes/engine";
 import { fpsToFfmpegArg as fpsToFfmpegArg3 } from "@hyperframes/core";
+function cfrRateControlArgs(locked) {
+  const preset = getEncoderPreset5(locked.quality ?? "standard", "mp4");
+  if (locked.crf == null && locked.bitrate) {
+    return ["-preset", preset.preset, "-b:v", locked.bitrate];
+  }
+  return ["-preset", preset.preset, "-crf", String(locked.crf ?? preset.quality)];
+}
 async function assemble(planDir, chunkPaths, audioPath, outputPath, options) {
   const start = Date.now();
   const log = options?.logger ?? defaultLogger;
@@ -17185,7 +17204,9 @@ async function assemble(planDir, chunkPaths, audioPath, outputPath, options) {
       if (!existsSync25(encoderJsonPath)) {
         throw new Error(`[assemble] planDir missing meta/encoder.json: ${encoderJsonPath}`);
       }
-      const encoderJson = JSON.parse(readFileSync13(encoderJsonPath, "utf-8"));
+      const encoderJson = JSON.parse(
+        readFileSync13(encoderJsonPath, "utf-8")
+      );
       if (encoderJson.encoder === "libx265-software") {
         throw new Error(
           `[assemble] cfr=true is not yet supported with codec: "h265". The cfr re-encode pass uses libx264 and would silently transcode the h265 chunks. Either disable cfr or render with codec: "h264".`
@@ -17197,10 +17218,7 @@ async function assemble(planDir, chunkPaths, audioPath, outputPath, options) {
         concatOutputPath,
         "-c:v",
         "libx264",
-        "-preset",
-        "medium",
-        "-crf",
-        "18",
+        ...cfrRateControlArgs(encoderJson),
         "-pix_fmt",
         "yuv420p",
         "-fps_mode",
@@ -17352,7 +17370,7 @@ import {
   createVideoFrameInjector as createVideoFrameInjector2,
   deriveBeginFrameProbeTimeTicks as deriveBeginFrameProbeTimeTicks2,
   extractVideoFramesRange,
-  getEncoderPreset as getEncoderPreset5,
+  getEncoderPreset as getEncoderPreset6,
   initializeSession as initializeSession9,
   probeBeginFrameLiveness as probeBeginFrameLiveness2,
   readWebGlVendorInfoFromCanvas,
@@ -17903,7 +17921,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       const isPngSequence = plan2.dimensions.format === "png-sequence";
       outputKind = isPngSequence ? "frame-dir" : "file";
       const presetFormat = isPngSequence ? "mp4" : plan2.dimensions.format;
-      const basePreset = getEncoderPreset5(job.config.quality, presetFormat, void 0);
+      const basePreset = getEncoderPreset6(job.config.quality, presetFormat, void 0);
       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

@@ -56,7 +56,7 @@ import {
   LOW_MEMORY_TOTAL_MB_THRESHOLD,
   assertConfiguredFfmpegBinariesExist,
   resolveBrowserGpuMode,
-  resolveHeadlessShellPath as resolveHeadlessShellPath2,
+  resolveHeadlessShellPath,
   compositionRequiresWebGpu as compositionRequiresWebGpu2,
   applyConcreteGpuScreenshotClamp,
   explainDrawElementDisabled,
@@ -1856,7 +1856,6 @@ import {
   getCapturePerfSummary as getCapturePerfSummary2,
   initializeSession as initializeSession2,
   prepareCaptureSessionForReuse as prepareCaptureSessionForReuse2,
-  resolveHeadlessShellPath,
   shouldDisableBrowserPoolForParallelWorker,
   spawnStreamingEncoder as spawnStreamingEncoder2
 } from "@hyperframes/engine";
@@ -4100,10 +4099,7 @@ async function openSegmentedSession(input) {
   const videoInjector = input.createRenderVideoFrameInjector();
   const captureOptions = input.buildCaptureOptions();
   const ownBrowser = shouldDisableBrowserPoolForParallelWorker({
-    parallel: (input.workerCount ?? 1) > 1,
-    platform: process.platform,
-    deviceScaleFactor: captureOptions.deviceScaleFactor,
-    headlessShellPath: resolveHeadlessShellPath(captureCfg)
+    parallel: (input.workerCount ?? 1) > 1
   });
   return createCaptureSession2(
     input.fileServer.url,
@@ -4147,6 +4143,14 @@ async function createSegmentWorker(run, id) {
     }
   };
 }
+async function openSegmentWorkersTogether(run, workersToCloseLater) {
+  const opened = await Promise.allSettled(
+    Array.from({ length: run.workerCount }, (_, id) => createSegmentWorker(run, id))
+  );
+  for (const o of opened) if (o.status === "fulfilled") workersToCloseLater.push(o.value);
+  const failure = opened.find((o) => o.status === "rejected");
+  if (failure && failure.status === "rejected") throw failure.reason;
+}
 async function recycleWorkerSession(run, worker, why) {
   run.input.dedupPerfs.push(getCapturePerfSummary2(worker.ctx.session));
   const memory = worker.ctx.session.chromeMemory?.stats();
@@ -4269,7 +4273,7 @@ async function runCaptureSegmentedStage(input) {
   };
   try {
     assertNotAborted();
-    for (let id = 0; id < run.workerCount; id++) workers.push(await createSegmentWorker(run, id));
+    await openSegmentWorkersTogether(run, workers);
     const outcomes = await Promise.allSettled(workers.map((w) => runWorkerLoop(w)));
     for (const worker of workers) dedupPerfs.push(getCapturePerfSummary2(worker.ctx.session));
     const failure = outcomes.find((o) => o.status === "rejected");
@@ -12192,7 +12196,7 @@ async function executeRenderPipeline(input) {
       code: "start_browsers"
     });
     const resolvedBrowserGpuMode = await resolveBrowserGpuMode(cfg.browserGpuMode, {
-      chromePath: resolveHeadlessShellPath2(cfg),
+      chromePath: resolveHeadlessShellPath(cfg),
       browserTimeout: cfg.browserTimeout
     });
     captureForceScreenshot = applyConcreteGpuScreenshotClamp(
@@ -12537,7 +12541,7 @@ async function executeRenderPipeline(input) {
     }
     const parallelCaptureMode = resolveParallelCaptureMode({
       platform: process.platform,
-      headlessShell: resolveHeadlessShellPath2(cfg) !== null,
+      headlessShell: resolveHeadlessShellPath(cfg) !== null,
       forceScreenshot: captureForceScreenshot,
       deviceScaleFactor: captureOptions.deviceScaleFactor
     });
@@ -13703,12 +13707,12 @@ function resolveWorkerEntry2() {
 }
 
 // src/server.ts
-import { isVideoFrameFormat as isVideoFrameFormat3 } from "@hyperframes/engine";
 import {
   parseFps,
   normalizeResolutionFlag,
   isAspectAgnosticResolutionAlias
 } from "@hyperframes/core";
+import { parseEncoderOptions } from "@hyperframes/studio-server/encoder-options";
 
 // src/renderRequest.ts
 import {
@@ -14018,13 +14022,16 @@ function parseRenderOptions(body) {
   const entryFile = nonEmptyString(body.entryFile);
   const format = parseServerFormat(body.format);
   const outputDynamicRange = parseServerOutputDynamicRange(body.outputDynamicRange) ?? fromRenderHdrMode(parseLegacyServerHdrMode(body.hdrMode));
-  const videoFrameFormat = isVideoFrameFormat3(body.videoFrameFormat) ? body.videoFrameFormat : void 0;
+  const encoder = parseEncoderOptions(body, format ?? "mp4");
+  const { crf, videoBitrate, videoFrameFormat } = encoder.ok ? encoder.options : {};
   const { variables, outputResolution, outputResolutionAspectAgnostic } = parseRenderOverrides(body);
   return {
     outputPath,
     fps,
     quality,
     workers,
+    crf,
+    videoBitrate,
     useGpu,
     debug,
     strictness,
@@ -14056,6 +14063,8 @@ function buildRenderJobConfig(input, outputPath, log) {
       quality: input.quality,
       format: input.format ?? "mp4",
       workers: input.workers,
+      crf: input.crf,
+      videoBitrate: input.videoBitrate,
       useGpu: input.useGpu,
       debug: input.debug,
       strictness: input.strictness,
@@ -14077,6 +14086,8 @@ function resolvePreparedRenderOutput(prepared, rendersDir, log) {
   return { input, cleanupProjectDir, absoluteOutputPath };
 }
 function validateRenderOverrides(body) {
+  const encoder = parseEncoderOptions(body, parseServerFormat(body.format) ?? "mp4");
+  if (!encoder.ok) return encoder.error;
   if (body.variables !== void 0 && !isPlainObject2(body.variables)) {
     return 'variables must be a JSON object keyed by variable id (e.g. {"title":"Hello"})';
   }

package/dist/server.d.ts

@@ -43,6 +43,8 @@ interface RenderInput {
     videoFrameFormat?: RenderConfig["videoFrameFormat"];
     outputDynamicRange?: "auto" | "hdr" | "sdr";
     workers?: number;
+    crf?: number;
+    videoBitrate?: string;
     useGpu: boolean;
     debug: boolean;
     strictness: RenderConfig["strictness"];

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

@@ -23,6 +23,7 @@
  * for moving `outputPath` to its orchestration-level storage.
  */
 import { type ProducerLogger } from "../../logger.js";
+import type { LockedRenderConfig } from "../render/stages/freezePlan.js";
 /**
  * Result of {@link assemble}. `fileSize` reflects the final file on disk
  * (mp4/mov) or the cumulative byte total of the frame directory
@@ -34,6 +35,8 @@ export interface AssembleResult {
     framesEncoded: number;
     fileSize: number;
 }
+type CfrRateControlSource = Partial<Pick<LockedRenderConfig, "quality" | "crf" | "bitrate">>;
+export declare function cfrRateControlArgs(locked: CfrRateControlSource): string[];
 /**
  * Assemble the chunk outputs into a single deliverable.
  *
@@ -60,10 +63,11 @@ export declare function assemble(planDir: string, chunkPaths: readonly string[],
      * duration lands on the requested `frameCount / fps` to ms
      * precision, with no PTS-derived drift). Trade-off: ~2-5x the
      * stitch time for a 60s 1080p clip plus second-generation H.264
-     * quality loss (negligible at `-crf 18` but non-zero). Default
+     * quality loss (at the chunks' own CRF or bitrate, non-zero). Default
      * `false` preserves the existing `-c copy` behavior. mp4 only
      * (libx264); webm / mov pass through unchanged because their
      * stream-copy paths don't exhibit the same avg-frame-rate drift.
      */
     cfr?: boolean;
 }): Promise<AssembleResult>;
+export {};

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

@@ -84,9 +84,9 @@ export declare function isVideoFrameCoverageError(err: unknown): err is VideoFra
  */
 export declare function resolveVideoCoverageThreshold(envValue?: string | undefined): number | null;
 /**
- * Count frames in a clip's authored `[start,end)` window. CFR extraction uses
- * FFmpeg's `-vf fps=<fps>` and rounds to the nearest output-frame boundary;
- * VFR extraction uses `-fps_mode cfr -r <fps>` and rounds up. Missing entries
+ * Count frames in a clip's authored `[start,end)` window. CFR extraction
+ * rounds to the nearest output-frame boundary and VFR extraction rounds up,
+ * as `extractionFrameCountForDuration` does. Missing entries
  * retain the fail-closed `ceil` default. Positive sub-frame clips emit one.
  */
 export declare function expectedFramesForClip(start: number, end: number, fps: FpsInput, rounding?: "ceil" | "nearest"): number;

package/package.json

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