Overhaul variant-based and stream-based interfaces

While I set out to fix failing assertions during playback, I found
many more changes necessary to clean up the code and make things more
consistent.

When we changed switch history to include variants instead of streams,
we broke the filtering logic that is applied to the history.  This
caused assertions at runtime that were not caught by the tests.

This moves the filtering logic to addToSwitchHistory_ and makes it
aware of variants.  It also adds a regression test that would have
caught the assertions.

This fix affected many other tests, though, which necessitated other
API changes and cleanup.

Many interfaces are simplified, as is switching logic in Player.  The
data flow is also easier to follow, since there are fewer transitions
between variant and stream.  Everything up to StreamingEngine uses
Variants, and StreamingEngine uses Streams internally.

  - All stream-based interfaces on AbrManager replaced
    - switch callback takes a variant
    - chooseStreams replaced with chooseVariant
    - setTextStreams has been dropped
    - Player maintains compatibility with old interfaces until v2.3

  - Most stream-based interfaces on StreamingEngine replaced
    - onChooseStreams callback to Player returns variant & text
      instead of a stream map
    - switch was replaced with switchVariant and switchTextStream,
      both of which delegate to switchInternal_, which is largely
      unchanged from the original switch method
    - still has getActiveStreams, which I hope some day can become
      getActiveVariant and getActiveTextStream so Player no longer
      has to convert anything

  - Most stream-based logic in Player replaced
    - deferred switches map broken into variant and text members
    - switch history logging broken into simpler variant and text
      methods
    - simplified manual and automatic track selection logic using
      new AbrManager and StreamingEngine APIs
    - player no longer filters duplicate selections, StreamingEngine
      handles that
    - replaced one case of deferred switches with an assertion

Closes #954

Change-Id: Ia49f6ffb9c5fa13ed8790dd03eeeded5122f7683

docs/tutorials/upgrade-v2-0.md

@@ -58,24 +58,28 @@ types (variant and text).
 
 #### Setting and configuring ABR manager
 
-In Shaka v2.0 a custom abr manager could be set through
+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
+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
+The API for AbrManager has 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
+
+In v2.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.
@@ -89,8 +93,39 @@ abrManager.setRestrictions(restrictions);
 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.
+In v2.0, AbrManager had a `chooseStreams()` method for the player to prompt for
+a stream selection, and a `switch()` callback to send unsolicited changes from
+AbrManager to player.  In v2.2, `chooseStreams()` has been replaced with
+`chooseVariant()`, and the `switch()` callback takes a variant instead of a map
+of streams.
+
+```js
+// v2.0:
+var map = abrManager.chooseStreams(['audio', 'video']);
+console.log(map['video'], map['audio']);
+
+MyAbrManager.prototype.makeDecision_ = function() {
+  var video = this.computeBestVideo_(this.bandwidth_);
+  var audio = this.computeBestAudio_(this.bandwidth_);
+  var map = {
+    'audio': audio,
+    'video': video
+  };
+  this.switch_(map);
+};
+
+// v2.2:
+var variant = abrManager.chooseVariant();
+console.log(variant, variant.video, variant.audio);
+
+MyAbrManager.prototype.makeDecision_ = function() {
+  var variant = this.computeBestVariant_(this.bandwidth_);
+  this.switch_(variant);
+};
+```
+
+In v2.2, the v2.0 interfaces are still supported, but are deprecated.  Support
+will be removed in v2.3.
 
 
 #### Selecting tracks and adaptation settings

docs/tutorials/upgrade-v2-1.md

@@ -82,24 +82,28 @@ See {@link shaka.text.Cue} for details.
 
 #### Setting and configuring ABR manager
 
-In Shaka v2.1 a custom abr manager could be set through
+In Shaka v2.1, a custom ABR manager could be set through:
+
 ```js
 player.configure({
   abr.manager: customAbrManager
 });
 ```
 
-In v2.2 it's done through
+In v2.2, it's done through:
+
 ```js
 player.configure({
   abrFactory: customAbrManager
 });
 ```
 
