rx-player 4.0.0 → 4.1.0-dev.2024031100

package/dist/es2017/main_thread/init/utils/get_initial_time.js

@@ -0,0 +1,106 @@
+/**
+ * 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 config from "../../../config";
+import log from "../../../log";
+import { getLivePosition, getMaximumSafePosition, getMinimumSafePosition, } from "../../../manifest";
+import isNullOrUndefined from "../../../utils/is_null_or_undefined";
+import getMonotonicTimeStamp from "../../../utils/monotonic_timestamp";
+/**
+ * Returns the calculated initial time for the content described by the given
+ * Manifest:
+ *   1. if a start time is defined by user, calculate starting time from the
+ *      manifest information
+ *   2. else if the media is live, use the live edge and suggested delays from
+ *      it
+ *   3. else returns the minimum time announced in the manifest
+ * @param {Manifest} manifest
+ * @param {boolean} lowLatencyMode
+ * @param {Object} startAt
+ * @returns {Number}
+ */
+export default function getInitialTime(manifest, lowLatencyMode, startAt) {
+    var _a;
+    if (!isNullOrUndefined(startAt)) {
+        const min = getMinimumSafePosition(manifest);
+        const max = getMaximumSafePosition(manifest);
+        if (!isNullOrUndefined(startAt.position)) {
+            log.debug("Init: using startAt.minimumPosition");
+            return Math.max(Math.min(startAt.position, max), min);
+        }
+        else if (!isNullOrUndefined(startAt.wallClockTime)) {
+            log.debug("Init: using startAt.wallClockTime");
+            const ast = manifest.availabilityStartTime === undefined ? 0 : manifest.availabilityStartTime;
+            const position = startAt.wallClockTime - ast;
+            return Math.max(Math.min(position, max), min);
+        }
+        else if (!isNullOrUndefined(startAt.fromFirstPosition)) {
+            log.debug("Init: using startAt.fromFirstPosition");
+            const { fromFirstPosition } = startAt;
+            return fromFirstPosition <= 0 ? min : Math.min(max, min + fromFirstPosition);
+        }
+        else if (!isNullOrUndefined(startAt.fromLastPosition)) {
+            log.debug("Init: using startAt.fromLastPosition");
+            const { fromLastPosition } = startAt;
+            return fromLastPosition >= 0 ? max : Math.max(min, max + fromLastPosition);
+        }
+        else if (!isNullOrUndefined(startAt.fromLivePosition)) {
+            log.debug("Init: using startAt.fromLivePosition");
+            const livePosition = (_a = getLivePosition(manifest)) !== null && _a !== void 0 ? _a : max;
+            const { fromLivePosition } = startAt;
+            return fromLivePosition >= 0
+                ? livePosition
+                : Math.max(min, livePosition + fromLivePosition);
+        }
+        else if (!isNullOrUndefined(startAt.percentage)) {
+            log.debug("Init: using startAt.percentage");
+            const { percentage } = startAt;
+            if (percentage > 100) {
+                return max;
+            }
+            else if (percentage < 0) {
+                return min;
+            }
+            const ratio = +percentage / 100;
+            const extent = max - min;
+            return min + extent * ratio;
+        }
+    }
+    const minimumPosition = getMinimumSafePosition(manifest);
+    if (manifest.isLive) {
+        const { suggestedPresentationDelay, clockOffset } = manifest;
+        const maximumPosition = getMaximumSafePosition(manifest);
+        let liveTime;
+        const { DEFAULT_LIVE_GAP } = config.getCurrent();
+        if (clockOffset === undefined) {
+            log.info("Init: no clock offset found for a live content, " +
+                "starting close to maximum available position");
+            liveTime = maximumPosition;
+        }
+        else {
+            log.info("Init: clock offset found for a live content, " +
+                "checking if we can start close to it");
+            const ast = manifest.availabilityStartTime === undefined ? 0 : manifest.availabilityStartTime;
+            const clockRelativeLiveTime = (getMonotonicTimeStamp() + clockOffset) / 1000 - ast;
+            liveTime = Math.min(maximumPosition, clockRelativeLiveTime);
+        }
+        const diffFromLiveTime = suggestedPresentationDelay !== null && suggestedPresentationDelay !== void 0 ? suggestedPresentationDelay : (lowLatencyMode ? DEFAULT_LIVE_GAP.LOW_LATENCY : DEFAULT_LIVE_GAP.DEFAULT);
+        log.debug(`Init: ${liveTime} defined as the live time, applying a live gap` +
+            ` of ${diffFromLiveTime}`);
+        return Math.max(liveTime - diffFromLiveTime, minimumPosition);
+    }
+    log.info("Init: starting at the minimum available position:", minimumPosition);
+    return minimumPosition;
+}

