shaka-player 4.6.3 → 4.7.0

package/docs/tutorials/debugging.md

@@ -1,189 +0,0 @@
-# Debugging
-
-#### Create an error
-
-Let's say that we have some kind of error, and we want to debug it.
-To simulate this, we'll start with the code from {@tutorial basic-usage}
-and make a bad change.
-
-First, let's change `manifestUri` by removing the last letter.
-
-```js
-const manifestUri =
-    'https://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mp';
-```
-
-Now reload the page.  This causes an error in the JS console that says "Error
-code 1001".
-
-
-#### Looking up error codes
-
-Look at the Error we just logged.  It has `category: 1`, `code: 1001`.  To find
-out what that means, check the docs for {@link shaka.util.Error}.  There we find
-that `1001` means `BAD_HTTP_STATUS`:
-
-> An HTTP network request returned an HTTP status that indicated a failure.
-> error.data[0] is the URI.
-> ...
-
-So some HTTP request failed, and we can see the failed URI in `data[0]`.
-
-
-#### Loading the debug library
-
-The compiled library has no usable stack traces and no logging.  So to get more
-information, we need to switch to the debug library.  The debug library is still
-compiled into a single bundle, but logging and other debug features are enabled.
-
-To load the debug version of the library instead of the compiled version, just
-change "compiled.js" to "compiled.debug.js" in our HTML file:
-
-```html
-  <head>
-    <!-- Shaka Player debug library: -->
-    <script src="shaka-player.compiled.debug.js"></script>
-
-    <!-- Your application source: -->
-    <script src="myapp.js"></script>
-  </head>
-```
-
-Once we're using the debug library, we will be able to see detailed logs and
-line numbers for errors.
-
-
-Reload the page and look in the JavaScript console.  Now we see something
-similar to this (formatted a bit differently in the console):
-
-```js
-HEAD http://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mp 404 (Not Found)  http_plugin.js:94
-
-HEAD http://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mp 404 (Not Found)  http_plugin.js:94
-
-HEAD request to guess manifest type failed! shaka.util.Error  manifest_parser.js:179
-
-Error code 1001 object shaka.util.Error  myapp.js:45
-```
-
-We have a little more information from the library now, and we can expand the
-Error object and see a human-readable message and a stack trace:
-
-```js
-shaka.util.Error
-  category: 1
-  code: 1001
-  data: Array[3]
-    0: "http://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mp"
-    1: 404
-    2: ""
-    length: 3
-  message:
-    "Shaka Error NETWORK.BAD_HTTP_STATUS (...)"
-  stack: "Error: Shaka Error NETWORK.BAD_HTTP_STATUS (http://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mp,404,)
-    at new shaka.util.Error (http://localhost/shaka/lib/util/error.js:77:13)
-    at XMLHttpRequest.xhr.onload (http://localhost/shaka/lib/net/http_plugin.js:70:16)"
-```
-
-With the information from the debug library, we have the error name as well as
-the code.  So we could avoid looking up the number in the documentation.  The
-stack trace gives us clues about where the error was generated, so we can look
-more closely at the source code if we need to.
-
-
-#### Setting the log level
-
-Sometimes the error and stack trace isn't enough.  Sometimes you need to see a
-long sequence of events leading up to an error.  You may also be asked to attach
-logs as part of a bug report to help the Shaka Player team understand your bug.
-
-For this, you want to set the log level.  The log level lets you control what
-logs are shown by the debug library.  To set the log level, add one of these to
-the top of `initApp()` in myapp.js:
-
-```js
-// Debug logs, when the default of INFO isn't enough:
-shaka.log.setLevel(shaka.log.Level.DEBUG);
-
-// Verbose logs, which can generate a lot of output:
-shaka.log.setLevel(shaka.log.Level.V1);
-
-// Verbose 2, which is extremely noisy:
-shaka.log.setLevel(shaka.log.Level.V2);
-```
-
-Please note that this method is not available from the compiled library.
-
-If we set the level to `V1` and reload, we get something like this in the
-JavaScript console:
-
-```js
-HEAD http://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mp 404 (Not Found)  http_plugin.js:94
-
-Unable to find byte-order-mark, making an educated guess.  string_utils.js:130
-
-HTTP error text:  http_plugin.js:69
-
-HEAD http://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mp 404 (Not Found)  http_plugin.js:94
-
-Unable to find byte-order-mark, making an educated guess.  string_utils.js:130
-
-HTTP error text:  http_plugin.js:69
-
-HEAD request to guess manifest type failed! shaka.util.Error  manifest_parser.js:179
-
-load() failed: shaka.util.Error  player.js:498
-
-Error code 1001 object shaka.util.Error  myapp.js:48
-```
-
-So much more information!  We can now see that the failed HEAD request caused
-`load()` to fail.
-
-
-#### Advanced: Loading the uncompiled library
-
-To do rapid testing and development, you can also load the uncompiled library.
-This allows you to edit files and just hit the "reload" button in the browser
-to see changes immediately.  This approach is trickier than using the debug
-library, because the entire source tree needs to be available to your web
-server, and because the individual sources can't be moved relative to the files
-in `dist/`.
-
-Instead of the single-file compiled library, we need to load three scripts in
-our HTML file:
-
-1. Closure's base library.  (This is a small JavaScript library related to the
-   Closure compiler used when we build Shaka.)  This is what loads Shaka without
-   requiring you to list all 50+ source files.
-2. A dependency file which maps Shaka's class names to source files.  This is
-   how Closure's base library can locate all of Shaka's individual source files.
-3. The uncompiled Shaka library's bootstrap file, "shaka-player.uncompiled.js".
-   This uses Closure to load the top-level parts of the library.  Each of those
-   files in turn load their internal dependencies.
-
-Once we're using the uncompiled library, we will be able to reload quickly
-without rebuilding.
-
-```html
-  <head>
-    <!-- Closure base: -->
-    <script src="node_modules/google-closure-library/closure/goog/base.js"></script>
-    <!-- Deps file: -->
-    <script src="dist/deps.js"></script>
-    <!-- Shaka Player uncompiled library: -->
-    <script src="shaka-player.uncompiled.js"></script>
-
-    <!-- Your application source: -->
-    <script src="myapp.js"></script>
-  </head>
-```
-
-
-#### Wrap up
-
-To sum up, remember these points when debugging your application:
-
- - Use the debug version of Shaka Player for debugging and integration work
- - Refer to the docs for error codes
- - Increase the log level when you need more detail

