Add alwaysStreamText config

This will allow text streaming to work correctly with browser native
controls.

Closes #1332

Change-Id: If11ba67957babad8dea23759aab9004d891aaf6b

docs/tutorials/config.md

@@ -54,6 +54,7 @@ player.getConfiguration();
        durationBackoff: 1
        failureCallback: Function
        ignoreTextStreamFailures: false
+       alwaysStreamText: false
        jumpLargeGaps: false
        rebufferingGoal: 2
        retryParameters: Object

externs/shaka/player.js

@@ -544,6 +544,7 @@ shakaExtern.ManifestConfiguration;
  *   bufferingGoal: number,
  *   bufferBehind: number,
  *   ignoreTextStreamFailures: boolean,
+ *   alwaysStreamText: boolean,
  *   startAtSegmentBoundary: boolean,
  *   smallGapLimit: number,
  *   jumpLargeGaps: boolean,
@@ -572,8 +573,13 @@ shakaExtern.ManifestConfiguration;
  *   in buffer behind the playhead when it appends a new media segment.
  *   The StreamingEngine will evict content to meet this limit.
  * @property {boolean} ignoreTextStreamFailures
- *   If true, the player will ignore text stream failures and proceed to play
+ *   If true, the player will ignore text stream failures and continue playing
  *   other streams.
+ * @property {boolean} alwaysStreamText
+ *   If true, always stream text tracks, regardless of whether or not they are
+ *   shown.  This is necessary when using the browser's built-in controls, which
+ *   are not capable of signaling display state changes back to Shaka Player.
+ *   Defaults to false.
  * @property {boolean} startAtSegmentBoundary
  *   If true, adjust the start time backwards so it is at the start of a
  *   segment. This affects both explicit start times and calculated start time

lib/player.js

