@hyperframes/engine 0.8.221 → 0.8.222

package/dist/index.d.ts

@@ -69,7 +69,8 @@ export { isBrowserSafePort, listenOnBrowserSafePort, settleOnBrowserSafePort, }
 export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
 export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, runFfprobe, 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 { _setDownloadFetchForTests, assertPublicHttpsUrl, isBlockedNetworkHost, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, type SafeDownloadUrlIdentity, type UrlDownloadOptions, type UrlDownloadTelemetry, type PublicHttpsTextOptions, } from "./utils/urlDownloader.js";
+export { _setDownloadFetchForTests, assertPublicHttpsUrl, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, type SafeDownloadUrlIdentity, type UrlDownloadOptions, type UrlDownloadTelemetry, type PublicHttpsTextOptions, } from "./utils/urlDownloader.js";
+export { isBlockedNetworkHost } from "./utils/networkPolicy.js";
 export { runFfmpeg, formatFfmpegError, describeFfmpegFailure, isExternalFfmpegInterruption, type RunFfmpegOptions, type RunFfmpegResult, } from "./utils/runFfmpeg.js";
 export { aacSegmentCount, encodeAac } from "./services/aacEncode.js";
 export { ManagedChildProcess, type ManagedChildProcessOptions, type ManagedChildProcessOutcome, type ManagedProcessTerminationReason, } from "./utils/managedChildProcess.js";

package/dist/index.js

@@ -73,7 +73,8 @@ export { isBrowserSafePort, listenOnBrowserSafePort, settleOnBrowserSafePort, }
 export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
 export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, runFfprobe, analyzeKeyframeIntervals, } from "./utils/ffprobe.js";
 export { NOT_MEDIA_PAYLOAD, NotMediaPayloadError, assertMediaPayload, fingerprintElementId, isNotMediaPayload, } from "./utils/notMediaPayload.js";
-export { _setDownloadFetchForTests, assertPublicHttpsUrl, isBlockedNetworkHost, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, } from "./utils/urlDownloader.js";
+export { _setDownloadFetchForTests, assertPublicHttpsUrl, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, } from "./utils/urlDownloader.js";
+export { isBlockedNetworkHost } from "./utils/networkPolicy.js";
 export { runFfmpeg, formatFfmpegError, describeFfmpegFailure, isExternalFfmpegInterruption, } from "./utils/runFfmpeg.js";
 export { aacSegmentCount, encodeAac } from "./services/aacEncode.js";
 export { ManagedChildProcess, } from "./utils/managedChildProcess.js";

package/dist/services/streamingEncoder.d.ts

