@banou/media-player 0.6.2 → 0.8.0

package/src/{components → lib/react/components}/volume-slider.tsx

@@ -1,9 +1,11 @@
-import { useRef, useState, useEffect, useMemo } from 'react'
+/// <reference types="@emotion/react/types/css-prop" />
+import { useRef, useEffect, useMemo } from 'react'
 import { css } from '@emotion/react'
 
 import { TooltipDisplay } from './tooltip-display'
-import { MediaMachineContext } from '../state-machines'
-import { logToLinearVolume } from '../utils/volume-utils'
+import { usePlayer } from '../player'
+import { useDragValue } from '../hooks/use-drag-value'
+import { logToLinearVolume } from '../../utils/volume-utils'
 
 const style = css`
   display: flex;
@@ -11,6 +13,10 @@ const style = css`
 
   padding: 16px 4px;
   margin: 0 2px;
+  /* a finger needs a 44px band to press, so the padding grows while the track stays 3px */
+  @media (pointer: coarse) {
+    padding: 22px 4px;
+  }
 
   cursor: pointer;
 
@@ -22,6 +28,14 @@ const style = css`
 
     width: 80px;
     height: 3px;
+    /* the control bar has under 360px to fit every button once the slider is always open, so the
+       track lends some of its length back on a phone and takes it again on anything wider */
+    @media (pointer: coarse) {
+      width: 64px;
+    }
+    @media (pointer: coarse) and (min-width: 768px) {
+      width: 80px;
+    }
   }
 
   .volume-handle {
@@ -31,7 +45,7 @@ const style = css`
     background: #ffffff;
     border-radius: 50%;
     transform: translateX(-50%);
-    pointer-events: none; 
+    pointer-events: none;
 
     width: 10px;
     height: 10px;
@@ -43,60 +57,31 @@ type VolumeSliderType = {
   onChange: (v: number) => void
 }
 
