@banou/media-player 0.7.0 → 0.8.1

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,22 +41,35 @@ 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
   setHideUI: (hide: boolean) => void
 
-  /** Owned here, not by `pip`: that watches the media element, and the window holds a mirror. */
-  togglePictureInPicture: () => void
+  /**
+   * Owned here, not by `pip`: that watches the media element, and the window holds a mirror.
+   *
+   * null means the control is not offered at all. Locally that is "no element yet". For a media the
+   * player does not own it means the source cannot do it, and the difference matters: the compositing
+   * this does needs a local element to draw, and even a source that forwards the request cannot
+   * report the resulting STATE back, since `document.pictureInPictureElement` is never a proxy. A
+   * button that toggles nothing and never lights up is worse than no button.
+   */
+  togglePictureInPicture: (() => void) | null
 
   /** Set when the pipeline fails. Cleared when it recovers. */
   playbackError: unknown
@@ -63,15 +89,15 @@ 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: () => {},
+  togglePictureInPicture: null,
   playbackError: null,
   ready: false,
   setSourceState: () => {},

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

@@ -1,6 +1,7 @@
 /// <reference types="@emotion/react/types/css-prop" />
 import type { ReactNode } from 'react'
 import type { DownloadedRange } from './source-feature'
+import type { DelegatedTracks, ExternalThumbnails, PlayerMedia } from './media'
 
 import { useEffect, useState } from 'react'
 import { css } from '@emotion/react'
@@ -20,7 +21,26 @@ export type MediaPlayerSource =
   | { read: (offset: number, size: number) => Promise<ArrayBuffer>, size: number }
   | { read?: undefined, size?: undefined }
 
-export type MediaPlayerOptions =
+/** Shared by both arms: nothing here depends on who owns the media. */
+type CommonOptions = {
+  title?: string
+  autoplay?: boolean
+
+  /**
+   * Drawn above the control bar and outside the click-to-pause region, for whatever the app has to
+   * say over the video. `children` land next to the media instead, below the chrome.
+   */
+  overlay?: ReactNode
+
+  onSeek?: (fraction: number) => void
+  onPlaybackError?: (error: unknown) => void
+}
+
+/**
+ * Bytes in: the player owns the `<video>`, and libav feeds it a fragment at a time.
+ */
+export type MediaPlayerLocalOptions =
+  & CommonOptions
   & MediaPlayerSource
   & {
     /**
@@ -41,18 +61,57 @@ export type MediaPlayerOptions =
     /** Fallback face for `liberation sans`, used when a subtitle track names a font the file does not carry. */
     defaultFontUrl?: string
     bufferSize?: number
-    autoplay?: boolean
 
-    title?: string
     /** Byte spans available, painted on the seekbar and informing the thumbnail generator. */
     downloadedRanges?: DownloadedRange[]
 
-    onSeek?: (fraction: number) => void
-    onPlaybackError?: (error: unknown) => void
+    /**
+     * Reader for the thumbnail engine, when it should differ from playback's.
+     *
+     * They are the same by default so generation shares playback's fetch order. A consumer whose
+     * reads are not free wants them apart: a torrent hands this a non-prioritising, fail-fast reader
+     * so generating previews cannot steal download order from the bytes playback is blocked on.
+     */
+    thumbnailRead?: (offset: number, size: number) => Promise<ArrayBuffer>
+    /** Off entirely. A second wasm worker during pipeline boot is worth avoiding on a slow source. */
+    thumbnailsEnabled?: boolean
+  }
+
+/**
+ * A media the caller owns and the player only drives.
+ *
+ * No bytes, so no libav, no MediaSource and no thumbnail generation. For a source whose video lives
+ * in a document this one cannot reach into, which is also the only arrangement under which its DRM
+ * works: the key session belongs to whoever owns the element.
+ */
+export type MediaPlayerRemoteOptions =
+  & CommonOptions
+  & {
+    media: PlayerMedia
+    read?: never
+    size?: never
+
+    /** The source's own storyboard, since there are no bytes to generate previews from. */
+    thumbnails?: ExternalThumbnails
+    /** The source renders these; the player draws the menu and reports the pick. */
+    subtitles?: DelegatedTracks
+    audioTracks?: DelegatedTracks
   }
 
