@hyperframes/engine 0.8.191 → 0.8.192

package/dist/index.d.ts

@@ -46,7 +46,7 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, type GpuEncoder, type PackageHlsOptions, } from "./services/chunkEncoder.js";
 export type { EncoderOptions, EncodeResult, MuxResult } from "./services/chunkEncoder.types.js";
 export { spawnStreamingEncoder, createFrameReorderBuffer, type StreamingEncoder, type StreamingEncoderOptions, type StreamingEncoderResult, type FrameReorderBuffer, } from "./services/streamingEncoder.js";
-export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, resolveFinalFrameExtractionWindow, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, type VideoElement, type ImageElement, type ExtractedFrames, type DeferredFrameRange, type FrameRange, type ExtractionOptions, type ExtractionResult, type ExtractionPhaseBreakdown, type TimelineExtractionWindow, type VideoExtractionFailure, type VideoExtractionFailureKind, type VideoExtractionFailureGroupDetails, type VideoExtractionFailureRetry, type VideoExtractionFailureStatusClass, type SafeVideoExtractionSourceIdentity, type VideoFrameFormat, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, } from "./services/videoFrameExtractor.js";
+export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, type VideoElement, type ImageElement, type ExtractedFrames, type DeferredFrameRange, type FrameRange, type ExtractionOptions, type ExtractionResult, type ExtractionPhaseBreakdown, type TimelineExtractionWindow, type VideoExtractionFailure, type VideoExtractionFailureKind, type VideoExtractionFailureGroupDetails, type VideoExtractionFailureRetry, type VideoExtractionFailureStatusClass, type SafeVideoExtractionSourceIdentity, type VideoFrameFormat, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, } from "./services/videoFrameExtractor.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, type RefResolverEl, type RefResolverDoc, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
@@ -64,7 +64,7 @@ export type { MotionBlurOptions, MotionBlurBlendSpace } from "./services/motionB
 export type { PageMotionBlurOff } from "./types.js";
 export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js";
 export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
-export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, probeMediaProfile, analyzeKeyframeIntervals, type VideoMetadata, type AudioMetadata, type MediaProbeProfile, type KeyframeAnalysis, } from "./utils/ffprobe.js";
+export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, probeMediaProfile, analyzeKeyframeIntervals, type VideoMetadata, type AudioMetadata, type MediaProbeProfile, type KeyframeAnalysis, } from "./utils/ffprobe.js";
 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";

package/dist/index.js

@@ -50,7 +50,7 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, } from "./services/chunkEncoder.js";
 export { spawnStreamingEncoder, createFrameReorderBuffer, } from "./services/streamingEncoder.js";
 // ── Media processing ───────────────────────────────────────────────────────────
-export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, resolveFinalFrameExtractionWindow, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, } from "./services/videoFrameExtractor.js";
+export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, } from "./services/videoFrameExtractor.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
@@ -68,7 +68,7 @@ export { appendSoftwareEncoderThreadsArg } from "./services/softwareEncoderThrea
 export { frameSequencePath } from "./services/extractedFrameIndex.js";
 export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js";
 export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
-export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, probeMediaProfile, analyzeKeyframeIntervals, } from "./utils/ffprobe.js";
+export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, probeMediaProfile, analyzeKeyframeIntervals, } from "./utils/ffprobe.js";
 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";

package/dist/services/audioMixer.js

