shaka-player 4.1.1 → 4.2.0

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="BBED8D28">
+         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="BBED8D28">
+         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="BBED8D28">
+         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="BBED8D28">
+         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="BBED8D28">
+         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': 'BBED8D28',
+  'castReceiverAppId': '07AEE832',
   // Enable casting to native Android Apps (e.g. Android TV Apps)
   'castAndroidReceiverCompatible': true,
 });

package/docs/tutorials/upgrade.md

@@ -25,6 +25,7 @@ application:
     - TextDecoder/TextEncoder platform support or polyfill required (affects
       Xbox One, but not evergreen browsers); we suggest the polyfill
       [https://github.com/anonyco/FastestSmallestTextEncoderDecoder](fastestsmallesttextencoderdecoder/EncoderDecoderTogether.min.js)
+      Fallback included by default in v4.2
 
   - Support removed:
     - IE11 support removed

package/docs/tutorials/welcome.md

@@ -98,11 +98,14 @@ You can find a full list of available browsers with `--browsers help`, and you
 can find a complete list of testing options with `--help`.
 
 
-#### Join the announcement list
+#### Announcements
 
-If you want to receive release or survey announcements, you should join our
+To subscribe to new releases on GitHub, you can follow
+[instructions from this blog](https://www.jessesquires.com/blog/2020/07/30/github-tip-watching-releases/).
+
+To receive infrequent announcements and surveys from us, you can join our
 [mailing list](https://groups.google.com/forum/#!forum/shaka-player-users).
-The list is very low volume.
+The list is very low volume, and can only be written to by us.
 
 
 #### Continue the Tutorials

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/karma.conf.js

@@ -160,10 +160,6 @@ module.exports = (config) => {
       'node_modules/es6-promise-polyfill/promise.js',
       //   Babel polyfill, required for async/await
       'node_modules/@babel/polyfill/dist/polyfill.js',
-      //   TextDecoder polyfill, required for TextDecoder/TextEncoder on IE and
-      //   legacy Edge
-      //   eslint-disable-next-line max-len
-      'node_modules/fastestsmallesttextencoderdecoder/EncoderDecoderTogether.min.js',
 
       // muxjs module next
       'node_modules/mux.js/dist/mux.min.js',
@@ -306,13 +302,6 @@ module.exports = (config) => {
     // Force failure when running empty test-suites.
     failOnEmptyTestSuite: true,
 
-    coverageReporter: {
-      includeAllSources: true,
-      reporters: [
-        {type: 'text'},
-      ],
-    },
-
     specReporter: {
       suppressSkipped: true,
       showBrowser: true,
@@ -405,9 +394,12 @@ module.exports = (config) => {
 
     config.set({
       coverageReporter: {
+        includeAllSources: true,
         reporters: [
           {type: 'html', dir: 'coverage'},
           {type: 'cobertura', dir: 'coverage', file: 'coverage.xml'},
+          {type: 'json-summary', dir: 'coverage', file: 'coverage.json'},
+          {type: 'json', dir: 'coverage', file: 'coverage-details.json'},
         ],
       },
     });

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;

package/lib/ads/client_side_ad_manager.js

@@ -427,7 +427,7 @@ shaka.ads.ClientSideAdManager = class {
   onAdComplete_(e) {
     this.onEvent_(new shaka.util.FakeEvent(shaka.ads.AdManager.AD_STOPPED,
         (new Map()).set('originalEvent', e)));
-    if (this.ad_.isLinear()) {
+    if (this.ad_ && this.ad_.isLinear()) {
       this.adContainer_.removeAttribute('ad-active');
       this.video_.play();
     }

package/lib/dash/dash_parser.js

@@ -513,6 +513,11 @@ shaka.dash.DashParser = class {
         }
         presentationTimeline.setClockOffset(offset);
       }
+
+      // This is the first point where we have a meaningful presentation start
+      // time, and we need to tell PresentationTimeline that so that it can
+      // maintain consistency from here on.
+      presentationTimeline.lockStartTime();
     } else {
       // Just update the variants and text streams, which may change as periods
       // are added or removed.