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

package/dist/FrameBuffer.d.ts

@@ -0,0 +1,62 @@
+/**
+ * FrameBuffer manages a collection of decoded VideoFrames with automatic LRU eviction.
+ *
+ * This class extracts the frame buffering logic from VideoAsset to improve
+ * testability and separation of concerns while maintaining the exact same
+ * memory management behavior.
+ */
+export declare class FrameBuffer {
+    private _frames;
+    private readonly _maxSize;
+    /**
+     * Creates a new FrameBuffer with the specified maximum size.
+     *
+     * @param maxSize Maximum number of frames to keep in buffer (default: 30)
+     */
+    constructor(maxSize?: number);
+    /**
+     * Gets the maximum size of the buffer.
+     */
+    get maxSize(): number;
+    /**
+     * Gets the current number of frames in the buffer.
+     */
+    get size(): number;
+    /**
+     * Gets a copy of the frames array for compatibility.
+     * Note: Returns a shallow copy to prevent external modification while allowing access.
+     */
+    get frames(): VideoFrame[];
+    /**
+     * Adds a frame to the buffer. If the buffer exceeds maxSize after adding,
+     * the oldest frames will be automatically pruned and closed.
+     *
+     * @param frame The VideoFrame to add to the buffer
+     */
+    add(frame: VideoFrame): void;
+    /**
+     * Finds a frame in the buffer by its timestamp.
+     *
+     * @param timestamp The timestamp to search for
+     * @returns The VideoFrame with matching timestamp, or undefined if not found
+     */
+    findByTimestamp(timestamp: number): VideoFrame | undefined;
+    /**
+     * Checks if the buffer contains the specified frame instance.
+     *
+     * @param frame The VideoFrame instance to check for
+     * @returns true if the frame is in the buffer, false otherwise
+     */
+    includes(frame: VideoFrame): boolean;
+    /**
+     * Removes all frames from the buffer and closes them to free memory.
+     * This method is safe to call even if some frames are already closed.
+     */
+    clear(): void;
+    /**
+     * Prunes the buffer to the maximum size by removing and closing the oldest frames.
+     * This maintains the LRU (Least Recently Used) eviction policy where oldest
+     * frames are removed first.
+     */
+    pruneToSize(): void;
+}

package/dist/FrameBuffer.js

@@ -0,0 +1,89 @@
+/**
+* FrameBuffer manages a collection of decoded VideoFrames with automatic LRU eviction.
+* 
+* This class extracts the frame buffering logic from VideoAsset to improve 
+* testability and separation of concerns while maintaining the exact same
+* memory management behavior.
+*/
+var FrameBuffer = class {
+	/**
+	* Creates a new FrameBuffer with the specified maximum size.
+	* 
+	* @param maxSize Maximum number of frames to keep in buffer (default: 30)
+	*/
+	constructor(maxSize = 30) {
+		this._frames = [];
+		this._maxSize = maxSize;
+	}
+	/**
+	* Gets the maximum size of the buffer.
+	*/
+	get maxSize() {
+		return this._maxSize;
+	}
+	/**
+	* Gets the current number of frames in the buffer.
+	*/
+	get size() {
+		return this._frames.length;
+	}
+	/**
+	* Gets a copy of the frames array for compatibility.
+	* Note: Returns a shallow copy to prevent external modification while allowing access.
+	*/
+	get frames() {
+		return [...this._frames];
+	}
+	/**
+	* Adds a frame to the buffer. If the buffer exceeds maxSize after adding,
+	* the oldest frames will be automatically pruned and closed.
+	* 
+	* @param frame The VideoFrame to add to the buffer
+	*/
+	add(frame) {
+		this._frames.push(frame);
+		this.pruneToSize();
+	}
+	/**
+	* Finds a frame in the buffer by its timestamp.
+	* 
+	* @param timestamp The timestamp to search for
+	* @returns The VideoFrame with matching timestamp, or undefined if not found
+	*/
+	findByTimestamp(timestamp) {
+		return this._frames.find((frame) => frame.timestamp === timestamp);
+	}
+	/**
+	* Checks if the buffer contains the specified frame instance.
+	* 
+	* @param frame The VideoFrame instance to check for
+	* @returns true if the frame is in the buffer, false otherwise
+	*/
+	includes(frame) {
+		return this._frames.includes(frame);
+	}
+	/**
+	* Removes all frames from the buffer and closes them to free memory.
+	* This method is safe to call even if some frames are already closed.
+	*/
+	clear() {
+		for (const frame of this._frames) try {
+			frame.close();
+		} catch (error) {}
+		this._frames = [];
+	}
+	/**
+	* Prunes the buffer to the maximum size by removing and closing the oldest frames.
+	* This maintains the LRU (Least Recently Used) eviction policy where oldest
+	* frames are removed first.
+	*/
+	pruneToSize() {
+		while (this._frames.length > this._maxSize) {
+			const oldestFrame = this._frames.shift();
+			if (oldestFrame) try {
+				oldestFrame.close();
+			} catch (error) {}
+		}
+	}
+};
+export { FrameBuffer };

