@banou/media-player 0.8.9 → 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/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.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/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/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);
     }