@@ -1691,6 +1691,9 @@ shaka.Player.prototype.setTextTrackVisibility = function(on) {
   this.textVisibility_ = on;
   this.onTextTrackVisibility_();
 
+  // If we always stream text, don't do anything special to StreamingEngine.
+  if (this.config_.streaming.alwaysStreamText) return;
+
   // Load text stream when the user chooses to show the caption, and pause
   // loading text stream when the user chooses to hide the caption.
   if (!this.streamingEngine_) return;
@@ -2183,6 +2186,7 @@ shaka.Player.prototype.defaultConfig_ = function() {
       bufferingGoal: 10,
       bufferBehind: 30,
       ignoreTextStreamFailures: false,
+      alwaysStreamText: false,
       startAtSegmentBoundary: false,
       smallGapLimit: 0.5,
       jumpLargeGaps: false,
@@ -2688,8 +2692,9 @@ shaka.Player.prototype.chooseStreamsAndSwitch_ = function(period) {
     this.switchVariant_(chosenVariant, true);
   }
 
+  // Only switch text if we should be streaming text right now.
   let chosenText = textStreams[0];
-  if (chosenText && this.isTextTrackVisible()) {
+  if (chosenText && this.streamText_()) {
     this.addTextStreamToSwitchHistory_(chosenText, /* fromAdaptation */ true);
     this.switchTextStream_(chosenText);
   }
@@ -2797,8 +2802,8 @@ shaka.Player.prototype.onChooseStreams_ = function(period) {
 
   // Don't fire a tracks-changed event since we aren't inside the new Period
   // yet.
-  // Don't initialize with a text stream if the caption is not visible.
-  if (this.isTextTrackVisible()) {
+  // Don't initialize with a text stream unless we should be streaming text.
+  if (this.streamText_()) {
     return {variant: chosenVariant, text: chosenTextStream};
   } else {
     return {variant: chosenVariant, text: null};
@@ -3091,3 +3096,11 @@ shaka.Player.prototype.onExpirationUpdated_ = function(keyId, expiration) {
   let event = new shaka.util.FakeEvent('expirationupdated');
   this.dispatchEvent(event);
 };
+
+/**
+ * @return {boolean} true if we should stream text right now.
+ * @private
+ */
+shaka.Player.prototype.streamText_ = function() {
+  return this.config_.streaming.alwaysStreamText || this.isTextTrackVisible();
+};

test/media/playhead_observer_unit.js

@@ -70,6 +70,7 @@ describe('PlayheadObserver', function() {
       failureCallback: function() {},
       bufferBehind: 15,
       ignoreTextStreamFailures: false,
+      alwaysStreamText: false,
       useRelativeCueTimestamps: false,
       startAtSegmentBoundary: false,
       smallGapLimit: 0.5,

test/media/playhead_unit.js

@@ -157,6 +157,7 @@ describe('Playhead', function() {
       failureCallback: function() {},
       bufferBehind: 15,
       ignoreTextStreamFailures: false,
+      alwaysStreamText: false,
       useRelativeCueTimestamps: false,
       startAtSegmentBoundary: false,
       smallGapLimit: 0.5,

test/media/streaming_engine_integration.js

@@ -83,6 +83,7 @@ describe('StreamingEngine', function() {
       failureCallback: function() {},
       bufferBehind: 15,
       ignoreTextStreamFailures: false,
+      alwaysStreamText: false,
       useRelativeCueTimestamps: false,
       startAtSegmentBoundary: false,
       smallGapLimit: 0.5,

test/media/streaming_engine_unit.js

@@ -449,6 +449,7 @@ describe('StreamingEngine', function() {
         failureCallback: function() {},
         bufferBehind: Infinity,
         ignoreTextStreamFailures: false,
+        alwaysStreamText: false,
         startAtSegmentBoundary: false,
         smallGapLimit: 0.5,
         jumpLargeGaps: false,
@@ -1902,6 +1903,7 @@ describe('StreamingEngine', function() {
         failureCallback: function() {},
         bufferBehind: Infinity,
         ignoreTextStreamFailures: true,
+        alwaysStreamText: false,
         startAtSegmentBoundary: false,
         smallGapLimit: 0.5,
         jumpLargeGaps: false,
@@ -1940,6 +1942,7 @@ describe('StreamingEngine', function() {
         failureCallback: function() { streamingEngine.retry(); },  // retry
         bufferBehind: Infinity,
         ignoreTextStreamFailures: false,
+        alwaysStreamText: false,
         startAtSegmentBoundary: false,
         smallGapLimit: 0.5,
         jumpLargeGaps: false,
@@ -1985,6 +1988,7 @@ describe('StreamingEngine', function() {
         failureCallback: function() {},  // no retry
         bufferBehind: Infinity,
         ignoreTextStreamFailures: false,
+        alwaysStreamText: false,
         startAtSegmentBoundary: false,
         smallGapLimit: 0.5,
         jumpLargeGaps: false,
@@ -2032,6 +2036,7 @@ describe('StreamingEngine', function() {
         failureCallback: shaka.test.Util.spyFunc(failureCallback),
         bufferBehind: Infinity,
         ignoreTextStreamFailures: false,
+        alwaysStreamText: false,
         startAtSegmentBoundary: false,
         smallGapLimit: 0.5,
         jumpLargeGaps: false,
@@ -2085,6 +2090,7 @@ describe('StreamingEngine', function() {
         failureCallback: shaka.test.Util.spyFunc(failureCallback),
         bufferBehind: Infinity,
         ignoreTextStreamFailures: false,
+        alwaysStreamText: false,
         startAtSegmentBoundary: false,
         smallGapLimit: 0.5,
         jumpLargeGaps: false,
@@ -2244,6 +2250,7 @@ describe('StreamingEngine', function() {
         failureCallback: function() {},
         bufferBehind: 10,
         ignoreTextStreamFailures: false,
+        alwaysStreamText: false,
         startAtSegmentBoundary: false,
         smallGapLimit: 0.5,
         jumpLargeGaps: false,
@@ -2364,6 +2371,7 @@ describe('StreamingEngine', function() {
         failureCallback: function() {},
         bufferBehind: 10,
         ignoreTextStreamFailures: false,
+        alwaysStreamText: false,
         startAtSegmentBoundary: false,
         smallGapLimit: 0.5,
         jumpLargeGaps: false,
@@ -2435,6 +2443,7 @@ describe('StreamingEngine', function() {
         failureCallback: function() {},
         bufferBehind: 10,
         ignoreTextStreamFailures: false,
+        alwaysStreamText: false,
         startAtSegmentBoundary: false,
         smallGapLimit: 0.5,
         jumpLargeGaps: false,
@@ -2621,6 +2630,7 @@ describe('StreamingEngine', function() {
         failureCallback: function() {},
         bufferBehind: Infinity,
         ignoreTextStreamFailures: false,
+        alwaysStreamText: false,
         startAtSegmentBoundary: false,
         // Only buffer ahead 1 second to make it easier to set segment
         // expectations based on playheadTime.

test/player_unit.js

@@ -494,14 +494,33 @@ describe('Player', function() {
         player.load('', 0, factory1).then(function() {
           player.setTextTrackVisibility(true);
           expect(streamingEngine.loadNewTextStream).toHaveBeenCalled();
+          expect(streamingEngine.getActiveText()).not.toBe(null);
         }).catch(fail).then(done);
       });
 
-      it('do not load text stream if caption is invisible', function(done) {
+      it('does not load text stream if caption is invisible', function(done) {
         player.load('', 0, factory1).then(function() {
           player.setTextTrackVisibility(false);
           expect(streamingEngine.loadNewTextStream).not.toHaveBeenCalled();
           expect(streamingEngine.unloadTextStream).toHaveBeenCalled();
+          expect(streamingEngine.getActiveText()).toBe(null);
+        }).catch(fail).then(done);
+      });
+
+      it('loads text stream if alwaysStreamText is set', function(done) {
+        player.setTextTrackVisibility(false);
+        player.configure({streaming: {alwaysStreamText: true}});
+
+        player.load('', 0, factory1).then(function() {
+          expect(streamingEngine.getActiveText()).not.toBe(null);
+
+          player.setTextTrackVisibility(true);
+          expect(streamingEngine.loadNewTextStream).not.toHaveBeenCalled();
+          expect(streamingEngine.unloadTextStream).not.toHaveBeenCalled();
+
+          player.setTextTrackVisibility(false);
+          expect(streamingEngine.loadNewTextStream).not.toHaveBeenCalled();
+          expect(streamingEngine.unloadTextStream).not.toHaveBeenCalled();
         }).catch(fail).then(done);
       });
     });

test/test/util/simple_fakes.js

@@ -204,7 +204,13 @@ shaka.test.FakeStreamingEngine = function(onChooseStreams, onCanSwitch) {
   ret.getActiveAudio.and.callFake(function() { return activeAudio; });
   ret.getActiveVideo.and.callFake(function() { return activeVideo; });
   ret.getActiveText.and.callFake(function() { return activeText; });
-  ret.loadNewTextStream.and.callFake(resolve);
+  ret.loadNewTextStream.and.callFake(function(stream) {
+    activeText = stream;
+    return Promise.resolve();
+  });
+  ret.unloadTextStream.and.callFake(function() {
+    activeText = null;
+  });
   ret.init.and.callFake(function() {
     let chosen = onChooseStreams();
     return Promise.resolve().then(function() {