@banou/media-player 0.8.9 → 0.8.11

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

@@ -1,12 +1,55 @@
 import type { PlaybackController } from '../../engine'
+import type { PlaybackErrorEntry } from '../source-feature'
 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, however many times it takes.
+ *
+ * There is deliberately no ceiling. The failure this exists for is a firefox decoder that will not
+ * take another packet, it is not the file's fault, and a viewer forty minutes into an episode is
+ * not helped by a budget running out. Every rebuild is recorded instead, and the control bar offers
+ * the record, so a file that genuinely cannot play is visible as a wall of identical entries rather
+ * than hidden behind a counter.
+ *
+ * The backoff is the whole guard: rebuilds that keep failing immediately slow down, so a source that
+ * fails deterministically settles into a slow retry instead of a hot loop that pins a core and
+ * reloads libav as fast as it can.
+ */
+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
+
+const messageOf = (error: unknown) =>
+  error instanceof Error ? error.message : String(error)
+
+/**
+ * The `cause` chain, unwound to text at the moment it happened.
+ *
+ * The reason a decode failure is worth copying out at all is almost always one level down: the top
+ * line says the media element failed, and the cause carries what the decoder actually said. A
+ * `MediaError` is not an `Error`, so it is read for its own two fields rather than skipped.
+ */
+const causeChain = (error: unknown) => {
+  const lines: string[] = []
+  let cause: unknown = (error as { cause?: unknown })?.cause
+  // bounded, because a cause chain can be circular and this runs inside an error path
+  for (let depth = 0; cause != null && depth < 8; depth++) {
+    if (typeof MediaError !== 'undefined' && cause instanceof MediaError) {
+      lines.push(`MediaError code ${cause.code}${cause.message ? `: ${cause.message}` : ''}`)
+      break
+    }
+    lines.push(messageOf(cause))
+    cause = (cause as { cause?: unknown })?.cause
+  }
+  return lines.length ? lines.join('\n') : undefined
+}
+
 /**
  * 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 +72,32 @@ 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 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. It is not ours: it reproduces on this player as it stood in
+   * October 2025, on a local file, and on every version since.
+   *
+   * 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 })
+  const restartTimer = useRef<ReturnType<typeof setTimeout>>(undefined)
+  // The streak belongs to one media, not to the player, and a pending rebuild of the old one must
+  // not land on the new one.
+  useEffect(() => {
+    restarts.current = { count: 0, at: 0 }
+    player.setSourceState({ playbackErrors: [] })
+    return () => { if (restartTimer.current) clearTimeout(restartTimer.current) }
+    // `player` is stable; listing it would not re-run this, and the reset belongs to the media
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [size])
+
   const controllerRef = useRef<PlaybackController | null>(null)
   /**
    * Where to pick playback back up, and WHICH media that position belongs to.
@@ -81,8 +150,42 @@ export const usePlayback = (
     if (!video || !canvas || !size || !read) return
     let cancelled = false
     player.setSourceState({ playbackError: null, ready: false })
+
+    /**
+     * Keep the failure, whether or not the viewer is about to be told about it.
+     *
+     * Appended rather than replaced, and never cleared by a recovery: a rebuild that works leaves
+     * `playbackError` null and would otherwise erase the only evidence that anything went wrong.
+     */
+    const record = (error: unknown, recovered: boolean) => {
+      const entry: PlaybackErrorEntry = {
+        at: Date.now(),
+        atMediaTime: Number.isFinite(video.currentTime) ? video.currentTime : undefined,
+        message: messageOf(error),
+        detail: causeChain(error),
+        recovered,
+      }
+      player.setSourceState({ playbackErrors: [...player.playbackErrors, entry] })
+    }
     const fail = (error: unknown) => {
       if (cancelled) return
+      const recoverable = isMediaElementError(error)
+      record(error, recoverable)
+      // 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.
+      if (recoverable) {
+        const now = performance.now()
+        // a failure long after the last one is not part of a streak, so it pays no delay
+        if (now - restarts.current.at > RESTART_SETTLED_MS) restarts.current = { count: 0, at: now }
+        const delay = RESTART_BACKOFF_MS[Math.min(restarts.current.count, RESTART_BACKOFF_MS.length - 1)]!
+        restarts.current = { count: restarts.current.count + 1, at: now }
+        console.warn(`the media element failed; rebuilding the pipeline${delay ? ` in ${delay}ms` : ''}`, error)
+        if (restartTimer.current) clearTimeout(restartTimer.current)
+        // still queued through a timer at zero delay, so the rebuild never runs inside the callback
+        // that reported the failure
+        restartTimer.current = setTimeout(() => setRestartToken((token) => token + 1), delay)
+        return
+      }
       console.error('playback failed', error)
       player.setSourceState({ playbackError: error })
       onPlaybackErrorRef.current?.(error)
@@ -154,6 +257,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/source-feature.ts

@@ -22,6 +22,25 @@ export type TrackChoice = {
   disabled?: boolean
 }
 
+/**
+ * One failure, kept so it can be read back and copied out long after playback recovered from it.
+ *
+ * Flattened to strings at the moment it happens rather than held as the `Error`: this is a report,
+ * the cause chain is most of what makes it useful, and an `Error` in a store is a live object whose
+ * `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. */
+  at: number
+  /** Seconds into the media, which is usually the first question asked of a playback failure. */
+  atMediaTime?: number
+  message: string
+  /** The `cause` chain, already unwound, one line per level. */
+  detail?: string
+  /** Whether the pipeline came back from it by itself. */
+  recovered: boolean
+}
+
 /**
  * A byte span of the file the consumer has in hand, mapped onto the timeline through the keyframe
  * index, because a file's download percentage is not its playback percentage.
@@ -100,6 +119,15 @@ export type SourceState = {
 
   /** Set when the pipeline fails. Cleared when it recovers. */
   playbackError: unknown
+  /**
+   * Every failure this source has had, oldest first, whether or not the viewer ever saw one.
+   *
+   * `playbackError` is the CURRENT state and is cleared on recovery, so on its own it hides exactly
+   * the failures worth knowing about: a media element that firefox wedged is rebuilt and playback
+   * carries on, leaving no trace anywhere. This is the record, and the control bar offers it only
+   * once there is something in it.
+   */
+  playbackErrors: PlaybackErrorEntry[]
   /** Whether the engine has produced its first media segment. */
   ready: boolean
 
@@ -128,6 +156,7 @@ const initialState: SourceState = {
   pictureInPictureMode: null,
   burnedInSubtitles: false,
   playbackError: null,
+  playbackErrors: [],
   ready: false,
   setSourceState: () => {},
 }

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
 }