feat: add disableAudioTrack API

demo/scripts/controllers/knobs/AudioTrack.tsx

@@ -34,38 +34,44 @@ function AudioTrackKnob({
       return [["Not available"], 0];
     }
     return [
-      availableAudioTracks.map((audioTrack) => {
-        return (
-          translateAudioTrackCode(audioTrack.normalized) +
-          (audioTrack.audioDescription ? " " + AUDIO_DESCRIPTION_ICON : "")
-        );
-      }),
+      ["no audio track"].concat(
+        availableAudioTracks.map((audioTrack) => {
+          return (
+            translateAudioTrackCode(audioTrack.normalized) +
+            (audioTrack.audioDescription ? " " + AUDIO_DESCRIPTION_ICON : "")
+          );
+        }),
+      ),
 
       currentAudioTrack
-        ? Math.max(findAudioTrackIndex(currentAudioTrack, availableAudioTracks), 0)
+        ? 1 + Math.max(findAudioTrackIndex(currentAudioTrack, availableAudioTracks), 0)
         : 0,
     ];
   }, [availableAudioTracks, currentAudioTrack]);
 
   const onAudioTrackChange = React.useCallback(
     ({ index }: { index: number }) => {
-      const track = availableAudioTracks[index];
-      if (track !== undefined) {
-        player.actions.setAudioTrack(track);
+      if (index > 0) {
+        const track = availableAudioTracks[index - 1];
+        if (track !== undefined) {
+          player.actions.setAudioTrack(track);
+        } else {
+          // eslint-disable-next-line no-console
+          console.error("Error: audio track not found");
+        }
       } else {
-        // eslint-disable-next-line no-console
-        console.error("Error: audio track not found");
+        player.actions.disableAudioTrack();
       }
     },
     [availableAudioTracks, player],
   );
 
   return (
     <Knob
-      name="Audio AudioTrack"
+      name="Audio Track"
       ariaLabel="Update the audio track"
       className={className}
-      disabled={availableAudioTracks.length < 2}
+      disabled={availableAudioTracks.length < 1}
       onChange={onAudioTrackChange}
       options={options}
       selected={{ index: selectedIndex, value: undefined }}

demo/scripts/modules/player/index.ts

@@ -419,6 +419,10 @@ const PlayerModule = declareModule(
         player.disableVideoTrack();
       },
 
+      disableAudioTrack() {
+        player.disableAudioTrack();
+      },
+
       setTextTrack(track: ITextTrack) {
         player.setTextTrack(track.id as string);
       },

doc/Getting_Started/Tutorials/Selecting_a_Track.md

@@ -437,11 +437,12 @@ subtitles or closed captions appearing on the screen.
 You could also want to disable the video track, which is a trick often used to reduce the
 network bandwidth used by a content.
 
-You can disable respectively the current text track and the current video track by calling
-those methods:
+You can disable respectively the current text track, the current video track and the
+current audio track by calling those methods:
 
 - [`disableTextTrack`](../../api/Track_Selection/disableTextTrack.md)
 - [`disableVideoTrack`](../../api/Track_Selection/disableVideoTrack.md)
+- [`disableAudioTrack`](../../api/Track_Selection/disableAudioTrack.md)
 
 However, like for selecting a track, this only concerns the current content being played.
 When playing a new content or even when just switching to another part of the content with

doc/api/Player_Events.md

@@ -797,8 +797,8 @@ The payload for this event is an object with the following properties:
     update it.
 
     This event is the direct consequence of calling `setAudioTrack`, `setTextTrack`,
-    `setVideoTrack`, `disableTextTrack` or `disableVideoTrack`, so it corresponds to track
-    updates you should already be aware of.
+    `setVideoTrack`, `disableTextTrack`, `disableVideoTrack` or `disableAudioTrack`, so it
+    corresponds to track updates you should already be aware of.
 
   - `"trickmode-enabled"`: The track is being updated because the application wanted to
     enable video trickmode tracks (usually by setting the `preferTrickModeTracks` option

doc/api/Track_Selection/disableAudioTrack.md

@@ -0,0 +1,37 @@
+# disableAudioTrack
+
+## Description
+
+Disable the current audio track, if one.
+
+Might enter in `RELOADING` state for a short period after calling this API.
+
+You can also disable the audio track for another Period by calling `disableAudioTrack`
+with the corresponding Period's id in argument. Such id can be obtained through the
+`getAvailablePeriods` method, the `newAvailablePeriods` event or the `periodChange` event.
+
+```js
+// example: disabling the audio track for all Periods
+const periods = rxPlayer.getAvailablePeriods();
+for (const period of periods) {
+  rxPlayer.disableAudioTrack(period.id);
+}
+```
+
+Note that disabling the audio track if there's no video track currently selected currently
+will lead to a [`NO_AUDIO_VIDEO_TRACKS` player error](../Player_Errors.md).
+
+## Syntax
+
+```js
+// Disable the current audio track
+player.disableAudioTrack();
+
+// Disable the audio track for a specific Period
+player.disableAudioTrack(periodId);
+```
+
+- **arguments**:
+  1.  _periodId_ `string|undefined`: The `id` of the Period for which you want to disable
+      the audio track. If not defined, the audio track of the currently-playing Period
+      will be disabled.

doc/api/Track_Selection/disableVideoTrack.md

@@ -18,6 +18,9 @@ for (const period of periods) {
 }
 ```
 
+Note that disabling the video track if there's no audio track currently selected currently
+will lead to a [`NO_AUDIO_VIDEO_TRACKS` player error](../Player_Errors.md).
+
 <div class="warning">
 This option may have no effect in <i>DirectFile</i> mode (see <a
 href="../Loading_a_Content.md#transport">loadVideo options</a>).

doc/reference/API_Reference.md

@@ -288,6 +288,9 @@ events and so on.
 - [`disableVideoTrack`](../api/Track_Selection/disableVideoTrack.md): Disable the current
   video track.
 
+- [`disableAudioTrack`](../api/Track_Selection/disableAudioTrack.md): Disable the current
+  audio track.
+
 - [`getVideoRepresentation`](../api/Representation_Selection/getVideoRepresentation.md):
   Returns the currently-loading video Representation.
 

src/main_thread/api/public_api.ts

@@ -2403,6 +2403,23 @@ class Player extends EventEmitter<IPublicAPIEvent> {
     );
   }
 
+  /**
+   * Disable audio track for the current content.
+   * @param {string|undefined} [periodId]
+   */
+  disableAudioTrack(periodId?: string | undefined): void {
+    if (this._priv_contentInfos === null) {
+      return;
+    }
+    const { isDirectFile, mediaElementTracksStore } = this._priv_contentInfos;
+    if (isDirectFile && mediaElementTracksStore !== null) {
+      return mediaElementTracksStore.disableAudioTrack();
+    }
+    return this._priv_callTracksStoreGetterSetter(periodId, undefined, (tcm, periodRef) =>
+      tcm.disableTrack(periodRef, "audio"),
+    );
+  }
+
   lockAudioRepresentations(arg: string[] | ILockedAudioRepresentationsSettings): void {
     if (this._priv_contentInfos === null) {
       throw new Error("No content loaded");
@@ -2691,6 +2708,7 @@ class Player extends EventEmitter<IPublicAPIEvent> {
       onTracksNotPlayableForType: {
         audio: contentInfos.onAudioTracksNotPlayable,
         video: contentInfos.onVideoTracksNotPlayable,
+        text: "continue",
       },
     });
     contentInfos.tracksStore = tracksStore;

src/main_thread/tracks_store/media_element_tracks_store.ts

@@ -212,9 +212,10 @@ export default class MediaElementTracksStore extends EventEmitter<IMediaElementT
    * MediaElementTracksStore's API(s).
    * Allows to "lock on" a track, to be sure that choice will be kept even
    * through audio track list updates, as long as it is still available.
+   * `null` if the audio track was disabled.
    * `undefined` if the audio track was not manually set.
    */
-  private _audioTrackLockedOn: ICompatAudioTrack | undefined;
+  private _audioTrackLockedOn: ICompatAudioTrack | undefined | null;
 
   /**
    * Last text track manually set active through the corresponding
@@ -322,6 +323,14 @@ export default class MediaElementTracksStore extends EventEmitter<IMediaElementT
     this._videoTrackLockedOn = null;
   }
 
+  /**
+   * Disable the currently-active audio track, if one.
+   */
+  public disableAudioTrack(): void {
+    disableAudioTracks(this._audioTracks);
+    this._audioTrackLockedOn = null;
+  }
+
   /**
    * Update the currently active video track by setting the wanted video track's
    * ID property.
@@ -809,3 +818,15 @@ function disableVideoTracks(videoTracks: Array<{ nativeTrack: ICompatVideoTrack
     nativeTrack.selected = false;
   }
 }
+
+/**
+ * Disable all audio track elements in the given array from showing.
+ * Note that browser need to support that use case, which they often do not.
+ * @param {Array.<Object>} audioTracks
+ */
+function disableAudioTracks(audioTracks: Array<{ nativeTrack: ICompatAudioTrack }>) {
+  for (let i = 0; i < audioTracks.length; i++) {
+    const { nativeTrack } = audioTracks[i];
+    nativeTrack.enabled = false;
+  }
+}