@banou/media-player 0.8.9 → 0.8.10

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

@@ -59,6 +59,15 @@ type CommonOptions = {
      * `pointer-events: auto` on itself. `children` land next to the media instead, below the chrome.
      */
     overlay?: ReactNode;
+    /**
+     * Where the viewer is heading, as a 0..1 fraction, for a source that fetches on demand.
+     *
+     * Throttled, and deliberately: the chrome moves the element on every pointermove, so a drag
+     * across the bar is dozens of positions a second, and a consumer that reprioritises its download
+     * window on each one never finishes anything it starts. This fires on the leading edge, so a
+     * single seek moves the window at once, and again on the trailing edge, so the position the drag
+     * ended on is the one that sticks. It is a heading, not an event log.
+     */
     onSeek?: (fraction: number) => void;
     onPlaybackError?: (error: unknown) => void;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/media-player",
-  "version": "0.8.9",
+  "version": "0.8.10",
   "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/index.ts

@@ -1,4 +1,4 @@
-export { startPlayback, terminateRemuxer, DEFAULT_BUFFER_SIZE } from './playback'
+export { startPlayback, terminateRemuxer, MediaElementError, isMediaElementError, DEFAULT_BUFFER_SIZE } from './playback'
 export type { PlaybackOptions, PlaybackController, MediaIndex, AudioStream } from './playback'
 
 export { createSubtitleRenderer, SUBTITLES_OFF } from './subtitles'

package/src/lib/engine/playback.ts

@@ -44,6 +44,25 @@ export type PlaybackController = {
   audioMimeType: string
 }
 
+/**
+ * A terminal failure of the media element itself, as opposed to anything this pipeline did.
+ *
+ * It is worth its own type because it is the one error class that says something about the CURE:
+ * the element is finished and no append will ever succeed against it again, so reporting it to the
+ * viewer is pointless and only a rebuilt element clears it. The flag rather than an `instanceof`
+ * is what survives the error crossing a module boundary.
+ */
+export class MediaElementError extends Error {
+  readonly mediaElement = true
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'MediaElementError'
+  }
+}
+
+export const isMediaElementError = (error: unknown): boolean =>
+  !!error && typeof error === 'object' && (error as { mediaElement?: boolean }).mediaElement === true
+
 // ~20s behind and ~60s ahead of the playhead, refilled when the forward buffer dips under 30s
 const PRE_EVICT = -20
 const POST_EVICT = 60
@@ -55,6 +74,10 @@ 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
+// 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
+const DRAG_SETTLE_MS = 250
 export const DEFAULT_BUFFER_SIZE = 2_500_000
 
 // destroy() only terminates after a round trip into the wasm, so terminate on our own clock too
@@ -199,11 +222,16 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
     let lastSeekPosition = 0
 
     // 'Cancelled' covers both an aborted task and a read that gave up, so it is only noise mid-seek
