@banou/media-player 0.8.11 → 0.8.13

package/dist/react/components/errors.d.ts

@@ -1,4 +1,6 @@
 import type { PlaybackErrorEntry } from '../source-feature';
+/** How many failures there have been, which is not how many rows: a repeat folds into its row. */
+export declare const countErrors: (errors: PlaybackErrorEntry[]) => number;
 /** What lands on the clipboard: the same thing the panel shows, in the order it happened. */
 export declare const formatErrors: (errors: PlaybackErrorEntry[]) => string;
 /**

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

@@ -26,9 +26,20 @@ export type TrackChoice = {
  * `cause` may be a `MediaError` that reads differently once the element has moved on.
  */
 export type PlaybackErrorEntry = {
-    /** Wall clock, so the report can be read next to a console log or a torrent's timeline. */
+    /** Wall clock of the FIRST of them, so the report can be read next to a console log. */
     at: number;
-    /** Seconds into the media, which is usually the first question asked of a playback failure. */
+    /** Wall clock of the most recent one. Equal to `at` until a repeat has folded into this row. */
+    lastAt: number;
+    /**
+     * How many times in a row this exact failure happened.
+     *
+     * A source that stays broken reports the same sentence every few seconds for as long as it stays
+     * broken, so consecutive identical failures fold into one row rather than filling the panel with a
+     * wall of one message. This is also what keeps the list from growing without end in that case,
+     * since there is no ceiling on how many failures are kept.
+     */
+    count: number;
+    /** Seconds into the media, at the first of them, which is usually the first question asked. */
     atMediaTime?: number;
     message: string;
     /** The `cause` chain, already unwound, one line per level. */
@@ -104,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;
     /**
@@ -179,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.11",
+  "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/errors.tsx

@@ -77,6 +77,12 @@ ${popoverStyle}
     .when {
       color: #bbb;
       ${fonts.bSmall.regular}
+
+      /* the one part of the line worth scanning for, so it is the one part at full brightness */
+      .count {
+        margin-left: 6px;
+        color: #fff;
+      }
     }
 
     .what {
@@ -101,12 +107,21 @@ const clock = (at: number) => new Date(at).toLocaleTimeString()
 const mediaTime = (seconds: number | undefined) =>
   seconds === undefined || !Number.isFinite(seconds) ? undefined : formatTime(Math.max(0, seconds))
 
+/** How many failures there have been, which is not how many rows: a repeat folds into its row. */
+export const countErrors = (errors: PlaybackErrorEntry[]) =>
+  errors.reduce((total, entry) => total + entry.count, 0)
+
 /** What lands on the clipboard: the same thing the panel shows, in the order it happened. */
 export const formatErrors = (errors: PlaybackErrorEntry[]) =>
   errors
     .map((entry, index) => {
       const at = mediaTime(entry.atMediaTime)
-      const head = `${index + 1}. ${new Date(entry.at).toISOString()}${at ? ` (at ${at})` : ''}${entry.recovered ? ' [recovered]' : ''}`
+      // A repeat carries the span it covers, so "40 times over two minutes" and "40 times in one
+      // second" are distinguishable in a report. Both happen, and they are different faults.
+      const when = entry.count > 1
+        ? `${new Date(entry.at).toISOString()} to ${new Date(entry.lastAt).toISOString()} ×${entry.count}`
+        : new Date(entry.at).toISOString()
+      const head = `${index + 1}. ${when}${at ? ` (at ${at})` : ''}${entry.recovered ? ' [recovered]' : ''}`
       return [head, entry.message, entry.detail].filter(Boolean).join('\n')
     })
     .join('\n\n')
@@ -142,7 +157,8 @@ export const ErrorsAction = () => {
     )
   }
 
-  const label = `Playback errors (${errors.length})`
+  // counted in failures rather than in rows, because a row that says ×40 is forty of them
+  const label = `Playback errors (${countErrors(errors)})`
 
   return (
     <div css={style} ref={containerRef}>
@@ -177,8 +193,11 @@ export const ErrorsAction = () => {
               <div className='entry no-hover' key={`${entry.at}-${index}`}>
                 <span className='when'>
                   {clock(entry.at)}
+                  {/* the span, so a row that is still growing is distinguishable from one that stopped */}
+                  {entry.count > 1 ? ` to ${clock(entry.lastAt)}` : ''}
                   {mediaTime(entry.atMediaTime) ? ` at ${mediaTime(entry.atMediaTime)}` : ''}
                   {entry.recovered ? ' recovered' : ''}
+                  {entry.count > 1 ? <span className='count'>{`×${entry.count}`}</span> : null}
                 </span>
                 <span className='what'>{entry.message}</span>
                 {entry.detail ? <span className='cause'>{entry.detail}</span> : null}

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
@@ -158,14 +224,33 @@ export const usePlayback = (
      * `playbackError` null and would otherwise erase the only evidence that anything went wrong.
      */
     const record = (error: unknown, recovered: boolean) => {
+      const at = Date.now()
+      const message = messageOf(error)
+      const detail = causeChain(error)
+      const errors = player.playbackErrors
+      const last = errors[errors.length - 1]
+
+      // A source that stays broken repeats one sentence for as long as it stays broken, so a
+      // consecutive repeat folds into the row it repeats rather than adding another. Only
+      // CONSECUTIVE ones: an identical failure either side of a different one is a second episode,
+      // and collapsing the two would lose the order that makes a report readable.
+      if (last && last.message === message && last.detail === detail && last.recovered === recovered) {
+        const folded: PlaybackErrorEntry = { ...last, count: last.count + 1, lastAt: at }
+        player.setSourceState({ playbackErrors: [...errors.slice(0, -1), folded] })
+        return
+      }
+
       const entry: PlaybackErrorEntry = {
-        at: Date.now(),
+        at,
+        lastAt: at,
+        count: 1,
+        // where it STARTED, kept as the row grows, because that is the position worth reporting
         atMediaTime: Number.isFinite(video.currentTime) ? video.currentTime : undefined,
-        message: messageOf(error),
-        detail: causeChain(error),
+        message,
+        detail,
         recovered,
       }
-      player.setSourceState({ playbackErrors: [...player.playbackErrors, entry] })
+      player.setSourceState({ playbackErrors: [...errors, entry] })
     }
     const fail = (error: unknown) => {
       if (cancelled) return

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

@@ -30,9 +30,20 @@ export type TrackChoice = {
  * `cause` may be a `MediaError` that reads differently once the element has moved on.
  */
 export type PlaybackErrorEntry = {
-  /** Wall clock, so the report can be read next to a console log or a torrent's timeline. */
+  /** Wall clock of the FIRST of them, so the report can be read next to a console log. */
   at: number
-  /** Seconds into the media, which is usually the first question asked of a playback failure. */
+  /** Wall clock of the most recent one. Equal to `at` until a repeat has folded into this row. */
+  lastAt: number
+  /**
+   * How many times in a row this exact failure happened.
+   *
+   * A source that stays broken reports the same sentence every few seconds for as long as it stays
+   * broken, so consecutive identical failures fold into one row rather than filling the panel with a
+   * wall of one message. This is also what keeps the list from growing without end in that case,
+   * since there is no ceiling on how many failures are kept.
+   */
+  count: number
+  /** Seconds into the media, at the first of them, which is usually the first question asked. */
   atMediaTime?: number
   message: string
   /** The `cause` chain, already unwound, one line per level. */
@@ -117,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[]