@hyperframes/engine 0.8.158 → 0.8.159

package/dist/index.d.ts

@@ -50,8 +50,9 @@ export { directorySizeBytes, gcExtractionCache } from "./services/extractionCach
 export { resolveReferencedStart, resolveReferencedDuration, type RefResolverEl, type RefResolverDoc, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
 export { MIXED_AUDIO_FILENAME, parseAudioElements, parseMasterFxChain, processCompositionAudio, } from "./services/audioMixer.js";
+export { audioFailureDiagnostics } from "./services/audioFailureDiagnostic.js";
 export { cloneCaptureWarning, cloneCaptureWarnings } from "./services/captureWarning.js";
-export type { AudioElement, AudioFailureReason, AudioFailureStage, AudioProcessingFailure, AudioTrack, AudioVolumeKeyframe, MixResult, } from "./services/audioMixer.types.js";
+export type { AudioElement, AudioFailureReason, AudioFailureStage, AudioProcessingFailure, AudioFailureDiagnostic, AudioSubprocessEvidence, AudioTrack, AudioVolumeKeyframe, MixResult, } from "./services/audioMixer.types.js";
 export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndicesForTask, verifyDiskDrawElementSamples, distributeFrames, distributeFramesInterleaved, executeParallelCapture, mergeWorkerFrames, getSystemResources, shouldDisableBrowserPoolForParallelWorker, type WorkerTask, type WorkerResult, type WorkerSizing, type WorkerSizingBound, type ParallelProgress, } from "./services/parallelCoordinator.js";
 export { createFileServer, type FileServerOptions, type FileServerHandle, } from "./services/fileServer.js";
 export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";

package/dist/index.js

@@ -54,6 +54,7 @@ export { directorySizeBytes, gcExtractionCache } from "./services/extractionCach
 export { resolveReferencedStart, resolveReferencedDuration, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
 export { MIXED_AUDIO_FILENAME, parseAudioElements, parseMasterFxChain, processCompositionAudio, } from "./services/audioMixer.js";
+export { audioFailureDiagnostics } from "./services/audioFailureDiagnostic.js";
 export { cloneCaptureWarning, cloneCaptureWarnings } from "./services/captureWarning.js";
 // ── Parallel rendering ─────────────────────────────────────────────────────────
 export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndicesForTask, verifyDiskDrawElementSamples, distributeFrames, distributeFramesInterleaved, executeParallelCapture, mergeWorkerFrames, getSystemResources, shouldDisableBrowserPoolForParallelWorker, } from "./services/parallelCoordinator.js";

package/dist/services/audioFailureDiagnostic.d.ts

@@ -0,0 +1,4 @@
+import type { AudioFailureDiagnostic, AudioSubprocessEvidence } from "./audioMixer.types.js";
+export declare function audioSubprocessEvidence(value: unknown): AudioSubprocessEvidence;
+/** Re-project at the wire boundary: neither typed callers nor warning details are a privacy boundary. */
+export declare function audioFailureDiagnostics(values: readonly unknown[]): AudioFailureDiagnostic[];

package/dist/services/audioFailureDiagnostic.js

