@banou/media-player 0.7.0 → 0.8.0

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

@@ -10,10 +10,10 @@ import { fonts } from '../../utils/fonts'
 
 const style = css`
   position: relative;
-  height: .4rem;
+  height: calc(.4 * var(--mp-unit));
 
-  --thumbnail-width: 25rem;
-  --thumbnail-half: 12.5rem;
+  --thumbnail-width: calc(25 * var(--mp-unit));
+  --thumbnail-half: calc(12.5 * var(--mp-unit));
 
   transition: transform .2s ease-in-out;
 
@@ -34,7 +34,7 @@ const style = css`
     }
     .loaded {
       transform: scaleY(1.5);
-      top: -.1rem;
+      top: calc(-.1 * var(--mp-unit));
     }
     .play-container {
       transform: scaleY(1.5);
@@ -56,10 +56,10 @@ const style = css`
     ${fonts.bMedium.bold}
 
     position: absolute;
-    top: -2.5rem;
-    width: 5rem;
+    top: calc(-2.5 * var(--mp-unit));
+    width: calc(5 * var(--mp-unit));
 
-    margin-left: -2.5rem;
+    margin-left: calc(-2.5 * var(--mp-unit));
     pointer-events: none;
   }
 
@@ -67,12 +67,12 @@ const style = css`
     transform-origin: 0 0;
     position: absolute;
     bottom: 0;
-    height: .4rem;
+    height: calc(.4 * var(--mp-unit));
     width: 100%;
     .loaded-part {
       transform-origin: 0 0;
       bottom: 0;
-      height: .4rem;
+      height: calc(.4 * var(--mp-unit));
       width: 100%;
       position: absolute;
       background-color: hsla(0, 100%, 100%, .4);
@@ -83,7 +83,7 @@ const style = css`
     position: absolute;
     bottom: 0;
     width: 100%;
-    height: .4rem;
+    height: calc(.4 * var(--mp-unit));
   }
 
   .play {
@@ -91,14 +91,14 @@ const style = css`
     background-color: #f03;
     position: absolute;
     bottom: 0;
-    height: .4rem;
+    height: calc(.4 * var(--mp-unit));
     width: 100%;
   }
 
   .padding {
     position: absolute;
     bottom: -7.5px;
-    height: 2rem;
+    height: calc(2 * var(--mp-unit));
     width: 100%;
   }
 
@@ -107,7 +107,7 @@ const style = css`
     justify-content: center;
 
     position: absolute;
-    top: calc(-3.4375rem - var(--thumbnail-width) * 9/16);
+    top: calc(calc(-3.4375 * var(--mp-unit)) - var(--thumbnail-width) * 9/16);
     height: calc(var(--thumbnail-width) * 9/16);
     width: var(--thumbnail-width);
 
@@ -115,8 +115,8 @@ const style = css`
     pointer-events: none;
 
     img {
-      border-radius: .4rem;
-      box-shadow: 0 0 1rem rgba(0, 0, 0, .5);
+      border-radius: calc(.4 * var(--mp-unit));
+      box-shadow: 0 0 calc(1 * var(--mp-unit)) rgba(0, 0, 0, .5);
 
       width: 100%;
       height: 100%;
@@ -124,9 +124,9 @@ const style = css`
     }
   }
 
-  /* a thumb is far wider than a cursor, so the hit strip grows to 44px and the track to .6rem */
+  /* a thumb is far wider than a cursor, so the hit strip grows to 44px and the track thickens */
   @media (pointer: coarse) {
-    height: .6rem;
+    height: calc(.6 * var(--mp-unit));
 
     /* press feedback, coarse only: a finger has no hover, so without this the bar gives no sign
        it is being dragged */
@@ -137,18 +137,18 @@ const style = css`
     }
 
     .loaded {
-      height: .6rem;
+      height: calc(.6 * var(--mp-unit));
       .loaded-part {
-        height: .6rem;
+        height: calc(.6 * var(--mp-unit));
       }
     }
 
     .play-container {
-      height: .6rem;
+      height: calc(.6 * var(--mp-unit));
     }
 
     .play {
-      height: .6rem;
+      height: calc(.6 * var(--mp-unit));
     }
 
     /* grows upward into the video: centred, it would hang over the control row and win hit
@@ -162,8 +162,8 @@ const style = css`
   /* the clamp only holds the preview inside the bar while the bar is the wider of the two, so
      below that the preview is narrowed instead */
   @media (max-width: 480px) {
-    --thumbnail-width: 18rem;
-    --thumbnail-half: 9rem;
+    --thumbnail-width: calc(18 * var(--mp-unit));
+    --thumbnail-half: calc(9 * var(--mp-unit));
   }
 `
 
@@ -175,6 +175,7 @@ export const ProgressBar = () => {
   const downloadedRanges = usePlayer((state) => state.downloadedRanges)
   const indexes = usePlayer((state) => state.indexes)
   const thumbnails = usePlayer((state) => state.thumbnails)
+  const thumbnailAt = usePlayer((state) => state.thumbnailAt)
 
   const progressBarRef = useRef<HTMLDivElement>(null)
 
@@ -271,14 +272,16 @@ export const ProgressBar = () => {
 
   // an empty url is a gap sentinel, so it renders nothing
   const thumbnail = useMemo(() => {
-    if (!thumbnails.length || !progressBarHoverTime) return undefined
+    if (!progressBarHoverTime) return undefined
+    if (thumbnailAt) return thumbnailAt(progressBarHoverTime)
+    if (!thumbnails.length) return undefined
     return (
       thumbnails
         .find(({ startTime, endTime }) =>
           startTime <= progressBarHoverTime && progressBarHoverTime < endTime
         )
     )
-  }, [thumbnails.length, progressBarHoverTime])
+  }, [thumbnails, thumbnailAt, progressBarHoverTime])
 
   return (
     <div
@@ -294,7 +297,7 @@ export const ProgressBar = () => {
           ? (
             <div
               className="cursor-time"
-              style={{ left: `clamp(1.8rem, ${timePercentage(progressBarHoverTime)}%, calc(100% - 1.8rem))` }}
+              style={{ left: `clamp(calc(1.8 * var(--mp-unit)), ${timePercentage(progressBarHoverTime)}%, calc(100% - calc(1.8 * var(--mp-unit))))` }}
             >
               {cusorTimeString}
             </div>

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

@@ -1,12 +1,13 @@
 /// <reference types="@emotion/react/types/css-prop" />
-import { useEffect, useMemo, useRef, useState } from 'react'
+import type { TrackChoice } from '../source-feature'
+
+import { useEffect, useRef, useState } from 'react'
 import { css } from '@emotion/react'
 import { ChevronLeft, ChevronRight, Settings } from 'react-feather'
 
 import { usePlayer } from '../player'
 import { TooltipDisplay } from './tooltip-display'
 import { fonts } from '../../utils/fonts'
-import { labelTracks, type LabelledTrack } from '../../utils/track-label'
 import PlaybackSlider from './playback-slider'
 
 const style = css`
@@ -167,18 +168,13 @@ enum PopoverContent {
   Audio
 }
 
-type TrackRow = { streamIndex: number, label: string }
-
-const toTrackRows = <T extends LabelledTrack>(streams: T[]): TrackRow[] =>
-  labelTracks(streams).map(({ track, label }) => ({ streamIndex: track.streamIndex, label }))
-
 /** One track picker, shared by the subtitle and audio menus. */
 const TrackMenu = (
   { title, tracks, selected, onSelect, onBack, allowDisable }: {
     title: string
-    tracks: TrackRow[]
-    selected: number | undefined
-    onSelect: (streamIndex: number | undefined) => void
+    tracks: TrackChoice[]
+    selected: string | number | undefined
+    onSelect: (id: string | number | undefined) => void
     onBack: () => void
     allowDisable?: boolean
   }
@@ -199,14 +195,14 @@ const TrackMenu = (
         : null
     }
     {
-      tracks.map(({ streamIndex, label }) => (
+      tracks.map(({ id, label }) => (
         <div
-          key={streamIndex}
-          onClick={() => onSelect(streamIndex)}
+          key={id}
+          onClick={() => onSelect(id)}
           className="description"
         >
           <span>{label}</span>
-          <span>{selected === streamIndex ? '✓' : ''}</span>
+          <span>{selected === id ? '✓' : ''}</span>
         </div>
       ))
     }
@@ -216,12 +212,12 @@ const TrackMenu = (
 export const SettingsAction = () => {
   const player = usePlayer()
   const playbackRate = usePlayer((state) => state.playbackRate)
-  const subtitleStreams = usePlayer((state) => state.subtitleStreams)
-  const selectedSubtitleStream = usePlayer((state) => state.selectedSubtitleStream)
-  const selectSubtitleStream = usePlayer((state) => state.selectSubtitleStream)
-  const audioStreams = usePlayer((state) => state.audioStreams)
-  const selectedAudioStream = usePlayer((state) => state.selectedAudioStream)
-  const selectAudioStream = usePlayer((state) => state.selectAudioStream)
+  const subtitleTracks = usePlayer((state) => state.subtitleTracks)
+  const selectedSubtitleTrack = usePlayer((state) => state.selectedSubtitleTrack)
+  const selectSubtitleTrack = usePlayer((state) => state.selectSubtitleTrack)
+  const audioTracks = usePlayer((state) => state.audioTracks)
+  const selectedAudioTrack = usePlayer((state) => state.selectedAudioTrack)
+  const selectAudioTrack = usePlayer((state) => state.selectAudioTrack)
 
   const [isOpenPopover, setIsOpenPopover] = useState(false)
   const [popoverContent, setPopoverContent] = useState(PopoverContent.Default)
@@ -252,17 +248,14 @@ export const SettingsAction = () => {
     return () => document.removeEventListener('pointerdown', handleClickOutside)
   }, [isOpenPopover])
 
-  const subtitleTracks = useMemo(() => toTrackRows(subtitleStreams), [subtitleStreams])
-  const audioTracks = useMemo(() => toTrackRows(audioStreams), [audioStreams])
-
-  const chooseSubtitle = (streamIndex: number | undefined) => {
-    selectSubtitleStream(streamIndex)
+  const chooseSubtitle = (id: string | number | undefined) => {
+    selectSubtitleTrack(id)
     togglePopover()
   }
 
-  const chooseAudio = (streamIndex: number | undefined) => {
+  const chooseAudio = (id: string | number | undefined) => {
     // the audio menu never offers "Disable"
-    if (streamIndex !== undefined) selectAudioStream(streamIndex)
+    if (id !== undefined) selectAudioTrack(id)
     togglePopover()
   }
 
@@ -366,7 +359,7 @@ export const SettingsAction = () => {
           <TrackMenu
             title='Subtitles'
             tracks={subtitleTracks}
-            selected={selectedSubtitleStream}
+            selected={selectedSubtitleTrack}
             onSelect={chooseSubtitle}
             onBack={changePopoverContent(PopoverContent.Default)}
             allowDisable
@@ -378,7 +371,7 @@ export const SettingsAction = () => {
           <TrackMenu
             title='Audio'
             tracks={audioTracks}
-            selected={selectedAudioStream}
+            selected={selectedAudioTrack}
             onSelect={chooseAudio}
             onBack={changePopoverContent(PopoverContent.Default)}
           />

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

@@ -43,7 +43,7 @@ const style = css`
   }
 
   &:hover .volume-slider-container {
-    width: 9rem;
+    width: calc(9 * var(--mp-unit));
 
     transition: margin .2s cubic-bezier(0,0,0.2,1), width .2s cubic-bezier(0,0,0.2,1);
     -webkit-transition: margin .2s cubic-bezier(0,0,0.2,1), width .2s cubic-bezier(0,0,0.2,1);

package/src/lib/react/components/tooltip-display.tsx

@@ -15,7 +15,7 @@ const style = (size: buttonSize) => css`
   display: flex;
   justify-content: flex-end;
 
-  border-radius: 0.4rem;
+  border-radius: calc(0.4 * var(--mp-unit));
   user-select: none;
 
   z-index: 3;
@@ -25,13 +25,13 @@ const style = (size: buttonSize) => css`
   }
 
   ${size === buttonSize.sm && css`
-    padding: 0.4rem!important;
+    padding: calc(0.4 * var(--mp-unit))!important;
   `}
   ${size === buttonSize.md && css`
-    padding: 0.6rem!important;
+    padding: calc(0.6 * var(--mp-unit))!important;
   `}
   ${size === buttonSize.lg && css`
-    padding: 1.2rem!important;
+    padding: calc(1.2 * var(--mp-unit))!important;
   `}
 `
 

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

@@ -1,10 +1,11 @@
 import type { PlaybackController } from '../../engine'
-import type { MediaPlayerOptions } from '../video-player'
+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
@@ -13,13 +14,16 @@ import { usePlayer } from '../player'
 export const usePlayback = (
   video: HTMLVideoElement | null,
   canvas: HTMLCanvasElement | null,
-  options: MediaPlayerOptions,
+  /** 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
+    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.
@@ -33,20 +37,24 @@ export const usePlayback = (
 
   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
+  const onSeekRef = useRef(options?.onSeek)
+  onSeekRef.current = options?.onSeek
+  const onPlaybackErrorRef = useRef(options?.onPlaybackError)
+  onPlaybackErrorRef.current = options?.onPlaybackError
 
-  const selectSubtitleStream = useCallback((streamIndex: number | undefined) => {
+  // 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({ selectedSubtitleStream: streamIndex })
+    player.setSourceState({ selectedSubtitleTrack: streamIndex })
     controllerRef.current?.selectSubtitleStream(streamIndex)
   }, [player])
 
-  const selectAudioStream = useCallback((streamIndex: number) => {
-    player.setSourceState({ selectedAudioStream: streamIndex })
-    setAudioStreamIndex(streamIndex)
+  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
@@ -55,8 +63,8 @@ export const usePlayback = (
   const setSourceState = usePlayer((state) => state.setSourceState)
 
   useEffect(() => {
-    setSourceState({ selectSubtitleStream, selectAudioStream })
-  }, [setSourceState, selectSubtitleStream, selectAudioStream])
+    setSourceState({ selectSubtitleTrack, selectAudioTrack })
+  }, [setSourceState, selectSubtitleTrack, selectAudioTrack])
 
   useEffect(() => {
     if (!video || !canvas || !size || !read) return
@@ -98,13 +106,13 @@ export const usePlayback = (
           onSubtitleStreams: (streams) => {
             if (cancelled) return
             player.setSourceState({
-              subtitleStreams: streams,
-              ...subtitleChoiceMade.current ? {} : { selectedSubtitleStream: streams[0]?.streamIndex },
+              subtitleTracks: toNamedTracks(streams),
+              ...subtitleChoiceMade.current ? {} : { selectedSubtitleTrack: streams[0]?.streamIndex },
             })
           },
           onAudioStreams: (streams, selected) => {
             if (cancelled) return
-            player.setSourceState({ audioStreams: streams, selectedAudioStream: selected })
+            player.setSourceState({ audioTracks: toNamedTracks(streams), selectedAudioTrack: selected })
           },
         })
         if (cancelled) {
@@ -114,8 +122,8 @@ export const usePlayback = (
         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.selectedSubtitleStream
-        if (chosen !== undefined) controller.selectSubtitleStream(chosen)
+        const chosen = player.selectedSubtitleTrack
+        if (typeof chosen === 'number') controller.selectSubtitleStream(chosen)
       } catch (error) {
         fail(error)
       }
@@ -127,8 +135,12 @@ export const usePlayback = (
       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, read, publicPath, libavWorkerUrl, jassubWorkerUrl, jassubWasmUrl,
+    player, video, canvas, size, publicPath, libavWorkerUrl, jassubWorkerUrl, jassubWasmUrl,
     jassubLegacyWasmUrl, defaultFontUrl, bufferSize, audioStreamIndex, autoplay,
   ])
 }

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

@@ -10,8 +10,9 @@ const RETRY_DELAY = 5_000
 const MAX_RETRY_DELAY = 60_000
 
 export type UseSeekThumbnailsOptions = {
-  publicPath: string
-  workerUrl: string
+  /** 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. */
@@ -35,7 +36,7 @@ export const useSeekThumbnails = ({
   rangesRef.current = ranges
 
   useEffect(() => {
-    if (!length || !read) return
+    if (!length || !read || !publicPath || !workerUrl) return
     let cancelled = false
     let generator: ThumbnailGenerator | null = null
     let retry: ReturnType<typeof setTimeout> | undefined

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/source-feature.ts

@@ -1,7 +1,20 @@
-import type { AudioStream, MediaIndex, SubtitleStream, ThumbnailImage } from '../engine'
+import type { MediaIndex, ThumbnailImage } from '../engine'
 
 import { definePlayerFeature } from '@videojs/core/dom'
 
+/**
+ * One row of a track menu, already named.
+ *
+ * Labelled by whoever writes it rather than by the menu, because the two writers know different
+ * things: the engine has a language tag and a title to disambiguate between, while a source that
+ * owns its own player hands over a label it has already decided on. The id is opaque here for the
+ * same reason, a libav stream index one way and a site's own track id the other.
+ */
+export type TrackChoice = {
+  id: string | number
+  label: string
+}
+
 /**
  * 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.
@@ -28,15 +41,20 @@ export type SourceState = {
   /** Keyframe index of the input, which turns a downloaded byte range into a time range. */
   indexes: MediaIndex[]
   thumbnails: ThumbnailImage[]
+  /**
+   * Answers for one time directly, when the source has a storyboard it can index but not enumerate.
+   * Falls back to scanning `thumbnails` when absent, which is what the engine's generator fills.
+   */
+  thumbnailAt?: (time: number) => ThumbnailImage | undefined
 
-  subtitleStreams: SubtitleStream[]
+  subtitleTracks: TrackChoice[]
   /** undefined means subtitles are off. */
-  selectedSubtitleStream: number | undefined
-  selectSubtitleStream: (streamIndex: number | undefined) => void
+  selectedSubtitleTrack: string | number | undefined
+  selectSubtitleTrack: (id: string | number | undefined) => void
 
-  audioStreams: AudioStream[]
-  selectedAudioStream: number
-  selectAudioStream: (streamIndex: number) => void
+  audioTracks: TrackChoice[]
+  selectedAudioTrack: string | number | undefined
+  selectAudioTrack: (id: string | number) => void
 
   /** Chrome auto-hide. True means the controls, title and cursor are hidden. */
   hideUI: boolean
@@ -63,12 +81,12 @@ export type SourceState = {
 const initialState: SourceState = {
   indexes: [],
   thumbnails: [],
-  subtitleStreams: [],
-  selectedSubtitleStream: undefined,
-  selectSubtitleStream: () => {},
-  audioStreams: [],
-  selectedAudioStream: -1,
-  selectAudioStream: () => {},
+  subtitleTracks: [],
+  selectedSubtitleTrack: undefined,
+  selectSubtitleTrack: () => {},
+  audioTracks: [],
+  selectedAudioTrack: undefined,
+  selectAudioTrack: () => {},
   hideUI: false,
   setHideUI: () => {},
   togglePictureInPicture: () => {},