@editframe/elements 0.16.8-beta.0 → 0.18.3-beta.0

package/src/elements/EFMedia/BufferedSeekingInput.browsertest.ts

@@ -0,0 +1,400 @@
+import { test as baseTest, describe } from "vitest";
+import { BufferedSeekingInput, NoSample } from "./BufferedSeekingInput";
+
+const test = baseTest.extend<{
+  fiveSampleBuffer: BufferedSeekingInput;
+  inputAtStart: BufferedSeekingInput;
+  inputAtMiddle: BufferedSeekingInput;
+  segment2: BufferedSeekingInput;
+}>({
+  fiveSampleBuffer: async ({}, use) => {
+    const response = await fetch("/jit-segments/segment-0ms-2s-low.mp4");
+    const arrayBuffer = await response.arrayBuffer();
+    const input = new BufferedSeekingInput(arrayBuffer, {
+      videoBufferSize: 5,
+      audioBufferSize: 5,
+    });
+    await use(input);
+  },
+  inputAtStart: async ({}, use) => {
+    const response = await fetch("/jit-segments/segment-0ms-2s-low.mp4");
+    const arrayBuffer = await response.arrayBuffer();
+    const input = new BufferedSeekingInput(arrayBuffer);
+    await use(input);
+  },
+  inputAtMiddle: async ({}, use) => {
+    const response = await fetch("/jit-segments/segment-6000ms-1s-low.mp4");
+    const arrayBuffer = await response.arrayBuffer();
+    const input = new BufferedSeekingInput(arrayBuffer);
+    await use(input);
+  },
+  segment2: async ({}, use) => {
+    const response = await fetch("/jit-segments/segment-2.mp4");
+    const arrayBuffer = await response.arrayBuffer();
+    const input = new BufferedSeekingInput(arrayBuffer);
+    await use(input);
+  },
+});
+
+describe("BufferedSeekingInput", () => {
+  describe("computeDuration", () => {
+    test("computes duration", async ({
+      expect,
+      inputAtStart,
+      inputAtMiddle,
+    }) => {
+      await expect(inputAtStart.computeDuration()).resolves.toBe(2);
+      await expect(inputAtMiddle.computeDuration()).resolves.toBeCloseTo(0.96);
+    });
+  });
+
+  describe("basic seeking", () => {
+    test("seeks to frame at 0 seconds", async ({ expect, inputAtStart }) => {
+      const sample = await inputAtStart.seek(1, 0);
+      expect(sample.timestamp).toBe(0);
+    });
+
+    test("seeks to frame at 0.02 seconds", async ({ expect, inputAtStart }) => {
+      const sample = await inputAtStart.seek(1, 20);
+      expect(sample.timestamp).toBe(0);
+    });
+
+    test("seeks to frame at 0.04 seconds", async ({ expect, inputAtStart }) => {
+      const sample = await inputAtStart.seek(1, 40);
+      expect(sample.timestamp).toBe(0.04);
+    });
+  });
+
+  describe("deterministic seeking behavior", () => {
+    test("seeks to exact sample timestamps", async ({
+      expect,
+      inputAtStart,
+    }) => {
+      expect((await inputAtStart.seek(1, 0)).timestamp).toBe(0);
+      expect((await inputAtStart.seek(1, 40)).timestamp).toBe(0.04);
+      expect((await inputAtStart.seek(1, 80)).timestamp).toBe(0.08);
+      expect((await inputAtStart.seek(1, 120)).timestamp).toBe(0.12);
+      expect((await inputAtStart.seek(1, 160)).timestamp).toBe(0.16);
+    });
+
+    test("seeks between samples returns previous sample", async ({
+      expect,
+      inputAtStart,
+    }) => {
+      expect((await inputAtStart.seek(1, 30)).timestamp).toBe(0);
+      expect((await inputAtStart.seek(1, 60)).timestamp).toBe(0.04);
+      expect((await inputAtStart.seek(1, 100)).timestamp).toBe(0.08);
+      expect((await inputAtStart.seek(1, 140)).timestamp).toBe(0.12);
+    });
+
+    test("seeks before first sample", async ({ expect, inputAtStart }) => {
+      inputAtStart.clearBuffer(1);
+      expect((await inputAtStart.seek(1, 0)).timestamp).toBe(0);
+    });
+
+    test("seeks to later samples in media", async ({
+      expect,
+      inputAtStart,
+    }) => {
+      const result200 = await inputAtStart.seek(1, 200);
+      const result1000 = await inputAtStart.seek(1, 1000);
+
+      expect(result200.timestamp! * 1000).toBeLessThanOrEqual(200);
+      expect(result1000.timestamp! * 1000).toBeLessThanOrEqual(1000);
+      expect(result200.timestamp).toBeGreaterThanOrEqual(0);
+      expect(result1000.timestamp).toBeGreaterThanOrEqual(result200.timestamp!);
+    });
+
+    test("never returns future sample", async ({ expect, inputAtStart }) => {
+      const testCases = [
+        { seekTimeMs: 0, expectedTimestamp: 0 },
+        { seekTimeMs: 10, expectedTimestamp: 0 },
+        { seekTimeMs: 30, expectedTimestamp: 0 },
+        { seekTimeMs: 40, expectedTimestamp: 0.04 },
+        { seekTimeMs: 50, expectedTimestamp: 0.04 },
+        { seekTimeMs: 70, expectedTimestamp: 0.04 },
+        { seekTimeMs: 80, expectedTimestamp: 0.08 },
+        { seekTimeMs: 90, expectedTimestamp: 0.08 },
+      ];
+
+      for (const { seekTimeMs, expectedTimestamp } of testCases) {
+        const result = await inputAtStart.seek(1, seekTimeMs);
+        expect(result.timestamp).toBe(expectedTimestamp);
+
+        const resultTimeMs = result.timestamp! * 1000;
+        expect(resultTimeMs).toBeLessThanOrEqual(seekTimeMs);
+      }
+    });
+  });
+
+  describe("buffer state management", () => {
+    test("starts with empty buffer", async ({ expect, inputAtStart }) => {
+      expect(inputAtStart.getBufferSize(1)).toBe(0);
+      expect(inputAtStart.getBufferTimestamps(1)).toEqual([]);
+      expect(inputAtStart.getBufferContents(1)).toEqual([]);
+    });
+
+    test("maintains separate buffers per track", async ({
+      expect,
+      inputAtStart,
+    }) => {
+      await inputAtStart.seek(1, 0);
+      const track1BufferSize = inputAtStart.getBufferSize(1);
+      expect(track1BufferSize).toBeGreaterThan(0);
+
+      expect(inputAtStart.getBufferSize(2)).toBe(0);
+
+      await inputAtStart.seek(2, 0);
+      expect(inputAtStart.getBufferSize(2)).toBeGreaterThan(0);
+      expect(inputAtStart.getBufferSize(1)).toBe(track1BufferSize);
+    });
+
+    test("buffer accumulates samples in order", async ({
+      expect,
+      inputAtStart,
+    }) => {
+      inputAtStart.clearBuffer(1);
+
+      await inputAtStart.seek(1, 0);
+      await inputAtStart.seek(1, 40);
+      await inputAtStart.seek(1, 80);
+
+      const timestamps = inputAtStart.getBufferTimestamps(1);
+      expect(timestamps).toContain(0);
+      expect(timestamps).toContain(0.04);
+      expect(timestamps).toContain(0.08);
+    });
+
+    test("buffer extends one sample ahead", async ({
+      expect,
+      fiveSampleBuffer,
+    }) => {
+      await fiveSampleBuffer.seek(1, 960);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([
+        0.8, 0.84, 0.88, 0.92, 0.96,
+      ]);
+    });
+
+    test("buffer resets when seeking back before the buffer", async ({
+      expect,
+      fiveSampleBuffer,
+    }) => {
+      await fiveSampleBuffer.seek(1, 960);
+      await fiveSampleBuffer.seek(1, 0);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([0]);
+    });
+
+    test("buffer is maintained when seeking forwards within the buffer", async ({
+      expect,
+      fiveSampleBuffer,
+    }) => {
+      await fiveSampleBuffer.seek(1, 960);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([
+        0.8, 0.84, 0.88, 0.92, 0.96,
+      ]);
+      await fiveSampleBuffer.seek(1, 900);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([
+        0.8, 0.84, 0.88, 0.92, 0.96,
+      ]);
+      await fiveSampleBuffer.seek(1, 960);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([
+        0.8, 0.84, 0.88, 0.92, 0.96,
+      ]);
+    });
+
+    test("buffer is maintained when seeking backwards within the buffer", async ({
+      expect,
+      fiveSampleBuffer,
+    }) => {
+      await fiveSampleBuffer.seek(1, 960);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([
+        0.8, 0.84, 0.88, 0.92, 0.96,
+      ]);
+      await fiveSampleBuffer.seek(1, 900);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([
+        0.8, 0.84, 0.88, 0.92, 0.96,
+      ]);
+    });
+
+    test("buffer is maintained when seeking backwards to start of buffer", async ({
+      expect,
+      fiveSampleBuffer,
+    }) => {
+      await fiveSampleBuffer.seek(1, 960);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([
+        0.8, 0.84, 0.88, 0.92, 0.96,
+      ]);
+      await fiveSampleBuffer.seek(1, 800);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([
+        0.8, 0.84, 0.88, 0.92, 0.96,
+      ]);
+    });
+
+    test("buffer is reset when seeking backwards to arbitrary time before buffer", async ({
+      expect,
+      fiveSampleBuffer,
+    }) => {
+      await fiveSampleBuffer.seek(1, 960);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([
+        0.8, 0.84, 0.88, 0.92, 0.96,
+      ]);
+      await fiveSampleBuffer.seek(1, 720);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([
+        0.56, 0.6, 0.64, 0.68, 0.72,
+      ]);
+    });
+
+    test("buffer is maintained when seeking forwards to end of buffer", async ({
+      expect,
+      fiveSampleBuffer,
+    }) => {
+      await fiveSampleBuffer.seek(1, 960);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([
+        0.8, 0.84, 0.88, 0.92, 0.96,
+      ]);
+      await fiveSampleBuffer.seek(1, 900);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([
+        0.8, 0.84, 0.88, 0.92, 0.96,
+      ]);
+      await fiveSampleBuffer.seek(1, 960);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([
+        0.8, 0.84, 0.88, 0.92, 0.96,
+      ]);
+    });
+
+    test("buffer is maintained when seeking forwards past the buffer", async ({
+      expect,
+      fiveSampleBuffer,
+    }) => {
+      await fiveSampleBuffer.seek(1, 960);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([
+        0.8, 0.84, 0.88, 0.92, 0.96,
+      ]);
+      await fiveSampleBuffer.seek(1, 1000);
+      expect(fiveSampleBuffer.getBufferTimestamps(1)).toEqual([
+        0.84, 0.88, 0.92, 0.96, 1,
+      ]);
+    });
+  });
+
+  describe("seeing to time not in buffer (time is before buffer)", () => {
+    test("throws error", async ({ expect, segment2 }) => {
+      await expect(segment2.seek(1, 0)).rejects.toThrow(NoSample);
+    });
+  });
+
+  describe("seeking forward at 1ms intervals", () => {
+    test("returns all samples in the media", async ({
+      expect,
+      inputAtStart,
+    }) => {
+      const timestamps = new Set<number>();
+      for (let i = 0; i < 1999; i++) {
+        const sample = await inputAtStart.seek(1, i);
+        timestamps.add(sample.timestamp!);
+      }
+      expect(Array.from(timestamps)).toEqual([
+        0, 0.04, 0.08, 0.12, 0.16, 0.2, 0.24, 0.28, 0.32, 0.36, 0.4, 0.44, 0.48,
+        0.52, 0.56, 0.6, 0.64, 0.68, 0.72, 0.76, 0.8, 0.84, 0.88, 0.92, 0.96, 1,
+        1.04, 1.08, 1.12, 1.16, 1.2, 1.24, 1.28, 1.32, 1.36, 1.4, 1.44, 1.48,
+        1.52, 1.56, 1.6, 1.64, 1.68, 1.72, 1.76, 1.8, 1.84, 1.88, 1.92, 1.96,
+      ]);
+    });
+  });
+
+  describe("error handling", () => {
+    test("throws error for non-existent track", async ({
+      expect,
+      inputAtStart,
+    }) => {
+      await expect(inputAtStart.seek(999, 0)).rejects.toThrow(
+        "Track 999 not found",
+      );
+    });
+  });
+
+  describe("concurrency handling", () => {
+    test("handles concurrent seeking operations safely", async ({
+      expect,
+      inputAtStart,
+    }) => {
+      const seek1 = inputAtStart.seek(1, 0);
+      const seek2 = inputAtStart.seek(1, 40);
+      const seek3 = inputAtStart.seek(1, 80);
+      const seek4 = inputAtStart.seek(1, 120);
+
+      const [sample1, sample2, sample3, sample4] = await Promise.all([
+        seek1,
+        seek2,
+        seek3,
+        seek4,
+      ]);
+
+      expect(sample1.timestamp).toBe(0);
+      expect(sample2.timestamp).toBe(0.04);
+      expect(sample3.timestamp).toBe(0.08);
+      expect(sample4.timestamp).toBe(0.12);
+
+      const bufferTimestamps = inputAtStart.getBufferTimestamps(1);
+      expect(bufferTimestamps.length).toBeGreaterThan(0);
+      for (let i = 1; i < bufferTimestamps.length; i++) {
+        expect(bufferTimestamps[i]).toBeGreaterThanOrEqual(
+          bufferTimestamps[i - 1]!,
+        );
+      }
+    });
+
+    test("handles concurrent seeks with backward jumps", async ({
+      expect,
+      inputAtStart,
+    }) => {
+      await inputAtStart.seek(1, 200);
+
+      const seek1 = inputAtStart.seek(1, 40);
+      const seek2 = inputAtStart.seek(1, 160);
+      const seek3 = inputAtStart.seek(1, 0);
+
+      const [sample1, sample2, sample3] = await Promise.all([
+        seek1,
+        seek2,
+        seek3,
+      ]);
+
+      expect(sample1.timestamp).toBe(0.04);
+      expect(sample2.timestamp).toBe(0.16);
+      expect(sample3.timestamp).toBe(0);
+      expect(inputAtStart.getBufferSize(1)).toBeGreaterThan(0);
+    });
+
+    test("handles concurrent seeks to same time", async ({
+      expect,
+      inputAtStart,
+    }) => {
+      const seeks = Array(5)
+        .fill(null)
+        .map(() => inputAtStart.seek(1, 80));
+      const results = await Promise.all(seeks);
+
+      for (const result of results) {
+        expect(result.timestamp).toBe(0.08);
+      }
+      expect(inputAtStart.getBufferSize(1)).toBeGreaterThan(0);
+    });
+
+    test("handles mixed concurrent operations across different tracks", async ({
+      expect,
+      inputAtStart,
+    }) => {
+      const track1Seek1 = inputAtStart.seek(1, 40);
+      const track1Seek2 = inputAtStart.seek(1, 80);
+
+      const [result1, result2] = await Promise.all([track1Seek1, track1Seek2]);
+
+      expect(result1.timestamp).toBe(0.04);
+      expect(result2.timestamp).toBe(0.08);
+
+      const track1Buffer = inputAtStart.getBufferTimestamps(1);
+      expect(track1Buffer.length).toBeGreaterThan(0);
+    });
+  });
+});

