@hyperframes/engine 0.8.191 → 0.8.193

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, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, 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";
@@ -72,6 +72,7 @@ export { aacSegmentCount, encodeAac } 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";
+export { renameWithRetry, renameWithRetryAsync } from "./utils/renameWithRetry.js";
 export { psnrDb, resolveDeVerifyMinDb } from "./utils/psnr.js";
 export { decodePng, decodePngToRgb48le, blitRgba8OverRgb48le, blitRgb48leRegion, blitRgb48leAffine, parseTransformMatrix, roundedRectAlpha, resampleRgb48leObjectFit, normalizeObjectFit, type ObjectFit, } from "./utils/alphaBlit.js";
 export { groupIntoLayers, type CompositeLayer } from "./utils/layerCompositor.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, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, 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";
@@ -76,6 +76,7 @@ export { aacSegmentCount, encodeAac } 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";
+export { renameWithRetry, renameWithRetryAsync } from "./utils/renameWithRetry.js";
 // drawElement self-verify comparison — shared by the streaming drain
 // (producer) and the parallel disk-path verify (parallelCoordinator).
 export { psnrDb, resolveDeVerifyMinDb } from "./utils/psnr.js";

package/dist/services/aacEncode.js

@@ -2,8 +2,10 @@
  * AAC for the mixed 48 kHz audio. One encoder is single-threaded (about 60x real time),
  * so long audio is encoded as frame-aligned segments in parallel and their frames joined.
  */
+import { execFile } from "node:child_process";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { getFfmpegBinary } from "../utils/ffmpegBinaries.js";
 import { runFfmpeg } from "../utils/runFfmpeg.js";
 const SAMPLE_RATE = 48_000;
 const FRAME_SAMPLES = 1024;
@@ -48,8 +50,33 @@ function planSegments(totalDuration, count) {
         return { trim, keepFrom: cut - firstFrame, keepTo: next - firstFrame };
     });
 }
