Feat: add an option to play without audio or video if audio or video failed

demo/scripts/components/Options/TrackSwitch.tsx

@@ -13,45 +13,67 @@ function TrackSwitchConfig({
   onDefaultAudioTrackSwitchingModeChange,
   onCodecSwitchChange,
   onEnableFastSwitchingChange,
+  onAudioTracksNotPlayable,
+  onAudioTracksNotPlayableChange,
+  onVideoTracksNotPlayable,
+  onVideoTracksNotPlayableChange,
 }: {
   defaultAudioTrackSwitchingMode: string;
   onDefaultAudioTrackSwitchingModeChange: (newVal: string) => void;
   enableFastSwitching: boolean;
   onCodecSwitch: string;
   onCodecSwitchChange: (val: string) => void;
   onEnableFastSwitchingChange: (val: boolean) => void;
+  onAudioTracksNotPlayable: string;
+  onAudioTracksNotPlayableChange: (val: string) => void;
+  onVideoTracksNotPlayable: string;
+  onVideoTracksNotPlayableChange: (val: string) => void;
 }): React.JSX.Element {
-  let defaultAudioTrackSwitchingModeDescMsg;
-  switch (defaultAudioTrackSwitchingMode) {
-    case "reload":
-      defaultAudioTrackSwitchingModeDescMsg =
-        "Reloading by default when the audio track is changed";
-      break;
-    case "direct":
-      defaultAudioTrackSwitchingModeDescMsg =
-        "Directly audible transition when the audio track is changed";
-      break;
-    case "seamless":
-      defaultAudioTrackSwitchingModeDescMsg =
-        "Smooth transition when the audio track is changed";
-      break;
-    default:
-      defaultAudioTrackSwitchingModeDescMsg = "Unknown value";
-      break;
-  }
+  const defaultAudioTrackSwitchingModeDescMsg = React.useMemo(() => {
+    switch (defaultAudioTrackSwitchingMode) {
+      case "reload":
+        return "Reloading by default when the audio track is changed";
+      case "direct":
+        return "Directly audible transition when the audio track is changed";
+      case "seamless":
+        return "Smooth transition when the audio track is changed";
+      default:
+        return "Unknown value";
+    }
+  }, [defaultAudioTrackSwitchingMode]);
 
-  let onCodecSwitchDescMsg;
-  switch (onCodecSwitch) {
-    case "reload":
-      onCodecSwitchDescMsg = "Reloading buffers when the codec changes";
-      break;
-    case "continue":
-      onCodecSwitchDescMsg = "Keeping the same buffers even when the codec changes";
-      break;
-    default:
-      onCodecSwitchDescMsg = "Unknown value";
-      break;
-  }
+  const onCodecSwitchDescMsg = React.useMemo(() => {
+    switch (onCodecSwitch) {
+      case "reload":
+        return "Reloading buffers when the codec changes";
+      case "continue":
+        return "Keeping the same buffers even when the codec changes";
+      default:
+        return "Unknown value";
+    }
+  }, [onCodecSwitch]);
+
+  const onAudioTracksNotPlayableDescMsg = React.useMemo(() => {
+    switch (onAudioTracksNotPlayable) {
+      case "error":
+        return "Throw an error if no audio track can be played";
+      case "continue":
+        return "Continue with video only if no audio track is playable";
+      default:
+        return "Unknown value";
+    }
+  }, [onAudioTracksNotPlayable]);
+
+  const onVideoTracksNotPlayableDescMsg = React.useMemo(() => {
+    switch (onVideoTracksNotPlayable) {
+      case "error":
+        return "Throw an error if no video track can be played";
+      case "continue":
+        return "Continue with audio only if no video track is playable";
+      default:
+        return "Unknown value";
+    }
+  }, [onVideoTracksNotPlayable]);
 
   const onCodecSwitchSelection = React.useCallback(
     ({ value }: { value: string }) => onCodecSwitchChange(value),
@@ -63,6 +85,16 @@ function TrackSwitchConfig({
     [onDefaultAudioTrackSwitchingModeChange],
   );
 
+  const onAudioTracksNotPlayableSelection = React.useCallback(
+    ({ value }: { value: string }) => onAudioTracksNotPlayableChange(value),
+    [onAudioTracksNotPlayableChange],
+  );
+
+  const onVideoTracksNotPlayableSelection = React.useCallback(
+    ({ value }: { value: string }) => onVideoTracksNotPlayableChange(value),
+    [onVideoTracksNotPlayableChange],
+  );
+
   return (
     <>
       <li>
@@ -109,6 +141,35 @@ function TrackSwitchConfig({
         </Select>
         <span className="option-desc">{onCodecSwitchDescMsg}</span>
       </li>
+      <li className="featureWrapperWithSelectMode">
+        <Select
+          ariaLabel="Selecting the onAudioTracksNotPlayable attribute"
+          disabled={false}
+          className="playerOptionInput"
+          name="onAudioTracksNotPlayable"
+          onChange={onAudioTracksNotPlayableSelection}
+          selected={{ value: onAudioTracksNotPlayable, index: undefined }}
+          options={["continue", "error"]}
+        >
+          On Audio Tracks Not Playable
+        </Select>
+        <span className="option-desc">{onAudioTracksNotPlayableDescMsg}</span>
+      </li>
+
+      <li className="featureWrapperWithSelectMode">
+        <Select
+          ariaLabel="Selecting the onVideoTracksNotPlayable attribute"
+          disabled={false}
+          className="playerOptionInput"
+          name="onVideoTracksNotPlayable"
+          onChange={onVideoTracksNotPlayableSelection}
+          selected={{ value: onVideoTracksNotPlayable, index: undefined }}
+          options={["continue", "error"]}
+        >
+          On Video Tracks Not Playable
+        </Select>
+        <span className="option-desc">{onVideoTracksNotPlayableDescMsg}</span>
+      </li>
     </>
   );
 }

demo/scripts/controllers/Settings.tsx

@@ -69,6 +69,8 @@ function Settings({
     checkManifestIntegrity,
     requestConfig,
     onCodecSwitch,
+    onAudioTracksNotPlayable,
+    onVideoTracksNotPlayable,
   } = loadVideoOptions;
   const cmcdCommunicationMethod = cmcd?.communicationType ?? "disabled";
   const { manifest: manifestRequestConfig, segment: segmentRequestConfig } =
@@ -301,6 +303,30 @@ function Settings({
     [updateLoadVideoOptions],
   );
 
+  const onAudioTracksNotPlayableChange = useCallback(
+    (value: string) => {
+      updateLoadVideoOptions((prevOptions) => {
+        if (value === prevOptions.onAudioTracksNotPlayable) {
+          return prevOptions;
+        }
+        return Object.assign({}, prevOptions, { onAudioTracksNotPlayable: value });
+      });
+    },
+    [updateLoadVideoOptions],
+  );
+
+  const onVideoTracksNotPlayableChange = useCallback(
+    (value: string) => {
+      updateLoadVideoOptions((prevOptions) => {
+        if (value === prevOptions.onVideoTracksNotPlayable) {
+          return prevOptions;
+        }
+        return Object.assign({}, prevOptions, { onVideoTracksNotPlayable: value });
+      });
+    },
+    [updateLoadVideoOptions],
+  );
+
   const onWantedBufferAheadChange = useCallback(
     (wantedBufferAhead: number) => {
       updatePlayerOptions((prevOptions) => {
@@ -424,6 +450,10 @@ function Settings({
             }
             onEnableFastSwitchingChange={onEnableFastSwitchingChange}
             onCodecSwitchChange={onCodecSwitchChange}
+            onAudioTracksNotPlayable={onAudioTracksNotPlayable}
+            onAudioTracksNotPlayableChange={onAudioTracksNotPlayableChange}
+            onVideoTracksNotPlayable={onVideoTracksNotPlayable}
+            onVideoTracksNotPlayableChange={onVideoTracksNotPlayableChange}
           />
         </Option>
         <Option title="Buffer Options">

demo/scripts/lib/defaultOptionsValues.ts

@@ -31,6 +31,8 @@ const defaultOptionsValues = {
       },
     },
     onCodecSwitch: "continue",
+    onAudioTracksNotPlayable: "error",
+    onVideoTracksNotPlayable: "error",
   },
 } satisfies {
   player: IConstructorOptions;

demo/scripts/modules/player/index.ts

@@ -138,6 +138,8 @@ export interface IPlayerModuleState {
   livePosition: null | undefined | number;
   maximumPosition: null | undefined | number;
   minimumPosition: null | undefined | number;
+  onAudioTracksNotPlayable: "continue" | "error";
+  onVideoTracksNotPlayable: "continue" | "error";
   playbackRate: number;
   /** Try to play contents in "multithread" mode when possible. */
   relyOnWorker: boolean;
@@ -196,6 +198,8 @@ const PlayerModule = declareModule(
     livePosition: undefined,
     maximumPosition: undefined,
     minimumPosition: undefined,
+    onAudioTracksNotPlayable: "error",
+    onVideoTracksNotPlayable: "error",
     playbackRate: 1,
     relyOnWorker: false,
     useWorker: false,
@@ -289,6 +293,8 @@ const PlayerModule = declareModule(
             {
               mode: state.get("relyOnWorker") ? "auto" : "main",
               textTrackElement,
+              onAudioTracksNotPlayable: state.get("onAudioTracksNotPlayable"),
+              onVideoTracksNotPlayable: state.get("onVideoTracksNotPlayable"),
             },
             arg,
           ) as ILoadVideoOptions,

doc/api/Loading_a_Content.md

@@ -706,6 +706,63 @@ Those are the possible values for that option:
   More information about the `"RELOADING"` state can be found in
   [the player states documentation](./Player_States.md).
 
+### onAudioTracksNotPlayable
+
+_type_: `string|undefined`
+
+_defaults_: `"error"`
+
+Specifies the behavior when all audio tracks are not playable - This can occur if the
+device does not support the required audio codecs, or if the content cannot be decrypted,
+for example, due to an insufficient security level.
+
+Those are the possible values for that option:
+
+- `"continue"`: The player will proceed to play the content without audio.
+
+- `"error"`: The player will throw an error `MediaError` with the code
+  `MANIFEST_INCOMPATIBLE_CODECS_ERROR`, `NO_AUDIO_VIDEO_TRACKS` or
+  `NO_PLAYABLE_REPRESENTATION` to indicate that the audio tracks could not be played.
+
+<div class="note">
+
+- An event [`noPlayableTrack`](./Player_Events.md) will be emitted if no audio tracks are
+  playable.
+
+- If neither the audio nor video tracks are playable, a `"NO_AUDIO_VIDEO_TRACKS"` error
+  will be thrown regardless of this setting.
+
+</div>
+
+### onVideoTracksNotPlayable
+
+_type_: `string|undefined`
+
+_defaults_: `"error"`
+
+Specifies the behavior when all video tracks are not playable - This can occur if the
+device does not support the required video codecs, or if the content cannot be decrypted,
+for example, due to an insufficient security level.
+
+Those are the possible values for that option:
+
+- `"continue"`: The player will proceed to play the content without video. (i.e.,
+  audio-only playback).
+
+- `"error"`: The player will throw an error `MediaError` with the code
+  `MANIFEST_INCOMPATIBLE_CODECS_ERROR`, `NO_AUDIO_VIDEO_TRACKS` or
+  `NO_PLAYABLE_REPRESENTATION` to indicate that the video tracks could not be played.
+
+<div class="note">
+
+- An event [`noPlayableTrack`](./Player_Events.md#noplayabletrack) will be emitted if no
+  video tracks are playable.
+
+- If neither the audio nor video tracks are playable, a `"NO_AUDIO_VIDEO_TRACKS"` error
+  will be thrown regardless of this setting.
+
+</div>
+
 ### lowLatencyMode
 
 _type_: `Boolean|undefined`
@@ -927,7 +984,7 @@ The `serverSyncInfos` object contains two keys:
   <div class="note">
   The `performance.now()` API is used here because it is the main API to
   obtain a monotically increasing clock on the client-side.
-  </div</div>
+  </div>
 
 Example:
 

doc/api/Player_Errors.md

@@ -191,6 +191,9 @@ An error of `type` `MEDIA_ERROR` can have the following codes (`code` property):
   For those errors, you may be able to know the characteristics of the corresponding
   track(s) by inspecting the error's `tracksInfo` property, described below.
 
+- `"NO_AUDIO_VIDEO_TRACKS"`: No audio and video tracks were selected. This can happen if
+  the application has disabled both audio and video.
+
 - `"MANIFEST_UPDATE_ERROR"`: This error should never be emitted as it is handled
   internally by the RxPlayer. Please open an issue if you encounter it.
 

doc/api/Player_Events.md

@@ -536,6 +536,48 @@ video track when in directfile mode to avoid that case (this is documented
 in the corresponding APIs).
 </div>
 
+### noPlayableTrack
+
+_payload type_: `Object`
+
+Emitted when no tracks of a given type can be selected for a given period.
+
+The payload is an object with the following properties:
+
+- `trackType` (`"audio" | "video" | "text"`): The type of the track that appears to have
+  no playable options available.
+
+- `period`: (`Object`): The period in which the track is not playable. This object has the
+  following properties:
+
+  - `id`: (`"string"`): The ID of the period.
+
+  - `start`: (`"number"`): The start time of the period.
+
+  - `end`: (`"number" | undefined`): The end time of the period. This value may be
+    `undefined` either if not known or if the Period has no end yet (e.g. for live
+    contents, the end might not be known for now)
+
+<div class="note">
+
+The `noPlayableTrack` event is emitted when none of the tracks for a specific type (audio,
+video, or subtitles) are playable for a given period.
+
+For example, this might occur if a content only has audio codecs that the device does not
+support, or if a media cannot be decrypted due to an insufficient security level.
+
+By listening for this event, the application can respond appropriately, such as notifying
+the user that the given track type is not playable, or taking corrective actions such as
+continuing playback with available tracks (e.g., playing video-only if no audio track is
+available).
+
+The `loadVideo()` options
+[`onAudioTracksNotPlayable`](./Loading_a_Content.md#onaudiotracksnotplayable) and
+[`onVideoTracksNotPlayable`](./Loading_a_Content.md#onvideotracksnotplayable) defines the
+player behavior when a track is not playable.
+
+</div>
+
 ## Representation selection events
 
 This chapter describes events linked to the current audio, video or Representation /

doc/reference/API_Reference.md

@@ -167,6 +167,12 @@ events and so on.
 - [`defaultAudioTrackSwitchingMode`](../api/Loading_a_Content.md#defaultaudiotrackswitchingmode):
   Default behavior when switching the audio track.
 
+- [`onAudioTracksNotPlayable`](../api/Loading_a_Content.md#onaudiotracksnotplayable):
+  Specifies the behavior when all audio tracks are not playable.
+
+- [`onVideoTracksNotPlayable`](../api/Loading_a_Content.md#onvideotracksnotplayable):
+  Specifies the behavior when all video tracks are not playable.
+
 - [`lowLatencyMode`](../api/Loading_a_Content.md#lowlatencymode): Allows to play
   low-latency contents efficiently.