package/src/elements/EFMedia/BufferedSeekingInput.ts

@@ -0,0 +1,267 @@
+import {
+  AudioSampleSink,
+  BufferSource,
+  Input,
+  MP4,
+  VideoSampleSink,
+} from "mediabunny";
+import { type MediaSample, SampleBuffer } from "../SampleBuffer";
+
+interface BufferedSeekingInputOptions {
+  videoBufferSize?: number;
+  audioBufferSize?: number;
+  /**
+   * FFmpeg start_time offset in milliseconds from the processed video.
+   * Applied during seeking to correct for timing shifts introduced by FFmpeg processing.
+   */
+  startTimeOffsetMs?: number;
+}
+
+const defaultOptions: BufferedSeekingInputOptions = {
+  videoBufferSize: 30,
+  audioBufferSize: 100,
+  startTimeOffsetMs: 0,
+};
+
+export class NoSample extends RangeError {}
+
+export class BufferedSeekingInput {
+  private input: Input;
+  private trackIterators: Map<number, AsyncIterator<MediaSample>> = new Map();
+  private trackBuffers: Map<number, SampleBuffer> = new Map();
+  private options: BufferedSeekingInputOptions;
+  // Separate locks for different operation types to prevent unnecessary blocking
+  private trackIteratorCreationPromises: Map<number, Promise<any>> = new Map();
+  private trackSeekPromises: Map<number, Promise<any>> = new Map();
+
+  /**
+   * FFmpeg start_time offset in milliseconds from the processed video.
+   * Applied during seeking to correct for timing shifts introduced by FFmpeg processing.
+   */
+  private readonly startTimeOffsetMs: number;
+
+  constructor(arrayBuffer: ArrayBuffer, options?: BufferedSeekingInputOptions) {
+    const bufferSource = new BufferSource(arrayBuffer);
+    const input = new Input({
+      source: bufferSource,
+      formats: [MP4],
+    });
+    this.input = input;
+    this.options = { ...defaultOptions, ...options };
+    this.startTimeOffsetMs = this.options.startTimeOffsetMs ?? 0;
+  }
+
+  // Buffer inspection API for testing
+  getBufferSize(trackId: number): number {
+    const buffer = this.trackBuffers.get(trackId);
+    return buffer ? buffer.length : 0;
+  }
+
+  getBufferContents(trackId: number): readonly MediaSample[] {
+    const buffer = this.trackBuffers.get(trackId);
+    return buffer ? Object.freeze([...buffer.getContents()]) : [];
+  }
+
+  getBufferTimestamps(trackId: number): number[] {
+    const contents = this.getBufferContents(trackId);
+    return contents.map((sample) => sample.timestamp || 0);
+  }
+
+  clearBuffer(trackId: number): void {
+    const buffer = this.trackBuffers.get(trackId);
+    if (buffer) {
+      buffer.clear();
+    }
+  }
+
+  computeDuration() {
+    return this.input.computeDuration();
+  }
+
+  async getTrack(trackId: number) {
+    const tracks = await this.input.getTracks();
+    const track = tracks.find((track) => track.id === trackId);
+    if (!track) {
+      throw new Error(`Track ${trackId} not found`);
+    }
+    return track;
+  }
+
+  async getAudioTrack(trackId: number) {
+    const tracks = await this.input.getAudioTracks();
+    const track = tracks.find(
+      (track) => track.id === trackId && track.type === "audio",
+    );
+    if (!track) {
+      throw new Error(`Track ${trackId} not found`);
+    }
+    return track;
+  }
+
+  async getVideoTrack(trackId: number) {
+    const tracks = await this.input.getVideoTracks();
+    const track = tracks.find(
+      (track) => track.id === trackId && track.type === "video",
+    );
+    if (!track) {
+      throw new Error(`Track ${trackId} not found`);
+    }
+    return track;
+  }
+
+  async getFirstVideoTrack() {
+    const tracks = await this.input.getVideoTracks();
+    return tracks[0];
+  }
+
+  async getFirstAudioTrack() {
+    const tracks = await this.input.getAudioTracks();
+    return tracks[0];
+  }
+
+  async getTrackIterator(trackId: number) {
+    if (this.trackIterators.has(trackId)) {
+      // biome-ignore lint/style/noNonNullAssertion: we know the map has the key
+      return this.trackIterators.get(trackId)!;
+    }
+
+    // Serialize iterator creation per track (but don't block seeks)
+    const existingIteratorCreation =
+      this.trackIteratorCreationPromises.get(trackId);
+    if (existingIteratorCreation) {
+      await existingIteratorCreation;
+      // Check again after waiting - another operation might have created it
+      if (this.trackIterators.has(trackId)) {
+        // biome-ignore lint/style/noNonNullAssertion: we know the map has the key
+        return this.trackIterators.get(trackId)!;
+      }
+    }
+
+    const creationPromise = this.createIteratorSafe(trackId);
+    this.trackIteratorCreationPromises.set(trackId, creationPromise);
+
+    try {
+      const iterator = await creationPromise;
+      return iterator;
+    } finally {
+      this.trackIteratorCreationPromises.delete(trackId);
+    }
+  }
+
+  private async createIteratorSafe(trackId: number) {
+    const track = await this.getTrack(trackId);
+    if (track.type === "audio") {
+      const track = await this.getAudioTrack(trackId);
+      const sampleSink = new AudioSampleSink(track);
+      const iterator = sampleSink.samples();
+      this.trackIterators.set(trackId, iterator);
+      return iterator;
+    }
+    {
+      const track = await this.getVideoTrack(trackId);
+      const sampleSink = new VideoSampleSink(track);
+      const iterator = sampleSink.samples();
+      this.trackIterators.set(trackId, iterator);
+      return iterator;
+    }
+  }
+
+  async createTrackBuffer(trackId: number) {
+    const track = await this.getTrack(trackId);
+    if (track.type === "audio") {
+      const bufferSize = this.options.audioBufferSize;
+      this.trackBuffers.set(trackId, new SampleBuffer(bufferSize));
+    } else {
+      const bufferSize = this.options.videoBufferSize;
+      this.trackBuffers.set(trackId, new SampleBuffer(bufferSize));
+    }
+  }
+
+  async seek(trackId: number, timeMs: number) {
+    // Apply the start time offset to deal with files that don't start on the zero
+    const correctedTimeMs = timeMs + this.startTimeOffsetMs;
+
+    // Serialize seek operations per track (but don't block iterator creation)
+    const existingSeek = this.trackSeekPromises.get(trackId);
+    if (existingSeek) {
+      await existingSeek;
+    }
+
+    const seekPromise = this.seekSafe(trackId, correctedTimeMs);
+    this.trackSeekPromises.set(trackId, seekPromise);
+
+    try {
+      return await seekPromise;
+    } finally {
+      this.trackSeekPromises.delete(trackId);
+    }
+  }
+
+  private async resetIterator(trackId: number) {
+    const trackBuffer = this.trackBuffers.get(trackId);
+    trackBuffer?.clear();
+    // Clean up iterator safely - wait for any ongoing iterator creation
+    const ongoingIteratorCreation =
+      this.trackIteratorCreationPromises.get(trackId);
+    if (ongoingIteratorCreation) {
+      await ongoingIteratorCreation;
+    }
+
+    const iterator = this.trackIterators.get(trackId);
+    if (iterator) {
+      try {
+        await iterator.return?.();
+      } catch (_error) {
+        // Iterator cleanup failed, continue anyway
+      }
+    }
+    this.trackIterators.delete(trackId);
+  }
+
+  private async seekSafe(trackId: number, timeMs: number) {
+    // Get or create track-specific buffer
+    if (!this.trackBuffers.has(trackId)) {
+      await this.createTrackBuffer(trackId);
+    }
+    // biome-ignore lint/style/noNonNullAssertion: we know the map has the key
+    const trackBuffer = this.trackBuffers.get(trackId)!;
+
+    if (timeMs < trackBuffer.firstTimestamp * 1000) {
+      await this.resetIterator(trackId);
+    }
+
+    const alreadyInBuffer = trackBuffer.find(timeMs);
+    const track = await this.getTrack(trackId);
+
+    // Early validation: check if seek time is outside track bounds
+    const firstTimestampMs = (await track.getFirstTimestamp()) * 1000;
+    const lastSampleEndMs = (await track.computeDuration()) * 1000; // computeDuration returns end time of last sample
+
+    if (timeMs < firstTimestampMs || timeMs >= lastSampleEndMs) {
+      throw new NoSample(
+        `Seek time ${timeMs}ms is outside track range [${firstTimestampMs}ms, ${lastSampleEndMs}ms]`,
+      );
+    }
+
+    if (alreadyInBuffer) return alreadyInBuffer;
+
+    const iterator = await this.getTrackIterator(trackId);
+    while (true) {
+      const { done, value: decodedSample } = await iterator.next();
+      if (decodedSample) {
+        trackBuffer.push(decodedSample);
+      }
+      const foundSample = trackBuffer.find(timeMs);
+      if (foundSample) {
+        return foundSample;
+      }
+      if (done) {
+        break;
+      }
+    }
+
+    throw new NoSample(
+      `Sample not found for time ${timeMs} in ${track.type} track ${trackId}`,
+    );
+  }
+}