package/dist/es2017/main_thread/init/utils/get_loaded_reference.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 type { IPlaybackObservation, IReadOnlyPlaybackObserver } from "../../../playback_observer";
+import type { IReadOnlySharedReference } from "../../../utils/reference";
+import type { CancellationSignal } from "../../../utils/task_canceller";
+/**
+ * Returns an `IReadOnlySharedReference` that switches to `true` once the
+ * content is considered loaded (i.e. once it can begin to be played).
+ * @param {Object} playbackObserver
+ * @param {HTMLMediaElement} mediaElement
+ * @param {boolean} isDirectfile - `true` if this is a directfile content
+ * @param {Object} cancelSignal
+ * @returns {Object}
+ */
+export default function getLoadedReference(playbackObserver: IReadOnlyPlaybackObserver<IPlaybackObservation>, mediaElement: HTMLMediaElement, isDirectfile: boolean, cancelSignal: CancellationSignal): IReadOnlySharedReference<boolean>;

package/dist/es2017/main_thread/init/utils/get_loaded_reference.js

@@ -0,0 +1,64 @@
+/**
+ * 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 shouldValidateMetadata from "../../../compat/should_validate_metadata";
+import shouldWaitForDataBeforeLoaded from "../../../compat/should_wait_for_data_before_loaded";
+import shouldWaitForHaveEnoughData from "../../../compat/should_wait_for_have_enough_data";
+import SharedReference from "../../../utils/reference";
+import TaskCanceller from "../../../utils/task_canceller";
+/**
+ * Returns an `IReadOnlySharedReference` that switches to `true` once the
+ * content is considered loaded (i.e. once it can begin to be played).
+ * @param {Object} playbackObserver
+ * @param {HTMLMediaElement} mediaElement
+ * @param {boolean} isDirectfile - `true` if this is a directfile content
+ * @param {Object} cancelSignal
+ * @returns {Object}
+ */
+export default function getLoadedReference(playbackObserver, mediaElement, isDirectfile, cancelSignal) {
+    const listenCanceller = new TaskCanceller();
+    listenCanceller.linkToSignal(cancelSignal);
+    const isLoaded = new SharedReference(false, listenCanceller.signal);
+    playbackObserver.listen((observation) => {
+        if (observation.rebuffering !== null ||
+            observation.freezing !== null ||
+            observation.readyState === 0) {
+            return;
+        }
+        if (!shouldWaitForDataBeforeLoaded(isDirectfile, mediaElement.hasAttribute("playsinline"))) {
+            // The duration is NaN if no media data is available,
+            // which means media is not loaded yet.
+            if (isNaN(mediaElement.duration)) {
+                return;
+            }
+            if (mediaElement.duration > 0) {
+                isLoaded.setValue(true);
+                listenCanceller.cancel();
+                return;
+            }
+        }
+        const minReadyState = shouldWaitForHaveEnoughData() ? 4 : 3;
+        if (observation.readyState >= minReadyState) {
+            if (observation.currentRange !== null || observation.ended) {
+                if (!shouldValidateMetadata() || mediaElement.duration > 0) {
+                    isLoaded.setValue(true);
+                    listenCanceller.cancel();
+                    return;
+                }
+            }
+        }
+    }, { includeLastObservation: true, clearSignal: listenCanceller.signal });
+    return isLoaded;
+}

