@editframe/assets 0.16.7-beta.0 → 0.17.6-beta.0

package/dist/SeekStrategy.d.ts

@@ -0,0 +1,82 @@
+import type * as MP4Box from "mp4box";
+/**
+ * Interface for the minimal FrameBuffer API needed by SeekStrategy
+ */
+interface FrameBufferLike {
+    findByTimestamp(timestamp: number): VideoFrame | undefined;
+}
+/**
+ * State information needed for seeking decisions
+ */
+export interface SeekState {
+    /** Current position in the samples array for decoding */
+    sampleCursor: number;
+    /** Position of the last successfully decoded frame output */
+    outCursor: number;
+    /** Optional frame buffer for checking cached frames */
+    frameBuffer?: FrameBufferLike;
+}
+/**
+ * SeekStrategy encapsulates the critical seeking decision logic extracted from VideoAsset.
+ *
+ * **CRITICAL**: This class preserves the exact seeking behavior and decoder flush conditions
+ * from the original VideoAsset implementation to maintain "warm" decoder state performance.
+ *
+ * The logic here directly controls when the decoder must be flushed, which is the most
+ * performance-critical aspect of frame-accurate seeking.
+ */
+export declare class SeekStrategy {
+    /**
+     * Determines if seeking will skip picture groups (GOPs), requiring a decoder flush.
+     *
+     * This is an EXACT extraction of the original `seekingWillSkipPictureGroup` logic.
+     *
+     * @param state Current seek state with cursor positions
+     * @param targetSample The sample we want to seek to
+     * @param allSamples All samples in display order
+     * @returns true if seeking will cross more than one sync frame (GOP boundary)
+     */
+    seekingWillSkipPictureGroup(state: SeekState, targetSample: MP4Box.Sample, allSamples: MP4Box.Sample[]): boolean;
+    /**
+     * Determines if seeking will go backwards in time, requiring a decoder flush.
+     *
+     * This is an EXACT extraction of the original `seekingWillGoBackwards` logic.
+     *
+     * @param state Current seek state with cursor positions and frame buffer
+     * @param targetSample The sample we want to seek to
+     * @param displayOrderedSamples Samples sorted by composition timestamp
+     * @returns true if seeking backwards and target frame is not cached
+     */
+    seekingWillGoBackwards(state: SeekState, targetSample: MP4Box.Sample, displayOrderedSamples: MP4Box.Sample[]): boolean;
+    /**
+     * Finds the sync sample at or before the target sample number.
+     *
+     * This is an EXACT extraction of the sync sample finding logic from the original
+     * `seekToTime` method. Used when decoder flush is required to find optimal restart point.
+     *
+     * @param targetSample The sample we want to seek to
+     * @param allSamples All samples in the video
+     * @returns The sample number of the sync frame to start decoding from
+     * @throws Error if no sync sample found when traversing backwards
+     */
+    findSyncSampleBefore(targetSample: MP4Box.Sample, allSamples: MP4Box.Sample[]): number;
+    /**
+     * The master decision function that determines if the decoder should be flushed.
+     *
+     * This consolidates the EXACT flush decision logic from the original VideoAsset.seekToTime().
+     * The decoder is flushed ONLY when:
+     * 1. Seeking will skip picture groups (crosses multiple GOP boundaries), OR
+     * 2. Seeking backwards and target frame is not in cache
+     *
+     * **CRITICAL**: This preserves the sophisticated flush minimization that keeps
+     * the decoder "warm" for optimal performance.
+     *
+     * @param state Current seek state
+     * @param targetSample The sample we want to seek to
+     * @param allSamples All samples in the video
+     * @param displayOrderedSamples Samples sorted by composition timestamp
+     * @returns true if decoder should be flushed before seeking
+     */
+    shouldFlushDecoder(state: SeekState, targetSample: MP4Box.Sample, allSamples: MP4Box.Sample[], displayOrderedSamples?: MP4Box.Sample[]): boolean;
+}
+export {};

package/dist/SeekStrategy.js

