react-helios 2.4.0 → 2.7.0

package/README.md

@@ -1,6 +1,6 @@
 # react-helios
 
-Production-grade React video player with HLS streaming, adaptive quality selection, live stream support, subtitle tracks, VTT sprite sheet thumbnail preview, Picture-in-Picture, and full keyboard control.
+Production-grade React video player with HLS streaming, zero-cost audio mode, adaptive quality selection, live stream support, subtitle tracks, VTT sprite sheet thumbnail preview, Picture-in-Picture, and full keyboard control.
 
 ## Installation
 
@@ -24,8 +24,13 @@ export default function App() {
   return (
     <VideoPlayer
       src="https://example.com/video.mp4"
+      poster="https://example.com/poster.jpg"
       controls
-      autoplay={false}
+      options={{
+        autoplay: false,
+        loop: false,
+        thumbnailVtt: "https://example.com/thumbs/storyboard.vtt",
+      }}
     />
   );
 }
@@ -41,12 +46,100 @@ Pass any `.m3u8` URL — HLS.js is initialised automatically:
 <VideoPlayer
   src="https://example.com/stream.m3u8"
   controls
-  enableHLS        // default: true
+  options={{
+    enableHLS: true,         // default: true
+    hlsConfig: {
+      maxBufferLength: 60,
+      capLevelToPlayerSize: true,
+    },
+  }}
 />
 ```
 
 On Safari the browser's native HLS engine is used. A **LIVE** badge and **GO LIVE** button appear automatically for live streams.
 
+## Audio Mode
+
+Audio mode pauses the video element completely (stopping all video decoding), shows the poster artwork, and hands playback off to a lightweight `<audio>` element — so the player uses roughly the same CPU/GPU as a music app instead of a playing video.
+
+```tsx
+<VideoPlayer
+  src="https://example.com/stream.m3u8"
+  poster="https://example.com/artwork.jpg"
+  controls
+  options={{
+    audioSrc: "https://example.com/audio-only.m3u8",
+    audioModeLabel: "Switch to Audio",
+    videoModeLabel: "Switch to Video",
+    defaultAudioMode: false,
+    onAudioModeChange: (isAudio) => console.log("audio mode:", isAudio),
+  }}
+/>
+```
+
+The audio toggle button only appears in the control bar when `audioSrc` is provided. Custom icons can be passed via `audioModeIcon` / `videoModeIcon`.
+
+When switching between modes, position, volume, and playback rate are synced automatically — the listener hears no gap.
+
+### Automatic switching
+
+The player uses two independent signals to detect poor conditions and switch to audio mode automatically. Either one firing is enough.
+
+**Bandwidth-based** — measures the actual download speed of each HLS fragment and switches when the rolling average drops below a threshold:
+
+```tsx
+import { AUDIO_BANDWIDTH_THRESHOLDS } from "react-helios";
+
+<VideoPlayer
+  src="https://example.com/stream.m3u8"
+  options={{
+    audioBandwidthThreshold: AUDIO_BANDWIDTH_THRESHOLDS.FAIR, // recommended
+    // audioBandwidthThreshold: 0,  // disable bandwidth-based switching
+  }}
+/>
+```
+
+| Preset | Kbps | Typical connection |
+|--------|------|--------------------|
+| `EXTREME` | 100 | 2G / Edge |
+| `POOR` | 300 | Slow 3G |
+| `FAIR` | 800 | Marginal 3G ← **recommended** |
+| `GOOD` | 1500 | Weak 4G / congested Wi-Fi |
+
+**Level-based** — switches when HLS.js drops to a specific quality level (its own ABR algorithm already does the hard work):
+
+```tsx
+import { AUDIO_SWITCH_LEVELS } from "react-helios";
+
+<VideoPlayer
+  src="https://example.com/stream.m3u8"
+  options={{
+    audioModeSwitchLevel: AUDIO_SWITCH_LEVELS.LOWEST, // switch at lowest quality level
+  }}
+/>
+```
+
+| Preset | Value | Meaning |
+|--------|-------|---------|
+| `LOWEST` | 0 | Switch when HLS.js is at the lowest available quality |
+| `SECOND_LOWEST` | 1 | Switch one level above the lowest |
+| `DISABLED` | -1 | Disable level-based switching |
+
+Using **both together** is the most reliable approach:
+
+```tsx
+<VideoPlayer
+  src="https://example.com/stream.m3u8"
+  options={{
+    audioSrc: "https://example.com/audio-only.m3u8",
+    audioBandwidthThreshold: AUDIO_BANDWIDTH_THRESHOLDS.FAIR,
+    audioModeSwitchLevel: AUDIO_SWITCH_LEVELS.LOWEST,
+  }}
+/>
+```
+
+After the user manually toggles audio mode a 60-second cooldown suppresses automatic switching. The player also probes for bandwidth recovery every 30 seconds while in auto-switched audio mode (configurable via `audioModeRecoveryInterval`).
+
 ## Thumbnail Preview
 
 Hover over the progress bar to see a time tooltip. For rich sprite-sheet thumbnails, pass a `thumbnailVtt` URL pointing to a [WebVTT thumbnail file](https://developer.bitmovin.com/playback/docs/webvtt-based-thumbnails).
@@ -54,7 +147,9 @@ Hover over the progress bar to see a time tooltip. For rich sprite-sheet thumbna
 ```tsx
 <VideoPlayer
   src="https://example.com/video.mp4"
