shaka-player 3.3.2 → 4.0.0

package/docs/design/REDESIGN.md

@@ -28,11 +28,11 @@ often requiring [multiple][] [fixes][] to get certain dependencies removed.
 This means users all end up using the same monolithic player library.
 Features in Shaka 2 should be modular and easy to exclude from the build.
 
-[difficult]: https://github.com/google/shaka-player/commit/671611ef3722169b9f6b51ab44bdd6b4098d959e
-[to exclude]: https://github.com/google/shaka-player/commit/603fae969550c69ea38a61249da905857c67b9f1
-[from the build]: https://github.com/google/shaka-player/commit/f248647685b92ba928bbfd06d45d2b99023d60c2
-[multiple]: https://github.com/google/shaka-player/commit/39be45d3d55cdcef20a6a529a87246b0ea11cb33
-[fixes]: https://github.com/google/shaka-player/commit/6fe239150a8939728876e93e1a4269032530d9f1
+[difficult]: https://github.com/shaka-project/shaka-player/commit/671611ef3722169b9f6b51ab44bdd6b4098d959e
+[to exclude]: https://github.com/shaka-project/shaka-player/commit/603fae969550c69ea38a61249da905857c67b9f1
+[from the build]: https://github.com/shaka-project/shaka-player/commit/f248647685b92ba928bbfd06d45d2b99023d60c2
+[multiple]: https://github.com/shaka-project/shaka-player/commit/39be45d3d55cdcef20a6a529a87246b0ea11cb33
+[fixes]: https://github.com/shaka-project/shaka-player/commit/6fe239150a8939728876e93e1a4269032530d9f1
 
 Some operations, in particular [starting playback and filling the buffer][],
 take longer than they need to.  Startup and buffering in Shaka 2 should be as
@@ -46,54 +46,54 @@ us from updating MediaSource duration][] and makes it [difficult to set initial
 playback time][] on browsers other than Chrome.  Shaka 2 should have a simpler
 streaming core that works better across browsers.
 
-[StreamVideoSource]: https://github.com/google/shaka-player/blob/v1.5.x/lib/player/stream_video_source.js
-[Stream]: https://github.com/google/shaka-player/blob/v1.5.x/lib/media/stream.js
-[SourceBufferManager]: https://github.com/google/shaka-player/blob/v1.5.x/lib/media/source_buffer_manager.js
-[prevents us from updating MediaSource duration]: https://github.com/google/shaka-player/blob/v1.5.1/lib/player/stream_video_source.js#L1807
-[difficult to set initial playback time]: https://github.com/google/shaka-player/issues/101
+[StreamVideoSource]: https://github.com/shaka-project/shaka-player/blob/v1.5.x/lib/player/stream_video_source.js
+[Stream]: https://github.com/shaka-project/shaka-player/blob/v1.5.x/lib/media/stream.js
+[SourceBufferManager]: https://github.com/shaka-project/shaka-player/blob/v1.5.x/lib/media/source_buffer_manager.js
+[prevents us from updating MediaSource duration]: https://github.com/shaka-project/shaka-player/blob/v1.5.1/lib/player/stream_video_source.js#L1807
+[difficult to set initial playback time]: https://github.com/shaka-project/shaka-player/issues/101
 
 [Buffering state][] in Shaka 1 involves coordination between several layers
 (from [Player][] to [Stream][]) and has been [tough][] [to][] [get][]
 [right][].  Buffering state in Shaka 2 should be simple and consistent.
 
