@hyperframes/engine 0.8.180 → 0.8.181

package/dist/config.d.ts

@@ -165,7 +165,7 @@ export interface EngineConfig {
     streamingEncodeDurationCapEnabled: boolean;
     /** Timeout for FFmpeg frame encoding (ms). Default: 600_000 */
     ffmpegEncodeTimeout: number;
-    /** Timeout for FFmpeg mux/faststart processes (ms). Default: 300_000 */
+    /** FFmpeg mux/faststart timeout (ms); extraction waits this long for each new frame. Default: 300_000 */
     ffmpegProcessTimeout: number;
     /**
      * Inactivity timeout for FFmpeg streaming encode (ms). The timer resets on

package/dist/index.d.ts

@@ -64,6 +64,7 @@ export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimes
 export { NOT_MEDIA_PAYLOAD, NotMediaPayloadError, assertMediaPayload, fingerprintElementId, isNotMediaPayload, } from "./utils/notMediaPayload.js";
 export { assertPublicHttpsUrl, isBlockedNetworkHost, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, type SafeDownloadUrlIdentity, type UrlDownloadOptions, type UrlDownloadTelemetry, type PublicHttpsTextOptions, } from "./utils/urlDownloader.js";
 export { runFfmpeg, formatFfmpegError, describeFfmpegFailure, isExternalFfmpegInterruption, type RunFfmpegOptions, type RunFfmpegResult, } from "./utils/runFfmpeg.js";
+export { aacSegmentCount } from "./services/aacEncode.js";
 export { ManagedChildProcess, type ManagedChildProcessOptions, type ManagedChildProcessOutcome, type ManagedProcessTerminationReason, } from "./utils/managedChildProcess.js";
 export { assertConfiguredFfmpegBinariesExist, getFfmpegBinary, getFfprobeBinary, FFMPEG_PATH_ENV, FFPROBE_PATH_ENV, } from "./utils/ffmpegBinaries.js";
 export { trackChildProcess, killTrackedProcesses } from "./utils/processTracker.js";

package/dist/index.js

@@ -69,6 +69,7 @@ export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimes
 export { NOT_MEDIA_PAYLOAD, NotMediaPayloadError, assertMediaPayload, fingerprintElementId, isNotMediaPayload, } from "./utils/notMediaPayload.js";
 export { assertPublicHttpsUrl, isBlockedNetworkHost, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, } from "./utils/urlDownloader.js";
 export { runFfmpeg, formatFfmpegError, describeFfmpegFailure, isExternalFfmpegInterruption, } from "./utils/runFfmpeg.js";
+export { aacSegmentCount } from "./services/aacEncode.js";
 export { ManagedChildProcess, } from "./utils/managedChildProcess.js";
 export { assertConfiguredFfmpegBinariesExist, getFfmpegBinary, getFfprobeBinary, FFMPEG_PATH_ENV, FFPROBE_PATH_ENV, } from "./utils/ffmpegBinaries.js";
 export { trackChildProcess, killTrackedProcesses } from "./utils/processTracker.js";

package/dist/services/videoFrameExtractor.js

@@ -16,7 +16,7 @@ import { resolveProjectRelativeSrc } from "@hyperframes/parsers/asset-resolution
 import { MEDIA_RENDER_ID_ATTR, isAudibleVideoElement, fpsToFfmpegArg, fpsToNumber, MEDIA_DURATION_CLAMP_EPSILON_SECONDS, normalizeRateSpec, readElementRateSpec, shiftRateLane, sourceTimeAt, timeAtSourceTime, exportClipWindow, hasClipStarted, isInClipWindow, parseStrictFiniteTimingNumber, readMediaStart, toFps, firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, } from "@hyperframes/core";
 import { resolveReferencedStart } from "./referenceResolver.js";
 import { isKnownInactiveTimelineWindow } from "./mediaTimelineWindow.js";
-import { extractFinalVideoFrameTimestamp, extractMediaMetadata, } from "../utils/ffprobe.js";
+import { extractFinalVideoFrameTimestamp, extractMediaMetadata, mediaFileIdentity, readMetadataCache, writeMetadataCache, } from "../utils/ffprobe.js";
 import { inputAlphaOpaqueWarning, probeInputAlphaPlane } from "../utils/alphaPlaneProbe.js";
 import { redactUrlQueriesInError, urlInputArgs } from "../utils/urlInput.js";
 import { analyzeCompositionHdr, isHdrColorSpace as isHdrColorSpaceUtil, } from "../utils/hdr.js";
@@ -417,12 +417,23 @@ export function parseImageElements(html) {
     }
     return images;
 }
-/** The first shown frame's colour tags; see {@link firstFrameColourArgs}. */
-async function readFirstFrameColour(videoPath, signal) {
-    const result = await runFfmpeg([...urlInputArgs(videoPath), ...firstFrameColourArgs(videoPath)], {
-        signal,
+const firstFrameColourCache = new Map();
+/** The first shown frame's colour tags (see {@link firstFrameColourArgs}), probed once per source file. */
+function readFirstFrameColour(videoPath) {
+    const identity = mediaFileIdentity(videoPath);
+    const cached = readMetadataCache(firstFrameColourCache, videoPath, identity);
+    if (cached)
+        return cached;
+    // In an extraction slot, so it never adds a decoder; unsignalled, so one cancel cannot cut it short for others.
+    const probe = inExtractionSlot(() => runFfmpeg([...urlInputArgs(videoPath), ...firstFrameColourArgs(videoPath)])).then((result) => {
+        // A failed probe answers this cut only; the next one probes again.
+        if (!result.success && firstFrameColourCache.get(videoPath)?.promise === probe) {
+            firstFrameColourCache.delete(videoPath);
+        }
+        return parseFirstFrameColour(result.stderr);
     });
-    return parseFirstFrameColour(result.stderr);
+    writeMetadataCache(firstFrameColourCache, videoPath, identity, probe);
+    return probe;
 }
 /** Chrome plays untagged VP9 and AV1 as BT.601, H.264 and VP8 as BT.709 from 720 coded lines (assumed for the rest). */
 const CHROME_BT601_UNTAGGED_CODECS = new Set(["vp9", "av1"]);
@@ -434,10 +445,9 @@ function chromeGuessForUntaggedMatrix(metadata) {
     return [`setparams=colorspace=${hd ? "bt709" : "smpte170m"}`];
 }
 /**
- * Longest stretch of output one ffmpeg process extracts. `ffmpegProcessTimeout` bounds a
- * single process, so one process over a long clip timed out however much time the render
- * had left. Longer ranges split into segments that run side by side. Segments sample the
- * same absolute times as a single pass, so their frames are byte-identical to it.
+ * Longest stretch of output one ffmpeg process extracts; longer ranges split into segments
+ * that run side by side. Segments sample the same absolute times as a single pass, so their
+ * frames are byte-identical to it.
  */
 const EXTRACTION_SEGMENT_SECONDS = 120;
 /** Frame times since file start are `PTS*TB + seek`; snapping them to `lead + k/FR` gives every process one grid. */
@@ -624,7 +634,7 @@ outputDirOverride) {
         vfFilters.push(SDR_TO_HDR_COLORSPACE_FILTER);
     }
     if (toneMappedToSdr) {
-        const frameColour = await readFirstFrameColour(videoPath, signal);
+        const frameColour = await readFirstFrameColour(videoPath);
         vfFilters.push(hdrToSdrToneMapFilter(metadata.colorSpace ?? {}, frameColour));
     }
     if (toneMappedToSdr || (!isHdr && !options.sdrToHdrTransfer)) {
@@ -637,7 +647,8 @@ outputDirOverride) {
     if (format === "png")
         encodeArgs.push("-compression_level", "1");
     encodeArgs.push("-y", outputPattern);
-    const runOptions = { signal, timeout: ffmpegProcessTimeout };
+    // A long 4K run can take far longer than the timeout and still be healthy; only a stall is a hang.
+    const runOptions = { signal, stallTimeout: ffmpegProcessTimeout };
     const filterArgsFor = (seek) => {
         const filters = [...vfFilters];
         filters.splice(samplingAt, 0, ...samplingFilters(seek));
@@ -677,8 +688,8 @@ outputDirOverride) {
         const hdrPrefix = options.sdrToHdrTransfer
             ? `SDR→HDR conversion failed (colorspace filter in extract pass, target ${options.sdrToHdrTransfer}): `
             : "";
-        const timedOut = processResult.terminationReason === "deadline";
-        const timeoutSuffix = timedOut ? ` (timed out after ${ffmpegProcessTimeout} ms)` : "";
+        const timedOut = processResult.terminationReason === "inactivity";
+        const timeoutSuffix = timedOut ? ` (no new frame for ${ffmpegProcessTimeout} ms)` : "";
         const diagnostic = `${hdrPrefix}FFmpeg exited with code ${processResult.exitCode}${timeoutSuffix}: ` +
             processResult.stderr.slice(-500);
         if (timedOut) {
@@ -1562,7 +1573,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
             : join(options.outputDir, group.groupId);
         try {
             rmSync(tempDir, { recursive: true, force: true });
-            // A long union can hit the fixed FFmpeg deadline even when each shorter
+            // A long union can fail even when each shorter
             // member range succeeds. Do not retry the optimization itself; preserve
             // the established grouped→direct fallback and apply bounded retries only
             // to the individual source ranges below.

package/dist/utils/ffprobe.d.ts

@@ -1,3 +1,7 @@
+export interface MediaProbeCacheEntry<T = FFProbeOutput> {
+    identity: string | null;
+    promise: Promise<T>;
+}
 export interface VideoColorSpace {
     /** Color transfer characteristics, e.g. "bt709", "smpte2084", "arib-std-b67" */
     colorTransfer: string;
@@ -48,6 +52,42 @@ export interface AudioMetadata {
     /** Seconds after the file's media time 0 at which its last audio or video stream starts. */
     latestStreamLeadSeconds?: number;
 }
+interface FFProbeStream {
+    codec_type: string;
+    codec_name?: string;
+    /** e.g. "LC", "HE-AAC", "HE-AACv2" — where the SBR marker lives, since
+     *  codec_name is plain "aac" for all of them. */
+    profile?: string;
+    width?: number;
+    height?: number;
+    duration?: string;
+    start_time?: string;
+    nb_frames?: string;
+    nb_read_packets?: string;
+    pix_fmt?: string;
+    r_frame_rate?: string;
+    avg_frame_rate?: string;
+    sample_rate?: string;
+    channels?: number;
+    color_range?: string;
+    color_transfer?: string;
+    color_primaries?: string;
+    color_space?: string;
+    tags?: Record<string, string>;
+    disposition?: {
+        attached_pic?: number;
+    };
+}
+interface FFProbeFormat {
+    duration?: string;
+    start_time?: string;
+    bit_rate?: string;
+    format_name?: string;
+}
+interface FFProbeOutput {
+    streams: FFProbeStream[];
+    format: FFProbeFormat;
+}
 interface StillImageMetadata {
     width: number;
     height: number;
@@ -58,6 +98,9 @@ export interface MediaProbeProfile {
     hasAudioStream: boolean;
     visualKind: "none" | "still" | "moving";
 }
+export declare function mediaFileIdentity(filePath: string): string | null;
+export declare function readMetadataCache<T>(cache: Map<string, MediaProbeCacheEntry<T>>, key: string, identity: string | null): Promise<T> | undefined;
+export declare function writeMetadataCache<T>(cache: Map<string, MediaProbeCacheEntry<T>>, key: string, identity: string | null, promise: Promise<T>): void;
 /**
  * Probe stream capabilities without assuming the caller's element type.
  * File extensions and HTTP MIME are deliberately ignored: extensionless

package/dist/utils/ffprobe.js

@@ -209,7 +209,7 @@ function isPngImageProbe(output) {
     return (formatNames.includes("png_pipe") ||
         output.streams.some((stream) => stream.codec_type === "video" && stream.codec_name?.toLowerCase() === "png"));
 }
-function mediaFileIdentity(filePath) {
+export function mediaFileIdentity(filePath) {
     try {
         const stat = statSync(filePath, { bigint: true });
         return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(":");
@@ -218,11 +218,11 @@ function mediaFileIdentity(filePath) {
         return null;
     }
 }
-function readMetadataCache(cache, key, identity) {
+export function readMetadataCache(cache, key, identity) {
     const cached = cache.get(key);
     return cached?.identity === identity ? cached.promise : undefined;
 }
-function writeMetadataCache(cache, key, identity, promise) {
+export function writeMetadataCache(cache, key, identity, promise) {
     const entry = { identity, promise };
     cache.set(key, entry);
     void promise.then(() => {

package/dist/utils/runFfmpeg.d.ts

@@ -8,6 +8,8 @@ import { type ManagedProcessTerminationReason } from "./managedChildProcess.js";
 export interface RunFfmpegOptions {
     signal?: AbortSignal;
     timeout?: number;
+    /** Replaces `timeout`: stop only once this long passes without a new output frame. */
+    stallTimeout?: number;
     onStderr?: (line: string) => void;
 }
 export interface RunFfmpegResult {

package/dist/utils/runFfmpeg.js

@@ -147,11 +147,25 @@ const ABORTED_BEFORE_START = {
 export async function runFfmpeg(args, opts) {
     if (opts?.signal?.aborted)
         return { ...ABORTED_BEFORE_START };
-    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const stallTimeout = opts?.stallTimeout;
+    let framesWritten = 0;
+    const readStats = ffmpegStatsReader(({ frames }) => {
+        if (frames === undefined || frames <= framesWritten)
+            return;
+        framesWritten = frames;
+        managed.markActivity();
+    });
     const managed = new ManagedChildProcess(spawnFfmpeg(args), {
         signal: opts?.signal,
-        deadlineAtMs: Date.now() + timeout,
-        onStderr: opts?.onStderr,
+        ...(stallTimeout === undefined
+            ? { deadlineAtMs: Date.now() + (opts?.timeout ?? DEFAULT_TIMEOUT) }
+            : { inactivityTimeoutMs: stallTimeout }),
+        onStderr: stallTimeout === undefined
+            ? opts?.onStderr
+            : (chunk) => {
+                readStats(chunk);
+                opts?.onStderr?.(chunk);
+            },
     });
     return toResult(await managed.wait());
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.180",
+  "version": "0.8.181",
   "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/core": "^0.8.180",
-    "@hyperframes/parsers": "^0.8.180"
+    "@hyperframes/core": "^0.8.181",
+    "@hyperframes/parsers": "^0.8.181"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",