@@ -0,0 +1,110 @@
+const STAGES = new Set([
+    "source",
+    "download",
+    "probe",
+    "extract",
+    "prepare",
+    "mix",
+    "silence",
+    "cancelled",
+    "internal",
+]);
+const REASONS = new Set([
+    "source_not_found",
+    "download_failed",
+    "probe_failed",
+    "invalid_media",
+    "ffmpeg_unsupported",
+    "ffmpeg_timeout",
+    "ffmpeg_unavailable",
+    "external_interruption",
+    "ffmpeg_failed",
+    "cancelled",
+    "internal",
+]);
+const TERMINATIONS = new Set(["exit", "abort", "deadline", "inactivity", "spawn_error"]);
+const SIGNALS = new Set([
+    "SIGABRT",
+    "SIGBUS",
+    "SIGFPE",
+    "SIGHUP",
+    "SIGILL",
+    "SIGINT",
+    "SIGKILL",
+    "SIGPIPE",
+    "SIGQUIT",
+    "SIGSEGV",
+    "SIGTERM",
+    "SIGTRAP",
+    "SIGXCPU",
+    "SIGXFSZ",
+]);
+const CODES = new Set([
+    "EACCES",
+    "EAGAIN",
+    "EBUSY",
+    "EIO",
+    "EISDIR",
+    "EMFILE",
+    "ENAMETOOLONG",
+    "ENFILE",
+    "ENOENT",
+    "ENOEXEC",
+    "ENOMEM",
+    "ENOSPC",
+    "ENOTDIR",
+    "EPERM",
+    "ETIMEDOUT",
+]);
+function isStage(value) {
+    return typeof value === "string" && STAGES.has(value);
+}
+function isReason(value) {
+    return typeof value === "string" && REASONS.has(value);
+}
+function isTermination(value) {
+    return typeof value === "string" && TERMINATIONS.has(value);
+}
+function record(value) {
+    return value !== null && typeof value === "object";
+}
+export function audioSubprocessEvidence(value) {
+    if (!record(value))
+        return {};
+    const evidence = {};
+    if (typeof value.exitCode === "number" &&
+        Number.isInteger(value.exitCode) &&
+        value.exitCode >= -2147483648 &&
+        value.exitCode <= 4294967295)
+        evidence.exitCode = value.exitCode;
+    if (typeof value.signal === "string" && SIGNALS.has(value.signal))
+        evidence.signal = value.signal;
+    if (isTermination(value.terminationReason))
+        evidence.terminationReason = value.terminationReason;
+    const error = record(value.error) ? value.error : value;
+    if (typeof error.code === "string" && CODES.has(error.code))
+        evidence.code = error.code;
+    return evidence;
+}
+/** Re-project at the wire boundary: neither typed callers nor warning details are a privacy boundary. */
+export function audioFailureDiagnostics(values) {
+    const result = [];
+    for (const value of values.slice(0, 16)) {
+        if (!record(value) ||
+            !isStage(value.stage) ||
+            !isReason(value.reason) ||
+            (value.owner !== "user" && value.owner !== "system") ||
+            typeof value.retryable !== "boolean")
+            continue;
+        result.push({
+            stage: value.stage,
+            reason: value.reason,
+            owner: value.owner,
+            retryable: value.retryable,
+            ...(record(value.subprocess)
+                ? { subprocess: audioSubprocessEvidence(value.subprocess) }
+                : {}),
+        });
+    }
+    return result;
+}

package/dist/services/audioMixer.js

@@ -10,6 +10,7 @@ import { clampFadesToDuration, readElementFades } from "@hyperframes/core/audio-
 import { downloadToTemp, isHttpUrl, UrlDownloadError, writeUrlDownloadTelemetry, } from "../utils/urlDownloader.js";
 import { DEFAULT_CONFIG } from "../config.js";
 import { formatFfmpegError, runFfmpeg } from "../utils/runFfmpeg.js";
+import { audioSubprocessEvidence } from "./audioFailureDiagnostic.js";
 import { unwrapTemplate } from "../utils/htmlTemplate.js";
 import { resolveMediaElementSrc, resolveProjectRelativeSrc } from "./videoFrameExtractor.js";
 import { resolveReferencedStart } from "./referenceResolver.js";
@@ -347,6 +348,7 @@ function ffmpegFailure(stage, result, elementId) {
         owner,
         retryable,
         elementId,
+        subprocess: audioSubprocessEvidence(result),
         detail: boundedDetail(result.error?.message
             ? `${formatFfmpegError(result.exitCode, stderr)}: ${result.error.message}`
             : formatFfmpegError(result.exitCode, stderr)),
@@ -843,10 +845,10 @@ async function mixGroupMembers(memberTracks, outputPath, totalDuration, signal,
             degradedAutomation = true;
         }
     }
