Add 4 new API methods

doc/api/.docConfig.json

@@ -53,12 +53,8 @@
       "displayName": "Buffer Control"
     },
     {
-      "path": "./Buffer_Information",
-      "displayName": "Buffer Information"
-    },
-    {
-      "path": "./Content_Information",
-      "displayName": "Content Information"
+      "path": "./Playback_Information",
+      "displayName": "Playback Information"
     },
     {
       "path": "./Static_Properties.md",

doc/api/Miscellaneous/Deprecated_APIs.md

@@ -229,7 +229,7 @@ You can replace this API by using the
 ### getCurrentKeySystem
 
 `getCurrentKeySystem` has been deprecated in profit of the similar
-[`getKeySystemConfiguration`](../Content_Information/getKeySystemConfiguration.md)
+[`getKeySystemConfiguration`](../Playback_Information/getKeySystemConfiguration.md)
 method.
 
 Note however that the key system string optionally returned as a `keySystem`

doc/api/Content_Information/.docConfig.json → doc/api/Playback_Information/.docConfig.json

@@ -19,6 +19,26 @@
     {
       "path": "./createDebugElement.md",
       "displayName": "createDebugElement"
+    },
+    {
+      "path": "./getVideoBufferGap.md",
+      "displayName": "getVideoBufferGap"
+    },
+    {
+      "path": "./isContentLoaded.md",
+      "displayName": "isContentLoaded"
+    },
+    {
+      "path": "./isBuffering.md",
+      "displayName": "isBuffering"
+    },
+    {
+      "path": "./isPaused.md",
+      "displayName": "isPaused"
+    },
+    {
+      "path": "./getLastStoredContentPosition.md",
+      "displayName": "getLastStoredContentPosition"
     }
   ]
-}
+}

doc/api/Playback_Information/getLastStoredContentPosition.md

@@ -0,0 +1,36 @@
+# getLastStoredContentPosition
+
+## Description
+
+Returns the last stored position of the last played content, in seconds.
+Returns `undefined` if no content was previously loaded.
+
+This method can be useful if you want to reload using `player.loadVideo()` and not
+`player.reload()`, after an error for example.
+
+It can also be used to retrieve the position where the player was at when the error arised.
+
+## Syntax
+
+```js
+const lastStoredContentPosition = player.getLastStoredContentPosition();
+```
+
+ - **return value** `number|undefined`
+
+ #### Example
+
+```js
+const lastStoredContentPosition = player.getLastStoredContentPosition();
+
+if (lastStoredContentPosition !== undefined) {
+  player.loadVideo({
+    // ...
+    startAt: {
+      position: lastStoredContentPosition,
+    },
+  });
+}
+```
+
+

doc/api/Playback_Information/isBuffering.md

@@ -0,0 +1,16 @@
+# isBuffering
+
+## Description
+
+Returns `true` if the player is buffering.
+
+The method relies solely on the state of the player, and is a shortcut for
+`["BUFFERING", "SEEKING", "LOADING", "RELOADING"].includes(player.getPlayerState())`.
+
+## Syntax
+
+```js
+const isBuffering = player.isBuffering();
+```
+
+ - **return value** `boolean`

doc/api/Playback_Information/isContentLoaded.md

@@ -0,0 +1,17 @@
+# isContentLoaded
+
+## Description
+
+Returns `true` if a content is loaded. If it is, the player is ready to play and you can
+use APIs interacting with the current content such as `seekTo` or `setAudioTrack`.
+
+The method relies solely on the state of the player, and is a shortcut for
+`!(["LOADING", "RELOADING", "STOPPED"].includes(player.getPlayerState()))`.
+
+## Syntax
+
+```js
+const isContentLoaded = player.isContentLoaded();
+```
+
+ - **return value** `boolean`

doc/api/Playback_Information/isPaused.md

@@ -0,0 +1,18 @@
+# isPaused
+
+## Description
+
+Returns the play/pause status of the player, that can be used for example to display a play/pause button:
+  - when the player is (re)loading, returns the scheduled play/pause condition
+    for when loading is over,
+  - in other states, returns the `<video>` element `.paused` value,
+  - if the player is disposed, returns `true`.
+
+
+## Syntax
+
+```js
+const isPaused = player.isPaused();
+```
+
+ - **return value** `boolean`