@@ -133,6 +133,8 @@ function legacyFilterScriptOptionIsUnsupported(stderr) {
  */
 // Caps the ffmpeg runs that prepare clips; all of a long mix's clips at once starved the host (200 clips, 200 ffmpeg).
 const inPrepareSlot = createConcurrencyLimit(Math.max(2, Math.floor(cpus().length / 2)));
+// A clip read from a URL spends its time waiting on the network, so it needs no CPU-sized limit.
+const inRemotePrepareSlot = createConcurrencyLimit(16);
 const MAX_VOLUME_SEGMENTS = 32;
 /**
  * Volume delta below which a keyframe is collinear enough to drop. Kept tight
@@ -428,11 +430,13 @@ export function parseAudioElements(html) {
     const startCache = new Map();
     const visiting = new Set();
     const resolveStart = (el) => el.getAttribute("data-start") ? resolveReferencedStart(document, el, startCache, visiting) : 0;
-    // `end` stays a plain numeric read (the mixer derives the real segment length
-    // from data-duration / natural media downstream); guard NaN so a malformed
-    // value never poisons the mix instead of falling back to 0.
-    const parseEnd = (raw) => {
-        return parseStrictFiniteTimingNumber(raw) ?? 0;
+    // Same rule as core's compileTimingAttrs: data-end, else start + data-duration, else 0 (unknown).
+    const resolveEnd = (el) => {
+        const end = parseStrictFiniteTimingNumber(el.getAttribute("data-end"));
+        if (end != null)
+            return end;
+        const duration = parseStrictFiniteTimingNumber(el.getAttribute("data-duration"));
+        return duration != null && duration > 0 ? resolveStart(el) + duration : 0;
     };
     const isHidden = isSelfOrAncestorHidden;
     // Resolved once per parse. A group element carrying `data-hidden` drops
@@ -454,9 +458,10 @@ export function parseAudioElements(html) {
             id,
             src,
             start: resolveStart(el),
-            end: parseEnd(el.getAttribute("data-end")),
+            end: resolveEnd(el),
             mediaStart: readMediaStart(el),
             playbackRate: readElementRateSpec(el),
+            loop: el.getAttribute("loop") !== null,
             layer: layerAttr ? parseInt(layerAttr) : 0,
             volume: volumeAttr ? parseFloat(volumeAttr) : 1.0,
             ...(fades.fadeIn > 0 ? { fadeIn: fades.fadeIn } : {}),
@@ -506,14 +511,14 @@ const FAIL_ON_READ_ERROR_INSTEAD_OF_ENDING_THERE = ["-xerror"];
 const SIDECAR_WARM_UP_SECONDS = 1;
 /** Decode `duration` s of audio from `mediaStart` in Chrome's media time. Until every stream has
  * started, an input seek snaps audio to the video's first keyframe, so read by timestamp instead. */
-async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, duration, playbackRate = 1, signal, config, audioSidecarUrl) {
+async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, duration, playbackRate = 1, signal, config, audioSidecarUrl, options) {
     const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
     const outputDir = dirname(outputPath);
     if (!existsSync(outputDir))
         mkdirSync(outputDir, { recursive: true });
     const normalizedPlaybackRate = normalizeRateSpec(playbackRate);
     const sourceDuration = sourceTimeAt(normalizedPlaybackRate, duration);
-    // A failed local probe keeps FFmpeg's default channel conversion and the input seek; a URL probe
+    // A failed non-looping local probe keeps FFmpeg's channel conversion and input seek; a URL probe
     // is retried once, then fails: a blip must not change how the next, successful read is mixed.
     const readsUrl = isHttpUrl(srcPath);
     const metadata = readsUrl
@@ -522,7 +527,53 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
                 throw error;
             return extractAudioMetadata(srcPath, { signal });
         })
-        : await extractAudioMetadata(srcPath).catch(() => null);
+        : await extractAudioMetadata(srcPath).catch((error) => {
+            if (options?.loop)
+                throw error;
+            return null;
+        });
+    const loopDuration = (metadata?.durationSeconds ?? 0) - mediaStart;
+    if (options?.loop && loopDuration > 0 && sourceDuration > loopDuration) {
+        const cycleDir = mkdtempSync(join(outputDir, ".audio-loop-"));
+        const cyclePath = join(cycleDir, "cycle.wav");
+        try {
+            const cycle = await extractAudioSegment(srcPath, cyclePath, stage, mediaStart, loopDuration, 1, signal, config, audioSidecarUrl, { padToDuration: true });
+            if (!cycle.success)
+                return { ...cycle, outputPath };
+            const outputArgs = preparedAudioOutputArgs(metadata, normalizedPlaybackRate, duration, null);
+            const result = await runFfmpeg([
+                "-stream_loop",
+                "-1",
+                "-t",
+                String(sourceDuration),
+                "-i",
+                cyclePath,
+                "-vn",
+                "-acodec",
+                "pcm_s16le",
+                "-ar",
+                "48000",
+                ...outputArgs,
+                "-t",
+                String(duration),
+                "-y",
+                outputPath,
+            ], { signal, timeout: ffmpegProcessTimeout });
+            const failure = result.success
+                ? undefined
+                : ffmpegFailure(stage, result, ffmpegProcessTimeout);
+            return {
+                success: result.success,
+                outputPath,
+                durationMs: cycle.durationMs + result.durationMs,
+                error: failure?.detail,
+                failure,
+            };
+        }
+        finally {
+            rmSync(cycleDir, { recursive: true, force: true });
+        }
+    }
     const inputSeek = mediaStart >= (metadata?.latestStreamLeadSeconds ?? 0);
     const start = formatFilterNumber(mediaStart);
     const timestampTrim = inputSeek
