@oddin-gg/havik-player 2.23.3 → 2.24.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'. */
@@ -346,7 +356,9 @@ export declare interface CreatePlayerOptions {
      * rejoins automatically (see {@link rejoinOnLive}). Default: true — and
      * fully graceful: if the endpoint is unreachable the subscription retries
      * quietly in the background while the HLS staleness watchdog remains the
-     * layer-fallback, so playback is never affected. Set false to disable.
+     * layer-fallback, so playback is never affected. An HTTP 410 (the match is
+     * gone) stops it, a 404 (not in the catalog) slows it to one retry every
+     * 5 min; either way one `warning` event. Set false to disable.
      */
     liveStateEvents?: boolean;
     /**
@@ -818,6 +830,26 @@ export declare interface LiveStateEvent {
     serverTime: string;
 }
 
+/**
+ * The HTTP answer a subscribe attempt got instead of a stream.
+ *
+ * - `terminal` (410): the match is over and gone for good; the subscription
+ *   stops instead of reconnecting every backoff period for as long as the
+ *   page stays open.
+ * - 404: the match is not in the catalog NOW — it ended and was dropped, or
+ *   it is not listed yet (a URN known to the integrator before Bragi lists
+ *   it). The second case heals on its own, so a 404 keeps retrying, but on
+ *   the slow lane ({@link SubscribeLiveStateOptions.notFoundRetryMs}, 5 min)
+ *   instead of the 15 s backoff cap: a finished match costs a request every
+ *   five minutes, not 240 an hour.
+ * - anything else retries with the normal backoff.
+ */
+export declare class LiveStateHttpError extends Error {
+    readonly status: number;
+    readonly terminal: boolean;
+    constructor(status: number);
+}
+
 export declare interface LiveStateSubscription {
     /** Stop the subscription and abort the in-flight request. Idempotent. */
     close(): void;
@@ -1274,7 +1306,11 @@ export declare interface StreamDescriptor {
  * The body is a `text/event-stream` we parse incrementally. The connection is
  * long-lived (the server caps it at ~30min and sends heartbeats); on any
  * close/error the client reconnects with exponential backoff and re-syncs from
- * the initial snapshot the server replays on connect. A connection that stops
+ * the initial snapshot the server replays on connect. Two answers are special:
+ * a 410 (the match is gone for good) ends the subscription, and a 404 (not in
+ * the catalog now) moves the retry to a slow lane, `notFoundRetryMs` — a tab
+ * left open on a finished match used to hit the endpoint every backoff period
+ * indefinitely, while a match listed late still gets picked up. A connection that stops
  * delivering without closing is caught by the idle watchdog
  * (`idleTimeoutMs`) — see the note on it in `readStream`. A subscription
  * failure is always non-fatal to playback — callers keep the HLS staleness
@@ -1290,9 +1326,11 @@ export declare interface SubscribeLiveStateOptions {
     /** Fired for the initial snapshot on connect and every subsequent transition. */
     onState: (ev: LiveStateEvent) => void;
     /**
-     * Fired on a non-fatal subscription problem (network drop, HTTP error,
-     * server lifetime-cap close). The client keeps retrying with backoff; this
-     * is observational only — it never tears playback down.
+     * Fired on a subscription problem (network drop, HTTP error, server
+     * lifetime-cap close). The client keeps retrying with backoff — a 404 on the
+     * slow lane ({@link notFoundRetryMs}), and not at all after a 410
+     * ({@link LiveStateHttpError} with `terminal: true`). Observational only —
+     * it never tears playback down.
      */
     onError?: (err: unknown) => void;
     /**
@@ -1304,6 +1342,13 @@ export declare interface SubscribeLiveStateOptions {
     /** Reconnect backoff floor / ceiling (ms). Defaults: 1000 / 15000. */
     minBackoffMs?: number;
     maxBackoffMs?: number;
+    /**
+     * Retry interval after an HTTP 404 (match not in the catalog). Default
+     * 300000 (5 min): long enough that a tab left open on a finished match is
+     * noise, short enough that a match listed late is picked up without a
+     * reload. Not floored by `maxBackoffMs`.
+     */
+    notFoundRetryMs?: number;
     /**
      * How long a request may stay silent before it is treated as dead and
      * reconnected. Applies to both phases: waiting for response headers, and

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'. */
@@ -346,7 +356,9 @@ export declare interface CreatePlayerOptions {
      * rejoins automatically (see {@link rejoinOnLive}). Default: true — and
      * fully graceful: if the endpoint is unreachable the subscription retries
      * quietly in the background while the HLS staleness watchdog remains the
-     * layer-fallback, so playback is never affected. Set false to disable.
+     * layer-fallback, so playback is never affected. An HTTP 410 (the match is
+     * gone) stops it, a 404 (not in the catalog) slows it to one retry every
+     * 5 min; either way one `warning` event. Set false to disable.
      */
     liveStateEvents?: boolean;
     /**
@@ -818,6 +830,26 @@ export declare interface LiveStateEvent {
     serverTime: string;
 }
 
+/**
+ * The HTTP answer a subscribe attempt got instead of a stream.
+ *
+ * - `terminal` (410): the match is over and gone for good; the subscription
+ *   stops instead of reconnecting every backoff period for as long as the
+ *   page stays open.
+ * - 404: the match is not in the catalog NOW — it ended and was dropped, or
+ *   it is not listed yet (a URN known to the integrator before Bragi lists
+ *   it). The second case heals on its own, so a 404 keeps retrying, but on
+ *   the slow lane ({@link SubscribeLiveStateOptions.notFoundRetryMs}, 5 min)
+ *   instead of the 15 s backoff cap: a finished match costs a request every
+ *   five minutes, not 240 an hour.
+ * - anything else retries with the normal backoff.
+ */
+export declare class LiveStateHttpError extends Error {
+    readonly status: number;
+    readonly terminal: boolean;
+    constructor(status: number);
+}
+
 export declare interface LiveStateSubscription {
     /** Stop the subscription and abort the in-flight request. Idempotent. */
     close(): void;
@@ -1274,7 +1306,11 @@ export declare interface StreamDescriptor {
  * The body is a `text/event-stream` we parse incrementally. The connection is
  * long-lived (the server caps it at ~30min and sends heartbeats); on any
  * close/error the client reconnects with exponential backoff and re-syncs from
- * the initial snapshot the server replays on connect. A connection that stops
+ * the initial snapshot the server replays on connect. Two answers are special:
+ * a 410 (the match is gone for good) ends the subscription, and a 404 (not in
+ * the catalog now) moves the retry to a slow lane, `notFoundRetryMs` — a tab
+ * left open on a finished match used to hit the endpoint every backoff period
+ * indefinitely, while a match listed late still gets picked up. A connection that stops
  * delivering without closing is caught by the idle watchdog
  * (`idleTimeoutMs`) — see the note on it in `readStream`. A subscription
  * failure is always non-fatal to playback — callers keep the HLS staleness
@@ -1290,9 +1326,11 @@ export declare interface SubscribeLiveStateOptions {
     /** Fired for the initial snapshot on connect and every subsequent transition. */
     onState: (ev: LiveStateEvent) => void;
     /**
-     * Fired on a non-fatal subscription problem (network drop, HTTP error,
-     * server lifetime-cap close). The client keeps retrying with backoff; this
-     * is observational only — it never tears playback down.
+     * Fired on a subscription problem (network drop, HTTP error, server
+     * lifetime-cap close). The client keeps retrying with backoff — a 404 on the
+     * slow lane ({@link notFoundRetryMs}), and not at all after a 410
+     * ({@link LiveStateHttpError} with `terminal: true`). Observational only —
+     * it never tears playback down.
      */
     onError?: (err: unknown) => void;
     /**
@@ -1304,6 +1342,13 @@ export declare interface SubscribeLiveStateOptions {
     /** Reconnect backoff floor / ceiling (ms). Defaults: 1000 / 15000. */
     minBackoffMs?: number;
     maxBackoffMs?: number;
+    /**
+     * Retry interval after an HTTP 404 (match not in the catalog). Default
+     * 300000 (5 min): long enough that a tab left open on a finished match is
+     * noise, short enough that a match listed late is picked up without a
+     * reload. Not floored by `maxBackoffMs`.
+     */
+    notFoundRetryMs?: number;
     /**
      * How long a request may stay silent before it is treated as dead and
      * reconnected. Applies to both phases: waiting for response headers, and