shaka-player 4.2.5 → 4.3.1

package/lib/player.js

@@ -8,6 +8,7 @@ goog.provide('shaka.Player');
 
 goog.require('goog.asserts');
 goog.require('shaka.Deprecate');
+goog.require('shaka.config.AutoShowText');
 goog.require('shaka.log');
 goog.require('shaka.media.AdaptationSetCriteria');
 goog.require('shaka.media.BufferingObserver');
@@ -17,7 +18,6 @@ goog.require('shaka.media.ManifestParser');
 goog.require('shaka.media.MediaSourceEngine');
 goog.require('shaka.media.MediaSourcePlayhead');
 goog.require('shaka.media.MetaSegmentIndex');
-goog.require('shaka.media.ClosedCaptionParser');
 goog.require('shaka.media.PlayRateController');
 goog.require('shaka.media.Playhead');
 goog.require('shaka.media.PlayheadObserverManager');
@@ -26,6 +26,7 @@ goog.require('shaka.media.QualityObserver');
 goog.require('shaka.media.RegionObserver');
 goog.require('shaka.media.RegionTimeline');
 goog.require('shaka.media.SegmentIndex');
+goog.require('shaka.media.SegmentReference');
 goog.require('shaka.media.SrcEqualsPlayhead');
 goog.require('shaka.media.StreamingEngine');
 goog.require('shaka.media.TimeRangesUtils');
@@ -55,7 +56,7 @@ goog.require('shaka.util.PublicPromise');
 goog.require('shaka.util.Stats');
 goog.require('shaka.util.StreamUtils');
 goog.require('shaka.util.Timer');
-goog.requireType('shaka.media.IClosedCaptionParser');
+goog.require('shaka.lcevc.Dil');
 goog.requireType('shaka.media.PresentationTimeline');
 goog.requireType('shaka.routing.Node');
 goog.requireType('shaka.routing.Payload');
@@ -325,7 +326,7 @@ goog.requireType('shaka.routing.Payload');
  *   the cue applies.
  * @property {string} metadataType
  *   Type of metadata. Eg: org.id3 or org.mp4ra
- * @property {shaka.extern.ID3Metadata} payload
+ * @property {shaka.extern.MetadataFrame} payload
  *   The metadata itself
  * @exportDoc
  */
@@ -367,6 +368,21 @@ goog.requireType('shaka.routing.Payload');
  */
 
 
+/**
+ * @event shaka.Player.SegmentAppended
+ * @description Fired when a segment is appended to the media element.
+ * @property {string} type
+ *   'segmentappended'
+ * @property {number} start
+ *   The start time of the segment.
+ * @property {number} end
+ *   The end time of the segment.
+ * @property {string} contentType
+ *   The content type of the segment. E.g. 'video', 'audio', or 'text'.
+ * @exportDoc
+ */
+
+
 /**
  * @event shaka.Player.SessionDataEvent
  * @description Fired when the manifest parser find info about session data.
@@ -505,6 +521,15 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     /** @private {shaka.util.CmcdManager} */
     this.cmcdManager_ = null;
 
+    // This is the canvas element that will be used for rendering LCEVC
+    // enhanced frames.
+    /** @private {?HTMLCanvasElement} */
+    this.lcevcCanvas_ = null;
+
+    // This is the LCEVC Dil object to decode LCEVC.
+    /** @private {?shaka.lcevc.Dil} */
+    this.lcevcDil_ = null;
+
     /** @private {shaka.media.QualityObserver} */
     this.qualityObserver_ = null;
 
@@ -523,6 +548,9 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     /** @private {?string} */
     this.assetUri_ = null;
 
+    /** @private {boolean} */
+    this.fullyLoaded_ = false;
+
     /** @private {shaka.extern.AbrManager} */
     this.abrManager_ = null;
 
@@ -726,6 +754,66 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     }
   }
 