@@ -68,6 +68,8 @@ export interface StreamingEncoderResult {
     error?: string;
     /** Stable machine-readable cause for failures safe to retry on a fresh host. */
     failureReason?: "external_interruption";
+    /** Total time `writeFrame` waited for FFmpeg to drain its stdin pipe. */
+    drainWaitMs?: number;
 }
 export interface StreamingEncoder {
     /**

package/dist/services/streamingEncoder.js

@@ -376,6 +376,7 @@ export async function spawnStreamingEncoder(outputPath, options, signal, config)
         }
     };
     let inputFrameIndex = 0;
+    let drainWaitMs = 0;
     const encoder = {
         writeFrame: async (buffer) => {
             const stdin = ffmpeg.stdin;
@@ -417,7 +418,9 @@ export async function spawnStreamingEncoder(outputPath, options, signal, config)
                 managed.markActivity();
                 return true;
             }
+            const drainStart = Date.now();
             const drainResult = await waitForDrainOrExit(stdin);
+            drainWaitMs += Date.now() - drainStart;
             if (drainResult !== "drain" || exitStatus !== "running") {
                 return false;
             }
@@ -476,7 +479,7 @@ export async function spawnStreamingEncoder(outputPath, options, signal, config)
                 };
             }
             const fileSize = existsSync(outputPath) ? statSync(outputPath).size : 0;
-            return { success: true, durationMs, fileSize };
+            return { success: true, durationMs, fileSize, drainWaitMs };
         },
         getExitStatus: () => exitStatus,
         getExitError: () => {

package/dist/services/videoFrameExtractor.d.ts

@@ -111,6 +111,10 @@ export interface ExtractionOptions {
     collectProbeFailures?: boolean;
     /** Extract only these runs of output frames, named as a full extraction names them. CFR only. */
     frameRanges?: readonly FrameRange[];
+    onProgress?: (progress: {
+        planned?: number;
+        done?: number;
+    }) => void;
     /** A short decode of a remote source, only to count its frames: it waits on the network, so it runs wider. */
     tailProbe?: boolean;
     /**

package/dist/services/videoFrameExtractor.js

@@ -22,7 +22,7 @@ import { inputAlphaOpaqueWarning, probeInputAlphaPlane } from "../utils/alphaPla
 import { redactUrlQueriesInError, urlInputArgs } from "../utils/urlInput.js";
 import { analyzeCompositionHdr, isHdrColorSpace as isHdrColorSpaceUtil, } from "../utils/hdr.js";
 import { downloadToTemp, isHttpUrl, safeDownloadUrlIdentity, UrlDownloadError, writeUrlDownloadTelemetry, } from "../utils/urlDownloader.js";
-import { runFfmpeg } from "../utils/runFfmpeg.js";
+import { ffmpegStatsReader, runFfmpeg } from "../utils/runFfmpeg.js";
 import { isFfmpegFilterAvailable, isFfmpegHwaccelAvailable, } from "../utils/psnrFilterAvailability.js";
 import { DEFAULT_CONFIG } from "../config.js";
 import { unwrapTemplate } from "../utils/htmlTemplate.js";
@@ -537,6 +537,18 @@ const EXTRACTION_SLOTS = Math.max(1, Math.floor(cpus().length / 2));
 const inExtractionSlot = createConcurrencyLimit(EXTRACTION_SLOTS);
 const TAIL_PROBE_SLOTS = Math.max(1, Number(process.env.HF_TAIL_PROBE_SLOTS) || 16);
 const inTailProbeSlot = createConcurrencyLimit(TAIL_PROBE_SLOTS);
+function framesWrittenReader(onProgress) {
+    if (!onProgress)
+        return undefined;
+    let seen = 0;
+    const read = ffmpegStatsReader(({ frames }) => {
+        if (frames === undefined || frames <= seen)
+            return;
+        onProgress({ done: frames - seen });
+        seen = frames;
+    });
+    return (chunk) => read(chunk);
+}
 /** Split runs so no single ffmpeg process extracts more than `segmentFrames` frames. */
 function splitFrameRanges(ranges, segmentFrames) {
     const segments = [];
@@ -583,6 +595,7 @@ async function runSegmentedExtraction(job) {
             ], {
                 ...job.runOptions,
                 signal,
+                onStderr: framesWrittenReader(job.onProgress),
                 timeout: stallTimeoutMs(job.runOptions.timeout, await leadInSecondsUnlessAborted(videoPath, seek, signal), sourceFps),
             }), signal);
             results[index] = result;
@@ -763,13 +776,20 @@ outputDirOverride) {
             gate: options.tailProbe ? inTailProbeSlot : inExtractionSlot,
             segments: splitFrameRanges(options.frameRanges ?? [{ firstFrame: 0, frames: totalFrames }], segmentFrames),
             runOptions,
+            onProgress: options.onProgress,
         })
         : inExtractionSlot(async () => runFfmpeg([...hwaccel, ...args, ...filterArgsFor(startTime), ...encodeArgs], {
             ...runOptions,
+            onStderr: framesWrittenReader(options.onProgress),
             timeout: stallTimeoutMs(ffmpegProcessTimeout, options.finalFrameOnly
                 ? startTime
                 : await leadInSecondsUnlessAborted(videoPath, startTime, signal), metadata.fps),
         }), signal);
+    options.onProgress?.({
+        planned: options.frameRanges
+            ? options.frameRanges.reduce((sum, range) => sum + range.frames, 0)
+            : totalFrames,
+    });
     let processResult = await extract(decodeWithVideoToolbox ? ["-hwaccel", "videotoolbox"] : []);
     const ffmpegExitedFailing = processResult.terminationReason === "exit" &&
         !processResult.success &&
