@hyperframes/engine 0.8.224 → 0.8.225

package/dist/services/audioMixer.js

@@ -5,7 +5,7 @@ import { renameWithRetry } from "@hyperframes/core/rename-retry";
 import { removeScratch } from "@hyperframes/core/remove-scratch";
 import { join, dirname, isAbsolute, relative } from "path";
 import { parseHTML } from "linkedom";
-import { extractAudioMetadata, ffmpegSeekSeconds } from "../utils/ffprobe.js";
+import { extractAudioMetadata, ffmpegSeekSeconds, formatFfmpegSeconds, } from "../utils/ffprobe.js";
 import { isNotMediaPayload } from "../utils/notMediaPayload.js";
 import { urlInputArgs } from "../utils/urlInput.js";
 import { clampAudioGain, clipGain } from "@hyperframes/core/audio-gain";
@@ -550,7 +550,7 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
                 "-stream_loop",
                 "-1",
                 "-t",
-                String(sourceDuration),
+                formatFfmpegSeconds(sourceDuration),
                 "-i",
                 cyclePath,
                 "-vn",
@@ -560,7 +560,7 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
                 "48000",
                 ...outputArgs,
                 "-t",
-                String(duration),
+                formatFfmpegSeconds(duration),
                 "-y",
                 outputPath,
             ], { signal, timeout: ffmpegProcessTimeout });
@@ -598,14 +598,19 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
         ...(readsUrl ? FAIL_ON_READ_ERROR_INSTEAD_OF_ENDING_THERE : []),
         ...urlInputArgs(readFrom),
         ...(inputSeek
-            ? ["-ss", String(ffmpegStart - warmUp), "-t", String(sourceDuration + warmUp)]
+            ? [
+                "-ss",
+                formatFfmpegSeconds(ffmpegStart - warmUp),
+                "-t",
+                formatFfmpegSeconds(sourceDuration + warmUp),
+            ]
             : []),
         "-i",
         readFrom,
     ];
     args.push("-vn", "-acodec", "pcm_s16le", "-ar", "48000", ...outputArgs);
     if (normalizedPlaybackRate !== 1 || options?.padToDuration)