doc/reference/API_Reference.md

@@ -406,9 +406,6 @@ properties, methods, events and so on.
   - [`isMute`](../api/Volume_Control/isMute.md):
     Return `true` if the audio volume is set to `0`.
 
-  - [`isMute`](../api/Volume_Control/isMute.md):
-    Return `true` if the audio volume is set to `0`.
-
   - [`unMute`](../api/Volume_Control/unMute.md):
     Restore the volume as it was before it was muted.
 
@@ -438,10 +435,35 @@ properties, methods, events and so on.
     Get the maximum memory the video buffer can take up in the memory, in
     kilobytes.
 
-  - [`getVideoBufferGap`](../api/Buffer_Information/getVideoBufferGap.md):
+  - [`getUrl`](../api/Playback_Information/getUrl.md):
+    Get URL of the currently-played content.
+
+  - [`updateContentUrls`](../api/Playback_Information/updateContentUrls.md):
+    Update URL(s) of the content currently being played.
+
+  - [`isLive`](../api/Playback_Information/isLive.md):
+    Returns `true` if the content is a "live" content.
+
+  - [`getKeySystemConfiguration`](../api/Playback_Information/getKeySystemConfiguration.md):
+    Returns information on the key system currently attached to the
+    HTMLMediaElement linked to the RxPlayer.
+
+  - [`getVideoBufferGap`](../api/Playback_Information/getVideoBufferGap.md):
     Returns in seconds the difference between the current position and the end
     of the current media time range.
 
+  - [`isContentLoaded`](../api/Playback_Information/isContentLoaded.md):
+    Returns `true` if a content is loaded.
+
+  - [`isBuffering`](../api/Playback_Information/isBuffering.md):
+    Returns `true` if the player is buffering.
+
+  - [`isPaused`](../api/Playback_Information/isPaused.md):
+    Returns `true` if the `<video>` element is paused.
+
+  - [`getLastStoredContentPosition`](../api/Playback_Information/getLastStoredContentPosition.md):
+    Returns the last stored content position, in seconds. 
+
   - [`getVideoLoadedTime`](../api/Deprecated/getVideoLoadedTime.md):
     [Deprecated] Returns in seconds the difference between the start and the end
     of the current media time range.
@@ -450,19 +472,6 @@ properties, methods, events and so on.
     [Deprecated] Returns in seconds the difference between the start of the
     current media time range and the current position.
 
-  - [`getUrl`](../api/Content_Information/getUrl.md):
-    Get URL of the currently-played content.
-
-  - [`updateContentUrls`](../api/Content_Information/updateContentUrls.md):
-    Update URL(s) of the content currently being played.
-
-  - [`isLive`](../api/Content_Information/isLive.md):
-    Returns `true` if the content is a "live" content.
-
-  - [`getKeySystemConfiguration`](../api/Content_Information/getKeySystemConfiguration.md):
-    Returns information on the key system currently attached to the
-    HTMLMediaElement linked to the RxPlayer.
-
   - [`getCurrentKeySystem`](../api/Deprecated/getCurrentKeySystem.md):
     [Deprecated] Returns the name of the current key system.
 

src/core/api/public_api.ts

@@ -69,6 +69,7 @@ import {
   IVideoTrackPreference,
 } from "../../public_types";
 import areArraysOfNumbersEqual from "../../utils/are_arrays_of_numbers_equal";
