shaka-player 4.1.3 → 4.2.1

package/docs/tutorials/fairplay.md

@@ -1,8 +1,41 @@
 # FairPlay Support
 
 We support FairPlay with EME on compatible environments or native `src=`.
+
+By default Shaka Player supports Modern EME, if your provider doesn't support
+Modern EME yet, you can use legacy Apple Media Keys with:
+```js
+shaka.polyfill.PatchedMediaKeysApple.install();
+```
+
+The support in each case would be the following:
+
+|            |Modern EME |legacy Apple Media Keys|
+|:----------:|:---------:|:---------------------:|
+|src= (CMAF) |**Y**      |**Y**                  |
+|src= (TS)   |**Y**      |**Y**                  |
+|MSE (CMAF)  |**Y**      | -                     |
+|MSE (TS)    | -         | -                     |
+
+
 Adding FairPlay support involves a bit more work than other key systems.
 
+
+## Keysystem used in EME
+
+Depending on the EME implementation that is being used, the Fairplay keysystem
+varies.
+
+For Modern EME:
+```
+com.apple.fps
+```
+
+For legacy Apple Media Keys:
+```
+com.apple.fps.1_0
+```
+
 ## Server certificate
 
 All FairPlay content requires setting a server certificate. You can either
@@ -22,6 +55,27 @@ player.configure('drm.advanced.com\\.apple\\.fps\\.serverCertificateUri',
                  'https://example.com/cert.der');
 ```
 
+## Content ID
+
+Note: Normally only applies to legacy Apple Media Keys but some providers also
+need it in Modern EME.
+
+Some FairPlay content use custom signaling for the content ID.  The content ID
+is used by the browser to generate the license request.  If you don't use the
+default content ID derivation, you need to specify a custom init data transform:
+
+```js
+player.configure('drm.initDataTransform', (initData, initDataType) => {
+  if (initDataType != 'skd')
+    return initData;
+  // 'initData' is a buffer containing an 'skd://' URL as a UTF-8 string.
+  const skdUri = shaka.util.StringUtils.fromBytesAutoDetect(initData);
+  const contentId = getMyContentId(skdUri);
+  const cert = player.drmInfo().serverCertificate;
+  return shaka.util.FairPlayUtils.initDataTransform(initData, contentId, cert);
+});
+```
+
 ## License wrapping
 
 Some FairPlay servers need to accept the license request in a different format
@@ -61,3 +115,98 @@ player.getNetworkingEngine().registerResponseFilter((type, response) => {
   response.data = shaka.util.Uint8ArrayUtils.fromBase64(responseText).buffer;
 });
 ```
+
+### Integration with some DRMs providers
+
+Note: Some providers support both Modern EME and legacy Apple Media Keys.
+
+#### EZDRM (Modern EME)
+
+For integration with EZDRM the following can be used:
+
+```js
+const FairPlayUtils = shaka.util.FairPlayUtils;
+player.getNetworkingEngine()
+    .registerRequestFilter(FairPlayUtils.ezdrmFairPlayRequest);
+player.getNetworkingEngine()
+    .registerResponseFilter(FairPlayUtils.commonFairPlayResponse);
+```
+
+Note: If the url of the license server has to undergo any transformation
+(eg: add the contentId), you would have to create your filter manually.
+
+```js
+player.getNetworkingEngine().registerRequestFilter((type, request) => {
+  if (type != shaka.net.NetworkingEngine.RequestType.LICENSE) {
+    return;
+  }
+  const uri = request.uris[0];
+  const FairPlayUtils = shaka.util.FairPlayUtils;
+  const contentId = FairPlayUtils.defaultGetContentId(request.initData);
+  const newUri = uri.replace('^assetId^', contentId);
+  request.uris = [newUri];
+  request.headers['Content-Type'] = 'application/octet-stream'
+});
+```
+
+#### EZDRM (legacy Apple Media Keys)
+
+For integration with EZDRM the following can be used:
+
+```js
+shaka.polyfill.PatchedMediaKeysApple.install();
+const FairPlayUtils = shaka.util.FairPlayUtils;
+player.getNetworkingEngine()
+    .registerRequestFilter(FairPlayUtils.ezdrmFairPlayRequest);
+player.getNetworkingEngine()
+    .registerResponseFilter(FairPlayUtils.commonFairPlayResponse);
+player.configure('drm.initDataTransform',
+                 FairPlayUtils.ezdrmInitDataTransform);
+```
+
+Note: If the url of the license server has to undergo any transformation
+(eg: add the contentId), you would have to create your filter manually.
+
+```js
+player.getNetworkingEngine().registerRequestFilter((type, request) => {
+  if (type != shaka.net.NetworkingEngine.RequestType.LICENSE) {
+    return;
+  }
+  const uri = request.uris[0];
+  const FairPlayUtils = shaka.util.FairPlayUtils;
+  const contentId = FairPlayUtils.defaultGetContentId(request.initData);
+  const newUri = uri.replace('^assetId^', contentId);
+  request.uris = [newUri];
+  request.headers['Content-Type'] = 'application/octet-stream'
+});
+```
+
+#### Verimatrix (legacy Apple Media Keys)
+
+For integration with Verimatrix the following can be used:
+
+```js
+shaka.polyfill.PatchedMediaKeysApple.install();
+const FairPlayUtils = shaka.util.FairPlayUtils;
+player.getNetworkingEngine()
+    .registerRequestFilter(FairPlayUtils.verimatrixFairPlayRequest);
+player.getNetworkingEngine()
+    .registerResponseFilter(FairPlayUtils.commonFairPlayResponse);
+player.configure('drm.initDataTransform',
+                 FairPlayUtils.verimatrixInitDataTransform);
+```
+
+#### Conax (legacy Apple Media Keys)
+
+For integration with Conax the following can be used:
+
+```js
+shaka.polyfill.PatchedMediaKeysApple.install();
+const FairPlayUtils = shaka.util.FairPlayUtils;
+player.getNetworkingEngine()
+    .registerRequestFilter(FairPlayUtils.conaxFairPlayRequest);
+player.getNetworkingEngine()
+    .registerResponseFilter(FairPlayUtils.commonFairPlayResponse);
+player.configure('drm.initDataTransform',
+                 FairPlayUtils.conaxInitDataTransform);
+```

