@hyperframes/engine 0.9.15 → 0.9.16

package/dist/index.d.ts

@@ -72,7 +72,7 @@ export type { PageMotionBlurOff } from "./types.js";
 export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js";
 export { isBrowserSafePort, listenOnBrowserSafePort, settleOnBrowserSafePort, } from "./utils/browserSafePort.js";
 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 { extractMediaMetadata, displaySize, 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, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, type SafeDownloadUrlIdentity, type UrlDownloadOptions, type UrlDownloadTelemetry, type PublicHttpsTextOptions, } from "./utils/urlDownloader.js";
 export { isBlockedNetworkHost } from "./utils/networkPolicy.js";

package/dist/index.js

@@ -76,7 +76,7 @@ export { frameSequencePath } from "./services/extractedFrameIndex.js";
 export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js";
 export { isBrowserSafePort, listenOnBrowserSafePort, settleOnBrowserSafePort, } from "./utils/browserSafePort.js";
 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 { extractMediaMetadata, displaySize, 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, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, } from "./utils/urlDownloader.js";
 export { isBlockedNetworkHost } from "./utils/networkPolicy.js";

package/dist/services/captureFailure.js

@@ -27,6 +27,7 @@ const TRANSIENT_BROWSER_ERROR_PATTERNS = [
     /ECONNREFUSED/i,
     /net::ERR_NETWORK_CHANGED/i,
     /Composition has zero duration[\s\S]*Runtime ready: false/,
+    /Composition setup did not finish/,
     // CDP can refuse a capture call outright with this exact wording; timed-out
     // variants of the same call hit PROTOCOL_TIMEOUT_PATTERNS, checked first.
     // Anchored to this literal reason (not just the CDP method) so an unrelated,

package/dist/services/frameCapture.d.ts

@@ -427,7 +427,7 @@ export interface HfDiagnostic {
     pendingBuildReadyKeys: string[];
     rejectedBuildReadyKeys: string[];
 }
-export declare function buildZeroDurationDiagnostic(diag: HfDiagnostic): string;
+export declare function buildZeroDurationDiagnostic(diag: HfDiagnostic, timeoutMs?: number): string;
 export declare function evaluateHfDiagnostic(page: Page): Promise<HfDiagnostic>;
 export declare function pollHfReady(page: Page, timeoutMs: number, intervalMs?: number): Promise<void>;
 export declare function waitForSubCompositionTimelines(session: CaptureSession, page: Page, timeoutMs: number, options?: {

package/dist/services/frameCapture.js

@@ -1217,12 +1217,16 @@ export const HF_READY_DIAGNOSTIC_EXPR = `(async function() {
   };
 })()`;
 // fallow-ignore-next-line complexity
-export function buildZeroDurationDiagnostic(diag) {
+export function buildZeroDurationDiagnostic(diag, timeoutMs) {
     const hints = [];
     if (diag.pendingBuildReadyKeys.length > 0) {
         hints.push(`window.__hf.buildReady never resolved for: ${diag.pendingBuildReadyKeys.join(", ")}. ` +
             "The runtime holds render-ready until every registered buildReady promise settles. " +
-            "Find where the composition registers that key and confirm it actually resolves.");
+            "Find where the composition registers that key and confirm it actually resolves. " +
+            "During a render, Date and performance.now stay at 0 and requestAnimationFrame " +
+            "callbacks wait until the first frame, so setup that awaits an animation frame or " +
+            "the clock never finishes. Await the library's own readiness promise instead (for " +
+            "Three.js, renderer.compileAsync).");
     }
     if (diag.rejectedBuildReadyKeys.length > 0) {
         hints.push(`window.__hf.buildReady rejected for: ${diag.rejectedBuildReadyKeys.join(", ")}. ` +
@@ -1231,7 +1235,7 @@ export function buildZeroDurationDiagnostic(diag) {
     if (!diag.hasPlayer) {
         hints.push("window.__player was never set: the HyperFrames runtime did not initialize.");
     }
-    if (!diag.hasTimeline) {
+    if (diag.renderReady && !diag.hasTimeline) {
         hints.push("No GSAP timeline registered (window.__timelines is empty). " +
             "CSS/WAAPI/Lottie animations are usually auto-detected (the runtime infers " +
             "duration from the longest running animation), but this composition's duration " +
@@ -1245,7 +1249,11 @@ export function buildZeroDurationDiagnostic(diag) {
     if (diag.hasSeek && diag.duration === 0 && diag.renderReady) {
         hints.push("The runtime finished initializing but reported zero duration. This is permanent.");
     }
-    return (`[FrameCapture] Composition has zero duration.\n` +
+    const within = timeoutMs === undefined ? "" : ` within ${timeoutMs}ms`;
+    const headline = diag.renderReady
+        ? "Composition has zero duration."
+        : `Composition setup did not finish${within}.`;
+    return (`[FrameCapture] ${headline}\n` +
         `  Runtime ready: ${diag.renderReady}, __player: ${diag.hasPlayer}, ` +
         `__hf.seek: ${diag.hasSeek}, GSAP timeline: ${diag.hasTimeline}, ` +
         `data-duration: ${diag.declaredDuration > 0 ? diag.declaredDuration + "s" : "not set"}\n` +
@@ -1301,7 +1309,7 @@ export async function pollHfReady(page, timeoutMs, intervalMs = 100) {
     }
     const diag = await evaluateHfDiagnostic(page);
     if (diag.hasSeek && diag.duration === 0) {
-        throw new Error(buildZeroDurationDiagnostic(diag));
+        throw new Error(buildZeroDurationDiagnostic(diag, timeoutMs));
     }
     throw new Error(`[FrameCapture] window.__hf not ready after ${timeoutMs}ms. ` +
         `Page must expose window.__hf = { duration, seek }.\n` +

package/dist/utils/ffprobe.d.ts

@@ -43,6 +43,7 @@ export interface VideoMetadata {
     colorRange?: string;
     pixelFormat?: string;
     sampleAspectRatio?: number;
+    rotation?: number;
     /** Decoded frame count from the video stream's `nb_frames`. Omitted when the
      * container does not surface a reliable count (still images, malformed
      * streams, or muxes that require `-count_packets` to populate). Callers
@@ -90,6 +91,9 @@ interface FFProbeStream {
     color_primaries?: string;
     color_space?: string;
     tags?: Record<string, string>;
+    side_data_list?: {
+        rotation?: number;
+    }[];
     disposition?: {
         attached_pic?: number;
     };
@@ -172,6 +176,10 @@ export declare function readTagCI(tags: Record<string, string | undefined> | und
  *    smallest representable 2dp rate instead.
  */
 export declare function parseFrameRate(frameRateStr: string | undefined): number;
+export declare function displaySize(metadata: Pick<VideoMetadata, "width" | "height" | "sampleAspectRatio" | "rotation">): {
+    width: number;
+    height: number;
+};
 export declare function parseSampleAspectRatio(value: string | undefined): number | undefined;
 /**
  * Whether the first frame decoded with `decoder` (alpha-aware) has an alpha pixel format; undefined on any

package/dist/utils/ffprobe.js

@@ -637,6 +637,18 @@ export function parseFrameRate(frameRateStr) {
     // caller's 30fps default.
     return rounded > 0 ? rounded : 0.01;
 }
+function displayRotation(stream) {
+    const turn = Number(stream.side_data_list?.find((data) => data.rotation !== undefined)?.rotation ??
+        stream.tags?.rotate ??
+        0);
+    return Number.isFinite(turn) && turn % 360 !== 0 ? { rotation: turn } : {};
+}
+export function displaySize(metadata) {
+    const width = Math.round(metadata.width * (metadata.sampleAspectRatio ?? 1));
+    return Math.abs(metadata.rotation ?? 0) % 180 === 90
+        ? { width: metadata.height, height: width }
+        : { width, height: metadata.height };
+}
 export function parseSampleAspectRatio(value) {
     const [num, den] = (value ?? "").split(":").map(Number);
     if (!num || !den || !Number.isFinite(num) || !Number.isFinite(den))
@@ -777,8 +789,12 @@ export async function extractMediaMetadata(filePath) {
         const alphaPlaneDecoded = alphaDecoder
             ? await probeDecodedAlphaPlane(filePath, alphaDecoder)
             : undefined;
-        const containerDuration = output?.format.duration ? parseFloat(output.format.duration) : 0;
+        let containerDuration = output?.format.duration ? parseFloat(output.format.duration) : 0;
         const streamDuration = videoStream.duration ? parseFloat(videoStream.duration) : 0;
+        // Recorder output (WebM/Matroska written to a pipe) carries no duration header: read it off the packets.
+        if (!(containerDuration > 0) && !(streamDuration > 0) && !isPng) {
+            containerDuration = (await scanPacketDuration(filePath, fps)) ?? 0;
+        }
         const parsedStreamStart = videoStream.start_time ? parseFloat(videoStream.start_time) : 0;
         const streamStart = Number.isFinite(parsedStreamStart) ? parsedStreamStart : 0;
         // `nb_frames` is populated by the container demuxer; a muxer that requires
@@ -825,6 +841,7 @@ export async function extractMediaMetadata(filePath) {
             colorRange: videoStream.color_range,
             pixelFormat,
             ...(sampleAspectRatio === undefined ? {} : { sampleAspectRatio }),
+            ...displayRotation(videoStream),
             frames,
         };
     })();
@@ -857,6 +874,30 @@ export function readStoredFinalFrame(filePath, metadata) {
             : undefined;
     });
 }
+const PACKET_TAIL_CHARS = 64 * 1024;
+/** The video stream's length from its packets (last end time), for a file whose headers state none. */
+async function scanPacketDuration(filePath, fps) {
+    try {
+        const stdout = await runFfprobe(filePath, [
+            ...["-select_streams", "v:0", "-show_entries", "packet=pts_time,duration_time"],
+            ...["-of", "csv=p=0"],
+        ], undefined, { retainTail: true, maxChars: PACKET_TAIL_CHARS });
+        const lines = stdout.split("\n");
+        // A tail cut at the cap starts partway through a line, and its number would read as a huge time.
+        if (stdout.length >= PACKET_TAIL_CHARS)
+            lines.shift();
+        const frame = fps > 0 ? 1 / fps : 0;
+        const ends = lines
+            .map((line) => line.trim().split(",").map(Number))
+            .filter(([pts]) => Number.isFinite(pts))
+            .map(([pts, duration]) => pts + (Number.isFinite(duration) ? duration : frame));
+        return ends.length ? Math.max(...ends) : undefined;
+    }
+    catch {
+        // expected: a file ffprobe cannot scan keeps its "no duration" verdict.
+        return undefined;
+    }
+}
 /**
  * `duration_time` of the stream's last packet (by presentation time), read from the same final
  * second the final-frame probe reads; undefined when ffprobe reports none.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.9.15",
+  "version": "0.9.16",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -61,8 +61,8 @@
     "puppeteer": "~25.11.0",
     "puppeteer-core": "^25.11.0",
     "undici": "7.25.0",
-    "@hyperframes/core": "^0.9.15",
-    "@hyperframes/parsers": "^0.9.15"
+    "@hyperframes/core": "^0.9.16",
+    "@hyperframes/parsers": "^0.9.16"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",