-const VolumeSlider = ({ value, onChange }: VolumeSliderType) => {
-  const volume = MediaMachineContext.useSelector((state) => state.context.media.volume)
-  const muted = MediaMachineContext.useSelector((state) => state.context.media.muted)
+export const VolumeSlider = ({ value, onChange }: VolumeSliderType) => {
+  const volume = usePlayer((state) => state.volume)
+  const muted = usePlayer((state) => state.muted)
 
   const sliderRef = useRef<HTMLDivElement>(null)
-  const [isDragging, setIsDragging] = useState(false)
-
-  const getNewVolumeFromEvent = (clientX: number): number => {
-    if (!sliderRef.current) return value
-    const rect = sliderRef.current.getBoundingClientRect()
-    const xPos = clientX - rect.left
-    const clamped = Math.max(0, Math.min(xPos, rect.width))
-    return clamped / rect.width
-  }
+  const trackRef = useRef<HTMLDivElement>(null)
 
-  const handlePointerDown = (e: React.MouseEvent<HTMLDivElement>) => {
-    setIsDragging(true)
-    const newVolume = getNewVolumeFromEvent(e.clientX)
-    onChange(newVolume)
-  }
-
-  const handlePointerMove = (e: MouseEvent) => {
-    if (!isDragging) return
-    const newVolume = getNewVolumeFromEvent(e.clientX)
-    onChange(newVolume)
-  }
-
-  const handlePointerUp = () => {
-    setIsDragging(false)
-  }
+  // the padded row owns the gesture, but the fraction is measured across the track the handle draws in
+  const { handlers } = useDragValue({
+    ref: trackRef,
+    onChange
+  })
 
   const handleWheel = (e: WheelEvent) => {
     e.preventDefault()
     const step = 0.05
     let newVol = value
     if (e.deltaY < 0) {
-      // scroll up
       newVol = Math.min(1, newVol + step)
     } else {
-      // scroll down
       newVol = Math.max(0, newVol - step)
     }
     onChange(newVol)
   }
 
-  useEffect(() => {
-    window.addEventListener('mousemove', handlePointerMove)
-    window.addEventListener('mouseup', handlePointerUp)
-    return () => {
-      window.removeEventListener('mousemove', handlePointerMove)
-      window.removeEventListener('mouseup', handlePointerUp)
-    }
-  }, [isDragging])
-
   useEffect(() => {
     const slider = sliderRef.current
     if (slider) {
@@ -115,7 +100,7 @@ const VolumeSlider = ({ value, onChange }: VolumeSliderType) => {
 
   const displayVolumePercent = useMemo(
     () => Math.round(muted ? 0 : logToLinearVolume(volume) * 100),
-    [volume]
+    [volume, muted]
   )
 
   return (
@@ -125,12 +110,13 @@ const VolumeSlider = ({ value, onChange }: VolumeSliderType) => {
         <div
           ref={sliderRef}
           css={style}
-          onMouseDown={handlePointerDown}
+          {...handlers}
         >
           <div
+            ref={trackRef}
             style={{
-              background: `linear-gradient(to right, 
-                ${fillColor} 0% ${fillPercent}%, 
+              background: `linear-gradient(to right,
+                ${fillColor} 0% ${fillPercent}%,
                 ${emptyColor} ${fillPercent}% 100%
               )`
             }}

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

@@ -0,0 +1,73 @@
+import type { PointerEvent as ReactPointerEvent, RefObject } from 'react'
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+export type UseDragValueOptions = {
+  /** The element the fraction is measured across. */
+  ref: RefObject<HTMLElement | null>
+  /** Called with a 0..1 fraction on press and on every move, and once more on release. */
+  onChange: (fraction: number) => void
+  orientation?: 'horizontal' | 'vertical'
+  disabled?: boolean
+}
+
+/** Press-and-drag over an element, reported as a 0..1 fraction. */
+export const useDragValue = ({ ref, onChange, orientation = 'horizontal', disabled = false }: UseDragValueOptions) => {
+  const [dragging, setDragging] = useState(false)
+  const onChangeRef = useRef(onChange)
+  onChangeRef.current = onChange
+  const activePointer = useRef<number | null>(null)
+
+  const fractionFor = useCallback((clientX: number, clientY: number) => {
+    const element = ref.current
+    if (!element) return 0
+    const { left, right, top, bottom } = element.getBoundingClientRect()
+    const fraction = orientation === 'horizontal'
+      ? (clientX - left) / (right - left)
+      // a vertical track fills upwards, so the top of the box is 1
+      : (bottom - clientY) / (bottom - top)
+    return Math.min(Math.max(fraction, 0), 1)
+  }, [ref, orientation])
+
+  const onPointerDown = useCallback((event: ReactPointerEvent<HTMLElement>) => {
+    if (disabled || event.button > 0) return
+    // Do not add preventDefault or stopPropagation here. The first kills the compatibility mouse
+    // 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)
+    setDragging(true)
+    onChangeRef.current(fractionFor(event.clientX, event.clientY))
+  }, [disabled, fractionFor])
+
+  const onPointerMove = useCallback((event: ReactPointerEvent<HTMLElement>) => {
+    if (activePointer.current !== event.pointerId) return
+    onChangeRef.current(fractionFor(event.clientX, event.clientY))
+  }, [fractionFor])
+
+  const endDrag = useCallback((event: ReactPointerEvent<HTMLElement>) => {
+    if (activePointer.current !== event.pointerId) return
+    activePointer.current = null
+    event.currentTarget.releasePointerCapture?.(event.pointerId)
+    setDragging(false)
+  }, [])
+
+  useEffect(() => {
+    if (!disabled) return
+    activePointer.current = null
+    setDragging(false)
+  }, [disabled])
+
+  return {
+    dragging,
+    /** Spread onto the element that owns the gesture. */
+    handlers: {
+      onPointerDown,
+      onPointerMove,
+      onPointerUp: endDrag,
+      onPointerCancel: endDrag,
+      // without this the browser scrolls the page instead of moving the slider
+      style: { touchAction: 'none' as const },
+    },
+  }
+}

package/src/lib/react/hooks/use-picture-in-picture.ts

@@ -0,0 +1,36 @@
+import type { PictureInPictureController } from '../../engine'
+
+import { useCallback, useEffect, useRef } from 'react'
+
+import { createPictureInPicture } from '../../engine'
+import { usePlayer } from '../player'
+
+/** Picture in picture with the subtitles composited in. */
+export const usePictureInPicture = (
+  video: HTMLVideoElement | null,
+  canvas: HTMLCanvasElement | null,
+) => {
+  const player = usePlayer()
+  const controller = useRef<PictureInPictureController | null>(null)
+
+  useEffect(() => {
+    if (!video || !canvas) return
+    const instance = createPictureInPicture({
+      video,
+      canvas,
+      // the store's action handles Safari and exits fullscreen first
+      fallback: () => player.togglePictureInPicture(),
+    })
+    controller.current = instance
+    return () => {
+      instance.destroy()
+      controller.current = null
+    }
+  }, [video, canvas, player])
+
+  return useCallback(() => {
+    void controller.current?.toggle().catch((error) => {
+      console.warn('picture in picture was refused', error)
+    })
+  }, [])
+}

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

@@ -0,0 +1,146 @@
+import type { PlaybackController } from '../../engine'
+import type { MediaPlayerLocalOptions } from '../video-player'
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { startPlayback } from '../../engine'
+import { usePlayer } from '../player'
+import { toNamedTracks } from '../../utils/track-label'
+
+/**
+ * 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.
+ */
+export const usePlayback = (
+  video: HTMLVideoElement | null,
+  canvas: HTMLCanvasElement | null,
+  /** null when the media is remote: there are no bytes, so there is no pipeline to run. */
+  options: MediaPlayerLocalOptions | null,
+) => {
+  const player = usePlayer()
+  // The four asset urls are required on the local arm, so a default only ever applies when options is
+  // null, and the effect below returns before touching them in that case.
+  const {
+    read, size, publicPath = '', libavWorkerUrl = '', jassubWorkerUrl = '', jassubWasmUrl = '',
+    jassubLegacyWasmUrl, defaultFontUrl, bufferSize, autoplay = false,
+  } = options ?? ({} as Partial<MediaPlayerLocalOptions>)
+
+  // The track the viewer picked, which is what a restart is keyed on. Distinct from the store's
+  // `selectedAudioStream`, which is whatever is playing right now.
+  const [audioStreamIndex, setAudioStreamIndex] = useState<number | undefined>(undefined)
+
+  const controllerRef = useRef<PlaybackController | null>(null)
+  const resumeTimeRef = 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)
+
+  const readRef = useRef(read)
+  readRef.current = read
+  const onSeekRef = useRef(options?.onSeek)
+  onSeekRef.current = options?.onSeek
+  const onPlaybackErrorRef = useRef(options?.onPlaybackError)
+  onPlaybackErrorRef.current = options?.onPlaybackError
+
+  // The store's ids are opaque, but everything this hook writes into it came from libav, so every id
+  // that comes back is one of its own stream indices.
+  const selectSubtitleTrack = useCallback((id: string | number | undefined) => {
+    const streamIndex = typeof id === 'number' ? id : undefined
+    subtitleChoiceMade.current = true
+    player.setSourceState({ selectedSubtitleTrack: streamIndex })
+    controllerRef.current?.selectSubtitleStream(streamIndex)
+  }, [player])
+
+  const selectAudioTrack = useCallback((id: string | number) => {
+    if (typeof id !== 'number') return
+    player.setSourceState({ selectedAudioTrack: id })
+    setAudioStreamIndex(id)
+  }, [player])
+
+  // Subscribed rather than read off the store, because it is a no-op until the media element
+  // attaches. These deps are otherwise all stable, so a mount-time publish would be the only one and
+  // both actions would stay dead defaults.
+  const setSourceState = usePlayer((state) => state.setSourceState)
+
+  useEffect(() => {
+    setSourceState({ selectSubtitleTrack, selectAudioTrack })
+  }, [setSourceState, selectSubtitleTrack, selectAudioTrack])
+
+  useEffect(() => {
+    if (!video || !canvas || !size || !read) return
+    let cancelled = false
+    player.setSourceState({ playbackError: null, ready: false })
+    const fail = (error: unknown) => {
+      if (cancelled) return
+      console.error('playback failed', error)
+      player.setSourceState({ playbackError: error })
+      onPlaybackErrorRef.current?.(error)
+    }
+    void (async () => {
+      try {
+        const controller = await startPlayback({
+          videoElement: video,
+          canvasElement: canvas,
+          read: (offset, length) => readRef.current!(offset, length),
+          length: size,
+          publicPath,
+          libavWorkerUrl,
+          jassubWorkerUrl,
+          jassubWasmUrl,
+          jassubLegacyWasmUrl,
+          defaultFontUrl,
+          bufferSize,
+          audioStreamIndex,
+          onReady: () => {
+            if (cancelled) return
+            player.setSourceState({ ready: true })
+            if (resumeTimeRef.current > 0) {
+              video.currentTime = resumeTimeRef.current
+              resumeTimeRef.current = 0
+            }
+            if (autoplay) video.play().catch(() => {})
+          },
+          onError: fail,
+          onRecovered: () => { if (!cancelled) player.setSourceState({ playbackError: null }) },
+          onSeek: (fraction) => onSeekRef.current?.(fraction),
+          onSubtitleStreams: (streams) => {
+            if (cancelled) return
+            player.setSourceState({
+              subtitleTracks: toNamedTracks(streams),
+              ...subtitleChoiceMade.current ? {} : { selectedSubtitleTrack: streams[0]?.streamIndex },
+            })
+          },
+          onAudioStreams: (streams, selected) => {
+            if (cancelled) return
+            player.setSourceState({ audioTracks: toNamedTracks(streams), selectedAudioTrack: selected })
+          },
+        })
+        if (cancelled) {
+          controller.destroy()
+          return
+        }
+        controllerRef.current = controller
+        player.setSourceState({ indexes: controller.indexes })
+        // a track chosen before this pipeline existed has to be re-applied to the new renderer
+        const chosen = player.selectedSubtitleTrack
+        if (typeof chosen === 'number') controller.selectSubtitleStream(chosen)
+      } catch (error) {
+        fail(error)
+      }
+    })()
+    return () => {
+      cancelled = true
+      resumeTimeRef.current = video.currentTime
+      controllerRef.current?.destroy()
+      controllerRef.current = null
+      player.setSourceState({ ready: false })
+    }
+    // `read` is deliberately absent: the effect only ever calls `readRef.current`, so listing it here
+    // would tear the whole pipeline down and rebuild it whenever the caller's reader changed
+    // identity. A streaming consumer passes a fresh closure on every state update, which is several
+    // 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,
+  ])
+}

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

@@ -0,0 +1,78 @@
+import type { ThumbnailGenerator, ThumbnailImage } from '../../engine'
+import type { DownloadedRange } from '../source-feature'
+
+import { useEffect, useMemo, useRef, useState } from 'react'
+
+import { createThumbnailGenerator } from '../../engine'
+
+// backs off because each failed init costs a wasm worker
+const RETRY_DELAY = 5_000
+const MAX_RETRY_DELAY = 60_000
+
+export type UseSeekThumbnailsOptions = {
+  /** Optional alongside `length`/`read`: with no bytes there is nothing to generate from. */
+  publicPath: string | undefined
+  workerUrl: string | undefined
+  length: number | undefined
+  read: ((offset: number, size: number) => Promise<ArrayBuffer>) | undefined
+  /** When omitted the whole file is treated as readable, which is the case for a local file. */
+  downloadedRanges?: DownloadedRange[]
+}
+
+export const useSeekThumbnails = ({
+  publicPath, workerUrl, length, read, downloadedRanges,
+}: UseSeekThumbnailsOptions): ThumbnailImage[] => {
+  const [thumbnails, setThumbnails] = useState<ThumbnailImage[]>([])
+  const generatorRef = useRef<ThumbnailGenerator | null>(null)
+  const readRef = useRef(read)
+  readRef.current = read
+
+  const ranges = useMemo(
+    () => downloadedRanges?.map(({ startByteOffset, endByteOffset }) => [startByteOffset, endByteOffset] as [number, number]),
+    // a streaming consumer changes the array identity every tick, so compare contents
+    [downloadedRanges?.map(({ startByteOffset, endByteOffset }) => `${startByteOffset}-${endByteOffset}`).join(',')],
+  )
+  const rangesRef = useRef(ranges)
+  rangesRef.current = ranges
+
+  useEffect(() => {
+    if (!length || !read || !publicPath || !workerUrl) return
+    let cancelled = false
+    let generator: ThumbnailGenerator | null = null
+    let retry: ReturnType<typeof setTimeout> | undefined
+    let delay = RETRY_DELAY
+    const boot = () => {
+      createThumbnailGenerator({
+        publicPath,
+        workerUrl,
+        length,
+        read: (offset, size) => readRef.current!(offset, size),
+        onThumbnails: (next) => { if (!cancelled) setThumbnails(next) },
+      }).then((created) => {
+        if (cancelled) {
+          created.destroy()
+          return
+        }
+        generator = created
+        generatorRef.current = created
+        created.update(rangesRef.current)
+      }, () => {
+        if (cancelled) return
+        retry = setTimeout(boot, delay)
+        delay = Math.min(delay * 2, MAX_RETRY_DELAY)
+      })
+    }
+    boot()
+    return () => {
+      cancelled = true
+      clearTimeout(retry)
+      generatorRef.current = null
+      generator?.destroy()
+      setThumbnails([])
+    }
+  }, [length, publicPath, workerUrl])
+
+  useEffect(() => { generatorRef.current?.update(ranges) }, [ranges])
+
+  return thumbnails
+}

package/src/lib/react/media.ts

@@ -0,0 +1,124 @@
+import type { ThumbnailImage } from '../engine'
+
+/**
+ * A media object the player drives but does not own.
+ *
+ * video.js v10 never asks for an `HTMLVideoElement`. Its `PlayerTarget` is `{ media, container }` and
+ * every feature gates on property presence alone, with no `instanceof` anywhere, so a plain object
+ * carrying these fields lights the whole chrome up. Upstream relies on the same thing: `VimeoMedia`
+ * implements `Partial<Video>` over a cross-origin iframe.
+ *
+ * Declared here rather than imported from `@videojs/media` on purpose. That package is transitive
+ * under `@videojs/core`, its `Media` type moved out of `@videojs/core/dom`'s exports between betas,
+ * and its shape changed across them, so importing it would pin every consumer to one beta. The
+ * assertion at the bottom of this file keeps this type honest against the real one at build time,
+ * where `@videojs/media` does exist.
+ *
+ * OMITTING a property is how you say "not supported". The feature owning it returns out of its
+ * `attach` and stays at its defaults, which is why this is mostly optional.
+ */
+export type TimeRangesLike = {
+  readonly length: number
+  start: (index: number) => number
+  end: (index: number) => number
+}
+
+export type PlayerMedia = EventTarget & {
+  /* MediaPlaybackCapability: the only genuinely required part */
+  play: () => Promise<void>
+  pause: () => void
+  paused: boolean
+
+  /**
+   * Seek and source capability. Both are needed or the store goes quiet: `playbackFeature` refuses
+   * to attach without them, and `seek` returns without doing anything. A remote media that loads
+   * nothing still has to answer `src`/`currentSrc`/`readyState`/`load`, and `readyState` has to
+   * reach HAVE_FUTURE_DATA (3) or `waiting` stays true forever and the spinner never clears.
+   */
+  currentTime: number
+  duration: number
+  seeking: boolean
+  src?: string
+  currentSrc?: string
+  readyState: number
+  load?: () => void
+
+  volume?: number
+  muted?: boolean
+  playbackRate?: number
+  ended?: boolean
+  /**
+   * Structural, not the DOM `TimeRanges`, because a remote source transports these as plain pairs and
+   * has nothing to hand back that passes an `instanceof`. Note that video.js decides "no buffer
+   * capability" by comparing against its own empty sentinel BY IDENTITY, so a hand-rolled empty
+   * `{ length: 0 }` reads as a genuinely empty buffer rather than as an absent capability. Omit the
+   * field entirely to mean absent.
+   */
+  buffered?: TimeRangesLike
+  seekable?: TimeRangesLike
+  /** Structurally what video.js reads off a failed element, so a remote source can report one too. */
+  error?: { readonly code: number, readonly message: string } | null
+
+  videoWidth?: number
+  videoHeight?: number
+
+  requestPictureInPicture?: () => Promise<unknown>
+  requestFullscreen?: () => Promise<unknown>
+}
+
+/**
+ * Where the seekbar's hover previews come from.
+ *
+ * With bytes in hand the player generates them itself with a second libav worker. A media it does not
+ * own has no bytes, but a commercial source usually publishes its own storyboard, so it can answer
+ * for a time directly. Narrowed on `at`, the field that carries the difference, rather than on a tag
+ * repeating what the shape already says.
+ */
+export type ExternalThumbnails = {
+  at: (time: number) => ThumbnailImage | undefined
+  /** Shown all at once on the seekbar if the source can enumerate them; previews work without it. */
+  all?: ThumbnailImage[]
+}
+
+export const isExternalThumbnails = (value: unknown): value is ExternalThumbnails =>
+  !!value && typeof value === 'object' && 'at' in value
+
+/**
+ * One choice among several the player presents but does not fulfil: the source owns the switch.
+ *
+ * This is what a subtitle or audio track becomes when the media is remote. The player draws the menu
+ * and reports the pick; whoever owns the document does the work and renders the result.
+ */
+export type DelegatedSelection = {
+  options: readonly { id: string, label: string, disabled?: boolean }[]
+  selectedId: string | null
+  select: (id: string | null) => void | Promise<void>
+  /** Label for the entry that turns the feature off, when the source offers one. */
+  offLabel?: string
+}
+
+export type DelegatedTracks = {
+  selection: DelegatedSelection
+}
+
+export const isDelegatedTracks = (value: unknown): value is DelegatedTracks =>
+  !!value && typeof value === 'object' && 'selection' in value
+
+/**
+ * Keeps `PlayerMedia` honest.
+ *
+ * `@videojs/media` is present in this repo but deliberately not in the published type surface, so the
+ * check lives here as a compile-time assertion instead of an import consumers inherit. If a beta bump
+ * changes the real interface in a way that matters, this stops compiling.
+ */
+// Deliberately NOT exported: an exported alias is emitted into the .d.ts, which would put
+// `import('@videojs/media')` back into the published surface and undo the point of declaring this
+// type. Unexported, it is checked here and emitted nowhere.
+type AssertAssignable<T extends U, U> = T
+type PlayerMediaMatchesVideoJs = AssertAssignable<
+  PlayerMedia,
+  Partial<import('@videojs/media').Video>
+>
+// One use, so the alias is not dead code. `never` carries nothing into the output.
+const _assertPlayerMedia: PlayerMediaMatchesVideoJs | undefined = undefined
+void _assertPlayerMedia

package/src/lib/react/player.ts

@@ -0,0 +1,20 @@
+import { videoFeatures } from '@videojs/core/dom'
+import { createPlayer } from '@videojs/react'
+
+import { sourceFeature } from './source-feature'
+
+// The preset plus our own source state, so the chrome reads one store rather than a store and a
+// context. createPlayer's generic overload infers the state from the whole tuple, so the extra
+// feature's fields are as typed as the built-in ones.
+export const Player = createPlayer({
+  features: [...videoFeatures, sourceFeature],
+  displayName: 'MediaPlayer',
+})
+
+/**
+ * Typed player state, to be used instead of the `usePlayer` from `@videojs/react`, whose fields come
+ * back as `unknown`. With no selector it returns the store without subscribing; with one it subscribes.
+ */
+export const usePlayer: typeof Player.usePlayer = Player.usePlayer
+
+export type PlayerStore = ReturnType<typeof Player.usePlayer>