package/docs/tutorials/ui.md

@@ -30,7 +30,7 @@ Set up controls with HTML data attributes:
          The data-shaka-player-cast-receiver-id tag allows you to provide a Cast Application ID that
            the cast button will cast to; the value provided here is the sample cast receiver. -->
     <div data-shaka-player-container style="max-width:40em"
-         data-shaka-player-cast-receiver-id="06EDA6EE">
+         data-shaka-player-cast-receiver-id="07AEE832">
        <!-- The data-shaka-player tag will make the UI library use this video element.
             If no video is provided, the UI will automatically make one inside the container div. -->
       <video autoplay data-shaka-player id="video" style="width:100%;height:100%"></video>
@@ -111,7 +111,7 @@ set up a listener for the 'caststatuschanged' events.
 <!-- Add a data-shaka-player-cast-receiver-id tag to provide a Cast Application ID that
            the cast button will cast to; the value provided here is the sample cast receiver. -->
     <div data-shaka-player-container style="max-width:40em"
-         data-shaka-player-cast-receiver-id="06EDA6EE">
+         data-shaka-player-cast-receiver-id="07AEE832">
     </div>
 ```
 
@@ -154,7 +154,7 @@ or a `<source>` tag inside it to enable auto loading of the specified content.
 
 ```html
     <div data-shaka-player-container style="max-width:40em"
-         data-shaka-player-cast-receiver-id="06EDA6EE">
+         data-shaka-player-cast-receiver-id="07AEE832">
       <!-- The manifest url in the src attribute will be automatically loaded -->
       <video autoplay data-shaka-player id="video" style="width:100%;height:100%"
        src="https://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mpd"></video>
@@ -165,7 +165,7 @@ or
 
 ```html
     <div data-shaka-player-container style="max-width:40em"
-         data-shaka-player-cast-receiver-id="06EDA6EE">
+         data-shaka-player-cast-receiver-id="07AEE832">
       <video autoplay data-shaka-player id="video" style="width:100%;height:100%">
         <!-- The manifest url in the src attribute will be auto loaded -->
        <source src="https://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mpd"/>
@@ -178,7 +178,7 @@ call to the first one fails.
 
 ```html
     <div data-shaka-player-container style="max-width:40em"
-         data-shaka-player-cast-receiver-id="06EDA6EE">
+         data-shaka-player-cast-receiver-id="07AEE832">
       <video autoplay data-shaka-player id="video" style="width:100%;height:100%">
         <!-- Try this first -->
         <source src="https://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mpd"/>
@@ -222,7 +222,7 @@ const video = controls.getVideo();
 // Receiver Compatability.
 ui.configure({
   // Set the castReceiverAppId
-  'castReceiverAppId': '06EDA6EE',
+  'castReceiverAppId': '07AEE832',
   // Enable casting to native Android Apps (e.g. Android TV Apps)
   'castAndroidReceiverCompatible': true,
 });

package/externs/shaka/abr_manager.js

