@oddin-gg/havik-player 2.27.2 → 2.28.1

package/dist/index.d.cts

@@ -271,6 +271,20 @@ export declare interface CreatePlayerOptions {
      * hands capping to hls.js.
      */
     stallCap?: boolean;
+    /**
+     * Stuck-freeze reload (native engine: Safari, iPhone, iPad; live only):
+     * when the playhead has not moved and the buffered media under it has not
+     * grown for 8 s, with the page visible, the element playing and the
+     * browser online, the player reloads the stream at the live edge. WebKit's
+     * native HLS has a freeze it never leaves by itself: on production iPhone
+     * Safari over 8 days to 2026-11-04 there were 2.31 such freezes per
+     * watch-hour (hls.js on Android, same CDN slots and countries: 0.35), not
+     * one recovered on its own, and viewers paused or left after a median
+     * 24 s. At most twice per 30 s of healthy playback; a slow start, a seek,
+     * a pause, a hidden tab and an offline browser never count. Each reload
+     * counts in `stuckReloads`. Default: true.
+     */
+    stuckReload?: boolean;
     /**
      * DRM cold start: download the first init segment and parts while the
      * first key is still being acquired, instead of after it (hls.js waits for
@@ -1007,6 +1021,13 @@ export declare class PlaybackError extends Error {
      * upper-case ISO 3166-1 alpha-2 tag (e.g. "RU"). Absent on every other code.
      */
     readonly country?: string;
+    /**
+     * The engine's own name for the failure, when it supplied one: an hls.js
+     * `ErrorDetails` value (`keySystemNoAccess`, `bufferStalledError`, …).
+     * Absent on errors the SDK or the server raised. Branch on this, not on
+     * `message`, to tell one engine failure from another.
+     */
+    readonly detail?: string;
     constructor(code: PlaybackErrorCode, httpStatus: number, message: string, init?: PlaybackErrorInit);
 }
 
@@ -1028,6 +1049,12 @@ export declare interface PlaybackErrorInit {
      * carried on a GEO_DENIED body so the player can name it.
      */
     country?: string;
+    /**
+     * The engine's own name for the failure (an hls.js `ErrorDetails` value
+     * such as `keySystemNoAccess`), when it supplied one. `message` is composed
+     * prose; this is the value to branch on.
+     */
+    detail?: string;
     cause?: unknown;
 }
 
@@ -1090,6 +1117,10 @@ export declare interface PlaybackStats {
     /** Times a playback stall stepped the ABR ceiling down one rung this session
      *  (hls.js engine only; see `stallCap`). */
     stallDownCaps?: number;
+    /** Times the stuck-freeze watchdog reloaded the stream because the playhead
+     *  and the buffered end both stopped for 8 s (native engine only; see
+     *  `stuckReload`). */
+    stuckReloads?: number;
     /** Height of the highest rendition ABR may pick right now (hls.js engine
      *  only). Present only while a ceiling is in force; a viewer stuck at 540p
      *  reads it next to `levelHeight` to see the ceiling, not the network. */

package/dist/index.d.ts

@@ -271,6 +271,20 @@ export declare interface CreatePlayerOptions {
      * hands capping to hls.js.
      */
     stallCap?: boolean;
+    /**
+     * Stuck-freeze reload (native engine: Safari, iPhone, iPad; live only):
+     * when the playhead has not moved and the buffered media under it has not
+     * grown for 8 s, with the page visible, the element playing and the
+     * browser online, the player reloads the stream at the live edge. WebKit's
+     * native HLS has a freeze it never leaves by itself: on production iPhone
+     * Safari over 8 days to 2026-11-04 there were 2.31 such freezes per
+     * watch-hour (hls.js on Android, same CDN slots and countries: 0.35), not
+     * one recovered on its own, and viewers paused or left after a median
+     * 24 s. At most twice per 30 s of healthy playback; a slow start, a seek,
+     * a pause, a hidden tab and an offline browser never count. Each reload
+     * counts in `stuckReloads`. Default: true.
+     */
+    stuckReload?: boolean;
     /**
      * DRM cold start: download the first init segment and parts while the
      * first key is still being acquired, instead of after it (hls.js waits for
@@ -1007,6 +1021,13 @@ export declare class PlaybackError extends Error {
      * upper-case ISO 3166-1 alpha-2 tag (e.g. "RU"). Absent on every other code.
      */
     readonly country?: string;
+    /**
+     * The engine's own name for the failure, when it supplied one: an hls.js
+     * `ErrorDetails` value (`keySystemNoAccess`, `bufferStalledError`, …).
+     * Absent on errors the SDK or the server raised. Branch on this, not on
+     * `message`, to tell one engine failure from another.
+     */
+    readonly detail?: string;
     constructor(code: PlaybackErrorCode, httpStatus: number, message: string, init?: PlaybackErrorInit);
 }
 
@@ -1028,6 +1049,12 @@ export declare interface PlaybackErrorInit {
      * carried on a GEO_DENIED body so the player can name it.
      */
     country?: string;
+    /**
+     * The engine's own name for the failure (an hls.js `ErrorDetails` value
+     * such as `keySystemNoAccess`), when it supplied one. `message` is composed
+     * prose; this is the value to branch on.
+     */
+    detail?: string;
     cause?: unknown;
 }
 
@@ -1090,6 +1117,10 @@ export declare interface PlaybackStats {
     /** Times a playback stall stepped the ABR ceiling down one rung this session
      *  (hls.js engine only; see `stallCap`). */
     stallDownCaps?: number;
+    /** Times the stuck-freeze watchdog reloaded the stream because the playhead
+     *  and the buffered end both stopped for 8 s (native engine only; see
+     *  `stuckReload`). */
+    stuckReloads?: number;
     /** Height of the highest rendition ABR may pick right now (hls.js engine
      *  only). Present only while a ceiling is in force; a viewer stuck at 540p
      *  reads it next to `levelHeight` to see the ceiling, not the network. */