@@ -530,7 +581,12 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
         : `atrim=start=${start}:end=${formatFilterNumber(mediaStart + sourceDuration)},asetpts=PTS-${start}/TB,aresample=async=1:first_pts=0`;
     const fromSidecar = audioSidecarUrl !== undefined && inputSeek && normalizedPlaybackRate === 1;
     const warmUp = fromSidecar ? Math.min(SIDECAR_WARM_UP_SECONDS, mediaStart) : 0;
-    const outputArgs = preparedAudioOutputArgs(metadata, normalizedPlaybackRate, duration, warmUp > 0 ? `atrim=start=${warmUp},asetpts=PTS-STARTPTS` : timestampTrim);
+    const outputArgs = preparedAudioOutputArgs(metadata, normalizedPlaybackRate, duration, [
+        warmUp > 0 ? `atrim=start=${warmUp},asetpts=PTS-STARTPTS` : timestampTrim,
+        ...(options?.padToDuration ? ["apad"] : []),
+    ]
+        .filter(Boolean)
+        .join(",") || null);
     const readFrom = fromSidecar ? audioSidecarUrl : srcPath;
     const args = [
         ...(readsUrl ? FAIL_ON_READ_ERROR_INSTEAD_OF_ENDING_THERE : []),
@@ -542,7 +598,7 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
         readFrom,
     ];
     args.push("-vn", "-acodec", "pcm_s16le", "-ar", "48000", ...outputArgs);
-    if (normalizedPlaybackRate !== 1)
+    if (normalizedPlaybackRate !== 1 || options?.padToDuration)
         args.push("-t", String(duration));
     args.push("-y", outputPath);
     const result = await runFfmpeg(args, { signal, timeout: ffmpegProcessTimeout });
@@ -575,6 +631,18 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
         failure,
     };
 }
+function isRemoteElement(element, baseDir, compiledDir, config) {
+    if (isHttpUrl(element.src))
+        return true;
+    if (!config?.urlByAbsentLocalPath?.size)
+        return false;
+    try {
+        return config.urlByAbsentLocalPath.has(resolveProjectRelativeSrc(element.src, baseDir, compiledDir));
+    }
+    catch {
+        return false;
+    }
+}
 async function generateSilence(outputPath, duration, signal, config) {
     const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
     const outputDir = dirname(outputPath);
@@ -1053,7 +1121,9 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
         else
             signal.addEventListener("abort", () => internalController.abort(), { once: true });
     }