-  thumbnailVtt="https://example.com/thumbs/storyboard.vtt"
+  options={{
+    thumbnailVtt: "https://example.com/thumbs/storyboard.vtt",
+  }}
 />
 ```
 
@@ -80,38 +175,90 @@ The player fetches the VTT file once, parses all cues, and uses CSS `background-
 To disable the preview entirely:
 
 ```tsx
-<VideoPlayer src="..." enablePreview={false} />
+<VideoPlayer src="..." options={{ enablePreview: false }} />
 ```
 
 ## Props
 
+### Top-level props
+
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `src` | `string` | — | Video URL (MP4, WebM, HLS `.m3u8`, …) |
-| `poster` | `string` | — | Poster image shown before playback |
+| `poster` | `string` | — | Poster image shown before playback and in audio mode |
 | `controls` | `boolean` | `true` | Show the built-in control bar |
+| `className` | `string` | — | CSS class on the player container |
+| `options` | `VideoPlayerOptions` | `{}` | All configuration (see below) |
+
+### `options` — Playback
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
 | `autoplay` | `boolean` | `false` | Start playback on mount |
 | `muted` | `boolean` | `false` | Start muted |
 | `loop` | `boolean` | `false` | Loop the video |
 | `preload` | `"none" \| "metadata" \| "auto"` | `"metadata"` | Native `preload` attribute |
-| `playbackRates` | `PlaybackRate[]` | `[0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]` | Available speed options |
+| `playbackRates` | `PlaybackRate[]` | `[0.25 … 2]` | Available speed options |
+| `crossOrigin` | `"anonymous" \| "use-credentials"` | — | CORS attribute for the video element |
+| `subtitles` | `SubtitleTrack[]` | — | Subtitle / caption tracks |
+
+### `options` — HLS
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
 | `enableHLS` | `boolean` | `true` | Enable HLS.js for `.m3u8` sources |
