@remotion/media 4.0.363 → 4.0.364

package/dist/esm/index.mjs

@@ -10,171 +10,7 @@ import {
   useCurrentFrame as useCurrentFrame2
 } from "remotion";
 
-// src/show-in-timeline.ts
-import { useMemo } from "react";
-import { Internals, useVideoConfig } from "remotion";
-var useLoopDisplay = ({
-  loop,
-  mediaDurationInSeconds,
-  playbackRate,
-  trimAfter,
-  trimBefore
-}) => {
-  const { durationInFrames: compDuration, fps } = useVideoConfig();
-  const loopDisplay = useMemo(() => {
-    if (!loop || !mediaDurationInSeconds) {
-      return;
-    }
-    const durationInFrames = Internals.calculateMediaDuration({
-      mediaDurationInFrames: mediaDurationInSeconds * fps,
-      playbackRate,
-      trimAfter,
-      trimBefore
-    });
-    const maxTimes = compDuration / durationInFrames;
-    return {
-      numberOfTimes: maxTimes,
-      startOffset: 0,
-      durationInFrames
-    };
-  }, [
-    compDuration,
-    fps,
-    loop,
-    mediaDurationInSeconds,
-    playbackRate,
-    trimAfter,
-    trimBefore
-  ]);
-  return loopDisplay;
-};
-
-// src/use-media-in-timeline.ts
-import { useContext, useEffect, useState } from "react";
-import { Internals as Internals2, useCurrentFrame } from "remotion";
-var useMediaInTimeline = ({
-  volume,
-  mediaVolume,
-  src,
-  mediaType,
-  playbackRate,
-  displayName,
-  stack,
-  showInTimeline,
-  premountDisplay,
-  postmountDisplay,
-  loopDisplay,
-  trimBefore,
-  trimAfter
-}) => {
-  const parentSequence = useContext(Internals2.SequenceContext);
-  const startsAt = Internals2.useMediaStartsAt();
-  const { registerSequence, unregisterSequence } = useContext(Internals2.SequenceManager);
-  const [sequenceId] = useState(() => String(Math.random()));
-  const [mediaId] = useState(() => String(Math.random()));
-  const frame = useCurrentFrame();
-  const {
-    volumes,
-    duration,
-    doesVolumeChange,
-    nonce,
-    rootId,
-    isStudio,
-    finalDisplayName
-  } = Internals2.useBasicMediaInTimeline({
-    volume,
-    mediaVolume,
-    mediaType,
-    src,
-    displayName,
-    trimBefore,
-    trimAfter,
-    playbackRate
-  });
-  useEffect(() => {
-    if (!src) {
-      throw new Error("No src passed");
-    }
-    if (!isStudio && window.process?.env?.NODE_ENV !== "test") {
-      return;
-    }
-    if (!showInTimeline) {
-      return;
-    }
-    const loopIteration = loopDisplay ? Math.floor(frame / loopDisplay.durationInFrames) : 0;
-    if (loopDisplay) {
-      registerSequence({
-        type: "sequence",
-        premountDisplay,
-        postmountDisplay,
-        parent: parentSequence?.id ?? null,
-        displayName: finalDisplayName,
-        rootId,
-        showInTimeline: true,
-        nonce,
-        loopDisplay,
-        stack,
-        from: 0,
-        duration,
-        id: sequenceId
-      });
-    }
-    registerSequence({
-      type: mediaType,
-      src,
-      id: mediaId,
-      duration: loopDisplay?.durationInFrames ?? duration,
-      from: loopDisplay ? loopIteration * loopDisplay.durationInFrames : 0,
-      parent: loopDisplay ? sequenceId : parentSequence?.id ?? null,
-      displayName: finalDisplayName,
-      rootId,
-      volume: volumes,
-      showInTimeline: true,
-      nonce,
-      startMediaFrom: 0 - startsAt,
-      doesVolumeChange,
-      loopDisplay: undefined,
-      playbackRate,
-      stack,
-      premountDisplay: null,
-      postmountDisplay: null
-    });
-    return () => {
-      if (loopDisplay) {
-        unregisterSequence(sequenceId);
-      }
-      unregisterSequence(mediaId);
-    };
-  }, [
-    doesVolumeChange,
-    duration,
-    finalDisplayName,
-    isStudio,
-    loopDisplay,
-    mediaId,
-    mediaType,
-    nonce,
-    parentSequence?.id,
-    playbackRate,
-    postmountDisplay,
-    premountDisplay,
-    registerSequence,
-    rootId,
-    sequenceId,
-    showInTimeline,
-    src,
-    stack,
-    startsAt,
-    unregisterSequence,
-    volumes,
-    frame
-  ]);
-  return {
-    id: mediaId
-  };
-};
-
-// src/video/media-player.ts
+// src/media-player.ts
 import {
   ALL_FORMATS,
   AudioBufferSink,
@@ -182,10 +18,71 @@ import {
   Input,
   UrlSource
 } from "mediabunny";
-import { Internals as Internals4 } from "remotion";
+import { Internals as Internals2 } from "remotion";
+
+// src/audio/audio-preview-iterator.ts
+var HEALTHY_BUFFER_THRESHOLD_SECONDS = 1;
+var makeAudioIterator = (audioSink, startFromSecond) => {
+  let destroyed = false;
+  const iterator = audioSink.buffers(startFromSecond);
+  let audioIteratorStarted = false;
+  let audioBufferHealth = 0;
+  const queuedAudioNodes = new Set;
+  const cleanupAudioQueue = () => {
+    for (const node of queuedAudioNodes) {
+      node.stop();
+    }
+    queuedAudioNodes.clear();
+  };
+  return {
+    cleanupAudioQueue,
+    destroy: () => {
+      cleanupAudioQueue();
+      destroyed = true;
+      iterator.return().catch(() => {
+        return;
+      });
+    },
+    isReadyToPlay: () => {
+      return audioIteratorStarted && audioBufferHealth > 0;
+    },
+    setAudioIteratorStarted: (started) => {
+      audioIteratorStarted = started;
+    },
+    getNext: () => {
+      return iterator.next();
+    },
+    setAudioBufferHealth: (health) => {
+      audioBufferHealth = health;
+    },
+    isDestroyed: () => {
+      return destroyed;
+    },
+    addQueuedAudioNode: (node) => {
+      queuedAudioNodes.add(node);
+    },
+    removeQueuedAudioNode: (node) => {
+      queuedAudioNodes.delete(node);
+    }
+  };
+};
+
+// src/debug-overlay/preview-overlay.ts
+var drawPreviewOverlay = (context, stats, audioContextState, audioSyncAnchor) => {
+  context.fillStyle = "rgba(0, 0, 0, 1)";
+  context.fillRect(20, 20, 600, 180);
+  context.fillStyle = "white";
+  context.font = "24px sans-serif";
+  context.textBaseline = "top";
+  context.fillText(`Debug overlay`, 30, 30);
+  context.fillText(`Video iterators created: ${stats.videoIteratorsCreated}`, 30, 60);
+  context.fillText(`Frames rendered: ${stats.framesRendered}`, 30, 90);
+  context.fillText(`Audio context state: ${audioContextState}`, 30, 120);
+  context.fillText(`Audio time: ${audioSyncAnchor.toFixed(3)}s`, 30, 150);
+};
 
 // src/get-time-in-seconds.ts
-import { Internals as Internals3 } from "remotion";
+import { Internals } from "remotion";
 var getTimeInSeconds = ({
   loop,
   mediaDurationInSeconds,
@@ -200,7 +97,7 @@ var getTimeInSeconds = ({
   if (mediaDurationInSeconds === null && loop && ifNoMediaDuration === "fail") {
     throw new Error(`Could not determine duration of ${src}, but "loop" was set.`);
   }
-  const loopDuration = loop ? Internals3.calculateMediaDuration({
+  const loopDuration = loop ? Internals.calculateMediaDuration({
     trimAfter,
     mediaDurationInFrames: mediaDurationInSeconds ? mediaDurationInSeconds * fps : Infinity,
     playbackRate: 1,
@@ -250,8 +147,135 @@ function withTimeout(promise, timeoutMs, errorMessage = "Operation timed out") {
   ]);
 }
 
-// src/video/media-player.ts
-var SEEK_THRESHOLD = 0.05;
+// src/helpers/round-to-4-digits.ts
+var roundTo4Digits = (timestamp) => {
+  return Math.round(timestamp * 1000) / 1000;
+};
+
+// src/video/video-preview-iterator.ts
+var createVideoIterator = (timeToSeek, videoSink) => {
+  let destroyed = false;
+  const iterator = videoSink.canvases(timeToSeek);
+  let lastReturnedFrame = null;
+  let iteratorEnded = false;
+  const getNextOrNullIfNotAvailable = async () => {
+    const next = iterator.next();
+    const result = await Promise.race([
+      next,
+      new Promise((resolve) => {
+        Promise.resolve().then(() => resolve());
+      })
+    ]);
+    if (!result) {
+      return {
+        type: "need-to-wait-for-it",
+        waitPromise: async () => {
+          const res = await next;
+          if (res.value) {
+            lastReturnedFrame = res.value;
+          } else {
+            iteratorEnded = true;
+          }
+          return res.value;
+        }
+      };
+    }
+    if (result.value) {
+      lastReturnedFrame = result.value;
+    } else {
+      iteratorEnded = true;
+    }
+    return {
+      type: "got-frame-or-end",
+      frame: result.value ?? null
+    };
+  };
+  const destroy = () => {
+    destroyed = true;
+    lastReturnedFrame = null;
+    iterator.return().catch(() => {
+      return;
+    });
+  };
+  const tryToSatisfySeek = async (time) => {
+    if (lastReturnedFrame) {
+      const frameTimestamp = roundTo4Digits(lastReturnedFrame.timestamp);
+      if (roundTo4Digits(time) < frameTimestamp) {
+        return {
+          type: "not-satisfied",
+          reason: `iterator is too far, most recently returned ${frameTimestamp}`
+        };
+      }
+      const frameEndTimestamp = roundTo4Digits(lastReturnedFrame.timestamp + lastReturnedFrame.duration);
+      const timestamp = roundTo4Digits(time);
+      if (frameTimestamp <= timestamp && frameEndTimestamp > timestamp) {
+        return {
+          type: "satisfied",
+          frame: lastReturnedFrame
+        };
+      }
+    }
+    if (iteratorEnded) {
+      if (lastReturnedFrame) {
+        return {
+          type: "satisfied",
+          frame: lastReturnedFrame
+        };
+      }
+      return {
+        type: "not-satisfied",
+        reason: "iterator ended"
+      };
+    }
+    while (true) {
+      const frame = await getNextOrNullIfNotAvailable();
+      if (frame.type === "need-to-wait-for-it") {
+        return {
+          type: "not-satisfied",
+          reason: "iterator did not have frame ready"
+        };
+      }
+      if (frame.type === "got-frame-or-end") {
+        if (frame.frame === null) {
+          iteratorEnded = true;
+          if (lastReturnedFrame) {
+            return {
+              type: "satisfied",
+              frame: lastReturnedFrame
+            };
+          }
+          return {
+            type: "not-satisfied",
+            reason: "iterator ended and did not have frame ready"
+          };
+        }
+        const frameTimestamp = roundTo4Digits(frame.frame.timestamp);
+        const frameEndTimestamp = roundTo4Digits(frame.frame.timestamp + frame.frame.duration);
+        const timestamp = roundTo4Digits(time);
+        if (frameTimestamp <= timestamp && frameEndTimestamp > timestamp) {
+          return {
+            type: "satisfied",
+            frame: frame.frame
+          };
+        }
+        continue;
+      }
+      throw new Error("Unreachable");
+    }
+  };
+  return {
+    destroy,
+    getNext: () => {
+      return iterator.next();
+    },
+    isDestroyed: () => {
+      return destroyed;
+    },
+    tryToSatisfySeek
+  };
+};
+
+// src/media-player.ts
 var AUDIO_BUFFER_TOLERANCE_THRESHOLD = 0.1;
 
 class MediaPlayer {
@@ -263,10 +287,12 @@ class MediaPlayer {
   audioStreamIndex;
   canvasSink = null;
   videoFrameIterator = null;
-  nextFrame = null;
+  debugStats = {
+    videoIteratorsCreated: 0,
+    framesRendered: 0
+  };
   audioSink = null;
   audioBufferIterator = null;
-  queuedAudioNodes = new Set;
   gainNode = null;
   currentVolume = 1;
   sharedAudioContext;
@@ -277,18 +303,15 @@ class MediaPlayer {
   fps;
   trimBefore;
   trimAfter;
-  animationFrameId = null;
-  videoAsyncId = 0;
-  audioAsyncId = 0;
   initialized = false;
   totalDuration;
   isBuffering = false;
   onBufferingChangeCallback;
-  audioBufferHealth = 0;
-  audioIteratorStarted = false;
-  HEALTHY_BUFER_THRESHOLD_SECONDS = 1;
   mediaEnded = false;
+  debugOverlay = false;
   onVideoFrameCallback;
+  initializationPromise = null;
+  bufferState;
   constructor({
     canvas,
     src,
@@ -299,7 +322,9 @@ class MediaPlayer {
     trimAfter,
     playbackRate,
     audioStreamIndex,
-    fps
+    fps,
+    debugOverlay,
+    bufferState
   }) {
     this.canvas = canvas ?? null;
     this.src = src;
@@ -311,6 +336,8 @@ class MediaPlayer {
     this.trimAfter = trimAfter;
     this.audioStreamIndex = audioStreamIndex ?? 0;
     this.fps = fps;
+    this.debugOverlay = debugOverlay;
+    this.bufferState = bufferState;
     if (canvas) {
       const context = canvas.getContext("2d", {
         alpha: true,
@@ -326,7 +353,7 @@ class MediaPlayer {
   }
   input = null;
   isReady() {
-    return this.initialized && Boolean(this.sharedAudioContext);
+    return this.initialized && Boolean(this.sharedAudioContext) && !this.input?.disposed;
   }
   hasAudio() {
     return Boolean(this.audioSink && this.sharedAudioContext && this.gainNode);
@@ -334,7 +361,15 @@ class MediaPlayer {
   isCurrentlyBuffering() {
     return this.isBuffering && Boolean(this.bufferingStartedAtMs);
   }
-  async initialize(startTimeUnresolved) {
+  isDisposalError() {
+    return this.input?.disposed === true;
+  }
+  initialize(startTimeUnresolved) {
+    const promise = this._initialize(startTimeUnresolved);
+    this.initializationPromise = promise;
+    return promise;
+  }
+  async _initialize(startTimeUnresolved) {
     try {
       const urlSource = new UrlSource(this.src);
       const input = new Input({
@@ -342,14 +377,20 @@ class MediaPlayer {
         formats: ALL_FORMATS
       });
       this.input = input;
+      if (input.disposed) {
+        return { type: "disposed" };
+      }
       try {
-        await this.input.getFormat();
+        await input.getFormat();
       } catch (error) {
+        if (this.isDisposalError()) {
+          return { type: "disposed" };
+        }
         const err = error;
         if (isNetworkError(err)) {
           throw error;
         }
-        Internals4.Log.error({ logLevel: this.logLevel, tag: "@remotion/media" }, `[MediaPlayer] Failed to recognize format for ${this.src}`, error);
+        Internals2.Log.error({ logLevel: this.logLevel, tag: "@remotion/media" }, `[MediaPlayer] Failed to recognize format for ${this.src}`, error);
         return { type: "unknown-container-format" };
       }
       const [durationInSeconds, videoTrack, audioTracks] = await Promise.all([
@@ -399,19 +440,23 @@ class MediaPlayer {
         this.audioSyncAnchor = this.sharedAudioContext.currentTime - startTime;
       }
       this.initialized = true;
-      await Promise.all([
-        this.startAudioIterator(startTime),
-        this.startVideoIterator(startTime)
-      ]);
-      this.startRenderLoop();
+      try {
+        this.startAudioIterator(startTime);
+        await this.startVideoIterator(startTime, this.currentSeekNonce);
+      } catch (error) {
+        if (this.isDisposalError()) {
+          return { type: "disposed" };
+        }
+        Internals2.Log.error({ logLevel: this.logLevel, tag: "@remotion/media" }, "[MediaPlayer] Failed to start audio and video iterators", error);
+      }
       return { type: "success", durationInSeconds };
     } catch (error) {
       const err = error;
       if (isNetworkError(err)) {
-        Internals4.Log.error({ logLevel: this.logLevel, tag: "@remotion/media" }, `[MediaPlayer] Network/CORS error for ${this.src}`, err);
+        Internals2.Log.error({ logLevel: this.logLevel, tag: "@remotion/media" }, `[MediaPlayer] Network/CORS error for ${this.src}`, err);
         return { type: "network-error" };
       }
-      Internals4.Log.error({ logLevel: this.logLevel, tag: "@remotion/media" }, "[MediaPlayer] Failed to initialize", error);
+      Internals2.Log.error({ logLevel: this.logLevel, tag: "@remotion/media" }, "[MediaPlayer] Failed to initialize", error);
       throw error;
     }
   }
@@ -420,20 +465,19 @@ class MediaPlayer {
       this.context.clearRect(0, 0, this.canvas.width, this.canvas.height);
     }
   }
-  cleanupAudioQueue() {
-    for (const node of this.queuedAudioNodes) {
-      node.stop();
-    }
-    this.queuedAudioNodes.clear();
-  }
-  async cleanAudioIteratorAndNodes() {
-    await this.audioBufferIterator?.return();
-    this.audioBufferIterator = null;
-    this.audioIteratorStarted = false;
-    this.audioBufferHealth = 0;
-    this.cleanupAudioQueue();
-  }
+  currentSeekNonce = 0;
+  seekPromiseChain = Promise.resolve();
   async seekTo(time) {
+    this.currentSeekNonce++;
+    const nonce = this.currentSeekNonce;
+    await this.seekPromiseChain;
+    this.seekPromiseChain = this.seekToDoNotCallDirectly(time, nonce);
+    await this.seekPromiseChain;
+  }
+  async seekToDoNotCallDirectly(time, nonce) {
+    if (nonce !== this.currentSeekNonce) {
+      return;
+    }
     if (!this.isReady())
       return;
     const newTime = getTimeInSeconds({
@@ -448,29 +492,29 @@ class MediaPlayer {
       src: this.src
     });
     if (newTime === null) {
-      this.videoAsyncId++;
-      this.nextFrame = null;
+      this.videoFrameIterator?.destroy();
+      this.videoFrameIterator = null;
       this.clearCanvas();
-      await this.cleanAudioIteratorAndNodes();
+      this.audioBufferIterator?.destroy();
+      this.audioBufferIterator = null;
       return;
     }
     const currentPlaybackTime = this.getPlaybackTime();
-    const isSignificantSeek = currentPlaybackTime === null || Math.abs(newTime - currentPlaybackTime) > SEEK_THRESHOLD;
-    if (isSignificantSeek) {
-      this.nextFrame = null;
-      this.audioSyncAnchor = this.sharedAudioContext.currentTime - newTime;
-      this.mediaEnded = false;
-      if (this.audioSink) {
-        await this.cleanAudioIteratorAndNodes();
-      }
-      await Promise.all([
-        this.startAudioIterator(newTime),
-        this.startVideoIterator(newTime)
-      ]);
+    if (currentPlaybackTime === newTime) {
+      return;
     }
-    if (!this.playing) {
-      this.render();
+    const satisfyResult = await this.videoFrameIterator?.tryToSatisfySeek(newTime);
+    if (satisfyResult?.type === "satisfied") {
+      this.drawFrame(satisfyResult.frame);
+      return;
     }
+    if (this.currentSeekNonce !== nonce) {
+      return;
+    }
+    this.mediaEnded = false;
+    this.audioSyncAnchor = this.sharedAudioContext.currentTime - newTime;
+    this.startAudioIterator(newTime);
+    this.startVideoIterator(newTime, nonce);
   }
   async play() {
     if (!this.isReady())
@@ -480,13 +524,11 @@ class MediaPlayer {
         await this.sharedAudioContext.resume();
       }
       this.playing = true;
-      this.startRenderLoop();
     }
   }
   pause() {
     this.playing = false;
-    this.cleanupAudioQueue();
-    this.stopRenderLoop();
+    this.audioBufferIterator?.cleanupAudioQueue();
   }
   setMuted(muted) {
     this.muted = muted;
@@ -504,6 +546,9 @@ class MediaPlayer {
       this.gainNode.gain.value = appliedVolume;
     }
   }
+  setDebugOverlay(debugOverlay) {
+    this.debugOverlay = debugOverlay;
+  }
   setPlaybackRate(rate) {
     this.playbackRate = rate;
   }
@@ -513,12 +558,18 @@ class MediaPlayer {
   setLoop(loop) {
     this.loop = loop;
   }
-  dispose() {
+  async dispose() {
+    this.initialized = false;
+    if (this.initializationPromise) {
+      try {
+        await this.initializationPromise;
+      } catch {}
+    }
     this.input?.dispose();
-    this.stopRenderLoop();
-    this.videoFrameIterator?.return();
-    this.cleanAudioIteratorAndNodes();
-    this.videoAsyncId++;
+    this.videoFrameIterator?.destroy();
+    this.videoFrameIterator = null;
+    this.audioBufferIterator?.destroy();
+    this.audioBufferIterator = null;
   }
   getPlaybackTime() {
     return this.sharedAudioContext.currentTime - this.audioSyncAnchor;
@@ -535,8 +586,8 @@ class MediaPlayer {
     } else {
       node.start(this.sharedAudioContext.currentTime, -delay);
     }
-    this.queuedAudioNodes.add(node);
-    node.onended = () => this.queuedAudioNodes.delete(node);
+    this.audioBufferIterator?.addQueuedAudioNode(node);
+    node.onended = () => this.audioBufferIterator?.removeQueuedAudioNode(node);
   }
   onBufferingChange(callback) {
     this.onBufferingChangeCallback = callback;
@@ -557,124 +608,65 @@ class MediaPlayer {
       }
     };
   }
-  canRenderVideo() {
-    return !this.hasAudio() || this.audioIteratorStarted && this.audioBufferHealth >= this.HEALTHY_BUFER_THRESHOLD_SECONDS;
-  }
-  startRenderLoop() {
-    if (this.animationFrameId !== null) {
-      return;
-    }
-    this.render();
-  }
-  stopRenderLoop() {
-    if (this.animationFrameId !== null) {
-      cancelAnimationFrame(this.animationFrameId);
-      this.animationFrameId = null;
-    }
-  }
-  render = () => {
-    if (this.isBuffering) {
-      this.maybeForceResumeFromBuffering();
-    }
-    if (this.shouldRenderFrame()) {
-      this.drawCurrentFrame();
-    }
-    if (this.playing) {
-      this.animationFrameId = requestAnimationFrame(this.render);
-    } else {
-      this.animationFrameId = null;
-    }
-  };
-  shouldRenderFrame() {
-    const playbackTime = this.getPlaybackTime();
-    if (playbackTime === null) {
-      return false;
-    }
-    return !this.isBuffering && this.canRenderVideo() && this.nextFrame !== null && this.nextFrame.timestamp <= playbackTime;
-  }
-  drawCurrentFrame() {
-    if (this.context && this.nextFrame) {
-      this.context.clearRect(0, 0, this.canvas.width, this.canvas.height);
-      this.context.drawImage(this.nextFrame.canvas, 0, 0);
+  drawFrame = (frame) => {
+    if (!this.context) {
+      throw new Error("Context not initialized");
     }
+    this.context.clearRect(0, 0, this.canvas.width, this.canvas.height);
+    this.context.drawImage(frame.canvas, 0, 0);
+    this.debugStats.framesRendered++;
+    this.drawDebugOverlay();
     if (this.onVideoFrameCallback && this.canvas) {
       this.onVideoFrameCallback(this.canvas);
     }
-    this.nextFrame = null;
-    this.updateNextFrame();
-  }
-  startAudioIterator = async (startFromSecond) => {
+    Internals2.Log.trace({ logLevel: this.logLevel, tag: "@remotion/media" }, `[MediaPlayer] Drew frame ${frame.timestamp.toFixed(3)}s`);
+  };
+  startAudioIterator = (startFromSecond) => {
     if (!this.hasAudio())
       return;
-    this.audioAsyncId++;
-    const currentAsyncId = this.audioAsyncId;
-    await this.audioBufferIterator?.return();
-    this.audioIteratorStarted = false;
-    this.audioBufferHealth = 0;
+    this.audioBufferIterator?.destroy();
     try {
-      this.audioBufferIterator = this.audioSink.buffers(startFromSecond);
-      this.runAudioIterator(startFromSecond, currentAsyncId);
+      const iterator = makeAudioIterator(this.audioSink, startFromSecond);
+      this.audioBufferIterator = iterator;
+      this.runAudioIterator(startFromSecond, iterator);
     } catch (error) {
-      Internals4.Log.error({ logLevel: this.logLevel, tag: "@remotion/media" }, "[MediaPlayer] Failed to start audio iterator", error);
+      if (this.isDisposalError()) {
+        return;
+      }
+      Internals2.Log.error({ logLevel: this.logLevel, tag: "@remotion/media" }, "[MediaPlayer] Failed to start audio iterator", error);
     }
   };
-  startVideoIterator = async (timeToSeek) => {
+  drawDebugOverlay() {
+    if (!this.debugOverlay)
+      return;
+    if (this.context && this.canvas) {
+      drawPreviewOverlay(this.context, this.debugStats, this.sharedAudioContext.state, this.sharedAudioContext.currentTime);
+    }
+  }
+  startVideoIterator = async (timeToSeek, nonce) => {
     if (!this.canvasSink) {
       return;
     }
-    this.videoAsyncId++;
-    const currentAsyncId = this.videoAsyncId;
-    this.videoFrameIterator?.return().catch(() => {
+    this.videoFrameIterator?.destroy();
+    const iterator = createVideoIterator(timeToSeek, this.canvasSink);
+    this.debugStats.videoIteratorsCreated++;
+    this.videoFrameIterator = iterator;
+    const delayHandle = this.bufferState?.delayPlayback();
+    const frameResult = await iterator.getNext();
+    delayHandle?.unblock();
+    if (iterator.isDestroyed()) {
       return;
-    });
-    this.videoFrameIterator = this.canvasSink.canvases(timeToSeek);
-    try {
-      const firstFrame = (await this.videoFrameIterator.next()).value ?? null;
-      const secondFrame = (await this.videoFrameIterator.next()).value ?? null;
-      if (currentAsyncId !== this.videoAsyncId) {
-        return;
-      }
-      if (firstFrame && this.context) {
-        Internals4.Log.trace({ logLevel: this.logLevel, tag: "@remotion/media" }, `[MediaPlayer] Drew initial frame ${firstFrame.timestamp.toFixed(3)}s`);
-        this.context.drawImage(firstFrame.canvas, 0, 0);
-        if (this.onVideoFrameCallback && this.canvas) {
-          this.onVideoFrameCallback(this.canvas);
-        }
-      }
-      this.nextFrame = secondFrame ?? null;
-      if (secondFrame) {
-        Internals4.Log.trace({ logLevel: this.logLevel, tag: "@remotion/media" }, `[MediaPlayer] Buffered next frame ${secondFrame.timestamp.toFixed(3)}s`);
-      }
-    } catch (error) {
-      Internals4.Log.error({ logLevel: this.logLevel, tag: "@remotion/media" }, "[MediaPlayer] Failed to start video iterator", error);
     }
-  };
-  updateNextFrame = async () => {
-    if (!this.videoFrameIterator) {
+    if (nonce !== this.currentSeekNonce) {
       return;
     }
-    try {
-      while (true) {
-        const newNextFrame = (await this.videoFrameIterator.next()).value ?? null;
-        if (!newNextFrame) {
-          this.mediaEnded = true;
-          break;
-        }
-        const playbackTime = this.getPlaybackTime();
-        if (playbackTime === null) {
-          continue;
-        }
-        if (newNextFrame.timestamp <= playbackTime) {
-          continue;
-        } else {
-          this.nextFrame = newNextFrame;
-          Internals4.Log.trace({ logLevel: this.logLevel, tag: "@remotion/media" }, `[MediaPlayer] Buffered next frame ${newNextFrame.timestamp.toFixed(3)}s`);
-          break;
-        }
-      }
-    } catch (error) {
-      Internals4.Log.error({ logLevel: this.logLevel, tag: "@remotion/media" }, "[MediaPlayer] Failed to update next frame", error);
+    if (this.videoFrameIterator.isDestroyed()) {
+      return;
     }
+    if (frameResult.value) {
+      this.audioSyncAnchor = this.sharedAudioContext.currentTime - frameResult.value.timestamp;
+      this.drawFrame(frameResult.value);
+    } else {}
   };
   bufferingStartedAtMs = null;
   minBufferingTimeoutMs = 500;
@@ -696,38 +688,27 @@ class MediaPlayer {
     const now = performance.now();
     const bufferingDuration = now - this.bufferingStartedAtMs;
     const minTimeElapsed = bufferingDuration >= this.minBufferingTimeoutMs;
-    const bufferHealthy = currentBufferDuration >= this.HEALTHY_BUFER_THRESHOLD_SECONDS;
+    const bufferHealthy = currentBufferDuration >= HEALTHY_BUFFER_THRESHOLD_SECONDS;
     if (minTimeElapsed && bufferHealthy) {
-      Internals4.Log.trace({ logLevel: this.logLevel, tag: "@remotion/media" }, `[MediaPlayer] Resuming from buffering after ${bufferingDuration}ms - buffer recovered`);
+      Internals2.Log.trace({ logLevel: this.logLevel, tag: "@remotion/media" }, `[MediaPlayer] Resuming from buffering after ${bufferingDuration}ms - buffer recovered`);
       this.setBufferingState(false);
     }
   }
-  maybeForceResumeFromBuffering() {
-    if (!this.isCurrentlyBuffering())
-      return;
-    const now = performance.now();
-    const bufferingDuration = now - this.bufferingStartedAtMs;
-    const forceTimeout = bufferingDuration > this.minBufferingTimeoutMs * 10;
-    if (forceTimeout) {
-      Internals4.Log.trace({ logLevel: this.logLevel, tag: "@remotion/media" }, `[MediaPlayer] Force resuming from buffering after ${bufferingDuration}ms`);
-      this.setBufferingState(false);
-    }
-  }
-  runAudioIterator = async (startFromSecond, audioAsyncId) => {
-    if (!this.hasAudio() || !this.audioBufferIterator)
+  runAudioIterator = async (startFromSecond, audioIterator) => {
+    if (!this.hasAudio())
       return;
     try {
       let totalBufferDuration = 0;
       let isFirstBuffer = true;
-      this.audioIteratorStarted = true;
+      audioIterator.setAudioIteratorStarted(true);
       while (true) {
-        if (audioAsyncId !== this.audioAsyncId) {
+        if (audioIterator.isDestroyed()) {
           return;
         }
         const BUFFERING_TIMEOUT_MS = 50;
         let result;
         try {
-          result = await withTimeout(this.audioBufferIterator.next(), BUFFERING_TIMEOUT_MS, "Iterator timeout");
+          result = await withTimeout(audioIterator.getNext(), BUFFERING_TIMEOUT_MS, "Iterator timeout");
         } catch (error) {
           if (error instanceof TimeoutError && !this.mediaEnded) {
             this.setBufferingState(true);
@@ -741,7 +722,7 @@ class MediaPlayer {
         }
         const { buffer, timestamp, duration } = result.value;
         totalBufferDuration += duration;
-        this.audioBufferHealth = Math.max(0, totalBufferDuration / this.playbackRate);
+        audioIterator.setAudioBufferHealth(Math.max(0, totalBufferDuration / this.playbackRate));
         this.maybeResumeFromBuffering(totalBufferDuration / this.playbackRate);
         if (this.playing) {
           if (isFirstBuffer) {
@@ -772,11 +753,178 @@ class MediaPlayer {
         }
       }
     } catch (error) {
-      Internals4.Log.error({ logLevel: this.logLevel, tag: "@remotion/media" }, "[MediaPlayer] Failed to run audio iterator", error);
+      if (this.isDisposalError()) {
+        return;
+      }
+      Internals2.Log.error({ logLevel: this.logLevel, tag: "@remotion/media" }, "[MediaPlayer] Failed to run audio iterator", error);
     }
   };
 }
 
+// src/show-in-timeline.ts
+import { useMemo } from "react";
+import { Internals as Internals3, useVideoConfig } from "remotion";
+var useLoopDisplay = ({
+  loop,
+  mediaDurationInSeconds,
+  playbackRate,
+  trimAfter,
+  trimBefore
+}) => {
+  const { durationInFrames: compDuration, fps } = useVideoConfig();
+  const loopDisplay = useMemo(() => {
+    if (!loop || !mediaDurationInSeconds) {
+      return;
+    }
+    const durationInFrames = Internals3.calculateMediaDuration({
+      mediaDurationInFrames: mediaDurationInSeconds * fps,
+      playbackRate,
+      trimAfter,
+      trimBefore
+    });
+    const maxTimes = compDuration / durationInFrames;
+    return {
+      numberOfTimes: maxTimes,
+      startOffset: 0,
+      durationInFrames
+    };
+  }, [
+    compDuration,
+    fps,
+    loop,
+    mediaDurationInSeconds,
+    playbackRate,
+    trimAfter,
+    trimBefore
+  ]);
+  return loopDisplay;
+};
+
+// src/use-media-in-timeline.ts
+import { useContext, useEffect, useState } from "react";
+import { Internals as Internals4, useCurrentFrame } from "remotion";
+var useMediaInTimeline = ({
+  volume,
+  mediaVolume,
+  src,
+  mediaType,
+  playbackRate,
+  displayName,
+  stack,
+  showInTimeline,
+  premountDisplay,
+  postmountDisplay,
+  loopDisplay,
+  trimBefore,
+  trimAfter
+}) => {
+  const parentSequence = useContext(Internals4.SequenceContext);
+  const startsAt = Internals4.useMediaStartsAt();
+  const { registerSequence, unregisterSequence } = useContext(Internals4.SequenceManager);
+  const [sequenceId] = useState(() => String(Math.random()));
+  const [mediaId] = useState(() => String(Math.random()));
+  const frame = useCurrentFrame();
+  const {
+    volumes,
+    duration,
+    doesVolumeChange,
+    nonce,
+    rootId,
+    isStudio,
+    finalDisplayName
+  } = Internals4.useBasicMediaInTimeline({
+    volume,
+    mediaVolume,
+    mediaType,
+    src,
+    displayName,
+    trimBefore,
+    trimAfter,
+    playbackRate
+  });
+  useEffect(() => {
+    if (!src) {
+      throw new Error("No src passed");
+    }
+    if (!isStudio && window.process?.env?.NODE_ENV !== "test") {
+      return;
+    }
+    if (!showInTimeline) {
+      return;
+    }
+    const loopIteration = loopDisplay ? Math.floor(frame / loopDisplay.durationInFrames) : 0;
+    if (loopDisplay) {
+      registerSequence({
+        type: "sequence",
+        premountDisplay,
+        postmountDisplay,
+        parent: parentSequence?.id ?? null,
+        displayName: finalDisplayName,
+        rootId,
+        showInTimeline: true,
+        nonce,
+        loopDisplay,
+        stack,
+        from: 0,
+        duration,
+        id: sequenceId
+      });
+    }
+    registerSequence({
+      type: mediaType,
+      src,
+      id: mediaId,
+      duration: loopDisplay?.durationInFrames ?? duration,
+      from: loopDisplay ? loopIteration * loopDisplay.durationInFrames : 0,
+      parent: loopDisplay ? sequenceId : parentSequence?.id ?? null,
+      displayName: finalDisplayName,
+      rootId,
+      volume: volumes,
+      showInTimeline: true,
+      nonce,
+      startMediaFrom: 0 - startsAt,
+      doesVolumeChange,
+      loopDisplay: undefined,
+      playbackRate,
+      stack,
+      premountDisplay: null,
+      postmountDisplay: null
+    });
+    return () => {
+      if (loopDisplay) {
+        unregisterSequence(sequenceId);
+      }
+      unregisterSequence(mediaId);
+    };
+  }, [
+    doesVolumeChange,
+    duration,
+    finalDisplayName,
+    isStudio,
+    loopDisplay,
+    mediaId,
+    mediaType,
+    nonce,
+    parentSequence?.id,
+    playbackRate,
+    postmountDisplay,
+    premountDisplay,
+    registerSequence,
+    rootId,
+    sequenceId,
+    showInTimeline,
+    src,
+    stack,
+    startsAt,
+    unregisterSequence,
+    volumes,
+    frame
+  ]);
+  return {
+    id: mediaId
+  };
+};
+
 // src/audio/audio-for-preview.tsx
 import { jsx } from "react/jsx-runtime";
 var {
@@ -878,7 +1026,9 @@ var NewAudioForPreview = ({
         fps: videoConfig.fps,
         canvas: null,
         playbackRate,
-        audioStreamIndex: audioStreamIndex ?? 0
+        audioStreamIndex: audioStreamIndex ?? 0,
+        debugOverlay: false,
+        bufferState: buffer
       });
       mediaPlayerRef.current = player;
       player.initialize(currentTimeRef.current).then((result) => {
@@ -950,7 +1100,8 @@ var NewAudioForPreview = ({
     playbackRate,
     videoConfig.fps,
     audioStreamIndex,
-    disallowFallbackToHtml5Audio
+    disallowFallbackToHtml5Audio,
+    buffer
   ]);
   useEffect2(() => {
     const audioPlayer = mediaPlayerRef.current;
@@ -1297,7 +1448,7 @@ var warnAboutMatroskaOnce = (src, logLevel) => {
   warned[src] = true;
   Internals6.Log.warn({ logLevel, tag: "@remotion/media" }, `Audio from ${src} will need to be read from the beginning. https://www.remotion.dev/docs/media/support#matroska-limitation`);
 };
-var makeAudioIterator = ({
+var makeAudioIterator2 = ({
   audioSampleSink,
   isMatroska,
   startTimestamp,
@@ -1422,7 +1573,7 @@ var makeAudioManager = () => {
     actualMatroskaTimestamps,
     logLevel
   }) => {
-    const iterator = makeAudioIterator({
+    const iterator = makeAudioIterator2({
       audioSampleSink,
       isMatroska,
       startTimestamp: timeInSeconds,
@@ -1584,9 +1735,6 @@ import {
 
 // src/video-extraction/keyframe-bank.ts
 import { Internals as Internals8 } from "remotion";
-var roundTo4Digits = (timestamp) => {
-  return Math.round(timestamp * 1000) / 1000;
-};
 var makeKeyframeBank = ({
   startTimestampInSeconds,
   endTimestampInSeconds,
@@ -2891,7 +3039,14 @@ Internals13.addSequenceStackTraces(Audio);
 import { Internals as Internals16, useRemotionEnvironment as useRemotionEnvironment4 } from "remotion";
 
 // src/video/video-for-preview.tsx
-import { useContext as useContext4, useEffect as useEffect3, useMemo as useMemo4, useRef as useRef2, useState as useState4 } from "react";
+import {
+  useContext as useContext4,
+  useEffect as useEffect3,
+  useLayoutEffect as useLayoutEffect2,
+  useMemo as useMemo4,
+  useRef as useRef2,
+  useState as useState4
+} from "react";
 import { Html5Video, Internals as Internals14, useBufferState as useBufferState2, useCurrentFrame as useCurrentFrame4 } from "remotion";
 import { jsx as jsx4 } from "react/jsx-runtime";
 var {
@@ -2925,7 +3080,8 @@ var VideoForPreview = ({
   stack,
   disallowFallbackToOffthreadVideo,
   fallbackOffthreadVideoProps,
-  audioStreamIndex
+  audioStreamIndex,
+  debugOverlay
 }) => {
   const src = usePreload2(unpreloadedSrc);
   const canvasRef = useRef2(null);
@@ -2977,9 +3133,6 @@ var VideoForPreview = ({
   if (!videoConfig) {
     throw new Error("No video config found");
   }
-  if (!src) {
-    throw new TypeError("No `src` was passed to <NewVideoForPreview>.");
-  }
   const currentTime = frame / videoConfig.fps;
   const currentTimeRef = useRef2(currentTime);
   currentTimeRef.current = currentTime;
@@ -3002,10 +3155,15 @@ var VideoForPreview = ({
         trimBefore,
         fps: videoConfig.fps,
         playbackRate,
-        audioStreamIndex
+        audioStreamIndex,
+        debugOverlay,
+        bufferState: buffer
       });
       mediaPlayerRef.current = player;
       player.initialize(currentTimeRef.current).then((result) => {
+        if (result.type === "disposed") {
+          return;
+        }
         if (result.type === "unknown-container-format") {
           if (disallowFallbackToOffthreadVideo) {
             throw new Error(`Unknown container format ${preloadedSrc}, and 'disallowFallbackToOffthreadVideo' was set.`);
@@ -3043,16 +3201,16 @@ var VideoForPreview = ({
           setMediaDurationInSeconds(result.durationInSeconds);
         }
       }).catch((error) => {
-        Internals14.Log.error({ logLevel, tag: "@remotion/media" }, "[NewVideoForPreview] Failed to initialize MediaPlayer", error);
+        Internals14.Log.error({ logLevel, tag: "@remotion/media" }, "[VideoForPreview] Failed to initialize MediaPlayer", error);
         setShouldFallbackToNativeVideo(true);
       });
     } catch (error) {
-      Internals14.Log.error({ logLevel, tag: "@remotion/media" }, "[NewVideoForPreview] MediaPlayer initialization failed", error);
+      Internals14.Log.error({ logLevel, tag: "@remotion/media" }, "[VideoForPreview] MediaPlayer initialization failed", error);
       setShouldFallbackToNativeVideo(true);
     }
     return () => {
       if (mediaPlayerRef.current) {
-        Internals14.Log.trace({ logLevel, tag: "@remotion/media" }, `[NewVideoForPreview] Disposing MediaPlayer`);
+        Internals14.Log.trace({ logLevel, tag: "@remotion/media" }, `[VideoForPreview] Disposing MediaPlayer`);
         mediaPlayerRef.current.dispose();
         mediaPlayerRef.current = null;
       }
@@ -3069,7 +3227,9 @@ var VideoForPreview = ({
     videoConfig.fps,
     playbackRate,
     disallowFallbackToOffthreadVideo,
-    audioStreamIndex
+    audioStreamIndex,
+    debugOverlay,
+    buffer
   ]);
   const classNameValue = useMemo4(() => {
     return [Internals14.OBJECTFIT_CONTAIN_CLASS_NAME, className].filter(Internals14.truthy).join(" ");
@@ -3080,18 +3240,18 @@ var VideoForPreview = ({
       return;
     if (playing) {
       mediaPlayer.play().catch((error) => {
-        Internals14.Log.error({ logLevel, tag: "@remotion/media" }, "[NewVideoForPreview] Failed to play", error);
+        Internals14.Log.error({ logLevel, tag: "@remotion/media" }, "[VideoForPreview] Failed to play", error);
       });
     } else {
       mediaPlayer.pause();
     }
   }, [playing, logLevel, mediaPlayerReady]);
-  useEffect3(() => {
+  useLayoutEffect2(() => {
     const mediaPlayer = mediaPlayerRef.current;
     if (!mediaPlayer || !mediaPlayerReady)
       return;
     mediaPlayer.seekTo(currentTime);
-    Internals14.Log.trace({ logLevel, tag: "@remotion/media" }, `[NewVideoForPreview] Updating target time to ${currentTime.toFixed(3)}s`);
+    Internals14.Log.trace({ logLevel, tag: "@remotion/media" }, `[VideoForPreview] Updating target time to ${currentTime.toFixed(3)}s`);
   }, [currentTime, logLevel, mediaPlayerReady]);
   useEffect3(() => {
     const mediaPlayer = mediaPlayerRef.current;
@@ -3101,11 +3261,11 @@ var VideoForPreview = ({
     const unsubscribe = mediaPlayer.onBufferingChange((newBufferingState) => {
       if (newBufferingState && !currentBlock) {
         currentBlock = buffer.delayPlayback();
-        Internals14.Log.trace({ logLevel, tag: "@remotion/media" }, "[NewVideoForPreview] MediaPlayer buffering - blocking Remotion playback");
+        Internals14.Log.trace({ logLevel, tag: "@remotion/media" }, "[VideoForPreview] MediaPlayer buffering - blocking Remotion playback");
       } else if (!newBufferingState && currentBlock) {
         currentBlock.unblock();
         currentBlock = null;
-        Internals14.Log.trace({ logLevel, tag: "@remotion/media" }, "[NewVideoForPreview] MediaPlayer unbuffering - unblocking Remotion playback");
+        Internals14.Log.trace({ logLevel, tag: "@remotion/media" }, "[VideoForPreview] MediaPlayer unbuffering - unblocking Remotion playback");
       }
     });
     return () => {
@@ -3130,6 +3290,13 @@ var VideoForPreview = ({
     }
     mediaPlayer.setVolume(userPreferredVolume);
   }, [userPreferredVolume, mediaPlayerReady]);
+  useEffect3(() => {
+    const mediaPlayer = mediaPlayerRef.current;
+    if (!mediaPlayer || !mediaPlayerReady) {
+      return;
+    }
+    mediaPlayer.setDebugOverlay(debugOverlay);
+  }, [debugOverlay, mediaPlayerReady]);
   const effectivePlaybackRate = useMemo4(() => playbackRate * globalPlaybackRate, [playbackRate, globalPlaybackRate]);
   useEffect3(() => {
     const mediaPlayer = mediaPlayerRef.current;
@@ -3198,7 +3365,7 @@ var VideoForPreview = ({
 // src/video/video-for-rendering.tsx
 import {
   useContext as useContext5,
-  useLayoutEffect as useLayoutEffect2,
+  useLayoutEffect as useLayoutEffect3,
   useMemo as useMemo5,
   useRef as useRef3,
   useState as useState5
@@ -3257,7 +3424,7 @@ var VideoForRendering = ({
   const [replaceWithOffthreadVideo, setReplaceWithOffthreadVideo] = useState5(false);
   const audioEnabled = Internals15.useAudioEnabled();
   const videoEnabled = Internals15.useVideoEnabled();
-  useLayoutEffect2(() => {
+  useLayoutEffect3(() => {
     if (!canvasRef.current) {
       return;
     }
@@ -3514,7 +3681,8 @@ var InnerVideo = ({
   volume,
   stack,
   toneFrequency,
-  showInTimeline
+  showInTimeline,
+  debugOverlay
 }) => {
   const environment = useRemotionEnvironment4();
   if (typeof src !== "string") {
@@ -3575,7 +3743,8 @@ var InnerVideo = ({
     trimBefore: trimBeforeValue,
     stack: stack ?? null,
     disallowFallbackToOffthreadVideo,
-    fallbackOffthreadVideoProps
+    fallbackOffthreadVideoProps,
+    debugOverlay: debugOverlay ?? false
   });
 };
 var Video = ({
@@ -3599,7 +3768,8 @@ var Video = ({
   trimBefore,
   volume,
   stack,
-  toneFrequency
+  toneFrequency,
+  debugOverlay
 }) => {
   return /* @__PURE__ */ jsx6(InnerVideo, {
     audioStreamIndex: audioStreamIndex ?? 0,
@@ -3622,7 +3792,8 @@ var Video = ({
     trimBefore,
     volume: volume ?? 1,
     toneFrequency: toneFrequency ?? 1,
-    stack
+    stack,
+    debugOverlay: debugOverlay ?? false
   });
 };
 Internals16.addSequenceStackTraces(Video);