@banou/media-player 0.8.10 → 0.8.11

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

@@ -0,0 +1,15 @@
+import type { PlaybackErrorEntry } from '../source-feature';
+/** What lands on the clipboard: the same thing the panel shows, in the order it happened. */
+export declare const formatErrors: (errors: PlaybackErrorEntry[]) => string;
+/**
+ * The failures this session had, offered only once there has been one.
+ *
+ * It exists because the interesting failures are now the ones the viewer never sees: a media element
+ * that firefox wedged is rebuilt underneath them and playback carries on, which is the right
+ * behaviour and also erases the evidence. Without this, "it glitched and carried on" is unreportable.
+ *
+ * Copy is the point of the whole control. A decoder message is two hundred characters of C++ and
+ * nobody is going to retype it into an issue.
+ */
+export declare const ErrorsAction: () => import("@emotion/react/jsx-runtime").JSX.Element | null;
+export default ErrorsAction;

package/dist/react/player.d.ts

@@ -18,6 +18,7 @@ export declare const Player: import("@videojs/react").CreatePlayerResult<import(
     pictureInPictureMode: import("../engine").PictureInPictureMode | null;
     burnedInSubtitles: boolean;
     playbackError: unknown;
+    playbackErrors: import("./source-feature").PlaybackErrorEntry[];
     ready: boolean;
     setSourceState: (partial: Partial<import("./source-feature").SourceState>) => void;
 }>]>>;

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