+| `hlsConfig` | `Partial<HlsConfig>` | — | Override any [hls.js config](https://github.com/video-dev/hls.js/blob/master/docs/API.md#fine-tuning) option |
+
+### `options` — Preview
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
 | `enablePreview` | `boolean` | `true` | Show thumbnail / time tooltip on progress bar hover |
 | `thumbnailVtt` | `string` | — | URL to a WebVTT sprite sheet file for rich thumbnail preview |
-| `hlsConfig` | `Partial<HlsConfig>` | — | Override any [hls.js configuration](https://github.com/video-dev/hls.js/blob/master/docs/API.md#fine-tuning) option |
-| `subtitles` | `SubtitleTrack[]` | — | Subtitle / caption tracks |
-| `crossOrigin` | `"anonymous" \| "use-credentials"` | — | CORS attribute for the video element |
-| `className` | `string` | — | CSS class on the player container |
-| `onPlay` | `() => void` | — | Fired when playback starts |
-| `onPause` | `() => void` | — | Fired when playback pauses |
-| `onEnded` | `() => void` | — | Fired when playback ends |
-| `onError` | `(error: VideoError) => void` | — | Fired on playback or stream errors |
-| `onTimeUpdate` | `(time: number) => void` | — | Fired every ~250 ms during playback |
-| `onDurationChange` | `(duration: number) => void` | — | Fired when video duration becomes known |
-| `onBuffering` | `(isBuffering: boolean) => void` | — | Fired when buffering starts / stops |
-| `onTheaterModeChange` | `(isTheater: boolean) => void` | — | Fired when theater mode is toggled |
-| `contextMenuItems` | `ContextMenuItem[]` | — | Extra items appended to the right-click context menu |
-| `controlBarItems` | `ControlBarItem[]` | — | Extra icon buttons appended to the right side of the control bar |
+
+### `options` — UI
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `autoHideControls` | `boolean` | `true` | Hide control bar on mouse leave when playing (video mode only) |
+
+### `options` — Audio mode
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `audioSrc` | `string` | — | Audio-only stream URL; the audio toggle button only shows when this is set |
+| `showAudioButton` | `boolean` | `!!audioSrc` | Force-show or hide the audio toggle button |
+| `defaultAudioMode` | `boolean` | `false` | Start in audio mode |
+| `audioModeLabel` | `string` | `"Audio"` | Label on the toggle button when in video mode |
+| `videoModeLabel` | `string` | `"Video"` | Label on the toggle button when in audio mode |
+| `audioModeIcon` | `ReactNode` | built-in headphones icon | Icon shown when in video mode (click → audio) |
+| `videoModeIcon` | `ReactNode` | built-in video icon | Icon shown when in audio mode (click → video) |
+| `audioModeFallback` | `ReactNode` | — | Custom content shown in audio mode when no `poster` is provided |
+| `logo` | `string \| ReactNode` | — | Logo shown in audio mode when no `poster` or `audioModeFallback` is provided |
+| `audioBandwidthThreshold` | `number` | `300` | Kbps — switch when per-fragment bandwidth average drops below this. `0` = disabled (HLS only) |
+| `audioModeSwitchLevel` | `number` | — | HLS quality level index — switch when HLS.js drops to this level or below. `0` = lowest. `-1` = disabled |
+| `audioModeRecoveryInterval` | `number` | `30000` | Ms between recovery probes while in auto-switched audio mode |
+
+### `options` — Callbacks
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `onPlay` | `() => void` | Fired when playback starts |
+| `onPause` | `() => void` | Fired when playback pauses |
+| `onEnded` | `() => void` | Fired when playback ends |
+| `onError` | `(error: VideoError) => void` | Fired on playback or stream errors |
+| `onTimeUpdate` | `(time: number) => void` | Fired every ~250 ms during playback |
+| `onDurationChange` | `(duration: number) => void` | Fired when video duration becomes known |
+| `onBuffering` | `(isBuffering: boolean) => void` | Fired when buffering starts / stops |
+| `onTheaterModeChange` | `(isTheater: boolean) => void` | Fired when theater mode is toggled |
+| `onAudioModeChange` | `(isAudio: boolean) => void` | Fired when audio mode is toggled (manual or automatic) |
+
+### `options` — Custom controls
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `contextMenuItems` | `ContextMenuItem[]` | Extra items appended to the right-click context menu |
+| `controlBarItems` | `ControlBarItem[]` | Extra icon buttons appended to the right side of the control bar |
 
 ## Quality Selection
 
@@ -120,8 +267,6 @@ For HLS streams (`.m3u8`) the player automatically parses the available quality
 - **Speed tab** — always visible, lets you change playback rate.
 - **Quality tab** — appears only for HLS streams. Lists all levels sorted by bitrate (e.g. 1080p, 720p, 480p) plus an **Auto** option that enables ABR (adaptive bitrate). The current auto-selected level is shown in parentheses next to "Auto".
 
-For plain MP4/WebM files there are no quality levels to switch between, so the Quality tab never appears.
-
 You can also switch quality programmatically via the ref:
 
 ```tsx
@@ -131,49 +276,41 @@ playerRef.current?.setQualityLevel(-1);  // back to ABR auto
 
 ## Custom Control Bar Buttons
 
-Inject your own icon buttons into the right side of the control bar (between the settings gear and the PiP/Theater/Fullscreen buttons) using `controlBarItems`:
+Inject your own icon buttons into the right side of the control bar using `controlBarItems`:
 
 ```tsx
-import { VideoPlayer, ControlBarItem } from "react-helios";
+import { VideoPlayer } from "react-helios";
+import type { ControlBarItem } from "react-helios";
 
 const items: ControlBarItem[] = [
   {
-    key: "download",
-    label: "Download",
-    icon: <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><path d="M19 9h-4V3H9v6H5l7 7 7-7zm-8 2V5h2v6h1.17L12 13.17 9.83 11H11zm-6 7h14v2H5v-2z"/></svg>,
-    onClick: () => downloadVideo(),
-  },
-  {
-    key: "share",
-    label: "Share",
-    title: "Share this video",
-    icon: <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><path d="M18 16.08c-.76 0-1.44.3-1.96.77L8.91 12.7c.05-.23.09-.46.09-.7s-.04-.47-.09-.7l7.05-4.11A2.99 2.99 0 0 0 18 8a3 3 0 1 0-3-3c0 .24.04.47.09.7L8.04 9.81A2.99 2.99 0 0 0 6 9a3 3 0 1 0 3 3c0-.24-.04-.47-.09-.7l7.05-4.11c.52.47 1.2.77 1.96.77a3 3 0 0 0 3-3 3 3 0 0 0-3-3z"/></svg>,
-    onClick: () => openShareDialog(),
+    key: "bookmark",
+    label: "Bookmark",
+    title: "Save current position",
+    icon: <BookmarkIcon />,
+    onClick: () => saveBookmark(playerRef.current?.getState().currentTime ?? 0),
   },
 ];
 
-<VideoPlayer src="..." controlBarItems={items} />
+<VideoPlayer src="..." options={{ controlBarItems: items }} />
 ```
 
-Buttons receive the same `controlButton` CSS class as built-in buttons (hover highlight, active press scale, no focus outline).
-
 ## Context Menu
 
-Right-clicking the player shows a built-in menu (Play/Pause, Loop, Copy URL, Picture-in-Picture). You can append your own items by passing `contextMenuItems`:
+Right-clicking the player shows a built-in menu (Play/Pause, Loop, Copy URL, Picture-in-Picture). Append your own items via `contextMenuItems`:
 
 ```tsx
-import { VideoPlayer, ContextMenuItem } from "react-helios";
+import { VideoPlayer } from "react-helios";
+import type { ContextMenuItem } from "react-helios";
 
 const items: ContextMenuItem[] = [
   { label: "Add to Watchlist", onClick: () => addToWatchlist() },
   { label: "Share", onClick: () => openShareDialog() },
 ];
 
-<VideoPlayer src="..." contextMenuItems={items} />
+<VideoPlayer src="..." options={{ contextMenuItems: items }} />
 ```
 
-Each item closes the menu automatically after its `onClick` is called.
-
 ## Imperative API (Ref)
 
 Use a `ref` to control the player programmatically:
@@ -192,7 +329,7 @@ export default function App() {
       <button onClick={() => playerRef.current?.pause()}>Pause</button>
       <button onClick={() => playerRef.current?.seek(30)}>Jump to 30s</button>
       <button onClick={() => playerRef.current?.setVolume(0.5)}>50% volume</button>
-      <button onClick={() => playerRef.current?.setPlaybackRate(1.5)}>1.5× speed</button>
+      <button onClick={() => playerRef.current?.toggleAudioMode()}>Toggle Audio</button>
     </>
   );
 }
@@ -213,12 +350,13 @@ export default function App() {
 | `toggleFullscreen` | `() => Promise<void>` | Toggle fullscreen |
 | `togglePictureInPicture` | `() => Promise<void>` | Toggle Picture-in-Picture |
 | `toggleTheaterMode` | `() => void` | Toggle theater (wide) mode |
+| `toggleAudioMode` | `() => void` | Toggle audio-only mode |
 | `getState` | `() => PlayerState` | Snapshot of current player state |
 | `getVideoElement` | `() => HTMLVideoElement \| null` | Access the underlying `<video>` element |
 
 ## Theater Mode
 
-The player fires `onTheaterModeChange` when theater mode is toggled (via the `T` key, the control bar button, or `playerRef.current?.toggleTheaterMode()`). Wire it to your layout state to widen your container:
+The player fires `onTheaterModeChange` when theater mode is toggled. Wire it to your layout state to widen your container:
 
 ```tsx
 "use client";
@@ -237,24 +375,26 @@ export default function Page() {
       <VideoPlayer
         src="https://example.com/stream.m3u8"
         controls
-        onTheaterModeChange={(t) => setIsTheater(t)}
+        options={{
+          onTheaterModeChange: (t) => setIsTheater(t),
+        }}
       />
     </main>
   );
 }
 ```
 
-The player itself does not manage your page layout — it only notifies you so you can adapt your design.
-
 ## Subtitles
 
 ```tsx
 <VideoPlayer
   src="https://example.com/video.mp4"
-  subtitles={[
-    { id: "en", src: "/subs/en.vtt", label: "English", srclang: "en", default: true },
-    { id: "es", src: "/subs/es.vtt", label: "Español", srclang: "es" },
-  ]}
+  options={{
+    subtitles: [
+      { id: "en", src: "/subs/en.vtt", label: "English", srclang: "en", default: true },
+      { id: "es", src: "/subs/es.vtt", label: "Español", srclang: "es" },
+    ],
+  }}
 />
 ```
 
@@ -292,6 +432,7 @@ All types are exported from the package:
 ```ts
 import type {
   VideoPlayerProps,
+  VideoPlayerOptions,
   VideoPlayerRef,
   PlayerState,
   PlaybackRate,
@@ -300,13 +441,15 @@ import type {
   BufferedRange,
   VideoError,
   VideoErrorCode,
-  ThumbnailCue,
   ContextMenuItem,
   ControlBarItem,
 } from "react-helios";
 
+import { AUDIO_BANDWIDTH_THRESHOLDS, AUDIO_SWITCH_LEVELS } from "react-helios";
+
 // VTT utilities (useful for server-side pre-parsing or custom UIs)
 import { parseThumbnailVtt, findThumbnailCue } from "react-helios";
+import type { ThumbnailCue } from "react-helios";
 ```
 
 ### `PlayerState`
@@ -325,6 +468,7 @@ interface PlayerState {
   isFullscreen: boolean;
   isPictureInPicture: boolean;
   isTheaterMode: boolean;
+  isAudioMode: boolean;
   isLive: boolean;
   qualityLevels: HLSQualityLevel[];
   currentQualityLevel: number; // -1 = ABR auto
@@ -349,20 +493,6 @@ interface VideoError {
 }
 ```
 
-### `ThumbnailCue`
-
-```ts
-interface ThumbnailCue {
-  start: number; // seconds
-  end: number;   // seconds
-  url: string;   // absolute URL to the sprite image
-  x: number;     // pixel offset within sprite
-  y: number;
-  w: number;     // cell width in pixels
-  h: number;     // cell height in pixels
-}
-```
-
 ### `ControlBarItem`
 
 ```ts
@@ -384,9 +514,21 @@ interface ContextMenuItem {
 }
 ```
 
-## Utility Functions
+### `ThumbnailCue`
 
-The package exports a few helper utilities used internally, exposed for custom integrations:
+```ts
+interface ThumbnailCue {
+  start: number; // seconds
+  end: number;   // seconds
+  url: string;   // absolute URL to the sprite image
+  x: number;     // pixel offset within sprite
+  y: number;
+  w: number;     // cell width in pixels
+  h: number;     // cell height in pixels
+}
+```
+
+## Utility Functions
 
 ```ts
 import { formatTime, isHLSUrl, getMimeType } from "react-helios";
@@ -421,16 +563,18 @@ if (cue) {
 The player is architected to produce **zero React re-renders during playback**:
 
 - `timeupdate` and `progress` events are handled by direct DOM mutation (refs), not React state.
-- `ProgressBar` and `TimeDisplay` self-subscribe to the video element — the parent tree never re-renders on seek or time change.
+- `ProgressBar` and `TimeDisplay` self-subscribe to the active media element — the parent tree never re-renders on seek or time change.
+- `Controls` and `AudioModeOverlay` are wrapped in `React.memo` — they only re-render when their own props change, not when unrelated state (buffering, errors) updates.
 - VTT sprite thumbnails are looked up via binary search (O(log n)) and rendered via CSS `background-position` — no hidden `<video>` element, no canvas, no network requests per hover.
 - Buffered ranges are the only state that triggers a re-render (fires every few seconds during buffering, not 60× per second).
+- In audio mode the `<video>` element is **paused** — the browser stops decoding frames entirely. A lightweight `<audio>` element takes over with `preload="none"` (no network cost at startup). The `<audio>` element only loads its source the first time the user switches to audio mode.
 
 ## Project Structure
 
 ```
 react-helios/
 ├── src/                    # Library source
-│   ├── components/         # VideoPlayer, Controls, control elements
+│   ├── components/         # VideoPlayer, Controls, AudioModeOverlay, control elements
 │   ├── hooks/              # useVideoPlayer (state + HLS init)
 │   ├── lib/                # Types, HLS utilities, VTT parser, format helpers
 │   └── styles/             # CSS