Update upgrade guides with v2.2 changes.

Closes #930.

Change-Id: Ie31f6f1e90df6dd4a768f7a662d68e31d6014bea

docs/tutorials/index.json

@@ -16,7 +16,8 @@
       "title": "Upgrade Guide",
       "children": {
         "upgrade-v1": { "title": "Upgrade Guide, v1 => v2.1" },
-        "upgrade-v2-0": { "title": "Upgrade Guide, v2.0 => v2.1" }
+        "upgrade-v2-0": { "title": "Upgrade Guide, v2.0 => v2.1" },
+        "upgrade-v2-1": { "title": "Upgrade Guide, v2.1 => v2.2" }
       }
   } }
 ]

docs/tutorials/plugins.md

@@ -39,6 +39,13 @@ __Subtitle/caption parsers__
     - TTML: {@linksource shaka.media.TtmlTextParser} and
       {@linksource shaka.media.Mp4TtmlParser}
 
+__Subtitle/caption displayers__
+  - Configured at runtime on a Player instance
+  - Use {@link player.configure} and set the `textDisplayFactory` field
+  - Must implement the {@link shakaExtern.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}
@@ -48,7 +55,7 @@ __Networking plugins__
 
 __ABR plugins__
   - Configured at runtime on a Player instance
-  - Use {@link player.configure} and set the `abr.manager` field
+  - Use {@link player.configure} and set the `abrFactory` field
   - Must implement the {@link shakaExtern.AbrManager} interface
   - Default AbrManager implementation: {@linksource shaka.abr.SimpleAbrManager}
 

docs/tutorials/upgrade-v1.md

@@ -23,6 +23,16 @@ Shaka v2 has several improvements over v1, including:
   - New plugin and build system to extend Shaka
   - Cache-friendly networking
   - Simpler, mobile-friendly demo app
+  - Basic HLS support
+  - DASH trick mode support
+  - Support for jumping gaps in the timeline
+  - Additional stats and events from Player
+  - Indication of critical errors vs recoverable errors
+  - Allowing applications to render their own text tracks
+  - Making the default ABR manager more configurable
+  - Adding channel count and bandwidth info to variant tracks
+  - Xlink support in DASH
+  - New option for offline protected content without persistent licensing
 
 
 #### Shaka Plugins
@@ -347,11 +357,8 @@ and custom AbrManagers are now provided via `player.configure()`:
 ```js
 // v2:
 var player = new shaka.Player(video);
-var customAbrManager = new MyCustomAbrManager();
 player.configure({
-  abr: {
-    manager: customAbrManager
-  }
+  abrFactory: MyCustomAbrManager
 });
 player.load(manifestUri);
 ```
@@ -536,9 +543,10 @@ player.getStats()
   bufferingTime: number  // seconds, same as v1
   switchHistory: Array of Objects  // replaces v1's streamHistory
     timestamp: number  // seconds, when the stream was selected
-    id: number  // stream ID
+    id: number  // track ID
     type: string  // 'variant' or 'text'
     fromAdaptation: boolean  // distinguishes between ABR and manual choices
+    bandwidth: ?number // track's bandwidth (null for text tracks)
   stateChange: Array of Objects
     timestamp: number  // seconds, when the state changed
     state: string  // 'buffering', 'playing', 'paused', or 'ended'

docs/tutorials/upgrade-v2-0.md

@@ -1,11 +1,11 @@
-# Shaka Upgrade Guide, v2.0 => v2.1
+# Shaka Upgrade Guide, v2.0 => v2.2
 
-This is a detailed guide for upgrading from Shaka Player v2.0 to v2.1.
+This is a detailed guide for upgrading from Shaka Player v2.0 to v2.2.
 Feel free to skim or to search for the class and method names you are using in
 your application.
 
 
-#### What's New in v2.1?
+#### What's New in v2.1 and v2.2?
 
 Shaka v2.1 introduces several improvements over v2.0, including:
   - Basic HLS support
@@ -14,6 +14,12 @@ Shaka v2.1 introduces several improvements over v2.0, including:
   - Asynchronous network filters
   - Additional stats and events from Player
   - Indication of critical errors vs recoverable errors