+export type MediaPlayerOptions = MediaPlayerLocalOptions | MediaPlayerRemoteOptions
+
 const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, children?: ReactNode }) => {
-  const { title, size, downloadedRanges, publicPath, libavWorkerUrl, read } = options
+  // Narrowed on the field that carries the difference: a remote arm brings its own media and, by
+  // construction, no bytes. Both halves stay null-safe so the engine hooks below can be called
+  // unconditionally, which they have to be.
+  const remote = 'media' in options ? options : null
+  const local = remote ? null : options as MediaPlayerLocalOptions
+  // `title` is common to both arms, so it is read off `options`. Everything else here belongs to the
+  // local arm and is absent when the media is remote.
+  const { title } = options
+  const {
+    size, downloadedRanges, publicPath, libavWorkerUrl, read, thumbnailRead, thumbnailsEnabled,
+  } = local ?? ({} as Partial<MediaPlayerLocalOptions>)
 
   const setMedia = useMediaAttach()
   // Mandatory, not an optimisation: without it requestFullscreen falls through to the bare <video>
@@ -62,17 +121,24 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
   const [video, setVideo] = useState<HTMLVideoElement | null>(null)
   const [canvas, setCanvas] = useState<HTMLCanvasElement | null>(null)
 
-  useEffect(() => { setMedia?.(video); return () => setMedia?.(null) }, [video, setMedia])
+  // Attaching is not optional in either arm: the store installs `setSourceState` in `attach`, and
+  // video.js only runs attach once media is non-null, so skipping it would leave every write below a
+  // permanent no-op.
+  const media = remote?.media ?? video
+  useEffect(() => { setMedia?.(media); return () => setMedia?.(null) }, [media, setMedia])
 
-  usePlayback(video, canvas, options)
+  // Each of these no-ops on null inputs, which is what a remote arm supplies: it renders no <video>,
+  // so there is nothing for them to attach to and nothing to guard at the call site.
+  usePlayback(video, canvas, local)
 
-  const thumbnails = useSeekThumbnails({
+  const generatedThumbnails = useSeekThumbnails({
     publicPath,
     workerUrl: libavWorkerUrl,
-    length: size,
-    read,
+    length: thumbnailsEnabled === false ? undefined : size,
+    read: thumbnailRead ?? read,
     downloadedRanges,
   })
+  const thumbnails = remote?.thumbnails?.all ?? generatedThumbnails
   const togglePictureInPicture = usePictureInPicture(video, canvas)
 
   // Subscribed rather than read off the store, because it is a no-op until the media element
@@ -83,15 +149,42 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
     setSourceState({ title, size, downloadedRanges })
   }, [setSourceState, title, size, downloadedRanges])
 
+  const thumbnailAt = remote?.thumbnails?.at
   useEffect(() => {
-    setSourceState({ thumbnails, togglePictureInPicture })
-  }, [setSourceState, thumbnails, togglePictureInPicture])
+    setSourceState({ thumbnails, thumbnailAt, togglePictureInPicture })
+  }, [setSourceState, thumbnails, thumbnailAt, togglePictureInPicture])
+
+  // A delegated track list writes the same store fields the engine writes, so the menus never learn
+  // which arm they are showing. Only the writer differs: here the pick is forwarded to whoever owns
+  // the document, and it renders the result itself.
+  const subtitles = remote?.subtitles?.selection
+  const audio = remote?.audioTracks?.selection
+  useEffect(() => {
+    if (!subtitles) return
+    setSourceState({
+      subtitleTracks: subtitles.options.map(({ id, label }) => ({ id, label })),
+      selectedSubtitleTrack: subtitles.selectedId ?? undefined,
+      selectSubtitleTrack: (id) => subtitles.select(id == null ? null : String(id)),
+    })
+  }, [setSourceState, subtitles])
+
+  useEffect(() => {
+    if (!audio) return
+    setSourceState({
+      audioTracks: audio.options.map(({ id, label }) => ({ id, label })),
+      selectedAudioTrack: audio.selectedId ?? undefined,
+      selectAudioTrack: (id) => audio.select(String(id)),
+    })
+  }, [setSourceState, audio])
 
   return (
     <Chrome
       ref={setContainer}
-      onVideoRef={setVideo}
+      // No element in the remote arm: the media is somebody else's, and whatever renders it is
+      // passed in as children. Rendering an idle <video> here would sit over it.
+      onVideoRef={remote ? undefined : setVideo}
       onCanvasRef={setCanvas}
+      overlay={options.overlay}
     >
       {children}
     </Chrome>
@@ -100,6 +193,17 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
 
 // #111 against the black inside is deliberate: this is the letterbox around the player box.
 const rootStyle = css`
+  /**
+   * The chrome's whole scale, in one place.
+   *
+   * Everything inside is sized against this rather than against \`rem\`, because \`rem\` is root
+   * relative and a library cannot own the host page's root font. The old contract was that the host
+   * set \`html { font-size: 62.5% }\`, which silently rendered every control 1.6x too large in any app
+   * that did not, and could not be met by an app whose own screens are sized against the default.
+   * Override it on the player element to rescale the whole chrome.
+   */
+  --mp-unit: 10px;
+
   display: flex;
   justify-content: center;
   background-color: #111;

package/src/lib/utils/fonts.ts

@@ -2,158 +2,158 @@ export const fonts = {
   headings: {
     large: `
       font-weight: 600;
-      font-size: 2.8rem;
-      line-height: 3.4rem;
+      font-size: calc(2.8 * var(--mp-unit));
+      line-height: calc(3.4 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 3.4rem;
-        line-height: 4.1rem;
+        font-size: calc(3.4 * var(--mp-unit));
+        line-height: calc(4.1 * var(--mp-unit));
       }
     `,
     medium: `
       font-weight: 600;
-      font-size: 2.4rem;
-      line-height: 2.9rem;
+      font-size: calc(2.4 * var(--mp-unit));
+      line-height: calc(2.9 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 2.8rem;
-        line-height: 3.4rem;
+        font-size: calc(2.8 * var(--mp-unit));
+        line-height: calc(3.4 * var(--mp-unit));
       }
     `,
     small: `
       font-weight: 500;
-      font-size: 1.8rem;
-      line-height: 1.9rem;
+      font-size: calc(1.8 * var(--mp-unit));
+      line-height: calc(1.9 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 1.8rem;
-        line-height: 2.2rem;
+        font-size: calc(1.8 * var(--mp-unit));
+        line-height: calc(2.2 * var(--mp-unit));
       }
       @media (min-width: 2560px) {
-        font-size: 2.2rem;
-        line-height: 2.6rem;
+        font-size: calc(2.2 * var(--mp-unit));
+        line-height: calc(2.6 * var(--mp-unit));
       }
     `,
     extraSmall: `
       font-weight: 500;
-      font-size: 1.4rem;
-      line-height: 1.7rem;
+      font-size: calc(1.4 * var(--mp-unit));
+      line-height: calc(1.7 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 1.6rem;
-        line-height: 1.9rem;
+        font-size: calc(1.6 * var(--mp-unit));
+        line-height: calc(1.9 * var(--mp-unit));
       }
     `
   },
   bLarge: {
     bold: `
       font-weight: 600;
-      font-size: 1.4rem;
-      line-height: 2rem;
+      font-size: calc(1.4 * var(--mp-unit));
+      line-height: calc(2 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 1.6rem;
-        line-height: 2.2rem;
+        font-size: calc(1.6 * var(--mp-unit));
+        line-height: calc(2.2 * var(--mp-unit));
       }
     `,
     medium: `
       font-weight: 500;
-      font-size: 1.4rem;
-      line-height: 2rem;
+      font-size: calc(1.4 * var(--mp-unit));
+      line-height: calc(2 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 1.6rem;
-        line-height: 2.2rem;
+        font-size: calc(1.6 * var(--mp-unit));
+        line-height: calc(2.2 * var(--mp-unit));
       }
     `,
     regular: `
       font-weight: 400;
-      font-size: 1.4rem;
-      line-height: 2rem;
+      font-size: calc(1.4 * var(--mp-unit));
+      line-height: calc(2 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 1.6rem;
-        line-height: 2.2rem;
+        font-size: calc(1.6 * var(--mp-unit));
+        line-height: calc(2.2 * var(--mp-unit));
       }
     `,
   },
   bMedium: {
     bold: `
       font-weight: 600;
-      font-size: 1.2rem;
-      line-height: 1.7rem;
+      font-size: calc(1.2 * var(--mp-unit));
+      line-height: calc(1.7 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 1.4rem;
-        line-height: 2rem;
+        font-size: calc(1.4 * var(--mp-unit));
+        line-height: calc(2 * var(--mp-unit));
       }
     `,
     medium: `
       font-weight: 500;
-      font-size: 1.2rem;
-      line-height: 1.7rem;
+      font-size: calc(1.2 * var(--mp-unit));
+      line-height: calc(1.7 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 1.4rem;
-        line-height: 2rem;
+        font-size: calc(1.4 * var(--mp-unit));
+        line-height: calc(2 * var(--mp-unit));
       }
     `,
     regular: `
       font-weight: 400;
-      font-size: 1.2rem;
-      line-height: 1.7rem;
+      font-size: calc(1.2 * var(--mp-unit));
+      line-height: calc(1.7 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 1.4rem;
-        line-height: 2rem;
+        font-size: calc(1.4 * var(--mp-unit));
+        line-height: calc(2 * var(--mp-unit));
       }
     `,
   },
   bSmall: {
     bold: `
       font-weight: 600;
-      font-size: 1rem;
-      line-height: 1.4rem;
+      font-size: calc(1 * var(--mp-unit));
+      line-height: calc(1.4 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 1.2rem;
-        line-height: 1.7rem;
+        font-size: calc(1.2 * var(--mp-unit));
+        line-height: calc(1.7 * var(--mp-unit));
       }
     `,
     medium: `
       font-weight: 500;
-      font-size: 1rem;
-      line-height: 1.4rem;
+      font-size: calc(1 * var(--mp-unit));
+      line-height: calc(1.4 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 1.2rem;
-        line-height: 1.7rem;
+        font-size: calc(1.2 * var(--mp-unit));
+        line-height: calc(1.7 * var(--mp-unit));
       }
     `,
     regular: `
       font-weight: 400;
-      font-size: 1rem;
-      line-height: 1.4rem;
+      font-size: calc(1 * var(--mp-unit));
+      line-height: calc(1.4 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 1.2rem;
-        line-height: 1.7rem;
+        font-size: calc(1.2 * var(--mp-unit));
+        line-height: calc(1.7 * var(--mp-unit));
       }
     `,
   },
   bExtraSmall: {
     bold: `
       font-weight: 600;
-      font-size: 0.8rem;
-      line-height: 1.1rem;
+      font-size: calc(0.8 * var(--mp-unit));
+      line-height: calc(1.1 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 1rem;
-        line-height: 1.4rem;
+        font-size: calc(1 * var(--mp-unit));
+        line-height: calc(1.4 * var(--mp-unit));
       }
     `,
     medium: `
       font-weight: 500;
-      font-size: 0.8rem;
-      line-height: 1.1rem;
+      font-size: calc(0.8 * var(--mp-unit));
+      line-height: calc(1.1 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 1rem;
-        line-height: 1.4rem;
+        font-size: calc(1 * var(--mp-unit));
+        line-height: calc(1.4 * var(--mp-unit));
       }
     `,
     regular: `
       font-weight: 400;
-      font-size: 0.8rem;
-      line-height: 1.1rem;
+      font-size: calc(0.8 * var(--mp-unit));
+      line-height: calc(1.1 * var(--mp-unit));
       @media (min-width: 960px) {
-        font-size: 1rem;
-        line-height: 1.4rem;
+        font-size: calc(1 * var(--mp-unit));
+        line-height: calc(1.4 * var(--mp-unit));
       }
     `,
   },

package/src/lib/utils/track-label.ts

@@ -4,6 +4,12 @@ export type LabelledTrack = {
   language: string
 }
 
+/** One row of a track menu, already named. Mirrors `TrackChoice` without importing the store. */
+export type NamedTrack = {
+  id: string | number
+  label: string
+}
+
 /**
  * Human name for a track's language tag. `fallback: 'none'` is what makes an unknown tag come back
  * undefined instead of echoing itself, so the caller can fall through to the title.
@@ -34,3 +40,12 @@ export const labelTracks = <T extends LabelledTrack>(tracks: T[]): { track: T, l
     return { track, label: ambiguous && detail && detail !== base ? `${base} (${detail})` : base }
   })
 }
+
+/**
+ * Names the engine's streams once, on the way into the store, so the menu only ever reads rows.
+ *
+ * The store's ids are opaque so a source that owns its own player can use its own track ids; the id
+ * here is the libav stream index, which is what this half of the code has to say.
+ */
+export const toNamedTracks = <T extends LabelledTrack>(tracks: T[]): NamedTrack[] =>
+  labelTracks(tracks).map(({ track, label }) => ({ id: track.streamIndex, label }))