@glitchlab/react-video-player 1.4.1 → 1.5.0

package/dist/index.d.ts

@@ -16,6 +16,26 @@ export declare interface AudioTrackInfo {
     lang?: string;
 }
 
+/**
+ * Chapter (cue marker) support. Chapters segment the timeline into named
+ * sections — useful for tutorials and long-form content. They can be supplied
+ * inline or as a WebVTT chapters file:
+ *
+ *   00:00:00.000 --> 00:02:30.000
+ *   Introduction
+ *
+ *   00:02:30.000 --> 00:10:00.000
+ *   Getting started
+ */
+export declare interface Chapter {
+    /** Chapter start time, in seconds. */
+    start: number;
+    /** Chapter end time, in seconds. */
+    end: number;
+    /** Human-readable chapter title. */
+    title: string;
+}
+
 declare type DeviceMode = "desktop" | "mobile";
 
 /**
@@ -37,6 +57,24 @@ export declare function parseYouTubeId(input: string): string | null;
 /** Extract a `t`/`start` timestamp (in seconds) from a YouTube URL, if present. */
 export declare function parseYouTubeStart(input: string): number | null;
 
+/** A single entry in a {@link VideoPlayerWrapperProps.playlist}. */
+export declare interface PlaylistItem {
+    /** Video source URL. `.m3u8` URLs are routed through hls.js automatically. */
+    src: string;
+    /** Poster image for this item. Falls back to the player-level `poster`. */
+    poster?: string;
+    /** Optional human-readable title for this item. */
+    title?: string;
+    /** Per-item WebVTT storyboard URL for seek-bar thumbnails. */
+    thumbnails?: string;
+    /** Per-item chapters (WebVTT URL or inline array). */
+    chapters?: string | Array<{
+        start: number;
+        end?: number;
+        title: string;
+    }>;
+}
+
 /**
  * A normalized quality-level descriptor for an HLS stream. `index` maps to a
  * `hls.js` level index; the special index `-1` represents "Auto" (adaptive
@@ -54,10 +92,26 @@ export declare interface QualityLevelInfo {
 export declare const ReactVideoPlayer: default_2.FC<ReactVideoPlayerProps>;
 
 export declare interface ReactVideoPlayerProps {
-    /** Video source URL. `.m3u8` URLs are routed through hls.js automatically. */
-    src: string;
+    /**
+     * Video source URL. `.m3u8` URLs are routed through hls.js automatically.
+     * Optional when `playlist` is supplied — the playlist drives the source.
+     */
+    src?: string;
     /** Poster image shown before playback. */
     poster?: string;
+    /**
+     * A list of videos to play in sequence. When provided, the player plays
+     * the item at `defaultIndex` and auto-advances on end. Prev/next buttons
+     * appear in the custom control bar. Each item can carry its own poster,
+     * thumbnails and chapters. Takes precedence over `src`.
+     */
+    playlist?: PlaylistItem[];
+    /** Index of the playlist item to start on. Defaults to `0`. */
+    defaultIndex?: number;
+    /** Auto-advance to the next playlist item when one ends. Defaults to `true`. */
+    autoAdvance?: boolean;
+    /** Called when the active playlist item changes. */
+    onPlaylistChange?: (index: number, item: PlaylistItem) => void;
     /** Show the desktop/mobile toggle pill in the top-left. Defaults to `true`. */
     showDeviceToggle?: boolean;
     /** Initial device mode. Defaults to `"desktop"`. */
@@ -104,6 +158,45 @@ export declare interface ReactVideoPlayerProps {
      * to avoid tearing down and rebuilding the HLS instance on each render.
      */
     hlsConfig?: HlsConfig;
+    /**
+     * URL of a WebVTT storyboard file for seek-bar thumbnail previews. Each cue
+     * points at a sprite region (`sprite.jpg#xywh=x,y,w,h`). Hovering the seek
+     * bar shows the matching frame. Only used with the custom control bar.
+     */
+    thumbnails?: string;
+    /**
+     * Timeline chapters. Either a URL of a WebVTT chapters file, or an inline
+     * array of `{ start, title }` (with optional `end`). Chapters add tick
+     * marks to the seek bar and the chapter title to the hover preview. Only
+     * used with the custom control bar.
+     */
+    chapters?: string | Array<{
+        start: number;
+        end?: number;
+        title: string;
+    }>;
+    /** Fired when playback starts or resumes. */
+    onPlay?: () => void;
+    /** Fired when playback is paused. */
+    onPause?: () => void;
+    /** Fired when the current video reaches its end. */
+    onEnded?: () => void;
+    /**
+     * Fired on every `timeupdate` (~4×/sec) with the current time and total
+     * duration, both in seconds. Use for progress bars or analytics.
+     */
+    onTimeUpdate?: (currentTime: number, duration: number) => void;
+    /** Fired after a seek completes, with the new time in seconds. */
+    onSeeked?: (currentTime: number) => void;
+    /** Fired when volume or mute state changes. */
+    onVolumeChange?: (volume: number, muted: boolean) => void;
+    /**
+     * Fired once each time watch progress crosses 25%, 50%, 75% and 100% of
+     * the video. Handy for completion analytics without your own timer.
+     */
+    onMilestone?: (percent: 25 | 50 | 75 | 100) => void;
+    /** Fired when the underlying media element reports an error. */
+    onError?: () => void;
     /**
      * Children rendered inside the underlying `<video>` element. Use this to
      * supply `<track>` elements for captions, subtitles, etc.
@@ -111,6 +204,37 @@ export declare interface ReactVideoPlayerProps {
     children?: default_2.ReactNode;
 }
 
+/**
+ * Parsing for WebVTT storyboard/thumbnail tracks — the format YouTube, Vimeo
+ * and most players use for seek-bar previews. Each cue maps a time range to a
+ * region of a sprite image:
+ *
+ *   00:00:00.000 --> 00:00:05.000
+ *   sprite.jpg#xywh=0,0,160,90
+ *
+ * The `#xywh=` fragment is optional. Without it, the whole image is used.
+ */
+export declare interface ThumbnailCue {
+    /** Cue start time, in seconds. */
+    start: number;
+    /** Cue end time, in seconds. */
+    end: number;
+    /** Absolute URL of the sprite (or standalone) image. */
+    url: string;
+    /** Crop region within the image, in pixels. */
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+
+/** A parsed thumbnail track plus a time → cue lookup. */
+export declare interface ThumbnailTrack {
+    cues: ThumbnailCue[];
+    /** Returns the cue covering `time`, or the nearest one. `null` if empty. */
+    cueAt(time: number): ThumbnailCue | null;
+}
+
 declare interface YouTubeEmbedOptions {
     /** Start playback immediately. Forces `mute` on, since browsers block sound-on autoplay. */
     autoPlay?: boolean;