+  - Allowing applications to render their own text tracks
+  - Making the default ABR manager more configurable
+  - Adding channel count and bandwidth info to variant tracks
+  - Xlink support in DASH
+  - Stricter runtime type-checking of EME cert configuration
+  - New option for offline protected content without persistent licensing
 
 
 #### Selecting tracks
@@ -30,7 +36,7 @@ var i = /* choose an index somehow */;
 player.selectTrack(videoTracks[i]);
 ```
 
-In Shaka v2.1, audio and video tracks are combined into a variant track.  It is
+In Shaka v2.2, audio and video tracks are combined into a variant track.  It is
 not possible to select individual audio/video streams, you can only select a
 specific variant as specified by the manifest.  This was necessary for us to
 support HLS.  Text tracks are independent of variant tracks.
@@ -40,22 +46,53 @@ You can get the currently available tracks using `getVariantTracks()` and
 `selectTextTrack()`.
 
 ```js
-// v2.1:
+// v2.2:
 var variantTracks = player.getVariantTracks();
 var i = /* choose an index somehow */;
 player.selectVariantTrack(variantTracks[i]);
 ```
 
-The v2.0 methods `getTracks()` and `selectTrack()` are still present in v2.1,
-but they are deprecated and will be removed in v2.2.  However, they are not
-completely backward compatible because of the `type` field.  If you are looking
-for `'video'` or `'audio'` in the `type` field, your application will need to
-be updated to handle `'variant'` instead.
-
 See also the {@link shakaExtern.Track} structure which is used for all track
 types (variant and text).
 
 
+#### Setting and configuring ABR manager
+
+In Shaka v2.0 a custom abr manager could be set through
+```js
+player.configure({
+  abr.manager: customAbrManager
+});
+```
+
+In v2.2 it's done through
+```js
+player.configure({
+  abrFactory: customAbrManager
+});
+```
+
+The API for abr manager also changed.
+In v2.0 default bandwidth estimate and restrictions were set through
+`setDefaultEstimate()` and `setRestrictions()` methods.
+In 2.2 they are set through `configure()` method which accepts a
+{@link shakaExtern.AbrConfiguration} structure. The new method is more general,
+and allows for the configuration of bandwidth upgrade and downgrade targets
+as well.
+
+```js
+// v2.0:
+abrManager.setDefaultEstimate(defaultBandwidthEstimate);
+abrManager.setRestrictions(restrictions);
+
+// v2.2:
+abrManager.configure(abrConfigurations);
+```
+
+In v2.2, the v2.0 interfaces for setting and configuring abr manager are
+still supported, but are deprecated.  Support will be removed in v2.3.
+
+
 #### Selecting tracks and adaptation settings
 
 In v2.0, selecting a new video or audio track would implicitly disable
@@ -69,10 +106,10 @@ player.selectTrack(videoTracks[i]);
 player.configure({abr: {enabled: true}});
 ```
 
-In v2.1, any change in ABR state must be made explicitly if desired.
+In v2.2, any change in ABR state must be made explicitly if desired.
 
 ```js
-// v2.1
+// v2.2
 player.selectVariantTrack(variantTracks[i]);
 // Adaptation state has not changed!
 // To explicitly disable:
@@ -93,7 +130,7 @@ player.load(manifestUri);  // Canadian French preferred for initial playback
 player.configure({ preferredAudioLanguage: 'el' });  // switch to Greek
 ```
 
-In Shaka v2.1, language selection during playback is explicit and separate from
+In Shaka v2.2, language selection during playback is explicit and separate from
 the configuration.  Configuration only affects the next call to `load()`, and
 will not change languages during playback.
 
