shaka-player 4.3.9 → 4.4.0

package/docs/tutorials/ad_monetization.md

@@ -81,6 +81,20 @@ See: [google.ima.AdsRequest][] for details on the request object.
 
 [google.ima.AdsRequest]: https://developers.google.com/interactive-media-ads/docs/sdks/html5/v3/reference/js/ima.AdsRequest
 
+Control the rendering of ads:
+
+```js
+const adsRenderingSettings = new google.ima.AdsRenderingSettings();
+adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
+adManager.initClientSide(container, video, adsRenderingSettings);
+// Updates the ads rendering settings.
+adManager.updateClientSideAdsRenderingSettings(adsRenderingSettings);
+```
+
+See: [google.ima.AdsRenderingSettings][] for details on the request object.
+
+[google.ima.AdsRenderingSettings]: https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.AdsRenderingSettings
+
 #### Streaming with Server Side Ads Insertion
 
 To integrate Server Side ads into a presentation, you need to have a Google Ad
@@ -203,7 +217,7 @@ default, so you should only need to set this if you've enabled it in other parts
 your code.
 
 ```js
-  player.getNetworkingEngine().registerRequestFilter(function(type, request) {
+  player.getNetworkingEngine().registerRequestFilter(function(type, request, context) {
     if (type == shaka.net.NetworkingEngine.RequestType.MANIFEST ||
         type == shaka.net.NetworkingEngine.RequestType.SEGMENT) {
       request.withCredentials = false;

package/docs/tutorials/application-level-redirects.md

@@ -36,7 +36,7 @@ const HTTP_IN_HEX = 0x68747470;
 
 const RequestType = shaka.net.NetworkingEngine.RequestType;
 
-player.getNetworkingEngine().registerResponseFilter(async (type, response) => {
+player.getNetworkingEngine().registerResponseFilter(async (type, response, context) => {
   // NOTE: If the system requires an ALR for both manifests and segments,
   // remove this RequestType check.
   if (type != RequestType.MANIFEST) {

package/docs/tutorials/config.md

@@ -64,6 +64,7 @@ player.getConfiguration();
      playRangeEnd: Infinity
      playRangeStart: 0
      preferredAudioLanguage: ""
+     preferredAudioLabel: ""
      preferredTextLanguage: ""
      restrictions: Object
      streaming: Object
@@ -77,6 +78,7 @@ player.getConfiguration();
        retryParameters: Object
        startAtSegmentBoundary: false
        safeSeekOffset: 5
+       segmentPrefetchLimit: 0
      textDisplayFactory: Function
 
 
@@ -120,18 +122,20 @@ buffering settings) while some will not have any effect until the next call to
 #### Low latency streaming
 
 With `.streaming.lowLatencyMode` set to true,
-`.streaming.inaccurateManifestTolerance` is set to 0 by default, and
-`.streaming.rebufferingGoal` is set to 0.01 by default.
+`.streaming.inaccurateManifestTolerance` is set to 0 by default,
+`.streaming.rebufferingGoal` is set to 0.01 by default, and
+`.streaming.segmentPrefetchLimit` is set to 2 by default.
 
-To customize the values of inaccurateManifestTolerance and rebufferingGoal
-with low latency mode, you can set the fields in the same or subsequent
-call to configure().
+To customize the values of inaccurateManifestTolerance, rebufferingGoal and
+segmentPrefetchLimit with low latency mode, you can set the fields in the same
+or subsequent call to configure().
 ```js
 player.configure({
   streaming: {
     lowLatencyMode: true,
     inaccurateManifestTolerance: 0,
     rebufferingGoal: 0.01,
+    segmentPrefetchLimit: 2,
   }
 });
 

package/docs/tutorials/drm-config.md

@@ -211,3 +211,64 @@ you should provide an empty string as robustness
 ##### Other key-systems
 
 Values for other key systems are not known to us at this time.