-        args.push("-t", String(duration));
+        args.push("-t", formatFfmpegSeconds(duration));
     args.push("-y", outputPath);
     const result = await runFfmpeg(args, { signal, timeout: ffmpegProcessTimeout });
     if (signal?.aborted) {
@@ -660,7 +665,7 @@ async function generateSilence(outputPath, duration, signal, config) {
         "-i",
         "anullsrc=r=48000:cl=stereo",
         "-t",
-        String(duration),
+        formatFfmpegSeconds(duration),
         "-acodec",
         "pcm_s16le",
         "-y",
@@ -761,7 +766,7 @@ async function mixAudioTracksFlat(tracks, outputPath, totalDuration, signal, con
             "-ar",
             "48000",
             "-t",
-            String(totalDuration),
+            formatFfmpegSeconds(totalDuration),
             "-y",
             outputPath,
         ];
@@ -923,7 +928,7 @@ async function mixGroupMembersFlat(memberTracks, outputPath, totalDuration, sign
                 "-ar",
                 "48000",
                 "-t",
-                String(totalDuration),
+                formatFfmpegSeconds(totalDuration),
                 "-y",
                 outputPath,
             ];

package/dist/services/videoFrameExtractor.d.ts

@@ -313,6 +313,7 @@ export interface TimelineExtractionWindow {
 }
 type TimelineWindowVideo = Pick<VideoElement, "start" | "end" | "mediaStart"> & Partial<Pick<VideoElement, "playbackRate">> & Partial<Pick<VideoElement, "loop">>;
 export declare function isVideoPastTimelineEnd(video: Pick<VideoElement, "start">, timelineEnd: number): boolean;
+export declare function alignClipStartToFirstOutputFrame(video: VideoElement, fps: number): void;
 /** Move a clip to its extraction window; a rate lane is shifted so it keeps integrating from the new origin. */
 export declare function rebaseVideoToWindow(video: VideoElement, window: TimelineExtractionWindow): void;
 /**

package/dist/services/videoFrameExtractor.js

@@ -18,7 +18,7 @@ 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 { resolveReferencedStart } from "./referenceResolver.js";
 import { isKnownInactiveTimelineWindow } from "./mediaTimelineWindow.js";
-import { extractFinalVideoFrameTimestamp, extractMediaMetadata, ffmpegSeekSeconds, keyframeGapSeconds, mediaFileIdentity, readMetadataCache, readStoredFinalFrame, resolvePlayableVideoDuration, videoStartOnMediaTimeline, writeMetadataCache, } from "../utils/ffprobe.js";
+import { extractFinalVideoFrameTimestamp, extractMediaMetadata, ffmpegSeekSeconds, formatFfmpegSeconds, keyframeGapSeconds, mediaFileIdentity, readMetadataCache, readStoredFinalFrame, resolvePlayableVideoDuration, videoStartOnMediaTimeline, writeMetadataCache, } from "../utils/ffprobe.js";
 import { inputAlphaOpaqueWarning, probeInputAlphaPlane } from "../utils/alphaPlaneProbe.js";
 import { redactUrlQueriesInError, urlInputArgs } from "../utils/urlInput.js";
 import { analyzeCompositionHdr, isHdrColorSpace as isHdrColorSpaceUtil, } from "../utils/hdr.js";
@@ -593,12 +593,12 @@ async function runSegmentedExtraction(job) {
                 ...decodeArgs,
                 "-noaccurate_seek",
                 "-ss",
-                String(job.ffmpegSeek(seek)),
+                formatFfmpegSeconds(job.ffmpegSeek(seek)),
                 "-i",
                 videoPath,
                 // Read one frame past the segment and keep exactly its own frames.
                 "-t",
-                String((frames + 1) / fps),
+                formatFfmpegSeconds((frames + 1) / fps),
                 "-frames:v",
                 String(frames),
                 "-start_number",
@@ -709,13 +709,13 @@ outputDirOverride) {
         // sample. This is intentionally reserved for the one-frame path: input
         // seeking is faster, but valid unindexed transports (notably MPEG-TS with
         // a negative timestamp base) can seek to EOF and emit zero frames.
-        args.push("-i", videoPath, "-ss", String(Math.max(0, ffmpegSeek(startTime))), "-frames:v", "1");
+        args.push("-i", videoPath, "-ss", formatFfmpegSeconds(Math.max(0, ffmpegSeek(startTime))), "-frames:v", "1");
     }
     else {
         // An accurate seek drops the frame on screen at startTime; the fps sampling below needs it.
         if (sampleAtOutputFps)
             args.push("-noaccurate_seek");
-        args.push("-ss", String(ffmpegSeek(startTime)), "-i", videoPath, "-t", String(duration));
+        args.push("-ss", formatFfmpegSeconds(ffmpegSeek(startTime)), "-i", videoPath, "-t", formatFfmpegSeconds(duration));
     }
     const vfFilters = [];
     if (keepsHdrForChrome) {
@@ -917,14 +917,17 @@ const FINAL_FRAME_LOGICAL_DURATION_SECONDS = 1e-6;
 export function isVideoPastTimelineEnd(video, timelineEnd) {
     return video.start >= timelineEnd;
 }
-function alignClipStartToFirstOutputFrame(video, fps) {
+export 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)
+    // Float dust (a sum landing a hair off the grid) snaps the start; it never reaches mediaStart.
+    if (Math.abs(shift) < 1e-9) {
+        video.start = firstFrame / fps;
         return;
+    }
     const playbackRate = normalizeRateSpec(video.playbackRate);
     video.mediaStart += sourceTimeAt(playbackRate, shift);
     video.playbackRate = shiftRateLane(playbackRate, shift);

package/dist/utils/ffprobe.d.ts

@@ -128,6 +128,7 @@ export declare function readProbeJson(filePath: string, signal?: AbortSignal): P
 /** What a site stores beside a video: its ffprobe JSON and the final-frame facts a plan would otherwise probe for. */
 export declare function buildProbeFactsText(filePath: string, signal?: AbortSignal): Promise<string>;
 export declare function videoStartOnMediaTimeline(metadata: Pick<VideoMetadata, "videoStreamLeadSeconds" | "mediaTimeOffsetSeconds">): number;
+export declare function formatFfmpegSeconds(seconds: number): string;
 export declare function ffmpegSeekSeconds(metadata: Pick<VideoMetadata, "mediaTimeOffsetSeconds">, mediaTime: number): number;
 export declare function resolvePlayableVideoDuration(metadata: VideoMetadata): number;
 /**

package/dist/utils/ffprobe.js

@@ -336,6 +336,10 @@ export async function buildProbeFactsText(filePath, signal) {
 export function videoStartOnMediaTimeline(metadata) {
     return (metadata.videoStreamLeadSeconds ?? 0) + (metadata.mediaTimeOffsetSeconds ?? 0);
 }
+export function formatFfmpegSeconds(seconds) {
+    const text = String(seconds);
+    return text.includes("e") ? String(+seconds.toFixed(6)) : text;
+}
 export function ffmpegSeekSeconds(metadata, mediaTime) {
     return mediaTime - (metadata.mediaTimeOffsetSeconds ?? 0);
 }
@@ -860,7 +864,7 @@ async function extractFinalPacketDuration(filePath, window, signal) {
         "-select_streams",
         "v:0",
         "-read_intervals",
-        `${intervalStart}%${streamEnd}`,
+        `${formatFfmpegSeconds(intervalStart)}%${formatFfmpegSeconds(streamEnd)}`,
         "-show_entries",
         "packet=pts_time,duration_time",
         "-of",
@@ -939,7 +943,8 @@ export async function extractFinalVideoFrameTimestamp(filePath, metadata, signal
             });
             return parseFinalTimestamp(stdout);
         };
-        const timestamp = (await probe(`${intervalStart}%${streamEnd}`)) ?? (await probe( /* full scan */));
+        const timestamp = (await probe(`${formatFfmpegSeconds(intervalStart)}%${formatFfmpegSeconds(streamEnd)}`)) ??
+            (await probe( /* full scan */));
         if (timestamp === undefined) {
             throw new Error("[FFmpeg] ffprobe found no decodable final video frame");
         }
@@ -1114,7 +1119,7 @@ export async function analyzeKeyframeIntervals(filePath, metadata) {
 export async function keyframeGapSeconds(filePath, seekSeconds, signal) {
     const stdout = await runFfprobe(filePath, [
         ...["-select_streams", "v:0", "-show_entries", "packet=pts_time", "-of", "csv=p=0"],
-        ...["-read_intervals", `${seekSeconds}%+#1`],
+        ...["-read_intervals", `${formatFfmpegSeconds(seekSeconds)}%+#1`],
     ], signal);
     const keyframe = parseFloat(stdout.split("\n")[0] ?? "");
     return Number.isFinite(keyframe) ? Math.max(0, seekSeconds - keyframe) : 0;

package/package.json

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