+const settsDurationSupport = new Map();
+/** FFmpeg before 5.0 (Ubuntu 22.04 ships 4.4) has no `duration` option on the setts filter. */
+function supportsSettsDuration(binary = getFfmpegBinary()) {
+    let supported = settsDurationSupport.get(binary);
+    if (!supported) {
+        supported = new Promise((resolve) => {
+            execFile(binary, ["-hide_banner", "-h", "bsf=setts"], (error, stdout) => {
+                // A binary that cannot even print help fails the encode with its own error, not this one.
+                resolve(error !== null || stdout.includes("duration"));
+            });
+        });
+        settsDurationSupport.set(binary, supported);
+    }
+    return supported;
+}
+function encodeInOnePass(input, outputPath, { signal, timeout, filter }) {
+    const filters = [filter, `aresample=${SAMPLE_RATE}`].filter(Boolean).join(",");
+    return runFfmpeg(["-i", input, "-af", filters, ...AAC_ARGS, "-y", outputPath], {
+        signal,
+        timeout,
+    });
+}
 /** `input`, after `filter`, is audio of exactly `totalDuration`. */
 export async function encodeAac(input, outputPath, totalDuration, { signal, timeout, filter, segments: count = aacSegmentCount(totalDuration), }) {
+    if (!(await supportsSettsDuration())) {
+        return encodeInOnePass(input, outputPath, { signal, timeout, filter });
+    }
     const dir = mkdtempSync(join(dirname(outputPath), ".aac-segments-"));
     try {
         const segments = planSegments(totalDuration, count).map((segment, k) => ({

package/dist/services/audioMixer.js

@@ -1,6 +1,7 @@
 // fallow-ignore-file complexity code-duplication
 import { isSelfOrAncestorHidden, memberGroupKey, isMemberGroupHidden } from "./mediaHidden.js";
-import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, renameSync, rmSync, writeFileSync, } from "fs";
+import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, rmSync, writeFileSync } from "fs";
+import { renameWithRetry } from "../utils/renameWithRetry.js";
 import { join, dirname, isAbsolute, relative } from "path";
 import { parseHTML } from "linkedom";
 import { extractAudioMetadata } from "../utils/ffprobe.js";
@@ -133,6 +134,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 +431,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 +459,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 +512,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 +528,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 +582,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 +599,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 +632,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);
@@ -945,7 +1014,7 @@ async function mixGroupMembers(memberTracks, outputPath, totalDuration, signal,
         const summed = await sumInSlices(memberTracks, scratchDir, totalDuration, signal, config);
         if (!summed.success)
             return summed;
-        renameSync(summed.track.srcPath, outputPath);
+        renameWithRetry(summed.track.srcPath, outputPath);
         return { success: true, degradedAutomation: summed.degradedAutomation };
     }
     finally {
@@ -991,15 +1060,18 @@ async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config)
  */
 async function mixThroughFloatSum(tracks, masterChain, outputPath, workDir, totalDuration, signal, config) {
     const sumPath = join(workDir, "master-sum.wav");
+    const mixStart = Date.now();
     const sum = await mixAudioTracks(tracks, sumPath, totalDuration, signal, config);
     if (!sum.success)
         return { ...sum, outputPath };
+    const masterStart = Date.now();
     const encoderInput = masterChain
         ? (await applyAudioFxChain(sumPath, masterChain, join(workDir, "master-fx.wav"), {
             trackId: "master",
             signal,
         })).path
         : sumPath;
+    const encodeStart = Date.now();
     const encoded = await encodeAac(encoderInput, outputPath, totalDuration, {
         signal,
         timeout: config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout,
@@ -1016,8 +1088,17 @@ async function mixThroughFloatSum(tracks, masterChain, outputPath, workDir, tota
         };
     }
     if (config?.keepEncoderInputAt)
-        renameSync(encoderInput, config.keepEncoderInputAt);
-    return { ...sum, outputPath, durationMs: sum.durationMs + encoded.durationMs };
+        renameWithRetry(encoderInput, config.keepEncoderInputAt);
+    return {
+        ...sum,
+        outputPath,
+        durationMs: sum.durationMs + encoded.durationMs,
+        phaseMs: {
+            mix: masterStart - mixStart,
+            master: encodeStart - masterStart,
+            encode: Date.now() - encodeStart,
+        },
+    };
 }
 export async function processCompositionAudio(elements, baseDir, workDir, outputPath, totalDuration, signal, config, compiledDir) {
     const startMs = Date.now();
@@ -1053,7 +1134,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 +1198,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 +1215,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 +1233,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 }
@@ -1296,6 +1380,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             failures,
         };
     };
+    const prepareMs = Date.now() - startMs;
     if (failures.length > 0)
         return bail();
     // Parsed before any group is mixed, so a malformed master chain fails fast and
@@ -1415,6 +1500,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
     }
     if (failures.length > 0)
         return bail();