package/dist/es2017/main_thread/init/utils/initial_seek_and_play.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 type { IMediaElementPlaybackObserver } from "../../../playback_observer";
+import type { IPlayerError } from "../../../public_types";
+import type { IReadOnlySharedReference } from "../../../utils/reference";
+import type { CancellationSignal } from "../../../utils/task_canceller";
+/** Event emitted when trying to perform the initial `play`. */
+export type IInitialPlayEvent = 
+/** Autoplay is not enabled, but all required steps to do so are there. */
+{
+    type: "skipped";
+}
+/**
+ * Tried to play, but autoplay is blocked by the browser.
+ * A corresponding warning should have already been sent.
+ */
+ | {
+    type: "autoplay-blocked";
+}
+/** Autoplay was done with success. */
+ | {
+    type: "autoplay";
+};
+/** Object returned by `initialSeekAndPlay`. */
+export interface IInitialSeekAndPlayObject {
+    /** Emit the result of the auto-play operation, once performed. */
+    autoPlayResult: Promise<IInitialPlayEvent>;
+    /**
+     * Shared reference whose value becomes `true` once the initial play has
+     * been considered / has been done by `performInitialSeekAndPlay`.
+     */
+    initialPlayPerformed: IReadOnlySharedReference<boolean>;
+}
+/**
+ * Seek as soon as possible at the initially wanted position and play if
+ * autoPlay is wanted.
+ * @param {Object} args
+ * @param {Object} cancelSignal
+ * @returns {Object}
+ */
+export default function performInitialSeekAndPlay({ mediaElement, playbackObserver, startTime, mustAutoPlay, isDirectfile, onWarning, }: {
+    mediaElement: HTMLMediaElement;
+    playbackObserver: IMediaElementPlaybackObserver;
+    startTime: number | (() => number);
+    mustAutoPlay: boolean;
+    isDirectfile: boolean;
+    onWarning: (err: IPlayerError) => void;
+}, cancelSignal: CancellationSignal): IInitialSeekAndPlayObject;

package/dist/es2017/main_thread/init/utils/initial_seek_and_play.js

