rx-player 3.26.2 → 3.27.0-dev.20220317

package/src/core/api/public_api.ts

@@ -87,10 +87,10 @@ import createSharedReference, {
 } from "../../utils/reference";
 import warnOnce from "../../utils/warn_once";
 import {
-  clearEMESession,
-  disposeEME,
+  clearOnStop,
+  disposeDecryptionResources,
   getCurrentKeySystem,
-} from "../eme";
+} from "../decrypt";
 import {
   IManifestFetcherParsedResult,
   IManifestFetcherWarningEvent,
@@ -140,7 +140,6 @@ import TrackChoiceManager, {
 
 /* eslint-disable @typescript-eslint/naming-convention */
 
-const { DEFAULT_UNMUTED_VOLUME } = config;
 
 const { isPageActive,
         isVideoVisible,
@@ -152,74 +151,6 @@ const { isPageActive,
         onTextTrackChanges$,
         videoWidth$ } = events;
 
-/** Payload emitted with a `positionUpdate` event. */
-interface IPositionUpdateItem {
-  /** current position the player is in, in seconds. */
-  position : number;
-  /** Last position set for the current media currently, in seconds. */
-  duration : number;
-  /** Playback rate (i.e. speed) at which the current media is played. */
-  playbackRate : number;
-  /** Amount of buffer available for now in front of the current position, in seconds. */
-  bufferGap : number;
-  /** Current maximum seekable position. */
-  maximumBufferTime? : number;
-  wallClockTime? : number;
-  /**
-   * Only for live contents. Difference between the "live edge" and the current
-   * position, in seconds.
-   */
-  liveGap? : number;
-}
-
-/** Payload emitted with a `bitrateEstimationChange` event. */
-interface IBitrateEstimate {
-  /** The type of buffer this estimate was done for (e.g. "audio). */
-  type : IBufferType;
-  /** The calculated bitrate, in bits per seconds. */
-  bitrate : number | undefined;
-}
-
-export type IStreamEvent = { data: IStreamEventData;
-                             start: number;
-                             end: number;
-                             onExit?: () => void; } |
-                           { data: IStreamEventData;
-                             start: number; };
-
-/** Every events sent by the RxPlayer's public API. */
-interface IPublicAPIEvent {
-  playerStateChange : string;
-  positionUpdate : IPositionUpdateItem;
-  audioTrackChange : ITMAudioTrack | null;
-  textTrackChange : ITMTextTrack | null;
-  videoTrackChange : ITMVideoTrack | null;
-  audioBitrateChange : number;
-  videoBitrateChange : number;
-  imageTrackUpdate : { data: IBifThumbnail[] };
-  fullscreenChange : boolean;
-  bitrateEstimationChange : IBitrateEstimate;
-  volumeChange : number;
-  error : ICustomError | Error;
-  warning : ICustomError | Error;
-  nativeTextTracksChange : TextTrack[];
-  periodChange : Period;
-  availableAudioBitratesChange : number[];
-  availableVideoBitratesChange : number[];
-  availableAudioTracksChange : ITMAudioTrackListItem[];
-  availableTextTracksChange : ITMTextTrackListItem[];
-  availableVideoTracksChange : ITMVideoTrackListItem[];
-  decipherabilityUpdate : Array<{ manifest : Manifest;
-                                  period : Period;
-                                  adaptation : Adaptation;
-                                  representation : Representation; }>;
-  seeking : null;
-  seeked : null;
-  streamEvent : IStreamEvent;
-  streamEventSkip : IStreamEvent;
-  inbandEvents : IInbandEvent[];
-}
-
 /**
  * @class Player
  * @extends EventEmitter
@@ -280,6 +211,8 @@ class Player extends EventEmitter<IPublicAPIEvent> {
     maxBufferAhead : ISharedReference<number>;
     /** Maximum kept buffer behind in the current position, in seconds. */
     maxBufferBehind : ISharedReference<number>;
+    /** Maximum size of video buffer , in kiloBytes */
+    maxVideoBufferSize : ISharedReference<number>;
   };
 
   /** Information on the current bitrate settings. */
@@ -321,7 +254,7 @@ class Player extends EventEmitter<IPublicAPIEvent> {
      * URL of the Manifest (or just of the content for DirectFile contents)
      * currently being played.
      */
-    url? : string;
+    url : string | undefined;
 
     /** Subject allowing to stop playing that content. */
     stop$ : Subject<void>;
@@ -488,13 +421,14 @@ class Player extends EventEmitter<IPublicAPIEvent> {
             throttleVideoBitrateWhenHidden,
             videoElement,
             wantedBufferAhead,
+            maxVideoBufferSize,
             stopAtEnd } = parseConstructorOptions(options);
-
+    const { DEFAULT_UNMUTED_VOLUME } = config.getCurrent();
     // Workaround to support Firefox autoplay on FF 42.
     // See: https://bugzilla.mozilla.org/show_bug.cgi?id=1194624
     videoElement.preload = "auto";
 
-    this.version = /* PLAYER_VERSION */"3.26.2";
+    this.version = /* PLAYER_VERSION */"3.27.0-dev.2022031700";
     this.log = log;
     this.state = "STOPPED";
     this.videoElement = videoElement;
@@ -554,6 +488,7 @@ class Player extends EventEmitter<IPublicAPIEvent> {
       wantedBufferAhead: createSharedReference(wantedBufferAhead),
       maxBufferAhead: createSharedReference(maxBufferAhead),
       maxBufferBehind: createSharedReference(maxBufferBehind),
+      maxVideoBufferSize: createSharedReference(maxVideoBufferSize),
     };
 
     this._priv_bitrateInfos = {
@@ -613,8 +548,13 @@ class Player extends EventEmitter<IPublicAPIEvent> {
     this.stop();
 
     if (this.videoElement !== null) {
-      // free resources used for EME management
-      disposeEME(this.videoElement);
+      // free resources used for decryption management
+      disposeDecryptionResources(this.videoElement)
+        .catch((err : unknown) => {
+          const message = err instanceof Error ? err.message :
+                                                 "Unknown error";
+          log.error("API: Could not dispose decryption resources: " + message);
+        });
     }
 
     // free Observables linked to the Player instance
@@ -627,6 +567,7 @@ class Player extends EventEmitter<IPublicAPIEvent> {
     this._priv_speed.finish();
     this._priv_contentLock.finish();
     this._priv_bufferOptions.wantedBufferAhead.finish();
+    this._priv_bufferOptions.maxVideoBufferSize.finish();
     this._priv_bufferOptions.maxBufferAhead.finish();
     this._priv_bufferOptions.maxBufferBehind.finish();
     this._priv_bitrateInfos.manualBitrates.video.finish();
@@ -1025,28 +966,26 @@ class Player extends EventEmitter<IPublicAPIEvent> {
     const playerState$ = observableConcat(
       observableOf(PLAYER_STATES.LOADING), // Begin with LOADING
 
-      // LOADED as soon as the first "loaded" event is sent
-      loaded$.pipe(take(1), map(() => PLAYER_STATES.LOADED)),
-
-      observableMerge(
-        loadedStateUpdates$
-          .pipe(
-            // From the first reload onward, we enter another dynamic (below)
+      loaded$.pipe(switchMap((_, i) => {
+        const isFirstLoad = i === 0;
+        return observableMerge(
+          // Purposely subscribed first so a RELOADING triggered synchronously
+          // after a LOADED state is catched.
+          reloading$.pipe(map(() => PLAYER_STATES.RELOADING)),
+          // Only switch to LOADED state for the first (i.e. non-RELOADING) load
+          isFirstLoad ? observableOf(PLAYER_STATES.LOADED) :
+                        EMPTY,
+          // Purposely put last so any other state change happens after we've
+          // already switched to LOADED
+          loadedStateUpdates$.pipe(
             takeUntil(reloading$),
-            skipWhile(state => state === PLAYER_STATES.PAUSED)
-          ),
-
-        // when reloading
-        reloading$.pipe(
-          switchMap(() =>
-            loaded$.pipe(
-              take(1), // wait for the next loaded event
-              mergeMap(() => loadedStateUpdates$), // to update the state as usual
-              startWith(PLAYER_STATES.RELOADING) // Starts with "RELOADING" state
-            )
+            // For the first load, we prefer staying at the LOADED state over
+            // PAUSED when autoPlay is disabled.
+            // For consecutive loads however, there's no LOADED state.
+            skipWhile(state => isFirstLoad && state === PLAYER_STATES.PAUSED)
           )
-        )
-      )
+        );
+      }))
     ).pipe(distinctUntilChanged());
 
     let playbackSubscription : Subscription|undefined;
@@ -1338,7 +1277,24 @@ class Player extends EventEmitter<IPublicAPIEvent> {
 
     const { isDirectFile, manifest } = this._priv_contentInfos;
     if (isDirectFile) {
-      return this.videoElement.currentTime;
+      // Calculating the "wall-clock time" necessitate to obtain first an offset,
+      // and then adding that offset to the HTMLMediaElement's current position.
+      // That offset is in most case present inside the Manifest file, yet in
+      // directfile mode, the RxPlayer won't parse that file, the browser does it.
+      //
+      // Thankfully Safari declares a `getStartDate` method allowing to obtain
+      // that offset when available. This logic is thus mainly useful when
+      // playing HLS contents in directfile mode on Safari.
+      const mediaElement : HTMLMediaElement & {
+        getStartDate? : () => number | null | undefined;
+      } = this.videoElement;
+      if (typeof mediaElement.getStartDate === "function") {
+        const startDate = mediaElement.getStartDate();
+        if (typeof startDate === "number" && !isNaN(startDate)) {
+          return startDate + mediaElement.currentTime;
+        }
+      }
+      return mediaElement.currentTime;
     }
     if (manifest !== null) {
       const currentTime = this.videoElement.currentTime;
@@ -1757,6 +1713,7 @@ class Player extends EventEmitter<IPublicAPIEvent> {
    * If the volume was set to 0, set a default volume instead (see config).
    */
   unMute() : void {
+    const { DEFAULT_UNMUTED_VOLUME } = config.getCurrent();
     const vol = this.getVolume();
     if (vol === 0) {
       this.setVolume(this._priv_mutedMemory === 0 ? DEFAULT_UNMUTED_VOLUME :
@@ -1865,6 +1822,15 @@ class Player extends EventEmitter<IPublicAPIEvent> {
     this._priv_bufferOptions.wantedBufferAhead.setValue(sizeInSeconds);
   }
 
+  /**
+   * Set the max buffer size the buffer should take in memory
+   * The player . will stop downloading chunks when this size is reached.
+   * @param {Number} sizeInKBytes
+   */
+  setMaxVideoBufferSize(sizeInKBytes : number) : void {
+    this._priv_bufferOptions.maxVideoBufferSize.setValue(sizeInKBytes);
+  }
+
   /**
    * Returns the max buffer size for the buffer behind the current position.
    * @returns {Number}
@@ -1889,6 +1855,14 @@ class Player extends EventEmitter<IPublicAPIEvent> {
     return this._priv_bufferOptions.wantedBufferAhead.getValue();
   }
 
+  /**
+   * Returns the max buffer memory size for the buffer in kilobytes
+   * @returns {Number}
+   */
+  getMaxVideoBufferSize() : number {
+    return this._priv_bufferOptions.maxVideoBufferSize.getValue();
+  }
+
   /**
    * Returns type of current keysystem (e.g. playready, widevine) if the content
    * is encrypted. null otherwise.
@@ -2336,25 +2310,23 @@ class Player extends EventEmitter<IPublicAPIEvent> {
 
     this._priv_contentEventsMemory = {};
 
-    // EME cleaning
+    // DRM-related clean-up
     const freeUpContentLock = () => {
       log.debug("Unlocking `contentLock`. Next content can begin.");
       this._priv_contentLock.setValue(false);
     };
 
     if (!isNullOrUndefined(this.videoElement)) {
-      clearEMESession(this.videoElement)
-        .subscribe({
-          error: (err : unknown) => {
-            log.error("API: An error arised when trying to clean-up the EME session:" +
-                      (err instanceof Error ? err.toString() :
-                                              "Unknown Error"));
-            freeUpContentLock();
-          },
-          complete: () => {
-            log.debug("API: EME session cleaned-up with success!");
-            freeUpContentLock();
-          },
+      clearOnStop(this.videoElement).then(
+        () => {
+          log.debug("API: DRM session cleaned-up with success!");
+          freeUpContentLock();
+        },
+        (err : unknown) => {
+          log.error("API: An error arised when trying to clean-up the DRM session:" +
+                    (err instanceof Error ? err.toString() :
+                                            "Unknown Error"));
+          freeUpContentLock();
         });
     } else {
       freeUpContentLock();
@@ -2975,7 +2947,75 @@ class Player extends EventEmitter<IPublicAPIEvent> {
     return activeRepresentations[currentPeriod.id];
   }
 }
-Player.version = /* PLAYER_VERSION */"3.26.2";
+Player.version = /* PLAYER_VERSION */"3.27.0-dev.2022031700";
+
+/** Payload emitted with a `positionUpdate` event. */
+export interface IPositionUpdateItem {
+  /** current position the player is in, in seconds. */
+  position : number;
+  /** Last position set for the current media currently, in seconds. */
+  duration : number;
+  /** Playback rate (i.e. speed) at which the current media is played. */
+  playbackRate : number;
+  /** Amount of buffer available for now in front of the current position, in seconds. */
+  bufferGap : number;
+  /** Current maximum seekable position. */
+  maximumBufferTime? : number | undefined;
+  wallClockTime? : number | undefined;
+  /**
+   * Only for live contents. Difference between the "live edge" and the current
+   * position, in seconds.
+   */
+  liveGap? : number | undefined;
+}
+
+/** Payload emitted with a `bitrateEstimationChange` event. */
+export interface IBitrateEstimate {
+  /** The type of buffer this estimate was done for (e.g. "audio). */
+  type : IBufferType;
+  /** The calculated bitrate, in bits per seconds. */
+  bitrate : number | undefined;
+}
+
+export type IStreamEvent = { data: IStreamEventData;
+                             start: number;
+                             end: number;
+                             onExit?: () => void; } |
+                           { data: IStreamEventData;
+                             start: number; };
+
+/** Every events sent by the RxPlayer's public API. */
+interface IPublicAPIEvent {
+  playerStateChange : string;
+  positionUpdate : IPositionUpdateItem;
+  audioTrackChange : ITMAudioTrack | null;
+  textTrackChange : ITMTextTrack | null;
+  videoTrackChange : ITMVideoTrack | null;
+  audioBitrateChange : number;
+  videoBitrateChange : number;
+  imageTrackUpdate : { data: IBifThumbnail[] };
+  fullscreenChange : boolean;
+  bitrateEstimationChange : IBitrateEstimate;
+  volumeChange : number;
+  error : ICustomError | Error;
+  warning : ICustomError | Error;
+  nativeTextTracksChange : TextTrack[];
+  periodChange : Period;
+  availableAudioBitratesChange : number[];
+  availableVideoBitratesChange : number[];
+  availableAudioTracksChange : ITMAudioTrackListItem[];
+  availableTextTracksChange : ITMTextTrackListItem[];
+  availableVideoTracksChange : ITMVideoTrackListItem[];
+  decipherabilityUpdate : Array<{ manifest : Manifest;
+                                  period : Period;
+                                  adaptation : Adaptation;
+                                  representation : Representation; }>;
+  seeking : null;
+  seeked : null;
+  streamEvent : IStreamEvent;
+  streamEventSkip : IStreamEvent;
+  inbandEvents : IInbandEvent[];
+}
 
 export default Player;
 export { IStreamEventData };

package/src/core/api/track_choice_manager.ts

@@ -63,7 +63,7 @@ interface IVideoTrackPreferenceObject {
  */
 interface ITMAudioRepresentation { id : string|number;
                                    bitrate : number;
-                                   codec? : string; }
+                                   codec? : string | undefined; }
 
 /** Audio track returned by the TrackChoiceManager. */
 export interface ITMAudioTrack { language : string;
@@ -85,11 +85,11 @@ export interface ITMTextTrack { language : string;
  */
 interface ITMVideoRepresentation { id : string|number;
                                    bitrate : number;
-                                   width? : number;
-                                   height? : number;
-                                   codec? : string;
-                                   frameRate? : string;
-                                   hdrInfo?: IHDRInformation; }
+                                   width? : number | undefined;
+                                   height? : number | undefined;
+                                   codec? : string | undefined;
+                                   frameRate? : string | undefined;
+                                   hdrInfo?: IHDRInformation | undefined; }
 
 /** Video track returned by the TrackChoiceManager. */
 export interface ITMVideoTrack { id : number|string;
@@ -134,10 +134,11 @@ type INormalizedPreferredAudioTrack = null |
 
 /** Audio track preference when it is not set to `null`. */
 interface INormalizedPreferredAudioTrackObject {
-  normalized? : string;
-  audioDescription? : boolean;
+  normalized? : string | undefined;
+  audioDescription? : boolean | undefined;
   codec? : { all: boolean;
-             test: RegExp; };
+             test: RegExp; } |
+           undefined;
 }
 
 /** Text track preference once normalized by the TrackChoiceManager. */

package/src/core/decrypt/README.md

@@ -0,0 +1,22 @@
+# The ContentDecryptor #########################################################
+
+
+## Overview ####################################################################
+
+This directory exports the `ContentDecryptor`, which allows to easily interface
+with the browser APIs for decrypting an encrypted content, it follows the
+[Encrypted Media Extensions recommandations](https://www.w3.org/TR/encrypted-media/).
+
+The `ContentDecryptor` is a module isolated from the rest of the player taking
+a form of a class.
+It starts initializing decryption capabilities as soon as it is instanciated and
+emits various events to communicate with external code.
+
+A central concept of the `ContentDecryptor` is its states.
+As decryption initialization goes on, it reaches multiple steps on which the
+rest of the RxPlayer code might want to react.
+
+Before going in, you're encouraged to read a little about the Encrypted Media
+Extensions (EME). This code is heavy on EME APIs and may be difficult to follow
+if you don't have a vague understanding of the concept of a `MediaKeySession`
+or of a `MediaKeySystemAccess`.