shaka-player 4.6.3 → 4.7.0

package/docs/tutorials/upgrade-manifest.md

@@ -1,281 +0,0 @@
-# Shaka Player Manifest Upgrade Guide (v3.0)
-
-v3.0 introduced many changes to the `shaka.extern.Manifest` structure.
-This is a detailed guide for upgrading `ManifestParser` plugins or applications
-using `Player.getManifest()` to extract information about content.  Any
-application with a custom `ManifestParser` or which uses `Player.getManifest()`
-MUST be upgraded for compatibility with v3.0.
-
-
-#### Registration
-
-In addition to registering new parsers or overriding existing ones with
-{@link shaka.media.ManifestParser.registerParserByMime}, you can now also
-unregister them with {@link shaka.media.ManifestParser.unregisterParserByMime}.
-
-
-#### Manifest and Period-flattening
-
-The {@link shaka.extern.Manifest} structure has changed.  The concept of
-"Periods", based closely on DASH, has been removed.  Many individual parts of
-the manifest structure have changed to make this possible.  In this section, we
-will give a high-level view of the changes.  In the sections below, you will
-find details on the changes to the various parts of the `Manifest` structure and
-the `ManifestParser` plugin interfaces.
-
-If you have a custom `ManifestParser` plugin that parses multi-Period DASH
-content, you will need to consider how `<Representation>`s connect across
-`<Period>`s.  Each {@link shaka.extern.Stream} now comprises the entire
-presentation, and {@link shaka.media.SegmentReference} timestamps are no longer
-Period-relative.
-
-If you have a custom `ManifestParser` plugin that parses other formats, or if
-your application reads the `Manifest` structure, you will just need to move a
-few fields and make some relatively minor API updates as detailed below.
-
-In v2.5, `Manifest` objects contained `Period`s, and each `Period` contained
-fields named `variants` and `textStreams`.  These fields are now part of the
-top-level `Manifest` structure, and the `Stream` objects that make them up now
-span all DASH Periods.  `ManifestParser` plugins MUST be updated to move these
-fields, and applications which read the `Manifest` object MUST be updated to
-look for them in the new location.
-
-
-#### Filtering
-
-The {@link shaka.extern.ManifestParser.PlayerInterface} structure has changed.
-Instead of `filterNewPeriod` and `filterAllPeriods`, there is now a single
-callback: {@link shaka.extern.ManifestParser.PlayerInterface#filter}.  This
-should be invoked any time new text streams or variants are added to the
-manifest.  `ManifestParser` plugins MUST be updated to use the new callback.
-Keep in mind that the new `filter` method is asynchronous, and thus it should
-probably be used in conjunction with `.then()` or `await`.
-
-```js
-// v2.5:
-// Call this after the initial parsing
-this.playerInterface_.filterAllPeriods(periods);
-
-// Call this after any new periods are added
-this.playerInterface_.filterNewPeriod(someNewPeriod);
-
-// v3.0:
-// Call this after the initial parsing or after any new streams are added
-await this.playerInterface_.filter(manifest);
-```
-
-
-#### Embedded Captions
-
-There is another new method inside the player interface,
-`makeTextStreamsForClosedCaptions`.
-This method must be called on the manifest initially, and after each time new
-content is added, in order for embedded captions, such as CEA 608 captions,
-to work.
-
-```js
-this.playerInterface_.makeTextStreamsForClosedCaptions(manifest);
-```
-
-
-#### PresentationTimeline
-
-The API for {@link shaka.media.PresentationTimeline} has changed.
-`ManifestParser` plugins that use these methods MUST be updated:
-
-  - {@link shaka.media.PresentationTimeline#notifySegments} now takes a
-    reference array only, instead of a reference array and a Period start time
-    or boolean flag.
-
-```js
-// v2.4:
-timeline.notifySegments(segmentList, /* periodStart= */ 0);
-
-// v2.5:
-timeline.notifySegments(segmentList, /* isFirstPeriod= */ true);
-
-// v3.0:
-timeline.notifySegments(segmentList);
-```
-
-
-#### DrmInfo
-
-The {@link shaka.extern.DrmInfo} structure has changed.  The `keyIds` field is
-now a `Set` of `string`s instead of an `Array`.  `ManifestParser` plugins MUST
-be updated to return the correct type, and applications which read this part of
-the `Manifest` structure MUST be updated to interact with `Set` instead of an
-`Array`.
-
-
-#### Variant
-
-The {@link shaka.extern.Variant} structure has changed.  The `drmInfos` field
-has moved to {@link shaka.extern.Stream}.  `ManifestParser` plugins MUST be
-updated to output this field on the correct object.
-
-
-#### Stream
-
-The {@link shaka.extern.Stream} structure has changed.
-
-The `drmInfos` field that used to appear in {@link shaka.extern.Variant} has
-been moved here.  `ManifestParser` plugins MUST be updated to output this field
-on the correct object.
-
-The `findSegmentPosition` and `getSegmentReference` callbacks have been replaced
-with `segmentIndex`, an instance of {@link shaka.media.SegmentIndex}.
-`ManifestParser` plugins MUST be updated to output a `segmentIndex` instead of
-these callbacks.  (In many cases, you may have been basing these callbacks on a
-`SegmentIndex` object's `find` and `get` methods already.)
-
-The `initSegmentReference` and `presentationTimeOffset` fields are no longer
-part of `Stream`.  This information has moved to
-{@link shaka.media.SegmentReference}.  `ManifestParser` plugins MUST be updated
-accordingly.  See the section on `SegmentReference` for details.
-
-The `keyId` field, a string, has been replaced with the `keyIds` field, a `Set`
-of `string`s.  `ManifestParser` plugins MUST be updated to output the new field.
-
-
-#### InitSegmentReference
-
-The {@link shaka.media.InitSegmentReference} API has changed.  The `createUris`
-methods has been removed, as it was redundant.  Applications with custom
-`ManifestParser` plugins and applications which read `InitSegmentReference`s
-MUST be updated to use `getUris` instead.
-
-
-#### SegmentReference
-
-The {@link shaka.media.SegmentReference} API has changed.  Applications with
-custom `ManifestParser` plugins and applications which read `SegmentReference`s
-MUST be updated to account for all changes below.
-
-The `createUris` methods has also been removed, as it was redundant.  Use
-`getUris` instead.
-
-`SegmentReference` objects no longer have any internal concept of "position".
-The `getPosition` method has been removed, and the constructor no longer takes a
-position parameter.
-
-`SegmentReference` timestamps are no longer relative to the Period.  Instead,
-they are presentation timestamps.  For example, if the Period starts at 100 and
-the segment begins at time 5 within that Period, `startTime` will now be 105.
-
-`SegmentReference` objects now contain their `InitSegmentReference`.  This
-allows the segments within a `Stream` to change init segments mid-stream, which
-is used both for multi-Period DASH and for HLS discontinuities.  If two segments
-have the same initialization segment, their `SegmentReference`s MUST have the
-same `InitSegmentReference` object at the same memory address.
-`StreamingEngine` will compare `InitSegmentReference` objects to determine when
-a new init segment must be fetched, and this will NOT be a deep comparison of
-the contents of the object.
-
-`SegmentReference` objects now contain an append window.  This is used to trim
-content in `MediaSource`.  For multi-Period content, this is the start and end
-of the Period from which the segment comes.  For other content, the start is
-usually 0 and the end is usually `Infinity`.
-
-`SegmentReference` objects now contain a timestamp offset.  `MediaSource` adds
-this value to the timestamps in the media segment when it is parsed by the
-browser.  This should be the value which aligns the media timestamps (in the
-segment) to the presentation timestamps (in the `SegmentReference`).  This is
-related to the `presentationTimeOffset` from v2.5 and earlier.
-`timestampOffset` should be the period start time minus the
-`presentationTimeOffset`.  (In v2.5, this is how `MediaSource`'s
-`timestampOffset` field was calculated.  Now, we pass the `timestampOffset`
-field from the `SegmentReference` directly to `MediaSource`.)
-
-```js
-// v2.5
-const period = {
-  startTime: 100,
-  /* ... */
-};
-const initSegmentReference = /* ... */;
-const stream = {
-  /* ... */
-  initSegmentReference,
-  presentationTimeOffset: 20,
-};
-const ref = new shaka.media.SegmentReference(
-    /* position= */ 0,
-    /* startTime= */ 0,
-    /* endTime= */ 10,
-    /* uris= */ () => [uri],
-    /* startByte= */ 0,
-    /* endByte= */ null);
-
-// v3.0
-const ref = new shaka.media.SegmentReference(
-    /* startTime= */ 100,  // <-- period start 100 + period-relative timestamp 0
-    /* endTime= */ 110,
-    /* uris= */ () => [uri],
-    /* startByte= */ 0,
-    /* endByte= */ null,
-    initSegmentReference,
-    /* timestampOffset= */ 80,  // <-- period start 100 - PTO 20
-    /* appendWindowStart= */ 100,  // <-- period start
-    /* appendWindowEnd= */ Infinity);  // <-- for the last period in live stream
-```
-
-
-#### SegmentIndex
-
-The {@link shaka.media.SegmentIndex} API has changed.  Applications with custom
-`ManifestParser` plugins and applications which read `SegmentIndex`es MUST be
-updated to account for all changes below.
-
-The asynchronous `destroy` method has been replaced with the synchronous
-`release` method.  Applications which destroy `SegmentIndex` objects SHOULD be
-updated to call `release` instead.  Backward compatibility will be removed in
-v4.0.
-
-The `find` method still returns a position which can be passed to `get`, but
-this position is no longer part of the underlying `SegmentReference` object.
-(See changes to `SegmentReference` in the section above.)  The value returned
-from `find` is now abstract.  This should be completely compatible with v2.5,
-but the value can no longer be tied to a `SegmentReference`.
-
-The `merge` method has been simplified.  It was already documented to only
-support extending the reference array without replacing anything or interleaving
-new references into the old ones.  Now it is actually a true statement about the
-implementation.  If your custom `ManifestParser` plugin was relying on the old
-merge behavior rather than its documentation, you MUST update your plugin.
-
-The `evict` method now takes a presentation timestamp.  See related changes in
-the `SegmentReference` section above.
-
-The `fit` method now takes a window start and end time instead of a period
-duration.  See related changes in the `SegmentReference` section above.
-
-The `updateEvery` method has been added.  This allows `ManifestParser` plugins
-to schedule callbacks to calculate additional `SegmentReference`s to be appended
-to the reference array.  This is useful, for example, in generating references
-for `<SegmentTemplate>` content in DASH.
-
-The static `forSingleSegment` method has been added.  It will generate a
-`SegmentIndex` for a single segment based on a start time, duration, and URIs.
-This is useful for `ManifestParser` plugins creating non-segmented text
-`Stream`s.
-
-Finally, `SegmentIndex` now implements the `Iterable` protocol.  This means
-applications can now iterate through the index or convert it to an Array.  For
-example:
-
-```js
-for (const reference of stream.segmentIndex) {
-  // ...
-}
-
-// OR
-
-const listOfReferences = Array.from(stream.segmentIndex);
-
-// OR
-
-const firstReference = Array.from(stream.segmentIndex)[0];
-```
-
-This could be useful to applications which read the contents of a `Manifest`.

package/docs/tutorials/upgrade.md

@@ -1,104 +0,0 @@
-# Shaka Player Upgrade 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:
-
- - {@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}
-
-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.)
-
-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).
-
-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)
-      Fallback included by default in v4.2
-
-  - 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` now defaults to a no-op
-    - `streaming.smallGapLimit` and `streaming.jumpLargeGaps` have been removed;
-      all gaps will now be jumped
-    - `manifest.hls.useFullSegmentsForStartTime` has been removed; this setting
-      is no longer necessary, as we no longer fetch segments for start times in
-      the HLS parser
-
-  - 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)
-
-## v5.0 (unreleased)
-
-  - 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.
-
-  - Player API Changes:
-    - The constructor no longer takes `mediaElement` as a parameter; use the `attach` method to attach to a media element instead. (Deprecated in v4.6)

package/docs/tutorials/welcome.md

@@ -1,108 +0,0 @@
-# Welcome to Shaka Player
-
-Shaka Player is a JavaScript library for adaptive video streaming.
-It plays [DASH][] content without browser plugins using
-[MediaSource Extensions][] and [Encrypted Media Extensions][].
-
-Shaka Player is meant to be deployed after being compiled. The tools you need
-to compile the sources and documentation are included in the sources:
-[Closure Compiler][], [Closure Linter][], and [JSDoc][].
-
-If you are integrating Shaka Player into another Closure-based project, our
-build process will generate externs for Shaka Player itself.
-
-If you installed Shaka Player via npm, the source has been compiled and the
-externs have been generated.
-
-[DASH]: http://dashif.org/
-[MediaSource Extensions]: http://w3c.github.io/media-source/
-[Encrypted Media Extensions]: https://w3c.github.io/encrypted-media/
-
-[Closure Compiler]: https://developers.google.com/closure/compiler/
-[Closure Linter]: https://developers.google.com/closure/utilities/docs/linter_howto
-[JSDoc]: http://usejsdoc.org/
-
-
-#### Prerequisites
-
-You can build Shaka on Linux, Windows, or Mac.
-To get the sources and compile the library, you will need:
-  * {@link https://git-scm.com/downloads Git v1.9+}
-  * {@link https://www.python.org/downloads/ Python v2.7 or v3.5+}
-  * {@link https://learn.microsoft.com/en-us/java/openjdk/download Java Runtime Environment v14+}
-  * {@link https://nodejs.org/en/download/ NodeJS v14+}
-  * A local web server, such as {@link https://httpd.apache.org/ Apache}
-    * _NOTE: A local web server is required because browsers place restrictions
-      on applications from file:/// URLs._
-
-If you just want to compile for export to other projects, you might consider compiling through a docker container. (see compile instructions)
-
-To quickly install these prerequisites on Ubuntu or Debian, you can run this
-script:
-
-```sh
-curl https://raw.githubusercontent.com/shaka-project/shaka-player/main/build/install-linux-prereqs.sh | bash
-```
-
-We do not provide detailed instructions or scripts for installing these
-prerequisites on other operating systems or on non-Debian-based Linux
-distributions.  (We couldn't possibly document them all.)  You can follow the
-links above to download and install the prerequisites manually on any OS.
-
-
-#### Get the source
-
-```sh
-git clone https://github.com/shaka-project/shaka-player.git
-cd shaka-player
-```
-
-
-#### Compile the library and generate the docs
-
-```sh
-python build/all.py
-```
-
-Alternatively you can use a docker container:
-```sh
-docker build -t shaka-player-build build/docker
-docker run -v $(pwd):/usr/src --user $(id -u):$(id -g) shaka-player-build
-```
-
-The output is:
- * dist/shaka-player.compiled.js (compiled bundle)
- * dist/shaka-player.compiled.debug.js (debug bundle)
- * dist/shaka-player.compiled.externs.js
-   (generated externs, for Closure-based projects)
- * docs/api/index.html (generated documentation)
-
-
-#### Run the tests
-
-The tests depend on a few third-party tools, which are installed automatically
-via `npm` when you run the tests. Nothing will be installed globally.
-
-Run the tests in your platform's browsers using `./build/test.py`. You can
-specify particular browsers with the `--browsers` argument. For example:
-
-```sh
-./build/test.py --browsers Opera
-
-# or:
-
-./build/test.py --browsers Chrome,Firefox,Edge
-```
-
-You can find a full list of available browsers with `--browsers help`, and you
-can find a complete list of testing options with `--help`.
-
-
-#### Announcements
-
-To subscribe to new releases on GitHub, you can follow
-[instructions from this blog](https://www.jessesquires.com/blog/2020/07/30/github-tip-watching-releases/).
-
-To receive infrequent announcements and surveys from us, you can join our
-[mailing list](https://groups.google.com/forum/#!forum/shaka-player-users).
-The list is very low volume, and can only be written to by us.

package/docs/tutorials/widevine-service-certs.md

@@ -1,45 +0,0 @@
-# Widevine Service Certificates
-
-With Widevine, you can eliminate one round-trip to your license server or proxy
-per session by preloading a Widevine service certificate. You can either provide
-it directly or set a URI and let Shaka fetch it for you. Do this before calling
-`player.load()`. The values will persist across multiple calls to `load()` on
-the same `shaka.Player` instance.
-
-```js
-// This is an example of loading the certificate from your site at runtime.
-// You could also choose to bundle it into your JavaScript as a Uint8Array.
-const req = await fetch('https://example.com/service.cert');
-const cert = new Uint8Array(await req.arrayBuffer());
-
-// This is the short form for configuration of a certificate:
-player.configure('drm.advanced.com\\.widevine\\.alpha.serverCertificate',
-                 cert);
-
-// This is the long form:
-player.configure({
-  drm: {
-    advanced: {
-      'com.widevine.alpha': {
-        'serverCertificate': cert,
-      },
-    },
-  },
-});
-
-
-// This is the short form for configuration of a certificate URI:
-player.configure('drm.advanced.com\\.widevine\\.alpha.serverCertificateUri',
-                 'https://example.com/service.cert');
-
-// This is the long form:
-player.configure({
-  drm: {
-    advanced: {
-      'com.widevine.alpha': {
-        'serverCertificateUri': 'https://example.com/service.cert',
-      },
-    },
-  },
-});
-```