@@ -0,0 +1,101 @@
+/**
+* SeekStrategy encapsulates the critical seeking decision logic extracted from VideoAsset.
+* 
+* **CRITICAL**: This class preserves the exact seeking behavior and decoder flush conditions
+* from the original VideoAsset implementation to maintain "warm" decoder state performance.
+* 
+* The logic here directly controls when the decoder must be flushed, which is the most
+* performance-critical aspect of frame-accurate seeking.
+*/
+var SeekStrategy = class {
+	/**
+	* Determines if seeking will skip picture groups (GOPs), requiring a decoder flush.
+	* 
+	* This is an EXACT extraction of the original `seekingWillSkipPictureGroup` logic.
+	* 
+	* @param state Current seek state with cursor positions
+	* @param targetSample The sample we want to seek to
+	* @param allSamples All samples in display order
+	* @returns true if seeking will cross more than one sync frame (GOP boundary)
+	*/
+	seekingWillSkipPictureGroup(state, targetSample, allSamples) {
+		let start = state.sampleCursor;
+		const end = targetSample.number;
+		let syncFrameCrossings = 0;
+		while (start <= end) {
+			const sample = allSamples[start];
+			if (!sample) break;
+			if (sample.is_sync) {
+				if (syncFrameCrossings > 1) return true;
+				syncFrameCrossings++;
+			}
+			start++;
+		}
+		return false;
+	}
+	/**
+	* Determines if seeking will go backwards in time, requiring a decoder flush.
+	* 
+	* This is an EXACT extraction of the original `seekingWillGoBackwards` logic.
+	* 
+	* @param state Current seek state with cursor positions and frame buffer
+	* @param targetSample The sample we want to seek to  
+	* @param displayOrderedSamples Samples sorted by composition timestamp
+	* @returns true if seeking backwards and target frame is not cached
+	*/
+	seekingWillGoBackwards(state, targetSample, displayOrderedSamples) {
+		const targetIndex = displayOrderedSamples.indexOf(targetSample);
+		const targetInCache = state.frameBuffer?.findByTimestamp(targetSample.cts);
+		const atEnd = state.sampleCursor === displayOrderedSamples.length - 1;
+		if (atEnd) return false;
+		if (targetInCache) return false;
+		return state.outCursor > targetIndex;
+	}
+	/**
+	* Finds the sync sample at or before the target sample number.
+	* 
+	* This is an EXACT extraction of the sync sample finding logic from the original
+	* `seekToTime` method. Used when decoder flush is required to find optimal restart point.
+	* 
+	* @param targetSample The sample we want to seek to
+	* @param allSamples All samples in the video
+	* @returns The sample number of the sync frame to start decoding from
+	* @throws Error if no sync sample found when traversing backwards
+	*/
+	findSyncSampleBefore(targetSample, allSamples) {
+		let syncSampleNumber = targetSample.number;
+		while (syncSampleNumber >= 0) {
+			const sample = allSamples[syncSampleNumber];
+			if (!sample) break;
+			if (sample.is_sync) return syncSampleNumber;
+			syncSampleNumber--;
+		}
+		throw new Error("No sync sample found when traversing backwards");
+	}
+	/**
+	* The master decision function that determines if the decoder should be flushed.
+	* 
+	* This consolidates the EXACT flush decision logic from the original VideoAsset.seekToTime().
+	* The decoder is flushed ONLY when:
+	* 1. Seeking will skip picture groups (crosses multiple GOP boundaries), OR
+	* 2. Seeking backwards and target frame is not in cache
+	* 
+	* **CRITICAL**: This preserves the sophisticated flush minimization that keeps
+	* the decoder "warm" for optimal performance.
+	* 
+	* @param state Current seek state
+	* @param targetSample The sample we want to seek to
+	* @param allSamples All samples in the video
+	* @param displayOrderedSamples Samples sorted by composition timestamp  
+	* @returns true if decoder should be flushed before seeking
+	*/
+	shouldFlushDecoder(state, targetSample, allSamples, displayOrderedSamples) {
+		const targetInCache = state.frameBuffer?.findByTimestamp(targetSample.cts);
+		if (targetInCache) return false;
+		const orderedSamples = displayOrderedSamples || allSamples;
+		if (this.seekingWillSkipPictureGroup(state, targetSample, allSamples)) return true;
+		if (this.seekingWillGoBackwards(state, targetSample, orderedSamples)) return true;
+		return false;
+	}
+};
+export { SeekStrategy };

package/dist/VideoRenderOptions.js

