shaka-player 4.6.4 → 4.7.0

package/docs/tutorials/ad_monetization.md

@@ -1,292 +0,0 @@
-# Monetization with Ads
-
-Shaka Player provides an API for serving ads to make monetization easier
-for apps. Our current API is tailored for our integration with the
-[Interactive Media Ads][] SDKs, but we plan to extend our support to
-other ad providers in v3.1+.
-Please note that the current API is likely to undergo significant
-changes as our support extends.
-
-#### AWS Elemental MediaTailor Integration
-
-Shaka Player provides an integration with the [AWS Elemental MediaTailor][].
-We support Client Side, Server Side and overlays ad insertion.
-
-[AWS Elemental MediaTailor]: https://aws.amazon.com/mediatailor/
-
-All ad insertion experiences are available through the
-{@linksource shaka.extern.IAdManager} object on the Player.
-
-If you're not using Shaka's UI library, you will
-also need to create a `<div>` over your video element to serve as an ad
-container.
-
-Start by initializing the server side logic.
-With Shaka UI:
-
-```js
-const video = document.getElementById('video');
-const ui = video['ui'];
-const controls = video.ui.getControls();
-// If you're using a non-UI build, this is the div you'll need to create
-// for your layout.
-const container = controls.getServerSideAdContainer();
-const player = controls.getPlayer();
-const netEngine = player.getNetworkingEngine();
-const adManager = player.getAdManager();
-adManager.initMediaTailor(container, netEngine, video);
-```
-
-Requesting a Client Side stream:
-
-```js
-const mediaTailorUrl = 'https://d305rncpy6ne2q.cloudfront.net/v1/session/94063eadf7d8c56e9e2edd84fdf897826a70d0df/SFP-MediaTailor-VOD-HLS-DASH/out/v1/b94f3611978f419985a18335bac9d9cb/ddb73bf548a44551a0059c346226445a/eaa5485198bf497284559efb8172425e/index.mpd';
-const mediaTailorAdsParams = {
-  adsParams: {
-    assetid: 'test2',
-    podduration: '15',
-  },
-};
-const uri = await adManager.requestMediaTailorStream(mediaTailorUrl, mediaTailorAdsParams);
-player.load(uri);
-```
-
-Requesting a Server Side stream:
-
-```js
-const mediaTailorUrl = 'https://ad391cc0d55b44c6a86d232548adc225.mediatailor.us-east-1.amazonaws.com/v1/session/d02fedbbc5a68596164208dd24e9b48aa60dadc7/singssai/master.m3u8';
-const uri = await adManager.requestMediaTailorStream(mediaTailorUrl);
-player.load(uri);
-```
-
-Note: overlays ad insertions is the same as server side.
-
-#### IMA SDK Integration
-
-Shaka Player provides an integration with the [Interactive Media Ads][] SDKs.
-We support both Client Side and Server Side ad insertion.
-
-
-[Interactive Media Ads]: https://developers.google.com/interactive-media-ads
-
-Both the Client Side and the Server Side ad insertion experiences are available
-through the {@linksource shaka.extern.IAdManager} object on the Player.
-
-
-```js
-const adManager = player.getAdManager();
-```
-
-First, you'll need to include the IMA SDK(s) on your HTML page:
-
-```html
-<!DOCTYPE html>
-<html>
-  <head>
-    <!-- Shaka Player ui compiled library: -->
-    <script src="dist/shaka-player.ui.js"></script>
-    <!-- Shaka Player ui compiled library default CSS: -->
-    <link rel="stylesheet" type="text/css" href="dist/controls.css">
-    <!-- IMA HTML5 SDK (for serving Client Side ads): -->
-    <script type="text/javascript" src="https://imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
-    <!-- IMA DAI SDK (for serving Server Side ads): -->
-    <script type="text/javascript" src="https://imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
-    <!-- Your application source: -->
-    <script src="myapp.js"></script>
-  </head>
-</html>
-```
-
-#### Streaming with Client Side Ads Insertion
-
-To integrate Client Side ads into a presentation, you need to have your ad tag
-URIs. If you're not using Shaka's UI library, you will also need to create a
-`<div>` over your video element to serve as an ad container.
-
-Start by initializing the client side logic.
-With Shaka UI:
-
-```js
-const adManager = player.getAdManager();
-const video = document.getElementById('video');
-const ui = video['ui'];
-// If you're using a non-UI build, this is the div you'll need to create
-// for your layout.  The ad manager will clear this div, when it unloads, so
-// don't pass in a div that contains non-ad elements.
-const container = video.ui.getControls().getClientSideAdContainer();
-adManager.initClientSide(container, video);
-```
-
-With the client side logic initialized, you can request ads at any time during
-the presentation.
-
-```js
-const adsRequest = new google.ima.AdsRequest();
-// Your ad tag url should go here. We are using a sample ad tag from the
-// IMA HTML5 SDK implementation guide for this tutorial.
-adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' +
-    'sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&' +
-    'impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&' +
-    'cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=';
-adManager.requestClientSideAds(adsRequest);
-```
-
-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
-Manager account and host your streams on Google Ad Manager's servers. To find
-out more about the Google Ad Manager service or sign up for an account, visit
-https://admanager.google.com/
-
-If you're not using Shaka's UI library, you will
-also need to create a `<div>` over your video element to serve as an ad
-container.
-
-Start by initializing the server side logic.
-With Shaka UI:
-
-```js
-const adManager = player.getAdManager();
-const video = document.getElementById('video');
-const ui = video['ui'];
-// If you're using a non-UI build, this is the div you'll need to create
-// for your layout.
-const container = video.ui.getControls().getServerSideAdContainer();
-adManager.initServerSide(container, video);
-```
-
-With server side logic initialized, you can request and load streams with
-dynamically inserted ads.
-
-Requesting a VOD stream:
-
-```js
-const streamRequest = new google.ima.dai.api.VODStreamRequest();
-// Your stream information will go here. We are using IMA's sample stream info
-// in this tutorial.
-streamRequest.contentSourceId = '2528370';
-streamRequest.videoId = 'tears-of-steel';
-const uri = await adManager.requestServerSideStream(streamRequest);
-player.load(uri);
-```
-
-`shaka.extern.IAdManager.requestServerSideStream()` returns a Promise with a
-manifest URI that points to a stream with ads inserted.
-
-See [google.ima.dai.api.VODStreamRequest][] for details on the request object.
-
-[google.ima.dai.api.VODStreamRequest]: https://developers.google.com/interactive-media-ads/docs/sdks/html5/dai/reference/js/VODStreamRequest
-
-Requesting a LIVE stream:
-
-```js
-const streamRequest = new google.ima.dai.api.LiveStreamRequest();
-// Your stream information will go here. We are using IMA's sample stream info
-// in this tutorial.
-streamRequest.assetKey = 'sN_IYUG8STe1ZzhIIE_ksA';
-const uri = await adManager.requestServerSideStream(streamRequest);
-player.load(uri);
-```
-
-See: [google.ima.dai.api.LiveStreamRequest][] for details on the request object.
-
-[google.ima.dai.api.LiveStreamRequest]: https://developers.google.com/interactive-media-ads/docs/sdks/html5/dai/reference/js/LiveStreamRequest
-
-If you are using Shaka's UI library, we will automatically hook up our ad UI.
-
-#### Listening To Ad Events
-We unify Server Side and Client Side ad events into our own Shaka ad events and
-objects. which your application can listen to and interact with.
-Check out the {@link shaka.ads.AdManager#event:AdBreakReadyEvent|full list of 
-ad events} for details.
-
-Let's register a simple listener to Shaka's AD_STARTED event. It will log the
-start of the ad in the console.
-
-```js
-adManager.addEventListener(shaka.ads.AdManager.AD_STARTED, () => {
-  console.log('An ad has started');
-});
-```
-
-Every shaka ad event contains an original SDK event and an ad object if those
-are available. Most apps are unlikely to need them, but if you have a use case
-that requires access to those, here is how to get them:
-
-```js
-// Note that unlike in the previous example, we are capturing the AD_STARTED
-// event object here (the "e" parameter of the lambda function) so we can access
-// its properties.
-adManager.addEventListener(shaka.ads.AdManager.AD_STARTED, (e) => {
-  const sdkAdObject = e['sdkAdObject'];
-  const originalEvent = e['originalEvent'];
-});
-```
-
-#### Accommodating IMA Power Users
-If you have an existing IMA integration you want to plug into Shaka, or you want
-to use more intricate SDK capabilities not exposed through our API, we provide a
-way to do that.
-Listen to the {@link shaka.ads.AdManager#event:ImaAdManagerLoadedEvent} for
-Client Side or the {@link shaka.ads.AdManager#event:ImaStreamManagerLoadedEvent}
-for Server Side to get the IMA [AdManager][] or [StreamManager][] objects.
-
-```js
-adManager.addEventListener(shaka.ads.AdManager.IMA_AD_MANAGER_LOADED, (e) => {
-  const imaAdManager = e['imaAdManager'];
-});
-
-adManager.addEventListener(shaka.ads.AdManager.IMA_STREAM_MANAGER_LOADED, (e) => {
-  const imaStreamManager = e['imaStreamManager'];
-});
-```
-[AdManager]: https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.AdsManager
-[StreamManager]: https://developers.google.com/interactive-media-ads/docs/sdks/html5/dai/reference/js/StreamManager
-
-#### Disabling Cookies For Serving Limited Ads
-The server side IMA SDK allows limited ads to be served when the user does not
-give or denies consent to cookies. To allow this, set the `ltd` parameter using
-`StreamRequest.adTagParameters` as described in the [IMA limited ads guide][].
-To set up cookie-less manifest and segment requests, use an appropriate
-`requestFilter`. Please note that `request.withCredentials` flag is `false` by
-default, so you should only need to set this if you've enabled it in other parts of
-your code.
-
-```js
-  player.getNetworkingEngine().registerRequestFilter(function(type, request, context) {
-    if (type == shaka.net.NetworkingEngine.RequestType.MANIFEST ||
-        type == shaka.net.NetworkingEngine.RequestType.SEGMENT) {
-      request.withCredentials = false;
-    }
-  });
-```
-[IMA limited ads guide]: https://developers.devsite.corp.google.com/interactive-media-ads/docs/sdks/html5/dai/limited-ads
-
-#### Custom Ad Manager Implementations
-Our architecture supports custom ad manager implementations. Every ad manager
-should implement the {@linksource shaka.extern.IAdManager} interface. To make
-the player use a custom ad manager implementation, invoke the code to set it
-before instantiating the player.
-
-```js
-// myapp.CustomAdManager is a placeholder name for your ad manager implementation.
-shaka.Player.setAdManagerFactory(() => new myapp.CustomAdManager());
-```

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

@@ -1,94 +0,0 @@
-# Application-Level Redirects
-
-Not all browsers will follow an HTTP redirect on a preflighted cross-origin
-request.  For more detailed background on Cross-Origin Resource Sharing (CORS),
-see [MDN's CORS article](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
-and in particular, the section titled "Preflighted requests and redirects".
-
-Some services have decided to work around this limitation by not using HTTP
-redirects at all, but rather using a technique called Application-Level
-Redirects or ALRs.  In this setup, the server will return an HTTP 200 response
-instead of an HTTP 302 redirect, and the new URL will be placed in the response
-body where the client can access it.
-
-With Shaka Player, it is possible to support this scheme through response
-filters.  The ALR response filter examines the response, determines if the
-response is an ALR, and if so, starts a new request.  The response to the new
-request replaces the original response.
-
-There are many potential reasons for these redirects, such as authentication or
-load-balancing.  There are also many possible schemes for a server to signal an
-Application-Level Redirect to a client.  Because it is "application-level", it
-is completely up to the application to define how it works.  Therefore we do not
-offer built-in ALR functionality in Shaka Player.  Instead, we give a full
-example here of how a particular ALR scheme might work.
-
-In this example, the ALR's full response body is the new URL.  It can be
-detected by looking for "http" in the beginning of the response body.  These
-ALRs are done on manifest requests, for the specific purpose of cookie-based
-authentication.  So the filter below checks for `RequestType.MANIFEST` and sets
-`allowCrossSiteCredentials`.  Please customize these details for your own
-purposes and ALR schemes.
-
-```js
-// The UTF-8 characters "h", "t", "t", and "p".
-const HTTP_IN_HEX = 0x68747470;
-
-const RequestType = shaka.net.NetworkingEngine.RequestType;
-
-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) {
-    return;
-  }
-
-  const dataView = new DataView(response.data);
-  if (response.data.byteLength < 4 ||
-      dataView.getUint32(0) != HTTP_IN_HEX) {
-    // Our ALRs are detected by a response body which is a URL.
-    // This doesn't start with "http", so it is not an ALR.
-    return;
-  }
-
-  // It's an Application-Level Redirect (ALR).  That requires us to get the new
-  // URL and follow it.
-
-  // Interpret the response data as a URL string.
-  const responseAsString = shaka.util.StringUtils.fromUTF8(response.data);
-
-  // For maximum flexibility for those who will copy and paste this whole code
-  // snippet, check the type of the request to determine what retry parameters
-  // to use.  Those who are reading and customizing this code can hard-code the
-  // parameters instead.
-  let retryParameters;
-  if (type == RequestType.MANIFEST) {
-    retryParameters = player.getConfiguration().manifest.retryParameters;
-  } else if (type == RequestType.SEGMENT) {
-    retryParameters = player.getConfiguration().streaming.retryParameters;
-  } else if (type == RequestType.LICENSE) {
-    retryParameters = player.getConfiguration().drm.retryParameters;
-  } else {
-    retryParameters = shaka.net.NetworkingEngine.defaultRetryParameters();
-  }
-
-  // Make another request for the redirect URL.
-  const uris = [responseAsString];
-  const redirectRequest =
-      shaka.net.NetworkingEngine.makeRequest(uris, retryParameters);
-
-  // NOTE: Only do this if the purpose of the redirect is authentication.  If
-  // the ALR is meant for something like load-balancing, remove the next line.
-  redirectRequest.allowCrossSiteCredentials = true;
-
-  const requestOperation =
-      player.getNetworkingEngine().request(type, redirectRequest);
-  const redirectResponse = await requestOperation.promise;
-
-  // Modify the original response to contain the results of the redirect
-  // response.
-  response.data = redirectResponse.data;
-  response.headers = redirectResponse.headers;
-  response.uri = redirectResponse.uri;
-});
-```

package/docs/tutorials/architecture.md

@@ -1,32 +0,0 @@
-# Architecture Diagrams
-
-<img
-  src="../design/dataflow.gv.png"
-  alt="Shaka data flow diagram"
-  style="max-width: 100%">
-
-<img
-  src="../design/ownership.gv.png"
-  alt="Shaka ownership diagram"
-  style="max-width: 100%">
-
-<img
-  src="../design/cast.gv.png"
-  alt="Shaka cast diagram"
-  style="max-width: 100%;">
-
-<img
-  src="../design/offline.gv.png"
-  alt="Shaka offline diagram"
-  style="max-width: 100%">
-
-<img
-  src="../design/timeline.svg"
-  alt="PresentationTimeline diagram"
-  style="max-width: 100%">
-
-<img
-  src="../design/newdemo.gv.png"
-  alt="Demo page architecture"
-  style="max-width: 100%">
-

package/docs/tutorials/basic-usage.md

@@ -1,89 +0,0 @@
-# Basic Usage
-
-Basic usage of Shaka Player is very easy:
-
-1. Start with {@tutorial welcome} and compile the library.
-2. Create a simple HTML page with a video or audio element.
-3. In your application's JavaScript -
-    1. Install Shaka's polyfills.
-    2. Check for browser support.
-    3. Create a Player object to wrap the media element.
-    4. Listen for errors.
-    5. Load a manifest.
-
-```html
-<!DOCTYPE html>
-<html>
-  <head>
-    <!-- Shaka Player compiled library: -->
-    <script src="dist/shaka-player.compiled.js"></script>
-    <!-- Your application source: -->
-    <script src="myapp.js"></script>
-  </head>
-  <body>
-    <video id="video"
-           width="640"
-           poster="//shaka-player-demo.appspot.com/assets/poster.jpg"
-           controls autoplay></video>
-  </body>
-</html>
-```
-
-```js
-// myapp.js
-
-const manifestUri =
-    'https://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mpd';
-
-function initApp() {
-  // Install built-in polyfills to patch browser incompatibilities.
-  shaka.polyfill.installAll();
-
-  // Check to see if the browser supports the basic APIs Shaka needs.
-  if (shaka.Player.isBrowserSupported()) {
-    // Everything looks good!
-    initPlayer();
-  } else {
-    // This browser does not have the minimum set of APIs we need.
-    console.error('Browser not supported!');
-  }
-}
-
-async function initPlayer() {
-  // Create a Player instance.
-  const video = document.getElementById('video');
-  const player = new shaka.Player();
-  await player.attach(video);
-
-  // Attach player to the window to make it easy to access in the JS console.
-  window.player = player;
-
-  // Listen for error events.
-  player.addEventListener('error', onErrorEvent);
-
-  // Try to load a manifest.
-  // This is an asynchronous process.
-  try {
-    await player.load(manifestUri);
-    // This runs if the asynchronous load is successful.
-    console.log('The video has now been loaded!');
-  } catch (e) {
-    // onError is executed if the asynchronous load fails.
-    onError(e);
-  }
-}
-
-function onErrorEvent(event) {
-  // Extract the shaka.util.Error object from the event.
-  onError(event.detail);
-}
-
-function onError(error) {
-  // Log the error.
-  console.error('Error code', error.code, 'object', error);
-}
-
-document.addEventListener('DOMContentLoaded', initApp);
-```
-
-That's it!

package/docs/tutorials/blob-url.md

@@ -1,15 +0,0 @@
-# Blob URL
-
-In case you need shaka-player to load a blob url mpd:
-
-`player.load(computedMpdBlobURL, startTime, 'application/dash+xml');`
-
-
-In case you need shaka-player to load a blob url m3u8 :
-
-`player.load(computedMpdBlobURL, startTime, 'application/x-mpegurl');`
-
-
-Note: relative URIs in the manifest are broken because the original manifest URI is lost. This can be worked around with either absolute URIs or the use of BaseURL element in DASH.
-
-Note: this tutorial only applies to v3.3 or higher

package/docs/tutorials/config.md

@@ -1,148 +0,0 @@
-# Configuration
-
-The goal of this tutorial is to introduce Shaka's configuration system and the
-concepts on which it is built.  More detail can be found in the API docs.
-
-Shaka's `Player` object has a hierarchical configuration.  The overall player
-config contains sub-configs for various parts of the system, such as manifests,
-streaming, and DRM.
-
-To see the current config, you can use `player.getConfiguration()`.  If you run
-this without setting anything first, you get the default configuration.
-
-`Player` also has a `configure()` method that takes it's argument(s) in one of two
-forms:
-
-1. A plain, anonymous object.  Any fields you leave out of the config object
-will retain their existing values, and any fields you explicitly set as
-`undefined` will be reverted to their default value.  For example:
-
-```js
-player.configure({
-  streaming: {
-    bufferingGoal: 120
-  }
-});
-```
-
-2. For setting a single field, a name (full path) of the field can be provided
-as the first argument (a string) and value of the field as the second. For
-example:
-
-```js
-player.configure('streaming.bufferingGoal', 120);
-```
-
-You can use the code from {@tutorial basic-usage} and try these examples in
-the JS console:
-
-```js
-player.getConfiguration();
-
-=> Object
-     abr: Object
-       bandwidthDowngradeTarget: 0.95
-       bandwidthUpgradeTarget: 0.85
-       defaultBandwidthEstimate: 500000
-       enabled: true
-       restrictions: Object
-       switchInterval: 8
-     abrFactory: Function
-     drm: Object
-       advanced: Object
-       clearKeys: Object
-       retryParameters: Object
-         backoffFactor: 2
-         baseDelay: 1000
-         fuzzFactor: 0.5
-         maxAttempts: 2
-         timeout: 0
-       servers: Object
-     manifest: Object
-       dash: Object
-       retryParameters: Object
-     playRangeEnd: Infinity
-     playRangeStart: 0
-     preferredAudioLanguage: ""
-     preferredAudioLabel: ""
-     preferredTextLanguage: ""
-     restrictions: Object
-     streaming: Object
-       bufferBehind: 30
-       bufferingGoal: 10
-       durationBackoff: 1
-       failureCallback: Function
-       ignoreTextStreamFailures: false
-       alwaysStreamText: false
-       rebufferingGoal: 2
-       retryParameters: Object
-       startAtSegmentBoundary: false
-       safeSeekOffset: 5
-       segmentPrefetchLimit: 0
-     textDisplayFactory: Function
-
-
-// Example configurations, all of which are arbitrary:
-
-// set audio language preference to Canadian French:
-player.configure('preferredAudioLanguage', 'fr-CA');
-// NOTE: language preferences affect the next call to load()
-
-// set text language preference to Greek and buffering goal to 2 minutes:
-player.configure({
-  preferredTextLanguage: 'el',
-  streaming: {
-    bufferingGoal: 120
-  }
-});
-
-// check audio language preference, which is still Canadian French:
-player.getConfiguration().preferredAudioLanguage
-
-// check buffering goal, which is 2 minutes:
-player.getConfiguration().streaming.bufferingGoal
-
-// check rebuffering goal, which is still the default of 2 seconds:
-player.getConfiguration().streaming.rebufferingGoal
-
-// set the rebuffering goal to 15 seconds and revert buffering goal to default:
-player.configure({
-  streaming: {
-    bufferingGoal: undefined,
-    rebufferingGoal: 15
-  }
-});
-```
-
-Some of these fields have immediate effects (such as networking settings and
-buffering settings) while some will not have any effect until the next call to
-`load()` (such as DRM settings, manifest settings, and language settings).
-
-
-#### Low latency streaming
-
-With `.streaming.lowLatencyMode` set to true,
-`.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, 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,
-  }
-});
-
-```
-
-
-#### Detailed API Docs
-
-For more detail on individual configuration options, please see the API docs for
-{@link shaka.extern.PlayerConfiguration} and {@link shaka.Player#configure}.