@hyperframes/engine 0.9.15 → 0.9.17

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` +
@@ -1753,8 +1761,8 @@ export function recordSubTimelineWarning(session, timeoutMs) {
                     `${pendingSuffix} (${sources.join(", ")}). Fix the error; a composition animated by ` +
                     `CSS or rAF rather than a GSAP timeline must mark its host with data-no-timeline.`
                 : scriptFailure
-                    ? `A sub-composition timeline script failed to load (${sources.join(", ")})` +
-                        scriptLoadCauseSuffix(loadCauses)
+                    ? `A sub-composition timeline script failed to load${scriptLoadCauseSuffix(loadCauses)} ` +
+                        `(${sources.join(", ")})`
                     : `Sub-composition timelines did not become ready within ${timeoutMs}ms${pendingSuffix}. ` +
                         `This can be intentional: a composition driven by CSS animations or rAF never registers ` +
                         `window.__timelines[id], and marking its host with data-no-timeline skips the wait entirely. ` +

package/dist/services/videoFrameExtractor.js

@@ -15,7 +15,7 @@ import { HF_COLOR_GRADING_ATTR } from "@hyperframes/core";
 import { isPathInside } from "@hyperframes/parsers/asset-paths";
 import { resolveProjectRelativeSrc } from "@hyperframes/parsers/asset-resolution";
 import { alphaDecoderFor } from "@hyperframes/parsers/media-alpha";
-import { MEDIA_RENDER_ID_ATTR, isAudibleVideoElement, fpsToFfmpegArg, fpsToNumber, MEDIA_DURATION_CLAMP_EPSILON_SECONDS, normalizeRateSpec, readElementRateSpec, shiftRateLane, sourceTimeAt, timeAtSourceTime, exportClipWindow, hasClipStarted, isInClipWindow, mediaElementTime, parseStrictFiniteTimingNumber, readMediaStart, toFps, firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, } from "@hyperframes/core";
+import { MEDIA_RENDER_ID_ATTR, isAudibleVideoElement, fpsToFfmpegArg, fpsToNumber, MEDIA_DURATION_CLAMP_EPSILON_SECONDS, normalizeRateSpec, readElementRateSpec, shiftRateLane, sourceTimeAt, timeAtSourceTime, exportClipWindow, hasClipStarted, isInClipWindow, mediaElementTime, parseStrictFiniteTimingNumber, readMediaStart, toFps, firstFrameColourArgs, keyframeTransferArgs, parseKeyframeTransfers, hdrToSdrToneMapFilter, parseFirstFrameColour, readsKeyframeTransfers, } from "@hyperframes/core";
 import { resolveReferencedStart } from "./referenceResolver.js";
 import { isKnownInactiveTimelineWindow } from "./mediaTimelineWindow.js";
 import { extractFinalVideoFrameTimestamp, extractMediaMetadata, ffmpegSeekSeconds, formatFfmpegSeconds, keyframeGapSeconds, mediaFileIdentity, readMetadataCache, readStoredFinalFrame, resolvePlayableVideoDuration, videoStartOnMediaTimeline, writeMetadataCache, } from "../utils/ffprobe.js";
@@ -506,19 +506,32 @@ export function parseImageElements(html) {
     return images;
 }
 const firstFrameColourCache = new Map();
+/** A source's SPS transfers, so a PQ or SDR keyframe keeps an HLG one at 100 nits; null when the read failed. */
+function readKeyframeTransfers(videoPath, codec) {
+    return inExtractionSlot(() => runFfmpeg([...urlInputArgs(videoPath), ...keyframeTransferArgs(videoPath, codec)])).then((result) => (result.success ? parseKeyframeTransfers(result.stderr) : null));
+}
 /** The first shown frame's colour tags (see {@link firstFrameColourArgs}), probed once per source file. */
-function readFirstFrameColour(videoPath) {
+function readFirstFrameColour(videoPath, codec) {
     const identity = mediaFileIdentity(videoPath);
     const cached = readMetadataCache(firstFrameColourCache, videoPath, identity);
     if (cached)
         return cached;
     // In an extraction slot, so it never adds a decoder; unsignalled, so one cancel cannot cut it short for others.
-    const probe = inExtractionSlot(() => runFfmpeg([...urlInputArgs(videoPath), ...firstFrameColourArgs(videoPath)])).then((result) => {
+    const probe = inExtractionSlot(() => runFfmpeg([...urlInputArgs(videoPath), ...firstFrameColourArgs(videoPath)])).then(async (result) => {
+        const forget = () => {
+            if (firstFrameColourCache.get(videoPath)?.promise === probe)
+                firstFrameColourCache.delete(videoPath);
+        };
         // A failed probe answers this cut only; the next one probes again.
-        if (!result.success && firstFrameColourCache.get(videoPath)?.promise === probe) {
-            firstFrameColourCache.delete(videoPath);
-        }
-        return parseFirstFrameColour(result.stderr);
+        if (!result.success)
+            forget();
+        const first = parseFirstFrameColour(result.stderr);
+        if (!result.success || !readsKeyframeTransfers(first))
+            return first;
+        const keyframeTransfers = await readKeyframeTransfers(videoPath, codec);
+        if (!keyframeTransfers)
+            forget();
+        return { ...first, keyframeTransfers: keyframeTransfers ?? [] };
     });
     writeMetadataCache(firstFrameColourCache, videoPath, identity, probe);
     return probe;
@@ -822,7 +835,9 @@ outputDirOverride) {
             args.push("-noaccurate_seek");
         args.push("-ss", formatFfmpegSeconds(ffmpegSeek(startTime)), "-i", videoPath, "-t", formatFfmpegSeconds(duration));
     }
-    const frameColour = toneMappedToSdr ? await readFirstFrameColour(videoPath) : undefined;
+    const frameColour = toneMappedToSdr
+        ? await readFirstFrameColour(videoPath, metadata.videoCodec)
+        : undefined;
     const filtersFor = videoFilterChain({
         metadata,
         format,

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.17",
   "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.17",
+    "@hyperframes/parsers": "^0.9.17"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",