@@ -103,6 +103,14 @@ shaka.extern.AbrManager = class {
    */
   playbackRateChanged(rate) {}
 
+  /**
+   * Set media element.
+   *
+   * @param {HTMLMediaElement} mediaElement
+   * @exportDoc
+   */
+  setMediaElement(mediaElement) {}
+
   /**
    * Sets the ABR configuration.
    *

package/externs/shaka/manifest.js

@@ -244,6 +244,49 @@ shaka.extern.Variant;
 shaka.extern.CreateSegmentIndexFunction;
 
 
+/**
+ * @typedef {{
+ *   method: string,
+ *   cryptoKey: (webCrypto.CryptoKey|undefined),
+ *   fetchKey: (shaka.extern.CreateSegmentIndexFunction|undefined),
+ *   iv: (!Uint8Array|undefined),
+ *   firstMediaSequenceNumber: number
+ * }}
+ *
+ * @description
+ * AES-128 key and iv info from the HLS manifest.
+ *
+ * @property {string} method
+ *   The key method defined in the HLS manifest.
+ * @property {webCrypto.CryptoKey|undefined} cryptoKey
+ *   Web crypto key object of the AES-128 CBC key. If unset, the "fetchKey"
+ *   property should be provided.
+ * @property {shaka.extern.FetchCryptoKeysFunction|undefined} fetchKey
+ *   A function that fetches the key.
+ *   Should be provided if the "cryptoKey" property is unset.
+ *   Should update this object in-place, to set "cryptoKey".
+ * @property {(!Uint8Array|undefined)} iv
+ *   The IV in the HLS manifest, if defined. See HLS RFC 8216 Section 5.2 for
+ *   handling undefined IV.
+ * @property {number} firstMediaSequenceNumber
+ *   The starting Media Sequence Number of the playlist, used when IV is
+ *   undefined.
+ *
+ * @exportDoc
+ */
+shaka.extern.HlsAes128Key;
+
+
+/**
+ * A function that fetches the crypto keys for AES-128.
+ * Returns a promise that resolves when the keys have been fetched.
+ *
+ * @typedef {function(): !Promise}
+ * @exportDoc
+ */
+shaka.extern.FetchCryptoKeysFunction;
+
+
 /**
  * @typedef {{
  *   id: number,

package/externs/shaka/player.js

@@ -1000,7 +1000,9 @@ shaka.extern.StreamingConfiguration;
  *   switchInterval: number,
  *   bandwidthUpgradeTarget: number,
  *   bandwidthDowngradeTarget: number,
- *   advanced: shaka.extern.AdvancedAbrConfiguration
+ *   advanced: shaka.extern.AdvancedAbrConfiguration,
+ *   restrictToElementSize: boolean,
+ *   ignoreDevicePixelRatio: boolean
  * }}
  *
  * @property {boolean} enabled
@@ -1029,7 +1031,16 @@ shaka.extern.StreamingConfiguration;
  *   The largest fraction of the estimated bandwidth we should use. We should
  *   downgrade to avoid this.
  * @property {shaka.extern.AdvancedAbrConfiguration} advanced
- *   Advanced ABR configuration.
+ *   Advanced ABR configuration
+ * @property {boolean} restrictToElementSize
+ *   If true, restrict the quality to media element size.
+ *   Note: The use of ResizeObserver is required for it to work properly. If
+ *   true without ResizeObserver, it behaves as false.
+ *   Defaults false.
+ * @property {boolean} ignoreDevicePixelRatio
+ *   If true,device pixel ratio is ignored when restricting the quality to
+ *   media element size.
+ *   Defaults false.
  * @exportDoc
  */
 shaka.extern.AbrConfiguration;

package/lib/abr/simple_abr_manager.js

@@ -10,6 +10,7 @@ goog.require('goog.asserts');
 goog.require('shaka.abr.EwmaBandwidthEstimator');
 goog.require('shaka.log');
 goog.require('shaka.util.StreamUtils');
+goog.require('shaka.util.Timer');
 
 
 /**
@@ -85,6 +86,22 @@ shaka.abr.SimpleAbrManager = class {
 
     /** @private {?shaka.extern.AbrConfiguration} */
     this.config_ = null;
+
+    /** @private {HTMLMediaElement} */
+    this.mediaElement_ = null;
+
+    /** @private {ResizeObserver} */
+    this.resizeObserver_ = null;
+
+    /** @private {shaka.util.Timer} */
+    this.resizeObserverTimer_ = new shaka.util.Timer(() => {
+      if (this.config_.restrictToElementSize) {
+        const chosenVariant = this.chooseVariant();
+        if (chosenVariant) {
+          this.switch_(chosenVariant);
+        }
+      }
+    });
   }
 
 
