@banou/media-player 0.7.0 → 0.8.0

package/dist/react/components/chrome.d.ts

@@ -1,9 +1,12 @@
 import type { ReactNode, Ref } from 'react';
 export type ChromeProps = {
     ref?: Ref<HTMLDivElement> | ((element: HTMLDivElement | null) => void);
-    onVideoRef: (element: HTMLVideoElement | null) => void;
+    /** Absent means render no video element: the media belongs to someone else and arrives as children. */
+    onVideoRef?: (element: HTMLVideoElement | null) => void;
     onCanvasRef: (element: HTMLCanvasElement | null) => void;
+    /** Above the control bar and outside the click-to-pause region, unlike `children`. */
+    overlay?: ReactNode;
     children?: ReactNode;
 };
-export declare const Chrome: ({ ref, onVideoRef, onCanvasRef, children }: ChromeProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const Chrome: ({ ref, onVideoRef, onCanvasRef, overlay, children }: ChromeProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Chrome;

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

@@ -1,6 +1,8 @@
-import type { MediaPlayerOptions } from '../video-player';
+import type { MediaPlayerLocalOptions } from '../video-player';
 /**
  * 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 declare const usePlayback: (video: HTMLVideoElement | null, canvas: HTMLCanvasElement | null, options: MediaPlayerOptions) => void;
+export declare 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) => void;

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

@@ -1,8 +1,9 @@
 import type { ThumbnailImage } from '../../engine';
 import type { DownloadedRange } from '../source-feature';
 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. */

package/dist/react/media.d.ts

@@ -0,0 +1,98 @@
+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 & {
+    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 declare const isExternalThumbnails: (value: unknown) => value is ExternalThumbnails;
+/**
+ * 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 declare const isDelegatedTracks: (value: unknown) => value is DelegatedTracks;

package/dist/react/player.d.ts

@@ -4,12 +4,13 @@ export declare const Player: import("@videojs/react").CreatePlayerResult<import(
     downloadedRanges?: import("./source-feature").DownloadedRange[];
     indexes: import("..").MediaIndex[];
     thumbnails: import("..").ThumbnailImage[];
-    subtitleStreams: import("..").SubtitleStream[];
-    selectedSubtitleStream: number | undefined;
-    selectSubtitleStream: (streamIndex: number | undefined) => void;
-    audioStreams: import("libav-wasm/build/worker").AudioStream[];
-    selectedAudioStream: number;
-    selectAudioStream: (streamIndex: number) => void;
+    thumbnailAt?: (time: number) => import("..").ThumbnailImage | undefined;
+    subtitleTracks: import("./source-feature").TrackChoice[];
+    selectedSubtitleTrack: string | number | undefined;
+    selectSubtitleTrack: (id: string | number | undefined) => void;
+    audioTracks: import("./source-feature").TrackChoice[];
+    selectedAudioTrack: string | number | undefined;
+    selectAudioTrack: (id: string | number) => void;
     hideUI: boolean;
     setHideUI: (hide: boolean) => void;
     togglePictureInPicture: () => void;

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

@@ -1,4 +1,16 @@
-import type { AudioStream, MediaIndex, SubtitleStream, ThumbnailImage } from '../engine';
+import type { MediaIndex, ThumbnailImage } from '../engine';
+/**
+ * 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.
@@ -23,13 +35,18 @@ export type SourceState = {
     /** Keyframe index of the input, which turns a downloaded byte range into a time range. */
     indexes: MediaIndex[];
     thumbnails: ThumbnailImage[];
-    subtitleStreams: SubtitleStream[];
+    /**
+     * 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;
+    subtitleTracks: TrackChoice[];
     /** undefined means subtitles are off. */
-    selectedSubtitleStream: number | undefined;
-    selectSubtitleStream: (streamIndex: number | undefined) => void;
-    audioStreams: AudioStream[];
-    selectedAudioStream: number;
-    selectAudioStream: (streamIndex: number) => void;
+    selectedSubtitleTrack: string | number | undefined;
+    selectSubtitleTrack: (id: string | number | undefined) => 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;
@@ -57,13 +74,18 @@ export declare const sourceFeature: import("@videojs/react").PlayerFeature<{
     /** Keyframe index of the input, which turns a downloaded byte range into a time range. */
     indexes: MediaIndex[];
     thumbnails: ThumbnailImage[];
-    subtitleStreams: SubtitleStream[];
+    /**
+     * 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;
+    subtitleTracks: TrackChoice[];
     /** undefined means subtitles are off. */
-    selectedSubtitleStream: number | undefined;
-    selectSubtitleStream: (streamIndex: number | undefined) => void;
-    audioStreams: AudioStream[];
-    selectedAudioStream: number;
-    selectAudioStream: (streamIndex: number) => void;
+    selectedSubtitleTrack: string | number | undefined;
+    selectSubtitleTrack: (id: string | number | undefined) => 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;

package/dist/react/video-player.d.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import type { DownloadedRange } from './source-feature';
+import type { DelegatedTracks, ExternalThumbnails, PlayerMedia } from './media';
 /**
  * The source, read a range at a time: the player never downloads the whole file. Both fields travel
  * together, so passing one without the other is a type error.
@@ -11,7 +12,22 @@ export type MediaPlayerSource = {
     read?: undefined;
     size?: undefined;
 };
-export type MediaPlayerOptions = MediaPlayerSource & {
+/** 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 & {
     /**
      * Where libav's wasm is served from. BOTH `libav.wasm` and `libav-jspi.wasm` have to be there:
      * libav-wasm picks between them on `WebAssembly.Suspending`, so serving one fails only on the
@@ -30,13 +46,37 @@ export type MediaPlayerOptions = MediaPlayerSource & {
     /** 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;
 export declare const MediaPlayer: (options: MediaPlayerOptions & {
     children?: ReactNode;
 }) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/utils/track-label.d.ts

@@ -3,6 +3,11 @@ export type LabelledTrack = {
     title: string;
     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.
@@ -17,3 +22,10 @@ export declare const labelTracks: <T extends LabelledTrack>(tracks: T[]) => {
     track: T;
     label: string;
 }[];
+/**
+ * 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 declare const toNamedTracks: <T extends LabelledTrack>(tracks: T[]) => NamedTrack[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/media-player",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A video player for containers and codecs the browser cannot play natively, remuxed on the fly",
   "type": "module",
   "main": "dist/index.js",
@@ -18,17 +18,23 @@
   },
   "files": [
     "dist",
-    "src/lib"
+    "src/lib",
+    "!src/lib/**/*.test.ts",
+    "!src/lib/**/*.test.tsx",
+    "!src/lib/**/*.fixture.ts"
   ],
   "scripts": {
     "dev": "npm run copy-assets && vp dev --port 4560",
     "build": "shx rm -rf build/ && npm run copy-assets && vp build",
     "preview": "vp preview",
     "build-lib": "shx rm -rf dist/ && vp build -c vite.lib.config.ts && npm run types",
+    "prepublishOnly": "npm run build-lib",
     "types": "tsc -p tsconfig.lib.json",
     "copy-assets": "shx mkdir -p public && npm run copy-libav && npm run copy-libass",
     "copy-libav": "shx cp node_modules/libav-wasm/build/worker.js public/libav-worker.js && shx cp node_modules/libav-wasm/build/libav.wasm public/libav.wasm && shx cp node_modules/libav-wasm/build/libav-jspi.wasm public/libav-jspi.wasm",
-    "copy-libass": "shx cp node_modules/jassub/dist/jassub-worker.js public/jassub-worker.js && shx cp node_modules/jassub/dist/jassub-worker.wasm public/jassub-worker.wasm && shx cp node_modules/jassub/dist/jassub-worker-modern.wasm public/jassub-worker-modern.wasm && shx cp node_modules/jassub/dist/default.woff2 public/default.woff2"
+    "copy-libass": "shx cp node_modules/jassub/dist/jassub-worker.js public/jassub-worker.js && shx cp node_modules/jassub/dist/jassub-worker.wasm public/jassub-worker.wasm && shx cp node_modules/jassub/dist/jassub-worker-modern.wasm public/jassub-worker-modern.wasm && shx cp node_modules/jassub/dist/default.woff2 public/default.woff2",
+    "test": "npm run fixtures && vp test run",
+    "fixtures": "node scripts/fixture.mjs"
   },
   "author": "Banou26",
   "dependencies": {
@@ -50,12 +56,15 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^6.0.3",
+    "@vitest/browser-playwright": "^4.1.10",
+    "playwright": "^1.62.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "shx": "^0.3.4",
     "typescript": "^7.0.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@0.2.4",
-    "vite-plus": "0.2.4"
+    "vite-plus": "0.2.4",
+    "vitest-browser-react": "^2.2.0"
   },
   "overrides": {
     "vite": "npm:@voidzero-dev/vite-plus-core@0.2.4"

package/src/lib/index.tsx

@@ -1,7 +1,22 @@
 /// <reference types="@emotion/react/types/css-prop" />
 
 export { MediaPlayer, default } from './react/video-player'
-export type { MediaPlayerOptions, MediaPlayerSource } from './react/video-player'
+export type {
+  MediaPlayerOptions,
+  MediaPlayerLocalOptions,
+  MediaPlayerRemoteOptions,
+  MediaPlayerSource,
+} from './react/video-player'
+
+// A media the player drives but does not own, for a source whose video lives somewhere unreachable.
+export { isDelegatedTracks, isExternalThumbnails } from './react/media'
+export type {
+  DelegatedSelection,
+  DelegatedTracks,
+  ExternalThumbnails,
+  PlayerMedia,
+  TimeRangesLike,
+} from './react/media'
 
 export { Player, usePlayer } from './react/player'
 export type { PlayerStore } from './react/player'

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

@@ -46,12 +46,15 @@ const style = css`
 
 export type ChromeProps = {
   ref?: Ref<HTMLDivElement> | ((element: HTMLDivElement | null) => void)
-  onVideoRef: (element: HTMLVideoElement | null) => void
+  /** Absent means render no video element: the media belongs to someone else and arrives as children. */
+  onVideoRef?: (element: HTMLVideoElement | null) => void
   onCanvasRef: (element: HTMLCanvasElement | null) => void
+  /** Above the control bar and outside the click-to-pause region, unlike `children`. */
+  overlay?: ReactNode
   children?: ReactNode
 }
 
-export const Chrome = ({ ref, onVideoRef, onCanvasRef, children }: ChromeProps) => {
+export const Chrome = ({ ref, onVideoRef, onCanvasRef, overlay, children }: ChromeProps) => {
   const player = usePlayer()
   const hideUI = usePlayer((state) => state.hideUI)
   const setHideUI = usePlayer((state) => state.setHideUI)
@@ -114,9 +117,10 @@ export const Chrome = ({ ref, onVideoRef, onCanvasRef, children }: ChromeProps)
       className={hideUI ? 'hide' : ''}
     >
       <Overlay onCanvasRef={onCanvasRef} />
+      {overlay}
       <ControlBar />
       <div className="video" onClick={onVideoClick}>
-        <video ref={onVideoRef} playsInline />
+        {onVideoRef ? <video ref={onVideoRef} playsInline /> : null}
         {children}
       </div>
     </div>

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

@@ -18,9 +18,9 @@ const titleStyle = css`
   top: 0;
   left: 0;
   width: 100%;
-  padding: 1.2rem 1.6rem;
+  padding: calc(1.2 * var(--mp-unit)) calc(1.6 * var(--mp-unit));
   /* clears a notch once the player is fullscreen; resolves to zero everywhere else */
-  padding-top: calc(1.2rem + env(safe-area-inset-top, 0px));
+  padding-top: calc(calc(1.2 * var(--mp-unit)) + env(safe-area-inset-top, 0px));
   ${fonts.headings.small}
   color: white;
   text-shadow: 0 0 4px rgba(0, 0, 0, 1);
@@ -34,8 +34,8 @@ const titleStyle = css`
   text-overflow: ellipsis;
 
   @media (min-width: 768px) {
-    padding: 2.4rem;
-    padding-top: calc(2.4rem + env(safe-area-inset-top, 0px));
+    padding: calc(2.4 * var(--mp-unit));
+    padding-top: calc(calc(2.4 * var(--mp-unit)) + env(safe-area-inset-top, 0px));
     white-space: normal;
     overflow: visible;
   }
@@ -59,8 +59,8 @@ const loadingStyle = css`
 
   ::after {
     content: '';
-    width: 4rem;
-    height: 4rem;
+    width: calc(4 * var(--mp-unit));
+    height: calc(4 * var(--mp-unit));
     border-radius: 50%;
     border: 3px solid rgba(255, 255, 255, 0.25);
     border-top-color: #fff;
@@ -73,7 +73,7 @@ const errorStyle = css`
   position: absolute;
   inset: auto 0 20%;
   z-index: 3;
-  padding: 0 2rem;
+  padding: 0 calc(2 * var(--mp-unit));
   text-align: center;
   color: #fff;
   ${fonts.bLarge.regular}
@@ -92,6 +92,8 @@ export const Overlay = ({ onCanvasRef }: { onCanvasRef: (element: HTMLCanvasElem
   const playbackError = usePlayer((state) => state.playbackError)
   const ready = usePlayer((state) => state.ready)
   const size = usePlayer((state) => state.size)
+  // video.js's own: readyState below HAVE_FUTURE_DATA while not paused
+  const waiting = usePlayer((state) => state.waiting)
 
   return (
     <>
@@ -105,9 +107,11 @@ export const Overlay = ({ onCanvasRef }: { onCanvasRef: (element: HTMLCanvasElem
           </div>
         )
         : undefined}
-      {/* pre-metadata, not buffering: the store reports 0 both before metadata and for a genuinely
-          unknown duration, while `size` tells whether a source was handed over at all */}
-      {size && !ready && !playbackError
+      {/* Two different waits, one spinner. With bytes it is pre-metadata rather than buffering: the
+          store reports 0 both before metadata and for a genuinely unknown duration, so `size` is what
+          tells whether a source was handed over at all. A media this player does not own has neither
+          `size` nor `ready`, and reports the ordinary `waiting` every element does. */}
+      {(size ? !ready : waiting) && !playbackError
         ? <div css={loadingStyle} />
         : undefined}
       {playbackError