-[Buffering state]: https://github.com/google/shaka-player/blob/v1.5.1/lib/player/player.js#L994
-[Player]: https://github.com/google/shaka-player/blob/v1.5.x/lib/player/player.js
-[Stream]: https://github.com/google/shaka-player/blob/v1.5.x/lib/media/stream.js
-[tough]: https://github.com/google/shaka-player/issues/44
-[to]: https://github.com/google/shaka-player/issues/63
-[get]: https://github.com/google/shaka-player/issues/127
-[right]: https://github.com/google/shaka-player/issues/221#issuecomment-152781243
+[Buffering state]: https://github.com/shaka-project/shaka-player/blob/v1.5.1/lib/player/player.js#L994
+[Player]: https://github.com/shaka-project/shaka-player/blob/v1.5.x/lib/player/player.js
+[Stream]: https://github.com/shaka-project/shaka-player/blob/v1.5.x/lib/media/stream.js
+[tough]: https://github.com/shaka-project/shaka-player/issues/44
+[to]: https://github.com/shaka-project/shaka-player/issues/63
+[get]: https://github.com/shaka-project/shaka-player/issues/127
+[right]: https://github.com/shaka-project/shaka-player/issues/221#issuecomment-152781243
 
 Shaka 1 relies on the browser to implement support for text types, and is
 therefore limited to non-segmented WebVTT.  Shaka 2 should also support
 [segmented text types][] and [types not natively supported by the browser][].
 
-[segmented text types]: https://github.com/google/shaka-player/issues/150
-[types not natively supported by the browser]: https://github.com/google/shaka-player/issues/111
+[segmented text types]: https://github.com/shaka-project/shaka-player/issues/150
+[types not natively supported by the browser]: https://github.com/shaka-project/shaka-player/issues/111
 
 Bandwidth estimation in Shaka 1 relies on the assumption that segments are not
 cached locally.  Use of [cache-busting techniques][] to enforce this makes
 Shaka very [cache][]-[unfriendly][].  Shaka 2 should be cache-friendly.
 