-    if (signal?.aborted)
-        return { success: false, error: "Group sub-mix cancelled" };
-    if (!result.success)
-        return { success: false, error: formatFfmpegError(result.exitCode, result.stderr) };
+    if (signal?.aborted || !result.success) {
+        const failure = ffmpegFailure("mix", result);
+        return { success: false, error: failure.detail, failure };
+    }
     return { success: true, degradedAutomation };
 }
 /**
@@ -1215,10 +1217,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             const subMix = await mixGroupMembers(memberTracks, groupWavPath, totalDuration, effectiveSignal, config);
             if (!subMix.success) {
                 failures.push({
-                    stage: "mix",
-                    reason: "ffmpeg_failed",
-                    owner: "system",
-                    retryable: false,
+                    ...subMix.failure,
                     elementId: groupId,
                     detail: boundedDetail(`Group sub-mix failed for group ${groupId}: ${subMix.error ?? "unknown"}`),
                 });

package/dist/services/audioMixer.types.d.ts

@@ -56,11 +56,19 @@ export interface AudioTrack {
 }
 export type AudioFailureStage = "source" | "download" | "probe" | "extract" | "prepare" | "mix" | "silence" | "cancelled" | "internal";
 export type AudioFailureReason = "source_not_found" | "download_failed" | "probe_failed" | "invalid_media" | "ffmpeg_unsupported" | "ffmpeg_timeout" | "ffmpeg_unavailable" | "external_interruption" | "ffmpeg_failed" | "cancelled" | "internal";
+export interface AudioSubprocessEvidence {
+    exitCode?: number;
+    signal?: string;
+    terminationReason?: "exit" | "abort" | "deadline" | "inactivity" | "spawn_error";
+    code?: string;
+}
+export type AudioFailureDiagnostic = Pick<AudioProcessingFailure, "stage" | "reason" | "owner" | "retryable" | "subprocess">;
 export interface AudioProcessingFailure {
     stage: AudioFailureStage;
     reason: AudioFailureReason;
     owner: "user" | "system";
     retryable: boolean;
+    subprocess?: AudioSubprocessEvidence;
     elementId?: string;
     /** Bounded diagnostic text; never includes the authored source URL/path. */
     detail: string;

package/dist/services/captureWarning.js

@@ -5,6 +5,10 @@ export function cloneCaptureWarning(warning) {
         details: warning.details
             ? {
                 ...warning.details,
+                audioFailures: warning.details.audioFailures?.map((failure) => ({
+                    ...failure,
+                    ...(failure.subprocess ? { subprocess: { ...failure.subprocess } } : {}),
+                })),
                 sources: warning.details.sources ? [...warning.details.sources] : undefined,
                 failureReasons: warning.details.failureReasons
                     ? [...warning.details.failureReasons]

package/dist/types.d.ts

@@ -4,6 +4,7 @@
  * The engine's page contract. Any web page that wants to be rendered
  * as video must expose `window.__hf` implementing the HfProtocol interface.
  */
+import type { AudioFailureDiagnostic } from "./services/audioMixer.types.js";
 import type { Fps } from "@hyperframes/core";
 import type { ChromeMemoryStats } from "./services/chromeMemorySampler.js";
 import type { MotionBlurOptions } from "./services/motionBlur.js";
@@ -30,6 +31,7 @@ export interface CaptureWarning {
         sources?: string[];
         pendingCompositionIds?: string[];
         timeoutMs?: number;
+        audioFailures?: AudioFailureDiagnostic[];
         failureReasons?: string[];
         failureStages?: string[];
         failureOwner?: "user" | "system";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.158",
+  "version": "0.8.159",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -50,8 +50,8 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^25.8.0",
     "puppeteer-core": "^25.8.0",
-    "@hyperframes/parsers": "^0.8.158",
-    "@hyperframes/core": "^0.8.158"
+    "@hyperframes/core": "^0.8.159",
+    "@hyperframes/parsers": "^0.8.159"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",