+
+#### Re-use persistent license DRM for online playback
+
+If your DRM provider configuration allows you to deliver persistent license,
+you could re-use the created MediaKeys session for the next online playback.
+
+Configure Shaka to start DRM sessions with the `persistent-license` type
+instead of the `temporary` one:
+
+```js
+player.configure({
+  drm: {
+    advanced: {
+      'com.widevine.alpha': {
+        'sessionType': 'persistent-license'
+      }
+    }
+  }
+});
+```
+
+**Using `persistent-license` might not work on every devices, use this feature
+carefully.**
+
+When the playback starts, you can retrieve the sessions metadata:
+
+```js
+const activeDrmSessions = this.player.getActiveSessionsMetadata();
+const persistentDrmSessions = activeDrmSessions.filter(
+  ({ sessionType }) => sessionType === 'persistent-license');
+
+// Add your own storage mechanism here, give it an unique known identifier for
+// the playing video
+```
+
+When starting the same video again, retrieve the metadata from the storage, and
+set it back to Shaka's configuration.
+
+Shaka will load the given DRM persistent sessions and will only request a
+license if some keys are missing for the content.
+
+```js
+player.configure({
+  drm: {
+    persistentSessionOnlinePlayback: true,
+    persistentSessionsMetadata: [{
+      sessionId: 'deadbeefdeadbeefdeadbeefdeadbeef',
+      initData: new InitData(0),
+      initDataType: 'cenc'
+    }]
+  }
+});
+```
+
+NB: Shaka doesn't provide a out-of-the-box storage mechanism for the sessions
+metadata.
+
+#### Continue the Tutorials
+
+Next, check out {@tutorial license-server-auth}.
+Or check out {@tutorial fairplay}.

package/docs/tutorials/fairplay.md

@@ -90,7 +90,7 @@ or give the response in a different format.  For more info, see the general
 {@tutorial license-wrapping} tutorial:
 
 ```js
-player.getNetworkingEngine().registerRequestFilter((type, request) => {
+player.getNetworkingEngine().registerRequestFilter((type, request, context) => {
   if (type != shaka.net.NetworkingEngine.RequestType.LICENSE) {
     return;
   }
@@ -103,7 +103,7 @@ player.getNetworkingEngine().registerRequestFilter((type, request) => {
   request.body = shaka.util.StringUtils.toUTF8(encodeURIComponent(params));
 });
 
-player.getNetworkingEngine().registerResponseFilter((type, response) => {
+player.getNetworkingEngine().registerResponseFilter((type, response, context) => {
   if (type != shaka.net.NetworkingEngine.RequestType.LICENSE) {
     return;
   }
@@ -143,7 +143,7 @@ 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) => {
+player.getNetworkingEngine().registerRequestFilter((type, request, context) => {
   if (type != shaka.net.NetworkingEngine.RequestType.LICENSE) {
     return;
   }
@@ -175,7 +175,7 @@ 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) => {
+player.getNetworkingEngine().registerRequestFilter((type, request, context) => {
   if (type != shaka.net.NetworkingEngine.RequestType.LICENSE) {
     return;
   }
@@ -217,3 +217,18 @@ player.getNetworkingEngine()
 player.configure('drm.initDataTransform',
                  FairPlayUtils.conaxInitDataTransform);
 ```
+
+#### ExpressPlay (legacy Apple Media Keys)
+
+For integration with ExpressPlay the following can be used:
+
+```js
+shaka.polyfill.PatchedMediaKeysApple.install();
+const FairPlayUtils = shaka.util.FairPlayUtils;
+player.getNetworkingEngine()
+    .registerRequestFilter(FairPlayUtils.expressplayFairPlayRequest);
+player.getNetworkingEngine()
+    .registerResponseFilter(FairPlayUtils.commonFairPlayResponse);
+player.configure('drm.initDataTransform',
+                 FairPlayUtils.expressplayInitDataTransform);
+```

package/docs/tutorials/license-server-auth.md

@@ -62,7 +62,7 @@ arbitrary headers to Shaka's requests through a request filter callback.
 Register the filter before calling `player.load()`:
 
 ```js
-  player.getNetworkingEngine().registerRequestFilter(function(type, request) {
+  player.getNetworkingEngine().registerRequestFilter(function(type, request, context) {
     // Only add headers to license requests:
     if (type == shaka.net.NetworkingEngine.RequestType.LICENSE) {
       // This is the specific header name and value the server wants:
@@ -92,7 +92,7 @@ try to use it without setting the parameter, you will see `Error code 6007`
 We can use a request filter to modify the URL and add the required parameter:
 
 ```js
