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

package/dist/_esm5.processed/core/api/track_management/track_dispatcher.js

@@ -0,0 +1,158 @@
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+import { MediaError } from "../../../errors";
+import EventEmitter from "../../../utils/event_emitter";
+import SharedReference from "../../../utils/reference";
+import TaskCanceller from "../../../utils/task_canceller";
+/**
+ * Class handling track changes and quality locking for a single Period and
+ * Adaptation type.
+ * @class TrackDispatcher
+ */
+var TrackDispatcher = /** @class */ (function (_super) {
+    __extends(TrackDispatcher, _super);
+    /**
+     * Create a new `TrackDispatcher` by giving its Reference and an initial track
+     * setting.
+     * This constructor will update the Reference with the right preferences
+     * synchronously.
+     * @param {Object} manifest
+     * @param {Object} adaptationRef
+     * @param {Object|null} initialTrackInfo
+     */
+    function TrackDispatcher(manifest, adaptationRef, initialTrackInfo) {
+        var _this = _super.call(this) || this;
+        _this._canceller = new TaskCanceller();
+        _this._manifest = manifest;
+        _this._adaptationRef = adaptationRef;
+        if (initialTrackInfo === null) {
+            _this._lastEmitted = initialTrackInfo;
+            adaptationRef.setValue(null);
+            return _this;
+        }
+        var reference = _this._constructLockedRepresentationsReference(initialTrackInfo);
+        _this._lastEmitted = { adaptation: initialTrackInfo.adaptation,
+            switchingMode: initialTrackInfo.switchingMode,
+            lockedRepresentations: null };
+        adaptationRef.setValue({ adaptation: initialTrackInfo.adaptation,
+            switchingMode: initialTrackInfo.switchingMode,
+            representations: reference });
+        return _this;
+    }
+    /**
+     * Update the wanted track on the Reference linked to this `TrackDispatcher`.
+     * @param {Object|null} newTrackInfo
+     */
+    TrackDispatcher.prototype.updateTrack = function (newTrackInfo) {
+        if (newTrackInfo === null) {
+            if (this._lastEmitted === null) {
+                return;
+            }
+            this._canceller.cancel();
+            // has no point but let's still create one for simplicity sake
+            this._canceller = new TaskCanceller();
+            this._lastEmitted = null;
+            this._adaptationRef.setValue(null);
+            return;
+        }
+        var adaptation = newTrackInfo.adaptation, switchingMode = newTrackInfo.switchingMode;
+        this._canceller.cancel();
+        this._canceller = new TaskCanceller();
+        var reference = this._constructLockedRepresentationsReference(newTrackInfo);
+        this._lastEmitted = { adaptation: adaptation, switchingMode: switchingMode, lockedRepresentations: null };
+        this._adaptationRef.setValue({ adaptation: adaptation, switchingMode: switchingMode, representations: reference });
+    };
+    /**
+     * Create a shared reference which will emit the wanted locked Representations
+     * based on the current capabilities and the last user settings.
+     *
+     * @param {Object} trackInfo
+     * @returns {Object}
+     */
+    TrackDispatcher.prototype._constructLockedRepresentationsReference = function (trackInfo) {
+        var manifest = this._manifest;
+        /* Initialize it. Will be at its true value at the end of the function. */
+        var reference = new SharedReference({
+            representations: [],
+            switchingMode: "lazy",
+        });
+        /* eslint-disable-next-line @typescript-eslint/no-this-alias */
+        var self = this;
+        manifest.addEventListener("decipherabilityUpdate", updateReferenceIfNeeded);
+        manifest.addEventListener("manifestUpdate", updateReferenceIfNeeded);
+        this._canceller.signal.register(removeListeners);
+        trackInfo.lockedRepresentations.onUpdate(updateReferenceIfNeeded, {
+            clearSignal: this._canceller.signal,
+            emitCurrentValue: false,
+        });
+        updateReferenceIfNeeded();
+        return reference;
+        function updateReferenceIfNeeded() {
+            var repSettings = trackInfo.lockedRepresentations.getValue();
+            var switchingMode;
+            /** Representations for which a `RepresentationStream` can be created. */
+            var playableRepresentations;
+            if (repSettings === null) { // unlocking
+                playableRepresentations = trackInfo.adaptation.getPlayableRepresentations();
+                // No need to remove the previous content when unlocking
+                switchingMode = "lazy";
+            }
+            else {
+                var representations = repSettings.representations;
+                switchingMode = repSettings.switchingMode;
+                playableRepresentations = representations.filter(function (r) { return r.isPlayable(); });
+                if (playableRepresentations.length === 0) {
+                    self.trigger("noPlayableLockedRepresentation", null);
+                    return;
+                }
+            }
+            if (playableRepresentations.length <= 0) {
+                var adaptationType = trackInfo.adaptation.type;
+                var noRepErr = new MediaError("NO_PLAYABLE_REPRESENTATION", "No Representation in the chosen " +
+                    adaptationType + " Adaptation can be played", { adaptation: trackInfo.adaptation });
+                throw noRepErr;
+            }
+            // Check if Locked Representations have changed
+            var oldRef = reference.getValue();
+            var sortedReps = playableRepresentations.slice().sort();
+            if (sortedReps.length !== oldRef.representations.length) {
+                reference.setValue({ representations: sortedReps, switchingMode: switchingMode });
+                return;
+            }
+            for (var i = 0; i < sortedReps.length; i++) {
+                if (oldRef.representations[i].id !== sortedReps[i].id) {
+                    reference.setValue({ representations: sortedReps, switchingMode: switchingMode });
+                    return;
+                }
+            }
+        }
+        function removeListeners() {
+            manifest.removeEventListener("decipherabilityUpdate", updateReferenceIfNeeded);
+            manifest.removeEventListener("manifestUpdate", updateReferenceIfNeeded);
+        }
+    };
+    /**
+     * Free the resources (e.g. `Manifest` event listeners) linked to this
+     * `TrackDispatcher`.
+     */
+    TrackDispatcher.prototype.dispose = function () {
+        this.removeEventListener();
+        this._canceller.cancel();
+        this._adaptationRef.finish();
+    };
+    return TrackDispatcher;
+}(EventEmitter));
+export default TrackDispatcher;