+  /**
+   * Create a shaka.lcevc.Dil object
+   * @param {shaka.extern.LcevcConfiguration} config
+   * @private
+   */
+  createLcevcDil_(config) {
+    if (this.lcevcDil_ == null) {
+      this.lcevcDil_ = new shaka.lcevc.Dil(
+          /** @type {HTMLVideoElement} */ (this.video_),
+          this.lcevcCanvas_,
+          config,
+      );
+      if (this.mediaSourceEngine_) {
+        this.mediaSourceEngine_.updateLcevcDil(this.lcevcDil_);
+      }
+    }
+  }
+
+  /**
+   * Close a shaka.lcevc.Dil object if present and hide the canvas.
+   * @private
+   */
+  closeLcevcDil_() {
+    if (this.lcevcDil_ != null) {
+      this.lcevcDil_.release();
+      this.lcevcDil_ = null;
+    }
+  }
+
+  /**
+   * Setup shaka.lcevc.Dil object
+   * @param {?shaka.extern.PlayerConfiguration} config
+   * @private
+   */
+  setupLcevc_(config) {
+    if (config.lcevc.enabled) {
+      const tracks = this.getVariantTracks();
+      if (tracks && tracks[0] &&
+        tracks[0].videoMimeType ==
+        shaka.Player.SRC_EQUAL_EXTENSIONS_TO_MIME_TYPES_['ts']) {
+        const edge = shaka.util.Platform.isEdge() ||
+          shaka.util.Platform.isLegacyEdge();
+        if (edge) {
+          if (!config.streaming.forceTransmux) {
+            // If forceTransmux is disabled for Microsoft Edge, LCEVC data
+            // is stripped out in case of a MPEG-2 TS container.
+            // Hence the warning for Microsoft Edge when playing content with
+            // MPEG-2 TS container.
+            shaka.log.alwaysWarn('LCEVC Warning: For MPEG-2 TS decoding '+
+            'the config.streaming.forceTransmux must be enabled.');
+          }
+        }
+      }
+      this.closeLcevcDil_();
+      this.createLcevcDil_(config.lcevc);
+    } else {
+      this.closeLcevcDil_();
+    }
+  }
+
   /**
    * @param {!shaka.util.FakeEvent.EventName} name
    * @param {Map.<string, Object>=} data
@@ -748,6 +836,9 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
       return;
     }
 
+    // If LCEVC Dil exists close it.
+    this.closeLcevcDil_();
+
     // Mark as "dead". This should stop external-facing calls from changing our
     // internal state any more. This will stop calls to |attach|, |detach|, etc.
     // from interrupting our final move to the detached state.
@@ -985,6 +1076,18 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     return this.wrapWalkerListenersWithPromise_(events);
   }
 
+
+  /**
+   * Calling <code>attachCanvas</code> will tell the player to set canvas
+   * element for LCEVC decoding.
+   *
+   * @param {HTMLCanvasElement} canvas
+   * @export
+   */
+  attachCanvas(canvas) {
+    this.lcevcCanvas_ = canvas;
+  }
+
   /**
    * Tell the player to stop using its current media element. If the player is:
    * <ul>
@@ -1050,12 +1153,17 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
       return Promise.reject(this.createAbortLoadError_());
     }
 
+    this.fullyLoaded_ = false;
+
     // If the platform does not support media source, we will never want to
     // initialize media source.
     if (!shaka.util.Platform.supportsMediaSource()) {
       initializeMediaSource = false;
     }
 
+    // If LCEVC Dil exists close it.
+    this.closeLcevcDil_();
+
     // Since we are going either to attached or detached (through unloaded), we
     // can't allow it to be interrupted or else we could lose track of what
     // media element we are suppose to use.
@@ -1141,6 +1249,8 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
   load(assetUri, startTime, mimeType) {
     this.updatedStartTime_ = null;
 
+    this.fullyLoaded_ = false;
+
     // Do not allow the player to be used after |destroy| is called.
     if (this.loadMode_ == shaka.Player.LoadMode.DESTROYED) {
       return Promise.reject(this.createAbortLoadError_());
@@ -1578,8 +1688,6 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
         this.mediaSourceEngine_ == null,
         'We should not have a media source engine yet.');
 
-    const closedCaptionsParser = new shaka.media.ClosedCaptionParser();
-
     // When changing text visibility we need to update both the text displayer
     // and streaming engine because we don't always stream text. To ensure that
     // text displayer and streaming engine are always in sync, wait until they
@@ -1590,11 +1698,12 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
 
     const mediaSourceEngine = this.createMediaSourceEngine(
         has.mediaElement,
-        closedCaptionsParser,
         textDisplayer,
         (metadata, offset, endTime) => {
           this.processTimedMetadataMediaSrc_(metadata, offset, endTime);
-        });
+        },
+        this.lcevcDil_);
+    mediaSourceEngine.configure(this.config_.mediaSource);
     const {segmentRelativeVttTiming} = this.config_.manifest;
     mediaSourceEngine.setSegmentRelativeVttTiming(segmentRelativeVttTiming);
 
@@ -1775,6 +1884,15 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
           this.streamingEngine_.updateDuration();
         }
       },
+      newDrmInfo: (stream) => {
+        // We may need to create new sessions for any new init data.
+        const currentDrmInfo =
+            this.drmEngine_ ? this.drmEngine_.getDrmInfo() : null;
+        // DrmEngine.newInitData() requires mediaKeys to be available.
+        if (currentDrmInfo && this.drmEngine_.getMediaKeys()) {
+          this.processDrmInfos_(currentDrmInfo.keySystem, stream);
+        }
+      },
     };
 
     const startTime = Date.now() / 1000;
@@ -1865,6 +1983,15 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
           const now = Date.now() / 1000;
           const delta = now - startTime;
           this.stats_.setDrmTime(delta);
+          // LCEVC data by itself is not encrypted in DRM protected streams and
+          // can therefore be accessed and decoded as normal. However, the LCEVC
+          // decoder needs access to the VideoElement output in order to apply
+          // the enhancement. In DRM contexts where the browser CDM restricts
+          // access from our decoder, the enhancement cannot be applied and
+          // therefore the LCEVC output canvas is hidden accordingly.
+          if (this.lcevcDil_) {
+            this.lcevcDil_.hideCanvas();
+          }
         }
       },
     });
@@ -1949,6 +2076,10 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     this.loadEventManager_.listen(mediaElement, 'ended', updateStateHistory);
     this.loadEventManager_.listen(mediaElement, 'ratechange', onRateChange);
 
+    // Check status of the LCEVC DIL Object and reset or
+    // create or close based on config
+    this.setupLcevc_(this.config_);
+
     const abrFactory = this.config_.abrFactory;
     if (!this.abrManager_ || this.abrManagerFactory_ != abrFactory) {
       this.abrManagerFactory_ = abrFactory;
@@ -1983,16 +2114,6 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     });
     this.abrManager_.setMediaElement(mediaElement);
 
-    this.playhead_ = this.createPlayhead(has.startTime);
-    this.playheadObservers_ = this.createPlayheadObserversForMSE_();
-
-    // We need to start the buffer management code near the end because it will
-    // set the initial buffering state and that depends on other components
-    // being initialized.
-    const rebufferThreshold = Math.max(
-        this.manifest_.minBufferTime, this.config_.streaming.rebufferingGoal);
-    this.startBufferManagement_(rebufferThreshold);
-
     // If the content is multi-codec and the browser can play more than one of
     // them, choose codecs now before we initialize streaming.
     shaka.util.StreamUtils.chooseCodecsAndFilterManifest(
@@ -2036,14 +2157,42 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
         this.makeEvent_(shaka.util.FakeEvent.EventName.Streaming));
 
     // Pick the initial streams to play.
-    // however, we would skip switch to initial variant
-    // if user already pick variant track (via selectVariantTrack api)
+    // Unless the user has already picked a variant, anyway, by calling
+    // selectVariantTrack before this loading stage.
     let initialVariant = null;
-    const activeVariantTrack = this.getVariantTracks().find((t) => t.active);
-
-    if (!activeVariantTrack) {
+    const activeVariant = this.streamingEngine_.getCurrentVariant();
+    if (!activeVariant) {
       initialVariant = this.chooseVariant_();
       goog.asserts.assert(initialVariant, 'Must choose an initial variant!');
+    }
+
+    // Lazy-load the stream, so we will have enough info to make the playhead.
+    const createSegmentIndexPromises = [];
+    const toLazyLoad = activeVariant || initialVariant;
+    for (const stream of [toLazyLoad.video, toLazyLoad.audio]) {
+      if (stream && !stream.segmentIndex) {
+        createSegmentIndexPromises.push(stream.createSegmentIndex());
+      }
+    }
+    if (createSegmentIndexPromises.length > 0) {
+      await Promise.all(createSegmentIndexPromises);
+    }
+
+    this.playhead_ = this.createPlayhead(has.startTime);
+    this.playheadObservers_ = this.createPlayheadObserversForMSE_();
+
+    // We need to start the buffer management code near the end because it will
+    // set the initial buffering state and that depends on other components
+    // being initialized.
+    const rebufferThreshold = Math.max(
+        this.manifest_.minBufferTime, this.config_.streaming.rebufferingGoal);
+    this.startBufferManagement_(rebufferThreshold);
+
+    // Now we can switch to the initial variant.
+    if (!activeVariant) {
+      goog.asserts.assert(initialVariant,
+          'Must have choosen an initial variant!');
+
       this.switchVariant_(initialVariant, /* fromAdaptation= */ true,
           /* clearBuffer= */ false, /* safeMargin= */ 0);
 