-  player.getNetworkingEngine().registerRequestFilter(function(type, request) {
+  player.getNetworkingEngine().registerRequestFilter(function(type, request, context) {
     // Only add headers to license requests:
     if (type == shaka.net.NetworkingEngine.RequestType.LICENSE) {
       // This is the specific parameter name and value the server wants:
@@ -140,7 +140,7 @@ Our `cookie_auth` endpoint sends back headers that allow credentialed requests,
 so we set a flag in our request filter to send credentials cross-site:
 
 ```js
-  player.getNetworkingEngine().registerRequestFilter(function(type, request) {
+  player.getNetworkingEngine().registerRequestFilter(function(type, request, context) {
     if (type == shaka.net.NetworkingEngine.RequestType.LICENSE) {
       request.allowCrossSiteCredentials = true;
     }
@@ -205,7 +205,7 @@ const authToken = null;
 Now change the request filter:
 
 ```js
-  player.getNetworkingEngine().registerRequestFilter(function(type, request) {
+  player.getNetworkingEngine().registerRequestFilter(function(type, request, context) {
     // Only add headers to license requests:
     if (type != shaka.net.NetworkingEngine.RequestType.LICENSE) return;
 

package/docs/tutorials/license-wrapping.md

@@ -65,7 +65,7 @@ will see `Error code 6007`, which means `LICENSE_REQUEST_FAILED`.  To wrap the
 license request, we must register a request filter:
 
 ```js
-  player.getNetworkingEngine().registerRequestFilter(function(type, request) {
+  player.getNetworkingEngine().registerRequestFilter(function(type, request, context) {
     // Alias some utilities provided by the library.
     const StringUtils = shaka.util.StringUtils;
     const Uint8ArrayUtils = shaka.util.Uint8ArrayUtils;
@@ -136,7 +136,7 @@ Widevine CDM does not understand this wrapped format, so we must unwrap it first
 using a request filter:
 
 ```js
-  player.getNetworkingEngine().registerResponseFilter(function(type, response) {
+  player.getNetworkingEngine().registerResponseFilter(function(type, response, context) {
     // Alias some utilities provided by the library.
     const StringUtils = shaka.util.StringUtils;
     const Uint8ArrayUtils = shaka.util.Uint8ArrayUtils;

package/docs/tutorials/ui-customization.md

@@ -61,7 +61,8 @@ The following elements can be added to the UI bar using this configuration value
   starts playing the presentation at an increased speed
 * spacer: adds a chunk of empty space between the adjacent elements.
 * picture_in_picture: adds a button that enables/disables picture-in-picture mode on browsers
-  that support it. Button is invisible on other browsers.
+  that support it. Button is invisible on other browsers. Note that it will use the
+  [Document Picture-in-Picture API]() if supported.
 * loop: adds a button that controls if the currently selected video is played in a loop.
 * airplay: adds a button that opens a AirPlay dialog. The button is visible only if the browser
   supports AirPlay.
@@ -72,6 +73,7 @@ The following elements can be added to the UI bar using this configuration value
 * playback_rate: adds a button that controls the playback rate selection.
 * captions: adds a button that controls the current text track selection (including turning it off).
 <!-- TODO: If we add more buttons that can be put in the order this way, list them here. -->
+[Document Picture-in-Picture API]: https://developer.chrome.com/docs/web-platform/document-picture-in-picture/
 
 Similarly, the 'overflowMenuButtons' configuration option can be used to control
 the contents of the overflow menu.
@@ -83,7 +85,8 @@ The following buttons can be added to the overflow menu:
 * quality: adds a button that controls enabling/disabling of abr and video resolution selection.
 * language: adds a button that controls audio language selection.
 * picture_in_picture: adds a button that enables/disables picture-in-picture mode on browsers
-  that support it. Button is invisible on other browsers.
+  that support it. Button is invisible on other browsers. Note that it will use the 
+  [Document Picture-in-Picture API]() if supported.
 * loop: adds a button that controls if the currently selected video is played in a loop.
 * playback_rate: adds a button that controls the playback rate selection.
 * airplay: adds a button that opens a AirPlay dialog. The button is visible only if the browser
@@ -122,7 +125,8 @@ The following buttons can be added to the context menu:
 * Statistics: adds a button that displays statistics of the video.
 * loop: adds a button that controls if the currently selected video is played in a loop.
 * picture_in_picture: adds a button that enables/disables picture-in-picture mode on browsers
-  that support it. Button is invisible on other browsers.
+  that support it. Button is invisible on other browsers. Note that it will use the 
+  [Document Picture-in-Picture API]() if supported.
 
 Example:
 ```js

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="8D8C71A7">
+         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="8D8C71A7">
+         data-shaka-player-cast-receiver-id="07AEE832">
     </div>
 ```
 
@@ -139,7 +139,7 @@ casting to an Android receiver app.
 
 ```html
     <div data-shaka-player-container style="max-width:40em"
-         data-shaka-player-cast-receiver-id="8D8C71A7"
+         data-shaka-player-cast-receiver-id="07AEE832"
          data-shaka-player-cast-android-receiver-compatible="true">
       <!-- The manifest url in the src attribute will be automatically loaded -->
       <video autoplay data-shaka-player id="video" style="width:100%;height:100%"
@@ -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="8D8C71A7">
+         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="8D8C71A7">
+         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="8D8C71A7">
+         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': '8D8C71A7',
+  'castReceiverAppId': '07AEE832',
   // Enable casting to native Android Apps (e.g. Android TV Apps)
   'castAndroidReceiverCompatible': true,
 });

package/docs/tutorials/upgrade.md

@@ -96,3 +96,6 @@ application:
   - Configuration changes:
     - `streaming.forceTransmuxTS` has been renamed to `streaming.forceTransmux`
       (deprecated in v4.3.0)
+
+  - Plugin changes:
+    - `Transmuxer` plugins now has three new parameters in `transmux()` method.

package/externs/ima.js

@@ -108,19 +108,93 @@ google.ima.AdsManager = class {
 
   /** @override */
   dispatchEvent() {}
+
+  /**
+   * @param {!google.ima.AdsRenderingSettings} adsRenderingSettings
+   */
+  updateAdsRenderingSettings(adsRenderingSettings) {}
 };
 
 
 /** @const */
 google.ima.AdsManagerLoadedEvent = class extends Event {
   /**
-   * @param {!HTMLElement} video
+   * @param {!(HTMLElement|{currentTime: number})} video
+   * @param {!google.ima.AdsRenderingSettings=} adsRenderingSettings
    * @return {!google.ima.AdsManager}
    */
-  getAdsManager(video) {}
+  getAdsManager(video, adsRenderingSettings) {}
 };
 
 
+/**
+ * @typedef {{
+ *   autoAlign: (boolean),
+ *   bitrate: (number),
+ *   enablePreloading: (boolean),
+ *   loadVideoTimeout: (number),
+ *   mimeTypes: (?Array.<string>),
+ *   playAdsAfterTime: (number),
+ *   restoreCustomPlaybackStateOnAdBreakComplete: (boolean),
+ *   uiElements: (?Array.<string>),
+ *   useStyledLinearAds: (boolean),
+ *   useStyledNonLinearAds: (boolean),
+ * }}
+ *
+ * @description Defines parameters that control the rendering of ads.
+ * @property {boolean} autoAlign
+ *   Set to false if you wish to have fine grained control over
+ *   the positioning of all non-linear ads.
+ *   If this value is true, the ad is positioned in the bottom center.
+ *   If this value is false, the ad is positioned in the top left corner.
+ *   The default value is true.
+ * @property {number} bitrate
+ *   Maximum recommended bitrate. The value is in kbit/s.
+ *   The SDK will pick media with bitrate below the specified max,
+ *   or the closest bitrate if there is no media with lower bitrate found.
+ *   Default value, -1, means the SDK selects the maximum bitrate.
+ * @property {boolean} enablePreloading
+ *   Enables preloading of video assets.
+ *   For more info see [our guide to preloading media]{@link https://developers.google.com/interactive-media-ads/docs/sdks/html5/preload}.
+ * @property {number} loadVideoTimeout
+ *   Timeout (in milliseconds) when loading a video ad media file.
+ *   If loading takes longer than this timeout, the ad playback is canceled
+ *   and the next ad in the pod plays, if available.
+ *   Use -1 for the default of 8 seconds.
+ * @property {?Array.<string>} mimeTypes
+ *   Only supported for linear video mime types.
+ *   If specified, the SDK will include media that matches
+ *   the MIME type(s) specified in the list and exclude media.
+ *   that does not match the specified MIME type(s).
+ *   The format is a list of strings,
+ *   for example, [ 'video/mp4', 'video/webm', ... ] If not specified,
+ *   the SDK will pick the media based on player capabilities.
+ * @property {number} playAdsAfterTime
+ *   For VMAP and ad rules playlists, only play ad breaks scheduled
+ *   after this time (in seconds).
+ *   This setting is strictly after - for example,
+ *   setting playAdsAfterTime to 15 will cause IMA to ignore
+ *   an ad break scheduled to play at 15s.
+ * @property {boolean} restoreCustomPlaybackStateOnAdBreakComplete
+ *   Specifies whether or not the SDK should restore the custom playback
+ *   state after an ad break completes. This is setting is used primarily
+ *   when the publisher passes in its content player to use for
+ *   custom ad playback.
+ * @property {?Array.<string>} uiElements
+ *   Specifies whether the UI elements that should be displayed.
+ *   The elements in this array are ignored for AdSense/AdX ads.
+ * @property {boolean} useStyledLinearAds
+ *   Render linear ads with full UI styling.
+ *   This setting does not apply to AdSense/AdX ads
+ *   or ads played in a mobile context that already
+ *   use full UI styling by default.
+ * @property {boolean} useStyledNonLinearAds
+ *   Render non-linear ads with a close and recall button.
+ * @exportDoc
+ */
+google.ima.AdsRenderingSettings;
+
+
 /** @const */
 google.ima.AdDisplayContainer = class {
   /**
@@ -173,6 +247,24 @@ google.ima.Ad = class {
 
   /** @return {string} */
   getDescription() {}
+
+  /** @return {number} */
+  getVastMediaBitrate() {}
+
+  /** @return {number} */
+  getVastMediaHeight() {}
+
+  /** @return {number} */
+  getVastMediaWidth() {}
+
+  /** @return {string} */
+  getAdId() {}
+
+  /** @return {string} */
+  getCreativeAdId() {}
+
+  /** @return {?string} */
+  getMediaUrl() {}
 };
 
 
@@ -183,6 +275,12 @@ google.ima.AdPodInfo = class {
 
   /** @return {number} */
   getTotalAds() {}
+
+  /** @return {number} */
+  getTimeOffset() {}
+
+  /** @return {number} */
+  getPodIndex() {}
 };
 
 /** @const */
@@ -206,6 +304,11 @@ google.ima.ImaSdkSettings = class {
    * @param {google.ima.ImaSdkSettings.VpaidMode} vpaidMode
    */
   setVpaidMode(vpaidMode) {}
+
+  /**
+   * @param {boolean} disable
+   */
+  setDisableCustomPlaybackForIOS10Plus(disable) {}
 };
 
 /**
@@ -401,6 +504,18 @@ google.ima.dai.api.Ad = class {
 
   /** @return {string} */
   getDescription() {}
+
+  /** @return {number} */
+  getVastMediaHeight() {}
+
+  /** @return {number} */
+  getVastMediaWidth() {}
+
+  /** @return {string} */
+  getAdId() {}
+
+  /** @return {string} */
+  getCreativeAdId() {}
 };
 
 
@@ -411,6 +526,12 @@ google.ima.dai.api.AdPodInfo = class {
 
   /** @return {number} */
   getTotalAds() {}
+
+  /** @return {number} */
+  getTimeOffset() {}
+
+  /** @return {number} */
+  getPodIndex() {}
 };