+import arrayIncludes from "../../utils/array_includes";
 import assert from "../../utils/assert";
 import EventEmitter, {
   IEventPayload,
@@ -307,6 +308,11 @@ class Player extends EventEmitter<IPublicAPIEvent> {
     reloadPosition?: number;
   };
 
+  /**
+   * Store last value of autoPlay, from the last load or reload.
+   */
+  private _priv_lastAutoPlay: boolean;
+
   /** All possible Error types emitted by the RxPlayer. */
   static get ErrorTypes() : Record<IErrorType, IErrorType> {
     return ErrorTypes;
@@ -481,6 +487,8 @@ class Player extends EventEmitter<IPublicAPIEvent> {
     this._priv_preferredVideoTracks = preferredVideoTracks;
 
     this._priv_reloadingMetadata = {};
+
+    this._priv_lastAutoPlay = false;
   }
 
   /**
@@ -551,6 +559,7 @@ class Player extends EventEmitter<IPublicAPIEvent> {
     log.info("API: Calling loadvideo", options.url, options.transport);
     this._priv_reloadingMetadata = { options };
     this._priv_initializeContentPlayback(options);
+    this._priv_lastAutoPlay = options.autoPlay;
   }
 
   /**
@@ -839,11 +848,12 @@ class Player extends EventEmitter<IPublicAPIEvent> {
       log.warn("API: Sending warning:", formattedError);
       this.trigger("warning", formattedError);
     });
-    initializer.addEventListener("reloadingMediaSource", () => {
+    initializer.addEventListener("reloadingMediaSource", (payload) => {
       contentInfos.segmentBuffersStore = null;
       if (contentInfos.trackChoiceManager !== null) {
         contentInfos.trackChoiceManager.resetPeriods();
       }
+      this._priv_lastAutoPlay = payload.autoPlay;
     });
     initializer.addEventListener("inbandEvents", (inbandEvents) =>
       this.trigger("inbandEvents", inbandEvents));
@@ -1109,6 +1119,42 @@ class Player extends EventEmitter<IPublicAPIEvent> {
     return this.state;
   }
 
+  /**
+   * Returns true if a content is loaded.
+   * @returns {Boolean} - `true` if a content is loaded, `false` otherwise.
+   */
+  isContentLoaded() : boolean {
+    return !arrayIncludes(["LOADING", "RELOADING", "STOPPED"], this.state);
+  }
+
+  /**
+   * Returns true if the player is buffering.
+   * @returns {Boolean} - `true` if the player is buffering, `false` otherwise.
+   */
+  isBuffering() : boolean {
+    return arrayIncludes(["BUFFERING", "SEEKING", "LOADING", "RELOADING"], this.state);
+  }
+
+  /**
+   * Returns the play/pause status of the player :
+   *   - when `LOADING` or `RELOADING`, returns the scheduled play/pause condition
+   *     for when loading is over,
+   *   - in other states, returns the `<video>` element .paused value,
+   *   - if the player is disposed, returns `true`.
+   * @returns {Boolean} - `true` if the player is paused or will be after loading,
+   * `false` otherwise.
+   */
+  isPaused() : boolean {
+    if (this.videoElement) {
+      if (arrayIncludes(["LOADING", "RELOADING"], this.state)) {
+        return !this._priv_lastAutoPlay;
+      } else {
+        return this.videoElement.paused;
+      }
+    }
+    return true;
+  }
+
   /**
    * Returns true if both:
    *   - a content is loaded
@@ -1288,6 +1334,15 @@ class Player extends EventEmitter<IPublicAPIEvent> {
     return this.videoElement.currentTime;
   }
 
+  /**
+   * Returns the last stored content position, in seconds.
+   *
+   * @returns {number|undefined}
+   */
+  getLastStoredContentPosition() : number|undefined {
+    return this._priv_reloadingMetadata.reloadPosition;
+  }
+
   /**
    * Returns the current playback rate at which the video plays.
    * @returns {Number}

src/core/init/media_source_content_initializer.ts

@@ -356,7 +356,7 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
         if (initCanceller.isUsed()) {
           return;
         }
-        triggerEvent("reloadingMediaSource", null);
+        triggerEvent("reloadingMediaSource", reloadOrder);
         if (initCanceller.isUsed()) {
           return;
         }

src/core/init/types.ts

@@ -117,7 +117,15 @@ export interface IContentInitializerEvents {
    * Event sent when we're starting attach a new MediaSource to the media element
    * (after removing the previous one).
    */
-  reloadingMediaSource: null;
+  reloadingMediaSource: {
+    /** The position we're reloading at, in seconds. */
+    position: number;
+    /**
+     * If `true`, we'll play directly after finishing the reloading operation.
+     * If `false`, we'll be paused after it.
+     */
+    autoPlay: boolean;
+  };
   /** Event sent after the player stalled. */
   stalled : IStallingSituation;
   /** Event sent when the player goes out of a stalling situation. */