@@ -0,0 +1,200 @@
+/**
+ * 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 canSeekDirectlyAfterLoadedMetadata from "../../../compat/can_seek_directly_after_loaded_metadata";
+import shouldValidateMetadata from "../../../compat/should_validate_metadata";
+import { MediaError } from "../../../errors";
+import log from "../../../log";
+import SharedReference from "../../../utils/reference";
+/**
+ * Seek as soon as possible at the initially wanted position and play if
+ * autoPlay is wanted.
+ * @param {Object} args
+ * @param {Object} cancelSignal
+ * @returns {Object}
+ */
+export default function performInitialSeekAndPlay({ mediaElement, playbackObserver, startTime, mustAutoPlay, isDirectfile, onWarning, }, cancelSignal) {
+    const initialPlayPerformed = new SharedReference(false, cancelSignal);
+    const autoPlayResult = new Promise((resolveAutoPlay, rejectAutoPlay) => {
+        const deregisterCancellation = cancelSignal.register((err) => {
+            rejectAutoPlay(err);
+        });
+        if (cancelSignal.isCancelled()) {
+            return;
+        }
+        /** `true` if we asked the `PlaybackObserver` to perform an initial seek. */
+        let hasAskedForInitialSeek = false;
+        const performInitialSeek = (initialSeekTime) => {
+            playbackObserver.setCurrentTime(initialSeekTime);
+            hasAskedForInitialSeek = true;
+        };
+        // `startTime` defined as a function might depend on metadata to make its
+        // choice, such as the content duration, minimum and/or maximum position.
+        //
+        // The RxPlayer might already know those through the Manifest file for
+        // non-Directfile contents, yet only through the `HTMLMediaElement` once a
+        // a sufficient `readyState` has been reached for directfile contents.
+        // So let's divide the two possibilities here.
+        if (!isDirectfile || typeof startTime === "number") {
+            const initiallySeekedTime = typeof startTime === "number" ? startTime : startTime();
+            if (initiallySeekedTime !== 0) {
+                performInitialSeek(initiallySeekedTime);
+            }
+            waitForSeekable();
+        }
+        else {
+            playbackObserver.listen((obs, stopListening) => {
+                if (obs.readyState >= 1) {
+                    stopListening();
+                    const initiallySeekedTime = typeof startTime === "number" ? startTime : startTime();
+                    if (initiallySeekedTime !== 0) {
+                        if (canSeekDirectlyAfterLoadedMetadata) {
+                            performInitialSeek(initiallySeekedTime);
+                        }
+                        else {
+                            setTimeout(() => {
+                                performInitialSeek(initiallySeekedTime);
+                            }, 0);
+                        }
+                    }
+                    waitForSeekable();
+                }
+            }, { includeLastObservation: true, clearSignal: cancelSignal });
+        }
+        /**
+         * Logic that should be run once the initial seek has been asked to the
+         * PlaybackObserver.
+         *
+         * Actually wait until the seek has been performed, wait for the right moment
+         * to perform autoplay, resolve the promise once everything has been done and
+         * potentially send warning if a minor issue is detected.
+         */
+        function waitForSeekable() {
+            /**
+             * We only want to continue to `play` when a `seek` has actually been
+             * performed (if it has been asked). This boolean keep track of if the
+             * seek arised.
+             */
+            let hasStartedSeeking = false;
+            playbackObserver.listen((obs, stopListening) => {
+                if (!hasStartedSeeking && obs.seeking !== 0 /* SeekingState.None */) {
+                    hasStartedSeeking = true;
+                }
+                if ((hasAskedForInitialSeek && !hasStartedSeeking) || obs.readyState === 0) {
+                    return;
+                }
+                stopListening();
+                if (shouldValidateMetadata() && mediaElement.duration === 0) {
+                    const error = new MediaError("MEDIA_ERR_NOT_LOADED_METADATA", "Cannot load automatically: your browser " +
+                        "falsely announced having loaded the content.");
+                    onWarning(error);
+                }
+                if (cancelSignal.isCancelled()) {
+                    return;
+                }
+                waitForPlayable();
+            }, { includeLastObservation: true, clearSignal: cancelSignal });
+        }
+        /**
+         * Logic that should be run once the initial seek has been properly performed.
+         *
+         * Wait for the media being playable before performing the autoplay operation
+         * if asked. Potentially send warning if a minor issue has been detected while
+         * doing so.
+         */
+        function waitForPlayable() {
+            playbackObserver.listen((observation, stopListening) => {
+                if (observation.seeking === 0 /* SeekingState.None */ &&
+                    observation.rebuffering === null &&
+                    observation.readyState >= 1) {
+                    stopListening();
+                    onPlayable();
+                }
+            }, { includeLastObservation: true, clearSignal: cancelSignal });
+        }
+        /**
+         * Callback called once the content is considered "playable".
+         *
+         * Perform the autoplay if needed, handling potential issues and resolve the
+         * Promise when done.
+         * Might also send warnings if minor issues arise.
+         */
+        function onPlayable() {
+            var _a;
+            log.info("Init: Can begin to play content");
+            if (!mustAutoPlay) {
+                if (mediaElement.autoplay) {
+                    log.warn("Init: autoplay is enabled on HTML media element. " +
+                        "Media will play as soon as possible.");
+                }
+                initialPlayPerformed.setValue(true);
+                initialPlayPerformed.finish();
+                deregisterCancellation();
+                return resolveAutoPlay({ type: "skipped" });
+            }
+            else if (mediaElement.ended) {
+                // the video has ended state to true, executing VideoElement.play() will
+                // restart the video from the start, which is not wanted in most cases.
+                // returning "skipped" prevents the call to play() and fix the issue
+                log.warn("Init: autoplay is enabled but the video is ended. " +
+                    "Skipping autoplay to prevent video to start again");
+                initialPlayPerformed.setValue(true);
+                initialPlayPerformed.finish();
+                deregisterCancellation();
+                return resolveAutoPlay({ type: "skipped" });
+            }
+            let playResult;
+            try {
+                playResult = (_a = mediaElement.play()) !== null && _a !== void 0 ? _a : Promise.resolve();
+            }
+            catch (playError) {
+                deregisterCancellation();
+                return rejectAutoPlay(playError);
+            }
+            playResult
+                .then(() => {
+                if (cancelSignal.isCancelled()) {
+                    return;
+                }
+                initialPlayPerformed.setValue(true);
+                initialPlayPerformed.finish();
+                deregisterCancellation();
+                return resolveAutoPlay({ type: "autoplay" });
+            })
+                .catch((playError) => {
+                deregisterCancellation();
+                if (cancelSignal.isCancelled()) {
+                    return;
+                }
+                if (playError instanceof Error && playError.name === "NotAllowedError") {
+                    // auto-play was probably prevented.
+                    log.warn("Init: Media element can't play." +
+                        " It may be due to browser auto-play policies.");
+                    const error = new MediaError("MEDIA_ERR_BLOCKED_AUTOPLAY", "Cannot trigger auto-play automatically: " +
+                        "your browser does not allow it.");
+                    onWarning(error);
+                    if (cancelSignal.isCancelled()) {
+                        return;
+                    }
+                    return resolveAutoPlay({ type: "autoplay-blocked" });
+                }
+                else {
+                    rejectAutoPlay(playError);
+                }
+            });
+        }
+    });
+    return { autoPlayResult, initialPlayPerformed };
+}

package/dist/es2017/main_thread/init/utils/initialize_content_decryption.d.ts