package/docs/tutorials/drm-config.md

@@ -1,274 +0,0 @@
-# DRM Configuration
-
-#### NOTE: EME and http URLs
-
-EME requires a secure URL to use.  This means you have to use `https` or be on
-`localhost`.  Currently only Chrome enforces it, but other browsers will in the
-future.  Also, because of mixed content requirements, if your site is using
-`https`, then your manifest and every segment will also need to use `https` too.
-
-See: Chrome's [announcement][], Firefox's [intent to remove][firefox_bug], and
-how to [disable for testing][allow_http].
-
-[allow_http]: https://www.chromium.org/Home/chromium-security/deprecating-powerful-features-on-insecure-origins
-[announcement]: https://groups.google.com/a/chromium.org/forum/#!msg/blink-dev/tXmKPlXsnCQ/ptOETCUvBwAJ
-[firefox_bug]: https://bugzilla.mozilla.org/show_bug.cgi?id=1322517
-
-
-#### License Servers
-
-Without DRM configuration, Shaka only plays clear content.  To play protected
-content, the application only needs to tell Shaka one basic thing: the URL(s)
-of its license server(s).
-
-We've made this simple through `player.configure()`.  The field `drm.servers` is
-an object mapping key system IDs to server URLs.  For example, to set license
-servers for both Widevine and Playready:
-
-```js
-player.configure({
-  drm: {
-    servers: {
-      'com.widevine.alpha': 'https://foo.bar/drm/widevine',
-      'com.microsoft.playready': 'https://foo.bar/drm/playready'
-    }
-  }
-});
-```
-
-Assuming your manifest uses the standard UUIDs for those key systems, that's
-all you need to do.
-
-
-#### Choosing a Key System
-
-Shaka Player is key-system-agnostic, meaning we don't prefer any key systems
-over any others.  We use EME to ask the browser what it supports, and make no
-assumptions.  If your browser supports multiple key systems, the first supported
-key system in the manifest is used.
-
-The interoperable encryption standard that DRM vendors are implementing is
-called Common Encryption (CENC).  Some DASH manifests don't specify any
-particular key system at all, but instead state that any CENC system will do:
-
-```xml
-<ContentProtection schemeIdUri="urn:mpeg:dash:mp4protection:2011" value="cenc"/>
-```
-
-If this is the only `<ContentProtection>` element in the manifest, Shaka will
-try all key systems it knows. (Based on keySystemsByURI in
-{@linksource shaka.extern.DashManifestConfiguration}.)
-
-Through `player.configure()`, you can update the dash key systems mapping by
-scheme URI:
-
-```js
-player.configure({
-  manifest: {
-    dash: {
-      keySystemsByURI: {
-        'urn:uuid:9a04f079-9840-4286-ab92-e65be0885f95': 'com.microsoft.playready.recommendation',
-        'urn:uuid:79f0049a-4098-8642-ab92-e65be0885f95': 'com.microsoft.playready.recommendation',
-      }
-  }
-  }
-});
-```
-
-If the browser supports it and you configured a license server URL for it, we'll
-use it.
-
-Alternative there are a config for make a mapping of keysystem if you know that
-is broadly supported. For example, `com.microsoft.playready.recommendation`:
-
-```js
-player.configure({
-  drm: {
-    keySystemsMapping: {
-      'com.microsoft.playready': 'com.microsoft.playready.recommendation',
-    }
-  }
-});
-```
-
-With the previous configuration you will choose the `recommendation` keySystem
-when your manifest (HLS or DASH) uses PlayReady.
-
-
-#### Clear Key
-
-The EME spec requires browsers to support a common key system called "Clear
-Key".  *(At the time of this writing (April 2016), only Chrome and Firefox
-have implemented "Clear Key".)*
-Clear Key uses unencrypted keys to decrypt CENC content, and can be useful
-for diagnosing problems and testing integrations.  To configure Clear Key,
-use the configuration field `drm.clearKeys` and provide a map of key IDs to
-content keys (both in hex):
-
-```js
-player.configure({
-  drm: {
-    clearKeys: {
-      // 'key-id-in-hex': 'key-in-hex',
-      'deadbeefdeadbeefdeadbeefdeadbeef': '18675309186753091867530918675309',
-      '02030507011013017019023029031037': '03050701302303204201080425098033'
-    }
-  }
-});
-```
-
-This will force the use of Clear Key for decryption, regardless of what is in
-your manifest.  Use this when you need to confirm that your keys are correct.
-
-
-#### Clear Key Licenses
-
-If your manifest actually specifies Clear Key, you can also use the normal
-license request mechanism to retrieve keys based on key IDs.  The EME spec
-defines a JSON-based [license request format] and [license format] for the
-Clear Key CDM.  If you have a server that understands these, just configure
-a license server as normal:
-
-```js
-player.configure({
-  drm: {
-    servers: {
-      'org.w3.clearkey': 'http://foo.bar/drm/clearkey'
-    }
-  }
-});
-```
-
-[license request format]: https://w3c.github.io/encrypted-media/#clear-key-request-format
-[license format]: https://w3c.github.io/encrypted-media/#clear-key-license-format
-
-
-#### Advanced DRM Configuration
-
-We have several {@link shaka.extern.AdvancedDrmConfiguration advanced options}
-available to give you access to the full EME configuration.  The config field
-`drm.advanced` is an object mapping key system IDs to their advanced settings.
-For example, to require hardware security in Widevine:
-
-```js
-player.configure({
-  drm: {
-    servers: {
-      'com.widevine.alpha': 'https://foo.bar/drm/widevine'
-    },
-    advanced: {
-      'com.widevine.alpha': {
-        'videoRobustness': 'HW_SECURE_ALL',
-        'audioRobustness': 'HW_SECURE_ALL'
-      }
-    }
-  }
-});
-```
-
-If you don't need them, you can leave these at their default settings.
-
-
-#### Robustness
-
-Robustness refers to how securely the content is handled by the key system. This
-is a key-system-specific string that specifies the requirements for successful
-playback.  Passing in a higher security level than can be supported will cause
-`player.load()` to fail with `REQUESTED_KEY_SYSTEM_CONFIG_UNAVAILABLE`.  The
-default is the empty string, which is the lowest security level supported by the
-key system.
-
-Each key system has their own values for robustness.
-
-##### Widevine
-
-Chromium sources: https://cs.chromium.org/chromium/src/components/cdm/renderer/widevine_key_system_properties.h?q=SW_SECURE_CRYPTO&l=22
-
-- `SW_SECURE_CRYPTO`
-- `SW_SECURE_DECODE`
-- `HW_SECURE_CRYPTO`
-- `HW_SECURE_DECODE`
-- `HW_SECURE_ALL`
-
-##### PlayReady
-
-Microsoft Documentation: https://docs.microsoft.com/en-us/playready/overview/security-level
-
-- `3000`
-- `2000`
-- `150`
-
-`com.microsoft.playready` key system ignores given robustness and stays at a
-`2000` decryption level.
-
-NB: Audio Hardware DRM is not supported (PlayReady limitation)
-
-##### FairPlay
-
-Based on [Apple's Documentation](https://developer.apple.com/streaming/fps/),
-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/errors.md

@@ -1,95 +0,0 @@
-# Error Handling
-
-The basics for handling native Error and {@link shaka.util.Error} thrown by Shaka.
-
-## Listening To and Handling Errors
-
-```javascript
-const handleError = (error) => {
-  if (error instanceof Error) {
-    // shaka crashed with an unhandled native error
-  }
-
-  if (error.severity === shaka.util.Error.Severity.CRITICAL) {
-    // handle fatal error, playback can not continue
-  } else {
-    // handle non-fatal error, playback can continue
-  }
-};
-
-const player = new shaka.Player();
-await player.attach(video);
-
-// handle errors that occur after load
-player.addEventListener('error', handleError);
-
-// there are two options for catching errors that occur during load
-
-// it's possible to listen directly on the promise
-player.load(url).catch(handleError);
-
-// or to use async/await with a try/catch
-try {
-  await player.load(url);
-} catch (e) {
-  handleError(e);
-}
-```
-
-## Custom Handling of Streaming Errors
-
-The `streaming.failureCallback` property of {@link shaka.extern.PlayerConfiguration} can be used to add custom handling or error conversion of errors that occur during streaming.
-
-```javascript
-player.configure('streaming.failureCallback', (error) => {
-  if (error.severity === shaka.util.Error.Severity.CRITICAL) {
-    // custom handling of critical error
-    // e.g. player.retryStreaming();
-  } else {
-    // custom handling of recoverable error
-  }
-});
-```
-
-## Custom Handling of Retries
-
-When configuring retry parameters in Shaka there may be known error codes that should not be retried, or the need to break out of an infinite retry loop in a live context. Retries for failed network requests are not reported as `RECOVERABLE` errors.
-
-For example, if a VOD manifest is missing, unlike when a LIVE manifest is missing, it can be expected to not show up and there is no need to retry.
-
-This is how to convert a retry into a critical error, see {@link shaka.net.NetworkingEngine.RetryEvent} and {@link shaka.util.Error} to decipher how the event can be parsed:
-
-```javascript
-const nwEngine = player.getNetworkingEngine();
-
-const vodManifestNotFoundHandler = (event /* shaka.net.NetworkingEngine.RetryEvent */) => {
-  const code = event.error.code;
-  const data = event.error.data;
-
-  if (code === shaka.util.Error.Code.BAD_HTTP_STATUS) {
-    if (
-      // each type of error has its own data structure (or none at all), tread with care
-      Array.isArray(data) &&
-      data[1] === 404 &&
-      data[4] === shaka.net.NetworkingEngine.RequestType.MANIFEST
-    ) {
-      // Throwing inside a retry callback will immediately stop retries
-      throw error;
-
-      // A proprietary error code can also be thrown
-      // throw new shaka.util.Error(
-      //   shaka.util.Error.Severity.CRITICAL,
-      //   shaka.util.Error.Category.NETWORK,
-      //   'RECOGNIZABLE_ERROR_MESSAGE'
-      // );
-    }
-  }
-};
-
-nwEngine.addEventListener('retry', vodManifestNotFoundHandler);
-
-player.addEventListener('load'() => {
-  nwEngine.removeEventListener('retry', vodManifestNotFoundHandler);
-});
-
-```