rx-player 4.0.0-dev.2023102700 → 4.0.0-dev.2023110700

package/dist/_esm5.processed/core/api/public_api.d.ts

@@ -1,7 +1,7 @@
 /**
  * Copyright 2015 CANAL+ Group
  *
- * Licensed under the Apache License, Version 2.0 (the "License");publicapi
+ * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
@@ -15,8 +15,8 @@
  */
 import { IErrorCode, IErrorType } from "../../errors";
 import { IFeature } from "../../features";
-import Manifest, { Adaptation, Representation } from "../../manifest";
-import { IAudioRepresentation, IAudioTrack, IAudioTrackSetting, IAvailableAudioTrack, IAvailableTextTrack, IAvailableVideoTrack, IBrokenRepresentationsLockContext, IConstructorOptions, IKeySystemConfigurationOutput, ILoadVideoOptions, ILockedAudioRepresentationsSettings, ILockedVideoRepresentationsSettings, ITrackUpdateEventPayload, IRepresentationListUpdateContext, IPeriod, IPeriodChangeEvent, IPlayerError, IPlayerState, IPositionUpdate, IStreamEvent, ITextTrack, IVideoRepresentation, ITextTrackSetting, IVideoTrack, IVideoTrackSetting } from "../../public_types";
+import Manifest from "../../manifest";
+import { IAdaptation, IAudioTrack, IAudioTrackPreference, IAvailableAudioTrack, IAvailableTextTrack, IAvailableVideoTrack, IBifThumbnail, IBitrateEstimate, IConstructorOptions, IDecipherabilityUpdateContent, IKeySystemConfigurationOutput, ILoadVideoOptions, IPeriod, IPlayerError, IPlayerState, IPositionUpdate, IRepresentation, IStreamEvent, ITextTrack, ITextTrackPreference, IVideoTrack, IVideoTrackPreference } from "../../public_types";
 import EventEmitter, { IListener } from "../../utils/event_emitter";
 import Logger from "../../utils/logger";
 import { IBufferedChunk, IBufferType } from "../segment_buffers";
