HDR/SDR VIDEO-RANGE selection and priority

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

@@ -3081,6 +3081,7 @@ export type RetryConfig = {
 //
 // @public (undocumented)
 export type SelectionPreferences = {
+    videoPreference?: VideoSelectionOption;
     audioPreference?: AudioSelectionOption;
     subtitlePreference?: SubtitleSelectionOption;
 };
@@ -3417,6 +3418,14 @@ export interface UserdataSample {
 // @public (undocumented)
 export type VariableMap = Record<string, string>;
 
+// Warning: (ae-missing-release-tag) "VideoSelectionOption" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public (undocumented)
+export type VideoSelectionOption = {
+    preferHDR?: boolean;
+    allowedVideoRanges?: Array<VideoRange>;
+};
+
 // (No @packageDocumentation comment for this package)
 
 ```

docs/API.md

@@ -79,6 +79,7 @@ See [API Reference](https://hlsjs-dev.video-dev.org/api-docs/) for a complete li
   - [`pLoader`](#ploader)
   - [`xhrSetup`](#xhrsetup)
   - [`fetchSetup`](#fetchsetup)
+  - [`videoPreference`](#videopreference)
   - [`audioPreference`](#audiopreference)
   - [`subtitlePreference`](#subtitlepreference)
   - [`abrController`](#abrcontroller)
@@ -1145,6 +1146,22 @@ var config = {
 };
 ```
 
+### `videoPreference`
+
+(default `undefined`)
+
+These settings determine whether HDR video should be selected before SDR video. Which VIDEO-RANGE values are allowed, and in what order of priority can also be specified.
+
+Format `{ preferHDR: boolean, allowedVideoRanges: ('SDR' | 'PQ' | 'HLG')[] }`
+
+- Allow all video ranges if `allowedVideoRanges` is unspecified.
+- If `preferHDR` is defined, use the value to filter `allowedVideoRanges`.
+- Else check window for HDR support and set `preferHDR` to the result.
+
+When `preferHDR` is set, skip checking if the window supports HDR and instead use the value provided to determine level selection preference via dynamic range. A value of `preferHDR === true` will attempt to use HDR levels before selecting from SDR levels.
+
+`allowedVideoRanges` can restrict playback to a limited set of VIDEO-RANGE transfer functions and set their priority for selection. For example, to ignore all HDR variants, set `allowedVideoRanges` to `['SDR']`. Or, to ignore all HLG variants, set `allowedVideoRanges` to `['SDR', 'PQ']`. To prioritize PQ variants over HLG, set `allowedVideoRanges` to `['SDR', 'HLG', 'PQ']`.
+
 ### `audioPreference`
 
 (default: `undefined`)

src/config.ts

@@ -32,6 +32,7 @@ import type {
 import type {
   AudioSelectionOption,
   SubtitleSelectionOption,
+  VideoSelectionOption,
 } from './types/media-playlist';
 
 export type ABRControllerConfig = {
@@ -223,6 +224,7 @@ export type StreamControllerConfig = {
 };
 
 export type SelectionPreferences = {
+  videoPreference?: VideoSelectionOption;
   audioPreference?: AudioSelectionOption;
   subtitlePreference?: SubtitleSelectionOption;
 };

src/controller/abr-controller.ts

@@ -633,7 +633,8 @@ class AbrController implements AbrComponentAPI {
     let currentCodecSet: string | undefined;
     let currentVideoRange: VideoRange | undefined = 'SDR';
     let currentFrameRate = level?.frameRate || 0;
-    const audioPreference = config.audioPreference;
+
+    const { audioPreference, videoPreference } = config;
     const audioTracksByGroup =
       this.audioTracksByGroup ||
       (this.audioTracksByGroup = getAudioTracksByGroup(allAudioTracks));
@@ -654,10 +655,14 @@ class AbrController implements AbrComponentAPI {
         currentVideoRange,
         currentBw,
         audioPreference,
+        videoPreference,
       );
-      const { codecSet, videoRange, minFramerate, minBitrate } = startTier;
+      const { codecSet, videoRanges, minFramerate, minBitrate, preferHDR } =
+        startTier;
       currentCodecSet = codecSet;
-      currentVideoRange = videoRange;
+      currentVideoRange = preferHDR
+        ? videoRanges[videoRanges.length - 1]
+        : videoRanges[0];
       currentFrameRate = minFramerate;
       currentBw = Math.max(currentBw, minBitrate);
       logger.log(`[abr] picked start tier ${JSON.stringify(startTier)}`);
@@ -686,12 +691,14 @@ class AbrController implements AbrComponentAPI {
         !levelInfo.supportedResult &&
         !levelInfo.supportedPromise
       ) {
-        const mediaCapabilities = navigator.mediaCapabilities;
+        const mediaCapabilities = navigator.mediaCapabilities as
+          | MediaCapabilities
+          | undefined;
         if (
+          typeof mediaCapabilities?.decodingInfo === 'function' &&
           requiresMediaCapabilitiesDecodingInfo(
             levelInfo,
             audioTracksByGroup,
-            mediaCapabilities,
             currentVideoRange,
             currentFrameRate,
             currentBw,

src/controller/buffer-controller.ts

@@ -400,8 +400,8 @@ export default class BufferController implements ComponentAPI {
       },
       onStart: () => {},
       onComplete: () => {},
-      onError: (e) => {
-        this.warn(`Failed to change ${type} SourceBuffer type`, e);
+      onError: (error: Error) => {
+        this.warn(`Failed to change ${type} SourceBuffer type`, error);
       },
     };
 
@@ -495,7 +495,7 @@ export default class BufferController implements ComponentAPI {
           timeRanges,
         });
       },
-      onError: (err) => {
+      onError: (error: Error) => {
         // in case any error occured while appending, put back segment in segments table
         const event: ErrorData = {
           type: ErrorTypes.MEDIA_ERROR,
@@ -505,12 +505,12 @@ export default class BufferController implements ComponentAPI {
           frag,
           part,
           chunkMeta,
-          error: err,
-          err,
+          error,
+          err: error,
           fatal: false,
         };
 
-        if (err.code === DOMException.QUOTA_EXCEEDED_ERR) {
+        if ((error as DOMException).code === DOMException.QUOTA_EXCEEDED_ERR) {
           // QuotaExceededError: http://www.w3.org/TR/html5/infrastructure.html#quotaexceedederror
           // let's stop appending any segments, and report BUFFER_FULL_ERROR error
           event.details = ErrorDetails.BUFFER_FULL_ERROR;
@@ -1032,7 +1032,9 @@ export default class BufferController implements ComponentAPI {
   }
 
   private _onSBUpdateError(type: SourceBufferName, event: Event) {
-    const error = new Error(`${type} SourceBuffer error`);
+    const error = new Error(
+      `${type} SourceBuffer error. MediaSource readyState: ${this.mediaSource?.readyState}`,
+    );
     this.error(`${error}`, event);
     // according to http://www.w3.org/TR/media-source/#sourcebuffer-append-error
     // SourceBuffer errors are not necessarily fatal; if so, the HTMLMediaElement will fire an error event
@@ -1046,7 +1048,7 @@ export default class BufferController implements ComponentAPI {
     // updateend is always fired after error, so we'll allow that to shift the current operation off of the queue
     const operation = this.operationQueue.current(type);
     if (operation) {
-      operation.onError(event);
+      operation.onError(error);
     }
   }
 

src/controller/error-controller.ts

@@ -453,6 +453,11 @@ export default class ErrorController implements NetworkComponentAPI {
           data.details !== ErrorDetails.FRAG_GAP
         ) {
           data.fatal = true;
+        } else if (/MediaSource readyState: ended/.test(data.error.message)) {
+          this.warn(
+            `MediaSource ended after "${data.sourceBufferName}" sourceBuffer append error. Attempting to recover from media error.`,
+          );
+          this.hls.recoverMediaError();
         }
         break;
       case NetworkErrorAction.RetryRequest:

src/hls.ts

@@ -30,6 +30,7 @@ import type {
   AudioSelectionOption,
   MediaPlaylist,
   SubtitleSelectionOption,
+  VideoSelectionOption,
 } from './types/media-playlist';
 import type { HlsConfig } from './config';
 import type { BufferInfo } from './utils/buffer-helper';
@@ -959,6 +960,7 @@ export default class Hls implements HlsEventEmitter {
 export type {
   AudioSelectionOption,
   SubtitleSelectionOption,
+  VideoSelectionOption,
   MediaPlaylist,
   ErrorDetails,
   ErrorTypes,

src/types/media-playlist.ts

@@ -1,5 +1,6 @@
 import type { AttrList } from '../utils/attr-list';
 import type { LevelDetails } from '../loader/level-details';
+import type { VideoRange } from './level';
 
 export type AudioPlaylistType = 'AUDIO';
 
@@ -9,6 +10,11 @@ export type SubtitlePlaylistType = 'SUBTITLES' | 'CLOSED-CAPTIONS';
 
 export type MediaPlaylistType = MainPlaylistType | SubtitlePlaylistType;
 
+export type VideoSelectionOption = {
+  preferHDR?: boolean;
+  allowedVideoRanges?: Array<VideoRange>;
+};
+
 export type AudioSelectionOption = {
   lang?: string;
   assocLang?: string;

src/utils/hdr.ts

@@ -0,0 +1,70 @@
+import { type VideoRange, VideoRangeValues } from '../types/level';
+import type { VideoSelectionOption } from '../types/media-playlist';
+
+/**
+ * @returns Whether we can detect and validate HDR capability within the window context
+ */
+export function isHdrSupported() {
+  if (typeof matchMedia === 'function') {
+    const mediaQueryList = matchMedia('(dynamic-range: high)');
+    const badQuery = matchMedia('bad query');
+    if (mediaQueryList.media !== badQuery.media) {
+      return mediaQueryList.matches === true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Sanitizes inputs to return the active video selection options for HDR/SDR.
+ * When both inputs are null:
+ *
+ *    `{ preferHDR: false, allowedVideoRanges: [] }`
+ *
+ * When `currentVideoRange` non-null, maintain the active range:
+ *
+ *    `{ preferHDR: currentVideoRange !== 'SDR', allowedVideoRanges: [currentVideoRange] }`
+ *
+ * When VideoSelectionOption non-null:
+ *
+ *  - Allow all video ranges if `allowedVideoRanges` unspecified.
+ *  - If `preferHDR` is non-null use the value to filter `allowedVideoRanges`.
+ *  - Else check window for HDR support and set `preferHDR` to the result.
+ *
+ * @param currentVideoRange
+ * @param videoPreference
+ */
+export function getVideoSelectionOptions(
+  currentVideoRange: VideoRange | undefined,
+  videoPreference: VideoSelectionOption | undefined,
+) {
+  let preferHDR = false;
+  let allowedVideoRanges: Array<VideoRange> = [];
+
+  if (currentVideoRange) {
+    preferHDR = currentVideoRange !== 'SDR';
+    allowedVideoRanges = [currentVideoRange];
+  }
+
+  if (videoPreference) {
+    allowedVideoRanges =
+      videoPreference.allowedVideoRanges || VideoRangeValues.slice(0);
+    preferHDR =
+      videoPreference.preferHDR !== undefined
+        ? videoPreference.preferHDR
+        : isHdrSupported();
+
+    if (preferHDR) {
+      allowedVideoRanges = allowedVideoRanges.filter(
+        (range: VideoRange) => range !== 'SDR',
+      );
+    } else {
+      allowedVideoRanges = ['SDR'];
+    }
+  }
+
+  return {
+    preferHDR,
+    allowedVideoRanges,
+  };
+}

src/utils/mediacapabilities-helper.ts

@@ -32,7 +32,6 @@ export const SUPPORTED_INFO_CACHE: Record<
 export function requiresMediaCapabilitiesDecodingInfo(
   level: Level,
   audioTracksByGroup: AudioTracksByGroup,
-  mediaCapabilities: MediaCapabilities | undefined,
   currentVideoRange: VideoRange | undefined,
   currentFrameRate: number,
   currentBw: number,
@@ -75,8 +74,7 @@ export function requiresMediaCapabilitiesDecodingInfo(
     }
   }
   return (
-    (typeof mediaCapabilities?.decodingInfo == 'function' &&
-      level.videoCodec !== undefined &&
+    (level.videoCodec !== undefined &&
       ((level.width > 1920 && level.height > 1088) ||
         (level.height > 1920 && level.width > 1088) ||
         level.frameRate > Math.max(currentFrameRate, 30) ||
@@ -94,11 +92,11 @@ export function requiresMediaCapabilitiesDecodingInfo(
 export function getMediaDecodingInfoPromise(
   level: Level,
   audioTracksByGroup: AudioTracksByGroup,
-  mediaCapabilities: MediaCapabilities,
+  mediaCapabilities: MediaCapabilities | undefined,
 ): Promise<MediaDecodingInfo> {
   const videoCodecs = level.videoCodec;
   const audioCodecs = level.audioCodec;
-  if (!videoCodecs || !audioCodecs) {
+  if (!videoCodecs || !audioCodecs || !mediaCapabilities) {
     return Promise.resolve(SUPPORTED_INFO_DEFAULT);
   }