-The API for abr manager also changed.
-In v2.1 default bandwidth estimate and restrictions were set through
+The API for AbrManager also changed.
+
+In v2.1, default bandwidth estimate and restrictions were set through
 `setDefaultEstimate()` and `setRestrictions()` methods.
-In 2.2 they are set through `configure()` method which accepts a
+
+In v2.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.
@@ -113,8 +117,39 @@ abrManager.setRestrictions(restrictions);
 abrManager.configure(abrConfigurations);
 ```
 
-In v2.2, the v2.1 interfaces for setting and configuring abr manager are
-still supported, but are deprecated.  Support will be removed in v2.3.
+In v2.1, AbrManager had a `chooseStreams()` method for the player to prompt for
+a stream selection, and a `switch()` callback to send unsolicited changes from
+AbrManager to player.  In v2.2, `chooseStreams()` has been replaced with
+`chooseVariant()`, and the `switch()` callback takes a variant instead of a map
+of streams.
+
+```js
+// v2.1:
+var map = abrManager.chooseStreams(['audio', 'video']);
+console.log(map['video'], map['audio']);
+
+MyAbrManager.prototype.makeDecision_ = function() {
+  var video = this.computeBestVideo_(this.bandwidth_);
+  var audio = this.computeBestAudio_(this.bandwidth_);
+  var map = {
+    'audio': audio,
+    'video': video
+  };
+  this.switch_(map);
+};
+
+// v2.2:
+var variant = abrManager.chooseVariant();
+console.log(variant, variant.video, variant.audio);
+
+MyAbrManager.prototype.makeDecision_ = function() {
+  var variant = this.computeBestVariant_(this.bandwidth_);
+  this.switch_(variant);
+};
+```
+
+In v2.2, the v2.1 interfaces are still supported, but are deprecated.  Support
+will be removed in v2.3.
 
 
 #### Switch history changes

externs/shaka/abr_manager.js

@@ -39,15 +39,15 @@ shakaExtern.AbrManager = function() {};
 
 
 /**
- * A callback from the Player that should be called when the AbrManager decides
- * it's time to change to a different set of streams.
+ * A callback into the Player that should be called when the AbrManager decides
+ * it's time to change to a different variant.
  *
- * The first argument is a map of content types to chosen streams.
+ * The first argument is a variant to switch to.
  *
  * The second argument is an optional boolean.  If true, all data will be
  * from the buffer, which will result in a buffering event.
  *
- * @typedef {function(!Object.<string, !shakaExtern.Stream>, boolean=)}
+ * @typedef {function(shakaExtern.Variant, boolean=)}
  * @exportDoc
  */
 shakaExtern.AbrManager.SwitchCallback;
@@ -90,31 +90,16 @@ shakaExtern.AbrManager.prototype.setVariants = function(variants) {};
 
 
 /**
- * Updates manager's text streams collection.
- *
- * @param {!Array.<!shakaExtern.Stream>} streams
- * @exportDoc
- */
-shakaExtern.AbrManager.prototype.setTextStreams = function(streams) {};
-
-
-/**
- * Chooses one Stream from each media type in mediaTypesToUpdate to switch to.
- * All Variants and Streams must be from the same Period.
- *
- * @param {!Array.<!string>} mediaTypesToUpdate
- * @return {!Object.<string, shakaExtern.Stream>}
+ * Chooses one variant to switch to.  Called by the Player.
+ * @return {shakaExtern.Variant}
  * @exportDoc
  */
-// TODO: Consider breaking down into chooseVariant() and chooseText()
-shakaExtern.AbrManager.prototype.chooseStreams =
-    function(mediaTypesToUpdate) {};
+shakaExtern.AbrManager.prototype.chooseVariant = function() {};
 
 
 /**
- * Enables automatic Stream choices from the last StreamSets passed to
- * chooseStreams(). After this, the AbrManager may call switchCallback() at any
- * time.
+ * Enables automatic Variant choices from the last ones passed to setVariants.
+ * After this, the AbrManager may call switchCallback() at any time.
  *
  * @exportDoc
  */