@@ -73,12 +73,20 @@ declare class Player extends EventEmitter<IPublicAPIEvent> {
      * `null` when no content is currently loading or loaded.
      */
     private _priv_contentInfos;
+    /** List of favorite audio tracks, in preference order.  */
+    private _priv_preferredAudioTracks;
+    /** List of favorite text tracks, in preference order.  */
+    private _priv_preferredTextTracks;
+    /** List of favorite video tracks, in preference order. */
+    private _priv_preferredVideoTracks;
     /** If `true` trickMode video tracks will be chosen if available. */
     private _priv_preferTrickModeTracks;
     /** Refer to last picture in picture event received. */
     private _priv_pictureInPictureRef;
-    /** Store wanted configuration for the `videoResolutionLimit` option. */
-    private readonly _priv_videoResolutionLimit;
+    /** Store wanted configuration for the `limitVideoWidth` option. */
+    private readonly _priv_limitVideoWidth;
+    /** Store wanted configuration for the `throttleWhenHidden` option. */
+    private readonly _priv_throttleWhenHidden;
     /** Store wanted configuration for the `throttleVideoBitrateWhenHidden` option. */
     private readonly _priv_throttleVideoBitrateWhenHidden;
     /** Store volume when mute is called, to restore it on unmute. */
@@ -91,6 +99,8 @@ declare class Player extends EventEmitter<IPublicAPIEvent> {
      * on stop.
      */
     private _priv_contentEventsMemory;
+    /** Determines whether or not the player should stop at the end of video playback. */
+    private readonly _priv_stopAtEnd;
     /**
      * Information that can be relied on once `reload` is called.
      * It should refer to the last content being played.
@@ -175,6 +185,29 @@ declare class Player extends EventEmitter<IPublicAPIEvent> {
      * @returns {Object|null} - The current Error (`null` when no error).
      */
     getError(): Error | null;
+    /**
+     * Returns manifest/playlist object.
+     * null if the player is STOPPED.
+     * @deprecated
+     * @returns {Manifest|null} - The current Manifest (`null` when not known).
+     */
+    getManifest(): Manifest | null;
+    /**
+     * Returns Adaptations (tracks) for every currently playing type
+     * (audio/video/text...).
+     * @deprecated
+     * @returns {Object|null} - The current Adaptation objects, per type (`null`
+     * when none is known for now.
+     */
+    getCurrentAdaptations(): Partial<Record<IBufferType, IAdaptation | null>> | null;
+    /**
+     * Returns representations (qualities) for every currently playing type
+     * (audio/video/text...).
+     * @deprecated
+     * @returns {Object|null} - The current Representation objects, per type
+     * (`null` when none is known for now.
+     */
+    getCurrentRepresentations(): Partial<Record<IBufferType, IRepresentation | null>> | null;
     /**
      * Returns the media DOM element used by the player.
      * You should not its HTML5 API directly and use the player's method instead,
@@ -183,6 +216,12 @@ declare class Player extends EventEmitter<IPublicAPIEvent> {
      * disposed)
      */
     getVideoElement(): HTMLMediaElement | null;
+    /**
+     * If one returns the first native text-track element attached to the media element.
+     * @deprecated
+     * @returns {TextTrack} - The native TextTrack attached (`null` when none)
+     */
+    getNativeTextTrack(): TextTrack | null;
     /**
      * Returns the player's current state.
      * @returns {string} - The current Player's state
@@ -223,12 +262,12 @@ declare class Player extends EventEmitter<IPublicAPIEvent> {
      */
     areTrickModeTracksEnabled(): boolean;
     /**
-     * Returns the URL(s) of the currently considered Manifest, or of the content for
+     * Returns the url of the currently considered Manifest, or of the content for
      * directfile content.
-     * @returns {Array.<string>|undefined} - Current URL. `undefined` if not known
-     * or no URL yet.
+     * @returns {string|undefined} - Current URL. `undefined` if not known or no
+     * URL yet.
      */
-    getContentUrls(): string[] | undefined;
+    getUrl(): string | undefined;
     /**
      * Update URL of the content currently being played (e.g. DASH's MPD).
      * @param {Array.<string>|undefined} urls - URLs to reach that content /
@@ -245,14 +284,28 @@ declare class Player extends EventEmitter<IPublicAPIEvent> {
      * NaN if no video is playing.
      * @returns {Number}
      */
-    getMediaDuration(): number;
+    getVideoDuration(): number;
     /**
      * Returns in seconds the difference between:
      *   - the end of the current contiguous loaded range.
      *   - the current time
      * @returns {Number}
      */
-    getCurrentBufferGap(): number;
+    getVideoBufferGap(): number;
+    /**
+     * Returns in seconds the difference between:
+     *   - the end of the current contiguous loaded range.
+     *   - the start of the current contiguous loaded range.
+     * @returns {Number}
+     */
+    getVideoLoadedTime(): number;
+    /**
+     * Returns in seconds the difference between:
+     *   - the current time.
+     *   - the start of the current contiguous loaded range.
+     * @returns {Number}
+     */
+    getVideoPlayedTime(): number;
     /**
      * Get the current position, in s, in wall-clock time.
      * That is:
@@ -351,25 +404,55 @@ declare class Player extends EventEmitter<IPublicAPIEvent> {
         preferTrickModeTracks?: boolean;
     }): void;
     /**
-     * Returns video Representation currently considered for the current Period.
-     *
-     * Returns `null` if no video track is playing for the current Period.
-     *
-     * Returns `undefined` either when are not currently playing any Period or
-     * when we don't know which Representation is playing.
-     * @returns {Object|null|undefined}
+     * Returns all available bitrates for the current video Adaptation.
+     * @returns {Array.<Number>}
      */
-    getVideoRepresentation(): IVideoRepresentation | null | undefined;
+    getAvailableVideoBitrates(): number[];
     /**
-     * Returns audio Representation currently considered for the current Period.
-     *
-     * Returns `null` if no audio track is playing for the current Period.
-     *
-     * Returns `undefined` either when are not currently playing any Period or
-     * when we don't know which Representation is playing.
-     * @returns {Object|null|undefined}
+     * Returns all available bitrates for the current audio Adaptation.
+     * @returns {Array.<Number>}
+     */
+    getAvailableAudioBitrates(): number[];
+    /**
+     * Returns the manual audio bitrate set. -1 if in AUTO mode.
+     * @returns {Number}
+     */
+    getManualAudioBitrate(): number;
+    /**
+     * Returns the manual video bitrate set. -1 if in AUTO mode.
+     * @returns {Number}
      */
-    getAudioRepresentation(): IAudioRepresentation | null | undefined;
+    getManualVideoBitrate(): number;
+    /**
+     * Returns currently considered bitrate for video segments.
+     * @returns {Number|undefined}
+     */
+    getVideoBitrate(): number | undefined;
+    /**
+     * Returns currently considered bitrate for audio segments.
+     * @returns {Number|undefined}
+     */
+    getAudioBitrate(): number | undefined;
+    /**
+     * Returns minimum wanted video bitrate currently set.
+     * @returns {Number}
+     */
+    getMinVideoBitrate(): number;
+    /**
+     * Returns minimum wanted audio bitrate currently set.
+     * @returns {Number}
+     */
+    getMinAudioBitrate(): number;
+    /**
+     * Returns maximum wanted video bitrate currently set.
+     * @returns {Number}
+     */
+    getMaxVideoBitrate(): number;
+    /**
+     * Returns maximum wanted audio bitrate currently set.
+     * @returns {Number}
+     */
+    getMaxAudioBitrate(): number;
     /**
      * Play/Resume the current video.
      * @returns {Promise}
@@ -391,6 +474,23 @@ declare class Player extends EventEmitter<IPublicAPIEvent> {
     } | {
         wallClockTime: number;
     }): number;
+    /**
+     * Returns true if the media element is full screen.
+     * @deprecated
+     * @returns {Boolean}
+     */
+    isFullscreen(): boolean;
+    /**
+     * Set/exit fullScreen.
+     * @deprecated
+     * @param {Boolean} [goFull=true] - if false, exit full screen.
+     */
+    setFullscreen(goFull?: boolean): void;
+    /**
+     * Exit from full screen mode.
+     * @deprecated
+     */
+    exitFullscreen(): void;
     /**
      * Returns the current player's audio volume on the media element.
      * From 0 (no audio) to 1 (maximum volume).
@@ -416,6 +516,38 @@ declare class Player extends EventEmitter<IPublicAPIEvent> {
      * If the volume was set to 0, set a default volume instead (see config).
      */
     unMute(): void;
+    /**
+     * Force the video bitrate to a given value. Act as a ceil.
+     * -1 to set it on AUTO Mode
+     * @param {Number} btr
+     */
+    setVideoBitrate(btr: number): void;
+    /**
+     * Force the audio bitrate to a given value. Act as a ceil.
+     * -1 to set it on AUTO Mode
+     * @param {Number} btr
+     */
+    setAudioBitrate(btr: number): void;
+    /**
+     * Update the minimum video bitrate the user can switch to.
+     * @param {Number} btr
+     */
+    setMinVideoBitrate(btr: number): void;
+    /**
+     * Update the minimum audio bitrate the user can switch to.
+     * @param {Number} btr
+     */
+    setMinAudioBitrate(btr: number): void;
+    /**
+     * Update the maximum video bitrate the user can switch to.
+     * @param {Number} btr
+     */
+    setMaxVideoBitrate(btr: number): void;
+    /**
+     * Update the maximum audio bitrate the user can switch to.
+     * @param {Number} btr
+     */
+    setMaxAudioBitrate(btr: number): void;
     /**
      * Set the max buffer size for the buffer behind the current position.
      * Every buffer data before will be removed.
@@ -460,7 +592,13 @@ declare class Player extends EventEmitter<IPublicAPIEvent> {
      * @returns {Number}
      */
     getMaxVideoBufferSize(): number;
-    getCurrentPeriod(): IPeriod | null;
+    /**
+     * Returns type of current keysystem (e.g. playready, widevine) if the content
+     * is encrypted. null otherwise.
+     * @deprecated
+     * @returns {string|null}
+     */
+    getCurrentKeySystem(): string | null;
     /**
      * Returns both the name of the key system (e.g. `"com.widevine.alpha"`) and
      * the `MediaKeySystemConfiguration` currently associated to the
@@ -471,86 +609,108 @@ declare class Player extends EventEmitter<IPublicAPIEvent> {
      */
     getKeySystemConfiguration(): IKeySystemConfigurationOutput | null;
     /**
-     * Returns the list of available Periods for which the current audio, video or
-     * text track can now be changed.
-     * @returns {Array.<Object>}
-     */
-    getAvailablePeriods(): IPeriod[];
-    /**
-     * Returns every available audio tracks for a given Period - or the current
-     * one if no `periodId` is given.
-     * @param {string|undefined} [periodId]
-     * @returns {Array.<Object>}
+     * Returns every available audio tracks for the current Period.
+     * @returns {Array.<Object>|null}
      */
-    getAvailableAudioTracks(periodId?: string | undefined): IAvailableAudioTrack[];
+    getAvailableAudioTracks(): IAvailableAudioTrack[];
     /**
-     * Returns every available text tracks for a given Period - or the current
-     * one if no `periodId` is given.
-     * @param {string|undefined} [periodId]
-     * @returns {Array.<Object>}
+     * Returns every available text tracks for the current Period.
+     * @returns {Array.<Object>|null}
      */
-    getAvailableTextTracks(periodId?: string | undefined): IAvailableTextTrack[];
+    getAvailableTextTracks(): IAvailableTextTrack[];
     /**
      * Returns every available video tracks for the current Period.
-     * @param {string|undefined} [periodId]
-     * @returns {Array.<Object>}
+     * @returns {Array.<Object>|null}
      */
-    getAvailableVideoTracks(periodId?: string | undefined): IAvailableVideoTrack[];
+    getAvailableVideoTracks(): IAvailableVideoTrack[];
     /**
      * Returns currently chosen audio language for the current Period.
-     * @param {string|undefined} [periodId]
-     * @returns {Object|null|undefined}
+     * @returns {string}
      */
-    getAudioTrack(periodId?: string | undefined): IAudioTrack | null | undefined;
+    getAudioTrack(): IAudioTrack | null | undefined;
     /**
      * Returns currently chosen subtitle for the current Period.
-     * @param {string|undefined} [periodId]
-     * @returns {Object|null|undefined}
+     * @returns {string}
      */
-    getTextTrack(periodId?: string | undefined): ITextTrack | null | undefined;
+    getTextTrack(): ITextTrack | null | undefined;
     /**
      * Returns currently chosen video track for the current Period.
-     * @param {string|undefined} [periodId]
-     * @returns {Object|null|undefined}
+     * @returns {string}
      */
-    getVideoTrack(periodId?: string | undefined): IVideoTrack | null | undefined;
+    getVideoTrack(): IVideoTrack | null | undefined;
     /**
      * Update the audio language for the current Period.
-     * @param {string | object} arg
-     * @throws Error - the current content has no TracksStore.
+     * @param {string} audioId
+     * @throws Error - the current content has no TrackChoiceManager.
      * @throws Error - the given id is linked to no audio track.
      */
-    setAudioTrack(arg: string | IAudioTrackSetting): void;
+    setAudioTrack(audioId: string): void;
     /**
      * Update the text language for the current Period.
-     * @param {string | Object} arg
-     * @throws Error - the current content has no TracksStore.
+     * @param {string} sub
+     * @throws Error - the current content has no TrackChoiceManager.
      * @throws Error - the given id is linked to no text track.
      */
-    setTextTrack(arg: string | ITextTrackSetting): void;
+    setTextTrack(textId: string): void;
     /**
      * Disable subtitles for the current content.
-     * @param {string|undefined} [periodId]
      */
-    disableTextTrack(periodId?: string | undefined): void;
+    disableTextTrack(): void;
     /**
      * Update the video track for the current Period.
-     * @param {string | Object} arg
-     * @throws Error - the current content has no TracksStore.
+     * @param {string} videoId
+     * @throws Error - the current content has no TrackChoiceManager.
      * @throws Error - the given id is linked to no video track.
      */
-    setVideoTrack(arg: string | IVideoTrackSetting): void;
+    setVideoTrack(videoId: string): void;
     /**
      * Disable video track for the current content.
-     * @param {string|undefined} [periodId]
      */
-    disableVideoTrack(periodId?: string | undefined): void;
-    lockVideoRepresentations(arg: string[] | ILockedVideoRepresentationsSettings): void;
-    lockAudioRepresentations(arg: string[] | ILockedAudioRepresentationsSettings): void;
-    getLockedVideoRepresentations(periodId?: string | undefined): string[] | null;
-    getLockedAudioRepresentations(periodId?: string | undefined): string[] | null;
-    unlockVideoRepresentations(periodId?: string | undefined): void;
-    unlockAudioRepresentations(periodId?: string | undefined): void;
+    disableVideoTrack(): void;
+    /**
+     * Returns the current list of preferred audio tracks, in preference order.
+     * @returns {Array.<Object>}
+     */
+    getPreferredAudioTracks(): IAudioTrackPreference[];
+    /**
+     * Returns the current list of preferred text tracks, in preference order.
+     * @returns {Array.<Object>}
+     */
+    getPreferredTextTracks(): ITextTrackPreference[];
+    /**
+     * Returns the current list of preferred text tracks, in preference order.
+     * @returns {Array.<Object>}
+     */
+    getPreferredVideoTracks(): IVideoTrackPreference[];
+    /**
+     * Set the list of preferred audio tracks, in preference order.
+     * @param {Array.<Object>} tracks
+     * @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(tracks: IAudioTrackPreference[], shouldApply?: boolean): void;
+    /**
+     * Set the list of preferred text tracks, in preference order.
+     * @param {Array.<Object>} tracks
+     * @param {boolean} shouldApply - `true` if those preferences should be
+     * applied on the currently loaded Periods. `false` if it should only
+     * be applied to new content.
+     */
+    setPreferredTextTracks(tracks: ITextTrackPreference[], shouldApply?: boolean): void;
+    /**
+     * Set the list of preferred text tracks, in preference order.
+     * @param {Array.<Object>} tracks
+     * @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(tracks: IVideoTrackPreference[], shouldApply?: boolean): void;
+    /**
+     * @returns {Array.<Object>|null}
+     * @deprecated
+     */
+    getImageTrackData(): IBifThumbnail[] | null;
     /**
      * Get minimum seek-able position.
      * @returns {number}
@@ -570,16 +730,6 @@ declare class Player extends EventEmitter<IPublicAPIEvent> {
      * @returns {Array.<Object>|null}
      */
     __priv_getSegmentBufferContent(bufferType: IBufferType): IBufferedChunk[] | null;
-    /**
-     * /!\ For tools use only! Do not touch!
-     *
-     * Returns manifest/playlist object.
-     * null if the player is STOPPED.
-     * @returns {Manifest|null} - The current Manifest (`null` when not known).
-     */
-    __priv_getManifest(): Manifest | null;
-    __priv_getCurrentAdaptation(): Partial<Record<IBufferType, Adaptation | null>> | null;
-    __priv_getCurrentRepresentations(): Partial<Record<IBufferType, Representation | null>> | null;
     /**
      * Reset all state properties relative to a playing content.
      */
@@ -636,7 +786,15 @@ declare class Player extends EventEmitter<IPublicAPIEvent> {
      *
      * @param {Object} value
      */
-    private _priv_onBitrateEstimateChange;
+    private _priv_onBitrateEstimationChange;
+    /**
+     * Triggered each time a textTrack is added to the video DOM Element.
+     *
+     * Trigger the right Player Event.
+     *
+     * @param {Array.<TextTrackElement>} tracks
+     */
+    private _priv_onNativeTextTracksNext;
     /**
      * Triggered each time the player state updates.
      *
@@ -654,6 +812,23 @@ declare class Player extends EventEmitter<IPublicAPIEvent> {
      * @param {Object} observation
      */
     private _priv_triggerPositionUpdate;
+    /**
+     * Trigger one of the "availableBitratesChange" event only if it changed from
+     * the previously stored value.
+     * @param {string} event
+     * @param {Array.<number>} newVal
+     * @param {Object} currentContentCancelSignal
+     */
+    private _priv_triggerAvailableBitratesChangeEvent;
+    /**
+     * Trigger one of the "bitrateChange" event only if it changed from the
+     * previously stored value.
+     * @param {string} event
+     * @param {number} newVal
+     * @param {Object} currentContentCancelSignal
+     */
+    private _priv_triggerCurrentBitrateChangeEvent;
+    private _priv_getCurrentRepresentations;
     /**
      * @param {string} evt
      * @param {*} arg
@@ -661,31 +836,12 @@ declare class Player extends EventEmitter<IPublicAPIEvent> {
      */
     private _priv_triggerEventIfNotStopped;
     /**
+     * @param {Object} defaultAudioTrack
+     * @param {Object} defaultTextTrack
      * @param {Object} cancelSignal
      * @returns {Object}
      */
-    private _priv_initializeMediaElementTracksStore;
-    private _priv_callTracksStoreGetterSetter;
-    /**
-     * Method to call when some event lead to a high for possibility that the
-     * available tracks for the given type have changed.
-     * Send the corresponding `available*Tracks` change event with the last
-     * available tracks.
-     *
-     * @param {string} trackType
-     * @param {Object|undefined} [oPeriodRef] - optional period object used by the
-     * `tracksStore` API, allows to optimize the method by bypassing this step.
-     */
-    private _priv_onAvailableTracksMayHaveChanged;
-    /**
-     * Method to call when a fatal error lead to the stopping of the current
-     * content.
-     *
-     * @param {*} err - The error encountered.
-     * @param {Object} contentInfos - The `IPublicApiContentInfos` object linked
-     * to the content for which the error was received.
-     */
-    private _priv_onFatalError;
+    private _priv_initializeMediaElementTrackChoiceManager;
 }
 /** Every events sent by the RxPlayer's public API. */
 interface IPublicAPIEvent {
@@ -694,21 +850,26 @@ interface IPublicAPIEvent {
     audioTrackChange: IAudioTrack | null;
     textTrackChange: ITextTrack | null;
     videoTrackChange: IVideoTrack | null;
-    audioRepresentationChange: IVideoRepresentation | null;
-    videoRepresentationChange: IAudioRepresentation | null;
+    audioBitrateChange: number;
+    videoBitrateChange: number;
+    imageTrackUpdate: {
+        data: IBifThumbnail[];
+    };
+    fullscreenChange: boolean;
+    bitrateEstimationChange: IBitrateEstimate;
     volumeChange: number;
     error: IPlayerError | Error;
     warning: IPlayerError | Error;
-    periodChange: IPeriodChangeEvent;
+    nativeTextTracksChange: TextTrack[];
+    periodChange: IPeriod;
+    availableAudioBitratesChange: number[];
+    availableVideoBitratesChange: number[];
     availableAudioTracksChange: IAvailableAudioTrack[];
     availableTextTracksChange: IAvailableTextTrack[];
     availableVideoTracksChange: IAvailableVideoTrack[];
+    decipherabilityUpdate: IDecipherabilityUpdateContent[];
     play: null;
     pause: null;
-    newAvailablePeriods: IPeriod[];
-    brokenRepresentationsLock: IBrokenRepresentationsLockContext;
-    trackUpdate: ITrackUpdateEventPayload;
-    representationListUpdate: IRepresentationListUpdateContext;
     seeking: null;
     seeked: null;
     streamEvent: IStreamEvent;