feat: maxDevicePixelRatio limits the browser's value (#6825)

Author: signalwerk

api-extractor/report/hls.js.api.md

@@ -2159,6 +2159,7 @@ export type HlsConfig = {
     enableSoftwareAES: boolean;
     minAutoBitrate: number;
     ignoreDevicePixelRatio: boolean;
+    maxDevicePixelRatio: number;
     preferManagedMediaSource: boolean;
     timelineOffset?: number;
     loader: {

docs/API.md

@@ -21,6 +21,7 @@ See [API Reference](https://hlsjs-dev.video-dev.org/api-docs/) for a complete li
   - [`capLevelToPlayerSize`](#capleveltoplayersize)
   - [`capLevelOnFPSDrop`](#caplevelonfpsdrop)
   - [`ignoreDevicePixelRatio`](#ignoredevicepixelratio)
+  - [`maxDevicePixelRatio`](#maxdevicepixelratio)
   - [`debug`](#debug)
   - [`autoStartLoad`](#autostartload)
   - [`startPosition`](#startposition)
@@ -526,6 +527,12 @@ This configuration will be applied by default to all instances.
 - when set to true, calculations related to player size will ignore browser `devicePixelRatio`.
 - when set to false, calculations related to player size will respect browser `devicePixelRatio`.
 
+### `maxDevicePixelRatio`
+
+(default: `Number.POSITIVE_INFINITY`)
+
+- when set, calculations related to player size will limit the browser's `devicePixelRatio` to this specified value.
+
 ### `debug`
 
 (default: `false`)

src/config.ts

@@ -272,6 +272,7 @@ export type HlsConfig = {
   enableSoftwareAES: boolean;
   minAutoBitrate: number;
   ignoreDevicePixelRatio: boolean;
+  maxDevicePixelRatio: number;
   preferManagedMediaSource: boolean;
   timelineOffset?: number;
   loader: { new (confg: HlsConfig): Loader<LoaderContext> };
@@ -356,6 +357,7 @@ export const hlsDefaultConfig: HlsConfig = {
   capLevelOnFPSDrop: false, // used by fps-controller
   capLevelToPlayerSize: false, // used by cap-level-controller
   ignoreDevicePixelRatio: false, // used by cap-level-controller
+  maxDevicePixelRatio: Number.POSITIVE_INFINITY, // used by cap-level-controller
   preferManagedMediaSource: true,
   initialLiveManifestSize: 1, // used by stream-controller
   maxBufferLength: 30, // used by stream-controller

src/controller/cap-level-controller.ts

@@ -258,7 +258,7 @@ class CapLevelController implements ComponentAPI {
       }
     }
 
-    return pixelRatio;
+    return Math.min(pixelRatio, this.hls.config.maxDevicePixelRatio);
   }
 
   private isLevelAllowed(level: Level): boolean {