@banou/media-player 0.9.0 → 0.10.0

package/dist/react/hooks/use-thumbnails.d.ts

@@ -9,4 +9,15 @@ export type UseSeekThumbnailsOptions = {
     /** When omitted the whole file is treated as readable, which is the case for a local file. */
     downloadedRanges?: DownloadedRange[];
 };
-export declare const useSeekThumbnails: ({ publicPath, workerUrl, length, read, downloadedRanges, }: UseSeekThumbnailsOptions) => ThumbnailImage[];
+export type SeekThumbnails = {
+    thumbnails: ThumbnailImage[];
+    /**
+     * Where the viewer is pointing on the seekbar, so that preview is decoded next.
+     *
+     * Stable for the life of the hook, so it can be published to the store once and called from a
+     * pointermove without re-rendering anything. A no-op until the generator boots, and on a source
+     * that brings its own storyboard.
+     */
+    requestThumbnail: (time: number | undefined) => void;
+};
+export declare const useSeekThumbnails: ({ publicPath, workerUrl, length, read, downloadedRanges, }: UseSeekThumbnailsOptions) => SeekThumbnails;

package/dist/react/player.d.ts

@@ -5,6 +5,7 @@ export declare const Player: import("@videojs/react").CreatePlayerResult<import(
     indexes: import("..").MediaIndex[];
     thumbnails: import("..").ThumbnailImage[];
     thumbnailAt?: (time: number) => import("..").ThumbnailImage | undefined;
+    requestThumbnail: (time: number | undefined) => void;
     subtitleTracks: import("./source-feature").TrackChoice[];
     selectedSubtitleTrack: string | number | undefined;
     selectSubtitleTrack: (id: string | number | undefined) => void | Promise<void>;

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

@@ -76,6 +76,17 @@ export type SourceState = {
      * Falls back to scanning `thumbnails` when absent, which is what the engine's generator fills.
      */
     thumbnailAt?: (time: number) => ThumbnailImage | undefined;
+    /**
+     * Where the pointer is on the seekbar, so the preview under it is generated before the rest.
+     *
+     * Generation otherwise walks the file start to end, so pointing at the last third of a long video
+     * means waiting out everything before it. Called on every pointermove, which is why it is a
+     * callback on the store rather than a piece of state: a hover time held in the store would
+     * re-render every subscriber for each move.
+     *
+     * A no-op on a source that brings its own storyboard, and until the generator has booted.
+     */
+    requestThumbnail: (time: number | undefined) => void;
     /**
      * Both selectors may answer with a promise, and the menu waits on it.
      *
@@ -163,6 +174,17 @@ export declare const sourceFeature: import("@videojs/react").PlayerFeature<{
      * Falls back to scanning `thumbnails` when absent, which is what the engine's generator fills.
      */
     thumbnailAt?: (time: number) => ThumbnailImage | undefined;
+    /**
+     * Where the pointer is on the seekbar, so the preview under it is generated before the rest.
+     *
+     * Generation otherwise walks the file start to end, so pointing at the last third of a long video
+     * means waiting out everything before it. Called on every pointermove, which is why it is a
+     * callback on the store rather than a piece of state: a hover time held in the store would
+     * re-render every subscriber for each move.
+     *
+     * A no-op on a source that brings its own storyboard, and until the generator has booted.
+     */
+    requestThumbnail: (time: number | undefined) => void;
     /**
      * Both selectors may answer with a promise, and the menu waits on it.
      *

package/package.json

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

@@ -29,6 +29,17 @@ const KEYFRAME_TIMEOUT = 10_000
 export type ThumbnailGenerator = {
   /** Report which byte ranges are readable. Called with no argument when the whole file is. */
   update: (ranges?: [number, number][]) => void
+  /**
+   * Where the viewer is pointing, so that preview is decoded next. `undefined` when they stop.
+   *
+   * Only the slot covering `time` jumps the queue, and only for as long as it is still waiting, so
+   * this moves one preview forward rather than re-ordering the run. Everything behind it keeps the
+   * order it was claimed in and carries on the moment the jumped slot is done.
+   *
+   * It cannot interrupt a decode that has already started, so the wait is the tail of the one in
+   * flight and not the whole backlog.
+   */
+  prioritize: (time: number | undefined) => void
   destroy: () => void
 }
 
@@ -68,7 +79,35 @@ export const createThumbnailGenerator = async (options: ThumbnailGeneratorOption
 
     let thumbnails: ThumbnailImage[] = []
     let destroyed = false
-    let queue = Promise.resolve()
+
+    /*
+     * Slots claimed for decoding but not yet started, in the order they were claimed.
+     *
+     * A promise chain used to be this queue, which fixed the running order at the moment each slot
+     * was chained on and left nothing a hover could reach: the preview under the pointer waited
+     * behind every slot already queued, which on a long file is the rest of the run. The order is
+     * the same, it is just held somewhere a pick can look into.
+     */
+    const pending: Slot[] = []
+    let running = false
+    /** Where the pointer is on the seekbar, or undefined when it is off it. */
+    let priorityTime: number | undefined
+
+    /*
+     * The slot to decode next: the one under the pointer when it is still waiting, else the oldest claim.
+     *
+     * Requiring the slot to COVER the time is what keeps this a single jump rather than a re-sort
+     * around the cursor. Once that slot is decoded nothing covers the pointer any more, so the very
+     * next pick is the oldest claim again and the sequential walk carries on where it left off.
+     */
+    const nextIndex = () => {
+      const at = priorityTime
+      if (at !== undefined) {
+        const hit = pending.findIndex(({ timestamp, endTime }) => timestamp <= at && at < endTime)
+        if (hit >= 0) return hit
+      }
+      return 0
+    }
 
     // the slider assumes a gapless storyboard, so gaps get sentinels the UI hides
     const emit = () => {
@@ -88,29 +127,44 @@ export const createThumbnailGenerator = async (options: ThumbnailGeneratorOption
       onThumbnails(display)
     }
 
-    const generate = (slot: Slot) => {
-      slot.done = true
-      queue = queue
-        .then(async () => {
-          if (destroyed) return
-          const png = await Promise.race([
-            remuxer.readKeyframe(slot.timestamp),
-            new Promise<never>((_, reject) => setTimeout(() => reject(new Error('timed out')), KEYFRAME_TIMEOUT)),
-          ])
-          const bitmap = await createImageBitmap(new Blob([png], { type: 'image/png' }))
-          const canvas = new OffscreenCanvas(width, Math.max(1, Math.round(bitmap.height * (width / bitmap.width))))
-          canvas.getContext('2d')!.drawImage(bitmap, 0, 0, canvas.width, canvas.height)
-          bitmap.close()
-          const blob = await canvas.convertToBlob({ type: 'image/webp', quality: 0.7 })
-          if (destroyed) return
-          thumbnails = [...thumbnails, { url: URL.createObjectURL(blob), startTime: slot.timestamp, endTime: slot.endTime }]
-            .sort((a, b) => a.startTime - b.startTime)
-          emit()
-        })
+    const decode = async (slot: Slot) => {
+      if (destroyed) return
+      const png = await Promise.race([
+        remuxer.readKeyframe(slot.timestamp),
+        new Promise<never>((_, reject) => setTimeout(() => reject(new Error('timed out')), KEYFRAME_TIMEOUT)),
+      ])
+      const bitmap = await createImageBitmap(new Blob([png], { type: 'image/png' }))
+      const canvas = new OffscreenCanvas(width, Math.max(1, Math.round(bitmap.height * (width / bitmap.width))))
+      canvas.getContext('2d')!.drawImage(bitmap, 0, 0, canvas.width, canvas.height)
+      bitmap.close()
+      const blob = await canvas.convertToBlob({ type: 'image/webp', quality: 0.7 })
+      if (destroyed) return
+      thumbnails = [...thumbnails, { url: URL.createObjectURL(blob), startTime: slot.timestamp, endTime: slot.endTime }]
+        .sort((a, b) => a.startTime - b.startTime)
+      emit()
+    }
+
+    // one decode at a time, because there is one wasm worker behind them all
+    const pump = () => {
+      if (running || destroyed || !pending.length) return
+      const slot = pending.splice(nextIndex(), 1)[0]!
+      running = true
+      void decode(slot)
         .catch(() => {
           slot.attempts += 1
+          // left claimable again, so a later `update` retries it
           slot.done = slot.attempts >= MAX_ATTEMPTS
         })
+        .finally(() => {
+          running = false
+          pump()
+        })
+    }
+
+    const claim = (slot: Slot) => {
+      slot.done = true
+      pending.push(slot)
+      pump()
     }
 
     emit()
@@ -120,11 +174,16 @@ export const createThumbnailGenerator = async (options: ThumbnailGeneratorOption
         if (destroyed) return
         for (const slot of slots) {
           if (slot.done) continue
-          if (!ranges || ranges.some(([from, to]) => from <= slot.startByte && slot.endByte <= to)) generate(slot)
+          if (!ranges || ranges.some(([from, to]) => from <= slot.startByte && slot.endByte <= to)) claim(slot)
         }
       },
+      prioritize: (time) => {
+        if (destroyed) return
+        priorityTime = time
+      },
       destroy: () => {
         destroyed = true
+        pending.length = 0
         for (const t of thumbnails) URL.revokeObjectURL(t.url)
         thumbnails = []
         terminateRemuxer(remuxer)

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

@@ -194,12 +194,25 @@ export const ProgressBar = () => {
   const indexes = usePlayer((state) => state.indexes)
   const thumbnails = usePlayer((state) => state.thumbnails)
   const thumbnailAt = usePlayer((state) => state.thumbnailAt)
+  const requestThumbnail = usePlayer((state) => state.requestThumbnail)
 
   const progressBarRef = useRef<HTMLDivElement>(null)
 
   const [seekFraction, setSeekFraction] = useState<number | undefined>(undefined)
   const [progressBarHoverTime, setProgressBarOverTime] = useState<number | undefined>(undefined)
 
+  /*
+   * Move the preview and the generator's next pick together.
+   *
+   * The frame under the pointer is both the one drawn and the one worth decoding first, and every
+   * place that opens or closes the preview goes through here so the two can never disagree. The
+   * request is a bare assignment inside the generator, so a pointermove costs nothing extra.
+   */
+  const showPreviewAt = (time: number | undefined) => {
+    setProgressBarOverTime(time)
+    requestThumbnail(time)
+  }
+
   // onChange reports a bare fraction, so the device that opened the gesture is recorded on press
   const dragPointerType = useRef<string | undefined>(undefined)
 
@@ -235,7 +248,7 @@ export const ProgressBar = () => {
     }
     setSeekFraction(fraction)
     if (dragPointerType.current === 'mouse') return
-    setProgressBarOverTime(fraction * duration)
+    showPreviewAt(fraction * duration)
   }
 
   const { dragging, handlers } = useDragValue({ ref: progressBarRef, onChange: onSeekDrag })
@@ -269,7 +282,7 @@ export const ProgressBar = () => {
     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)
+    showPreviewAt(undefined)
   }
 
   // offsetX is relative to whichever child is under the pointer, and a captured pointer has none
@@ -281,12 +294,12 @@ export const ProgressBar = () => {
   }
 
   const onProgressBarOver: DOMAttributes<HTMLDivElement>['onMouseMove'] = (ev) => {
-    setProgressBarOverTime(timeAtClientX(ev.clientX))
+    showPreviewAt(timeAtClientX(ev.clientX))
   }
 
   const hideProgressBarTime = () => {
     if (!progressBarRef.current) return
-    setProgressBarOverTime(undefined)
+    showPreviewAt(undefined)
   }
 
   // duration is 0 until metadata lands, which is never a divisor

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

@@ -1,7 +1,7 @@
 import type { ThumbnailGenerator, ThumbnailImage } from '../../engine'
 import type { DownloadedRange } from '../source-feature'
 
-import { useEffect, useMemo, useRef, useState } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 
 import { createThumbnailGenerator } from '../../engine'
 
@@ -19,9 +19,21 @@ export type UseSeekThumbnailsOptions = {
   downloadedRanges?: DownloadedRange[]
 }
 
+export type SeekThumbnails = {
+  thumbnails: ThumbnailImage[]
+  /**
+   * Where the viewer is pointing on the seekbar, so that preview is decoded next.
+   *
+   * Stable for the life of the hook, so it can be published to the store once and called from a
+   * pointermove without re-rendering anything. A no-op until the generator boots, and on a source
+   * that brings its own storyboard.
+   */
+  requestThumbnail: (time: number | undefined) => void
+}
+
 export const useSeekThumbnails = ({
   publicPath, workerUrl, length, read, downloadedRanges,
-}: UseSeekThumbnailsOptions): ThumbnailImage[] => {
+}: UseSeekThumbnailsOptions): SeekThumbnails => {
   const [thumbnails, setThumbnails] = useState<ThumbnailImage[]>([])
   const generatorRef = useRef<ThumbnailGenerator | null>(null)
   const readRef = useRef(read)
@@ -74,5 +86,9 @@ export const useSeekThumbnails = ({
 
   useEffect(() => { generatorRef.current?.update(ranges) }, [ranges])
 
-  return thumbnails
+  const requestThumbnail = useCallback((time: number | undefined) => {
+    generatorRef.current?.prioritize(time)
+  }, [])
+
+  return { thumbnails, requestThumbnail }
 }

package/src/lib/react/source-feature.ts

@@ -83,6 +83,17 @@ export type SourceState = {
    * Falls back to scanning `thumbnails` when absent, which is what the engine's generator fills.
    */
   thumbnailAt?: (time: number) => ThumbnailImage | undefined
+  /**
+   * Where the pointer is on the seekbar, so the preview under it is generated before the rest.
+   *
+   * Generation otherwise walks the file start to end, so pointing at the last third of a long video
+   * means waiting out everything before it. Called on every pointermove, which is why it is a
+   * callback on the store rather than a piece of state: a hover time held in the store would
+   * re-render every subscriber for each move.
+   *
+   * A no-op on a source that brings its own storyboard, and until the generator has booted.
+   */
+  requestThumbnail: (time: number | undefined) => void
 
   /**
    * Both selectors may answer with a promise, and the menu waits on it.
@@ -168,6 +179,7 @@ export type SourceState = {
 const initialState: SourceState = {
   indexes: [],
   thumbnails: [],
+  requestThumbnail: () => {},
   subtitleTracks: [],
   selectedSubtitleTrack: undefined,
   selectSubtitleTrack: () => {},

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

@@ -237,7 +237,7 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
   // so there is nothing for them to attach to and nothing to guard at the call site.
   usePlayback(video, subtitleLayer, local)
 
-  const generatedThumbnails = useSeekThumbnails({
+  const { thumbnails: generatedThumbnails, requestThumbnail } = useSeekThumbnails({
     publicPath,
     workerUrl: libavWorkerUrl,
     length: thumbnailsEnabled === false ? undefined : size,
@@ -264,12 +264,14 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
     setSourceState({
       thumbnails,
       thumbnailAt,
+      requestThumbnail,
       togglePictureInPicture,
       pictureInPictureMode,
       burnedInSubtitles,
     })
   }, [
-    setSourceState, thumbnails, thumbnailAt, togglePictureInPicture, pictureInPictureMode, burnedInSubtitles,
+    setSourceState, thumbnails, thumbnailAt, requestThumbnail, togglePictureInPicture, pictureInPictureMode,
+    burnedInSubtitles,
   ])
 
   // A delegated track list writes the same store fields the engine writes, so the menus never learn