@@ -0,0 +1,87 @@
+import type { IKeySystemOption, IPlayerError } from "../../../public_types";
+import type { IReadOnlySharedReference } from "../../../utils/reference";
+import SharedReference from "../../../utils/reference";
+import type { CancellationSignal } from "../../../utils/task_canceller";
+import type { IContentProtection, IProcessedProtectionData } from "../../decrypt";
+/**
+ * Initialize content decryption capabilities on the given `HTMLMediaElement`.
+ *
+ * You can call this function even if you don't want decrytpion capabilities, in
+ * which case you can just set the `keySystems` option as an empty array.
+ * In this situation, the returned object will directly correspond to an
+ * "`initialized`" state and the `onError` callback will be triggered as soon
+ * as protection information is received.
+ *
+ * @param {HTMLMediaElement} mediaElement - `HTMLMediaElement` on which content
+ * decryption may be wanted.
+ * @param {Array.<Object>} keySystems - Key system configuration(s) wanted
+ * Empty array if no content decryption capability is wanted.
+ * @param {Object} protectionRef - Reference through which content
+ * protection initialization data will be sent through.
+ * @param {Object} callbacks - Callbacks called at various decryption-related
+ * events.
+ * @param {Object} cancelSignal - When that signal emits, this function will
+ * stop listening to various events as well as items sent through the
+ * `protectionRef` parameter.
+ * @returns {Object} - Reference emitting the current status regarding DRM
+ * initialization.
+ */
+export default function initializeContentDecryption(mediaElement: HTMLMediaElement, keySystems: IKeySystemOption[], protectionRef: IReadOnlySharedReference<null | IContentProtection>, callbacks: {
+    onWarning: (err: IPlayerError) => void;
+    onError: (err: Error) => void;
+    onBlackListProtectionData: (val: IProcessedProtectionData) => void;
+    onKeyIdsCompatibilityUpdate: (updates: {
+        whitelistedKeyIds: Uint8Array[];
+        blacklistedKeyIds: Uint8Array[];
+        delistedKeyIds: Uint8Array[];
+    }) => void;
+}, cancelSignal: CancellationSignal): IReadOnlySharedReference<IDrmInitializationStatus>;
+/** Status of content decryption initialization. */
+interface IDrmInitializationStatus {
+    /** Current initialization state the decryption logic is in. */
+    initializationState: IDecryptionInitializationState;
+    /**
+     * If set, corresponds to the hex string describing the current key system
+     * used.
+     * `undefined` if unknown or if it does not apply.
+     */
+    drmSystemId: string | undefined;
+}
+/** Initialization steps to add decryption capabilities to an `HTMLMediaElement`. */
+type IDecryptionInitializationState = 
+/**
+ * Decryption capabilities have not been initialized yet.
+ * You should wait before performing any action on the concerned
+ * `HTMLMediaElement` (such as linking a content / `MediaSource` to it).
+ */
+{
+    type: "uninitialized";
+    value: null;
+}
+/**
+ * The `MediaSource` or media url has to be linked to the `HTMLMediaElement`
+ * before continuing.
+ * Once it has been linked with success (e.g. the `MediaSource` has "opened"),
+ * the `isMediaLinked` `SharedReference` should be set to `true`.
+ *
+ * In the `MediaSource` case, you should wait until the `"initialized"`
+ * state before pushing segment.
+ *
+ * Note that the `"awaiting-media-link"` is an optional state. It can be
+ * skipped to directly `"initialized"` instead.
+ */
+ | {
+    type: "awaiting-media-link";
+    value: {
+        isMediaLinked: SharedReference<boolean>;
+    };
+}
+/**
+ * The `MediaSource` or media url can be linked AND segments can be pushed to
+ * the `HTMLMediaElement` on which decryption capabilities were wanted.
+ */
+ | {
+    type: "initialized";
+    value: null;
+};
+export {};

package/dist/es2017/main_thread/init/utils/initialize_content_decryption.js