-[cache-busting techniques]: https://github.com/google/shaka-player/blob/v1.5.1/lib/util/ajax_request.js#L241
-[cache]: https://github.com/google/shaka-player/issues/76
-[unfriendly]: https://github.com/google/shaka-player/issues/191
+[cache-busting techniques]: https://github.com/shaka-project/shaka-player/blob/v1.5.1/lib/util/ajax_request.js#L241
+[cache]: https://github.com/shaka-project/shaka-player/issues/76
+[unfriendly]: https://github.com/shaka-project/shaka-player/issues/191
 
 Shaka 1 [uses HTTP headers to synchronize the user's clock][] with the server.
 This is [error-prone for some CDNs][] and also raises [CORS issues][], so Shaka
 2 should avoid using HTTP headers.
 
-[uses HTTP headers to synchronize the user's clock]: https://github.com/google/shaka-player/blob/v1.5.1/lib/util/ajax_request.js#L448
-[error-prone for some CDNs]: https://github.com/google/shaka-player/issues/205
-[CORS issues]: https://github.com/google/shaka-player/issues/159
+[uses HTTP headers to synchronize the user's clock]: https://github.com/shaka-project/shaka-player/blob/v1.5.1/lib/util/ajax_request.js#L448
+[error-prone for some CDNs]: https://github.com/shaka-project/shaka-player/issues/205
+[CORS issues]: https://github.com/shaka-project/shaka-player/issues/159
 
 [HttpVideoSource][] does not build on MSE and classes like [EmeManager][] have
 special cases to support it.  Since it was originally created for debugging
 purposes, Shaka 2 should drop HttpVideoSource and only support MSE-based
 playback.
 
-[HttpVideoSource]: https://github.com/google/shaka-player/blob/v1.5.x/lib/player/http_video_source.js
-[EmeManager]: https://github.com/google/shaka-player/blob/v1.5.x/lib/media/eme_manager.js
+[HttpVideoSource]: https://github.com/shaka-project/shaka-player/blob/v1.5.x/lib/player/http_video_source.js
+[EmeManager]: https://github.com/shaka-project/shaka-player/blob/v1.5.x/lib/media/eme_manager.js
 
 Integration tests using externally-hosted resources [can be flaky][],
 especially when run outside of Google's network.  Shaka 2 should avoid tests
@@ -106,34 +106,34 @@ and application developers sometimes [have to use error message strings][]
 hard-coded into the library.  Shaka 2 should have a consistent error format
 that is easy to read.
 
-[have to use error message strings]: https://github.com/google/shaka-player/issues/201
+[have to use error message strings]: https://github.com/shaka-project/shaka-player/issues/201
 
 Networking abstractions in Shaka 1 are built inside of AjaxRequest, which
 requires non-HTTP requests to [pretend to come from XmlHttpRequest][].  The
 networking abstraction in Shaka 2 should be simpler and should not treat
 XHR as the basis for all networking.
 
-[pretend to come from XmlHttpRequest]: https://github.com/google/shaka-player/blob/v1.5.1/lib/util/ajax_request.js#L305
+[pretend to come from XmlHttpRequest]: https://github.com/shaka-project/shaka-player/blob/v1.5.1/lib/util/ajax_request.js#L305
 
 A developer who wishes to use a custom network protocol or a custom manifest
 format in Shaka 1 will have to modify the library to do so.  Shaka 2 should
 [support external plugins for networking][] and manifest support.
 
-[support external plugins for networking]: https://github.com/google/shaka-player/issues/198
+[support external plugins for networking]: https://github.com/shaka-project/shaka-player/issues/198
 
 The functionality that can be injected into Shaka 1 ([IBandwidthEstimator][],
 [IAbrManager][]) is based on implementing class interfaces, which can be complex
 for those unfamiliar with the Closure compiler.  Plugins and extensions to Shaka
 2 should be as simple as possible.
 
-[IBandwidthEstimator]: https://github.com/google/shaka-player/blob/v1.5.1/lib/util/i_bandwidth_estimator.js
-[IAbrManager]: https://github.com/google/shaka-player/blob/v1.5.1/lib/media/i_abr_manager.js
+[IBandwidthEstimator]: https://github.com/shaka-project/shaka-player/blob/v1.5.1/lib/util/i_bandwidth_estimator.js
+[IAbrManager]: https://github.com/shaka-project/shaka-player/blob/v1.5.1/lib/media/i_abr_manager.js
 
 [Static members][] in Shaka 1 make it impossible in some cases to host multiple
 Player instances with different settings.  Player instances should be completely
 independent in Shaka 1.
 
-[Static members]: https://github.com/google/shaka-player/issues/126
+[Static members]: https://github.com/shaka-project/shaka-player/issues/126
 
 
 ## Shaka v2 Design Principles

package/docs/design/bg-fetch.md

@@ -12,7 +12,7 @@ At the time it was added to the backlog, the feature was not quite ready for
 use. Since then, it has matured, and now is something we could feasibly use, but
 it has still been a low-priority feature.
 
-[since 2017]: https://github.com/google/shaka-player/issues/879
+[since 2017]: https://github.com/shaka-project/shaka-player/issues/879
 
 ## Design Concept
 
@@ -131,4 +131,4 @@ unrelated service worker for our own.
    1. This message can also be used to make sure the versions are the same.
 
 [the documentation]: https://developers.google.com/web/updates/2018/12/background-fetch#starting_a_background_fetch
-[a given scope]: https://developers.google.com/web/fundamentals/primers/service-workers#register_a_service_worker
+[a given scope]: https://developers.google.com/web/fundamentals/primers/service-workers#register_a_service_worker

package/docs/design/codec_preferences.md

@@ -97,7 +97,7 @@ A platform may support multiple DRM key systems, (for example, Widevine and
 PlayReady). The `drm.preferredKeySystems` configuration allows the application
 to specify which key systems it wants to choose.
 
-[Github issue](https://github.com/google/shaka-player/issues/3002)
+[Github issue](https://github.com/shaka-project/shaka-player/issues/3002)
 
 Previously, Shaka Player chose a DRM key system based on:
 1. Only use the key systems supported by the platform.

package/docs/design/dash-audio-channels.md

@@ -4,7 +4,7 @@ Shaka Player parses channel count information from HLS manifests, but not yet
 from DASH manifests.  We have had an [open request][dash_channels_request] to
 do this for a year.
 
-[dash_channels_request]: https://github.com/google/shaka-player/issues/424
+[dash_channels_request]: https://github.com/shaka-project/shaka-player/issues/424
 
 
 ## The DASH Spec
@@ -79,7 +79,7 @@ Neither 23003-3 nor the DASH spec corrigenda were freely available at the time
 of this writing, so we have not confirmed these assumptions.
 
 [cast_labs_23003]: https://github.com/castlabs/dashencrypt/blob/1d604896/dash.fragmencrypter/src/main/java/com/castlabs/dash/helpers/DashHelper.java#L193
-[shaka_packager_23003]: https://github.com/google/shaka-packager/blob/4ba5bec6/packager/mpd/base/xml/xml_node.cc#L378
+[shaka_packager_23003]: https://github.com/shaka-project/shaka-packager/blob/4ba5bec6/packager/mpd/base/xml/xml_node.cc#L378
 
 
 ### tag:dolby.com,2014:dash:audio\_channel\_configuration:2011
@@ -101,7 +101,7 @@ Packager][shaka_packager_ec3_enum] supports this interpretation.  This has not
 been confirmed from primary sources.
 
 [dash_if_audio_config]: http://dashif.org/identifiers/audio-source-data/
-[shaka_packager_ec3_enum]: https://github.com/google/shaka-packager/blob/47363dd0/packager/media/codecs/ec3_audio_util.cc#L34
+[shaka_packager_ec3_enum]: https://github.com/shaka-project/shaka-packager/blob/47363dd0/packager/media/codecs/ec3_audio_util.cc#L34
 
 
 ### urn:dts:dash:audio\_channel\_configuration:2012

package/docs/design/dash-manifests.md

@@ -244,5 +244,5 @@ segments.  You can follow progress in [#999][].  But note that DASH requires
 accurate clock times, so even after that feature is added, your manifest may
 not play in other DASH players.
 
-[#999]: https://github.com/google/shaka-player/issues/999
+[#999]: https://github.com/shaka-project/shaka-player/issues/999
 

package/docs/design/gap-jumping.md

@@ -21,13 +21,13 @@ buffered ranges.
 
 There have been a number of bugs filed asking for this feature.
 
-#### [#180](https://github.com/google/shaka-player/issues/180)
+#### [#180](https://github.com/shaka-project/shaka-player/issues/180)
 One of the first bugs asking for gap jumping.  The author talks about how live
 streams can commonly lose source content (e.g. from network outages or weather).
 This can cause the packagers to introduce gaps in either the media segments or
 the manifest.
 
-#### [#555](https://github.com/google/shaka-player/issues/555)
+#### [#555](https://github.com/shaka-project/shaka-player/issues/555)
 This one is also asking about live streams and outages.  The author discusses
 several options for dealing with interruptions in the live streams.  The
 suggestions were:
@@ -41,7 +41,7 @@ can’t tell if a segment will never be available or is just not created yet.
 Also that dummy content is usually generated by the server; however, the author
 notes that this may not be feasible.
 
-#### [#661](https://github.com/google/shaka-player/issues/661)
+#### [#661](https://github.com/shaka-project/shaka-player/issues/661)
 This content with small gaps in the media that result in playback stalling.
 Chrome and Firefox will actually play through the gap, but we don’t allow it
 since it wouldn’t work on Safari.

package/docs/design/preload.md

@@ -15,7 +15,7 @@ This allows an application using Shaka Player to:
   the user is making a decision on which video to play.
 - Start to play the selected video almost immediately.
 
-[Github issue](https://github.com/google/shaka-player/issues/880)
+[Github issue](https://github.com/shaka-project/shaka-player/issues/880)
 
 
 ## Background & Context
@@ -296,4 +296,4 @@ When preloading, the MediaSourceEngine appends the data to the SourceBuffer.
    to the MediaSource.
 3. For a live stream video, StreamingEngine can keep fetching the latest piece
    of the content. The MediaSourceEngine stores the latest data, and abandons
-   the older data.
+   the older data.

package/docs/tutorials/config.md

@@ -73,10 +73,8 @@ player.getConfiguration();
        failureCallback: Function
        ignoreTextStreamFailures: false
        alwaysStreamText: false
-       jumpLargeGaps: false
        rebufferingGoal: 2
        retryParameters: Object
-       smallGapLimit: 0.5
        startAtSegmentBoundary: false
        safeSeekOffset: 5
      textDisplayFactory: Function

package/docs/tutorials/drm-config.md

@@ -184,6 +184,11 @@ Microsoft Documentation: https://docs.microsoft.com/en-us/playready/overview/sec
 
 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.

package/docs/tutorials/fairplay.md

@@ -1,40 +1,25 @@
 # FairPlay Support
 
-When using native `src=` playback, we support using FairPlay on Safari.
+We support FairPlay with EME on compatible environments or native `src=`.
 Adding FairPlay support involves a bit more work than other key systems.
 
-
 ## Server certificate
 
-All FairPlay content requires setting a server certificate.  This is set in the
-Player configuration:
+All FairPlay content requires setting a server certificate. You can either
+provide it directly or set a serverCertificateUri for Shaka to fetch it for
+you.
 
 ```js
 const req = await fetch('https://example.com/cert.der');
 const cert = await req.arrayBuffer();
 
-player.configure('drm.advanced.com\\.apple\\.fps\\.1_0.serverCertificate',
+player.configure('drm.advanced.com\\.apple\\.fps\\.serverCertificate',
                  new Uint8Array(cert));
 ```
 
-
-## Content ID
-
-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);
-});
+player.configure('drm.advanced.com\\.apple\\.fps\\.serverCertificateUri',
+                 'https://example.com/cert.der');
 ```
 
 ## License wrapping

package/docs/tutorials/faq.md

@@ -43,17 +43,6 @@ headers in the response.  Additionally, with some manifests, we will send a
 This can also happen with mixed-content restrictions.  If the site is using
 `https:`, then your manifest and segments must also.
 
-*Sending `Range` header at the start of HLS playback can be disabled using this config:*
-```
-player.configure({
-    manifest: {
-        hls: {
-            useFullSegmentsForStartTime: true,
-        },
-    },
-})
-```
-
 <hr>
 
 **Q:** I am getting `REQUESTED_KEY_SYSTEM_CONFIG_UNAVAILABLE` or error code
@@ -274,18 +263,18 @@ so don't declare it using a ref(), and if you put your player instance into a
 data() object, you can prefix the property name with "$" or "_" to make Vue not
 proxy them.
 
-[386]: https://github.com/google/shaka-player/issues/386#issuecomment-227898001
-[489]: https://github.com/google/shaka-player/issues/489#issuecomment-240466224
-[743]: https://github.com/google/shaka-player/issues/743
-[887]: https://github.com/google/shaka-player/issues/887
-[999]: https://github.com/google/shaka-player/issues/999
-[1667]: https://github.com/google/shaka-player/issues/1667
+[386]: https://github.com/shaka-project/shaka-player/issues/386#issuecomment-227898001
+[489]: https://github.com/shaka-project/shaka-player/issues/489#issuecomment-240466224
+[743]: https://github.com/shaka-project/shaka-player/issues/743
+[887]: https://github.com/shaka-project/shaka-player/issues/887
+[999]: https://github.com/shaka-project/shaka-player/issues/999
+[1667]: https://github.com/shaka-project/shaka-player/issues/1667
 [BigInteger.js]: https://github.com/peterolson/BigInteger.js
 [CORS]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
-[Shaka Player Embedded]: https://github.com/google/shaka-player-embedded
+[Shaka Player Embedded]: https://github.com/shaka-project/shaka-player-embedded
 [auth]: https://shaka-player-demo.appspot.com/docs/api/tutorial-license-server-auth.html
 [buffering]: https://shaka-player-demo.appspot.com/docs/api/tutorial-network-and-buffering-config.html
 [drm_tutorial]: https://shaka-player-demo.appspot.com/docs/api/tutorial-drm-config.html
 [eme_https]: https://sites.google.com/a/chromium.org/dev/Home/chromium-security/deprecating-powerful-features-on-insecure-origins
 [wrapping]: https://shaka-player-demo.appspot.com/docs/api/tutorial-license-wrapping.html
-[including mux.js]: https://github.com/google/shaka-player/blob/967f3399/demo/index.html#L39
+[including mux.js]: https://github.com/shaka-project/shaka-player/blob/967f3399/demo/index.html#L39

package/docs/tutorials/index.json

@@ -19,13 +19,8 @@
   { "fairplay": { "title": "FairPlay support" } },
   { "application-level-redirects": { "title": "Application-Level Redirects" } },
   { "blob-url": { "title": "Blob URL" } },
+  { "selenium-grid-config": { "title": "Selenium Grid Config" } },
   { "faq": { "title": "Frequently Asked Questions" } },
-  { "upgrade": {
-      "title": "Upgrade Guide",
-      "children": {
-        "upgrade-v2-5": { "title": "Upgrade Guide, v2.5 => v3" },
-        "upgrade-v3": { "title": "Upgrade Guide, v3" },
-        "upgrade-manifest": { "title": "Shaka Player Manifest Upgrade Guide" }
-      }
-  } }
+  { "upgrade": { "title": "Upgrade Guide" } },
+  { "upgrade-manifest": { "title": "ManifestParser Upgrade Guide" } }
 ]

package/docs/tutorials/plugins.md

@@ -69,9 +69,7 @@ __Polyfills__
       {@linksource shaka.polyfill.Fullscreen}
     - prefixed video QoE metrics:
       {@linksource shaka.polyfill.VideoPlaybackQuality}
-    - prefixed EME implementations for IE 11 and very old versions of embedded
-      Chrome/Chromium:
-      - {@linksource shaka.polyfill.PatchedMediaKeysMs}
+    - prefixed EME implementations:
       - {@linksource shaka.polyfill.PatchedMediaKeysWebkit}
       - {@linksource shaka.polyfill.PatchedMediaKeysNop}
     - variants of VTTCue and TextTrackCue constructors:
@@ -108,7 +106,7 @@ python build/build.py +@complete -@polyfill
 python build/build.py +@complete -@polyfill -@text
 ```
 
-To see the complete list of categories, its in [`build/types/`](https://github.com/google/shaka-player/tree/master/build/types)
+To see the complete list of categories, its in [`build/types/`](https://github.com/shaka-project/shaka-player/tree/main/build/types)
 
 #### Build Configs
 
@@ -177,5 +175,5 @@ 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/google/shaka-player/issues/new/choose
-[pull request]: https://github.com/google/shaka-player/pull/new/master
+[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

@@ -0,0 +1,122 @@
+# 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_config: *firefox_config
+
+FirefoxWindows:
+  browser: firefox
+  os: Windows
+  extra_config: *firefox_config
+
+FirefoxLinux:
+  browser: firefox
+  os: Linux
+  extra_config: *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_config` (optional): A dictionary 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_config:
+    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
+```

package/docs/tutorials/upgrade.md

@@ -1,17 +1,89 @@
 # Shaka Player Upgrade Guide
 
-If you are upgrading from **v1 - v2.2**, please see
-{@link https://v2-4-7-dot-shaka-player-demo.appspot.com/docs/api/tutorial-upgrade.html
-the upgrade guides from the v2.4 releases}, then return to this guide.
+If you are upgrading from **v1 or v2**, these releases are no longer supported,
+and upgrade guides are no longer maintained.  You can use these old upgrades
+guides to upgrade in stages:
 
-If you are upgrading from **v2.3 - v2.4**, please see
-{@link https://v2-5-10-dot-shaka-player-demo.appspot.com/docs/api/tutorial-upgrade.html
-the upgrade guides from the v2.5 releases}, then return to this guide.
+ - {@link https://v2-4-7-dot-shaka-player-demo.appspot.com/docs/api/tutorial-upgrade.html Upgrade to v2.4}
+ - {@link https://v2-5-23-dot-shaka-player-demo.appspot.com/docs/api/tutorial-upgrade-v2-4.html Upgrade v2.4 => v2.5}
+ - {@link https://v3-0-15-dot-shaka-player-demo.appspot.com/docs/api/tutorial-upgrade-v2-5.html Upgrade v2.5 => v3.0}
 
-From these older release branches, you will have to use our upgrade guides in
-phases.  This is necessary to keep our guides maintainable.  Thanks for your
-understanding!
+Since v3.0, Shaka Player has been following semantic versioning.  (The
+IE11 deprecation announced before v3.0 happened in v3.1, which technically
+breaks semantic versioning guarantees.  It is the only intentional exception.)
 
-If you are upgrading from **v2.5**, please see {@tutorial upgrade-v2-5}.
+Upgrading from any v3 release to a newer v3 release should be backward
+compatible.  The same is true of all major version numbers (v4 => v4, etc).
 
-If you are upgrading from another **v3** release, please see {@tutorial upgrade-v3}.
+Here is a summary of breaking changes that might require upgrades to your
+application:
+
+
+## v3.1
+
+  - New dependencies:
+    - 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)
+
+  - Support removed:
+    - IE11 support removed
+
+
+## v4.0
+
+  - Support removed:
+    - Older TVs and set-top boxes that do not support MediaSource sequence mode
+      can no longer play HLS content (since we now use sequence mode for that)
+    - Support for iOS 12 and Safari 12 has been removed
+
+  - Configuration changes:
+    - `manifest.dash.defaultPresentationDelay` has been replaced by
+      `manifest.defaultPresentationDelay` (deprecated in v3.0.0)
+    - Configuration of factories should be plain factory functions, not
+      constructors; these will not be invoked with `new` (deprecated in v3.1.0)
+    - `drm.initDataTransform` has been removed (no longer needed since the
+      minimum supported version of iOS is now 13)
+    - `streaming.smallGapLimit` and `streaming.jumpLargeGaps` have been removed;
+      all gaps will now be jumped
+
+  - Player API changes:
+    - `shaka.Player.prototype.addTextTrack()` has been replaced by
+      `addTextTrackAsync()`, which returns a `Promise` (deprecated in v3.1.0)
+
+  - UI API changes:
+    - `shaka.ui.TrackLabelFormat` has been renamed to
+      `shaka.ui.Overlay.TrackLabelFormat` (deprecated in v3.1.0)
+    - `shaka.ui.FailReasonCode` has been renamed to
+      `shaka.ui.Overlay.FailReasonCode` (deprecated in v3.1.0)
+
+  - Offline API changes:
+    - `shaka.offline.Storage.prototype.store()` returns `AbortableOperation`
+      instead of `Promise`; callers should change `.then()` to
+      `.promise.then()` and `await rv` to `await rv.promise` (deprecated in
+      v3.0.0)
+    - `shaka.offline.Storage.prototype.getStoreInProgress()` has been removed;
+      concurrent operations are supported since v3, so callers don't need to
+      check this (deprecated in v3.0.0)
+
+  - Utility API changes:
+    - `shaka.util.Uint8ArrayUtils.equal` has been replaced by
+      `shaka.util.BufferUtils.equal`, which can handle multiple types of
+      buffers (deprecated in v3.0.0)
+
+  - Manifest API changes:
+    - `shaka.media.SegmentIndex.prototype.destroy()` has been replaced by
+      `release()`, which is synchronous (deprecated in v3.0.0)
+    - `shaka.media.SegmentIterator.prototype.seek()`, which mutates the
+      iterator, has been replaced by
+      `shaka.media.SegmentIndex.getIteratorForTime()` (deprecated in v3.1.0)
+    - `shaka.media.SegmentIndex.prototype.merge()` has become private; use
+      `mergeAndEvict()` instead (deprecated in v3.2.0)
+
+  - Plugin changes:
+    - `AbrManager` plugins must implement the `playbackRateChanged()` method
+      (deprecated in v3.0.0)
+    - `shaka.extern.Cue.prototype.spacer` has been replaced by the more
+      clearly-named `lineBreak` (deprecated in v3.1.0)
+    - `IUIElement` plugins must have a `release()` method (not `destroy()`)
+      (deprecated in v3.0.0)