@@ -1,36 +1,34 @@
 import { z } from "zod";
 const VideoRenderOptions = z.object({
-  mode: z.enum(["canvas", "screenshot"]),
-  strategy: z.enum(["v1", "v2"]),
-  showFrameBox: z.boolean().optional(),
-  encoderOptions: z.object({
-    sequenceNumber: z.number(),
-    keyframeIntervalMs: z.number(),
-    toMs: z.number(),
-    fromMs: z.number(),
-    shouldPadStart: z.boolean(),
-    shouldPadEnd: z.boolean(),
-    alignedFromUs: z.number(),
-    alignedToUs: z.number(),
-    isInitSegment: z.boolean(),
-    noVideo: z.boolean().optional(),
-    noAudio: z.boolean().optional(),
-    video: z.object({
-      width: z.number(),
-      height: z.number(),
-      framerate: z.number(),
-      codec: z.string(),
-      bitrate: z.number()
-    }),
-    audio: z.object({
-      sampleRate: z.number(),
-      codec: z.string(),
-      numberOfChannels: z.number(),
-      bitrate: z.number()
-    })
-  }),
-  fetchHost: z.string()
+	mode: z.enum(["canvas", "screenshot"]),
+	strategy: z.enum(["v1", "v2"]),
+	showFrameBox: z.boolean().optional(),
+	encoderOptions: z.object({
+		sequenceNumber: z.number(),
+		keyframeIntervalMs: z.number(),
+		toMs: z.number(),
+		fromMs: z.number(),
+		shouldPadStart: z.boolean(),
+		shouldPadEnd: z.boolean(),
+		alignedFromUs: z.number(),
+		alignedToUs: z.number(),
+		isInitSegment: z.boolean(),
+		noVideo: z.boolean().optional(),
+		noAudio: z.boolean().optional(),
+		video: z.object({
+			width: z.number(),
+			height: z.number(),
+			framerate: z.number(),
+			codec: z.string(),
+			bitrate: z.number()
+		}),
+		audio: z.object({
+			sampleRate: z.number(),
+			codec: z.string(),
+			numberOfChannels: z.number(),
+			bitrate: z.number()
+		})
+	}),
+	fetchHost: z.string()
 });
-export {
-  VideoRenderOptions
-};
+export { VideoRenderOptions };

package/dist/idempotentTask.js

@@ -1,83 +1,83 @@
-import { existsSync, createWriteStream } from "node:fs";
-import path from "node:path";
 import { md5FilePath } from "./md5.js";
 import debug from "debug";