-    const reportError = (error: unknown, aborted: boolean) => {
+    const reportError = (error: unknown, aborted: boolean, terminal = false) => {
       const cancelled = (error as Error)?.message === 'Cancelled'
       if (aborted && cancelled) return
       console.error(error)
-      if (outstandingError) return
+      // A terminal failure of the element outranks whatever was already outstanding. It is the one
+      // error whose HANDLING differs, and the sequence that produces it starts with a starved
+      // buffer, which is also when a read is most likely to have reported first. Swallowing it
+      // behind that earlier report would leave the caller holding a dead element, able to fix it
+      // and never told to.
+      if (outstandingError && !terminal) return
       outstandingError = true
       onError?.(cancelled ? new Error('Reading the video file failed', { cause: error }) : error)
     }
@@ -305,7 +333,9 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
     }
 
     const pump = async () => {
-      if (reading || seeking || destroyed) return
+      // a settling drag is about to reposition the remuxer, so reading forward from where it
+      // happens to sit is throwing a read away
+      if (reading || seeking || dragTimer !== undefined || destroyed) return
       if (!pending && (finished || !needsData())) return
       const generation = ++readGeneration
       const seekAtStart = seekGeneration
@@ -345,13 +375,84 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
      */
     const alreadyPlayable = (time: number) => time >= lastSeekPosition && !!playheadRange()
 
+    /**
+     * Where a drag reaches the consumer, at a rate a consumer can act on.
+     *
+     * `onSeek` moves the reader's download window, and the chrome moves the element on every
+     * pointermove, so one drag across the bar used to reprioritise the source dozens of times a
+     * second. Nothing a torrent starts survives being re-anchored at that rate, which is most of
+     * why a scrub could leave the buffer empty for half a minute. Leading edge so a single seek
+     * still moves the window at once, trailing edge so the position the drag ENDED on is the one
+     * that sticks.
+     */
+    let lastSeekReport = 0
+    let trailingFraction: number | null = null
+    let trailingTimer: ReturnType<typeof setTimeout> | undefined
+    const reportSeek = (fraction: number) => {
+      const now = performance.now()
+      const since = now - lastSeekReport
+      if (since >= SEEK_REPORT_MS) {
+        lastSeekReport = now
+        trailingFraction = null
+        onSeek?.(fraction)
+        return
+      }
+      trailingFraction = fraction
+      if (trailingTimer) return
+      trailingTimer = setTimeout(() => {
+        trailingTimer = undefined
+        const pendingFraction = trailingFraction
+        trailingFraction = null
+        if (pendingFraction === null || destroyed) return
+        lastSeekReport = performance.now()
+        onSeek?.(pendingFraction)
+      }, SEEK_REPORT_MS - since)
+    }
+    teardown.push(() => { if (trailingTimer) clearTimeout(trailingTimer) })
+
+    /**
+     * A drag is not a seek per pointermove, however many the element reports.
+     *
+     * The chrome moves the element on every pointermove, and every one of those used to start a
+     * remuxer seek, which ABORTS the one already running. So during a drag none of them ever
+     * finished: a measured drag over a torrent produced 315 seeks, zero `seeked`, and thirty
+     * seconds in which not one byte reached the source buffer. An empty buffer for that long is
+     * also what wedges firefox's decoder, so this is not only wasted work.
+     *
+     * A move that arrives on its own still seeks AT ONCE, so a click on the bar costs nothing and
+     * nothing waits out a read that can run for tens of seconds over a torrent. Only a run of
+     * moves is a drag, and a drag gets one seek when it settles, to wherever it actually stopped.
+     */
+    let lastSeekingAt = 0
+    let dragTimer: ReturnType<typeof setTimeout> | undefined
+    teardown.push(() => { if (dragTimer) clearTimeout(dragTimer) })
+
     const onSeeking = () => {
       const time = videoElement.currentTime
       const duration = metadata.info.input.duration || videoElement.duration
-      if (duration > 0) onSeek?.(Math.min(Math.max(time / duration, 0), 1))
+      if (duration > 0) reportSeek(Math.min(Math.max(time / duration, 0), 1))
+      // stamped before the playable check, so a drag that crosses buffered ground and comes out
+      // the far side is still recognised as one drag rather than as a fresh click
+      const now = performance.now()
+      const dragging = now - lastSeekingAt < DRAG_SETTLE_MS
+      lastSeekingAt = now
       if (alreadyPlayable(time)) return
       finished = false
-      void seekTo(time)
+      if (dragTimer) clearTimeout(dragTimer)
+      if (!dragging) {
+        dragTimer = undefined
+        void seekTo(time)
+        return
+      }
+      dragTimer = setTimeout(() => {
+        dragTimer = undefined
+        if (destroyed) return
+        // where the drag ENDED, which is the only position anyone is waiting on
+        const settled = videoElement.currentTime
+        if (alreadyPlayable(settled)) return
+        finished = false
+        void seekTo(settled)
+      }, DRAG_SETTLE_MS)
     }
     videoElement.addEventListener('seeking', onSeeking)
     teardown.push(() => videoElement.removeEventListener('seeking', onSeeking))
@@ -368,6 +469,11 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
      *
      * That cost a session: a decode failure presented as an append bug, which is a completely
      * different place to look. Report what actually happened, then stop.
+     *
+     * It is reported as a MediaElementError because the caller can do something about this one that
+     * it cannot do about any other: nothing appended here will ever decode again, but a rebuilt
+     * element gets a fresh decoder, and the pipeline already knows how to come back at the same
+     * position. See `isMediaElementError`.
      */
     let elementFailed = false
     const onElementError = () => {
@@ -375,8 +481,9 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
       elementFailed = true
       const error = videoElement.error
       reportError(
-        new Error(`the media element failed: ${error?.message ?? 'unknown'}`, { cause: error }),
+        new MediaElementError(`the media element failed: ${error?.message ?? 'unknown'}`, { cause: error }),
         false,
+        true,
       )
     }
     videoElement.addEventListener('error', onElementError)

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

@@ -3,10 +3,15 @@ import type { MediaPlayerLocalOptions } from '../video-player'
 
 import { useCallback, useEffect, useRef, useState } from 'react'
 
-import { startPlayback } from '../../engine'
+import { isMediaElementError, startPlayback } from '../../engine'
 import { usePlayer } from '../player'
 import { toNamedTracks } from '../../utils/track-label'
 
+// A wedged element is rebuilt rather than reported, but a file that wedges over and over is a real
+// failure and has to reach the viewer instead of looping forever.
+const MAX_RESTARTS = 3
+const RESTART_WINDOW_MS = 60_000
+
 /**
  * Owns the engine for the life of a source: start, teardown, and every piece of state the pipeline
  * discovers. Nothing is mirrored in React state, so the store is the only place any of it lives.
@@ -29,6 +34,24 @@ export const usePlayback = (
   // `selectedAudioStream`, which is whatever is playing right now.
   const [audioStreamIndex, setAudioStreamIndex] = useState<number | undefined>(undefined)
 
+  /**
+   * Bumped to rebuild the pipeline after the media element itself has failed.
+   *
+   * Firefox can wedge its own decoder: when the source buffer runs dry it drains the decoder so the
+   * frames still inside it get shown, and clearing that drain needs a decoded sample to resume
+   * from. A seek into an empty buffer over a slow source has none, so the drain is never cleared
+   * and every packet after it comes back `avcodec_send_packet error: End of file`. The element is
+   * finished at that point and no append can revive it.
+   *
+   * Rebuilding is the cure, and this hook already does exactly that for an audio track change,
+   * position and all, so the recovery is a dep rather than a second teardown path.
+   */
+  const [restartToken, setRestartToken] = useState(0)
+  const restarts = useRef({ count: 0, at: 0 })
+  // The budget belongs to one media, not to the player: a file that used it up must not leave the
+  // next one with no recovery at all.
+  useEffect(() => { restarts.current = { count: 0, at: 0 } }, [size])
+
   const controllerRef = useRef<PlaybackController | null>(null)
   /**
    * Where to pick playback back up, and WHICH media that position belongs to.
@@ -83,6 +106,19 @@ export const usePlayback = (
     player.setSourceState({ playbackError: null, ready: false })
     const fail = (error: unknown) => {
       if (cancelled) return
+      // Not something the viewer can act on and not something an append can survive: rebuild the
+      // element instead of putting a dead player behind an error message. Counted in a window, so
+      // a file that wedges again and again still reaches the viewer rather than looping.
+      if (isMediaElementError(error)) {
+        const now = performance.now()
+        if (now - restarts.current.at > RESTART_WINDOW_MS) restarts.current = { count: 0, at: now }
+        if (restarts.current.count < MAX_RESTARTS) {
+          restarts.current = { count: restarts.current.count + 1, at: now }
+          console.warn('the media element failed; rebuilding the pipeline', error)
+          setRestartToken((token) => token + 1)
+          return
+        }
+      }
       console.error('playback failed', error)
       player.setSourceState({ playbackError: error })
       onPlaybackErrorRef.current?.(error)
@@ -154,6 +190,6 @@ export const usePlayback = (
     // times a second, and the restart loop reads as "Loading metadata" forever at a flat 0 B/s.
   }, [
     player, video, canvas, size, publicPath, libavWorkerUrl, jassubWorkerUrl, jassubWasmUrl,
-    jassubLegacyWasmUrl, defaultFontUrl, bufferSize, audioStreamIndex, autoplay,
+    jassubLegacyWasmUrl, defaultFontUrl, bufferSize, audioStreamIndex, autoplay, restartToken,
   ])
 }

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

@@ -71,6 +71,15 @@ type CommonOptions = {
    */
   overlay?: ReactNode
 
+  /**
+   * Where the viewer is heading, as a 0..1 fraction, for a source that fetches on demand.
+   *
+   * Throttled, and deliberately: the chrome moves the element on every pointermove, so a drag
+   * across the bar is dozens of positions a second, and a consumer that reprioritises its download
+   * window on each one never finishes anything it starts. This fires on the leading edge, so a
+   * single seek moves the window at once, and again on the trailing edge, so the position the drag
+   * ended on is the one that sticks. It is a heading, not an event log.
+   */
   onSeek?: (fraction: number) => void
   onPlaybackError?: (error: unknown) => void
 }