package/dist/_esm5.processed/core/api/track_management/tracks_store.d.ts

@@ -0,0 +1,406 @@
+/**
+ * Copyright 2015 CANAL+ Group
+ *
+ * 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
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import Manifest, { Adaptation, Period } from "../../../manifest";
+import { IAudioRepresentationsSwitchingMode, IAudioTrack, IAudioTrackSwitchingMode, ITrackUpdateEventPayload, IAvailableAudioTrack, IAvailableTextTrack, IAvailableVideoTrack, IBrokenRepresentationsLockContext, IPeriod, ITextTrack, IVideoRepresentationsSwitchingMode, IVideoTrack, IVideoTrackSwitchingMode } from "../../../public_types";
+import EventEmitter from "../../../utils/event_emitter";
+import SharedReference from "../../../utils/reference";
+import { IAdaptationChoice, IRepresentationsChoice } from "../../stream";
+import TrackDispatcher from "./track_dispatcher";
+/**
+ * Class helping with the management of the audio, video and text tracks and
+ * qualities.
+ *
+ * The `TracksStore` allows to choose a track and qualities for different types
+ * of media through a simpler API.
+ *
+ * @class TracksStore
+ */
+export default class TracksStore extends EventEmitter<ITracksStoreEvents> {
+    /**
+     * Store track selection information, per Period.
+     * Sorted by Period's start time ascending
+     */
+    private _storedPeriodInfo;
+    private _isDisposed;
+    /**
+     * Period information that was before in `_storedPeriodInfo` but has since
+     * been removed is added to the `_cachedPeriodInfo` cache as a weak reference.
+     *
+     * This allows to still retrieve old track information for Periods which are
+     * for example not in the Manifest anymore as long as the same Period's
+     * reference is still kept.
+     */
+    private _cachedPeriodInfo;
+    /** Tells if trick mode has been enabled by the RxPlayer user */
+    private _isTrickModeTrackEnabled;
+    private _defaultAudioTrackSwitchingMode;
+    constructor(args: {
+        preferTrickModeTracks: boolean;
+        defaultAudioTrackSwitchingMode: IAudioTrackSwitchingMode | undefined;
+    });
+    /**
+     * Return Array of Period information, to allow an outside application to
+     * modify the track of any Period.
+     * @returns {Array.<Object>}
+     */
+    getAvailablePeriods(): IPeriod[];
+    /**
+     * Update the list of Periods handled by the TracksStore and make a
+     * track choice decision for each of them.
+     * @param {Object} manifest - The new Manifest object
+     */
+    updatePeriodList(manifest: Manifest): void;
+    /**
+     * Add shared reference to choose Adaptation for new "audio", "video" or
+     * "text" Period.
+     *
+     * Note that such reference has to be removed through `removeTrackReference`
+     * so ressources can be freed.
+     * @param {string} bufferType - The concerned buffer type
+     * @param {Object} manifest
+     * @param {Period} period - The concerned Period.
+     * @param {Object} adaptationRef - A reference through which
+     * the choice will be given.
+     */
+    addTrackReference(bufferType: "audio" | "text" | "video", manifest: Manifest, period: Period, adaptationRef: SharedReference<IAdaptationChoice | null | undefined>): void;
+    /**
+     * Remove shared reference to choose an "audio", "video" or "text" Adaptation
+     * for a Period.
+     * @param {string} bufferType - The concerned buffer type
+     * @param {Period} period - The concerned Period.
+     */
+    removeTrackReference(bufferType: "audio" | "text" | "video", period: Period): void;
+    /**
+     * Allows to recuperate a "Period Object" - used in get/set methods of the
+     * `TracksStore` - by giving the Period itself.
+     *
+     * This method should be preferred when possible over `getPeriodObjectFromId`
+     * because it is able to fallback on an internal cache in case the
+     * corresponding Period is not stored anymore.
+     * This for example could happen when a Period has been removed from the
+     * Manifest yet may still be needed (e.g. because its linked segments might
+     * still live in the buffers).
+     *
+     * Note however that this cache-retrieval logic is based on a Map whose key
+     * is the Period's JavaScript reference. As such, the cache won't be used if
+     * `Period` corresponds to a copy of the original `Period` object.
+     *
+     * @param {Object} period
+     * @returns {Object}
+     */
+    getPeriodObjectFromPeriod(period: Period): ITMPeriodObject | undefined;
+    /**
+     * Allows to recuperate a "Period Object" - used in get/set methods of the
+     * `TracksStore` - by giving the Period's id.
+     *
+     * Note that unlike `getPeriodObjectFromPeriod` this method is only going to look
+     * into currently stored Period and as such old Periods not in the Manifest
+     * anymore might not be retrievable.
+     * If you want to retrieve Period objects linked to such Period, you might
+     * prefer to use `getPeriodObjectFromPeriod` (which necessitates the original
+     * Period object).
+     *
+     * @param {string} periodId - The concerned Period's id
+     * @returns {Object}
+     */
+    getPeriodObjectFromId(periodId: string): ITMPeriodObject | undefined;
+    disableVideoTrickModeTracks(): void;
+    enableVideoTrickModeTracks(): void;
+    /**
+     * Reset the TracksStore's Period objects:
+     *   - All Period which are not in the manifest currently will be removed.
+     *   - All References used to communicate the wanted track will be removed.
+     *
+     * You might want to call this API when restarting playback.
+     */
+    resetPeriodObjects(): void;
+    /**
+     * @returns {boolean}
+     */
+    isTrickModeEnabled(): boolean;
+    /**
+     * Set audio track based on the ID of its Adaptation for a given added Period.
+     * @param {Object} periodObj - The concerned Period's object.
+     * @param {string} wantedId - adaptation id of the wanted track.
+     * @param {string} switchingMode - Behavior when replacing the track by
+     * another.
+     * @param {Object|null} reprsToLock - Audio Representations that should be
+     * locked after switchingMode to that track.
+     * `null` if no Audio Representation should be locked.
+     */
+    setAudioTrack(periodObj: ITMPeriodObject, wantedId: string, switchingMode: IAudioTrackSwitchingMode | undefined, reprsToLock: string[] | null): void;
+    /**
+     * Set text track based on the ID of its Adaptation for a given added Period.
+     * @param {Object} periodObj - The concerned Period's object.
+     * @param {string} wantedId - adaptation id of the wanted track.
+     */
+    setTextTrack(periodObj: ITMPeriodObject, wantedId: string): void;
+    /**
+     * Set audio track based on the ID of its Adaptation for a given added Period.
+     * @param {Object} periodObj - The concerned Period's object.
+     * @param {string} wantedId - adaptation id of the wanted track.
+     * @param {string} switchingMode - Behavior when replacing the track by
+     * another.
+     * @param {Array.<string>|null} reprsToLock - Audio Representations that should be
+     * locked after switchingMode to that track.
+     * `null` if no Audio Representation should be locked.
+     */
+    private _setAudioOrTextTrack;
+    /**
+     * Set video track based on the ID of its Adaptation for a given added Period.
+     * @param {Object} periodObj - The concerned Period's object.
+     * @param {string} wantedId - adaptation id of the wanted track.
+     * @param {string} switchingMode - Behavior when replacing the track by
+     * another.
+     * @param {Array.<string>|null} reprsToLock - Video Representations that should be
+     * locked after switchingMode to that track.
+     * `null` if no Video Representation should be locked.
+     */
+    setVideoTrack(periodObj: ITMPeriodObject, wantedId: string, switchingMode: IVideoTrackSwitchingMode | undefined, reprsToLock: string[] | null): void;
+    /**
+     * Disable the current text track for a given period.
+     *
+     * @param {Object} periodObj - The concerned Period's object
+     * @param {string} bufferType - The type of track to disable.
+     * @throws Error - Throws if the period given has not been added
+     */
+    disableTrack(periodObj: ITMPeriodObject, bufferType: "audio" | "video" | "text"): void;
+    /**
+     * Returns an object describing the chosen audio track for the given audio
+     * Period.
+     *
+     * Returns `null` is the the current audio track is disabled or not
+     * set yet.a pas bcp de marge de manoeuvre j'ai l'impression
+     *
+     * Returns `undefined` if the given Period's id is not currently found in the
+     * `TracksStore`. The cause being most probably that the corresponding
+     * Period is not available anymore.
+     * If you're in that case and if still have the corresponding JavaScript
+     * reference to the wanted Period, you can call `getOldAudioTrack` with it. It
+     * will try retrieving the choice it made from its cache.
+     * @param {Object} periodObj - The concerned Period's object
+     * @returns {Object|null|undefined} - The audio track chosen for this Period.
+     * `null` if audio tracks were disabled and `undefined` if the Period is not
+     * known.
+     */
+    getChosenAudioTrack(periodObj: ITMPeriodObject): IAudioTrack | null;
+    /**
+     * Returns an object describing the chosen text track for the given text
+     * Period.
+     *
+     * Returns null is the the current text track is disabled or not
+     * set yet.
+     *
+     * @param {Object} periodObj - The concerned Period's object
+     * @returns {Object|null} - The text track chosen for this Period
+     */
+    getChosenTextTrack(periodObj: ITMPeriodObject): ITextTrack | null;
+    /**
+     * Returns an object describing the chosen video track for the given video
+     * Period.
+     *
+     * Returns null is the the current video track is disabled or not
+     * set yet.
+     *
+     * @param {Object} periodObj - The concerned Period's object
+     * @returns {Object|null} - The video track chosen for this Period
+     */
+    getChosenVideoTrack(periodObj: ITMPeriodObject): IVideoTrack | null;
+    /**
+     * Returns all available audio tracks for a given Period, as an array of
+     * objects.
+     *
+     * Returns `undefined` if the given Period's id is not known.
+     *
+     * @param {Object} periodObj - The concerned Period's object
+     * @returns {Array.<Object>}
+     */
+    getAvailableAudioTracks(periodObj: ITMPeriodObject): IAvailableAudioTrack[] | undefined;
+    /**
+     * Returns all available text tracks for a given Period, as an array of
+     * objects.
+     *
+     * Returns `undefined` if the given Period's id is not known.
+     *
+     * @param {Object} periodObj - The concerned Period's object
+     * @returns {Array.<Object>}
+     */
+    getAvailableTextTracks(periodObj: ITMPeriodObject): IAvailableTextTrack[] | undefined;
+    /**
+     * Returns all available video tracks for a given Period, as an array of
+     * objects.
+     *
+     * Returns `undefined` if the given Period's id is not known.
+     *
+     * @param {Object} periodObj - The concerned Period's object
+     * @returns {Array.<Object>}
+     */
+    getAvailableVideoTracks(periodObj: ITMPeriodObject): IAvailableVideoTrack[] | undefined;
+    getLockedAudioRepresentations(periodObj: ITMPeriodObject): string[] | null;
+    getLockedVideoRepresentations(periodObj: ITMPeriodObject): string[] | null;
+    lockAudioRepresentations(periodObj: ITMPeriodObject, lockSettings: IAudioRepresentationsLockSettings): void;
+    lockVideoRepresentations(periodObj: ITMPeriodObject, lockSettings: IVideoRepresentationsLockSettings): void;
+    unlockAudioRepresentations(periodObj: ITMPeriodObject): void;
+    unlockVideoRepresentations(periodObj: ITMPeriodObject): void;
+    dispose(): void;
+    /**
+     * @param {Period} period
+     * @returns {Object}
+     */
+    private _addPeriod;
+    private _resetVideoTrackChoices;
+    private _removePeriodObject;
+    private _getRepresentationsToLock;
+}
+/** Every information stored for a single Period. */
+export interface ITMPeriodObject {
+    /** The Period in question. */
+    period: Period;
+    /**
+     * If `true`, this Period was present at the last `updatePeriodList` call,
+     * meaning it's probably still in the Manifest.
+     *
+     * If `false`, this Period was not. In that case it is probably just here
+     * because some audio/video/text buffer still contains data of the given type.
+     */
+    inManifest: boolean;
+    audio: IAudioPeriodInfo;
+    text: ITextPeriodInfo;
+    video: IVideoPeriodInfo;
+    isRemoved: boolean;
+}
+/**
+ * Internal representation of audio track preferences for a given `Period` of
+ * the Manifest.
+ */
+interface IAudioPeriodInfo {
+    /**
+     * Information on the last audio track settings wanted by the user.
+     * `null` if no audio track is wanted.
+     */
+    storedSettings: {
+        /** Contains the last `Adaptation` wanted by the user. */
+        adaptation: Adaptation;
+        /** "Switching mode" in which the track switch should happen. */
+        switchingMode: IAudioTrackSwitchingMode;
+        /**
+         * Contains the last locked `Representation`s for this `Adaptation` wanted
+         * by the user.
+         * `null` if no Representation is locked.
+         */
+        lockedRepresentations: SharedReference<IRepresentationsChoice | null>;
+    } | null;
+    /**
+     * Tracks are internally emitted through RxJS's `Subject`s.
+     * A `TrackDispatcher` allows to facilitate and centralize the management of
+     * that Subject so that the right wanted track and qualities are emitted
+     * through it.
+     *
+     * `null` if no `Subject` has been linked for this `Period` and buffer type
+     * for now.
+     */
+    dispatcher: TrackDispatcher | null;
+}
+/**
+ * Internal representation of text track preferences for a given `Period` of
+ * the Manifest.
+ */
+export interface ITextPeriodInfo {
+    /**
+     * Information on the last text track settings wanted.
+     * `null` if no text track is wanted.
+     */
+    storedSettings: {
+        /** Contains the last `Adaptation` wanted by the user. */
+        adaptation: Adaptation;
+        /** "Switching mode" in which the track switch should happen. */
+        switchingMode: "direct";
+        /**
+         * Contains the last locked `Representation`s for this `Adaptation` wanted
+         * by the user.
+         * `null` if no Representation is locked.
+         */
+        lockedRepresentations: SharedReference<IRepresentationsChoice | null>;
+    } | null;
+    /**
+     * Tracks are internally emitted through RxJS's `Subject`s.
+     * A `TrackDispatcher` allows to facilitate and centralize the management of
+     * that Subject so that the right wanted track and qualities are emitted
+     * through it.
+     *
+     * `null` if no `Subject` has been linked for this `Period` and buffer type
+     * for now.
+     */
+    dispatcher: TrackDispatcher | null;
+}
+/**
+ * Internal representation of video track preferences for a given `Period` of
+ * the Manifest.
+ */
+export interface IVideoPeriodInfo {
+    /**
+     * Information on the last video track settings wanted.
+     * `null` if no video track is wanted.
+     */
+    storedSettings: {
+        /**
+         * The wanted Adaptation itself (may be different from `adaptationBase`
+         * when a trickmode track is chosen, in which case `adaptationBase` is
+         * the Adaptation the trickmode track is linked to and `adaptation` is
+         * the trickmode track).
+         */
+        adaptation: Adaptation;
+        /** "Switching mode" in which the track switch should happen. */
+        switchingMode: IVideoTrackSwitchingMode;
+        /**
+         * The "base" Adaptation for `storedSettings` (if a trickmode track was
+         * chosen, this is the Adaptation the trickmode track is linked to, and not
+         * the trickmode track itself).
+         */
+        adaptationBase: Adaptation;
+        /**
+         * Contains the last locked `Representation`s for this `Adaptation` wanted
+         * by the user.
+         * `null` if no Representation is locked.
+         */
+        lockedRepresentations: SharedReference<IRepresentationsChoice | null>;
+    } | null;
+    /**
+     * Tracks are internally emitted through RxJS's `Subject`s.
+     * A `TrackDispatcher` allows to facilitate and centralize the management of
+     * that Subject so that the right wanted track and qualities are emitted
+     * through it.
+     *
+     * `null` if no `Subject` has been linked for this `Period` and buffer type
+     * for now.
+     */
+    dispatcher: TrackDispatcher | null;
+}
+/** Events emitted by the TracksStore. */
+interface ITracksStoreEvents {
+    newAvailablePeriods: IPeriod[];
+    brokenRepresentationsLock: IBrokenRepresentationsLockContext;
+    trackUpdate: ITrackUpdateEventPayload;
+}
+export interface IAudioRepresentationsLockSettings {
+    representations: string[];
+    switchingMode?: IAudioRepresentationsSwitchingMode | undefined;
+}
+export interface IVideoRepresentationsLockSettings {
+    representations: string[];
+    switchingMode?: IVideoRepresentationsSwitchingMode | undefined;
+}
+export {};