shaka-player 4.6.3 → 4.7.0

package/docs/tutorials/plugins.md

@@ -1,184 +0,0 @@
-# Plugins and Customizing the Build
-
-Shaka has a plugin system to make it easier to extend and customize the
-library. The plugin interfaces are here to allow you extend or customize Shaka
-Player in one of these areas: manifest parsing, subtitle and caption parsing,
-networking, ABR, and polyfills.  Each of these parts of the system has its own
-plugin interface. Even our "built-in" parsers, such as DASH and WebVTT, are
-actually just plugins we build by default.
-
-Plugins can be written outside the library (in your application), or
-they can be built into the library to take advantage of the [Closure compiler].
-
-[Closure compiler]: https://github.com/google/closure-compiler
-
-
-#### Plugins
-
-We will only cover plugin concepts at a high level here and will not go into
-detailed examples of plugin development.  If you are interested in customizing
-or extending Shaka in one of these areas, please see the links below.
-
-A plugin registers itself with a "core" component.  These are the various
-plugin interfaces and the default plugins that Shaka provides:
-
-__Manifest parsers__
-  - Selected by file extension, with a fall back to manifest MIME type
-  - Register with {@link shaka.media.ManifestParser.registerParserByExtension}
-    and {@link shaka.media.ManifestParser.registerParserByMime}
-  - Default manifest parser plugins:
-    - DASH: {@linksource shaka.dash.DashParser}
-    - HLS: {@linksource shaka.hls.HlsParser}
-    - MSS: {@linksource shaka.mss.MssParser}
-
-__Subtitle/caption parsers__
-  - Selected by MIME type
-  - Register with {@link shaka.text.TextEngine.registerParser}
-  - Default text parser plugins:
-    - WebVTT: {@linksource shaka.text.VttTextParser} and
-      {@linksource shaka.text.Mp4VttParser}
-    - TTML: {@linksource shaka.text.TtmlTextParser} and
-      {@linksource shaka.text.Mp4TtmlParser}
-    - SubRip (SRT): {@linksource shaka.text.SrtTextParser}
-    - LyRiCs (LRC): {@linksource shaka.text.LrcTextParser}
-    - SubStation Alpha (SSA, ASS): {@linksource shaka.text.SsaTextParser}
-    - SubViewer (SBV): {@linksource shaka.text.SbvTextParser}
-
-__Subtitle/caption displayers__
-  - Configured at runtime on a Player instance
-  - Use {@link player.configure} and set the `textDisplayFactory` field
-  - Must implement the {@link shaka.extern.TextDisplayer} interface
-  - Default TextDisplayer implementation:
-    {@linksource shaka.text.SimpleTextDisplayer}
-
-__Networking plugins__
-  - Selected by URI scheme (http, https, etc.)
-  - Register with {@link shaka.net.NetworkingEngine.registerScheme}
-  - Returns an {@link shaka.util.AbortableOperation} object, to allow aborting
-  - Default networking plugins:
-    - HTTP(S) XHR: {@linksource shaka.net.HttpXHRPlugin}
-    - HTTP(S) Fetch: {@linksource shaka.net.HttpFetchPlugin}
-    - data URIs: {@linksource shaka.net.DataUriPlugin}
-
-__ABR plugins__
-  - Configured at runtime on a Player instance
-  - Use {@link player.configure} and set the `abrFactory` field
-  - Must implement the {@link shaka.extern.AbrManager} interface
-  - Default AbrManager implementation: {@linksource shaka.abr.SimpleAbrManager}
-
-__Polyfills__
-  - All polyfills are installed by {@link shaka.polyfill.installAll}
-  - Register with {@link shaka.polyfill.register}
-  - Default polyfills:
-    - prefixed fullscreen implementations:
-      {@linksource shaka.polyfill.Fullscreen}
-    - prefixed video QoE metrics:
-      {@linksource shaka.polyfill.VideoPlaybackQuality}
-    - prefixed EME implementations:
-      - {@linksource shaka.polyfill.PatchedMediaKeysWebkit}
-      - {@linksource shaka.polyfill.PatchedMediaKeysNop}
-    - variants of VTTCue and TextTrackCue constructors:
-      {@linksource shaka.polyfill.VTTCue}
-
-
-#### Excluding Default Plugins
-
-Core components cannot be removed from the build, but everything else is
-technically optional.  For example, if you don't need WebVTT, you can exclude
-our VTT parser from the build to save space.  Any VTT text streams found in a
-manifest would then be ignored.
-
-*(At the time of this writing, our default plugins account for 54% of the size
-of our compiled library.)*
-
-Because each plugin's source file ends with a call to register itself with the
-core system, a plugin can simply be excluded from the build without changing
-any of the source code.
-
-You can start with the complete library (`+@complete`) and exclude any
-individual source file with a minus sign and a path:
-
-```sh
-python build/build.py +@complete -lib/text/mp4_ttml_parser.js
-```
-
-You can also exclude an entire category of plugins:
-
-```sh
-# Build without polyfills:
-python build/build.py +@complete -@polyfill
-# Build without polyfills or text parsers:
-python build/build.py +@complete -@polyfill -@text
-```
-
-To see the complete list of categories, its in [`build/types/`](https://github.com/shaka-project/shaka-player/tree/main/build/types)
-
-#### Build Configs
-
-Each of these arguments that starts with an '@' sign is a build config file in
-`build/types/` containing a list sources or other configs to include.  Each
-line in these files is treated as an argument to `build.py`.  For example,
-this is what `build/types/networking` looks like:
-
-```sh
-# All standard networking scheme plugins.
-+../../lib/net/http_xhr_plugin.js
-+../../lib/net/http_fetch_plugin.js
-+../../lib/net/http_plugin_utils.js
-+../../lib/net/data_uri_plugin.js
-```
-
-
-#### Adding Your Own Plugins
-
-If you want to take advantage of the [Closure compiler], you can add your own
-sources to the build.  Your plugins, like ours, should register themselves at
-the bottom of the source file.
-
-To add a single source file, prefix it with a plus sign:
-
-```sh
-python build/build.py +@complete +my_plugin.js
-```
-
-You can add multiple sources as well:
-
-```sh
-python build/build.py +@complete +my_plugin.js +/path/to/my_other_plugin.js
-```
-
-
-#### Custom Build Configs
-
-If you have a long list of customizations, you may want to create your own
-group file.  For example:
-
-```sh
-# Start with a complete library
-+@complete
-# Drop subtitle support
--@text
-# Remove default networking plugins
--@networking
-# Add my custom HTTP implementation
-+/path/to/my_http_plugin.js
-# Add an additional polyfill for some odd platform I'm targeting
-+/path/to/my_platform_polyfill.js
-```
-
-
-#### Plugins in Your Application
-
-Every plugin interface is exported from the compiled library so that you don't
-have to customize the build to create a plugin.  Just register your plugins
-with the appropriate interfaces after the library is loaded.
-
-
-#### Giving Back
-
-If you have a great plugin that you'd like to contribute back to the community,
-we'd love to hear from you.  You can get in touch via our [issue tracker][] to
-discuss it, and once it's ready, you can send a [pull request][] on github.
-
-[issue tracker]: https://github.com/shaka-project/shaka-player/issues/new/choose
-[pull request]: https://github.com/shaka-project/shaka-player/pull/new/main

package/docs/tutorials/selenium-grid-config.md

@@ -1,174 +0,0 @@
-# Selenium Grid Config
-
-Shaka Player's test runner (Karma) can be directed to run tests on a Selenium
-grid.  For this, you need a config file that defines what browsers are
-available, and how to request them via WebDriver.
-
-For a fully-worked, detailed example, see the config for the private grid in
-our lab at [build/shaka-lab.yaml](https://github.com/shaka-project/shaka-player/blob/main/build/shaka-lab.yaml)
-
-## Usage
-
-```sh
-python build/test.py \
-    --grid-config grid-config.yaml \
-    --grid-address selenium-hub-hostname:4444
-```
-
-## Syntax
-
-The config file is written in YAML.  We chose YAML because it has two big
-advantages over JSON:
-
-1. You can add comments
-2. You can define variables (with YAML "anchors") to factor out common configs
-
-### Variables
-
-You can define any common variables in the `vars` section, then refer to them
-elsewhere.  For example:
-
-```yaml
-vars:
-  # Generates an "anchor" with the given name.  Later, you can inject the
-  # contents of the variable with "*name".
-  firefox_config: &firefox_config
-    moz:firefoxOptions:
-      # Override Firefox default preferences in the temporary profile created
-      # for each test run.
-      prefs:
-        # Overrides Selenium's explicit default setting, to allow Firefox to
-        # install the Widevine CDM on demand.
-        media.gmp-manager.updateEnabled: true
-        # Overrides Firefox's Linux-specific default setting to disable DRM.
-        media.eme.enabled: true
-
-# These three browser definitions share the same config from above.
-FirefoxMac:
-  browser: firefox
-  os: Mac
-  extra_configs:
-    - *firefox_config
-
-FirefoxWindows:
-  browser: firefox
-  os: Windows
-  extra_configs:
-    - *firefox_config
-
-FirefoxLinux:
-  browser: firefox
-  os: Linux
-  extra_configs:
-    - *firefox_config
-```
-
-### Browsers
-
-Each top-level key in the config file (except for `vars`) is the name of a
-browser made available to Karma.  Within each of those keys are the following:
-
- - `browser`: The name of the browser.  This is case-sensitive, and must match
-       the string and case used by Selenium.
- - `os` (optional): The name of the OS.  This is case-INsensitive, and must
-       match the name of the platform as used by Selenium.  For Generic
-       WebDriver Server, this can be omitted or set to the name of the host
-       platform.
- - `version` (optional): The version of the browser.  This is case-sensitive,
-       and must match the string and case used in the Selenium node config.
- - `disabled` (optional): If true, this browser is disabled and will not be
-       used unless explicitly requested.
- - `extra_configs` (optional): An array of dictionaries of extra configs which
-       will be merged with the WebDriver launcher config in Karma.
-
-Examples of basic desktop browsers definitions:
-
-```yaml
-ChromeMac:
-  browser: chrome
-  os: Mac
-
-FirefoxMac:
-  browser: firefox
-  os: Mac
-
-Safari:
-  browser: safari
-  os: Mac
-
-SafariTP:
-  browser: safari
-  os: Mac
-  extra_configs:
-    - safari.options:
-        technologyPreview: true
-
-ChromeWindows:
-  browser: chrome
-  os: Windows
-
-FirefoxWindows:
-  browser: firefox
-  os: Windows
-
-Edge:
-  browser: msedge
-  os: Windows
-
-ChromeLinux:
-  browser: chrome
-  os: Linux
-
-FirefoxLinux:
-  browser: firefox
-  os: Linux
-```
-
-### Composing configs
-
-You can define variables for browser configs that can be composed together in
-`extra_configs`.  For example, below you will see some basic definitions for
-Chrome arguments and parameters, and then an additional config with an argument
-that is only needed for some platforms.  `karma.conf.js` will merge those
-argument lists intelligently when it loads the YAML config.
-
-```yaml
-vars:
-  basic_chrome_config: &basic_chrome_config
-    goog:chromeOptions:
-      args:
-        # Normally, Chrome disallows autoplaying videos in many cases.  Enable
-        # it for testing.
-        - "--autoplay-policy=no-user-gesture-required"
-
-      # Instruct chromedriver not to disable component updater.
-      excludeSwitches:
-        - "disable-component-update"
-
-  headless_chrome_config: &headless_chrome_config
-    goog:chromeOptions:
-      args:
-        # Run in headless mode.
-        - "--headless"
-
-ChromeLinux:
-  browser: chrome
-  os: Mac
-  extra_configs:
-    - *basic_chrome_config
-
-ChromeWindows:
-  browser: chrome
-  os: Mac
-  extra_configs:
-    - *basic_chrome_config
-
-ChromeMac:
-  browser: chrome
-  os: Mac
-  # Take the parameters and arguments for basic_chrome_config, then append the
-  # arguments for headless_chrome_config.
-  extra_configs:
-    - *basic_chrome_config
-    - *headless_chrome_config
-```

package/docs/tutorials/service-worker.md

@@ -1,106 +0,0 @@
-# Service Worker Caching
-
-[Service workers][1] provide a way to have a script run in the background even
-when the page is not loaded.  It can respond to push events from other sites and
-can act as a transparent cache for the page.
-
-We strongly recommend against using service workers to cache content for offline
-playback.  There are many subtle issues introduced when you try to cache content
-manifests and segments, and we have built an offline storage system that manages
-all of these issues for you.  See {@tutorial offline} and
-{@link shaka.offline.Storage} for more information.
-
-For other use cases, this doc will show a basic example of how to create a cache
-that will not interfere with Shaka Player's bandwidth estimation. This is NOT a
-tutorial of service workers in general.
-
-[1]: https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API
-
-
-## Cache Header
-
-Shaka looks for a special header `X-Shaka-From-Cache` to indicate that a
-response was from a cache.  This tells us to ignore the response for bandwidth
-estimation purposes.  If we used these cached responses to estimate bandwidth,
-our estimate would too high, and we would make the wrong adaptation decisions.
-Simply adding this header to the response object will ensure that cached
-segments will not interfere with bandwidth estimates.
-
-
-## Example Caching Service Worker
-
-Registering code in the app:
-
-```js
-if ('serviceWorker' in navigator) {
-  try {
-    await navigator.serviceWorker.register('/service_worker.js');
-    console.log('Service worker registered successfully');
-  } catch(e) {
-    console.error('Error registering service worker', e);
-  }
-} else {
-  console.error('Browser doesn\'t support service workers');
-}
-```
-
-Service worker code (`/service_worker.js`):
-
-```js
-const CACHE_NAME = 'segment-cache-v1';
-
-function shouldCache(url) {
-  return url.endsWith('.mp4') || url.endsWith('.m4s');
-}
-
-function loadFromCacheOrFetch(request) {
-  return caches.open(CACHE_NAME).then(function(cache) {
-    return cache.match(request).then(function(response) {
-      if (response) {
-        // The custom header was added before putting it in the cache.
-        console.log('Handling cached request', request.url);
-        return response;
-      }
-
-      // Request not cached, make a real request for the file.
-      return fetch(request).then(function(response) {
-        // Cache any successfully request for an MP4 segment.  Service
-        // workers cannot cache 206 (Partial Content).  This means that
-        // content that uses range requests (e.g. SegmentBase) will require
-        // more work.
-        if (response.ok && response.status != 206 && shouldCache(request.url)) {
-          console.log('Caching MP4 segment', request.url);
-          cacheResponse(cache, request, response);
-        }
-
-        return response;
-      });
-    });
-  })
-}
-
-function cacheResponse(cache, request, response) {
-  // Response objects are read-only, so to add our custom header, we need to
-  // recreate the object.
-  const init = {
-    status: response.status,
-    statusText: response.statusText,
-    headers: {'X-Shaka-From-Cache': true}
-  };
-
-  response.headers.forEach(function(value, key) {
-    init.headers[key] = value;
-  });
-
-  // Response objects are single use.  This means we need to call clone() so
-  // we can both store the ArrayBuffer and give the response to the page.
-  return response.clone().arrayBuffer().then(function(ab) {
-    cache.put(request, new Response(ab, init));
-  });
-}
-
-
-self.addEventListener('fetch', function(event) {
-  event.respondWith(loadFromCacheOrFetch(event.request));
-});
-```