+    const groupsMs = Date.now() - startMs - prepareMs;
     let mixResult;
     try {
         mixResult =
@@ -1434,6 +1520,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
     return {
         ...mixResult,
         durationMs: Date.now() - startMs,
+        phaseMs: { prepare: prepareMs, groups: groupsMs, ...mixResult.phaseMs },
         // Both, when both degraded. `mixResult.error ?? degradedNote` reported only
         // the outer mix and dropped the one that names which GROUPS lost their
         // members' automation — two different losses, and the operator needs to

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[];
@@ -80,4 +81,5 @@ export interface MixResult {
     tracksProcessed: number;
     error?: string;
     failures?: AudioProcessingFailure[];
+    phaseMs?: Partial<Record<"prepare" | "groups" | "mix" | "master" | "encode", number>>;
 }

package/dist/services/audioVolumeEnvelope.js

@@ -14,7 +14,8 @@
  * `extractAudioSegment`). Anything else is rejected so
  * the caller can fall back to the expression path rather than corrupting audio.
  */
-import { mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { renameWithRetry } from "../utils/renameWithRetry.js";
 import { dirname, join } from "path";
 import { normaliseEnvelope } from "@hyperframes/core/media-volume-envelope";
 import { riffChunks, wavFormatTag } from "./wavChunks.js";
@@ -131,7 +132,7 @@ export function applyVolumeEnvelopeToWav(wavPath, keyframes, trackStart, baseVol
         stagingDir = mkdtempSync(join(dirname(wavPath), ".hf-volume-"));
         const tempPath = join(stagingDir, "audio.wav");
         writeFileSync(tempPath, buffer, { flag: "wx" });
-        renameSync(tempPath, wavPath);
+        renameWithRetry(tempPath, wavPath);
         return true;
     }
     catch {

package/dist/services/browserManager.js

@@ -769,6 +769,7 @@ function getLowMemoryFlags() {
 }
 const CANVAS_DRAW_ELEMENT_FEATURE_FLAG = "--enable-features=CanvasDrawElement";
 const WEBGPU_FLAG = "--enable-unsafe-webgpu";
+const DISABLE_DXC_FLAG = "--disable-dawn-features=use_dxc";
 /**
  * Whether this launch renders WebGPU on SwiftShader: the composition needs it, the render opted in, no GPU is in use.
  * SwiftShader draws canvas WebGPU only via Vulkan with GPU compositing on, and not at all under --disable-gpu.
@@ -839,6 +840,9 @@ export function buildChromeArgs(options, config) {
     ];
     if (browserGpuMode !== "software" || options.requiresWebGpu) {
         chromeArgs.push(WEBGPU_FLAG);
+        if (platform === "win32") {
+            chromeArgs.push(DISABLE_DXC_FLAG);
+        }
     }
     if (softwareWebGpu)
         chromeArgs.push("--use-vulkan=swiftshader");

package/dist/services/captureFailure.d.ts

@@ -10,16 +10,19 @@ export declare class CaptureFailure extends Error {
     readonly kind: CaptureFailureKind;
     readonly cause: unknown;
     readonly workerDiagnostics: readonly CaptureWorkerDiagnostic[];
+    readonly pageErrorLines: readonly string[];
     constructor(input: {
         kind: CaptureFailureKind;
         message: string;
         cause?: unknown;
         workerDiagnostics?: readonly CaptureWorkerDiagnostic[];
+        pageErrorLines?: readonly string[];
     });
 }
 export declare function classifyCaptureFailure(error: unknown, options?: {
     signal?: AbortSignal;
     workerDiagnostics?: readonly CaptureWorkerDiagnostic[];
+    pageErrorLines?: readonly string[];
 }): CaptureFailure;
 export declare function isTransientBrowserError(error: unknown): boolean;
 export declare function isMemoryExhaustionError(error: unknown): boolean;

package/dist/services/captureFailure.js

@@ -2,12 +2,14 @@ export class CaptureFailure extends Error {
     kind;
     cause;
     workerDiagnostics;
+    pageErrorLines;
     constructor(input) {
         super(input.message);
         this.name = "CaptureFailure";
         this.kind = input.kind;
         this.cause = input.cause;
         this.workerDiagnostics = Object.freeze((input.workerDiagnostics ?? []).map((diagnostic) => Object.freeze({ ...diagnostic, lines: Object.freeze([...diagnostic.lines]) })));
+        this.pageErrorLines = Object.freeze([...(input.pageErrorLines ?? [])]);
         if (input.cause instanceof Error && input.cause.stack)
             this.stack = input.cause.stack;
     }
@@ -101,41 +103,40 @@ function ioError(error, message) {
         BROKEN_PIPE_MESSAGE.test(message) ||
         hasIoOperationFailure(message));
 }
+const ORDERED_KIND_RULES = [
+    [
+        "memory_exhaustion",
+        (message) => BUN_MEMORY_EXHAUSTION_EXACT_MESSAGE.test(message.trim()) ||
+            BUN_MEMORY_EXHAUSTION_WRAPPED_WORKER_MESSAGE.test(message) ||
+            matchesAny(message, MEMORY_EXHAUSTION_ERROR_PATTERNS),
+    ],
+    ["verification", (message) => matchesAny(message, VERIFICATION_ERROR_PATTERNS)],
+    ["protocol_timeout", (message) => matchesAny(message, PROTOCOL_TIMEOUT_PATTERNS)],
+    ["transient_browser", (message) => matchesAny(message, TRANSIENT_BROWSER_ERROR_PATTERNS)],
+    ["authoring", (message) => matchesAny(message, AUTHORING_ERROR_PATTERNS)],
+];
+function classifyKind(error, message, signal) {
+    if (signal?.aborted || /(?:render|capture)?_?cancelled|AbortError/i.test(message)) {
+        return "cancelled";
+    }
+    const rule = ORDERED_KIND_RULES.find(([, matches]) => matches(message));
+    if (rule)
+        return rule[0];
+    return ioError(error, message) ? "io" : "authoring";
+}
 export function classifyCaptureFailure(error, options = {}) {
-    if (error instanceof CaptureFailure && !options.workerDiagnostics && !options.signal?.aborted) {
-        return error;
+    const prior = error instanceof CaptureFailure ? error : undefined;
+    if (prior && !(options.workerDiagnostics || options.pageErrorLines || options.signal?.aborted)) {
+        return prior;
     }
     const message = messageOf(error);
-    let kind;
-    if (options.signal?.aborted || /(?:render|capture)?_?cancelled|AbortError/i.test(message)) {
-        kind = "cancelled";
-    }
-    else if (BUN_MEMORY_EXHAUSTION_EXACT_MESSAGE.test(message.trim()) ||
-        BUN_MEMORY_EXHAUSTION_WRAPPED_WORKER_MESSAGE.test(message) ||
-        matchesAny(message, MEMORY_EXHAUSTION_ERROR_PATTERNS)) {
-        kind = "memory_exhaustion";
-    }
-    else if (matchesAny(message, VERIFICATION_ERROR_PATTERNS)) {
-        kind = "verification";
-    }
-    else if (matchesAny(message, PROTOCOL_TIMEOUT_PATTERNS)) {
-        kind = "protocol_timeout";
-    }
-    else if (matchesAny(message, TRANSIENT_BROWSER_ERROR_PATTERNS)) {
-        kind = "transient_browser";
-    }
-    else if (matchesAny(message, AUTHORING_ERROR_PATTERNS)) {
-        kind = "authoring";
-    }
-    else {
-        kind = ioError(error, message) ? "io" : "authoring";
-    }
+    const kind = classifyKind(error, message, options.signal);
     return new CaptureFailure({
         kind,
         message,
         cause: error,
-        workerDiagnostics: options.workerDiagnostics ??
-            (error instanceof CaptureFailure ? error.workerDiagnostics : undefined),
+        workerDiagnostics: options.workerDiagnostics ?? prior?.workerDiagnostics,
+        pageErrorLines: options.pageErrorLines ?? prior?.pageErrorLines,
     });
 }
 export function isTransientBrowserError(error) {

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

@@ -32,7 +32,8 @@
  * become inert and can be gc'd by the caller.
  */
 import { createHash, randomUUID } from "node:crypto";
-import { createReadStream, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync, } from "node:fs";
+import { createReadStream, existsSync, lstatSync, mkdirSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync, } from "node:fs";
+import { renameWithRetry } from "../utils/renameWithRetry.js";
 import { join } from "node:path";
 import { FRAME_FILENAME_PREFIX, framePathsFromDirectory } from "./extractedFrameIndex.js";
 /** Filename prefix for extracted frames. Shared with the extractor. */
@@ -172,7 +173,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 };
@@ -185,7 +186,7 @@ export function publishCacheEntry(entry, partialDir) {
         return { dir: partialDir, published: false };
     }
     try {
-        renameSync(partialDir, entry.dir);
+        renameWithRetry(partialDir, entry.dir);
         return { dir: entry.dir, published: true };
     }
     catch (err) {
@@ -202,7 +203,7 @@ export function publishCacheEntry(entry, partialDir) {
         return { dir: partialDir, published: false };
     }
     try {
-        renameSync(partialDir, entry.dir);
+        renameWithRetry(partialDir, entry.dir);
         return { dir: entry.dir, published: true };
     }
     catch {

package/dist/services/frameCapture.js

@@ -393,14 +393,17 @@ export async function driveWarmupTicks(options, state) {
             if (!state.running)
                 return;
         }
+        let ticked = false;
         try {
             await options.tick(state.ticks * options.intervalMs, options.intervalMs);
             state.ticks += 1;
+            ticked = true;
         }
         catch {
             // Page not ready yet; keep spinning.
         }
-        await sleep(options.intervalMs);
+        if (!(options.lockWarmupTicks && !state.running && ticked))
+            await sleep(options.intervalMs);
     }
 }
 export function resolveCaptureSessionOptions(options, browserVersion, platform = process.platform) {

package/dist/services/parallelCoordinator.d.ts

@@ -46,6 +46,8 @@ export interface WorkerResult {
     perf?: CapturePerfSummary;
     error?: string;
     diagnostics?: string[];
+    /** The worker session's `[Browser:PAGEERROR]` console lines, kept so the render's error count sees them. */
+    pageErrorLines?: string[];
     failure?: CaptureFailure;
 }
 export interface ParallelProgress {