@oddin-gg/havik-player 2.21.0 → 2.22.0

package/dist/index.d.cts

@@ -207,6 +207,23 @@ export declare interface CreatePlayerOptions {
      * hlsConfig.abrEwmaDefaultEstimate or startLevel still wins. Default: true.
      */
     rememberBandwidth?: boolean;
+    /**
+     * How many rendition rungs ABR may pick ABOVE the one that merely covers
+     * the player's pixel box (hls.js engine). The box cap exists so a small
+     * embed never fetches 1080p, but exactly-covering is too tight: a 960 px
+     * box at 1x "covers" with 960×540, and a 540p encode at 1:1 looks softer
+     * than 720p downscaled into the same box. Measured on production 2026-11-01:
+     * Windows viewers spent 73% of their time at ≤540p with 20–60 Mbps to spare.
+     * Unset (the default): 1 rung on displays below 2x devicePixelRatio
+     * (bandwidth permitting; the top rung is never exceeded), 0 at 2x and
+     * above — phones and 2x Macs keep the cover-only cap, whose rung already
+     * matches their device pixels, so a rung above it would mostly cost data
+     * on small screens. An explicit value applies on every display: 0 = the
+     * strict cover-only cap, Infinity = no size cap. `maxBitrate` and the
+     * frame-drop cap still apply on top, and `hlsConfig.capLevelToPlayerSize:
+     * true` (hls.js's own poller) caps to the covering rung with no headroom.
+     */
+    sizeCapHeadroom?: number;
     /**
      * 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

package/dist/index.d.ts

@@ -207,6 +207,23 @@ export declare interface CreatePlayerOptions {
      * hlsConfig.abrEwmaDefaultEstimate or startLevel still wins. Default: true.
      */
     rememberBandwidth?: boolean;
+    /**
+     * How many rendition rungs ABR may pick ABOVE the one that merely covers
+     * the player's pixel box (hls.js engine). The box cap exists so a small
+     * embed never fetches 1080p, but exactly-covering is too tight: a 960 px
+     * box at 1x "covers" with 960×540, and a 540p encode at 1:1 looks softer
+     * than 720p downscaled into the same box. Measured on production 2026-11-01:
+     * Windows viewers spent 73% of their time at ≤540p with 20–60 Mbps to spare.
+     * Unset (the default): 1 rung on displays below 2x devicePixelRatio
+     * (bandwidth permitting; the top rung is never exceeded), 0 at 2x and
+     * above — phones and 2x Macs keep the cover-only cap, whose rung already
+     * matches their device pixels, so a rung above it would mostly cost data
+     * on small screens. An explicit value applies on every display: 0 = the
+     * strict cover-only cap, Infinity = no size cap. `maxBitrate` and the
+     * frame-drop cap still apply on top, and `hlsConfig.capLevelToPlayerSize:
+     * true` (hls.js's own poller) caps to the covering rung with no headroom.
+     */
+    sizeCapHeadroom?: number;
     /**
      * 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