@hyperframes/producer 0.8.190 → 0.8.191

package/dist/index.js

@@ -1508,7 +1508,7 @@ async function defaultArtifactDurationProbe(path) {
   };
 }
 function buildArtifactExpectation(input) {
-  if (input.outputFormat === "png-sequence" || input.outputFormat === "gif") return void 0;
+  if (input.outputFormat === "gif") return void 0;
   if (!Number.isFinite(input.durationSeconds) || input.durationSeconds <= 0) return void 0;
   const expectation = {
     expectedDurationSeconds: input.durationSeconds,
@@ -1573,12 +1573,12 @@ function assertDurationWithinTolerance(expectedSeconds, probedSeconds, tolerance
     `Render artifact is truncated: expected ${expectedSeconds.toFixed(3)}s, probed ${probedSeconds.toFixed(3)}s (deficit ${deficit.toFixed(3)}s exceeds tolerance ${toleranceSeconds.toFixed(3)}s). Artifact: ${stagingPath}`
   );
 }
-function assertFrameCountWithinTolerance(expectedFrames, probedFrames, stagingPath) {
+function assertFrameCountWithinTolerance(expectedFrames, probedFrames, stagingPath, toleranceFrames = 1) {
   if (probedFrames === void 0 || !Number.isFinite(probedFrames) || probedFrames <= 0) {
     return;
   }
   const shortfall = expectedFrames - probedFrames;
-  if (shortfall <= 1) return;
+  if (shortfall <= toleranceFrames) return;
   throw new Error(
     `Render artifact is truncated: expected ${expectedFrames} frames, probed ${probedFrames} frames (shortfall ${shortfall} frames). Artifact: ${stagingPath}`
   );
@@ -1615,8 +1615,8 @@ var ArtifactTransaction = class {
       if (expected) await this.assertArtifactDuration(expected);
       return;
     }
-    this.assertReadableNonEmptyDirectory();
-    if (expected) await this.assertDirectoryExpectation(expected);
+    const files = this.assertReadableNonEmptyDirectory();
+    if (expected) await this.assertDirectoryExpectation(expected, files);
   }
   assertReadableNonEmptyDirectory() {
     let files;
@@ -1631,13 +1631,14 @@ var ArtifactTransaction = class {
       throw new Error(`Render artifact directory is empty: ${this.stagingPath}`);
     }
     for (const file of files) assertReadableNonEmptyFile(file);
+    return files;
   }
   /**
    * The named-entry and duration gates a directory artifact opts into. A
-   * directory has no single probe target, so an expectation without
-   * `probeTarget` (png-sequence) keeps the historical behavior: structure only.
+   * directory with a probe target checks duration; one without a probe target
+   * checks the exported PNG frame count when the caller supplied it.
    */
-  async assertDirectoryExpectation(expected) {
+  async assertDirectoryExpectation(expected, files) {
     for (const required of expected.requiredFiles ?? []) {
       const path = join5(this.stagingPath, required);
       if (!existsSync5(path)) {
@@ -1645,8 +1646,25 @@ var ArtifactTransaction = class {
       }
       assertReadableNonEmptyFile(path);
     }
-    if (expected.probeTarget === void 0) return;
-    await this.assertArtifactDuration(expected, join5(this.stagingPath, expected.probeTarget));
+    if (expected.probeTarget !== void 0) {
+      await this.assertArtifactDuration(expected, join5(this.stagingPath, expected.probeTarget));
+      return;
+    }
+    if (expected.expectedFrames === void 0) return;
+    const frameCount = files.filter(
+      (file) => dirname4(file) === this.stagingPath && /^frame_\d+\.png$/.test(basename3(file))
+    ).length;
+    if (frameCount === 0) {
+      throw new Error(
+        `Render artifact is truncated: expected ${expected.expectedFrames} frames, probed 0 frames. Artifact: ${this.stagingPath}`
+      );
+    }
+    assertFrameCountWithinTolerance(
+      expected.expectedFrames,
+      frameCount,
+      this.stagingPath,
+      Math.max(1, Math.ceil(expected.expectedFrames * 2e-3))
+    );
   }
   async assertArtifactDuration(expected, probePath = this.stagingPath) {
     const expectedSeconds = expected.expectedDurationSeconds;
@@ -7145,7 +7163,7 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
       );
       if (analysis.isProblematic) {
         defaultLogger.warn(
-          `[Compiler] WARNING: Video "${video.id}" has sparse keyframes (max interval: ${analysis.maxIntervalSeconds}s). This causes seek failures and frame freezing. Re-encode with: ${reencode}`
+          `[Compiler] WARNING: Video "${video.id}" has sparse keyframes (max interval: ${analysis.maxIntervalSeconds}s). Long GOPs can make preview seeking slower; rendering is unaffected. If preview seeking is slow, re-encode with: ${reencode}`
         );
       }
       if (metadata.isVFR) {
@@ -9196,6 +9214,7 @@ async function mixAudioForDelivery(input, duration, pcmSourcePath) {
     audios,
     masterFxChain,
     urlByAbsentLocalPath,
+    audioSidecarUrlByLocalPath,
     abortSignal,
     assertNotAborted,
     log
@@ -9219,6 +9238,7 @@ async function mixAudioForDelivery(input, duration, pcmSourcePath) {
           audioGain,
           masterFxChain,
           urlByAbsentLocalPath,
+          audioSidecarUrlByLocalPath,
           keepEncoderInputAt: pcmSourcePath
         },
         compiledDir
@@ -15901,6 +15921,11 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
   const localPathByUrl = new Map(
     remoteFiles.map(([rel, file]) => [file.url, remoteLocalPath(rel)])
   );
+  const audioSidecarUrlByLocalPath = new Map(
+    remoteFiles.flatMap(
+      ([rel, file]) => file.audioSidecarUrl ? [[remoteLocalPath(rel), file.audioSidecarUrl]] : []
+    )
+  );
   stageStarted = Date.now();
   const compileResult = await runCompileStage({
     urlByAbsentLocalPath,
@@ -15985,6 +16010,7 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
     finalCompiledDir,
     remoteFiles,
     urlByAbsentLocalPath,
+    audioSidecarUrlByLocalPath,
     localPathByUrl,
     compileResult,
     compiled,
@@ -16002,6 +16028,7 @@ function mixPlanAudio(c, compiledDir) {
     workDir: c.workDir,
     compiledDir,
     urlByAbsentLocalPath: c.urlByAbsentLocalPath,
+    audioSidecarUrlByLocalPath: c.audioSidecarUrlByLocalPath,
     totalFrames: c.totalFrames,
     fps: c.job.config.fps,
     ffmpegProcessTimeout: c.cfg.ffmpegProcessTimeout,
@@ -19556,6 +19583,10 @@ async function assembleV2(planV2Dir, chunkPaths, outputPath, options) {
 
 // src/services/distributed/projectHash.ts
 var READ_CHUNK_BYTES = 256 * 1024;
+
+// src/services/distributed/audioSidecar.ts
+import { extractAudioMetadata as extractAudioMetadata4, runFfmpeg as runFfmpeg8 } from "@hyperframes/engine";
+var AUDIO_SIDECAR_MIN_BYTES = 32 * 1024 * 1024;
 export {
   CURRENT_PLAN_PROTOCOL,
   DEFAULT_CONFIG2 as DEFAULT_CONFIG,

package/dist/public-server.js

@@ -1527,7 +1527,7 @@ async function defaultArtifactDurationProbe(path) {
   };
 }
 function buildArtifactExpectation(input) {
-  if (input.outputFormat === "png-sequence" || input.outputFormat === "gif") return void 0;
+  if (input.outputFormat === "gif") return void 0;
   if (!Number.isFinite(input.durationSeconds) || input.durationSeconds <= 0) return void 0;
   const expectation = {
     expectedDurationSeconds: input.durationSeconds,
@@ -1592,12 +1592,12 @@ function assertDurationWithinTolerance(expectedSeconds, probedSeconds, tolerance
     `Render artifact is truncated: expected ${expectedSeconds.toFixed(3)}s, probed ${probedSeconds.toFixed(3)}s (deficit ${deficit.toFixed(3)}s exceeds tolerance ${toleranceSeconds.toFixed(3)}s). Artifact: ${stagingPath}`
   );
 }
-function assertFrameCountWithinTolerance(expectedFrames, probedFrames, stagingPath) {
+function assertFrameCountWithinTolerance(expectedFrames, probedFrames, stagingPath, toleranceFrames = 1) {
   if (probedFrames === void 0 || !Number.isFinite(probedFrames) || probedFrames <= 0) {
     return;
   }
   const shortfall = expectedFrames - probedFrames;
-  if (shortfall <= 1) return;
+  if (shortfall <= toleranceFrames) return;
   throw new Error(
     `Render artifact is truncated: expected ${expectedFrames} frames, probed ${probedFrames} frames (shortfall ${shortfall} frames). Artifact: ${stagingPath}`
   );
@@ -1634,8 +1634,8 @@ var ArtifactTransaction = class {
       if (expected) await this.assertArtifactDuration(expected);
       return;
     }
-    this.assertReadableNonEmptyDirectory();
-    if (expected) await this.assertDirectoryExpectation(expected);
+    const files = this.assertReadableNonEmptyDirectory();
+    if (expected) await this.assertDirectoryExpectation(expected, files);
   }
   assertReadableNonEmptyDirectory() {
     let files;
@@ -1650,13 +1650,14 @@ var ArtifactTransaction = class {
       throw new Error(`Render artifact directory is empty: ${this.stagingPath}`);
     }
     for (const file of files) assertReadableNonEmptyFile(file);
+    return files;
   }
   /**
    * The named-entry and duration gates a directory artifact opts into. A
-   * directory has no single probe target, so an expectation without
-   * `probeTarget` (png-sequence) keeps the historical behavior: structure only.
+   * directory with a probe target checks duration; one without a probe target
+   * checks the exported PNG frame count when the caller supplied it.
    */
-  async assertDirectoryExpectation(expected) {
+  async assertDirectoryExpectation(expected, files) {
     for (const required of expected.requiredFiles ?? []) {
       const path = join5(this.stagingPath, required);
       if (!existsSync5(path)) {
@@ -1664,8 +1665,25 @@ var ArtifactTransaction = class {
       }
       assertReadableNonEmptyFile(path);
     }
-    if (expected.probeTarget === void 0) return;
-    await this.assertArtifactDuration(expected, join5(this.stagingPath, expected.probeTarget));
+    if (expected.probeTarget !== void 0) {
+      await this.assertArtifactDuration(expected, join5(this.stagingPath, expected.probeTarget));
+      return;
+    }
+    if (expected.expectedFrames === void 0) return;
+    const frameCount = files.filter(
+      (file) => dirname4(file) === this.stagingPath && /^frame_\d+\.png$/.test(basename3(file))
+    ).length;
+    if (frameCount === 0) {
+      throw new Error(
+        `Render artifact is truncated: expected ${expected.expectedFrames} frames, probed 0 frames. Artifact: ${this.stagingPath}`
+      );
+    }
+    assertFrameCountWithinTolerance(
+      expected.expectedFrames,
+      frameCount,
+      this.stagingPath,
+      Math.max(1, Math.ceil(expected.expectedFrames * 2e-3))
+    );
   }
   async assertArtifactDuration(expected, probePath = this.stagingPath) {
     const expectedSeconds = expected.expectedDurationSeconds;
@@ -7164,7 +7182,7 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
       );
       if (analysis.isProblematic) {
         defaultLogger.warn(
-          `[Compiler] WARNING: Video "${video.id}" has sparse keyframes (max interval: ${analysis.maxIntervalSeconds}s). This causes seek failures and frame freezing. Re-encode with: ${reencode}`
+          `[Compiler] WARNING: Video "${video.id}" has sparse keyframes (max interval: ${analysis.maxIntervalSeconds}s). Long GOPs can make preview seeking slower; rendering is unaffected. If preview seeking is slow, re-encode with: ${reencode}`
         );
       }
       if (metadata.isVFR) {
@@ -9179,6 +9197,7 @@ async function mixAudioForDelivery(input, duration, pcmSourcePath) {
     audios,
     masterFxChain,
     urlByAbsentLocalPath,
+    audioSidecarUrlByLocalPath,
     abortSignal,
     assertNotAborted,
     log
@@ -9202,6 +9221,7 @@ async function mixAudioForDelivery(input, duration, pcmSourcePath) {
           audioGain,
           masterFxChain,
           urlByAbsentLocalPath,
+          audioSidecarUrlByLocalPath,
           keepEncoderInputAt: pcmSourcePath
         },
         compiledDir

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

@@ -0,0 +1,10 @@
+/**
+ * A video's audio copied out of its container, nothing re-encoded, stored beside it. Reading audio from the
+ * cloud file moves the whole interleaved file; the sidecar is a few MB.
+ */
+/** Smaller files are cheap to read whole. */
+export declare const AUDIO_SIDECAR_MIN_BYTES: number;
+export declare function wantsAudioSidecar(path: string, sizeBytes: number): boolean;
+/** `unavailable`: no ffmpeg on this machine. `none`: no audio, or audio the sidecar would not read back the same. */
+export type AudioSidecarOutcome = "built" | "none" | "unavailable";
+export declare function buildAudioSidecar(inputPath: string, outputPath: string, signal?: AbortSignal): Promise<AudioSidecarOutcome>;

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

@@ -217,6 +217,8 @@ export interface BuildLocalExecutionPlanOptions {
 }
 export interface RemoteProjectFile {
     readonly url: string;
+    /** A file of only this video's audio, when one was stored: the audio mix reads it, not the video. */
+    readonly audioSidecarUrl?: string;
     readonly sha256: string;
     readonly sizeBytes: number;
 }

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

@@ -37,7 +37,7 @@ export interface ArtifactDurationProbeResult {
  */
 export type ArtifactDurationProbe = (path: string) => Promise<ArtifactDurationProbeResult>;
 /**
- * Caller-supplied expectation for file-artifact validation. The transaction
+ * Caller-supplied expectation for artifact validation. The transaction
  * still does the readable-non-empty check; this layer adds a duration /
  * frame-count comparison against the values the pipeline already held.
  *
@@ -48,15 +48,15 @@ export type ArtifactDurationProbe = (path: string) => Promise<ArtifactDurationPr
  *
  * `toleranceSeconds` defaults to a single frame at `fps` (or 20 ms when fps
  * is unknown) so that a normal container-level last-frame rounding does not
- * trip the gate. Multi-frame drops (e.g. the 326-frame / 11s truncation in
- * #3395) still fail.
+ * trip the gate. Multi-frame drops beyond that tolerance still fail.
  *
  * `probeTarget` / `requiredFiles` exist for directory artifacts. A `"file"`
  * artifact is its own probe target; a directory has no single one, so an HLS
  * output names its video playlist (`probeTarget: "video.m3u8"`) and the files
  * that must be present (`requiredFiles: ["master.m3u8"]`). Without
- * `probeTarget` the directory branch keeps its historical behavior — readable
- * non-empty files only, no duration gate (png-sequence).
+ * `probeTarget`, an `expectedFrames` value instead checks the top-level PNG
+ * frame files. Directory artifacts without either keep their historical
+ * readable-non-empty check.
  */
 export interface ArtifactValidationExpectation {
     expectedDurationSeconds: number;
@@ -75,8 +75,10 @@ export interface ArtifactValidationExpectation {
  * The per-format expectation the render pipeline hands `validate()`, or
  * `undefined` when the format has nothing probeable.
  *
- * - `png-sequence` / `gif`: no expectation. A PNG directory has no container
- *   duration, and the GIF encoder writes `outputPath` itself without a
+ * - `png-sequence`: count exported PNG frames without a duration probe.
+ *   `expectedDurationSeconds` is carried by the shared expectation but is
+ *   unused for this directory format.
+ * - `gif`: no expectation. The GIF encoder writes `outputPath` itself without a
  *   frame-accurate duration the pipeline could compare against.
  * - `hls`: the directory's `video.m3u8` is the probe target and `master.m3u8`
  *   must exist. `expectedFrames` is passed through but is inert — ffprobe
@@ -104,8 +106,9 @@ export declare function buildArtifactExpectation(input: {
  * transaction additionally probes the staged artifact's container duration
  * (and decoded frame count when available) and rejects any artifact that is
  * significantly shorter than what the pipeline asked for. A directory artifact
- * is probed only when `expected.probeTarget` names a file inside it. The
- * readable-non-empty check is unchanged; this is a second gate on top.
+ * is probed only when `expected.probeTarget` names a file inside it.
+ * Without a directory probe target, the expectation instead checks exported
+ * PNG frame files. The readable-non-empty check is a separate gate.
  */
 export declare class ArtifactTransaction {
     private readonly kind;
@@ -121,8 +124,8 @@ export declare class ArtifactTransaction {
     private assertReadableNonEmptyDirectory;
     /**
      * The named-entry and duration gates a directory artifact opts into. A
-     * directory has no single probe target, so an expectation without
-     * `probeTarget` (png-sequence) keeps the historical behavior: structure only.
+     * directory with a probe target checks duration; one without a probe target
+     * checks the exported PNG frame count when the caller supplied it.
      */
     private assertDirectoryExpectation;
     private assertArtifactDuration;

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

@@ -36,6 +36,7 @@ export interface AudioStageInput {
     audios: CompositionMetadata["audios"];
     masterFxChain?: string;
     urlByAbsentLocalPath?: ReadonlyMap<string, string>;
+    audioSidecarUrlByLocalPath?: ReadonlyMap<string, string>;
     abortSignal: AbortSignal | undefined;
     assertNotAborted: () => void;
     /** Where a per-track failure's detail goes. Optional so tests need not pass one. */

package/package.json

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