rx-player 4.0.0-dev.2023120600 → 4.0.0-dev.2023121900

package/dist/_esm5.processed/core/api/{track_management/media_element_tracks_store.d.ts → tracks_management/media_element_track_choice_manager.d.ts}

@@ -13,10 +13,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { IAudioTrack, ITextTrack, IVideoTrack, IAvailableVideoTrack, IAvailableAudioTrack, IAvailableTextTrack } from "../../../public_types";
+import { IAudioTrack, ITextTrack, IVideoTrack, IAudioTrackPreference, ITextTrackPreference, IVideoTrackPreference, IAvailableVideoTrack, IAvailableAudioTrack, IAvailableTextTrack } from "../../../public_types";
 import EventEmitter from "../../../utils/event_emitter";
-/** Events emitted by the MediaElementTracksStore. */
-interface IMediaElementTracksStoreEvents {
+/** Events emitted by the MediaElementTrackChoiceManager. */
+interface IMediaElementTrackChoiceManagerEvents {
     availableVideoTracksChange: IAvailableVideoTrack[];
     availableAudioTracksChange: IAvailableAudioTrack[];
     availableTextTracksChange: IAvailableTextTrack[];
@@ -26,9 +26,24 @@ interface IMediaElementTracksStoreEvents {
 }
 /**
  * Manage video, audio and text tracks for current direct file content.
- * @class MediaElementTracksStore
+ * @class MediaElementTrackChoiceManager
  */
-export default class MediaElementTracksStore extends EventEmitter<IMediaElementTracksStoreEvents> {
+export default class MediaElementTrackChoiceManager extends EventEmitter<IMediaElementTrackChoiceManagerEvents> {
+    /**
+     * Array of preferred settings for audio tracks.
+     * Sorted by order of preference descending.
+     */
+    private _preferredAudioTracks;
+    /**
+     * Array of preferred languages for text tracks.
+     * Sorted by order of preference descending.
+     */
+    private _preferredTextTracks;
+    /**
+     * Array of preferred settings for video tracks.
+     * Sorted by order of preference descending.
+     */
+    private _preferredVideoTracks;
     /** List every available audio tracks available on the media element. */
     private _audioTracks;
     /** List every available text tracks available on the media element. */
@@ -49,7 +64,7 @@ export default class MediaElementTracksStore extends EventEmitter<IMediaElementT
     private _nativeTextTracks;
     /**
      * Last audio track manually set active through the corresponding
-     * MediaElementTracksStore's API(s).
+     * MediaElementTrackChoiceManager'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.
      * `undefined` if the audio track was not manually set.
@@ -57,7 +72,7 @@ export default class MediaElementTracksStore extends EventEmitter<IMediaElementT
     private _audioTrackLockedOn;
     /**
      * Last text track manually set active through the corresponding
-     * MediaElementTracksStore's API(s).
+     * MediaElementTrackChoiceManager's API(s).
      * Allows to "lock on" a track, to be sure that choice will be kept even
      * through text track list updates, as long as it is still available.
      * `null` if the text track was disabled.
@@ -66,7 +81,7 @@ export default class MediaElementTracksStore extends EventEmitter<IMediaElementT
     private _textTrackLockedOn;
     /**
      * Last video track manually set active through the corresponding
-     * MediaElementTracksStore's API(s).
+     * MediaElementTrackChoiceManager's API(s).
      * Allows to "lock on" a track, to be sure that choice will be kept even
      * through video track list updates, as long as it is still available.
      * `null` if the video track was disabled.
@@ -74,6 +89,30 @@ export default class MediaElementTracksStore extends EventEmitter<IMediaElementT
      */
     private _videoTrackLockedOn;
     constructor(mediaElement: HTMLMediaElement);
+    /**
+     * Set the list of preferred audio tracks, in preference order.
+     * @param {Array.<Object>} preferredAudioTracks
+     * @param {boolean} shouldApply - `true` if those preferences should be
+     * applied on the currently loaded Period. `false` if it should only
+     * be applied to new content.
+     */
+    setPreferredAudioTracks(preferredAudioTracks: IAudioTrackPreference[], shouldApply: boolean): void;
+    /**
+     * Set the list of preferred text tracks, in preference order.
+     * @param {Array.<Object>} preferredTextTracks
+     * @param {boolean} shouldApply - `true` if those preferences should be
+     * applied on the currently loaded Period. `false` if it should only
+     * be applied to new content.
+     */
+    setPreferredTextTracks(preferredTextTracks: ITextTrackPreference[], shouldApply: boolean): void;
+    /**
+     * Set the list of preferred video tracks, in preference order.
+     * @param {Array.<Object>} preferredVideoTracks
+     * @param {boolean} shouldApply - `true` if those preferences should be
+     * applied on the currently loaded Period. `false` if it should only
+     * be applied to new content.
+     */
+    setPreferredVideoTracks(preferredVideoTracks: IVideoTrackPreference[], shouldApply: boolean): void;
     /**
      * Update the currently active audio track by setting the wanted audio track's
      * ID property.
@@ -140,7 +179,7 @@ export default class MediaElementTracksStore extends EventEmitter<IMediaElementT
      */
     getAvailableVideoTracks(): IAvailableVideoTrack[];
     /**
-     * Free the resources used by the MediaElementTracksStore.
+     * Free the resources used by the MediaElementTrackChoiceManager.
      */
     dispose(): void;
     /**
@@ -149,39 +188,60 @@ export default class MediaElementTracksStore extends EventEmitter<IMediaElementT
      * `null` if no audio track is chosen.
      * @returns {Object|undefined|null}
      */
-    private _getCurrentAudioTrack;
+    private _getPrivateChosenAudioTrack;
     /**
      * Get information about the currently chosen video track.
      * `undefined` if we cannot know it.
      * `null` if no video track is chosen.
      * @returns {Object|undefined|null}
      */
-    private _getCurrentVideoTrack;
+    private _getPrivateChosenVideoTrack;
     /**
      * Get information about the currently chosen text track.
      * `undefined` if we cannot know it.
      * `null` if no text track is chosen.
      * @returns {Object|undefined|null}
      */
-    private _getCurrentTextTrack;
+    private _getPrivateChosenTextTrack;
     /**
      * Iterate over every available audio tracks on the media element and either:
      *   - if the last manually set audio track is found, set that one.
+     *   - if not, set the most preferred one
      *   - if we still do not find an optimal track, let the one chosen by default
      */
-    private _setPreviouslyLockedAudioTrack;
+    private _setOptimalAudioTrack;
+    /**
+     * Try to find a track corresponding to the audio track preferences:
+     *   - if found, set it as the active track
+     *   - if not found, let the chosen audio track by default
+     */
+    private _applyAudioPreferences;
     /**
      * Iterate over every available text tracks on the media element and either:
      *   - if the last manually set text track is found, set that one.
+     *   - if not, set the most preferred one
      *   - if we still do not find an optimal track, just disable it.
      */
-    private _setPreviouslyLockedTextTrack;
+    private _setOptimalTextTrack;
+    /**
+     * Try to find a track corresponding to the text track preferences:
+     *   - if found, set it as the active track
+     *   - if not found, let the chosen text track by default
+     */
+    private _applyTextPreferences;
     /**
      * Iterate over every available video tracks on the media element and either:
      *   - if the last manually set video track is found, set that one.
+     *   - if not, set the most preferred one
      *   - if we still do not find an optimal track, let the one chosen by default
      */
-    private _setPreviouslyLockedVideoTrack;
+    private _setOptimalVideoTrack;
+    /**
+     * Try to find a track corresponding to the text track preferences:
+     *   - if found, set it as the active track
+     *   - if not found, let the chosen text track by default
+     */
+    private _applyVideoPreferences;
     /**
      * Monitor native tracks add, remove and change callback and trigger the
      * change events.