@@ -0,0 +1,116 @@
+import { EncryptedMediaError } from "../../../errors";
+import features from "../../../features";
+import log from "../../../log";
+import SharedReference from "../../../utils/reference";
+import TaskCanceller from "../../../utils/task_canceller";
+import { ContentDecryptorState } from "../../decrypt";
+/**
+ * Initialize content decryption capabilities on the given `HTMLMediaElement`.
+ *
+ * You can call this function even if you don't want decrytpion capabilities, in
+ * which case you can just set the `keySystems` option as an empty array.
+ * In this situation, the returned object will directly correspond to an
+ * "`initialized`" state and the `onError` callback will be triggered as soon
+ * as protection information is received.
+ *
+ * @param {HTMLMediaElement} mediaElement - `HTMLMediaElement` on which content
+ * decryption may be wanted.
+ * @param {Array.<Object>} keySystems - Key system configuration(s) wanted
+ * Empty array if no content decryption capability is wanted.
+ * @param {Object} protectionRef - Reference through which content
+ * protection initialization data will be sent through.
+ * @param {Object} callbacks - Callbacks called at various decryption-related
+ * events.
+ * @param {Object} cancelSignal - When that signal emits, this function will
+ * stop listening to various events as well as items sent through the
+ * `protectionRef` parameter.
+ * @returns {Object} - Reference emitting the current status regarding DRM
+ * initialization.
+ */
+export default function initializeContentDecryption(mediaElement, keySystems, protectionRef, callbacks, cancelSignal) {
+    if (keySystems.length === 0) {
+        return createEmeDisabledReference("No `keySystems` option given.");
+    }
+    else if (features.decrypt === null) {
+        return createEmeDisabledReference("EME feature not activated.");
+    }
+    const decryptorCanceller = new TaskCanceller();
+    decryptorCanceller.linkToSignal(cancelSignal);
+    const drmStatusRef = new SharedReference({
+        initializationState: { type: "uninitialized", value: null },
+        drmSystemId: undefined,
+    }, cancelSignal);
+    const ContentDecryptor = features.decrypt;
+    if (!ContentDecryptor.hasEmeApis()) {
+        return createEmeDisabledReference("EME API not available on the current page.");
+    }
+    log.debug("Init: Creating ContentDecryptor");
+    const contentDecryptor = new ContentDecryptor(mediaElement, keySystems);
+    contentDecryptor.addEventListener("stateChange", (state) => {
+        if (state === ContentDecryptorState.WaitingForAttachment) {
+            const isMediaLinked = new SharedReference(false);
+            isMediaLinked.onUpdate((isAttached, stopListening) => {
+                if (isAttached) {
+                    stopListening();
+                    if (state === ContentDecryptorState.WaitingForAttachment) {
+                        contentDecryptor.attach();
+                    }
+                }
+            }, { clearSignal: decryptorCanceller.signal });
+            drmStatusRef.setValue({
+                initializationState: {
+                    type: "awaiting-media-link",
+                    value: { isMediaLinked },
+                },
+                drmSystemId: contentDecryptor.systemId,
+            });
+        }
+        else if (state === ContentDecryptorState.ReadyForContent) {
+            drmStatusRef.setValue({
+                initializationState: { type: "initialized", value: null },
+                drmSystemId: contentDecryptor.systemId,
+            });
+            contentDecryptor.removeEventListener("stateChange");
+        }
+    });
+    contentDecryptor.addEventListener("error", (error) => {
+        decryptorCanceller.cancel();
+        callbacks.onError(error);
+    });
+    contentDecryptor.addEventListener("warning", (error) => {
+        callbacks.onWarning(error);
+    });
+    contentDecryptor.addEventListener("blackListProtectionData", (x) => {
+        callbacks.onBlackListProtectionData(x);
+    });
+    contentDecryptor.addEventListener("keyIdsCompatibilityUpdate", (x) => {
+        callbacks.onKeyIdsCompatibilityUpdate(x);
+    });
+    protectionRef.onUpdate((data) => {
+        if (data === null) {
+            return;
+        }
+        contentDecryptor.onInitializationData(data);
+    }, { clearSignal: decryptorCanceller.signal });
+    decryptorCanceller.signal.register(() => {
+        contentDecryptor.dispose();
+    });
+    return drmStatusRef;
+    function createEmeDisabledReference(errMsg) {
+        protectionRef.onUpdate((data, stopListening) => {
+            if (data === null) {
+                // initial value
+                return;
+            }
+            stopListening();
+            const err = new EncryptedMediaError("MEDIA_IS_ENCRYPTED_ERROR", errMsg);
+            callbacks.onError(err);
+        }, { clearSignal: cancelSignal });
+        const ref = new SharedReference({
+            initializationState: { type: "initialized", value: null },
+            drmSystemId: undefined,
+        });
+        ref.finish(); // We know that no new value will be triggered
+        return ref;
+    }
+}