-    await Promise.all(elements.map((element, index) => inPrepareSlot(async () => {
+    await Promise.all(elements.map((element, index) => (isRemoteElement(element, baseDir, compiledDir, config)
+        ? inRemotePrepareSlot
+        : inPrepareSlot)(async () => {
         if (effectiveSignal.aborted) {
             failures.push({
                 stage: "cancelled",
@@ -1115,6 +1185,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             }
             // Fallback: if no duration was specified, probe the actual file
             if (element.end - element.start <= 0) {
+                console.warn(`[audioMixer] ${element.id} has no data-duration or data-end; its length is unknown, so it plays to the end of its source`);
                 let metadata;
                 try {
                     metadata = await extractAudioMetadata(srcPath, readInPlace ? { signal: effectiveSignal } : undefined);
@@ -1131,7 +1202,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             let audioSrcPath = srcPath;
             if (element.type === "video") {
                 const extractedPath = join(workDir, `${element.id}-extracted.wav`);
-                const extractResult = await extractAudioSegment(srcPath, extractedPath, "extract", element.mediaStart, element.end - element.start, element.playbackRate, effectiveSignal, config, audioSidecarUrl);
+                const extractResult = await extractAudioSegment(srcPath, extractedPath, "extract", element.mediaStart, element.end - element.start, element.playbackRate, effectiveSignal, config, audioSidecarUrl, { loop: element.loop });
                 if (!extractResult.success) {
                     failures.push(extractResult.failure
                         ? { ...extractResult.failure, elementId: element.id }
@@ -1149,7 +1220,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             }
             else {
                 const trimmedPath = join(workDir, `${element.id}-trimmed.wav`);
-                const prepResult = await extractAudioSegment(srcPath, trimmedPath, "prepare", element.mediaStart, element.end - element.start, element.playbackRate, effectiveSignal, config);
+                const prepResult = await extractAudioSegment(srcPath, trimmedPath, "prepare", element.mediaStart, element.end - element.start, element.playbackRate, effectiveSignal, config, undefined, { loop: element.loop });
                 if (!prepResult.success) {
                     failures.push(prepResult.failure
                         ? { ...prepResult.failure, elementId: element.id }

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

@@ -11,6 +11,7 @@ export interface AudioElement {
     mediaStart: number;
     /** Normalized source-time multiplier: a constant, or the clip's `rate` lane. */
     playbackRate?: RateSpec;
+    loop?: boolean;
     layer: number;
     volume?: number;
     volumeKeyframes?: AudioVolumeKeyframe[];

package/dist/services/chunkEncoder.js

@@ -214,7 +214,7 @@ export function buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder = nu
         else {
             const encoderName = codec === "h264" ? "libx264" : "libx265";
             args.push("-c:v", encoderName, "-preset", preset);
-            appendSoftwareEncoderThreadsArg(args);
+            appendSoftwareEncoderThreadsArg(args, encoderName);
             if (bitrate)
                 args.push("-b:v", bitrate);
             else

package/dist/services/extractionCache.js

@@ -172,7 +172,7 @@ function isTargetExistsRenameError(err) {
  * winner is always correct. Returns null when no winner is present.
  */
 function adoptPublishedWinner(entry, partialDir) {
-    if (!existsSync(join(entry.dir, COMPLETE_SENTINEL)))
+    if (!existsSync(join(entry.dir, COMPLETE_SENTINEL)) || !hasFrameFiles(entry.dir))
         return null;
     removeDir(partialDir);
     return { dir: entry.dir, published: true };

package/dist/services/softwareEncoderThreads.d.ts

@@ -1,2 +1,3 @@
+export declare const X265_MAX_THREADS = 16;
 /** x264/x265 bitstreams depend on the thread count, so it comes from the CPU quota, never ffmpeg's host-core guess. */
-export declare function appendSoftwareEncoderThreadsArg(args: string[], parallelism?: number): void;
+export declare function appendSoftwareEncoderThreadsArg(args: string[], encoder: "libx264" | "libx265", parallelism?: number): void;

package/dist/services/softwareEncoderThreads.js

@@ -1,5 +1,7 @@
 import { availableParallelism } from "node:os";
+export const X265_MAX_THREADS = 16;
 /** x264/x265 bitstreams depend on the thread count, so it comes from the CPU quota, never ffmpeg's host-core guess. */
-export function appendSoftwareEncoderThreadsArg(args, parallelism = availableParallelism()) {
-    args.push("-threads", String(Math.max(1, Math.floor(parallelism))));
+export function appendSoftwareEncoderThreadsArg(args, encoder, parallelism = availableParallelism()) {
+    const cap = encoder === "libx265" ? X265_MAX_THREADS : Infinity;
+    args.push("-threads", String(Math.min(cap, Math.max(1, Math.floor(parallelism)))));
 }

package/dist/services/streamingEncoder.js

@@ -181,7 +181,7 @@ export function buildStreamingArgs(options, outputPath, gpuEncoder = null) {
         else {
             const encoderName = codec === "h264" ? "libx264" : "libx265";
             args.push("-c:v", encoderName, "-preset", preset);
-            appendSoftwareEncoderThreadsArg(args);
+            appendSoftwareEncoderThreadsArg(args, encoderName);
             if (bitrate)
                 args.push("-b:v", bitrate);
             else

package/dist/utils/ffprobe.d.ts

@@ -100,6 +100,8 @@ export interface MediaProbeProfile {
     hasAudioStream: boolean;
     visualKind: "none" | "still" | "moving";
 }
+/** A URL whose bytes can never change (its path holds their hash), so probes of it are cacheable. */
+export declare function declareContentAddressedUrl(url: string, sha256: string): void;
 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;

package/dist/utils/ffprobe.js

@@ -140,6 +140,7 @@ const videoMetadataCache = new Map();
 const finalVideoFrameTimestampCache = new Map();
 const finalVideoFrameTimestampSignalCaches = new WeakMap();
 const audioMetadataCache = new Map();
+const audioMetadataSignalCaches = new WeakMap();
 const mediaProbeOutputCache = new Map();
 const mediaProbeOutputSignalCaches = new WeakMap();
 const MEDIA_PROBE_OUTPUT_CACHE_MAX_ENTRIES = 128;
@@ -210,7 +211,17 @@ function isPngImageProbe(output) {
     return (formatNames.includes("png_pipe") ||
         output.streams.some((stream) => stream.codec_type === "video" && stream.codec_name?.toLowerCase() === "png"));
 }
+const contentAddressedUrls = new Map();
+const withoutQuery = (url) => url.split(/[?#]/, 1)[0] ?? url;
+/** A URL whose bytes can never change (its path holds their hash), so probes of it are cacheable. */
+export function declareContentAddressedUrl(url, sha256) {
+    contentAddressedUrls.set(withoutQuery(url), sha256);
+}
 export function mediaFileIdentity(filePath) {
+    if (/^https?:\/\//i.test(filePath)) {
+        const sha256 = contentAddressedUrls.get(withoutQuery(filePath));
+        return sha256 ? `sha256:${sha256}` : null;
+    }
     try {
         const stat = statSync(filePath, { bigint: true });
         return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(":");
@@ -740,49 +751,53 @@ export async function extractFinalVideoFrameTimestamp(filePath, metadata, signal
  */
 export const extractVideoMetadata = extractMediaMetadata;
 export async function extractAudioMetadata(filePath, options) {
-    // A caller-owned abort signal cannot safely share a cached in-flight probe:
-    // cancelling one consumer would also cancel unrelated consumers. Signal-bound
-    // probes therefore bypass the process-promise cache.
+    // A probe bound to a caller's abort signal is shared only among callers of that same signal,
+    // and only when the file has an identity to key it by.
     const identity = mediaFileIdentity(filePath);
-    const cached = options?.signal
-        ? undefined
-        : readMetadataCache(audioMetadataCache, filePath, identity);
+    const signal = options?.signal;
+    if (signal && identity === null)
+        return probeAudioMetadata(filePath, signal);
+    let cache = audioMetadataCache;
+    if (signal) {
+        cache = audioMetadataSignalCaches.get(signal) ?? new Map();
+        audioMetadataSignalCaches.set(signal, cache);
+    }
+    const cached = readMetadataCache(cache, filePath, identity);
     if (cached)
         return cached;
-    const probePromise = (async () => {
-        const output = await probeMediaOutput(filePath, options?.signal);
-        const audioStream = output.streams.find((s) => s.codec_type === "audio");
-        if (!audioStream)
-            throw new Error("[FFmpeg] No audio stream found");
-        let durationSeconds = output.format.duration ? parseFloat(output.format.duration) : 0;
-        const streamDuration = audioStream.duration ? parseFloat(audioStream.duration) : undefined;
-        const sampleRate = audioStream.sample_rate ? parseInt(audioStream.sample_rate) : 44100;
-        const audioCodec = audioStream.codec_name || "unknown";
-        // Container summaries can undercount intact audio, so the decoded last frame wins.
-        // The probe returns null instead of throwing: a throw here drops the audio element.
-        if (sampleRate > 0) {
-            const decoded = await probeDecodedAudioDuration(filePath, sampleRate, audioStartSeconds(audioStream, output.format), durationSeconds, options?.signal);
-            if (decoded !== null) {
-                durationSeconds = reconcileAudioDuration(durationSeconds, decoded, output.format);
-            }
-        }
-        return {
-            durationSeconds,
-            streamDurationSeconds: streamDuration && streamDuration > 0 ? streamDuration : undefined,
-            sampleRate,
-            channels: audioStream.channels || 2,
-            audioCodec,
-            bitrate: output.format.bit_rate ? parseInt(output.format.bit_rate) : undefined,
-            latestStreamLeadSeconds: latestStreamLeadSeconds(output),
-            audioStreamLeadSeconds: streamLeadSeconds(output, audioStream),
-            audioStreamCount: output.streams.filter((s) => s.codec_type === "audio").length,
-        };
-    })();
-    if (options?.signal)
-        return probePromise;
-    writeMetadataCache(audioMetadataCache, filePath, identity, probePromise);
+    const probePromise = probeAudioMetadata(filePath, signal);
+    writeMetadataCache(cache, filePath, identity, probePromise);
     return probePromise;
 }
+async function probeAudioMetadata(filePath, signal) {
+    const output = await probeMediaOutput(filePath, signal);
+    const audioStream = output.streams.find((s) => s.codec_type === "audio");
+    if (!audioStream)
+        throw new Error("[FFmpeg] No audio stream found");
+    let durationSeconds = output.format.duration ? parseFloat(output.format.duration) : 0;
+    const streamDuration = audioStream.duration ? parseFloat(audioStream.duration) : undefined;
+    const sampleRate = audioStream.sample_rate ? parseInt(audioStream.sample_rate) : 44100;
+    const audioCodec = audioStream.codec_name || "unknown";
+    // Container summaries can undercount intact audio, so the decoded last frame wins.
+    // The probe returns null instead of throwing: a throw here drops the audio element.
+    if (sampleRate > 0) {
+        const decoded = await probeDecodedAudioDuration(filePath, sampleRate, audioStartSeconds(audioStream, output.format), durationSeconds, signal);
+        if (decoded !== null) {
+            durationSeconds = reconcileAudioDuration(durationSeconds, decoded, output.format);
+        }
+    }
+    return {
+        durationSeconds,
+        streamDurationSeconds: streamDuration && streamDuration > 0 ? streamDuration : undefined,
+        sampleRate,
+        channels: audioStream.channels || 2,
+        audioCodec,
+        bitrate: output.format.bit_rate ? parseInt(output.format.bit_rate) : undefined,
+        latestStreamLeadSeconds: latestStreamLeadSeconds(output),
+        audioStreamLeadSeconds: streamLeadSeconds(output, audioStream),
+        audioStreamCount: output.streams.filter((s) => s.codec_type === "audio").length,
+    };
+}
 /** Chrome's media time 0 is the earliest of these; a stream starting later plays that much in. */
 function audioVideoStreamStarts(output) {
     return (output?.streams ?? [])

package/dist/utils/htmlTemplate.js

@@ -22,7 +22,7 @@ function getSingleMeaningfulChild(container) {
  */
 export function unwrapTemplate(html) {
     const lowered = html.toLowerCase();
-    if (!lowered.includes("<template") || !lowered.includes("</template>")) {
+    if (!lowered.includes("<template") || !/<\/template[ \t\n\r\f]*>/.test(lowered)) {
         return html;
     }
     const { body } = parseHTMLContent(html);

package/dist/utils/processRss.js

@@ -78,8 +78,11 @@ export async function sampleProcessRss(pids, exec = defaultExec(), platform = pr
         if (platform === "win32") {
             const results = [];
             for (const pid of unique) {
-                const { stdout } = await exec("tasklist", ["/FO", "CSV", "/NH", "/FI", `PID eq ${pid}`]);
-                results.push(...parseTasklistCsv(pid, stdout));
+                try {
+                    const { stdout } = await exec("tasklist", ["/FO", "CSV", "/NH", "/FI", `PID eq ${pid}`]);
+                    results.push(...parseTasklistCsv(pid, stdout));
+                }
+                catch { }
             }
             return results;
         }

package/package.json

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