@@ -98,6 +115,14 @@ shaka.abr.SimpleAbrManager = class {
     this.variants_ = [];
     this.playbackRate_ = 1;
     this.lastTimeChosenMs_ = null;
+    this.mediaElement_ = null;
+
+    if (this.resizeObserver_) {
+      this.resizeObserver_.disconnect();
+      this.resizeObserver_ = null;
+    }
+
+    this.resizeObserverTimer_.stop();
 
     // Don't reset |startupComplete_|: if we've left the startup interval, we
     // can start using bandwidth estimates right away after init() is called.
@@ -120,9 +145,19 @@ shaka.abr.SimpleAbrManager = class {
   chooseVariant() {
     const SimpleAbrManager = shaka.abr.SimpleAbrManager;
 
+    let maxHeight = Infinity;
+    let maxWidth = Infinity;
+
+    if (this.resizeObserver_ && this.config_.restrictToElementSize) {
+      const devicePixelRatio =
+          this.config_.ignoreDevicePixelRatio ? 1 : window.devicePixelRatio;
+      maxHeight = this.mediaElement_.clientWidth * devicePixelRatio;
+      maxWidth = this.mediaElement_.clientHeight * devicePixelRatio;
+    }
+
     // Get sorted Variants.
     let sortedVariants = SimpleAbrManager.filterAndSortVariants_(
-        this.config_.restrictions, this.variants_);
+        this.config_.restrictions, this.variants_, maxHeight, maxWidth);
 
     const defaultBandwidthEstimate = this.getDefaultBandwidth_();
     const currentBandwidth = this.bandwidthEstimator_.getBandwidthEstimate(
@@ -137,7 +172,8 @@ shaka.abr.SimpleAbrManager = class {
       shaka.log.warning('No variants met the ABR restrictions. ' +
                         'Choosing a variant by lowest bandwidth.');
       sortedVariants = SimpleAbrManager.filterAndSortVariants_(
-          /* restrictions= */ null, this.variants_);
+          /* restrictions= */ null, this.variants_,
+          /* maxHeight= */ Infinity, /* maxWidth= */ Infinity);
       sortedVariants = [sortedVariants[0]];
     }
 
@@ -243,6 +279,28 @@ shaka.abr.SimpleAbrManager = class {
   }
 
 
+  /**
+   * @override
+   * @export
+   */
+  setMediaElement(mediaElement) {
+    this.mediaElement_ = mediaElement;
+    if (this.resizeObserver_) {
+      this.resizeObserver_.disconnect();
+      this.resizeObserver_ = null;
+    }
+    if (this.mediaElement_ && 'ResizeObserver' in window) {
+      this.resizeObserver_ = new ResizeObserver(() => {
+        const SimpleAbrManager = shaka.abr.SimpleAbrManager;
+        // Batch up resize changes before checking them.
+        this.resizeObserverTimer_.tickAfter(
+            /* seconds= */ SimpleAbrManager.RESIZE_OBSERVER_BATCH_TIME);
+      });
+      this.resizeObserver_.observe(this.mediaElement_);
+    }
+  }
+
+
   /**
    * @override
    * @export
@@ -320,11 +378,13 @@ shaka.abr.SimpleAbrManager = class {
   /**
    * @param {?shaka.extern.Restrictions} restrictions
    * @param {!Array.<shaka.extern.Variant>} variants
+   * @param {!number} maxHeight
+   * @param {!number} maxWidth
    * @return {!Array.<shaka.extern.Variant>} variants filtered according to
    *   |restrictions| and sorted in ascending order of bandwidth.
    * @private
    */
-  static filterAndSortVariants_(restrictions, variants) {
+  static filterAndSortVariants_(restrictions, variants, maxHeight, maxWidth) {
     if (restrictions) {
       variants = variants.filter((variant) => {
         // This was already checked in another scope, but the compiler doesn't
@@ -333,7 +393,7 @@ shaka.abr.SimpleAbrManager = class {
 
         return shaka.util.StreamUtils.meetsRestrictions(
             variant, restrictions,
-            /* maxHwRes= */ {width: Infinity, height: Infinity});
+            /* maxHwRes= */ {width: maxWidth, height: maxHeight});
       });
     }
 
@@ -342,3 +402,11 @@ shaka.abr.SimpleAbrManager = class {
     });
   }
 };
+
+
+/**
+ * The amount of time, in seconds, we wait to batch up rapid resize changes.
+ * This allows us to avoid multiple resize events in most cases.
+ * @type {number}
+ */
+shaka.abr.SimpleAbrManager.RESIZE_OBSERVER_BATCH_TIME = 1;