Merge pull request #1202 from canalplus/feat/getKeySystemConfiguration

Add the `getKeySystemConfiguration` method to the RxPlayer

doc/api/Content_Information/getKeySystemConfiguration.md

@@ -0,0 +1,45 @@
+# getKeySystemConfiguration
+
+## Description
+
+Returns information on the key system configuration currently associated to the
+HTMLMediaElement (e.g. `<video>` element) linked to the RxPlayer.
+
+The returned value might be null if no key system configuration is attached or
+if it is unknown, or, if a key system is attached and known, an object with the
+following properties:
+
+  - `keySystem` (`string`): The actual key system string of the key system
+    currently used.
+
+    Note that it may be different than the key system name used as `type`
+    property of the `keySystems` `loadVideo` option originally communicated.
+
+    For example, calling the `loadVideo` like this:
+    ```js
+    rxPlayer.loadVideo({
+      keySystems: [{
+        type: "widevine",
+        // ...
+      }],
+      // ...
+    });
+    ```
+    May lead to `keySystem` being set to `"com.widevine.alpha"` instead on most
+    platforms where it is its proper denomination.
+
+  - `configuration` (`Object`): The
+    [`MediaKeySystemConfiguration`](https://www.w3.org/TR/encrypted-media/#dom-mediakeysystemconfiguration)
+    actually used currently by the key system.
+
+    You may parse that configuration to deduce for example the current
+    robustness levels of the key system.
+
+
+## Syntax
+
+```js
+const values = player.getKeySystemConfiguration();
+```
+
+ - **return value** `Object|null`

doc/api/Content_Information/getCurrentKeySystem.md → doc/api/Deprecated/getCurrentKeySystem.md

@@ -1,5 +1,11 @@
 # getCurrentKeySystem
 
+<div class="warning">
+This option is deprecated, it will disappear in the next major release
+`v4.0.0` (see <a href="../Miscellaneous/Deprecated_APIs.md">Deprecated
+APIs</a>).
+</div>
+
 ## Description
 
 Returns the type of keySystem used for DRM-protected contents.

doc/api/Miscellaneous/Deprecated_APIs.md

@@ -225,6 +225,50 @@ You can read [the related chapter](#bif-apis) for more information.
 You can replace this API by using the
 [parseBifThumbnails](../Tools/parseBifThumbnails.md) tool.
 
+
+### getCurrentKeySystem
+
+`getCurrentKeySystem` has been deprecated in profit of the similar
+[`getKeySystemConfiguration`](../Content_Information/getKeySystemConfiguration.md)
+method.
+
+Note however that the key system string optionally returned as a `keySystem`
+property from the latter is slightly different than the optional string returned
+from the former:
+
+  - `getCurrentKeySystem` returned the same keysystem name used as `type`
+    property of the `keySystems` `loadVideo` option originally communicated.
+
+    For example, calling the `loadVideo` like this:
+    ```js
+    rxPlayer.loadVideo({
+      keySystems: [{
+        type: "widevine",
+        // ...
+      }],
+      // ...
+    });
+    ```
+    May lead to `getCurrentKeySystem` returning just `"widevine"`.
+
+  - The `keySystem` property from `getKeySystemConfiguration` returns the actual
+    key system string used, alongside the actual configuration used in its
+    `configuration` key.
+
+    For example, calling the `loadVideo` like this:
+    ```js
+    rxPlayer.loadVideo({
+      keySystems: [{
+        type: "widevine",
+        // ...
+      }],
+      // ...
+    });
+    ```
+    May lead to a more complex `keySystem` property being reported, like for
+    example, `"com.widevine.alpha"`.
+
+
 ## RxPlayer Events
 
 The following RxPlayer events has been deprecated.

doc/reference/API_Reference.md

@@ -459,8 +459,12 @@ properties, methods, events and so on.
   - [`isLive`](../api/Content_Information/isLive.md):
     Returns `true` if the content is a "live" content.
 
-  - [`getCurrentKeySystem`](../api/Content_Information/getCurrentKeySystem.md):
-    Returns the name of the current key system.
+  - [`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.
 
   - [`getManifest`](../api/Deprecated/getManifest.md):
     [Deprecated] Information on the current Manifest.

src/compat/__tests__/should_reload_media_source_on_decipherability_update.test.ts

@@ -19,7 +19,7 @@ import shouldReloadMediaSourceOnDecipherabilityUpdate from "../should_reload_med
 
 describe("Compat - shouldReloadMediaSourceOnDecipherabilityUpdate", () => {
   it("should return true for an unknown key system", () => {
-    expect(shouldReloadMediaSourceOnDecipherabilityUpdate(null)).toEqual(true);
+    expect(shouldReloadMediaSourceOnDecipherabilityUpdate(undefined)).toEqual(true);
   });
 
   it("should return false for any string containing the string \"widevine\"", () => {

src/compat/should_reload_media_source_on_decipherability_update.ts

@@ -21,12 +21,12 @@
  * We found that on all Widevine targets tested, a simple seek is sufficient.
  * As widevine clients make a good chunk of users, we can make a difference
  * between them and others as it is for the better.
- * @param {string|null} currentKeySystem
+ * @param {string|undefined} currentKeySystem
  * @returns {Boolean}
  */
 export default function shouldReloadMediaSourceOnDecipherabilityUpdate(
-  currentKeySystem : string | null
+  currentKeySystem : string | undefined
 ) : boolean {
-  return currentKeySystem === null ||
+  return currentKeySystem === undefined ||
          currentKeySystem.indexOf("widevine") < 0;
 }

src/core/api/public_api.ts

@@ -55,6 +55,7 @@ import {
   IBitrateEstimate,
   IConstructorOptions,
   IDecipherabilityUpdateContent,
+  IKeySystemConfigurationOutput,
   ILoadVideoOptions,
   IPeriod,
   IPlayerError,
@@ -95,6 +96,7 @@ import { IABRThrottlers } from "../adaptive";
 import {
   clearOnStop,
   disposeDecryptionResources,
+  getKeySystemConfiguration,
   getCurrentKeySystem,
 } from "../decrypt";
 import { ContentInitializer } from "../init";
@@ -1807,15 +1809,37 @@ class Player extends EventEmitter<IPublicAPIEvent> {
   /**
    * Returns type of current keysystem (e.g. playready, widevine) if the content
    * is encrypted. null otherwise.
+   * @deprecated
    * @returns {string|null}
    */
   getCurrentKeySystem() : string|null {
+    warnOnce("`getCurrentKeySystem` is deprecated." +
+             "Please use the `getKeySystemConfiguration` method instead.");
     if (this.videoElement === null) {
       throw new Error("Disposed player");
     }
     return getCurrentKeySystem(this.videoElement);
   }
 
+  /**
+   * Returns both the name of the key system (e.g. `"com.widevine.alpha"`) and
+   * the `MediaKeySystemConfiguration` currently associated to the
+   * HTMLMediaElement linked to the RxPlayer.
+   *
+   * Returns `null` if no such capabilities is associated or if unknown.
+   * @returns {Object|null}
+   */
+  getKeySystemConfiguration() : IKeySystemConfigurationOutput | null {
+    if (this.videoElement === null) {
+      throw new Error("Disposed player");
+    }
+    const values = getKeySystemConfiguration(this.videoElement);
+    if (values === null) {
+      return null;
+    }
+    return { keySystem: values[0], configuration: values[1] };
+  }
+
   /**
    * Returns every available audio tracks for the current Period.
    * @returns {Array.<Object>|null}

src/core/decrypt/get_current_key_system.ts → src/core/decrypt/get_key_system_configuration.ts

@@ -17,11 +17,32 @@
 import MediaKeysInfosStore from "./utils/media_keys_infos_store";
 
 /**
- * Returns the name of the current key system used.
+ * Returns the name of the current key system used as well as its configuration,
+ * as reported by the `MediaKeySystemAccess` itself.
+ * @param {HTMLMediaElement} mediaElement
+ * @returns {Array|null}
+ */
+export default function getKeySystemConfiguration(
+  mediaElement : HTMLMediaElement
+) : [string, MediaKeySystemConfiguration] | null {
+  const currentState = MediaKeysInfosStore.getState(mediaElement);
+  if (currentState === null) {
+    return null;
+  }
+  return [
+    currentState.mediaKeySystemAccess.keySystem,
+    currentState.mediaKeySystemAccess.getConfiguration(),
+  ];
+}
+
+/**
+ * Returns the name of the current key system used, as originally indicated by
+ * the user.
+ * @deprecated
  * @param {HTMLMediaElement} mediaElement
  * @returns {string|null}
  */
-export default function getCurrentKeySystem(
+export function getCurrentKeySystem(
   mediaElement : HTMLMediaElement
 ) : string | null {
   const currentState = MediaKeysInfosStore.getState(mediaElement);

src/core/decrypt/index.ts

@@ -25,14 +25,17 @@ import ContentDecryptor, {
   IContentDecryptorEvent,
 } from "./content_decryptor";
 import disposeDecryptionResources from "./dispose_decryption_resources";
-import getCurrentKeySystem from "./get_current_key_system";
+import getKeySystemConfiguration, {
+  getCurrentKeySystem,
+} from "./get_key_system_configuration";
 export * from "./types";
 
 export default ContentDecryptor;
 export {
   clearOnStop,
   ContentDecryptorState,
   disposeDecryptionResources,
+  getKeySystemConfiguration,
   getCurrentKeySystem,
   IContentDecryptorEvent,
 };

src/core/init/media_source_content_initializer.ts

@@ -40,7 +40,7 @@ import AdaptiveRepresentationSelector, {
 } from "../adaptive";
 import { IReadOnlyPlaybackObserver, PlaybackObserver } from "../api";
 import {
-  getCurrentKeySystem,
+  getKeySystemConfiguration,
   IContentProtection,
 } from "../decrypt";
 import {
@@ -598,8 +598,8 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
         needsMediaSourceReload: (value) => onReloadOrder(value),
 
         needsDecipherabilityFlush(value) {
-          const keySystem = getCurrentKeySystem(mediaElement);
-          if (shouldReloadMediaSourceOnDecipherabilityUpdate(keySystem)) {
+          const keySystem = getKeySystemConfiguration(mediaElement);
+          if (shouldReloadMediaSourceOnDecipherabilityUpdate(keySystem?.[0])) {
             onReloadOrder(value);
           } else {
             // simple seek close to the current position

src/public_types.ts

@@ -788,6 +788,14 @@ export interface IVideoTrack { id : number|string;
                                label? : string | undefined;
                                representations: IVideoRepresentation[]; }
 
+/** Output of the `getKeySystemConfiguration` method. */
+export interface IKeySystemConfigurationOutput {
+  /** Key system string. */
+  keySystem : string;
+  /** `MediaKeySystemConfiguration` actually used by the key system. */
+  configuration : MediaKeySystemConfiguration;
+}
+
 /** Audio track from a list of audio tracks returned by the RxPlayer. */
 export interface IAvailableAudioTrack
   extends IAudioTrack { active : boolean }