@@ -18,6 +18,24 @@ 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.
@@ -88,6 +106,15 @@ export type SourceState = {
     burnedInSubtitles: boolean;
     /** 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;
     /**
@@ -154,6 +181,15 @@ export declare const sourceFeature: import("@videojs/react").PlayerFeature<{
     burnedInSubtitles: boolean;
     /** 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;
     /**

package/package.json

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

@@ -24,7 +24,7 @@ export type { PlayerStore } from './react/player'
 // Source state lives on the player store next to the built-in playback state, so `usePlayer` is the
 // only hook the chrome needs.
 export { sourceFeature } from './react/source-feature'
-export type { DownloadedRange, SourceState } from './react/source-feature'
+export type { DownloadedRange, PlaybackErrorEntry, SourceState } from './react/source-feature'
 
 export { useSeekThumbnails } from './react/hooks/use-thumbnails'
 export { usePictureInPicture } from './react/hooks/use-picture-in-picture'

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

@@ -11,6 +11,7 @@ import { TooltipDisplay } from './tooltip-display'
 import { ProgressBar } from './progress-bar'
 import pictureInPicture from '../../assets/picture-in-picture.svg'
 import { SubtitlesInPicture } from './icons'
+import ErrorsAction from './errors'
 import SettingsAction from './settings'
 import SubtitlesAction from './subtitles'
 import colors from '../../utils/colors'
@@ -106,7 +107,7 @@ const style = css`
         stroke: ${colors.accent};
       }
 
-      .play, .sound, .time, .subtitles, .settings, .picture-in-picture, .full-screen {
+      .play, .sound, .time, .errors, .subtitles, .settings, .picture-in-picture, .full-screen {
         display: flex;
         align-items: center;
 
@@ -124,7 +125,7 @@ const style = css`
         }
       }
 
-      .play, .sound, .subtitles, .settings, .picture-in-picture, .full-screen {
+      .play, .sound, .errors, .subtitles, .settings, .picture-in-picture, .full-screen {
         border-radius: 4px;
 
         padding: 8px;
@@ -307,6 +308,7 @@ export const ControlBar = () => {
           </div>
         </div>
         <div className='right'>
+          <ErrorsAction />
           <SubtitlesAction />
           <SettingsAction />
           {togglePictureInPicture

package/src/lib/react/components/errors.tsx

@@ -0,0 +1,194 @@
+/// <reference types="@emotion/react/types/css-prop" />
+import type { PlaybackErrorEntry } from '../source-feature'
+
+import { useState } from 'react'
+import { css } from '@emotion/react'
+import { AlertTriangle, Check, Copy } from 'react-feather'
+
+import { fonts } from '../../utils/fonts'
+import { formatTime } from '../../utils/time'
+import { usePlayer } from '../player'
+import { TooltipDisplay } from './tooltip-display'
+import { popoverStyle, useTrackMenu } from './track-menu'
+
+const style = css`
+/* Not a containing block, for the reason given on popoverStyle: the menu anchors to the control bar,
+   which is the width of the player box, so it can be clamped to it. */
+position: static;
+
+.errors {
+  /* the icon keeps its size, the pressable box grows around it */
+  @media (pointer: coarse) {
+    box-sizing: border-box;
+    justify-content: center;
+
+    min-width: 44px;
+    min-height: 44px;
+  }
+}
+
+${popoverStyle}
+
+.popover.error-list {
+  /* Wider than a track menu and taller, because these rows are sentences rather than labels, and a
+     decoder message that has been ellipsized is not worth copying. */
+  width: 420px;
+  max-height: min(300px, calc(100cqh - 100% - 16px));
+
+  /* track-menu's header is a left-aligned label row; here it carries a control too, so the two
+     ends go to the two ends */
+  .back {
+    justify-content: space-between;
+    gap: 8px;
+  }
+
+  .copy {
+    /* sits in the header row, which track-menu styles as .back */
+    display: flex;
+    align-items: center;
+    gap: 6px;
+
+    background: none;
+    border: none;
+    padding: 4px 6px;
+    border-radius: 4px;
+
+    color: #fff;
+    cursor: pointer;
+    ${fonts.bSmall.regular}
+
+    &:hover {
+      background-color: rgba(255,255,255,.1);
+    }
+
+    svg {
+      width: 14px;
+      height: 14px;
+    }
+  }
+
+  .entry {
+    /* one failure is a block of text, so it stacks instead of sitting on one line */
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 2px;
+
+    .when {
+      color: #bbb;
+      ${fonts.bSmall.regular}
+    }
+
+    .what {
+      /* the decoder's own words, which are long and must not be cut */
+      overflow-wrap: anywhere;
+      white-space: pre-wrap;
+    }
+
+    .cause {
+      color: #ddd;
+      overflow-wrap: anywhere;
+      white-space: pre-wrap;
+      ${fonts.bSmall.regular}
+    }
+  }
+}
+`
+
+const clock = (at: number) => new Date(at).toLocaleTimeString()
+
+// the chrome's own formatter, so a position in the log reads exactly like the one on the seekbar
+const mediaTime = (seconds: number | undefined) =>
+  seconds === undefined || !Number.isFinite(seconds) ? undefined : formatTime(Math.max(0, seconds))
+
+/** 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]' : ''}`
+      return [head, entry.message, entry.detail].filter(Boolean).join('\n')
+    })
+    .join('\n\n')
+
+/**
+ * The failures this session had, offered only once there has been one.
+ *
+ * It exists because the interesting failures are now the ones the viewer never sees: a media element
+ * that firefox wedged is rebuilt underneath them and playback carries on, which is the right
+ * behaviour and also erases the evidence. Without this, "it glitched and carried on" is unreportable.
+ *
+ * Copy is the point of the whole control. A decoder message is two hundred characters of C++ and
+ * nobody is going to retype it into an issue.
+ */
+export const ErrorsAction = () => {
+  const errors = usePlayer((state) => state.playbackErrors)
+  const { open, toggle, containerRef } = useTrackMenu()
+  const [copied, setCopied] = useState(false)
+
+  // After every hook, never before. Nothing to report means no button at all, rather than a control
+  // that is present and says "no errors": the bar is not the place to advertise that.
+  if (errors.length === 0) return null
+
+  const copy = () => {
+    // Deliberately unawaited state: the tick is feedback, not a promise the viewer waits on. A
+    // clipboard the browser refuses (no permission, insecure context) simply never ticks.
+    navigator.clipboard?.writeText(formatErrors(errors)).then(
+      () => {
+        setCopied(true)
+        setTimeout(() => setCopied(false), 2_000)
+      },
+      (error) => console.warn('[media-player] could not copy the errors:', error),
+    )
+  }
+
+  const label = `Playback errors (${errors.length})`
+
+  return (
+    <div css={style} ref={containerRef}>
+      <TooltipDisplay
+        id='errors'
+        disabled={open}
+        text={
+          <button
+            className='errors'
+            type='button'
+            onClick={toggle}
+            aria-label={label}
+            aria-expanded={open}
+          >
+            <AlertTriangle className='alert-triangle' />
+          </button>
+        }
+        toolTipText={<span>{label}</span>}
+      />
+      {
+        open && (
+          <div className='popover error-list'>
+            {/* `no-hover` because the header is a label with a control in it, not a row to click */}
+            <div className='back no-hover'>
+              <span>{label}</span>
+              <button className='copy' type='button' onClick={copy} aria-label='Copy the errors'>
+                {copied ? <Check /> : <Copy />}
+                <span>{copied ? 'Copied' : 'Copy'}</span>
+              </button>
+            </div>
+            {errors.map((entry, index) => (
+              <div className='entry no-hover' key={`${entry.at}-${index}`}>
+                <span className='when'>
+                  {clock(entry.at)}
+                  {mediaTime(entry.atMediaTime) ? ` at ${mediaTime(entry.atMediaTime)}` : ''}
+                  {entry.recovered ? ' recovered' : ''}
+                </span>
+                <span className='what'>{entry.message}</span>
+                {entry.detail ? <span className='cause'>{entry.detail}</span> : null}
+              </div>
+            ))}
+          </div>
+        )
+      }
+    </div>
+  )
+}
+
+export default ErrorsAction

package/src/lib/react/components/track-menu.tsx

@@ -83,10 +83,10 @@ export const popoverStyle = css`
     :last-of-type {
       border-radius: 0 0 8px 8px;
     }
-    :not(&.no-hover) {
+    &:not(.no-hover) {
       cursor: pointer;
     }
-    :not(&.no-hover):hover {
+    &:not(.no-hover):hover {
       background-color: rgba(255,255,255,.1);
     }
 

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

@@ -1,4 +1,5 @@
 import type { PlaybackController } from '../../engine'
+import type { PlaybackErrorEntry } from '../source-feature'
 import type { MediaPlayerLocalOptions } from '../video-player'
 
 import { useCallback, useEffect, useRef, useState } from 'react'
@@ -7,10 +8,47 @@ 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
+/**
+ * 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
@@ -39,18 +77,26 @@ export const usePlayback = (
    *
    * 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.
+   * 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 })
-  // 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 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)
   /**
@@ -104,20 +150,41 @@ 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. Counted in a window, so
-      // a file that wedges again and again still reaches the viewer rather than looping.
-      if (isMediaElementError(error)) {
+      // element instead of putting a dead player behind an error message.
+      if (recoverable) {
         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
-        }
+        // 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 })

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: () => {},
 }