@banou/media-player 0.8.12 → 0.8.13

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.13",
   "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,13 @@ 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>
   selectSubtitleStream: (streamIndex: number | undefined) => void
   /** Keyframe index of the input, which is what maps a downloaded byte range onto the timeline. */
   indexes: MediaIndex[]
@@ -210,6 +217,8 @@ 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
     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 +246,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
@@ -375,6 +396,38 @@ 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.
+     */
+    const prepareSeek = async (time: number) => {
+      if (destroyed || playableAt(time)) return
+      finished = false
+      preparing++
+      try {
+        await seekTo(time)
+      } finally {
+        preparing--
+      }
+    }
+
     /**
      * Where a drag reaches the consumer, at a rate a consumer can act on.
      *
@@ -437,6 +490,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 +563,7 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
 
     return {
       destroy: runTeardown,
+      prepareSeek,
       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

@@ -184,6 +184,7 @@ const style = css`
 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)
@@ -275,8 +276,12 @@ export const ProgressBar = () => {
   useEffect(() => {
     if (seekFraction === undefined || !duration) return
     const timestamp = seekFraction * duration
-    player.seek(timestamp)
-  }, [player, seekFraction, duration])
+    // `requestSeek` gets the data in place before the playhead moves, which is what stops firefox
+    // wedging its decoder on a seek into a hole. Absent for a media this player does not own, where
+    // there is no pipeline to ask and the element's own seek is all there is.
+    if (requestSeek) requestSeek(timestamp)
+    else player.seek(timestamp)
+  }, [player, requestSeek, seekFraction, duration])
 
   const scaleX = useMemo(() => {
     return !duration || typeof currentTime !== 'number'

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

@@ -25,6 +25,21 @@ 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
+
+/**
+ * Under this gap between seek requests, it is a drag rather than a series of decisions.
+ *
+ * Kept equal to the engine's own settle window, so both layers agree on what a drag is.
+ */
+const DRAG_SETTLE_MS = 250
+
 const messageOf = (error: unknown) =>
   error instanceof Error ? error.message : String(error)
 
@@ -66,6 +81,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
@@ -111,6 +127,8 @@ export const usePlayback = (
    * deliberately not, since a streaming consumer passes a fresh closure several times a second.
    */
   const resumeRef = useRef<{ time: number, size: number } | null>(null)
+  // when the seek bar last asked for a position, which is how a drag is told from a click
+  const lastSeekRequestAt = useRef(0)
   // The renderer turns the first track on by itself, so the menu has to mirror that or it shows
   // "Disable" ticked over subtitles that are visibly on screen.
   const subtitleChoiceMade = useRef(false)
@@ -131,6 +149,54 @@ 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 }
+
+    /*
+     * A drag is left exactly as it was.
+     *
+     * The seek bar reports a fraction on every pointermove, so preparing each one would remux per
+     * move, and waiting on each would make a scrub feel like treacle. Neither is worth paying:
+     * a drag never reproduced this fault (its seeks land ~28ms apart, far too fast for a drain to
+     * complete), and the engine already coalesces the remux to wherever the drag stops.
+     *
+     * Discrete seeks are the ones that wedge it, at a few hundred ms apart, and those get the data
+     * first.
+     */
+    const now = performance.now()
+    const dragging = now - lastSeekRequestAt.current < DRAG_SETTLE_MS
+    lastSeekRequestAt.current = now
+    if (dragging) { player.seek(time); return }
+
+    let moved = false
+    const move = () => {
+      if (moved) return
+      moved = true
+      player.seek(time)
+    }
+    const deadline = setTimeout(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 +209,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[]