@@ -885,6 +905,19 @@ const FINAL_FRAME_LOGICAL_DURATION_SECONDS = 1e-6;
 export function isVideoPastTimelineEnd(video, timelineEnd) {
     return video.start >= timelineEnd;
 }
+function alignClipStartToFirstOutputFrame(video, fps) {
+    if (video.loop || !Number.isFinite(video.start) || video.start < 0 || !(fps > 0))
+        return;
+    const position = exportClipWindow(video.start, Infinity, fps).start * fps;
+    const firstFrame = Math.abs(position - Math.round(position)) < 1e-6 ? Math.round(position) : Math.ceil(position);
+    const shift = firstFrame / fps - video.start;
+    if (shift === 0)
+        return;
+    const playbackRate = normalizeRateSpec(video.playbackRate);
+    video.mediaStart += sourceTimeAt(playbackRate, shift);
+    video.playbackRate = shiftRateLane(playbackRate, shift);
+    video.start += shift;
+}
 /** Move a clip to its extraction window; a rate lane is shifted so it keeps integrating from the new origin. */
 export function rebaseVideoToWindow(video, window) {
     if (window.preserveTimelinePhase)
@@ -1732,6 +1765,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
         }
         try {
             const metadata = videoMetadata[index] ?? (await extractMediaMetadata(videoPath));
+            alignClipStartToFirstOutputFrame(video, fps);
             const initialWindow = resolveVideoExtractionWindow(video, metadata, options.timelineEnd);
             const window = await resolveFinalFrameExtractionWindow(videoPath, video, metadata, initialWindow, signal);
             const videoDuration = window.durationSeconds;

package/dist/utils/networkPolicy.d.ts

@@ -0,0 +1,2 @@
+/** Literal-host policy shared by rendering and capture; DNS resolution remains trusted. */
+export declare function isBlockedNetworkHost(hostname: string): boolean;

package/dist/utils/networkPolicy.js

@@ -0,0 +1,53 @@
+import { BlockList, isIP } from "node:net";
+// The one list of special-use networks: asset downloads and the capture proxy both read it, so a site one can reach the other can too.
+const NON_PUBLIC_IPV4_ADDRESSES = new BlockList();
+for (const [network, prefix] of [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10],
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16],
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.0.2.0", 24],
+    ["192.88.99.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["198.51.100.0", 24],
+    ["203.0.113.0", 24],
+    ["224.0.0.0", 4],
+    ["240.0.0.0", 4],
+]) {
+    NON_PUBLIC_IPV4_ADDRESSES.addSubnet(network, prefix, "ipv4");
+}
+const NON_PUBLIC_IPV6_ADDRESSES = new BlockList();
+for (const [network, prefix] of [
+    ["::", 128],
+    ["::1", 128],
+    ["::ffff:0:0", 96],
+    ["fc00::", 7],
+    ["fe80::", 10],
+    ["fec0::", 10],
+    ["ff00::", 8],
+    ["2001:db8::", 32],
+]) {
+    NON_PUBLIC_IPV6_ADDRESSES.addSubnet(network, prefix, "ipv6");
+}
+/** Literal-host policy shared by rendering and capture; DNS resolution remains trusted. */
+export function isBlockedNetworkHost(hostname) {
+    const h = hostname
+        .toLowerCase()
+        .replace(/\.$/, "")
+        .replace(/^\[|\]$/g, "");
+    if (h === "localhost" ||
+        h.endsWith(".localhost") ||
+        h.endsWith(".local") ||
+        h.endsWith(".internal"))
+        return true;
+    const addressType = isIP(h);
+    if (addressType === 0)
+        return false;
+    return addressType === 4
+        ? NON_PUBLIC_IPV4_ADDRESSES.check(h, "ipv4")
+        : NON_PUBLIC_IPV6_ADDRESSES.check(h, "ipv6");
+}

package/dist/utils/urlDownloader.d.ts

@@ -46,8 +46,6 @@ export declare class UrlDownloadError extends Error {
     /** A bounded in-call refetch can be safe even when upstream retry is not. */
     locallyRetryable?: boolean);
 }
