react-helios 2.4.0 → 2.7.0

package/dist/index.d.mts

@@ -5,30 +5,57 @@ import { HlsConfig } from 'hls.js';
 /**
  * Preset bandwidth thresholds (Kbps) for automatic audio mode switching.
  *
- * | Preset    | Kbps | Typical connection      |
- * |-----------|------|-------------------------|
- * | EXTREME   |  100 | 2G / Edge               |
- * | POOR      |  300 | Slow 3G  ← **default**  |
- * | FAIR      |  700 | 3G                      |
- * | GOOD      | 1500 | 4G / Wi-Fi              |
+ * | Preset    | Kbps | Typical connection             |
+ * |-----------|------|--------------------------------|
+ * | EXTREME   |  100 | 2G / Edge                      |
+ * | POOR      |  300 | Slow 3G                        |
+ * | FAIR      |  800 | Marginal 3G ← **recommended**  |
+ * | GOOD      | 1500 | Weak 4G / congested Wi-Fi      |
  *
  * Pass any of these (or a custom number) as `audioBandwidthThreshold`.
- * Set to `0` to disable automatic switching entirely.
+ * Set to `0` to disable bandwidth-based switching entirely.
  *
  * @example
  * import { AUDIO_BANDWIDTH_THRESHOLDS } from "react-helios";
- * <VideoPlayer audioBandwidthThreshold={AUDIO_BANDWIDTH_THRESHOLDS.FAIR} ... />
+ * <VideoPlayer options={{ audioBandwidthThreshold: AUDIO_BANDWIDTH_THRESHOLDS.FAIR }} />
  */
 declare const AUDIO_BANDWIDTH_THRESHOLDS: {
     /** < 100 Kbps — very poor, 2G / Edge */
     readonly EXTREME: 100;
-    /** < 300 Kbps — poor, slow 3G (default) */
+    /** < 300 Kbps — poor, slow 3G */
     readonly POOR: 300;
-    /** < 700 Kbps — fair, 3G */
-    readonly FAIR: 700;
-    /** < 1500 Kbps — decent, 4G / Wi-Fi */
+    /** < 800 Kbps — marginal 3G ← **recommended default** */
+    readonly FAIR: 800;
+    /** < 1500 Kbps — weak 4G / congested Wi-Fi */
     readonly GOOD: 1500;
 };
