@banou/media-player 0.8.12 → 0.8.15

package/dist/react/player.d.ts

@@ -17,6 +17,7 @@ export declare const Player: import("@videojs/react").CreatePlayerResult<import(
     togglePictureInPicture: (() => void) | null;
     pictureInPictureMode: import("../engine").PictureInPictureMode | null;
     burnedInSubtitles: boolean;
+    requestSeek?: (time: number) => void;
     playbackError: unknown;
     playbackErrors: import("./source-feature").PlaybackErrorEntry[];
     ready: boolean;

package/dist/react/source-feature.d.ts

@@ -115,6 +115,18 @@ export type SourceState = {
     pictureInPictureMode: PictureInPictureMode | null;
     /** Burn-in only. True while the composite is the picture on screen. */
     burnedInSubtitles: boolean;
+    /**
+     * Move the playhead, letting the pipeline get the data there first.
+     *
+     * The chrome calls this instead of the player's own `seek`, because an element that demuxes into a
+     * hole is what wedges firefox's decoder: the underrun drains it and nothing ever flushes it again.
+     * Waiting is bounded by a deadline, so a source that cannot answer in time costs that deadline and
+     * not the whole read.
+     *
+     * Undefined for a media this player does not own, where there is no pipeline to prepare and the
+     * caller should seek directly.
+     */
+    requestSeek?: (time: number) => void;
     /** Set when the pipeline fails. Cleared when it recovers. */
     playbackError: unknown;
     /**
@@ -190,6 +202,18 @@ export declare const sourceFeature: import("@videojs/react").PlayerFeature<{
     pictureInPictureMode: PictureInPictureMode | null;
     /** Burn-in only. True while the composite is the picture on screen. */
     burnedInSubtitles: boolean;
+    /**
+     * Move the playhead, letting the pipeline get the data there first.
+     *
+     * The chrome calls this instead of the player's own `seek`, because an element that demuxes into a
+     * hole is what wedges firefox's decoder: the underrun drains it and nothing ever flushes it again.
+     * Waiting is bounded by a deadline, so a source that cannot answer in time costs that deadline and
+     * not the whole read.
+     *
+     * Undefined for a media this player does not own, where there is no pipeline to prepare and the
+     * caller should seek directly.
+     */
+    requestSeek?: (time: number) => void;
     /** Set when the pipeline fails. Cleared when it recovers. */
     playbackError: unknown;
     /**

package/dist/react/video-player.d.ts

@@ -93,6 +93,14 @@ export type MediaPlayerLocalOptions = CommonOptions & MediaPlayerSource & {
     /** Fallback face for `liberation sans`, used when a subtitle track names a font the file does not carry. */
     defaultFontUrl?: string;
     bufferSize?: number;
+    /**
+     * How long a seek waits for its own data before the playhead moves anyway, in ms. Default 500.
+     *
+     * Seeking into a hole is what wedges firefox's decoder, so the pipeline is asked for the target
+     * first. This is the ceiling on that wait, since a read over a torrent has none of its own. Set
+     * it to 0 to seek immediately and rely on the recovery instead.
+     */
+    seekPrepareBudgetMs?: number;
     /** Byte spans available, painted on the seekbar and informing the thumbnail generator. */
     downloadedRanges?: DownloadedRange[];
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/media-player",
-  "version": "0.8.12",
+  "version": "0.8.15",
   "description": "A video player for containers and codecs the browser cannot play natively, remuxed on the fly",
   "type": "module",
   "main": "dist/index.js",

package/src/lib/engine/playback.ts

@@ -36,6 +36,15 @@ export type PlaybackOptions = {
 
 export type PlaybackController = {
   destroy: () => void
+  /**
+   * Get the data for a position in place BEFORE the playhead moves there.
+   *
+   * Resolves at once when that position already has data. The caller decides how long to wait,
+   * because this can take as long as a read, which over a torrent has no ceiling.
+   */
+  prepareSeek: (time: number) => Promise<void>
+  /** The element this pipeline drives, so a caller can read what actually got buffered. */
+  videoElement: HTMLVideoElement
   selectSubtitleStream: (streamIndex: number | undefined) => void
   /** Keyframe index of the input, which is what maps a downloaded byte range onto the timeline. */
   indexes: MediaIndex[]
@@ -74,6 +83,16 @@ const MAX_APPEND_ATTEMPTS = 5
 const SOURCE_OPEN_TIMEOUT = 15_000
 // how far past the playhead a range may start and still count as the one holding it
 const BOUNDARY_SLACK = 1
+/*
+ * Seconds of data a seek target needs behind it before the playhead is allowed to move there.
+ *
+ * Covering the target instant is not enough: the element plays through a one chunk island in well
+ * under a second and runs dry, and that underrun drains firefox's decoder just as a seek into a hole
+ * does. Measured in production, six seeks that all reported themselves prepared still wedged.
+ */
+const SEEK_RUNWAY = 3
+// reads allowed to build that runway, so a source that answers with nothing cannot spin here
+const SEEK_RUNWAY_READS = 12
 // the fastest a drag may move the consumer's download window
 const SEEK_REPORT_MS = 200
 // quiet time that ends a drag: pointermoves arrive every few ms, so this cannot cut one in half
@@ -210,6 +229,18 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
 
     let reading = false
     let seeking = false
+    // how many prepares are in flight, so eviction knows not to delete what they are fetching
+    let preparing = 0
+    /*
+     * Where buffering should aim while a seek is being prepared.
+     *
+     * The playhead has not moved there yet, so anything anchored on `currentTime` is aiming at the
+     * position being left behind. `needsData` in particular would answer for the old position and
+     * stop reading, which is how a prepare came to leave a one chunk island: enough to cover the
+     * target instant, and nowhere near enough to play from.
+     */
+    let prepareTarget: number | undefined
+    const bufferAnchor = () => prepareTarget ?? videoElement.currentTime
     let finished = false
     // libav aborts the running task when a new one starts, so both flags need a generation token
     let readGeneration = 0
@@ -237,6 +268,18 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
     }
 
     const evict = async (tight = false) => {
+      /*
+       * Hold off while data is being put in place for a position the playhead has not reached.
+       *
+       * Eviction is anchored on the playhead, and `prepareSeek` deliberately appends far from it, so
+       * running now deletes exactly what was just fetched. The 100ms interval below made that a
+       * certainty. The benchmark caught it as prepared seeks being the SLOWEST arm, which is the
+       * opposite of the point.
+       *
+       * `tight` still runs, because that one is the answer to a quota refusal and has to be able to
+       * free space no matter what else is happening.
+       */
+      if (preparing > 0 && !tight) return
       const ct = videoElement.currentTime
       const pre = tight ? PRE_EVICT_TIGHT : PRE_EVICT
       const post = tight ? POST_EVICT_TIGHT : POST_EVICT
@@ -251,10 +294,20 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
     const needsData = () => {
       const ranges = getTimeRanges(sourceBuffer)
       if (!ranges.length) return true
-      const ct = videoElement.currentTime
-      // never read past what evict() keeps
-      if (Math.max(...ranges.map((r) => r.end)) >= ct + POST_EVICT) return false
+      const ct = bufferAnchor()
       const range = ranges.find((r) => r.start <= ct + BOUNDARY_SLACK && ct < r.end)
+      /*
+       * Never read past what evict() keeps, measured on the run holding the anchor rather than
+       * across every island.
+       *
+       * Taking the max end over ALL ranges meant one stale island far ahead could refuse a read
+       * right where the playhead was about to be. Repeated seeking is exactly how those islands
+       * appear, and eviction is suppressed while a seek is being prepared, so they survive to do it.
+       * Seen in production as forward seeks getting a 4s runway while every BACKWARD seek collapsed
+       * to 1.0s, then 0.5s, then 0.3s, and wedged: the island left out at ~760s was past
+       * `target + POST_EVICT` for every one of them.
+       */
+      if (range && range.end >= ct + POST_EVICT) return false
       return !range || range.end < ct + BUFFER_TARGET
     }
 
@@ -375,6 +428,75 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
      */
     const alreadyPlayable = (time: number) => time >= lastSeekPosition && !!playheadRange()
 
+    /** Whether a GIVEN time has data behind it, as opposed to whether the playhead does. */
+    const playableAt = (time: number) =>
+      getTimeRanges(sourceBuffer).some((r) => r.start <= time + BOUNDARY_SLACK && time < r.end)
+
+    /**
+     * Put the data in place for a position the playhead has NOT moved to yet.
+     *
+     * Firefox wedges its own decoder when the element demuxes into a hole: the underrun requests a
+     * drain, the drain completes, the re-prime that would flush the decoder never runs, and every
+     * packet after that comes back `avcodec_send_packet error: End of file`. Seeking only after the
+     * target has data removes the hole, and with it the drain and the whole failure.
+     *
+     * Measured on a standalone rig against a real 1080p stream: 7 wedges in 7 runs seeking the
+     * ordinary way, 0 in 4 seeking this way. The control matters, because appending first also
+     * delays the seek: delaying the seek by the same amount while appending nothing still wedged 4
+     * out of 4, so it is the data and not the delay.
+     *
+     * Returns as soon as there is nothing to wait for, so a seek into buffered ground costs nothing.
+     * The CALLER owns the deadline: this can take as long as a read takes, and over a torrent that
+     * is unbounded.
+     */
+    /** Seconds of contiguous data past a position that make it safe to play from. */
+    const runwayFrom = (time: number) => {
+      const range = getTimeRanges(sourceBuffer).find((r) => r.start <= time + BOUNDARY_SLACK && time < r.end)
+      return range ? range.end - time : 0
+    }
+
+    const prepareSeek = async (time: number) => {
+      if (destroyed) return
+      if (runwayFrom(time) >= SEEK_RUNWAY) return
+      finished = false
+      preparing++
+      prepareTarget = time
+      try {
+        if (!playableAt(time)) await seekTo(time)
+        /*
+         * Captured AFTER the seek, never before.
+         *
+         * `seekTo` bumps `seekGeneration` itself, so a generation read before it is stale the moment
+         * it returns and every staleness check below fails on its first pass. That silently disabled
+         * this entire loop: prepares came back in ~170ms with a 0.5s to 1.9s island and the runway
+         * was never built at all.
+         */
+        const generation = seekGeneration
+        /*
+         * Then keep reading until there is something to PLAY, not merely something to land on.
+         *
+         * `remuxer.seek` returns a single chunk, so the first version of this left a small island:
+         * the element arrived on covered ground, played through it in well under a second, and ran
+         * dry there. That underrun drains the decoder exactly as a seek into a hole would, and it
+         * wedged in production with every seek reporting itself as prepared. Preparing a point was
+         * never the requirement; preparing a runway is.
+         *
+         * Bounded twice over: by the runway being reached, and by a read that returns nothing new.
+         * The caller's deadline bounds the wall clock on top of that.
+         */
+        for (let attempt = 0; attempt < SEEK_RUNWAY_READS; attempt++) {
+          if (destroyed || generation !== seekGeneration || finished) break
+          if (runwayFrom(time) >= SEEK_RUNWAY) break
+          const before = runwayFrom(time)
+          await pump()
+          if (runwayFrom(time) <= before) break
+        }
+      } finally {
+        preparing--
+        if (prepareTarget === time) prepareTarget = undefined
+      }
+    }
+
     /**
      * Where a drag reaches the consumer, at a rate a consumer can act on.
      *
@@ -437,6 +559,15 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
       const dragging = now - lastSeekingAt < DRAG_SETTLE_MS
       lastSeekingAt = now
       if (alreadyPlayable(time)) return
+      /*
+       * A seek for exactly this position is already running, so let it finish.
+       *
+       * `prepareSeek` starts one BEFORE the playhead moves, and the caller moves the playhead anyway
+       * once its budget runs out. Without this, the move fires `seeking`, which starts the identical
+       * read again and bumps the generation, throwing away everything the first one had done. The
+       * benchmark caught it as a seek that took twice as long as seeking the old way.
+       */
+      if (seeking && Math.abs(time - lastSeekPosition) < 0.001) return
       finished = false
       if (dragTimer) clearTimeout(dragTimer)
       if (!dragging) {
@@ -501,6 +632,8 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
 
     return {
       destroy: runTeardown,
+      prepareSeek,
+      videoElement,
       selectSubtitleStream: (streamIndex: number | undefined) => subtitles.selectStream(streamIndex),
       indexes: metadata.indexes ?? [],
       duration: metadata.info.input.duration,

package/src/lib/react/components/control-bar.tsx

@@ -190,6 +190,9 @@ export const ControlBar = () => {
   const pictureInPictureMode = usePlayer((state) => state.pictureInPictureMode)
   const burnedInSubtitles = usePlayer((state) => state.burnedInSubtitles)
   const subtitleTracks = usePlayer((state) => state.subtitleTracks)
+  // Keyboard seeks go through the same door as the seek bar: data first, then the playhead. See
+  // `requestSeek` on the source state for why an element that seeks into a hole is the problem.
+  const requestSeek = usePlayer((state) => state.requestSeek)
   const [volumeElement, setVolumeElement] = useState<HTMLButtonElement | null>(null)
 
   const burnIn = pictureInPictureMode === 'burn-in'
@@ -213,6 +216,7 @@ export const ControlBar = () => {
   }, [player])
 
   useEffect(() => {
+    const seek = (time: number) => requestSeek ? requestSeek(time) : player.seek(time)
     const eventListener = (ev: KeyboardEvent) => {
       // on the window, so typing into a consumer's own input is the one case that opts out
       const target = ev.target as HTMLElement | null
@@ -232,10 +236,10 @@ export const ControlBar = () => {
       }
       else if (ev.key === 'ArrowRight') {
         if (!player.duration) return
-        player.seek(Math.min(player.currentTime + SEEK_STEP, player.duration))
+        seek(Math.min(player.currentTime + SEEK_STEP, player.duration))
       }
       else if (ev.key === 'ArrowLeft') {
-        player.seek(Math.max(player.currentTime - SEEK_STEP, 0))
+        seek(Math.max(player.currentTime - SEEK_STEP, 0))
       }
       else {
         shouldPreventDefault = false
@@ -247,7 +251,7 @@ export const ControlBar = () => {
     }
     window.addEventListener('keydown', eventListener)
     return () => window.removeEventListener('keydown', eventListener)
-  }, [player, modifyVolume])
+  }, [player, modifyVolume, requestSeek])
 
   const handleWheel = useCallback((e: WheelEvent) => {
     e.preventDefault()

package/src/lib/react/components/progress-bar.tsx

@@ -181,9 +181,13 @@ const style = css`
   }
 `
 
+/** Movement from the press, in px, past which a gesture is a scrub rather than a click. */
+const SCRUB_THRESHOLD_PX = 4
+
 export const ProgressBar = () => {
   const player = usePlayer()
   const currentTime = usePlayer((state) => state.currentTime)
+  const requestSeek = usePlayer((state) => state.requestSeek)
   const duration = usePlayer((state) => state.duration)
   const size = usePlayer((state) => state.size)
   const downloadedRanges = usePlayer((state) => state.downloadedRanges)
@@ -199,7 +203,36 @@ export const ProgressBar = () => {
   // onChange reports a bare fraction, so the device that opened the gesture is recorded on press
   const dragPointerType = useRef<string | undefined>(undefined)
 
+  /*
+   * How many changes this gesture has produced, which is what tells a click from a scrub.
+   *
+   * `useDragValue` reports onChange on the PRESS and again on every move, so a click that drifts one
+   * pixel produces two. Counting them is exact where a timer is not: the first is the press, and
+   * anything after it is the pointer actually moving.
+   */
+  const changesThisPress = useRef(0)
+  const latestFraction = useRef<number | undefined>(undefined)
+  const pressFraction = useRef<number | undefined>(undefined)
+  /*
+   * Whether this gesture has become a scrub, latched once it has.
+   *
+   * A pixel of drift is a click, not a drag: every real mouse produces some. Counting changes was
+   * not enough, because that pixel arrives as a pointermove and so looked like scrubbing, which put
+   * the playhead onto unbuffered ground before its data existed and wedged firefox exactly as
+   * before. Distance from the press is the honest test, and it latches so that dragging back toward
+   * the origin does not flip the gesture back into a click.
+   */
+  const isScrub = useRef(false)
+
   const onSeekDrag = (fraction: number) => {
+    changesThisPress.current += 1
+    latestFraction.current = fraction
+    if (pressFraction.current === undefined) {
+      pressFraction.current = fraction
+    } else if (!isScrub.current) {
+      const width = progressBarRef.current?.getBoundingClientRect().width ?? 0
+      if (Math.abs(fraction - pressFraction.current) * width > SCRUB_THRESHOLD_PX) isScrub.current = true
+    }
     setSeekFraction(fraction)
     if (dragPointerType.current === 'mouse') return
     setProgressBarOverTime(fraction * duration)
@@ -209,11 +242,31 @@ export const ProgressBar = () => {
 
   const onDragStart: DOMAttributes<HTMLDivElement>['onPointerDown'] = (ev) => {
     dragPointerType.current = ev.pointerType
+    changesThisPress.current = 0
+    pressFraction.current = undefined
+    isScrub.current = false
     handlers.onPointerDown(ev)
   }
 
   const onDragEnd: DOMAttributes<HTMLDivElement>['onPointerUp'] = (ev) => {
     handlers.onPointerUp(ev)
+    /*
+     * The seek that counts, and the only one allowed to move the playhead onto new ground.
+     *
+     * Where the gesture ENDED is the position anyone is waiting for, and it is issued through
+     * `requestSeek` so the data is in place before the element demuxes there. A seek into a hole is
+     * what wedges firefox's decoder, and the whole gesture exists to arrive at this one moment.
+     */
+    // a pointerup with no press behind it is not this gesture, and must not seek anywhere
+    const fraction = changesThisPress.current > 0 ? latestFraction.current : undefined
+    if (fraction !== undefined && duration) {
+      const timestamp = fraction * duration
+      if (requestSeek) requestSeek(timestamp)
+      else player.seek(timestamp)
+    }
+    changesThisPress.current = 0
+    isScrub.current = false
+    pressFraction.current = undefined
     // a lifted finger leaves nothing over the bar, so the preview it opened closes with it
     if (ev.pointerType === 'mouse') return
     setProgressBarOverTime(undefined)
@@ -272,11 +325,20 @@ export const ProgressBar = () => {
     return `${hoursString}${minutes < 10 ? '0' : ''}${minutes}:${seconds < 10 ? '0' : ''}${seconds}`
   }, [progressBarHoverTime])
 
+  /*
+   * Follow the pointer while it is actually moving, and NOT on the press itself.
+   *
+   * Seeking on the press is what defeated the first version of this: a click that drifts a pixel
+   * looked like a drag, so the playhead jumped onto unbuffered ground before its data existed, which
+   * is exactly the wedge. A scrub still follows the pointer, because a drag has never reproduced the
+   * fault (its seeks land ~28ms apart, far too fast for a drain to complete) and a frozen picture
+   * during a scrub would be a real regression. The settled position is handled on release.
+   */
   useEffect(() => {
     if (seekFraction === undefined || !duration) return
-    const timestamp = seekFraction * duration
-    player.seek(timestamp)
-  }, [player, seekFraction, duration])
+    if (!dragging || !isScrub.current) return
+    player.seek(seekFraction * duration)
+  }, [player, dragging, seekFraction, duration])
 
   const scaleX = useMemo(() => {
     return !duration || typeof currentTime !== 'number'

package/src/lib/react/hooks/use-drag-value.ts

@@ -35,7 +35,10 @@ export const useDragValue = ({ ref, onChange, orientation = 'horizontal', disabl
     // events the seek preview runs on, the second keeps the press from reaching the document
     // listeners that close the popover and refresh the auto-hide timer.
     activePointer.current = event.pointerId
-    event.currentTarget.setPointerCapture?.(event.pointerId)
+    // Throws NotFoundError for a pointer id that is not active, and an exception here would abandon
+    // the gesture before it records anything. Capture is an optimisation for tracking outside the
+    // element, never a requirement.
+    try { event.currentTarget.setPointerCapture?.(event.pointerId) } catch {}
     setDragging(true)
     onChangeRef.current(fractionFor(event.clientX, event.clientY))
   }, [disabled, fractionFor])
@@ -48,7 +51,7 @@ export const useDragValue = ({ ref, onChange, orientation = 'horizontal', disabl
   const endDrag = useCallback((event: ReactPointerEvent<HTMLElement>) => {
     if (activePointer.current !== event.pointerId) return
     activePointer.current = null
-    event.currentTarget.releasePointerCapture?.(event.pointerId)
+    try { event.currentTarget.releasePointerCapture?.(event.pointerId) } catch {}
     setDragging(false)
   }, [])
 

package/src/lib/react/hooks/use-playback.ts

@@ -25,6 +25,14 @@ const RESTART_BACKOFF_MS = [0, 250, 1_000, 3_000, 10_000]
 // far enough back that an unrelated hiccup later in an episode starts from no delay again
 const RESTART_SETTLED_MS = 60_000
 
+/**
+ * How long a seek may wait for its data before the playhead moves anyway.
+ *
+ * The prevention only works while the wait is honoured, and a read over a torrent has no ceiling, so
+ * this is the ceiling. Half a second is the point where a seek stops feeling like a seek.
+ */
+const SEEK_PREPARE_BUDGET_MS = 500
+
 const messageOf = (error: unknown) =>
   error instanceof Error ? error.message : String(error)
 
@@ -66,6 +74,7 @@ export const usePlayback = (
   const {
     read, size, publicPath = '', libavWorkerUrl = '', jassubWorkerUrl = '', jassubWasmUrl = '',
     jassubLegacyWasmUrl, defaultFontUrl, bufferSize, autoplay = false,
+    seekPrepareBudgetMs = SEEK_PREPARE_BUDGET_MS,
   } = options ?? ({} as Partial<MediaPlayerLocalOptions>)
 
   // The track the viewer picked, which is what a restart is keyed on. Distinct from the store's
@@ -131,6 +140,77 @@ export const usePlayback = (
     controllerRef.current?.selectSubtitleStream(streamIndex)
   }, [player])
 
+  /**
+   * Seek with the data already there, or after the deadline, whichever comes first.
+   *
+   * The prevention for the firefox decoder wedge. Seeking into a hole makes the reader drain the
+   * decoder and never flush it again, so the pipeline is asked for the target first. The deadline is
+   * what keeps that honest: a read over a torrent has no ceiling, and a seek bar that waits on one
+   * is worse than the fault it avoids. So the playhead moves either when the data lands or when the
+   * budget runs out, once, whichever happens first.
+   *
+   * A seek into buffered ground resolves immediately, so scrubbing inside the buffer is unaffected.
+   */
+  const requestSeek = useCallback((time: number) => {
+    const controller = controllerRef.current
+    // no budget means the feature is off: seek at once and do not spend a read preparing something
+    // nobody is going to wait for
+    if (!controller || seekPrepareBudgetMs <= 0) { player.seek(time); return }
+
+    /*
+     * Every call gets the data first. There is deliberately no "this looks like a drag" shortcut.
+     *
+     * The first version of this guessed at drags from the gap between calls, and that is what let
+     * the fault through in production: the seek bar reports a change on the PRESS and again on every
+     * move, so a click that drifts one pixel produced two calls milliseconds apart, the second was
+     * read as a drag, and the playhead jumped onto unbuffered ground before its data existed. Two
+     * quick taps of the arrow keys would have done the same.
+     *
+     * The chrome knows what gesture it is in and now says so by only calling this for settled seeks,
+     * which is knowledge rather than inference. Rapid calls are safe here anyway: each supersedes
+     * the last through the engine's seek generation.
+     */
+    /*
+     * A debug trace, off unless asked for.
+     *
+     * The fault this prevents is reproducible in seconds on some machines and not at all on others,
+     * so the only way to learn anything from someone else's reproduction is to have the seek say
+     * what it did. Set `window.__mediaPlayerSeekDebug = true` (the dev route does it for
+     * `?seekDebug=1`) and every seek reports whether the data was ready, how long it waited, and
+     * whether the playhead moved before the data arrived, which is the exact condition that wedges
+     * firefox.
+     */
+    const debug = typeof window !== 'undefined' && (window as { __mediaPlayerSeekDebug?: boolean }).__mediaPlayerSeekDebug
+    const startedAt = performance.now()
+
+    let moved = false
+    let movedBecause: 'prepared' | 'deadline' = 'prepared'
+    const move = () => {
+      if (moved) return
+      moved = true
+      player.seek(time)
+      if (debug) {
+        // eslint-disable-next-line no-console
+        const video = controller.videoElement
+        let runway = 0
+        if (video) {
+          for (let i = 0; i < video.buffered.length; i++) {
+            if (video.buffered.start(i) <= time + 1 && time < video.buffered.end(i)) runway = video.buffered.end(i) - time
+          }
+        }
+        // eslint-disable-next-line no-console
+        console.warn(`[media-player] seek to ${time.toFixed(2)} moved after ${Math.round(performance.now() - startedAt)}ms via ${movedBecause}, runway ${runway.toFixed(1)}s${movedBecause === 'deadline' ? ' (EXPOSED: moved before its data was ready)' : ''}`)
+      }
+    }
+    const deadline = setTimeout(() => { movedBecause = 'deadline'; move() }, seekPrepareBudgetMs)
+    void controller
+      .prepareSeek(time)
+      // a failed prepare is not a reason to refuse the seek: the pump and the existing recovery
+      // both still apply, and refusing would strand the viewer on a bar that does nothing
+      .catch(() => {})
+      .finally(() => { clearTimeout(deadline); move() })
+  }, [player, seekPrepareBudgetMs])
+
   const selectAudioTrack = useCallback((id: string | number) => {
     if (typeof id !== 'number') return
     player.setSourceState({ selectedAudioTrack: id })
@@ -143,8 +223,8 @@ export const usePlayback = (
   const setSourceState = usePlayer((state) => state.setSourceState)
 
   useEffect(() => {
-    setSourceState({ selectSubtitleTrack, selectAudioTrack })
-  }, [setSourceState, selectSubtitleTrack, selectAudioTrack])
+    setSourceState({ selectSubtitleTrack, selectAudioTrack, requestSeek })
+  }, [setSourceState, selectSubtitleTrack, selectAudioTrack, requestSeek])
 
   useEffect(() => {
     if (!video || !canvas || !size || !read) return

package/src/lib/react/source-feature.ts

@@ -128,6 +128,19 @@ export type SourceState = {
   /** Burn-in only. True while the composite is the picture on screen. */
   burnedInSubtitles: boolean
 
+  /**
+   * Move the playhead, letting the pipeline get the data there first.
+   *
+   * The chrome calls this instead of the player's own `seek`, because an element that demuxes into a
+   * hole is what wedges firefox's decoder: the underrun drains it and nothing ever flushes it again.
+   * Waiting is bounded by a deadline, so a source that cannot answer in time costs that deadline and
+   * not the whole read.
+   *
+   * Undefined for a media this player does not own, where there is no pipeline to prepare and the
+   * caller should seek directly.
+   */
+  requestSeek?: (time: number) => void
+
   /** Set when the pipeline fails. Cleared when it recovers. */
   playbackError: unknown
   /**

package/src/lib/react/video-player.tsx

@@ -109,6 +109,14 @@ export type MediaPlayerLocalOptions =
     /** Fallback face for `liberation sans`, used when a subtitle track names a font the file does not carry. */
     defaultFontUrl?: string
     bufferSize?: number
+    /**
+     * How long a seek waits for its own data before the playhead moves anyway, in ms. Default 500.
+     *
+     * Seeking into a hole is what wedges firefox's decoder, so the pipeline is asked for the target
+     * first. This is the ceiling on that wait, since a read over a torrent has none of its own. Set
+     * it to 0 to seek immediately and rely on the recovery instead.
+     */
+    seekPrepareBudgetMs?: number
 
     /** Byte spans available, painted on the seekbar and informing the thumbnail generator. */
     downloadedRanges?: DownloadedRange[]