react-helios 2.0.1 → 2.1.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, thumbnail preview, Picture-in-Picture, and full keyboard control.
+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.
 
 ## Installation
 
@@ -47,6 +47,42 @@ Pass any `.m3u8` URL — HLS.js is initialised automatically:
 
 On Safari the browser's native HLS engine is used. A **LIVE** badge and **GO LIVE** button appear automatically for live streams.
 
+## 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).
+
+```tsx
+<VideoPlayer
+  src="https://example.com/video.mp4"
+  thumbnailVtt="https://example.com/thumbs/storyboard.vtt"
+/>
+```
+
+### VTT format
+
+Each cue in the `.vtt` file maps a time range to a rectangular region inside a sprite image using the `#xywh=x,y,w,h` fragment:
+
+```
+WEBVTT
+
+00:00:00.000 --> 00:00:05.000
+https://example.com/thumbs/sprite.jpg#xywh=0,0,160,90
+
+00:00:05.000 --> 00:00:10.000
+https://example.com/thumbs/sprite.jpg#xywh=160,0,160,90
+
+00:00:10.000 --> 00:00:15.000
+https://example.com/thumbs/sprite.jpg#xywh=320,0,160,90
+```
+
+The player fetches the VTT file once, parses all cues, and uses CSS `background-position` to display the correct sprite cell during hover — **no additional network requests per hover**.
+
+To disable the preview entirely:
+
+```tsx
+<VideoPlayer src="..." enablePreview={false} />
+```
+
 ## Props
 
 | Prop | Type | Default | Description |
@@ -60,7 +96,8 @@ On Safari the browser's native HLS engine is used. A **LIVE** badge and **GO LIV
 | `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 |
 | `enableHLS` | `boolean` | `true` | Enable HLS.js for `.m3u8` sources |
-| `enablePreview` | `boolean` | `true` | Show thumbnail preview on progress bar hover (disabled automatically for HLS) |
+| `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 |
@@ -165,7 +202,11 @@ import type {
   BufferedRange,
   VideoError,
   VideoErrorCode,
+  ThumbnailCue,
 } from "react-helios";