@@ -2117,6 +2266,8 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
                         'arbitrary language initially');
     }
 
+    this.fullyLoaded_ = true;
+
     // Wait for the 'loadedmetadata' event to measure load() latency.
     this.loadEventManager_.listenOnce(mediaElement, 'loadedmetadata', () => {
       const now = Date.now() / 1000;
@@ -2463,6 +2614,8 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
           shaka.util.Error.Code.OPERATION_ABORTED);
       fullyLoaded.reject(abortedError);
       return Promise.resolve();  // Abort complete.
+    }).chain(() => {
+      this.fullyLoaded_ = true;
     });
   }
 
@@ -2575,11 +2728,15 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    */
   processTimedMetadataMediaSrc_(metadata, offset, segmentEndTime) {
     for (const sample of metadata) {
-      if (sample['data'] && sample['cueTime'] && sample['frames']) {
-        const start = sample['cueTime'] + offset;
-        const end = segmentEndTime;
-        const metadataType = 'ID3';
-        for (const frame of sample['frames']) {
+      if (sample.data && sample.cueTime && sample.frames) {
+        const start = sample.cueTime + offset;
+        let end = segmentEndTime;
+        // This can happen when the ID3 info arrives in a previous segment.
+        if (end && start > end) {
+          end = start;
+        }
+        const metadataType = 'org.id3';
+        for (const frame of sample.frames) {
           const payload = frame;
           this.dispatchMetadataEvent_(start, end, metadataType, payload);
         }
@@ -2598,7 +2755,7 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    * @param {number} startTime
    * @param {?number} endTime
    * @param {string} metadataType
-   * @param {shaka.extern.ID3Metadata} payload
+   * @param {shaka.extern.MetadataFrame} payload
    * @private
    */
   dispatchMetadataEvent_(startTime, endTime, metadataType, payload) {
@@ -2896,17 +3053,19 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    * way to inject fake media source engine instances.
    *
    * @param {!HTMLMediaElement} mediaElement
-   * @param {!shaka.media.IClosedCaptionParser} closedCaptionsParser
    * @param {!shaka.extern.TextDisplayer} textDisplayer
    * @param {!function(!Array.<shaka.extern.ID3Metadata>, number, ?number)}
    *  onMetadata
+   * @param {shaka.lcevc.Dil} lcevcDil
    *
    * @return {!shaka.media.MediaSourceEngine}
    */
-  createMediaSourceEngine(mediaElement, closedCaptionsParser, textDisplayer,
-      onMetadata) {
+  createMediaSourceEngine(mediaElement, textDisplayer, onMetadata, lcevcDil) {
     return new shaka.media.MediaSourceEngine(
-        mediaElement, closedCaptionsParser, textDisplayer, onMetadata);
+        mediaElement,
+        textDisplayer,
+        onMetadata,
+        lcevcDil);
   }
 
   /**
@@ -2937,13 +3096,13 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    */
   createStreamingEngine() {
     goog.asserts.assert(
-        this.playhead_ && this.abrManager_ && this.mediaSourceEngine_ &&
+        this.abrManager_ && this.mediaSourceEngine_ &&
         this.cmcdManager_ && this.manifest_,
         'Must not be destroyed');
 
     /** @type {shaka.media.StreamingEngine.PlayerInterface} */
     const playerInterface = {
-      getPresentationTime: () => this.playhead_.getTime(),
+      getPresentationTime: () => this.playhead_ ? this.playhead_.getTime() : 0,
       getBandwidthEstimate: () => this.abrManager_.getBandwidthEstimate(),
       modifySegmentRequest: (request, segmentInfo) => {
         this.cmcdManager_.applySegmentData(request, segmentInfo);
@@ -2953,7 +3112,9 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
       onError: (error) => this.onError_(error),
       onEvent: (event) => this.dispatchEvent(event),
       onManifestUpdate: () => this.onManifestUpdate_(),
-      onSegmentAppended: () => this.onSegmentAppended_(),
+      onSegmentAppended: (start, end, contentType) => {
+        this.onSegmentAppended_(start, end, contentType);
+      },
       onInitSegmentAppended: (position, initSegment) => {
         const mediaQuality = initSegment.getMediaQuality();
         if (mediaQuality && this.qualityObserver_) {
@@ -2963,6 +3124,9 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
       beforeAppendSegment: (contentType, segment) => {
         return this.drmEngine_.parseInbandPssh(contentType, segment);
       },
+      onMetadata: (metadata, offset, endTime) => {
+        this.processTimedMetadataMediaSrc_(metadata, offset, endTime);
+      },
     };
 
     return new shaka.media.StreamingEngine(this.manifest_, playerInterface);
@@ -3006,6 +3170,16 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
 
     goog.asserts.assert(typeof(config) == 'object', 'Should be an object!');
 
+    // Deprecate 'streaming.forceTransmuxTS' configuration.
+    if (config['streaming'] && 'forceTransmuxTS' in config['streaming']) {
+      shaka.Deprecate.deprecateFeature(5,
+          'streaming.forceTransmuxTS configuration',
+          'Please Use streaming.forceTransmux instead.');
+      config['streaming']['forceTransmux'] =
+          config['streaming']['forceTransmuxTS'];
+      delete config['streaming']['forceTransmuxTS'];
+    }
+
     // If lowLatencyMode is enabled, and inaccurateManifestTolerance and
     // rebufferingGoal are not specified, set inaccurateManifestTolerance to 0
     // and rebufferingGoal to 0.01 by default for low latency streaming.
@@ -3072,6 +3246,7 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     }
 
     if (this.mediaSourceEngine_) {
+      this.mediaSourceEngine_.configure(this.config_.mediaSource);
       const {segmentRelativeVttTiming} = this.config_.manifest;
       this.mediaSourceEngine_.setSegmentRelativeVttTiming(
           segmentRelativeVttTiming);
@@ -3359,6 +3534,10 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    * @export
    */
   seekRange() {
+    if (!this.fullyLoaded_) {
+      return {'start': 0, 'end': 0};
+    }
+
     if (this.manifest_) {
       const timeline = this.manifest_.presentationTimeline;
 
@@ -3701,8 +3880,8 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
       const fullImageHeight = imageStream.height || 0;
       const columns = parseInt(match[1], 10);
       const rows = parseInt(match[2], 10);
-      const width = fullImageWidth / columns;
-      const height = fullImageHeight / rows;
+      let width = fullImageWidth / columns;
+      let height = fullImageHeight / rows;
       const totalImages = columns * rows;
       const segmentDuration = reference.trueEndTime - reference.startTime;
       const thumbnailDuration =
@@ -3728,6 +3907,15 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
         positionX = (thumbnailPosition % columns) * width;
         positionY = Math.floor(thumbnailPosition / columns) * height;
       }
+      let sprite = false;
+      const thumbnailSprite = reference.getThumbnailSprite();
+      if (thumbnailSprite) {
+        sprite = true;
+        height = thumbnailSprite.height;
+        positionX = thumbnailSprite.positionX;
+        positionY = thumbnailSprite.positionY;
+        width = thumbnailSprite.width;
+      }
       return {
         imageHeight: fullImageHeight,
         imageWidth: fullImageWidth,
@@ -3738,6 +3926,7 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
         duration: thumbnailDuration,
         uris: reference.getUris(),
         width: width,
+        sprite: sprite,
       };
     }
     return null;
@@ -3921,20 +4110,21 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
 
   /**
    * Sets the current audio language and current variant role to the selected
-   * language and role, and chooses a new variant if need be. If the player has
-   * not loaded any content, this will be a no-op.
+   * language, role and channel count, and chooses a new variant if need be.
+   * If the player has not loaded any content, this will be a no-op.
    *
    * @param {string} language
    * @param {string=} role
+   * @param {number=} channelsCount
    * @export
    */
-  selectAudioLanguage(language, role) {
+  selectAudioLanguage(language, role, channelsCount = 0) {
     const LanguageUtils = shaka.util.LanguageUtils;
 
     if (this.manifest_ && this.playhead_) {
       this.currentAdaptationSetCriteria_ =
           new shaka.media.PreferenceBasedCriteria(language, role || '',
-          /* channelCount= */ 0, /* label= */ '');
+              channelsCount, /* label= */ '');
 
       const diff = (a, b) => {
         if (!a.video && !b.video) {
@@ -4613,6 +4803,146 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     return shaka.util.StreamUtils.textStreamToTrack(stream);
   }
 
+  /**
+   * Adds the given thumbnails track to the loaded manifest.
+   * <code>load()</code> must resolve before calling.  The presentation must
+   * have a duration.
+   *
+   * This returns the created track, which can immediately be used by the
+   * application.
+   *
+   * @param {string} uri
+   * @param {string=} mimeType
+   * @return {!Promise.<shaka.extern.Track>}
+   * @export
+   */
+  async addThumbnailsTrack(uri, mimeType) {
+    if (this.loadMode_ != shaka.Player.LoadMode.MEDIA_SOURCE &&
+        this.loadMode_ != shaka.Player.LoadMode.SRC_EQUALS) {
+      shaka.log.error(
+          'Must call load() and wait for it to resolve before adding image ' +
+          'tracks.');
+      throw new shaka.util.Error(
+          shaka.util.Error.Severity.RECOVERABLE,
+          shaka.util.Error.Category.PLAYER,
+          shaka.util.Error.Code.CONTENT_NOT_LOADED);
+    }
+
+    if (this.loadMode_ == shaka.Player.LoadMode.SRC_EQUALS) {
+      shaka.log.error('Cannot add this thumbnail track when loaded with src=');
+      throw new shaka.util.Error(
+          shaka.util.Error.Severity.RECOVERABLE,
+          shaka.util.Error.Category.TEXT,
+          shaka.util.Error.Code.CANNOT_ADD_EXTERNAL_THUMBNAILS_TO_SRC_EQUALS);
+    }
+
+    if (!mimeType) {
+      mimeType = await this.getTextMimetype_(uri);
+    }
+
+    if (mimeType != 'text/vtt') {
+      throw new shaka.util.Error(
+          shaka.util.Error.Severity.RECOVERABLE,
+          shaka.util.Error.Category.TEXT,
+          shaka.util.Error.Code.UNSUPPORTED_EXTERNAL_THUMBNAILS_URI,
+          uri);
+    }
+
+    const ContentType = shaka.util.ManifestParserUtils.ContentType;
+
+    const duration = this.manifest_.presentationTimeline.getDuration();
+    if (duration == Infinity) {
+      throw new shaka.util.Error(
+          shaka.util.Error.Severity.RECOVERABLE,
+          shaka.util.Error.Category.MANIFEST,
+          shaka.util.Error.Code.CANNOT_ADD_EXTERNAL_THUMBNAILS_TO_LIVE_STREAM);
+    }
+
+    goog.asserts.assert(
+        this.networkingEngine_, 'Need networking engine.');
+    const buffer = await this.getTextData_(uri,
+        this.networkingEngine_,
+        this.config_.streaming.retryParameters);
+
+    const factory = shaka.text.TextEngine.findParser(mimeType);
+    if (!factory) {
+      throw new shaka.util.Error(
+          shaka.util.Error.Severity.CRITICAL,
+          shaka.util.Error.Category.TEXT,
+          shaka.util.Error.Code.MISSING_TEXT_PLUGIN,
+          mimeType);
+    }
+    const TextParser = factory();
+    const time = {
+      periodStart: 0,
+      segmentStart: 0,
+      segmentEnd: duration,
+      vttOffset: 0,
+    };
+    const data = shaka.util.BufferUtils.toUint8(buffer);
+    const cues = TextParser.parseMedia(data, time);
+
+    const references = [];
+    for (const cue of cues) {
+      const imageUri = shaka.util.ManifestParserUtils.resolveUris(
+          [uri], [cue.payload])[0];
+      const reference = new shaka.media.SegmentReference(
+          cue.startTime,
+          cue.endTime,
+          () => [imageUri],
+          /* startByte= */ 0,
+          /* endByte= */ null,
+          /* initSegmentReference= */ null,
+          /* timestampOffset= */ 0,
+          /* appendWindowStart= */ 0,
+          /* appendWindowEnd= */ Infinity,
+      );
+      if (imageUri.includes('#xywh')) {
+        const spriteInfo = imageUri.split('#xywh=')[1].split(',');
+        if (spriteInfo.length === 4) {
+          reference.setThumbnailSprite({
+            height: parseInt(spriteInfo[3], 10),
+            positionX: parseInt(spriteInfo[0], 10),
+            positionY: parseInt(spriteInfo[1], 10),
+            width: parseInt(spriteInfo[2], 10),
+          });
+        }
+      }
+      references.push(reference);
+    }
+
+    /** @type {shaka.extern.Stream} */
+    const stream = {
+      id: this.nextExternalStreamId_++,
+      originalId: null,
+      createSegmentIndex: () => Promise.resolve(),
+      segmentIndex: new shaka.media.SegmentIndex(references),
+      mimeType: mimeType || '',
+      codecs: '',
+      kind: '',
+      encrypted: false,
+      drmInfos: [],
+      keyIds: new Set(),
+      language: 'und',
+      label: null,
+      type: ContentType.IMAGE,
+      primary: false,
+      trickModeVideo: null,
+      emsgSchemeIdUris: null,
+      roles: [],
+      forced: false,
+      channelsCount: null,
+      audioSamplingRate: null,
+      spatialAudio: false,
+      closedCaptions: null,
+      tilesLayout: '1x1',
+    };
+
+    this.manifest_.imageStreams.push(stream);
+    this.onTracksChanged_();
+    return shaka.util.StreamUtils.imageStreamToTrack(stream);
+  }
+
   /**
    * Adds the given chapters track to the loaded manifest.  <code>load()</code>
    * must resolve before calling.  The presentation must have a duration.
@@ -5084,28 +5414,39 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     }
 
     // We may need to create new sessions for any new init data.
-    const curDrmInfo = this.drmEngine_ ? this.drmEngine_.getDrmInfo() : null;
+    const currentDrmInfo =
+        this.drmEngine_ ? this.drmEngine_.getDrmInfo() : null;
     // DrmEngine.newInitData() requires mediaKeys to be available.
-    if (curDrmInfo && this.drmEngine_.getMediaKeys()) {
+    if (currentDrmInfo && this.drmEngine_.getMediaKeys()) {
       for (const variant of manifest.variants) {
-        const videoDrmInfos = variant.video ? variant.video.drmInfos : [];
-        const audioDrmInfos = variant.audio ? variant.audio.drmInfos : [];
-        const drmInfos = videoDrmInfos.concat(audioDrmInfos);
-        for (const drmInfo of drmInfos) {
-          // Ignore any data for different key systems.
-          if (drmInfo.keySystem == curDrmInfo.keySystem) {
-            for (const initData of (drmInfo.initData || [])) {
-              this.drmEngine_.newInitData(
-                  initData.initDataType, initData.initData);
-            }
-          }
-        }
+        this.processDrmInfos_(currentDrmInfo.keySystem, variant.video);
+        this.processDrmInfos_(currentDrmInfo.keySystem, variant.audio);
       }
     }
-
     this.checkRestrictedVariants_(manifest);
   }
 
+  /**
+   * @param {string} keySystem
+   * @param {?shaka.extern.Stream} stream
+   * @private
+   */
+  processDrmInfos_(keySystem, stream) {
+    if (!stream) {
+      return;
+    }
+
+    for (const drmInfo of stream.drmInfos) {
+      // Ignore any data for different key systems.
+      if (drmInfo.keySystem == keySystem) {
+        for (const initData of (drmInfo.initData || [])) {
+          this.drmEngine_.newInitData(
+              initData.initDataType, initData.initData);
+        }
+      }
+    }
+  }
+
   /**
    * @private
    */
@@ -5481,38 +5822,62 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
   /**
    * Check if we should show text on screen automatically.
    *
-   * The text should automatically be shown if the text is language-compatible
-   * with the user's text language preference, but not compatible with the
-   * audio.
-   *
-   * For example:
-   *   preferred | chosen | chosen |
-   *   text      | text   | audio  | show
-   *   -----------------------------------
-   *   en-CA     | en     | jp     | true
-   *   en        | en-US  | fr     | true
-   *   fr-CA     | en-US  | jp     | false
-   *   en-CA     | en-US  | en-US  | false
-   *
    * @param {shaka.extern.Stream} audioStream
    * @param {shaka.extern.Stream} textStream
    * @return {boolean}
    * @private
    */
   shouldInitiallyShowText_(audioStream, textStream) {
+    const AutoShowText = shaka.config.AutoShowText;
+
+    if (this.config_.autoShowText == AutoShowText.NEVER) {
+      return false;
+    }
+    if (this.config_.autoShowText == AutoShowText.ALWAYS) {
+      return true;
+    }
+
     const LanguageUtils = shaka.util.LanguageUtils;
 
     /** @type {string} */
     const preferredTextLocale =
         LanguageUtils.normalize(this.config_.preferredTextLanguage);
     /** @type {string} */
-    const audioLocale = LanguageUtils.normalize(audioStream.language);
-    /** @type {string} */
     const textLocale = LanguageUtils.normalize(textStream.language);
 
-    return (
-      LanguageUtils.areLanguageCompatible(textLocale, preferredTextLocale) &&
-      !LanguageUtils.areLanguageCompatible(audioLocale, textLocale));
+    if (this.config_.autoShowText == AutoShowText.IF_PREFERRED_TEXT_LANGUAGE) {
+      // Only the text language match matters.
+      return LanguageUtils.areLanguageCompatible(
+          textLocale,
+          preferredTextLocale);
+    }
+
+    if (this.config_.autoShowText == AutoShowText.IF_SUBTITLES_MAY_BE_NEEDED) {
+      /* The text should automatically be shown if the text is
+       * language-compatible with the user's text language preference, but not
+       * compatible with the audio.  These are cases where we deduce that
+       * subtitles may be needed.
+       *
+       * For example:
+       *   preferred | chosen | chosen |
+       *   text      | text   | audio  | show
+       *   -----------------------------------
+       *   en-CA     | en     | jp     | true
+       *   en        | en-US  | fr     | true
+       *   fr-CA     | en-US  | jp     | false
+       *   en-CA     | en-US  | en-US  | false
+       *
+       */
+      /** @type {string} */
+      const audioLocale = LanguageUtils.normalize(audioStream.language);
+
+      return (
+        LanguageUtils.areLanguageCompatible(textLocale, preferredTextLocale) &&
+        !LanguageUtils.areLanguageCompatible(audioLocale, textLocale));
+    }
+
+    shaka.log.alwaysWarn('Invalid autoShowText setting!');
+    return false;
   }
 
   /**
@@ -5531,7 +5896,7 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    *
    * @private
    */
-  onSegmentAppended_() {
+  onSegmentAppended_(start, end, contentType) {
     // When we append a segment to media source (via streaming engine) we are
     // changing what data we have buffered, so notify the playhead of the
     // change.
@@ -5539,6 +5904,14 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
       this.playhead_.notifyOfBufferingChange();
     }
     this.pollBufferState_();
+
+    // Dispatch an event for users to consume, too.
+    const data = new Map()
+        .set('start', start)
+        .set('end', end)
+        .set('contentType', contentType);
+    this.dispatchEvent(this.makeEvent_(
+        shaka.util.FakeEvent.EventName.SegmentAppended, data));
   }
 
   /**
@@ -5584,6 +5957,9 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     const data = new Map()
         .set('oldTrack', from)
         .set('newTrack', to);
+    if (this.lcevcDil_) {
+      this.lcevcDil_.updateVariant(to);
+    }
     const event =
         this.makeEvent_(shaka.util.FakeEvent.EventName.Adaptation, data);
     this.delayDispatchEvent_(event);
@@ -5612,6 +5988,10 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     const data = new Map()
         .set('oldTrack', from)
         .set('newTrack', to);
+    if (this.lcevcDil_) {
+      this.lcevcDil_.updateVariant(to);
+    }
+
     const event =
         this.makeEvent_(shaka.util.FakeEvent.EventName.VariantChanged, data);
     this.delayDispatchEvent_(event);
@@ -6556,7 +6936,6 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
   }
 };
 
-
 /**
  * In order to know what method of loading the player used for some content, we
  * have this enum. It lets us know if content has not been loaded, loaded with
@@ -6595,7 +6974,7 @@ shaka.Player.TYPICAL_BUFFERING_THRESHOLD_ = 0.5;
  * @define {string} A version number taken from git at compile time.
  * @export
  */
-shaka.Player.version = 'v4.2.5-uncompiled';
+shaka.Player.version = 'v4.3.1-uncompiled';
 
 // Initialize the deprecation system using the version string we just set
 // on the player.