package/dist/MP4File.d.ts

@@ -1,6 +1,14 @@
 import * as MP4Box from "mp4box";
+export interface MP4FileOptions {
+    readyTimeoutMs?: number;
+    sampleWaitTimeoutMs?: number;
+}
 export declare class MP4File extends MP4Box.ISOFile {
-    readyPromise: Promise<void>;
+    private timeoutId?;
+    private readonly readyTimeoutMs;
+    private readonly sampleWaitTimeoutMs;
+    readonly readyPromise: Promise<void>;
+    constructor(options?: MP4FileOptions);
     setSegmentOptions(id: number, user: any, options: MP4Box.SegmentOptions): void;
     /**
      * Fragments all tracks in a file into separate array buffers.

package/dist/MP4File.js

@@ -1,223 +1,209 @@
 import * as MP4Box from "mp4box";
 import debug from "debug";
 const log = debug("ef:av:mp4file");
-class MP4File extends MP4Box.ISOFile {
-  constructor() {
-    super(...arguments);
-    this.readyPromise = new Promise((resolve, reject) => {
-      this.onReady = () => resolve();
-      this.onError = reject;
-    });
-    this.waitingForSamples = [];
-    this._hasSeenLastSamples = false;
-    this._arrayBufferFileStart = 0;
-  }
-  setSegmentOptions(id, user, options) {
-    const trak = this.getTrackById(id);
-    if (trak) {
-      trak.nextSample = 0;
-      this.fragmentedTracks.push({
-        id,
-        user,
-        trak,
-        segmentStream: null,
-        nb_samples: "nbSamples" in options && options.nbSamples || 1e3,
-        rapAlignement: ("rapAlignement" in options && options.rapAlignement) ?? true
-      });
-    }
-  }
-  /**
-   * Fragments all tracks in a file into separate array buffers.
-   */
-  async fragmentAllTracks() {
-    const trackBuffers = {};
-    for await (const segment of this.fragmentIterator()) {
-      (trackBuffers[segment.track] ??= []).push(segment.data);
-    }
-    return trackBuffers;
-  }
-  async *fragmentIterator() {
-    await this.readyPromise;
-    const trackInfo = {};
-    for (const videoTrack of this.getInfo().videoTracks) {
-      trackInfo[videoTrack.id] = { index: 0 };
-      this.setSegmentOptions(videoTrack.id, null, {
-        rapAlignement: true
-      });
-    }
-    for (const audioTrack of this.getInfo().audioTracks) {
-      trackInfo[audioTrack.id] = { index: 0 };
-      const sampleRate = audioTrack.audio.sample_rate;
-      const probablePacketSize = 1024;
-      const probableFourSecondsOfSamples = Math.ceil(
-        sampleRate / probablePacketSize * 4
-      );
-      this.setSegmentOptions(audioTrack.id, null, {
-        nbSamples: probableFourSecondsOfSamples
-      });
-    }
-    const initSegments = this.initializeSegmentation();
-    for (const initSegment of initSegments) {
-      yield {
-        track: initSegment.id,
-        segment: "init",
-        data: initSegment.buffer
-      };
-    }
-    const fragmentStartSamples = {};
-    let finishedReading = false;
-    do {
-      for (const fragTrak of this.fragmentedTracks) {
-        const trak = fragTrak.trak;
-        if (trak.nextSample === void 0) {
-          throw new Error("trak.nextSample is undefined");
-        }
-        if (trak.samples === void 0) {
-          throw new Error("trak.samples is undefined");
-        }
-        log("trak.nextSample", fragTrak.id, trak.nextSample);
-        log("trak.samples.length", fragTrak.id, trak.samples.length);
-        while (trak.nextSample < trak.samples.length) {
-          let result = void 0;
-          const fragTrakNextSample = trak.samples[trak.nextSample];
-          if (fragTrakNextSample) {
-            fragmentStartSamples[fragTrak.id] ||= fragTrakNextSample;
-          }
-          try {
-            result = this.createFragment(
-              fragTrak.id,
-              trak.nextSample,
-              fragTrak.segmentStream
-            );
-          } catch (error) {
-            console.error("Failed to createFragment", error);
-          }
-          if (result) {
-            fragTrak.segmentStream = result;
-            trak.nextSample++;
-          } else {
-            finishedReading = await this.waitForMoreSamples();
-            break;
-          }
-          const nextSample = trak.samples[trak.nextSample];
-          const emitSegment = (
-            // if rapAlignement is true, we emit a fragment when we have a rap sample coming up next
-            fragTrak.rapAlignement === true && nextSample?.is_sync || // if rapAlignement is false, we emit a fragment when we have the required number of samples
-            !fragTrak.rapAlignement && trak.nextSample % fragTrak.nb_samples === 0 || // // if this is the last sample, we emit the fragment
-            // finished ||
-            // if we have more samples than the number of samples requested, we emit the fragment
-            trak.nextSample >= trak.samples.length
-          );
-          if (emitSegment) {
-            const trackInfoForFrag = trackInfo[fragTrak.id];
-            if (!trackInfoForFrag) {
-              throw new Error("trackInfoForFrag is undefined");
-            }
-            const startSample = fragmentStartSamples[fragTrak.id];
-            const endSample = trak.samples[trak.nextSample - 1];
-            if (!startSample || !endSample) {
-              throw new Error("startSample or endSample is undefined");
-            }
-            log(
-              `Yielding fragment #${trackInfoForFrag.index} for track=${fragTrak.id}`,
-              `startTime=${startSample.cts}`,
-              `endTime=${endSample.cts + endSample.duration}`
-            );
-            yield {
-              track: fragTrak.id,
-              segment: trackInfoForFrag.index,
-              data: fragTrak.segmentStream.buffer,
-              cts: startSample.cts,
-              dts: startSample.dts,
-              duration: endSample.cts - startSample.cts + endSample.duration
-            };
-            trackInfoForFrag.index += 1;
-            fragTrak.segmentStream = null;
-            delete fragmentStartSamples[fragTrak.id];
-          }
-        }
-      }
-      finishedReading = await this.waitForMoreSamples();
-    } while (!finishedReading);
-    for (const fragTrak of this.fragmentedTracks) {
-      const trak = fragTrak.trak;
-      if (trak.nextSample === void 0) {
-        throw new Error("trak.nextSample is undefined");
-      }
-      if (trak.samples === void 0) {
-        throw new Error("trak.samples is undefined");
-      }
-      while (trak.nextSample < trak.samples.length) {
-        let result = void 0;
-        try {
-          result = this.createFragment(
-            fragTrak.id,
-            trak.nextSample,
-            fragTrak.segmentStream
-          );
-        } catch (error) {
-          console.error("Failed to createFragment", error);
-        }
-        if (result) {
-          fragTrak.segmentStream = result;
-          trak.nextSample++;
-        } else {
-          finishedReading = await this.waitForMoreSamples();
-          break;
-        }
-        const nextSample = trak.samples[trak.nextSample];
-        const emitSegment = (
-          // if rapAlignement is true, we emit a fragment when we have a rap sample coming up next
-          fragTrak.rapAlignement === true && nextSample?.is_sync || // if rapAlignement is false, we emit a fragment when we have the required number of samples
-          !fragTrak.rapAlignement && trak.nextSample % fragTrak.nb_samples === 0 || // if we have more samples than the number of samples requested, we emit the fragment
-          trak.nextSample >= trak.samples.length
-        );
-        if (emitSegment) {
-          const trackInfoForFrag = trackInfo[fragTrak.id];
-          if (!trackInfoForFrag) {
-            throw new Error("trackInfoForFrag is undefined");
-          }
-          const startSample = fragmentStartSamples[fragTrak.id];
-          const endSample = trak.samples[trak.nextSample - 1];
-          if (!startSample || !endSample) {
-            throw new Error("startSample or endSample is undefined");
-          }
-          log(
-            `Yielding fragment #${trackInfoForFrag.index} for track=${fragTrak.id}`,
-            `startTime=${startSample.cts}`,
-            `endTime=${endSample.cts + endSample.duration}`
-          );
-          yield {
-            track: fragTrak.id,
-            segment: trackInfoForFrag.index,
-            data: fragTrak.segmentStream.buffer,
-            cts: startSample.cts,
-            dts: startSample.dts,
-            duration: endSample.cts - startSample.cts + endSample.duration
-          };
-          trackInfoForFrag.index += 1;
-          fragTrak.segmentStream = null;
-          delete fragmentStartSamples[fragTrak.id];
-        }
-      }
-    }
-  }
-  waitForMoreSamples() {
-    if (this._hasSeenLastSamples) {
-      return Promise.resolve(true);
-    }
-    return new Promise((resolve) => {
-      this.waitingForSamples.push(resolve);
-    });
-  }
-  processSamples(last) {
-    this._hasSeenLastSamples = last;
-    for (const observer of this.waitingForSamples) {
-      observer(last);
-    }
-    this.waitingForSamples = [];
-  }
-}
-export {
-  MP4File
+var MP4File = class extends MP4Box.ISOFile {
+	constructor(options = {}) {
+		super();
+		this.waitingForSamples = [];
+		this._hasSeenLastSamples = false;
+		this._arrayBufferFileStart = 0;
+		this.readyTimeoutMs = options.readyTimeoutMs ?? 100;
+		this.sampleWaitTimeoutMs = options.sampleWaitTimeoutMs ?? 100;
+		this.readyPromise = new Promise((resolve, reject) => {
+			this.onReady = () => {
+				if (this.timeoutId) {
+					clearTimeout(this.timeoutId);
+					this.timeoutId = void 0;
+				}
+				resolve();
+			};
+			this.onError = (error) => {
+				if (this.timeoutId) {
+					clearTimeout(this.timeoutId);
+					this.timeoutId = void 0;
+				}
+				reject(error);
+			};
+			this.timeoutId = setTimeout(() => {
+				this.timeoutId = void 0;
+				reject(/* @__PURE__ */ new Error("MP4File ready timeout - file may be invalid or incomplete"));
+			}, this.readyTimeoutMs);
+		});
+		this.readyPromise.catch(() => {});
+	}
+	setSegmentOptions(id, user, options) {
+		const trak = this.getTrackById(id);
+		if (trak) {
+			trak.nextSample = 0;
+			this.fragmentedTracks.push({
+				id,
+				user,
+				trak,
+				segmentStream: null,
+				nb_samples: "nbSamples" in options && options.nbSamples || 1e3,
+				rapAlignement: ("rapAlignement" in options && options.rapAlignement) ?? true
+			});
+		}
+	}
+	/**
+	* Fragments all tracks in a file into separate array buffers.
+	*/
+	async fragmentAllTracks() {
+		const trackBuffers = {};
+		try {
+			for await (const segment of this.fragmentIterator()) (trackBuffers[segment.track] ??= []).push(segment.data);
+		} catch (error) {
+			console.warn("fragmentAllTracks failed:", error);
+		}
+		return trackBuffers;
+	}
+	async *fragmentIterator() {
+		try {
+			await this.readyPromise;
+		} catch (error) {
+			console.warn("MP4File not ready:", error);
+			return;
+		}
+		const trackInfo = {};
+		const videoTracks = this.getInfo().videoTracks;
+		const audioTracks = this.getInfo().audioTracks;
+		if (videoTracks.length === 0 && audioTracks.length === 0) {
+			console.warn("No video or audio tracks found in MP4 file");
+			return;
+		}
+		for (const videoTrack of videoTracks) {
+			trackInfo[videoTrack.id] = { index: 0 };
+			this.setSegmentOptions(videoTrack.id, null, { rapAlignement: true });
+		}
+		for (const audioTrack of audioTracks) {
+			trackInfo[audioTrack.id] = { index: 0 };
+			const sampleRate = audioTrack.audio.sample_rate;
+			const probablePacketSize = 1024;
+			const probableFourSecondsOfSamples = Math.ceil(sampleRate / probablePacketSize * 4);
+			this.setSegmentOptions(audioTrack.id, null, { nbSamples: probableFourSecondsOfSamples });
+		}
+		if (this.fragmentedTracks.length === 0) {
+			console.warn("No fragmented tracks set up");
+			return;
+		}
+		const initSegments = this.initializeSegmentation();
+		for (const initSegment of initSegments) yield {
+			track: initSegment.id,
+			segment: "init",
+			data: initSegment.buffer
+		};
+		const fragmentStartSamples = {};
+		let finishedReading = false;
+		do {
+			/**
+			* For each track marked for fragmentation, check if the next sample is
+			* there (i.e. if the sample information is known (i.e. moof has arrived)
+			* and if it has been downloaded) and create a fragment with it
+			*/
+			for (const fragTrak of this.fragmentedTracks) {
+				const trak = fragTrak.trak;
+				if (trak.nextSample === void 0) throw new Error("trak.nextSample is undefined");
+				if (trak.samples === void 0) throw new Error("trak.samples is undefined");
+				log("trak.nextSample", fragTrak.id, trak.nextSample);
+				log("trak.samples.length", fragTrak.id, trak.samples.length);
+				while (trak.nextSample < trak.samples.length) {
+					let result = void 0;
+					const fragTrakNextSample = trak.samples[trak.nextSample];
+					if (fragTrakNextSample) fragmentStartSamples[fragTrak.id] ||= fragTrakNextSample;
+					try {
+						result = this.createFragment(fragTrak.id, trak.nextSample, fragTrak.segmentStream);
+					} catch (error) {
+						console.error("Failed to createFragment", error);
+					}
+					if (result) {
+						fragTrak.segmentStream = result;
+						trak.nextSample++;
+					} else {
+						finishedReading = await this.waitForMoreSamples();
+						break;
+					}
+					const nextSample = trak.samples[trak.nextSample];
+					const emitSegment = fragTrak.rapAlignement === true && nextSample?.is_sync || !fragTrak.rapAlignement && trak.nextSample % fragTrak.nb_samples === 0 || trak.nextSample >= trak.samples.length;
+					if (emitSegment) {
+						const trackInfoForFrag = trackInfo[fragTrak.id];
+						if (!trackInfoForFrag) throw new Error("trackInfoForFrag is undefined");
+						const startSample = fragmentStartSamples[fragTrak.id];
+						const endSample = trak.samples[trak.nextSample - 1];
+						if (!startSample || !endSample) throw new Error("startSample or endSample is undefined");
+						log(`Yielding fragment #${trackInfoForFrag.index} for track=${fragTrak.id}`, `startTime=${startSample.cts}`, `endTime=${endSample.cts + endSample.duration}`);
+						yield {
+							track: fragTrak.id,
+							segment: trackInfoForFrag.index,
+							data: fragTrak.segmentStream.buffer,
+							cts: startSample.cts,
+							dts: startSample.dts,
+							duration: endSample.cts - startSample.cts + endSample.duration
+						};
+						trackInfoForFrag.index += 1;
+						fragTrak.segmentStream = null;
+						delete fragmentStartSamples[fragTrak.id];
+					}
+				}
+			}
+			finishedReading = await this.waitForMoreSamples();
+		} while (!finishedReading);
+		for (const fragTrak of this.fragmentedTracks) {
+			const trak = fragTrak.trak;
+			if (trak.nextSample === void 0) throw new Error("trak.nextSample is undefined");
+			if (trak.samples === void 0) throw new Error("trak.samples is undefined");
+			while (trak.nextSample < trak.samples.length) {
+				let result = void 0;
+				try {
+					result = this.createFragment(fragTrak.id, trak.nextSample, fragTrak.segmentStream);
+				} catch (error) {
+					console.error("Failed to createFragment", error);
+				}
+				if (result) {
+					fragTrak.segmentStream = result;
+					trak.nextSample++;
+				} else {
+					finishedReading = await this.waitForMoreSamples();
+					break;
+				}
+				const nextSample = trak.samples[trak.nextSample];
+				const emitSegment = fragTrak.rapAlignement === true && nextSample?.is_sync || !fragTrak.rapAlignement && trak.nextSample % fragTrak.nb_samples === 0 || trak.nextSample >= trak.samples.length;
+				if (emitSegment) {
+					const trackInfoForFrag = trackInfo[fragTrak.id];
+					if (!trackInfoForFrag) throw new Error("trackInfoForFrag is undefined");
+					const startSample = fragmentStartSamples[fragTrak.id];
+					const endSample = trak.samples[trak.nextSample - 1];
+					if (!startSample || !endSample) throw new Error("startSample or endSample is undefined");
+					log(`Yielding fragment #${trackInfoForFrag.index} for track=${fragTrak.id}`, `startTime=${startSample.cts}`, `endTime=${endSample.cts + endSample.duration}`);
+					yield {
+						track: fragTrak.id,
+						segment: trackInfoForFrag.index,
+						data: fragTrak.segmentStream.buffer,
+						cts: startSample.cts,
+						dts: startSample.dts,
+						duration: endSample.cts - startSample.cts + endSample.duration
+					};
+					trackInfoForFrag.index += 1;
+					fragTrak.segmentStream = null;
+					delete fragmentStartSamples[fragTrak.id];
+				}
+			}
+		}
+	}
+	waitForMoreSamples() {
+		if (this._hasSeenLastSamples) return Promise.resolve(true);
+		return new Promise((resolve) => {
+			this.waitingForSamples.push(resolve);
+			setTimeout(() => {
+				const index = this.waitingForSamples.indexOf(resolve);
+				if (index !== -1) this.waitingForSamples.splice(index, 1);
+				resolve(true);
+			}, this.sampleWaitTimeoutMs);
+		});
+	}
+	processSamples(last) {
+		this._hasSeenLastSamples = last;
+		for (const observer of this.waitingForSamples) observer(last);
+		this.waitingForSamples = [];
+	}
 };
+export { MP4File };