@oddin-gg/havik-player 2.23.4 → 2.25.0

package/dist/index.d.cts

@@ -260,6 +260,16 @@ export declare interface CreatePlayerOptions {
      * clear streams, and when `hlsConfig.fLoader` is set.
      */
     mediaDuringKey?: boolean;
+    /**
+     * Live LL-HLS (hls.js engine): fetch the part each playlist's
+     * EXT-X-PRELOAD-HINT names as soon as the playlist arrives, instead of
+     * waiting for the next playlist to list it. The origin and CDNs hold that
+     * request until the part exists, so a viewer far from the origin saves
+     * about one round trip per part. Bytes reach hls.js only when it asks for
+     * the part; a hinted part it never asks for is dropped. Default: false.
+     * Ignored when `hlsConfig.fLoader` is set.
+     */
+    preloadHints?: boolean;
     /** Force an engine; 'auto' uses the native engine for FairPlay on Apple
      *  browsers and for every stream on iPhone/iPad, hls.js elsewhere wherever
      *  supported, and falls back to native HLS. Default: 'auto'. */
@@ -311,6 +321,16 @@ export declare interface CreatePlayerOptions {
     interruptedMessage?: string;
     /** Message on the fatal-error card. Default: the error's own message. */
     errorMessage?: string;
+    /**
+     * Message on the card shown while the browser reports no network
+     * (`navigator.onLine === false` — wifi off, airplane mode, cable out).
+     * Default: "No internet connection — waiting to reconnect". The card
+     * replaces the error and reconnecting cards for as long as the browser
+     * says offline, and carries no Retry button: nothing can succeed without a
+     * route. Playback resumes on its own when the browser fires `online` (see
+     * the `offline`/`online` events).
+     */
+    offlineMessage?: string;
     /**
      * Turn on hls.js's internal console logging — segment/part scheduling, ABR
      * switches, and EME key-session + license traffic. Default: false.
@@ -1092,6 +1112,14 @@ export declare interface PlaybackStats {
 export declare interface Player {
     readonly state: PlayerState;
     readonly descriptor: StreamDescriptor | null;
+    /**
+     * True while the browser reports no network (`navigator.onLine === false`).
+     * Reliable in that direction only: `false` means "not known to be offline",
+     * which a captive portal or a dead upstream still satisfies. Orthogonal to
+     * `state` — a player can be 'buffering' or 'error' with this true, and the
+     * control bar shows the offline card over either while it is.
+     */
+    readonly offline: boolean;
     /** Why the stream ended, when the server said so; null otherwise. Cleared
      *  when fresh playback commits (including a rejoin). See EndedReason. */
     readonly endedReason: EndedReason | null;
@@ -1144,7 +1172,7 @@ export declare interface Player {
     destroy(): void;
 }
 
-export declare type PlayerEvent = 'ready' | 'waiting' | 'playing' | 'buffering' | 'paused' | 'ended' | 'error' | 'warning' | 'autoplayblocked' | 'qualitychange' | 'audiotrackchange' | 'texttrackchange' | 'pipchange' | 'latencytargetchange' | 'stats' | 'statechange';
+export declare type PlayerEvent = 'ready' | 'waiting' | 'playing' | 'buffering' | 'paused' | 'ended' | 'error' | 'warning' | 'autoplayblocked' | 'qualitychange' | 'audiotrackchange' | 'texttrackchange' | 'pipchange' | 'latencytargetchange' | 'stats' | 'statechange' | 'offline' | 'online';
 
 export declare interface PlayerEventMap {
     ready: void;
@@ -1183,6 +1211,21 @@ export declare interface PlayerEventMap {
     latencytargetchange: LiveTargetChange;
     stats: PlaybackStats;
     statechange: PlayerState;
+    /**
+     * The browser reported it lost its network (`window` `offline`). The
+     * player state is unchanged — what follows depends on where the loss
+     * lands: the hls.js engine parks its loader on the next failed fetch, a
+     * resolve in flight fails NETWORK — and `offline` is the one signal that
+     * the cause is the viewer's link. See {@link Player.offline}.
+     */
+    offline: void;
+    /**
+     * The browser reported its network is back (`window` `online`). The
+     * player resumes on its own: a parked hls.js loader restarts at once, and
+     * a fatal error that happened while offline (or any NETWORK error) is
+     * retried — the same re-resolve as `retry()`.
+     */
+    online: void;
 }
 
 export declare type PlayerState = 'idle' | 'waiting' | 'loading' | 'playing' | 'buffering' | 'paused' | 'ended' | 'error';

package/dist/index.d.ts

@@ -260,6 +260,16 @@ export declare interface CreatePlayerOptions {
      * clear streams, and when `hlsConfig.fLoader` is set.
      */
     mediaDuringKey?: boolean;
+    /**
+     * Live LL-HLS (hls.js engine): fetch the part each playlist's
+     * EXT-X-PRELOAD-HINT names as soon as the playlist arrives, instead of
+     * waiting for the next playlist to list it. The origin and CDNs hold that
+     * request until the part exists, so a viewer far from the origin saves
+     * about one round trip per part. Bytes reach hls.js only when it asks for
+     * the part; a hinted part it never asks for is dropped. Default: false.
+     * Ignored when `hlsConfig.fLoader` is set.
+     */
+    preloadHints?: boolean;
     /** Force an engine; 'auto' uses the native engine for FairPlay on Apple
      *  browsers and for every stream on iPhone/iPad, hls.js elsewhere wherever
      *  supported, and falls back to native HLS. Default: 'auto'. */
@@ -311,6 +321,16 @@ export declare interface CreatePlayerOptions {
     interruptedMessage?: string;
     /** Message on the fatal-error card. Default: the error's own message. */
     errorMessage?: string;
+    /**
+     * Message on the card shown while the browser reports no network
+     * (`navigator.onLine === false` — wifi off, airplane mode, cable out).
+     * Default: "No internet connection — waiting to reconnect". The card
+     * replaces the error and reconnecting cards for as long as the browser
+     * says offline, and carries no Retry button: nothing can succeed without a
+     * route. Playback resumes on its own when the browser fires `online` (see
+     * the `offline`/`online` events).
+     */
+    offlineMessage?: string;
     /**
      * Turn on hls.js's internal console logging — segment/part scheduling, ABR
      * switches, and EME key-session + license traffic. Default: false.
@@ -1092,6 +1112,14 @@ export declare interface PlaybackStats {
 export declare interface Player {
     readonly state: PlayerState;
     readonly descriptor: StreamDescriptor | null;
+    /**
+     * True while the browser reports no network (`navigator.onLine === false`).
+     * Reliable in that direction only: `false` means "not known to be offline",
+     * which a captive portal or a dead upstream still satisfies. Orthogonal to
+     * `state` — a player can be 'buffering' or 'error' with this true, and the
+     * control bar shows the offline card over either while it is.
+     */
+    readonly offline: boolean;
     /** Why the stream ended, when the server said so; null otherwise. Cleared
      *  when fresh playback commits (including a rejoin). See EndedReason. */
     readonly endedReason: EndedReason | null;
@@ -1144,7 +1172,7 @@ export declare interface Player {
     destroy(): void;
 }
 
-export declare type PlayerEvent = 'ready' | 'waiting' | 'playing' | 'buffering' | 'paused' | 'ended' | 'error' | 'warning' | 'autoplayblocked' | 'qualitychange' | 'audiotrackchange' | 'texttrackchange' | 'pipchange' | 'latencytargetchange' | 'stats' | 'statechange';
+export declare type PlayerEvent = 'ready' | 'waiting' | 'playing' | 'buffering' | 'paused' | 'ended' | 'error' | 'warning' | 'autoplayblocked' | 'qualitychange' | 'audiotrackchange' | 'texttrackchange' | 'pipchange' | 'latencytargetchange' | 'stats' | 'statechange' | 'offline' | 'online';
 
 export declare interface PlayerEventMap {
     ready: void;
@@ -1183,6 +1211,21 @@ export declare interface PlayerEventMap {
     latencytargetchange: LiveTargetChange;
     stats: PlaybackStats;
     statechange: PlayerState;
+    /**
+     * The browser reported it lost its network (`window` `offline`). The
+     * player state is unchanged — what follows depends on where the loss
+     * lands: the hls.js engine parks its loader on the next failed fetch, a
+     * resolve in flight fails NETWORK — and `offline` is the one signal that
+     * the cause is the viewer's link. See {@link Player.offline}.
+     */
+    offline: void;
+    /**
+     * The browser reported its network is back (`window` `online`). The
+     * player resumes on its own: a parked hls.js loader restarts at once, and
+     * a fatal error that happened while offline (or any NETWORK error) is
+     * retried — the same re-resolve as `retry()`.
+     */
+    online: void;
 }
 
 export declare type PlayerState = 'idle' | 'waiting' | 'loading' | 'playing' | 'buffering' | 'paused' | 'ended' | 'error';