-/** Literal-host policy shared by rendering and capture; DNS resolution remains trusted. */
-export declare function isBlockedNetworkHost(hostname: string): boolean;
 /**
  * Validate that a URL is safe to fetch on behalf of customer-supplied
  * compositions. Throws if the URL is non-HTTPS or targets a private/reserved

package/dist/utils/urlDownloader.js

@@ -2,7 +2,7 @@ import { closeSync, createReadStream, createWriteStream, existsSync, fsyncSync,
 import { createHash, randomUUID } from "crypto";
 import dns from "node:dns";
 import { fetchGoesThroughEnvProxy } from "@hyperframes/core/env-proxy";
-import { BlockList, isIP } from "node:net";
+import { isBlockedNetworkHost } from "./networkPolicy.js";
 import { dirname, extname, join } from "path";
 import { Readable, Transform } from "stream";
 import { pipeline } from "stream/promises";
@@ -111,57 +111,6 @@ function isRetryableNetworkCause(error) {
         code.startsWith("UND_ERR_") ||
         /fetch failed|network|socket|connection reset|terminated/i.test(message));
 }
-const NON_PUBLIC_IPV4_ADDRESSES = new BlockList();
-for (const [network, prefix] of [
-    ["0.0.0.0", 8],
-    ["10.0.0.0", 8],
-    ["100.64.0.0", 10],
-    ["127.0.0.0", 8],
-    ["169.254.0.0", 16],
-    ["172.16.0.0", 12],
-    ["192.0.0.0", 24],
-    ["192.0.2.0", 24],
-    ["192.88.99.0", 24],
-    ["192.168.0.0", 16],
-    ["198.18.0.0", 15],
-    ["198.51.100.0", 24],
-    ["203.0.113.0", 24],
-    ["224.0.0.0", 4],
-    ["240.0.0.0", 4],
-]) {
-    NON_PUBLIC_IPV4_ADDRESSES.addSubnet(network, prefix, "ipv4");
-}
-const NON_PUBLIC_IPV6_ADDRESSES = new BlockList();
-for (const [network, prefix] of [
-    ["::", 128],
-    ["::1", 128],
-    ["::ffff:0:0", 96],
-    ["fc00::", 7],
-    ["fe80::", 10],
-    ["fec0::", 10],
-    ["ff00::", 8],
-    ["2001:db8::", 32],
-]) {
-    NON_PUBLIC_IPV6_ADDRESSES.addSubnet(network, prefix, "ipv6");
-}
-/** Literal-host policy shared by rendering and capture; DNS resolution remains trusted. */
-export function isBlockedNetworkHost(hostname) {
-    const h = hostname
-        .toLowerCase()
-        .replace(/\.$/, "")
-        .replace(/^\[|\]$/g, "");
-    if (h === "localhost" ||
-        h.endsWith(".localhost") ||
-        h.endsWith(".local") ||
-        h.endsWith(".internal"))
-        return true;
-    const addressType = isIP(h);
-    if (addressType === 0)
-        return false;
-    return addressType === 4
-        ? NON_PUBLIC_IPV4_ADDRESSES.check(h, "ipv4")
-        : NON_PUBLIC_IPV6_ADDRESSES.check(h, "ipv6");
-}
 /**
  * Validate that a URL is safe to fetch on behalf of customer-supplied
  * compositions. Throws if the URL is non-HTTPS or targets a private/reserved

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.221",
+  "version": "0.8.222",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -43,7 +43,11 @@
       "import": "./dist/utils/shaderTransitions.js",
       "types": "./dist/utils/shaderTransitions.d.ts"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./network-policy": {
+      "import": "./dist/utils/networkPolicy.js",
+      "types": "./dist/utils/networkPolicy.d.ts"
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -55,8 +59,8 @@
     "puppeteer": "~25.11.0",
     "puppeteer-core": "^25.11.0",
     "undici": "7.25.0",
-    "@hyperframes/core": "^0.8.221",
-    "@hyperframes/parsers": "^0.8.221"
+    "@hyperframes/core": "^0.8.222",
+    "@hyperframes/parsers": "^0.8.222"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",