+
+// VTT utilities (useful for server-side pre-parsing or custom UIs)
+import { parseThumbnailVtt, findThumbnailCue } from "react-helios";
 ```
 
 ### `PlayerState`
@@ -207,14 +248,37 @@ 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
+}
+```
+
+## Performance
+
+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.
+- 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).
+
 ## Project Structure
 
 ```
-react-video-player/
+react-helios/
 ├── src/                    # Library source
 │   ├── components/         # VideoPlayer, Controls, control elements
 │   ├── hooks/              # useVideoPlayer (state + HLS init)
-│   ├── lib/                # Types, HLS utilities, format helpers
+│   ├── lib/                # Types, HLS utilities, VTT parser, format helpers
 │   └── styles/             # CSS
 ├── examples/
 │   └── nextjs-demo/        # Standalone Next.js demo app

package/dist/index.d.mts

@@ -11,12 +11,12 @@ interface VideoError {
     code: VideoErrorCode;
     message: string;
 }
+/** Display name e.g. "1080p", "720p", "Auto" */
 interface HLSQualityLevel {
     id: number;
     height: number;
     width: number;
     bitrate: number;
-    /** Display name e.g. "1080p", "720p", "Auto" */
     name: string;
 }
 interface SubtitleTrack {
@@ -38,11 +38,8 @@ interface PlayerState {
     error: VideoError | null;
     isFullscreen: boolean;
     isPictureInPicture: boolean;
-    /** True when the stream is a live HLS stream (Infinity duration) */
     isLive: boolean;
-    /** Available HLS quality levels; empty for non-HLS sources */
     qualityLevels: HLSQualityLevel[];
-    /** Currently active quality level id; -1 = ABR auto */
     currentQualityLevel: number;
 }
 type PlaybackRate = 0.25 | 0.5 | 0.75 | 1 | 1.25 | 1.5 | 1.75 | 2;
@@ -51,12 +48,9 @@ interface VideoPlayerRef {
     pause: () => void;
     seek: (time: number) => void;
     setVolume: (volume: number) => void;
-    /** Toggle mute while remembering the pre-mute volume */
     toggleMute: () => void;
     setPlaybackRate: (rate: PlaybackRate) => void;
-    /** Set HLS quality level; pass -1 for automatic ABR */
     setQualityLevel: (level: number) => void;
-    /** Jump to the live edge of an HLS live stream */
     seekToLive: () => void;
     toggleFullscreen: () => Promise<void>;
     togglePictureInPicture: () => Promise<void>;
@@ -75,11 +69,26 @@ interface VideoPlayerProps {
     className?: string;
     enableHLS?: boolean;
     enablePreview?: boolean;
-    /** Additional hls.js configuration options */
+    /**
+     * 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>;
-    /** Subtitle / caption tracks */
     subtitles?: SubtitleTrack[];
-    /** crossorigin attribute for CORS-enabled preview thumbnails */
     crossOrigin?: "anonymous" | "use-credentials";
     onPlay?: () => void;
     onPause?: () => void;
@@ -93,14 +102,13 @@ interface VideoPlayerProps {
 declare const VideoPlayer: react__default.ForwardRefExoticComponent<VideoPlayerProps & react__default.RefAttributes<VideoPlayerRef>>;
 
 interface ControlsProps {
+    videoRef: react__default.RefObject<HTMLVideoElement | null>;
     playerRef: VideoPlayerRef;
-    /** Ref to the outer player container; used to scope keyboard shortcuts to the focused player */
     playerContainerRef: react__default.RefObject<HTMLElement | null>;
     playbackRates: PlaybackRate[];
     enablePreview: boolean;
+    thumbnailVtt?: string;
     isPlaying: boolean;
-    currentTime: number;
-    duration: number;
     volume: number;
     isMuted: boolean;
     playbackRate: number;
@@ -109,25 +117,17 @@ interface ControlsProps {
     isLive: boolean;
     qualityLevels: HLSQualityLevel[];
     currentQualityLevel: number;
-    bufferedRanges: BufferedRange[];
 }
-/**
- * Controls is intentionally NOT wrapped in React.memo here – it receives
- * currentTime which changes every tick, so memo wouldn't help at this level.
- * Instead, all its CHILDREN are memoized so they skip renders when their
- * specific props haven't changed.
- */
 declare const Controls: react__default.FC<ControlsProps>;
 
 interface TimeDisplayProps {
-    currentTime: number;
-    duration: number;
+    videoRef: React.RefObject<HTMLVideoElement | null>;
     isLive?: boolean;
 }
 /**
- * TimeDisplay re-renders every timeupdate tick (currentTime changes).
- * Wrapped in memo anyway so that if its specific props haven't changed
- * (e.g. when only volume changes) it skips the render.
+ * TimeDisplay subscribes directly to the video element's timeupdate and
+ * durationchange events, updating the DOM via refs. It never re-renders
+ * during playback — only when isLive changes (once per source change).
  */
 declare const TimeDisplay: react.NamedExoticComponent<TimeDisplayProps>;
 
@@ -139,22 +139,13 @@ interface SettingsMenuProps {
     currentQualityLevel?: number;
     onQualityChange?: (level: number) => void;
 }
-/**
- * SettingsMenu wrapped in React.memo.
- * playbackRate and qualityLevel rarely change → this component skips
- * almost all re-renders during normal playback.
- *
- * sortedLevels is memoized so the .sort() only runs when qualityLevels
- * actually changes (usually once after manifest is parsed).
- */
 declare const SettingsMenu: react.NamedExoticComponent<SettingsMenuProps>;
 
 interface ProgressBarProps {
+    videoRef: react__default.RefObject<HTMLVideoElement | null>;
     playerRef: VideoPlayerRef;
-    currentTime: number;
-    duration: number;
-    bufferedRanges: BufferedRange[];
     enablePreview?: boolean;
+    thumbnailVtt?: string;
 }
 declare const ProgressBar: react__default.FC<ProgressBarProps>;
 
@@ -164,11 +155,6 @@ interface VolumeControlProps {
     onVolumeChange: (volume: number) => void;
     onToggleMute: () => void;
 }
-/**
- * VolumeControl wrapped in React.memo.
- * volume and isMuted don't change during timeupdate → 0 re-renders during
- * normal playback when the user isn't touching volume controls.
- */
 declare const VolumeControl: react.NamedExoticComponent<VolumeControlProps>;
 
 interface PlayButtonProps {
@@ -185,12 +171,6 @@ interface PiPButtonProps {
     onClick: () => void;
     isPiP?: boolean;
 }
-/**
- * All button components are wrapped in React.memo.
- * They receive stable callback refs (useCallback in Controls), so they
- * only re-render when their specific props (isFullscreen, isPiP, etc.)
- * actually change – not on every timeupdate tick.
- */
 declare const PlayButton: react.NamedExoticComponent<PlayButtonProps>;
 declare const PauseButton: react.NamedExoticComponent<PauseButtonProps>;
 declare const FullscreenButton: react.NamedExoticComponent<FullscreenButtonProps>;
@@ -241,4 +221,35 @@ declare function isHLSUrl(url: string): boolean;
  */
 declare function getMimeType(url: string): string;
 
-export { type BufferedRange, index as ControlElements, Controls, type HLSQualityLevel, type PlaybackRate, type PlayerState, type SubtitleTrack, type VideoError, type VideoErrorCode, VideoPlayer, type VideoPlayerProps, type VideoPlayerRef, formatTime, getMimeType, isHLSUrl };
+interface ThumbnailCue {
+    start: number;
+    end: number;
+    /** Absolute URL to the sprite image */
+    url: string;
+    /** Pixel offset from the left of the sprite sheet */
+    x: number;
+    /** Pixel offset from the top of the sprite sheet */
+    y: number;
+    /** Width of a single thumbnail cell */
+    w: number;
+    /** Height of a single thumbnail cell */
+    h: number;
+}
+/**
+ * Parse a WebVTT thumbnail track into an array of cues.
+ *
+ * Supports the standard sprite-sheet format:
+ *   00:00:00.000 --> 00:00:05.000
+ *   https://cdn.example.com/thumbs/s0.jpg#xywh=0,0,160,90
+ *
+ * @param text    Raw VTT file text
+ * @param baseUrl VTT file URL — used to resolve relative image paths
+ */
+declare function parseThumbnailVtt(text: string, baseUrl?: string): ThumbnailCue[];
+/**
+ * Binary-search for the cue that covers `time` (seconds).
+ * Returns null if no cue covers that timestamp.
+ */
+declare function findThumbnailCue(cues: ThumbnailCue[], time: number): ThumbnailCue | null;
+
+export { type BufferedRange, 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 };

package/dist/index.d.ts

@@ -11,12 +11,12 @@ interface VideoError {
     code: VideoErrorCode;
     message: string;
 }
+/** Display name e.g. "1080p", "720p", "Auto" */
 interface HLSQualityLevel {
     id: number;
     height: number;
     width: number;
     bitrate: number;
-    /** Display name e.g. "1080p", "720p", "Auto" */
     name: string;
 }
 interface SubtitleTrack {
@@ -38,11 +38,8 @@ interface PlayerState {
     error: VideoError | null;
     isFullscreen: boolean;
     isPictureInPicture: boolean;
-    /** True when the stream is a live HLS stream (Infinity duration) */
     isLive: boolean;
-    /** Available HLS quality levels; empty for non-HLS sources */
     qualityLevels: HLSQualityLevel[];
-    /** Currently active quality level id; -1 = ABR auto */
     currentQualityLevel: number;
 }
 type PlaybackRate = 0.25 | 0.5 | 0.75 | 1 | 1.25 | 1.5 | 1.75 | 2;
@@ -51,12 +48,9 @@ interface VideoPlayerRef {
     pause: () => void;
     seek: (time: number) => void;
     setVolume: (volume: number) => void;
-    /** Toggle mute while remembering the pre-mute volume */
     toggleMute: () => void;
     setPlaybackRate: (rate: PlaybackRate) => void;
-    /** Set HLS quality level; pass -1 for automatic ABR */
     setQualityLevel: (level: number) => void;
-    /** Jump to the live edge of an HLS live stream */
     seekToLive: () => void;
     toggleFullscreen: () => Promise<void>;
     togglePictureInPicture: () => Promise<void>;
@@ -75,11 +69,26 @@ interface VideoPlayerProps {
     className?: string;
     enableHLS?: boolean;
     enablePreview?: boolean;
-    /** Additional hls.js configuration options */
+    /**
+     * 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>;
-    /** Subtitle / caption tracks */
     subtitles?: SubtitleTrack[];
-    /** crossorigin attribute for CORS-enabled preview thumbnails */
     crossOrigin?: "anonymous" | "use-credentials";
     onPlay?: () => void;
     onPause?: () => void;
@@ -93,14 +102,13 @@ interface VideoPlayerProps {
 declare const VideoPlayer: react__default.ForwardRefExoticComponent<VideoPlayerProps & react__default.RefAttributes<VideoPlayerRef>>;
 
 interface ControlsProps {
+    videoRef: react__default.RefObject<HTMLVideoElement | null>;
     playerRef: VideoPlayerRef;
-    /** Ref to the outer player container; used to scope keyboard shortcuts to the focused player */
     playerContainerRef: react__default.RefObject<HTMLElement | null>;
     playbackRates: PlaybackRate[];
     enablePreview: boolean;
+    thumbnailVtt?: string;
     isPlaying: boolean;
-    currentTime: number;
-    duration: number;
     volume: number;
     isMuted: boolean;
     playbackRate: number;
@@ -109,25 +117,17 @@ interface ControlsProps {
     isLive: boolean;
     qualityLevels: HLSQualityLevel[];
     currentQualityLevel: number;
-    bufferedRanges: BufferedRange[];
 }
-/**
- * Controls is intentionally NOT wrapped in React.memo here – it receives
- * currentTime which changes every tick, so memo wouldn't help at this level.
- * Instead, all its CHILDREN are memoized so they skip renders when their
- * specific props haven't changed.
- */
 declare const Controls: react__default.FC<ControlsProps>;
 
 interface TimeDisplayProps {
-    currentTime: number;
-    duration: number;
+    videoRef: React.RefObject<HTMLVideoElement | null>;
     isLive?: boolean;
 }
 /**
- * TimeDisplay re-renders every timeupdate tick (currentTime changes).
- * Wrapped in memo anyway so that if its specific props haven't changed
- * (e.g. when only volume changes) it skips the render.
+ * TimeDisplay subscribes directly to the video element's timeupdate and
+ * durationchange events, updating the DOM via refs. It never re-renders
+ * during playback — only when isLive changes (once per source change).
  */
 declare const TimeDisplay: react.NamedExoticComponent<TimeDisplayProps>;
 
@@ -139,22 +139,13 @@ interface SettingsMenuProps {
     currentQualityLevel?: number;
     onQualityChange?: (level: number) => void;
 }
-/**
- * SettingsMenu wrapped in React.memo.
- * playbackRate and qualityLevel rarely change → this component skips
- * almost all re-renders during normal playback.
- *
- * sortedLevels is memoized so the .sort() only runs when qualityLevels
- * actually changes (usually once after manifest is parsed).
- */
 declare const SettingsMenu: react.NamedExoticComponent<SettingsMenuProps>;
 
 interface ProgressBarProps {
+    videoRef: react__default.RefObject<HTMLVideoElement | null>;
     playerRef: VideoPlayerRef;
-    currentTime: number;
-    duration: number;
-    bufferedRanges: BufferedRange[];
     enablePreview?: boolean;
+    thumbnailVtt?: string;
 }
 declare const ProgressBar: react__default.FC<ProgressBarProps>;
 
@@ -164,11 +155,6 @@ interface VolumeControlProps {
     onVolumeChange: (volume: number) => void;
     onToggleMute: () => void;
 }
-/**
- * VolumeControl wrapped in React.memo.
- * volume and isMuted don't change during timeupdate → 0 re-renders during
- * normal playback when the user isn't touching volume controls.
- */
 declare const VolumeControl: react.NamedExoticComponent<VolumeControlProps>;
 
 interface PlayButtonProps {
@@ -185,12 +171,6 @@ interface PiPButtonProps {
     onClick: () => void;
     isPiP?: boolean;
 }
-/**
- * All button components are wrapped in React.memo.
- * They receive stable callback refs (useCallback in Controls), so they
- * only re-render when their specific props (isFullscreen, isPiP, etc.)
- * actually change – not on every timeupdate tick.
- */
 declare const PlayButton: react.NamedExoticComponent<PlayButtonProps>;
 declare const PauseButton: react.NamedExoticComponent<PauseButtonProps>;
 declare const FullscreenButton: react.NamedExoticComponent<FullscreenButtonProps>;
@@ -241,4 +221,35 @@ declare function isHLSUrl(url: string): boolean;
  */
 declare function getMimeType(url: string): string;
 
-export { type BufferedRange, index as ControlElements, Controls, type HLSQualityLevel, type PlaybackRate, type PlayerState, type SubtitleTrack, type VideoError, type VideoErrorCode, VideoPlayer, type VideoPlayerProps, type VideoPlayerRef, formatTime, getMimeType, isHLSUrl };
+interface ThumbnailCue {
+    start: number;
+    end: number;
+    /** Absolute URL to the sprite image */
+    url: string;
+    /** Pixel offset from the left of the sprite sheet */
+    x: number;
+    /** Pixel offset from the top of the sprite sheet */
+    y: number;
+    /** Width of a single thumbnail cell */
+    w: number;
+    /** Height of a single thumbnail cell */
+    h: number;
+}
+/**
+ * Parse a WebVTT thumbnail track into an array of cues.
+ *
+ * Supports the standard sprite-sheet format:
+ *   00:00:00.000 --> 00:00:05.000
+ *   https://cdn.example.com/thumbs/s0.jpg#xywh=0,0,160,90
+ *
+ * @param text    Raw VTT file text
+ * @param baseUrl VTT file URL — used to resolve relative image paths
+ */
+declare function parseThumbnailVtt(text: string, baseUrl?: string): ThumbnailCue[];
+/**
+ * Binary-search for the cue that covers `time` (seconds).
+ * Returns null if no cue covers that timestamp.
+ */
+declare function findThumbnailCue(cues: ThumbnailCue[], time: number): ThumbnailCue | null;
+
+export { type BufferedRange, 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 };