@oddin-gg/havik-player 2.16.13 → 2.18.0

package/dist/index.d.cts

@@ -98,6 +98,9 @@ export declare interface CatalogTournament {
  */
 export declare function clearDeviceId(): void;
 
+/** Forget every remembered estimate (privacy / "reset player data" control). */
+export declare function clearRememberedBandwidth(): void;
+
 /**
  * Endpoint selection, enforced at COMPILE time.
  *
@@ -193,6 +196,17 @@ export declare interface CreatePlayerOptions {
      * return is the one from before leaving. Default: true. Live/LL only.
      */
     snapToLiveOnRefocus?: boolean;
+    /**
+     * Start a stream at the quality this device's last measured speed allows,
+     * instead of always at ~360p. The hls.js engine saves its bandwidth estimate
+     * in localStorage (key `havik.player.bandwidth`, per connection type where the
+     * browser reports one) after ~10 s of playback and reuses it, discounted to
+     * 80%, for up to 3 days; a device that measured a slow line starts from that
+     * lower figure (never below 0.3 Mbps). A first visit, a stale record, or
+     * blocked storage keeps the conservative ~1 Mbps start. An explicit
+     * hlsConfig.abrEwmaDefaultEstimate or startLevel still wins. Default: true.
+     */
+    rememberBandwidth?: 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
@@ -905,6 +919,17 @@ 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;
+    /** 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
+     *  capping to hls.js (`capLevelToPlayerSize` / `capLevelOnFPSDrop`), even if
+     *  `maxLevelHeight` is set from hls.js's own cap. */
+    capReason?: 'size' | 'bitrate' | 'fps';
     /** 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

@@ -98,6 +98,9 @@ export declare interface CatalogTournament {
  */
 export declare function clearDeviceId(): void;
 
+/** Forget every remembered estimate (privacy / "reset player data" control). */
+export declare function clearRememberedBandwidth(): void;
+
 /**
  * Endpoint selection, enforced at COMPILE time.
  *
@@ -193,6 +196,17 @@ export declare interface CreatePlayerOptions {
      * return is the one from before leaving. Default: true. Live/LL only.
      */
     snapToLiveOnRefocus?: boolean;
+    /**
+     * Start a stream at the quality this device's last measured speed allows,
+     * instead of always at ~360p. The hls.js engine saves its bandwidth estimate
+     * in localStorage (key `havik.player.bandwidth`, per connection type where the
+     * browser reports one) after ~10 s of playback and reuses it, discounted to
+     * 80%, for up to 3 days; a device that measured a slow line starts from that
+     * lower figure (never below 0.3 Mbps). A first visit, a stale record, or
+     * blocked storage keeps the conservative ~1 Mbps start. An explicit
+     * hlsConfig.abrEwmaDefaultEstimate or startLevel still wins. Default: true.
+     */
+    rememberBandwidth?: 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
@@ -905,6 +919,17 @@ 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;
+    /** 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
+     *  capping to hls.js (`capLevelToPlayerSize` / `capLevelOnFPSDrop`), even if
+     *  `maxLevelHeight` is set from hls.js's own cap. */
+    capReason?: 'size' | 'bitrate' | 'fps';
     /** Bitrate of the current rendition in kbps, when known. */
     renditionBitrateKbps?: number;
     /** Duration of the most recent DRM license acquisition in ms (0 = none yet). */