+/**
+ * Preset HLS quality level indices for automatic audio mode switching.
+ *
+ * When HLS.js drops to this level or below (due to poor bandwidth), the player
+ * automatically switches to audio mode. Level `0` is always the lowest quality
+ * available in the manifest.
+ *
+ * | Preset         | Value | Meaning                                       |
+ * |----------------|-------|-----------------------------------------------|
+ * | LOWEST         |   0   | Switch when at the very lowest quality ← **recommended** |
+ * | SECOND_LOWEST  |   1   | Switch one level above the lowest             |
+ * | DISABLED       |  -1   | Disable level-based switching entirely        |
+ *
+ * Works alongside `audioBandwidthThreshold` — whichever fires first wins.
+ *
+ * @example
+ * import { AUDIO_SWITCH_LEVELS } from "react-helios";
+ * <VideoPlayer options={{ audioModeSwitchLevel: AUDIO_SWITCH_LEVELS.LOWEST }} />
+ */
+declare const AUDIO_SWITCH_LEVELS: {
+    /** Switch when HLS.js is at the lowest available quality (recommended default). */
+    readonly LOWEST: 0;
+    /** Switch when HLS.js drops to the second-lowest quality. */
+    readonly SECOND_LOWEST: 1;
+    /** Disable level-based auto-switching. */
+    readonly DISABLED: -1;
+};
 interface BufferedRange {
     start: number;
     end: number;
@@ -101,83 +128,77 @@ interface ControlBarItem {
     title?: string;
     onClick: () => void;
 }
-interface VideoPlayerProps {
-    src: string;
-    poster?: string;
+interface VideoPlayerOptions {
     autoplay?: boolean;
     muted?: boolean;
     loop?: boolean;
-    controls?: boolean;
     preload?: "none" | "metadata" | "auto";
     playbackRates?: PlaybackRate[];
-    className?: string;
     enableHLS?: boolean;
+    hlsConfig?: Partial<HlsConfig>;
     enablePreview?: boolean;
-    /**
-     * URL to a WebVTT thumbnail track for sprite-sheet preview on the progress bar.
-     *
-     * The VTT file should map time ranges to sprite-sheet coordinates using the
-     * standard `#xywh=x,y,w,h` fragment format:
-     *
-     * ```
-     * WEBVTT
-     *
-     * 00:00:00.000 --> 00:00:05.000
-     * https://cdn.example.com/thumbs/storyboard0.jpg#xywh=0,0,160,90
-     * ```
-     *
-     * When provided, hovering the progress bar shows a thumbnail instead of
-     * requiring a second video decode. If omitted, only the timestamp tooltip
-     * is shown.
-     */
     thumbnailVtt?: string;
-    hlsConfig?: Partial<HlsConfig>;
+    autoHideControls?: boolean;
     subtitles?: SubtitleTrack[];
     crossOrigin?: "anonymous" | "use-credentials";
-    onPlay?: () => void;
-    onPause?: () => void;
-    onEnded?: () => void;
-    onError?: (error: VideoError) => void;
-    onTimeUpdate?: (time: number) => void;
-    onDurationChange?: (duration: number) => void;
-    onBuffering?: (isBuffering: boolean) => void;
-    onTheaterModeChange?: (isTheater: boolean) => void;
-    /**
-     * Image URL or ReactNode shown as artwork in audio mode.
-     * Priority: `poster` prop → `logo` string/ReactNode → waveform-only.
-     * If a string URL is provided the image is rendered white-normalised (filter invert)
-     * so it stands out on the dark background.
-     */
     logo?: string | ReactNode;
-    /**
-     * Show the headphones / audio-mode toggle button in the control bar.
-     * @default true
-     */
+    audioSrc?: string;
     showAudioButton?: boolean;
+    audioModeIcon?: ReactNode;
+    videoModeIcon?: ReactNode;
     /**
-     * Start the player in audio-only mode on mount.
-     * @default false
+     * Custom content shown in audio mode when no `poster` is provided.
+     * Replaces the default animated-gradient + waveform fallback entirely.
+     * The `logo` prop is still rendered on top of this if also provided.
      */
+    audioModeFallback?: ReactNode;
+    /** Label shown next to the icon when in video mode (click → switches to audio). Default: "Audio" */
+    audioModeLabel?: string;
+    /** Label shown next to the icon when in audio mode (click → switches to video). Default: "Video" */
+    videoModeLabel?: string;
     defaultAudioMode?: boolean;
     /**
-     * Bandwidth threshold in **Kbps**. When the measured download speed falls below
-     * this value the player automatically switches to audio mode.
-     * Use the exported `AUDIO_BANDWIDTH_THRESHOLDS` presets for convenience.
-     * Set to `0` to disable automatic switching.
-     * Only applies to HLS streams (where hls.js measures real segment bandwidth).
-     * @default 300  (AUDIO_BANDWIDTH_THRESHOLDS.POOR)
+     * Kbps — switch to audio mode when rolling average bandwidth drops below this value.
+     * `0` disables bandwidth-based switching. Default: `300` (slow 3G).
+     * Works alongside `audioModeSwitchLevel` — whichever fires first wins.
      */
     audioBandwidthThreshold?: number;
-    /** Fired whenever audio mode is toggled — either automatically or by the user. */
+    /**
+     * HLS quality level index — switch to audio mode when HLS.js drops to this level or below.
+     * `0` = lowest quality (recommended default). `-1` disables level-based switching.
+     * Works alongside `audioBandwidthThreshold` — whichever fires first wins.
+     */
+    audioModeSwitchLevel?: number;
+    /**
+     * Milliseconds between automatic recovery probes while in auto-switched audio mode.
+     * The player briefly resumes video loading to sample bandwidth, then switches back
+     * to video if conditions have improved. Default: `30000` (30 seconds).
+     */
+    audioModeRecoveryInterval?: number;
+    onPlay?: () => void;
+    onPause?: () => void;
+    onEnded?: () => void;
+    onError?: (error: VideoError) => void;
+    onTimeUpdate?: (time: number) => void;
+    onDurationChange?: (duration: number) => void;
+    onBuffering?: (isBuffering: boolean) => void;
+    onTheaterModeChange?: (isTheater: boolean) => void;
     onAudioModeChange?: (isAudio: boolean) => void;
     contextMenuItems?: ContextMenuItem[];
     controlBarItems?: ControlBarItem[];
 }
+interface VideoPlayerProps {
+    src: string;
+    poster?: string;
+    className?: string;
+    controls?: boolean;
+    options?: VideoPlayerOptions;
+}
 
 declare const VideoPlayer: react__default.ForwardRefExoticComponent<VideoPlayerProps & react__default.RefAttributes<VideoPlayerRef>>;
 
 interface ControlsProps {
-    videoRef: react__default.RefObject<HTMLVideoElement | null>;
+    videoRef: react__default.RefObject<HTMLMediaElement | null>;
     playerRef: VideoPlayerRef;
     playerContainerRef: react__default.RefObject<HTMLElement | null>;
     playbackRates: PlaybackRate[];
@@ -192,15 +213,20 @@ interface ControlsProps {
     isTheaterMode: boolean;
     isAudioMode: boolean;
     showAudioButton: boolean;
+    audioModeIcon?: ReactNode;
+    videoModeIcon?: ReactNode;
+    audioModeLabel?: string;
+    videoModeLabel?: string;
     isLive: boolean;
     qualityLevels: HLSQualityLevel[];
     currentQualityLevel: number;
     controlBarItems?: ControlBarItem[];
+    autoHideControls: boolean;
 }
-declare const Controls: react__default.FC<ControlsProps>;
+declare const Controls: react__default.NamedExoticComponent<ControlsProps>;
 
 interface TimeDisplayProps {
-    videoRef: React.RefObject<HTMLVideoElement | null>;
+    videoRef: React.RefObject<HTMLMediaElement | null>;
     isLive?: boolean;
 }
 /**
@@ -221,7 +247,7 @@ interface SettingsMenuProps {
 declare const SettingsMenu: react.NamedExoticComponent<SettingsMenuProps>;
 
 interface ProgressBarProps {
-    videoRef: react__default.RefObject<HTMLVideoElement | null>;
+    videoRef: react__default.RefObject<HTMLMediaElement | null>;
     playerRef: VideoPlayerRef;
     enablePreview?: boolean;
     thumbnailVtt?: string;
@@ -339,4 +365,4 @@ declare function parseThumbnailVtt(text: string, baseUrl?: string): ThumbnailCue
  */
 declare function findThumbnailCue(cues: ThumbnailCue[], time: number): ThumbnailCue | null;
 
-export { AUDIO_BANDWIDTH_THRESHOLDS, type BufferedRange, type ContextMenuItem, type ControlBarItem, index as ControlElements, Controls, type HLSQualityLevel, type PlaybackRate, type PlayerState, type SubtitleTrack, type ThumbnailCue, type VideoError, type VideoErrorCode, VideoPlayer, type VideoPlayerProps, type VideoPlayerRef, findThumbnailCue, formatTime, getMimeType, isHLSUrl, parseThumbnailVtt };
+export { AUDIO_BANDWIDTH_THRESHOLDS, AUDIO_SWITCH_LEVELS, type BufferedRange, type ContextMenuItem, type ControlBarItem, index as ControlElements, Controls, type HLSQualityLevel, type PlaybackRate, type PlayerState, type SubtitleTrack, type ThumbnailCue, type VideoError, type VideoErrorCode, VideoPlayer, type VideoPlayerOptions, type VideoPlayerProps, type VideoPlayerRef, findThumbnailCue, formatTime, getMimeType, isHLSUrl, parseThumbnailVtt };

package/dist/index.d.ts

@@ -5,30 +5,57 @@ import { HlsConfig } from 'hls.js';
 /**
  * Preset bandwidth thresholds (Kbps) for automatic audio mode switching.
  *
- * | Preset    | Kbps | Typical connection      |
- * |-----------|------|-------------------------|
- * | EXTREME   |  100 | 2G / Edge               |
- * | POOR      |  300 | Slow 3G  ← **default**  |
- * | FAIR      |  700 | 3G                      |
- * | GOOD      | 1500 | 4G / Wi-Fi              |
+ * | Preset    | Kbps | Typical connection             |
+ * |-----------|------|--------------------------------|
+ * | EXTREME   |  100 | 2G / Edge                      |
+ * | POOR      |  300 | Slow 3G                        |
+ * | FAIR      |  800 | Marginal 3G ← **recommended**  |
+ * | GOOD      | 1500 | Weak 4G / congested Wi-Fi      |
  *
  * Pass any of these (or a custom number) as `audioBandwidthThreshold`.
- * Set to `0` to disable automatic switching entirely.
+ * Set to `0` to disable bandwidth-based switching entirely.
  *
  * @example
  * import { AUDIO_BANDWIDTH_THRESHOLDS } from "react-helios";
- * <VideoPlayer audioBandwidthThreshold={AUDIO_BANDWIDTH_THRESHOLDS.FAIR} ... />
+ * <VideoPlayer options={{ audioBandwidthThreshold: AUDIO_BANDWIDTH_THRESHOLDS.FAIR }} />
  */
 declare const AUDIO_BANDWIDTH_THRESHOLDS: {
     /** < 100 Kbps — very poor, 2G / Edge */
     readonly EXTREME: 100;
-    /** < 300 Kbps — poor, slow 3G (default) */
+    /** < 300 Kbps — poor, slow 3G */
     readonly POOR: 300;
-    /** < 700 Kbps — fair, 3G */
-    readonly FAIR: 700;
-    /** < 1500 Kbps — decent, 4G / Wi-Fi */
+    /** < 800 Kbps — marginal 3G ← **recommended default** */
+    readonly FAIR: 800;
+    /** < 1500 Kbps — weak 4G / congested Wi-Fi */
     readonly GOOD: 1500;
 };
+/**
+ * Preset HLS quality level indices for automatic audio mode switching.
+ *
+ * When HLS.js drops to this level or below (due to poor bandwidth), the player
+ * automatically switches to audio mode. Level `0` is always the lowest quality
+ * available in the manifest.
+ *
+ * | Preset         | Value | Meaning                                       |
+ * |----------------|-------|-----------------------------------------------|
+ * | LOWEST         |   0   | Switch when at the very lowest quality ← **recommended** |
+ * | SECOND_LOWEST  |   1   | Switch one level above the lowest             |
+ * | DISABLED       |  -1   | Disable level-based switching entirely        |
+ *
+ * Works alongside `audioBandwidthThreshold` — whichever fires first wins.
+ *
+ * @example
+ * import { AUDIO_SWITCH_LEVELS } from "react-helios";
+ * <VideoPlayer options={{ audioModeSwitchLevel: AUDIO_SWITCH_LEVELS.LOWEST }} />
+ */
+declare const AUDIO_SWITCH_LEVELS: {
+    /** Switch when HLS.js is at the lowest available quality (recommended default). */
+    readonly LOWEST: 0;
+    /** Switch when HLS.js drops to the second-lowest quality. */
+    readonly SECOND_LOWEST: 1;
+    /** Disable level-based auto-switching. */
+    readonly DISABLED: -1;
+};
 interface BufferedRange {
     start: number;
     end: number;
@@ -101,83 +128,77 @@ interface ControlBarItem {
     title?: string;
     onClick: () => void;
 }
-interface VideoPlayerProps {
-    src: string;
-    poster?: string;
+interface VideoPlayerOptions {
     autoplay?: boolean;
     muted?: boolean;
     loop?: boolean;
-    controls?: boolean;
     preload?: "none" | "metadata" | "auto";
     playbackRates?: PlaybackRate[];
-    className?: string;
     enableHLS?: boolean;
+    hlsConfig?: Partial<HlsConfig>;
     enablePreview?: boolean;
-    /**
-     * URL to a WebVTT thumbnail track for sprite-sheet preview on the progress bar.
-     *
-     * The VTT file should map time ranges to sprite-sheet coordinates using the
-     * standard `#xywh=x,y,w,h` fragment format:
-     *
-     * ```
-     * WEBVTT
-     *
-     * 00:00:00.000 --> 00:00:05.000
-     * https://cdn.example.com/thumbs/storyboard0.jpg#xywh=0,0,160,90
-     * ```
-     *
-     * When provided, hovering the progress bar shows a thumbnail instead of
-     * requiring a second video decode. If omitted, only the timestamp tooltip
-     * is shown.
-     */
     thumbnailVtt?: string;
-    hlsConfig?: Partial<HlsConfig>;
+    autoHideControls?: boolean;
     subtitles?: SubtitleTrack[];
     crossOrigin?: "anonymous" | "use-credentials";
-    onPlay?: () => void;
-    onPause?: () => void;
-    onEnded?: () => void;
-    onError?: (error: VideoError) => void;
-    onTimeUpdate?: (time: number) => void;
-    onDurationChange?: (duration: number) => void;
-    onBuffering?: (isBuffering: boolean) => void;
-    onTheaterModeChange?: (isTheater: boolean) => void;
-    /**
-     * Image URL or ReactNode shown as artwork in audio mode.
-     * Priority: `poster` prop → `logo` string/ReactNode → waveform-only.
-     * If a string URL is provided the image is rendered white-normalised (filter invert)
-     * so it stands out on the dark background.
-     */
     logo?: string | ReactNode;
-    /**
-     * Show the headphones / audio-mode toggle button in the control bar.
-     * @default true
-     */
+    audioSrc?: string;
     showAudioButton?: boolean;
+    audioModeIcon?: ReactNode;
+    videoModeIcon?: ReactNode;
     /**
-     * Start the player in audio-only mode on mount.
-     * @default false
+     * Custom content shown in audio mode when no `poster` is provided.
+     * Replaces the default animated-gradient + waveform fallback entirely.
+     * The `logo` prop is still rendered on top of this if also provided.
      */
+    audioModeFallback?: ReactNode;
+    /** Label shown next to the icon when in video mode (click → switches to audio). Default: "Audio" */
+    audioModeLabel?: string;
+    /** Label shown next to the icon when in audio mode (click → switches to video). Default: "Video" */
+    videoModeLabel?: string;
     defaultAudioMode?: boolean;
     /**
-     * Bandwidth threshold in **Kbps**. When the measured download speed falls below
-     * this value the player automatically switches to audio mode.
-     * Use the exported `AUDIO_BANDWIDTH_THRESHOLDS` presets for convenience.
-     * Set to `0` to disable automatic switching.
-     * Only applies to HLS streams (where hls.js measures real segment bandwidth).
-     * @default 300  (AUDIO_BANDWIDTH_THRESHOLDS.POOR)
+     * Kbps — switch to audio mode when rolling average bandwidth drops below this value.
+     * `0` disables bandwidth-based switching. Default: `300` (slow 3G).
+     * Works alongside `audioModeSwitchLevel` — whichever fires first wins.
      */
     audioBandwidthThreshold?: number;
-    /** Fired whenever audio mode is toggled — either automatically or by the user. */
+    /**
+     * HLS quality level index — switch to audio mode when HLS.js drops to this level or below.
+     * `0` = lowest quality (recommended default). `-1` disables level-based switching.
+     * Works alongside `audioBandwidthThreshold` — whichever fires first wins.
+     */
+    audioModeSwitchLevel?: number;
+    /**
+     * Milliseconds between automatic recovery probes while in auto-switched audio mode.
+     * The player briefly resumes video loading to sample bandwidth, then switches back
+     * to video if conditions have improved. Default: `30000` (30 seconds).
+     */
+    audioModeRecoveryInterval?: number;
+    onPlay?: () => void;
+    onPause?: () => void;
+    onEnded?: () => void;
+    onError?: (error: VideoError) => void;
+    onTimeUpdate?: (time: number) => void;
+    onDurationChange?: (duration: number) => void;
+    onBuffering?: (isBuffering: boolean) => void;
+    onTheaterModeChange?: (isTheater: boolean) => void;
     onAudioModeChange?: (isAudio: boolean) => void;
     contextMenuItems?: ContextMenuItem[];
     controlBarItems?: ControlBarItem[];
 }
+interface VideoPlayerProps {
+    src: string;
+    poster?: string;
+    className?: string;
+    controls?: boolean;
+    options?: VideoPlayerOptions;
+}
 
 declare const VideoPlayer: react__default.ForwardRefExoticComponent<VideoPlayerProps & react__default.RefAttributes<VideoPlayerRef>>;
 
 interface ControlsProps {
-    videoRef: react__default.RefObject<HTMLVideoElement | null>;
+    videoRef: react__default.RefObject<HTMLMediaElement | null>;
     playerRef: VideoPlayerRef;
     playerContainerRef: react__default.RefObject<HTMLElement | null>;
     playbackRates: PlaybackRate[];
@@ -192,15 +213,20 @@ interface ControlsProps {
     isTheaterMode: boolean;
     isAudioMode: boolean;
     showAudioButton: boolean;
+    audioModeIcon?: ReactNode;
+    videoModeIcon?: ReactNode;
+    audioModeLabel?: string;
+    videoModeLabel?: string;
     isLive: boolean;
     qualityLevels: HLSQualityLevel[];
     currentQualityLevel: number;
     controlBarItems?: ControlBarItem[];
+    autoHideControls: boolean;
 }
-declare const Controls: react__default.FC<ControlsProps>;
+declare const Controls: react__default.NamedExoticComponent<ControlsProps>;
 
 interface TimeDisplayProps {
-    videoRef: React.RefObject<HTMLVideoElement | null>;
+    videoRef: React.RefObject<HTMLMediaElement | null>;
     isLive?: boolean;
 }
 /**
@@ -221,7 +247,7 @@ interface SettingsMenuProps {
 declare const SettingsMenu: react.NamedExoticComponent<SettingsMenuProps>;
 
 interface ProgressBarProps {
-    videoRef: react__default.RefObject<HTMLVideoElement | null>;
+    videoRef: react__default.RefObject<HTMLMediaElement | null>;
     playerRef: VideoPlayerRef;
     enablePreview?: boolean;
     thumbnailVtt?: string;
@@ -339,4 +365,4 @@ declare function parseThumbnailVtt(text: string, baseUrl?: string): ThumbnailCue
  */
 declare function findThumbnailCue(cues: ThumbnailCue[], time: number): ThumbnailCue | null;
 
-export { AUDIO_BANDWIDTH_THRESHOLDS, type BufferedRange, type ContextMenuItem, type ControlBarItem, index as ControlElements, Controls, type HLSQualityLevel, type PlaybackRate, type PlayerState, type SubtitleTrack, type ThumbnailCue, type VideoError, type VideoErrorCode, VideoPlayer, type VideoPlayerProps, type VideoPlayerRef, findThumbnailCue, formatTime, getMimeType, isHLSUrl, parseThumbnailVtt };
+export { AUDIO_BANDWIDTH_THRESHOLDS, AUDIO_SWITCH_LEVELS, type BufferedRange, type ContextMenuItem, type ControlBarItem, index as ControlElements, Controls, type HLSQualityLevel, type PlaybackRate, type PlayerState, type SubtitleTrack, type ThumbnailCue, type VideoError, type VideoErrorCode, VideoPlayer, type VideoPlayerOptions, type VideoPlayerProps, type VideoPlayerRef, findThumbnailCue, formatTime, getMimeType, isHLSUrl, parseThumbnailVtt };