@banou/media-player 0.8.13 → 0.8.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/media-player",
-  "version": "0.8.13",
+  "version": "0.8.16",
   "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

@@ -43,6 +43,8 @@ export type PlaybackController = {
    * because this can take as long as a read, which over a torrent has no ceiling.
    */
   prepareSeek: (time: number) => Promise<void>
+  /** The element this pipeline drives, so a caller can read what actually got buffered. */
+  videoElement: HTMLVideoElement
   selectSubtitleStream: (streamIndex: number | undefined) => void
   /** Keyframe index of the input, which is what maps a downloaded byte range onto the timeline. */
   indexes: MediaIndex[]
@@ -81,6 +83,16 @@ 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
+/*
+ * Seconds of data a seek target needs behind it before the playhead is allowed to move there.
+ *
+ * Covering the target instant is not enough: the element plays through a one chunk island in well
+ * under a second and runs dry, and that underrun drains firefox's decoder just as a seek into a hole
+ * does. Measured in production, six seeks that all reported themselves prepared still wedged.
+ */
+const SEEK_RUNWAY = 3
+// reads allowed to build that runway, so a source that answers with nothing cannot spin here
+const SEEK_RUNWAY_READS = 12
 // 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
@@ -219,6 +231,16 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
     let seeking = false
     // how many prepares are in flight, so eviction knows not to delete what they are fetching
     let preparing = 0
+    /*
+     * Where buffering should aim while a seek is being prepared.
+     *
+     * The playhead has not moved there yet, so anything anchored on `currentTime` is aiming at the
+     * position being left behind. `needsData` in particular would answer for the old position and
+     * stop reading, which is how a prepare came to leave a one chunk island: enough to cover the
+     * target instant, and nowhere near enough to play from.
+     */
+    let prepareTarget: number | undefined
+    const bufferAnchor = () => prepareTarget ?? videoElement.currentTime
     let finished = false
     // libav aborts the running task when a new one starts, so both flags need a generation token
     let readGeneration = 0
@@ -272,10 +294,20 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
     const needsData = () => {
       const ranges = getTimeRanges(sourceBuffer)
       if (!ranges.length) return true
-      const ct = videoElement.currentTime
-      // never read past what evict() keeps
-      if (Math.max(...ranges.map((r) => r.end)) >= ct + POST_EVICT) return false
+      const ct = bufferAnchor()
       const range = ranges.find((r) => r.start <= ct + BOUNDARY_SLACK && ct < r.end)
+      /*
+       * Never read past what evict() keeps, measured on the run holding the anchor rather than
+       * across every island.
+       *
+       * Taking the max end over ALL ranges meant one stale island far ahead could refuse a read
+       * right where the playhead was about to be. Repeated seeking is exactly how those islands
+       * appear, and eviction is suppressed while a seek is being prepared, so they survive to do it.
+       * Seen in production as forward seeks getting a 4s runway while every BACKWARD seek collapsed
+       * to 1.0s, then 0.5s, then 0.3s, and wedged: the island left out at ~760s was past
+       * `target + POST_EVICT` for every one of them.
+       */
+      if (range && range.end >= ct + POST_EVICT) return false
       return !range || range.end < ct + BUFFER_TARGET
     }
 
@@ -417,14 +449,51 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
      * The CALLER owns the deadline: this can take as long as a read takes, and over a torrent that
      * is unbounded.
      */
+    /** Seconds of contiguous data past a position that make it safe to play from. */
+    const runwayFrom = (time: number) => {
+      const range = getTimeRanges(sourceBuffer).find((r) => r.start <= time + BOUNDARY_SLACK && time < r.end)
+      return range ? range.end - time : 0
+    }
+
     const prepareSeek = async (time: number) => {
-      if (destroyed || playableAt(time)) return
+      if (destroyed) return
+      if (runwayFrom(time) >= SEEK_RUNWAY) return
       finished = false
       preparing++
+      prepareTarget = time
       try {
-        await seekTo(time)
+        if (!playableAt(time)) await seekTo(time)
+        /*
+         * Captured AFTER the seek, never before.
+         *
+         * `seekTo` bumps `seekGeneration` itself, so a generation read before it is stale the moment
+         * it returns and every staleness check below fails on its first pass. That silently disabled
+         * this entire loop: prepares came back in ~170ms with a 0.5s to 1.9s island and the runway
+         * was never built at all.
+         */
+        const generation = seekGeneration
+        /*
+         * Then keep reading until there is something to PLAY, not merely something to land on.
+         *
+         * `remuxer.seek` returns a single chunk, so the first version of this left a small island:
+         * the element arrived on covered ground, played through it in well under a second, and ran
+         * dry there. That underrun drains the decoder exactly as a seek into a hole would, and it
+         * wedged in production with every seek reporting itself as prepared. Preparing a point was
+         * never the requirement; preparing a runway is.
+         *
+         * Bounded twice over: by the runway being reached, and by a read that returns nothing new.
+         * The caller's deadline bounds the wall clock on top of that.
+         */
+        for (let attempt = 0; attempt < SEEK_RUNWAY_READS; attempt++) {
+          if (destroyed || generation !== seekGeneration || finished) break
+          if (runwayFrom(time) >= SEEK_RUNWAY) break
+          const before = runwayFrom(time)
+          await pump()
+          if (runwayFrom(time) <= before) break
+        }
       } finally {
         preparing--
+        if (prepareTarget === time) prepareTarget = undefined
       }
     }
 
@@ -564,6 +633,7 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
     return {
       destroy: runTeardown,
       prepareSeek,
+      videoElement,
       selectSubtitleStream: (streamIndex: number | undefined) => subtitles.selectStream(streamIndex),
       indexes: metadata.indexes ?? [],
       duration: metadata.info.input.duration,

package/src/lib/engine/subtitles.ts

@@ -1,4 +1,3 @@
-import type { ParsedASS, ParsedASSStyles } from 'ass-compiler'
 import type { ASS_Event } from 'jassub'
 import type { Attachment, SubtitleFragment } from 'libav-wasm/build/worker'
 
@@ -10,8 +9,17 @@ export type SubtitleStream = { streamIndex: number, title: string, language: str
 /** -1 turns subtitles off. It frees the track and matches no header, so nothing is set. */
 export const SUBTITLES_OFF = -1
 
-type SubtitleHeaderPart = { type: 'header', streamIndex: number, content: string, eventsContent: string, parsed: ParsedASS }
-type SubtitleDialoguePart = { type: 'dialogue', streamIndex: number, index: number, assEvent: ASS_Event }
+/**
+ * jassub's `ASS_Event` types `Style` as a string, which the library it wraps does not agree with:
+ * the field is written straight through to libass's `int Style`, an index into the track's style
+ * list. Corrected once, here, so a name cannot end up in it again.
+ */
+type StyledEvent = Omit<ASS_Event, 'Style'> & { Style: number }
+
+const createEvent = (jassub: JASSUB, event: StyledEvent) => jassub.createEvent(event as unknown as ASS_Event)
+
+type SubtitleHeaderPart = { type: 'header', streamIndex: number, content: string, eventsContent: string, styles: Map<string, number> }
+type SubtitleDialoguePart = { type: 'dialogue', streamIndex: number, index: number, assEvent: StyledEvent }
 
 export type SubtitleRendererOptions = {
   video: HTMLVideoElement
@@ -34,35 +42,36 @@ export type SubtitleRendererOptions = {
 
 const convertTimestamp = (ms: number) => new Date(ms).toISOString().slice(11, 22)
 
-const appendParsedStyle = (jassub: JASSUB, style: ParsedASSStyles['style'][number]) =>
-  jassub.createStyle({
-    ...style,
-    treat_fontname_as_pattern: 0,
-    Blur: 0,
-    Justify: 0,
-    FontName: style.Fontname,
-    FontSize: Number(style.Fontsize),
-    PrimaryColour: Number(style.PrimaryColour),
-    SecondaryColour: Number(style.SecondaryColour),
-    OutlineColour: Number(style.OutlineColour),
-    BackColour: Number(style.BackColour),
-    Bold: Number(style.Bold),
-    Italic: Number(style.Italic),
-    Underline: Number(style.Underline),
-    StrikeOut: Number(style.StrikeOut),
-    ScaleX: Number(style.ScaleX),
-    ScaleY: Number(style.ScaleY),
-    Spacing: Number(style.Spacing),
-    Angle: Number(style.Angle),
-    BorderStyle: Number(style.BorderStyle),
-    Outline: Number(style.Outline),
-    Shadow: Number(style.Shadow),
-    Alignment: Number(style.Alignment),
-    MarginL: Number(style.MarginL),
-    MarginR: Number(style.MarginR),
-    MarginV: Number(style.MarginV),
-    Encoding: Number(style.Encoding),
-  } as Parameters<JASSUB['createStyle']>[0])
+/**
+ * How many styles libass keeps in front of the ones the file declares.
+ *
+ * `ass_new_track` always allocates its own "Default" at index 0 before parsing a line of the header,
+ * so the file's first style lands at 1. That number is what an event's `Style` field holds: libass
+ * reads it as an index into the track's style list and nothing else. `subtitle-scale.browser.test.tsx`
+ * is what pins this, by measuring the rendered text against what libass itself draws.
+ */
+const LIBASS_OWN_STYLES = 1
+
+const headerStyles = (content: string) =>
+  // a duplicated name resolves to the LAST one, the way libass's own lookup scans the list backwards
+  new Map(parse(content).styles.style.map((style, index) => [style.Name, index + LIBASS_OWN_STYLES]))
+
+/**
+ * The index libass will resolve this event's style to.
+ *
+ * jassub types `ASS_Event.Style` as a string and writes it straight through to an `int`, so handing
+ * it a style NAME stores 0, which is libass's own default: Arial at size 18, with margins and a drop
+ * shadow of its own. Subtitles still appear, in a face and a size the file never asked for.
+ *
+ * Falling back to the header's own "Default", then to 0, is what libass does for a name it cannot
+ * find. The leading-`*` strip and the case fold on "Default" are its normalisation, kept so a
+ * `*Default` written by an older tool resolves here too.
+ */
+const styleIndex = (header: SubtitleHeaderPart, name: string) => {
+  const stripped = name.replace(/^\*+/, '')
+  const key = stripped.toLowerCase() === 'default' ? 'Default' : stripped
+  return header.styles.get(key) ?? header.styles.get('Default') ?? 0
+}
 
 // cleared so jassub scales the script to the canvas, not to the authored resolution
 const renderable = (content: string) => {
@@ -84,7 +93,7 @@ const toHeaderPart = (fragment: SubtitleFragment & { type: 'header' }): Subtitle
     console.warn(`subtitle stream ${fragment.streamIndex} has no Events format, ignoring the track`)
     return null
   }
-  return { type: 'header', streamIndex: fragment.streamIndex, content: fragment.content, eventsContent, parsed: parse(fragment.content) }
+  return { type: 'header', streamIndex: fragment.streamIndex, content: fragment.content, eventsContent, styles: headerStyles(fragment.content) }
 }
 
 const toDialoguePart = (header: SubtitleHeaderPart, fragment: SubtitleFragment & { type: 'dialogue' }): SubtitleDialoguePart => {
@@ -102,6 +111,7 @@ const toDialoguePart = (header: SubtitleHeaderPart, fragment: SubtitleFragment &
     index: dialogueIndex,
     assEvent: {
       ...event,
+      Style: styleIndex(header, event.Style),
       Effect: event.Effect ?? '',
       Text: event.Text.raw,
       Duration: (event.End - event.Start) * 1000,
@@ -109,7 +119,7 @@ const toDialoguePart = (header: SubtitleHeaderPart, fragment: SubtitleFragment &
       End: event.End * 1000,
       ReadOrder: dialogueIndex,
       _index: dialogueIndex,
-    } as ASS_Event,
+    } as StyledEvent,
   }
 }
 
@@ -149,7 +159,6 @@ export const createSubtitleRenderer = (options: SubtitleRendererOptions) => {
     // jassub 1.8.x binds setRate as the ratechange listener, so the Event becomes the rate
     video.removeEventListener('ratechange', (jassub as unknown as { _boundSetRate: EventListener })._boundSetRate)
     video.addEventListener('ratechange', onRateChange)
-    for (const style of header.parsed.styles.style) appendParsedStyle(jassub, style)
   }
 
   const pushAttachments = (incoming: Attachment[]) => {
@@ -175,7 +184,7 @@ export const createSubtitleRenderer = (options: SubtitleRendererOptions) => {
         const part = toDialoguePart(header, fragment)
         if (byIndex.has(part.index)) continue
         byIndex.set(part.index, part)
-        if (selected === fragment.streamIndex) jassub?.createEvent(part.assEvent)
+        if (selected === fragment.streamIndex && jassub) createEvent(jassub, part.assEvent)
       }
     }
   }
@@ -188,8 +197,7 @@ export const createSubtitleRenderer = (options: SubtitleRendererOptions) => {
     const header = headers.get(next)
     if (!header) return
     jassub.setTrack(renderable(header.content))
-    for (const style of header.parsed.styles.style) appendParsedStyle(jassub, style)
-    for (const part of dialogues.get(next)?.values() ?? []) jassub.createEvent(part.assEvent)
+    for (const part of dialogues.get(next)?.values() ?? []) createEvent(jassub, part.assEvent)
     jassub.setCurrentTime(video.paused, video.currentTime, video.playbackRate)
   }
 

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

@@ -181,6 +181,9 @@ const style = css`
   }
 `
 
+/** Movement from the press, in px, past which a gesture is a scrub rather than a click. */
+const SCRUB_THRESHOLD_PX = 4
+
 export const ProgressBar = () => {
   const player = usePlayer()
   const currentTime = usePlayer((state) => state.currentTime)
@@ -200,7 +203,36 @@ export const ProgressBar = () => {
   // onChange reports a bare fraction, so the device that opened the gesture is recorded on press
   const dragPointerType = useRef<string | undefined>(undefined)
 
+  /*
+   * How many changes this gesture has produced, which is what tells a click from a scrub.
+   *
+   * `useDragValue` reports onChange on the PRESS and again on every move, so a click that drifts one
+   * pixel produces two. Counting them is exact where a timer is not: the first is the press, and
+   * anything after it is the pointer actually moving.
+   */
+  const changesThisPress = useRef(0)
+  const latestFraction = useRef<number | undefined>(undefined)
+  const pressFraction = useRef<number | undefined>(undefined)
+  /*
+   * Whether this gesture has become a scrub, latched once it has.
+   *
+   * A pixel of drift is a click, not a drag: every real mouse produces some. Counting changes was
+   * not enough, because that pixel arrives as a pointermove and so looked like scrubbing, which put
+   * the playhead onto unbuffered ground before its data existed and wedged firefox exactly as
+   * before. Distance from the press is the honest test, and it latches so that dragging back toward
+   * the origin does not flip the gesture back into a click.
+   */
+  const isScrub = useRef(false)
+
   const onSeekDrag = (fraction: number) => {
+    changesThisPress.current += 1
+    latestFraction.current = fraction
+    if (pressFraction.current === undefined) {
+      pressFraction.current = fraction
+    } else if (!isScrub.current) {
+      const width = progressBarRef.current?.getBoundingClientRect().width ?? 0
+      if (Math.abs(fraction - pressFraction.current) * width > SCRUB_THRESHOLD_PX) isScrub.current = true
+    }
     setSeekFraction(fraction)
     if (dragPointerType.current === 'mouse') return
     setProgressBarOverTime(fraction * duration)
@@ -210,11 +242,31 @@ export const ProgressBar = () => {
 
   const onDragStart: DOMAttributes<HTMLDivElement>['onPointerDown'] = (ev) => {
     dragPointerType.current = ev.pointerType
+    changesThisPress.current = 0
+    pressFraction.current = undefined
+    isScrub.current = false
     handlers.onPointerDown(ev)
   }
 
   const onDragEnd: DOMAttributes<HTMLDivElement>['onPointerUp'] = (ev) => {
     handlers.onPointerUp(ev)
+    /*
+     * The seek that counts, and the only one allowed to move the playhead onto new ground.
+     *
+     * Where the gesture ENDED is the position anyone is waiting for, and it is issued through
+     * `requestSeek` so the data is in place before the element demuxes there. A seek into a hole is
+     * what wedges firefox's decoder, and the whole gesture exists to arrive at this one moment.
+     */
+    // a pointerup with no press behind it is not this gesture, and must not seek anywhere
+    const fraction = changesThisPress.current > 0 ? latestFraction.current : undefined
+    if (fraction !== undefined && duration) {
+      const timestamp = fraction * duration
+      if (requestSeek) requestSeek(timestamp)
+      else player.seek(timestamp)
+    }
+    changesThisPress.current = 0
+    isScrub.current = false
+    pressFraction.current = undefined
     // a lifted finger leaves nothing over the bar, so the preview it opened closes with it
     if (ev.pointerType === 'mouse') return
     setProgressBarOverTime(undefined)
@@ -273,15 +325,20 @@ export const ProgressBar = () => {
     return `${hoursString}${minutes < 10 ? '0' : ''}${minutes}:${seconds < 10 ? '0' : ''}${seconds}`
   }, [progressBarHoverTime])
 
+  /*
+   * Follow the pointer while it is actually moving, and NOT on the press itself.
+   *
+   * Seeking on the press is what defeated the first version of this: a click that drifts a pixel
+   * looked like a drag, so the playhead jumped onto unbuffered ground before its data existed, which
+   * is exactly the wedge. A scrub still follows the pointer, because a drag has never reproduced the
+   * fault (its seeks land ~28ms apart, far too fast for a drain to complete) and a frozen picture
+   * during a scrub would be a real regression. The settled position is handled on release.
+   */
   useEffect(() => {
     if (seekFraction === undefined || !duration) return
-    const timestamp = 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])
+    if (!dragging || !isScrub.current) return
+    player.seek(seekFraction * duration)
+  }, [player, dragging, seekFraction, duration])
 
   const scaleX = useMemo(() => {
     return !duration || typeof currentTime !== 'number'

package/src/lib/react/hooks/use-drag-value.ts

@@ -35,7 +35,10 @@ export const useDragValue = ({ ref, onChange, orientation = 'horizontal', disabl
     // events the seek preview runs on, the second keeps the press from reaching the document
     // listeners that close the popover and refresh the auto-hide timer.
     activePointer.current = event.pointerId
-    event.currentTarget.setPointerCapture?.(event.pointerId)
+    // Throws NotFoundError for a pointer id that is not active, and an exception here would abandon
+    // the gesture before it records anything. Capture is an optimisation for tracking outside the
+    // element, never a requirement.
+    try { event.currentTarget.setPointerCapture?.(event.pointerId) } catch {}
     setDragging(true)
     onChangeRef.current(fractionFor(event.clientX, event.clientY))
   }, [disabled, fractionFor])
@@ -48,7 +51,7 @@ export const useDragValue = ({ ref, onChange, orientation = 'horizontal', disabl
   const endDrag = useCallback((event: ReactPointerEvent<HTMLElement>) => {
     if (activePointer.current !== event.pointerId) return
     activePointer.current = null
-    event.currentTarget.releasePointerCapture?.(event.pointerId)
+    try { event.currentTarget.releasePointerCapture?.(event.pointerId) } catch {}
     setDragging(false)
   }, [])
 

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

@@ -33,13 +33,6 @@ const RESTART_SETTLED_MS = 60_000
  */
 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)
 
@@ -127,8 +120,6 @@ 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)
@@ -167,28 +158,51 @@ export const usePlayback = (
     if (!controller || seekPrepareBudgetMs <= 0) { player.seek(time); return }
 
     /*
-     * A drag is left exactly as it was.
+     * Every call gets the data first. There is deliberately no "this looks like a drag" shortcut.
      *
-     * 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.
+     * The first version of this guessed at drags from the gap between calls, and that is what let
+     * the fault through in production: the seek bar reports a change on the PRESS and again on every
+     * move, so a click that drifts one pixel produced two calls milliseconds apart, the second was
+     * read as a drag, and the playhead jumped onto unbuffered ground before its data existed. Two
+     * quick taps of the arrow keys would have done the same.
      *
-     * Discrete seeks are the ones that wedge it, at a few hundred ms apart, and those get the data
-     * first.
+     * The chrome knows what gesture it is in and now says so by only calling this for settled seeks,
+     * which is knowledge rather than inference. Rapid calls are safe here anyway: each supersedes
+     * the last through the engine's seek generation.
      */
-    const now = performance.now()
-    const dragging = now - lastSeekRequestAt.current < DRAG_SETTLE_MS
-    lastSeekRequestAt.current = now
-    if (dragging) { player.seek(time); return }
+    /*
+     * A debug trace, off unless asked for.
+     *
+     * The fault this prevents is reproducible in seconds on some machines and not at all on others,
+     * so the only way to learn anything from someone else's reproduction is to have the seek say
+     * what it did. Set `window.__mediaPlayerSeekDebug = true` (the dev route does it for
+     * `?seekDebug=1`) and every seek reports whether the data was ready, how long it waited, and
+     * whether the playhead moved before the data arrived, which is the exact condition that wedges
+     * firefox.
+     */
+    const debug = typeof window !== 'undefined' && (window as { __mediaPlayerSeekDebug?: boolean }).__mediaPlayerSeekDebug
+    const startedAt = performance.now()
 
     let moved = false
+    let movedBecause: 'prepared' | 'deadline' = 'prepared'
     const move = () => {
       if (moved) return
       moved = true
       player.seek(time)
+      if (debug) {
+        // eslint-disable-next-line no-console
+        const video = controller.videoElement
+        let runway = 0
+        if (video) {
+          for (let i = 0; i < video.buffered.length; i++) {
+            if (video.buffered.start(i) <= time + 1 && time < video.buffered.end(i)) runway = video.buffered.end(i) - time
+          }
+        }
+        // eslint-disable-next-line no-console
+        console.warn(`[media-player] seek to ${time.toFixed(2)} moved after ${Math.round(performance.now() - startedAt)}ms via ${movedBecause}, runway ${runway.toFixed(1)}s${movedBecause === 'deadline' ? ' (EXPOSED: moved before its data was ready)' : ''}`)
+      }
     }
-    const deadline = setTimeout(move, seekPrepareBudgetMs)
+    const deadline = setTimeout(() => { movedBecause = 'deadline'; move() }, seekPrepareBudgetMs)
     void controller
       .prepareSeek(time)
       // a failed prepare is not a reason to refuse the seek: the pump and the existing recovery