@@ -102,7 +139,7 @@ To list available languages, we provide the `getAudioLanguages()` and
 `selectAudioLanguage()` and `selectTextLanguage()`.
 
 ```js
-// v2.1:
+// v2.2:
 player.configure({ preferredAudioLanguage: 'fr-CA' });
 player.load(manifestUri);  // Canadian French preferred for initial playback
 
@@ -138,8 +175,7 @@ For more information, see discussions here:
 If you have taken advantage of Shaka v2's plugin APIs, you may need to update
 your plugins to the new interfaces.
 
-In v2.1, the v2.0 interfaces for text and manifest parsers are still supported,
-but are deprecated.  Support will be removed in v2.2.
+The v2.0 interfaces for text and manifest are no longer supported.
 
 
 #### Text parser plugin changes
@@ -167,19 +203,21 @@ function MyTextParser(data, periodOffset, segmentStartTime, segmentEndTime) {
   var cues = [];
   var parserState = new MyInternalParser(data);
   while (parserState.more()) {
-    cues.push(parserState.nextCueOrThrow(periodOffset));
+    cues.push(new VTTCue(...));
   }
   return cues;
 }
 ```
 
-In Shaka v2.1, the text parser interface is now a constructor.  The interface
+In Shaka v2.2, the text parser interface is now a constructor.  The interface
 now has explicit methods for init segments and media segments, and parameters
 related to time offsets have been grouped together into one `TimeContext`
 parameter.
+Also text parser plugins now return shaka.text.Cue objects instead of VTTCue or
+TextTrackCue objects.
 
 ```js
-// v2.1
+// v2.2
 /** @constructor */
 function MyTextParser() {}
 
@@ -188,23 +226,49 @@ MyTextParser.prototype.parseInit = function(data) {
   checkInitSegmentOrThrow(data);
 };
 
+
 /**
  * @param {!ArrayBuffer} data
  * @param {shakaExtern.TextParser.TimeContext} timeContext
- * @return {!Array.<!TextTrackCue>}
+ * @return {!Array.<!shaka.text.Cue>}
  */
 MyTextParser.prototype.parseMedia = function(data, timeContext) {
   var cues = [];
   var parserState = new MyInternalParser(data);
   while (parserState.more()) {
-    cues.push(parserState.nextCueOrThrow(timeContext.periodStart));
+    cues.push(new shaka.text.Cue(...));
   }
   return cues;
 };
 ```
 
-For more information, see the {@link shakaExtern.TextParser.TimeContext} and
-{@link shakaExtern.TextParser} definitions in the API docs.
+All application-specific text-parsing plugins MUST to be updated,
+v2.2 does not have backward compatibility on this!
+The `Shaka.text.Cue` class contains the same information about a text cue as
+the VTTCue class, plus extra information about text style.
+
+For more information, see the {@link shakaExtern.TextParser.TimeContext},
+{@link shaka.text.Cue} and {@link shakaExtern.TextParser} definitions in
+the API docs.
+
+
+#### Customizing subtitle display
+
+Shaka v2 gave applications an opportunity to have a custom text parser, but
+all the displaying was handled by the browser. Shaka v2.2 adds the
+possibility to have custom logic for displaying text. By default the
+rendering will still be done by the {@linksource shaka.text.SimpleTextDisplayer}
+class.
+
+A custom text display factory can be specified by calling player.configure().
+
+```js
+player.configure({
+  textDisplayFactory: customTextDisplayerClass
+});
+```
+
+See {@linksource shakaExtern.TextDisplayer} for details.
 
 
 #### Manifest parser plugin changes
@@ -281,15 +345,15 @@ MyManifestParser.prototype.start = function(uri, playerInterface) {
 };
 ```
 
-Shaka v2.1 also adds two new methods to the manifest parser interface:
+Shaka v2.2 also adds two new methods to the manifest parser interface:
 `update()` and `onExpirationUpdated()`.
 
 The `update()` method allows `StreamingEngine` to ask for an explicit manifest
 update.  This is used, for example, to support `emsg` boxes in MP4 content,
 which can be used by the stream to indicate that a manifest update is needed.
 
 ```js
-// v2.1
+// v2.2
 MyManifestParser.prototype.update = function() {
   // Trigger an update now!
   this.updateManifest_();
@@ -302,7 +366,7 @@ changed.  We use this internally in our offline support, so that we can keep
 track of expiring licenses for stored content.
 
 ```js
-// v2.1
+// v2.2
 MyManifestParser.prototype.onExpirationUpdated =
     function(sessionId, expiration) {
   var oldExpiration = this.database_.getExpiration(this.contentId_);