@oddin-gg/havik-player 2.26.0 → 2.27.0

package/dist/index.d.cts

@@ -256,6 +256,21 @@ export declare interface CreatePlayerOptions {
      * stepping.
      */
     adaptiveHoldBackCeiling?: number;
+    /**
+     * Stall-aware quality ceiling (hls.js engine): after a playback stall (not in
+     * the first 10 s after playback starts or resumes, not while seeking, not
+     * with media still buffered ahead, not a wait at the live edge for a part
+     * not yet published) the player caps quality one rung below
+     * the rendition that stalled, and gives one rung back per 3 minutes of
+     * playback without another stall. Without it, ABR climbs straight back onto
+     * a rung the link just failed to carry: on measured production sessions
+     * 55-65 % of rebuffer time was such a repeat stall within 3 minutes. Each step counts
+     * in `stallDownCaps`; while it is the binding ceiling, `capReason` is
+     * `'stall'`. Default: true. Ignored while the viewer pinned a quality, and
+     * off when `hlsConfig.capLevelToPlayerSize` or `capLevelOnFPSDrop: true`
+     * hands capping to hls.js.
+     */
+    stallCap?: 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
@@ -1072,17 +1087,21 @@ export declare interface PlaybackStats {
     /** Times the ABR ceiling was stepped down because the device kept dropping
      *  frames on the rendition it played (hls.js engine only). */
     fpsDownCaps?: number;
+    /** Times a playback stall stepped the ABR ceiling down one rung this session
+     *  (hls.js engine only; see `stallCap`). */
+    stallDownCaps?: 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. */
     maxLevelHeight?: number;
     /** Which SDK-owned cap set `maxLevelHeight`: the player's pixel box, the
-     *  caller's `maxBitrate` budget, or frame-drop capping. Present only while
-     *  the SDK's own ceiling is applied; when two caps land on the same rung the
-     *  first of size, bitrate, fps is reported. Omitted when the caller handed
+     *  caller's `maxBitrate` budget, frame-drop capping, or the stall-aware
+     *  ceiling. Present only while the SDK's own ceiling is applied; when two
+     *  caps land on the same rung the first of size, bitrate, fps, stall is
+     *  reported. Omitted when the caller handed
      *  capping to hls.js (`capLevelToPlayerSize` / `capLevelOnFPSDrop`), even if
      *  `maxLevelHeight` is set from hls.js's own cap. */
-    capReason?: 'size' | 'bitrate' | 'fps';
+    capReason?: 'size' | 'bitrate' | 'fps' | 'stall';
     /** Bitrate of the current rendition in kbps, when known. */
     renditionBitrateKbps?: number;
     /** Duration of the most recent DRM license acquisition in ms (0 = none yet). */

package/dist/index.d.ts

@@ -256,6 +256,21 @@ export declare interface CreatePlayerOptions {
      * stepping.
      */
     adaptiveHoldBackCeiling?: number;
+    /**
+     * Stall-aware quality ceiling (hls.js engine): after a playback stall (not in
+     * the first 10 s after playback starts or resumes, not while seeking, not
+     * with media still buffered ahead, not a wait at the live edge for a part
+     * not yet published) the player caps quality one rung below
+     * the rendition that stalled, and gives one rung back per 3 minutes of
+     * playback without another stall. Without it, ABR climbs straight back onto
+     * a rung the link just failed to carry: on measured production sessions
+     * 55-65 % of rebuffer time was such a repeat stall within 3 minutes. Each step counts
+     * in `stallDownCaps`; while it is the binding ceiling, `capReason` is
+     * `'stall'`. Default: true. Ignored while the viewer pinned a quality, and
+     * off when `hlsConfig.capLevelToPlayerSize` or `capLevelOnFPSDrop: true`
+     * hands capping to hls.js.
+     */
+    stallCap?: 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
@@ -1072,17 +1087,21 @@ export declare interface PlaybackStats {
     /** Times the ABR ceiling was stepped down because the device kept dropping
      *  frames on the rendition it played (hls.js engine only). */
     fpsDownCaps?: number;
+    /** Times a playback stall stepped the ABR ceiling down one rung this session
+     *  (hls.js engine only; see `stallCap`). */
+    stallDownCaps?: 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. */
     maxLevelHeight?: number;
     /** Which SDK-owned cap set `maxLevelHeight`: the player's pixel box, the
-     *  caller's `maxBitrate` budget, or frame-drop capping. Present only while
-     *  the SDK's own ceiling is applied; when two caps land on the same rung the
-     *  first of size, bitrate, fps is reported. Omitted when the caller handed
+     *  caller's `maxBitrate` budget, frame-drop capping, or the stall-aware
+     *  ceiling. Present only while the SDK's own ceiling is applied; when two
+     *  caps land on the same rung the first of size, bitrate, fps, stall is
+     *  reported. Omitted when the caller handed
      *  capping to hls.js (`capLevelToPlayerSize` / `capLevelOnFPSDrop`), even if
      *  `maxLevelHeight` is set from hls.js's own cap. */
-    capReason?: 'size' | 'bitrate' | 'fps';
+    capReason?: 'size' | 'bitrate' | 'fps' | 'stall';
     /** Bitrate of the current rendition in kbps, when known. */
     renditionBitrateKbps?: number;
     /** Duration of the most recent DRM license acquisition in ms (0 = none yet). */