+import { createWriteStream, existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
 import { Readable } from "node:stream";
-const idempotentTask = ({
-  label,
-  filename,
-  runner
-}) => {
-  const tasks = {};
-  return async (rootDir, absolutePath, ...args) => {
-    const log = debug(`ef:${label}`);
-    const cacheDirRoot = path.join(rootDir, ".cache");
-    await mkdir(cacheDirRoot, { recursive: true });
-    log(`Running ef:${label} task for ${absolutePath} in ${rootDir}`);
-    if (absolutePath.includes("http")) {
-      const safePath = absolutePath.replace(/[^a-zA-Z0-9]/g, "_");
-      const cachePath2 = path.join(rootDir, ".cache", `${safePath}.file`);
-      if (existsSync(absolutePath)) {
-        log(`Already cached ${absolutePath}`);
-      } else {
-        const response = await fetch(absolutePath);
-        const stream = response.body;
-        if (response.ok && stream) {
-          const writeStream = createWriteStream(cachePath2);
-          const readable = Readable.fromWeb(stream);
-          readable.pipe(writeStream);
-          await new Promise((resolve, reject) => {
-            readable.on("error", reject);
-            writeStream.on("error", reject);
-            writeStream.on("finish", resolve);
-          });
-          absolutePath = cachePath2;
-        } else {
-          throw new Error(`Failed to fetch file from URL ${absolutePath}`);
-        }
-      }
-    }
-    const md5 = await md5FilePath(absolutePath);
-    const cacheDir = path.join(cacheDirRoot, md5);
-    log(`Cache dir: ${cacheDir}`);
-    await mkdir(cacheDir, { recursive: true });
-    const cachePath = path.join(cacheDir, filename(absolutePath, ...args));
-    const key = cachePath;
-    if (existsSync(cachePath)) {
-      log(`Returning cached ef:${label} task for ${key}`);
-      return { cachePath, md5Sum: md5 };
-    }
-    const maybeTask = tasks[key];
-    if (maybeTask) {
-      log(`Returning existing ef:${label} task for ${key}`);
-      await maybeTask;
-      return { cachePath, md5Sum: md5 };
-    }
-    log(`Creating new ef:${label} task for ${key}`);
-    const task = runner(absolutePath, ...args);
-    tasks[key] = task;
-    log(`Awaiting task for ${key}`);
-    const result = await task;
-    if (result instanceof Readable) {
-      log(`Piping task for ${key} to cache`);
-      const writeStream = createWriteStream(cachePath);
-      result.pipe(writeStream);
-      await new Promise((resolve, reject) => {
-        result.on("error", reject);
-        writeStream.on("error", reject);
-        writeStream.on("finish", resolve);
-      });
-      return { cachePath, md5Sum: md5 };
-    }
-    log(`Writing to ${cachePath}`);
-    await writeFile(cachePath, result);
-    return {
-      md5Sum: md5,
-      cachePath
-    };
-  };
-};
-export {
-  idempotentTask
+const idempotentTask = ({ label, filename, runner }) => {
+	const tasks = {};
+	return async (rootDir, absolutePath, ...args) => {
+		const log = debug(`ef:${label}`);
+		const cacheDirRoot = path.join(rootDir, ".cache");
+		await mkdir(cacheDirRoot, { recursive: true });
+		log(`Running ef:${label} task for ${absolutePath} in ${rootDir}`);
+		if (absolutePath.includes("http")) {
+			const safePath = absolutePath.replace(/[^a-zA-Z0-9]/g, "_");
+			const cachePath$1 = path.join(rootDir, ".cache", `${safePath}.file`);
+			if (existsSync(absolutePath)) log(`Already cached ${absolutePath}`);
+			else {
+				const response = await fetch(absolutePath);
+				const stream = response.body;
+				if (response.ok && stream) {
+					const writeStream = createWriteStream(cachePath$1);
+					const readable = Readable.fromWeb(stream);
+					readable.pipe(writeStream);
+					await new Promise((resolve, reject) => {
+						readable.on("error", reject);
+						writeStream.on("error", reject);
+						writeStream.on("finish", resolve);
+					});
+					absolutePath = cachePath$1;
+				} else throw new Error(`Failed to fetch file from URL ${absolutePath}`);
+			}
+		}
+		const md5 = await md5FilePath(absolutePath);
+		const cacheDir = path.join(cacheDirRoot, md5);
+		log(`Cache dir: ${cacheDir}`);
+		await mkdir(cacheDir, { recursive: true });
+		const cachePath = path.join(cacheDir, filename(absolutePath, ...args));
+		const key = cachePath;
+		if (existsSync(cachePath)) {
+			log(`Returning cached ef:${label} task for ${key}`);
+			return {
+				cachePath,
+				md5Sum: md5
+			};
+		}
+		const maybeTask = tasks[key];
+		if (maybeTask) {
+			log(`Returning existing ef:${label} task for ${key}`);
+			await maybeTask;
+			return {
+				cachePath,
+				md5Sum: md5
+			};
+		}
+		log(`Creating new ef:${label} task for ${key}`);
+		const task = runner(absolutePath, ...args);
+		tasks[key] = task;
+		log(`Awaiting task for ${key}`);
+		const result = await task;
+		if (result instanceof Readable) {
+			log(`Piping task for ${key} to cache`);
+			const writeStream = createWriteStream(cachePath);
+			result.pipe(writeStream);
+			await new Promise((resolve, reject) => {
+				result.on("error", reject);
+				writeStream.on("error", reject);
+				writeStream.on("finish", resolve);
+			});
+			return {
+				cachePath,
+				md5Sum: md5
+			};
+		}
+		log(`Writing to ${cachePath}`);
+		await writeFile(cachePath, result);
+		return {
+			md5Sum: md5,
+			cachePath
+		};
+	};
 };
+export { idempotentTask };

package/dist/index.js

@@ -5,18 +5,4 @@ import { generateTrack, generateTrackFromPath } from "./tasks/generateTrack.js";
 import { findOrCreateCaptions, generateCaptionDataFromPath } from "./tasks/findOrCreateCaptions.js";
 import { cacheImage } from "./tasks/cacheImage.js";
 import { VideoRenderOptions } from "./VideoRenderOptions.js";
-export {
-  Probe,
-  VideoRenderOptions,
-  cacheImage,
-  findOrCreateCaptions,
-  generateCaptionDataFromPath,
-  generateTrack,
-  generateTrackFragmentIndex,
-  generateTrackFragmentIndexFromPath,
-  generateTrackFromPath,
-  md5Buffer,
-  md5Directory,
-  md5FilePath,
-  md5ReadStream
-};
+export { Probe, VideoRenderOptions, cacheImage, findOrCreateCaptions, generateCaptionDataFromPath, generateTrack, generateTrackFragmentIndex, generateTrackFragmentIndexFromPath, generateTrackFromPath, md5Buffer, md5Directory, md5FilePath, md5ReadStream };

package/dist/md5.js

@@ -4,63 +4,47 @@ import { join } from "node:path";
 import crypto from "node:crypto";
 import ora from "ora";
 async function md5Directory(directory, spinner) {
-  const shouldEndSpinner = !spinner;
-  spinner ||= ora("⚡️ Calculating MD5").start();
-  spinner.suffixText = directory;
-  const files = await readdir(directory, { withFileTypes: true });
-  const hashes = await Promise.all(
-    files.map(async (file) => {
-      const filePath = join(directory, file.name);
-      if (file.isDirectory()) {
-        return md5Directory(filePath, spinner);
-      }
-      spinner.suffixText = filePath;
-      return md5FilePath(filePath);
-    })
-  );
-  const hash = crypto.createHash("md5");
-  for (const fileHash of hashes) {
-    hash.update(fileHash);
-  }
-  if (shouldEndSpinner) {
-    spinner.succeed("MD5 calculated");
-    spinner.suffixText = directory;
-  }
-  return addDashesToUUID(hash.digest("hex"));
+	const shouldEndSpinner = !spinner;
+	spinner ||= ora("⚡️ Calculating MD5").start();
+	spinner.suffixText = directory;
+	const files = await readdir(directory, { withFileTypes: true });
+	const hashes = await Promise.all(files.map(async (file) => {
+		const filePath = join(directory, file.name);
+		if (file.isDirectory()) return md5Directory(filePath, spinner);
+		spinner.suffixText = filePath;
+		return md5FilePath(filePath);
+	}));
+	const hash = crypto.createHash("md5");
+	for (const fileHash of hashes) hash.update(fileHash);
+	if (shouldEndSpinner) {
+		spinner.succeed("MD5 calculated");
+		spinner.suffixText = directory;
+	}
+	return addDashesToUUID(hash.digest("hex"));
 }
 async function md5FilePath(filePath) {
-  const readStream = createReadStream(filePath);
-  return md5ReadStream(readStream);
+	const readStream = createReadStream(filePath);
+	return md5ReadStream(readStream);
 }
 function md5ReadStream(readStream) {
-  return new Promise((resolve, reject) => {
-    const hash = crypto.createHash("md5");
-    readStream.on("data", (data) => {
-      hash.update(data);
-    });
-    readStream.on("error", reject);
-    readStream.on("end", () => {
-      resolve(addDashesToUUID(hash.digest("hex")));
-    });
-  });
+	return new Promise((resolve, reject) => {
+		const hash = crypto.createHash("md5");
+		readStream.on("data", (data) => {
+			hash.update(data);
+		});
+		readStream.on("error", reject);
+		readStream.on("end", () => {
+			resolve(addDashesToUUID(hash.digest("hex")));
+		});
+	});
 }
 function md5Buffer(buffer) {
-  const hash = crypto.createHash("md5");
-  hash.update(buffer);
-  return addDashesToUUID(hash.digest("hex"));
+	const hash = crypto.createHash("md5");
+	hash.update(buffer);
+	return addDashesToUUID(hash.digest("hex"));
 }
 function addDashesToUUID(uuidWithoutDashes) {
-  if (uuidWithoutDashes.length !== 32) {
-    throw new Error("Invalid UUID without dashes. Expected 32 characters.");
-  }
-  return (
-    // biome-ignore lint/style/useTemplate: using a template makes a long line
-    uuidWithoutDashes.slice(0, 8) + "-" + uuidWithoutDashes.slice(8, 12) + "-" + uuidWithoutDashes.slice(12, 16) + "-" + uuidWithoutDashes.slice(16, 20) + "-" + uuidWithoutDashes.slice(20, 32)
-  );
+	if (uuidWithoutDashes.length !== 32) throw new Error("Invalid UUID without dashes. Expected 32 characters.");
+	return uuidWithoutDashes.slice(0, 8) + "-" + uuidWithoutDashes.slice(8, 12) + "-" + uuidWithoutDashes.slice(12, 16) + "-" + uuidWithoutDashes.slice(16, 20) + "-" + uuidWithoutDashes.slice(20, 32);
 }
-export {
-  md5Buffer,
-  md5Directory,
-  md5FilePath,
-  md5ReadStream
-};
+export { md5Buffer, md5Directory, md5FilePath, md5ReadStream };

package/dist/memoize.js

@@ -1,14 +1,11 @@
+/** method decorator to memoize the value of a getter */
 const memoize = (_target, _propertyKey, descriptor) => {
-  const get = descriptor.get;
-  if (!get) return;
-  const memoized = /* @__PURE__ */ new WeakMap();
-  descriptor.get = function() {
-    if (!memoized.has(this)) {
-      memoized.set(this, get.call(this));
-    }
-    return memoized.get(this);
-  };
-};
-export {
-  memoize
+	const get = descriptor.get;
+	if (!get) return;
+	const memoized = /* @__PURE__ */ new WeakMap();
+	descriptor.get = function() {
+		if (!memoized.has(this)) memoized.set(this, get.call(this));
+		return memoized.get(this);
+	};
 };
+export { memoize };

package/dist/mp4FileWritable.js

@@ -1,21 +1,19 @@
 import { Writable } from "node:stream";
 const mp4FileWritable = (mp4File) => {
-  let arrayBufferStart = 0;
-  return new Writable({
-    write: (chunk, _encoding, callback) => {
-      const mp4BoxBuffer = chunk.buffer;
-      mp4BoxBuffer.fileStart = arrayBufferStart;
-      arrayBufferStart += chunk.length;
-      mp4File.appendBuffer(mp4BoxBuffer, false);
-      callback();
-    },
-    final: (callback) => {
-      mp4File.flush();
-      mp4File.processSamples(true);
-      callback();
-    }
-  });
-};
-export {
-  mp4FileWritable
+	let arrayBufferStart = 0;
+	return new Writable({
+		write: (chunk, _encoding, callback) => {
+			const mp4BoxBuffer = chunk.buffer;
+			mp4BoxBuffer.fileStart = arrayBufferStart;
+			arrayBufferStart += chunk.length;
+			mp4File.appendBuffer(mp4BoxBuffer, false);
+			callback();
+		},
+		final: (callback) => {
+			mp4File.flush();
+			mp4File.processSamples(true);
+			callback();
+		}
+	});
 };
+export { mp4FileWritable };

package/dist/tasks/cacheImage.js

@@ -2,21 +2,19 @@ import { idempotentTask } from "../idempotentTask.js";
 import { createReadStream } from "node:fs";
 import path from "node:path";
 const cacheImageTask = idempotentTask({
-  label: "image",
-  filename: (absolutePath) => path.basename(absolutePath),
-  runner: async (absolutePath) => {
-    return createReadStream(absolutePath);
-  }
+	label: "image",
+	filename: (absolutePath) => path.basename(absolutePath),
+	runner: async (absolutePath) => {
+		return createReadStream(absolutePath);
+	}
 });
 const cacheImage = async (cacheRoot, absolutePath) => {
-  try {
-    return await cacheImageTask(cacheRoot, absolutePath);
-  } catch (error) {
-    console.error(error);
-    console.trace("Error caching image", error);
-    throw error;
-  }
-};
-export {
-  cacheImage
+	try {
+		return await cacheImageTask(cacheRoot, absolutePath);
+	} catch (error) {
+		console.error(error);
+		console.trace("Error caching image", error);
+		throw error;
+	}
 };
+export { cacheImage };