shaka-player 4.3.3 → 4.3.5

package/docs/tutorials/errors.md

@@ -0,0 +1,94 @@
+# Error Handling
+
+The basics for handling native Error and {@link shaka.util.Error} thrown by Shaka.
+
+## Listening To and Handling Errors
+
+```javascript
+const handleError = (error) => {
+  if (error instanceof Error) {
+    // shaka crashed with an unhandled native error
+  }
+
+  if (error.severity === shaka.util.Error.Severity.CRITICAL) {
+    // handle fatal error, playback can not continue
+  } else {
+    // handle non-fatal error, playback can continue
+  }
+};
+
+const player = new shaka.Player(video);
+
+// handle errors that occur after load
+player.addEventListener('error', handleError);
+
+// there are two options for catching errors that occur during load
+
+// it's possible to listen directly on the promise
+player.load(url).catch(handleError);
+
+// or to use async/await with a try/catch
+try {
+  await player.load(url);
+} catch (e) {
+  handleError(e);
+}
+```
+
+## Custom Handling of Streaming Errors
+
+The `streaming.failureCallback` property of {@link shaka.extern.PlayerConfiguration} can be used to add custom handling or error conversion of errors that occur during streaming.
+
+```javascript
+player.configure('streaming.failureCallback', (error) => {
+  if (error.severity === shaka.util.Error.Severity.CRITICAL) {
+    // custom handling of critical error
+    // e.g. player.retryStreaming();
+  } else {
+    // custom handling of recoverable error
+  }
+});
+```
+
+## Custom Handling of Retries
+
+When configuring retry parameters in Shaka there may be known error codes that should not be retried, or the need to break out of an infinite retry loop in a live context. Retries for failed network requests are not reported as `RECOVERABLE` errors.
+
+For example, if a VOD manifest is missing, unlike when a LIVE manifest is missing, it can be expected to not show up and there is no need to retry.
+
+This is how to convert a retry into a critical error, see {@link shaka.net.NetworkingEngine.RetryEvent} and {@link shaka.util.Error} to decipher how the event can be parsed:
+
+```javascript
+const nwEngine = player.getNetworkingEngine();
+
+const vodManifestNotFoundHandler = (event /* shaka.net.NetworkingEngine.RetryEvent */) => {
+  const code = event.error.code;
+  const data = event.error.data;
+
+  if (code === shaka.util.Error.Code.BAD_HTTP_STATUS) {
+    if (
+      // each type of error has its own data structure (or none at all), tread with care
+      Array.isArray(data) &&
+      data[1] === 404 &&
+      data[4] === shaka.net.NetworkingEngine.RequestType.MANIFEST
+    ) {
+      // Throwing inside a retry callback will immediately stop retries
+      throw error;
+
+      // A proprietary error code can also be thrown
+      // throw new shaka.util.Error(
+      //   shaka.util.Error.Severity.CRITICAL,
+      //   shaka.util.Error.Category.NETWORK,
+      //   'RECOGNIZABLE_ERROR_MESSAGE'
+      // );
+    }
+  }
+};
+
+nwEngine.addEventListener('retry', vodManifestNotFoundHandler);
+
+player.addEventListener('load'() => {
+  nwEngine.removeEventListener('retry', vodManifestNotFoundHandler);
+});
+
+```

package/docs/tutorials/fairplay.md

@@ -53,12 +53,12 @@ you.
 const req = await fetch('https://example.com/cert.der');
 const cert = await req.arrayBuffer();
 
-player.configure('drm.advanced.com\\.apple\\.fps\\.serverCertificate',
+player.configure('drm.advanced.com\\.apple\\.fps.serverCertificate',
                  new Uint8Array(cert));
 ```
 
 ```js
-player.configure('drm.advanced.com\\.apple\\.fps\\.serverCertificateUri',
+player.configure('drm.advanced.com\\.apple\\.fps.serverCertificateUri',
                  'https://example.com/cert.der');
 ```
 

package/docs/tutorials/index.json

@@ -9,6 +9,7 @@
   { "license-wrapping": { "title": "License Wrapping" } },
   { "ui": { "title": "UI Library" } },
   { "ui-customization": { "title": "Configuring the UI" } },
+  { "errors": { "title": "Error Handling" } },
   { "a11y": { "title": "Creating accessible buttons" } },
   { "ad_monetization": { "title": "Serving ads with our IMA SDK integration" } },
   { "plugins": { "title": "Plugins and Customizing the Build" } },
@@ -16,6 +17,7 @@
   { "architecture": { "title": "Architecture Diagrams" } },
   { "service-worker": { "title": "Service Worker Caching" } },
   { "offline": { "title": "Offline Storage and Playback" } },
+  { "widevine-service-certs": { "title": "Widevine Service Certificates" } },
   { "fairplay": { "title": "FairPlay support" } },
   { "application-level-redirects": { "title": "Application-Level Redirects" } },
   { "blob-url": { "title": "Blob URL" } },

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

@@ -0,0 +1,45 @@
+# 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',
+      },
+    },
+  },
+});
+```

package/externs/ima.js

@@ -513,6 +513,15 @@ google.ima.dai.api.StreamRequest.prototype.streamActivityMonitorId;
 google.ima.dai.api.StreamRequest.prototype.format;
 
 
+/**
+ * @enum {string}
+ */
+google.ima.dai.api.StreamRequest.StreamFormat = {
+  DASH: 'dash',
+  HLS: 'hls',
+};
+
+
 /** @const */
 google.ima.dai.api.VODStreamRequest =
     class extends google.ima.dai.api.StreamRequest {};

package/lib/ads/client_side_ad_manager.js

@@ -79,9 +79,9 @@ shaka.ads.ClientSideAdManager = class {
         });
 
     // Notify the SDK when the video has ended, so it can play post-roll ads.
-    this.video_.onended = () => {
+    this.eventManager_.listen(this.video_, 'ended', () => {
       this.adsLoader_.contentComplete();
-    };
+    });
   }
 
   /**
@@ -440,6 +440,7 @@ shaka.ads.ClientSideAdManager = class {
     if (this.ad_.isLinear()) {
       this.adContainer_.setAttribute('ad-active', 'true');
       this.video_.pause();
+      this.ad_.setVolume(this.video_.muted ? 0 : this.video_.volume);
     }
   }
 
@@ -452,7 +453,9 @@ shaka.ads.ClientSideAdManager = class {
         (new Map()).set('originalEvent', e)));
     if (this.ad_ && this.ad_.isLinear()) {
       this.adContainer_.removeAttribute('ad-active');
-      this.video_.play();
+      if (!this.video_.ended) {
+        this.video_.play();
+      }
     }
   }
 };

package/lib/dash/segment_template.js

@@ -102,11 +102,23 @@ shaka.dash.SegmentTemplate = class {
       const periodEnd = context.periodInfo.duration ?
           context.periodInfo.start + context.periodInfo.duration : Infinity;
 
-      // Don't fit live content, since it might receive more segments.
-      // Unless that live content is multi-period; it's safe to fit every period
-      // but the last one, since only the last period might receive new
-      // segments.
-      const shouldFit = periodEnd != Infinity;
+      /* When to fit segments.  All refactors should honor/update this table:
+       *
+       * | dynamic | infinite | last   | should | notes                     |
+       * |         | period   | period | fit    |                           |
+       * | ------- | -------- | ------ | ------ | ------------------------- |
+       * |     F   |     F    |    X   |    T   | typical VOD               |
+       * |     F   |     T    |    X   |    X   | impossible: infinite VOD  |
+       * |     T   |     F    |    F   |    T   | typical live, old period  |
+       * |     T   |     F    |    T   |    F   | typical IPR               |
+       * |     T   |     T    |    F   |    X   | impossible: old, infinite |
+       * |     T   |     T    |    T   |    F   | typical live, new period  |
+       */
+
+      // We never fit the final period of dynamic content, which could be
+      // infinite live (with no limit to fit to) or IPR (which would expand the
+      // most recent segment to the end of the presentation).
+      const shouldFit = !(context.dynamic && context.periodInfo.isLastPeriod);
 
       if (segmentIndex) {
         if (shouldFit) {

package/lib/hls/hls_parser.js

@@ -311,7 +311,10 @@ shaka.hls.HlsParser = class {
       const PresentationType = shaka.hls.HlsParser.PresentationType_;
       this.setPresentationType_(PresentationType.VOD);
 
-      const maxTimestamps = streamInfos.map((s) => s.maxTimestamp);
+      // The duration is the minimum of the end times of all active streams.
+      // Non-active streams are not guaranteed to have useful maxTimestamp
+      // values, due to the lazy-loading system, so they are ignored.
+      const maxTimestamps = activeStreamInfos.map((s) => s.maxTimestamp);
       // The duration is the minimum of the end times of all streams.
       this.presentationTimeline_.setDuration(Math.min(...maxTimestamps));
       this.playerInterface_.updateDuration();
@@ -945,6 +948,8 @@ shaka.hls.HlsParser = class {
       }
     });
 
+    const type = shaka.util.ManifestParserUtils.ContentType.TEXT;
+
     // Set the codecs for text streams.
     for (const tag of subtitleTags) {
       const groupId = tag.getRequiredAttrValue('GROUP-ID');
@@ -954,6 +959,9 @@ shaka.hls.HlsParser = class {
         if (textStreamInfos) {
           for (const textStreamInfo of textStreamInfos) {
             textStreamInfo.stream.codecs = codecs;
+            textStreamInfo.stream.mimeType =
+                this.guessMimeTypeBeforeLoading_(type, codecs) ||
+                this.guessMimeTypeFallback_(type);
           }
         }
       }
@@ -3312,6 +3320,7 @@ shaka.hls.HlsParser.AUDIO_EXTENSIONS_TO_MIME_TYPES_ = {
   'cmfa': 'audio/mp4',
   // MPEG2-TS also uses video/ for audio: https://bit.ly/TsMse
   'ts': 'video/mp2t',
+  'tsa': 'video/mp2t',
 };
 
 
@@ -3328,6 +3337,7 @@ shaka.hls.HlsParser.VIDEO_EXTENSIONS_TO_MIME_TYPES_ = {
   'm4f': 'video/mp4',
   'cmfv': 'video/mp4',
   'ts': 'video/mp2t',
+  'tsv': 'video/mp2t',
 };
 
 
@@ -3342,7 +3352,7 @@ shaka.hls.HlsParser.TEXT_EXTENSIONS_TO_MIME_TYPES_ = {
   'm4f': 'application/mp4',
   'cmft': 'application/mp4',
   'vtt': 'text/vtt',
-  'webvtt': 'txt/vtt',
+  'webvtt': 'text/vtt',
   'ttml': 'application/ttml+xml',
 };
 

package/lib/media/drm_engine.js

@@ -480,8 +480,10 @@ shaka.media.DrmEngine = class {
           () => this.closeOpenSessions_());
     }
 
-    const manifestInitData = this.currentDrmInfo_.initData.find(
-        (initDataOverride) => initDataOverride.initData.length > 0);
+    const manifestInitData = this.currentDrmInfo_ ?
+      this.currentDrmInfo_.initData.find(
+          (initDataOverride) => initDataOverride.initData.length > 0,
+      ) : null;
 
     /**
      * We can attach media keys before the playback actually begins when:

package/lib/media/transmuxer.js

@@ -35,9 +35,7 @@ shaka.media.Transmuxer = class {
     this.muxjs_ = shaka.dependencies.muxjs();
 
     /** @private {muxjs.mp4.Transmuxer} */
-    this.muxTransmuxer_ = new this.muxjs_.mp4.Transmuxer({
-      'keepOriginalTimestamps': true,
-    });
+    this.muxTransmuxer_ = null;
 
     /** @private {shaka.util.PublicPromise} */
     this.transmuxPromise_ = null;
@@ -51,16 +49,22 @@ shaka.media.Transmuxer = class {
     /** @private {boolean} */
     this.isTransmuxing_ = false;
 
-    this.muxTransmuxer_.on('data', (segment) => this.onTransmuxed_(segment));
-
-    this.muxTransmuxer_.on('done', () => this.onTransmuxDone_());
+    if (this.muxjs_) {
+      this.muxTransmuxer_ = new this.muxjs_.mp4.Transmuxer({
+        'keepOriginalTimestamps': true,
+      });
+      this.muxTransmuxer_.on('data', (segment) => this.onTransmuxed_(segment));
+      this.muxTransmuxer_.on('done', () => this.onTransmuxDone_());
+    }
   }
 
   /**
    * @override
    */
   destroy() {
-    this.muxTransmuxer_.dispose();
+    if (this.muxTransmuxer_) {
+      this.muxTransmuxer_.dispose();
+    }
     this.muxTransmuxer_ = null;
     return Promise.resolve();
   }
@@ -216,6 +220,8 @@ shaka.media.Transmuxer = class {
    *                     captions: !Array.<!muxjs.mp4.ClosedCaption>}>}
    */
   transmux(data) {
+    goog.asserts.assert(this.muxTransmuxer_,
+        'mux.js should be available.');
     goog.asserts.assert(!this.isTransmuxing_,
         'No transmuxing should be in progress.');
     this.isTransmuxing_ = true;

package/lib/media/video_wrapper.js

@@ -135,15 +135,15 @@ shaka.media.VideoWrapper = class {
     // calling |Player.load|, meaning that |currentTime| is more meaningful than
     // |startTime|.
     //
-    // Seeking to the current time is a work around for Issue 1298. If we don't
-    // do this, the video may get stuck and not play.
+    // Seeking to the current time is a work around for Issue 1298 and 4888.
+    // If we don't do this, the video may get stuck and not play.
     //
     // TODO: Need further investigation why it happens. Before and after
     // setting the current time, video.readyState is 1, video.paused is true,
     // and video.buffered's TimeRanges length is 0.
     // See: https://github.com/shaka-project/shaka-player/issues/1298
     this.mover_.moveTo(
-        this.video_.currentTime == 0 ?
+        (!this.video_.currentTime || this.video_.currentTime == 0) ?
         startTime :
         this.video_.currentTime);
   }

package/lib/offline/indexeddb/storage_mechanism.js

@@ -67,7 +67,7 @@ shaka.offline.indexeddb.StorageMechanism = class {
           shaka.util.Error.Category.STORAGE,
           shaka.util.Error.Code.INDEXED_DB_INIT_TIMED_OUT));
     });
-    timeOutTimer.tickAfter(2);
+    timeOutTimer.tickAfter(5);
 
     const open = window.indexedDB.open(name, version);
     open.onsuccess = (event) => {

package/lib/player.js

@@ -2584,6 +2584,8 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
               // goes wrong.
               new shaka.util.Timer(resolve).tickAfter(1);
             });
+          } else if (textTracks.length > 0) {
+            this.isTextVisible_ = true;
           }
 
           // If we have moved on to another piece of content while waiting for
@@ -6984,7 +6986,7 @@ shaka.Player.TYPICAL_BUFFERING_THRESHOLD_ = 0.5;
  * @define {string} A version number taken from git at compile time.
  * @export
  */
-shaka.Player.version = 'v4.3.3-uncompiled';
+shaka.Player.version = 'v4.3.5-uncompiled';
 
 // Initialize the deprecation system using the version string we just set
 // on the player.

package/lib/polyfill/media_capabilities.js

@@ -9,7 +9,6 @@ goog.provide('shaka.polyfill.MediaCapabilities');
 goog.require('shaka.log');
 goog.require('shaka.media.Capabilities');
 goog.require('shaka.polyfill');
-goog.require('shaka.util.Error');
 goog.require('shaka.util.Platform');
 
 
@@ -48,6 +47,8 @@ shaka.polyfill.MediaCapabilities = class {
     // should always install polyfill for WebOS browsers.
     // Since MediaCapabilities implementation is buggy in EOS browsers, we
     // should always install polyfill for EOS browsers.
+    // Since MediaCapabilities implementation is buggy in Hisense browsers, we
+    // should always install polyfill for Hisense browsers.
     let canUseNativeMCap = true;
     if (shaka.util.Platform.isApple() ||
         shaka.util.Platform.isPS5() ||
@@ -55,7 +56,8 @@ shaka.polyfill.MediaCapabilities = class {
         shaka.util.Platform.isWebOS() ||
         shaka.util.Platform.isTizen() ||
         shaka.util.Platform.isChromecast() ||
-        shaka.util.Platform.isEOS()) {
+        shaka.util.Platform.isEOS() ||
+        shaka.util.Platform.isHisense()) {
       canUseNativeMCap = false;
     }
     if (canUseNativeMCap && navigator.mediaCapabilities) {
@@ -227,13 +229,8 @@ shaka.polyfill.MediaCapabilities = class {
    * @private
    */
   static canCastDisplayType_(videoConfig) {
-    if (!(window.cast)) {
-      shaka.log.error('Expected cast namespace to be available!');
-      throw new shaka.util.Error(
-          shaka.util.Error.Severity.CRITICAL,
-          shaka.util.Error.Category.CAST,
-          shaka.util.Error.Code.CAST_API_UNAVAILABLE);
-    } else if (!(cast.__platform__ && cast.__platform__.canDisplayType)) {
+    if (!(window.cast &&
+        cast.__platform__ && cast.__platform__.canDisplayType)) {
       shaka.log.warning('Expected cast APIs to be available! Falling back to ' +
           'shaka.media.Capabilities.isTypeSupported() for type support.');
       return shaka.media.Capabilities.isTypeSupported(videoConfig.contentType);

package/lib/polyfill/mediasource.js

@@ -53,14 +53,19 @@ shaka.polyfill.MediaSource = class {
         // Offsetting the end of the removal range seems to help.
         // Bug filed: https://bugs.webkit.org/show_bug.cgi?id=177884
         shaka.polyfill.MediaSource.patchRemovalRange_();
-      } else {
-        shaka.log.info('Patching Safari 13 MSE bugs.');
+      } else if (safariVersion <= 15) {
+        shaka.log.info('Patching Safari 13 & 14 & 15 MSE bugs.');
         // Safari 13 does not correctly implement abort() on SourceBuffer.
         // Calling abort() before appending a segment causes that segment to be
         // incomplete in the buffer.
         // Bug filed: https://bugs.webkit.org/show_bug.cgi?id=165342
         shaka.polyfill.MediaSource.stubAbort_();
       }
+    } else if (shaka.util.Platform.isEdge()) {
+      shaka.log.info('Rejecting TS container.');
+      // TS content is broken on Edge in general.
+      // See https://github.com/shaka-project/shaka-player/issues/4955
+      shaka.polyfill.MediaSource.rejectContainer_('mp2t');
     } else if (shaka.util.Platform.isTizen2() ||
         shaka.util.Platform.isTizen3() ||
         shaka.util.Platform.isTizen4()) {
@@ -122,6 +127,23 @@ shaka.polyfill.MediaSource = class {
     };
   }
 
+  /**
+   * Patch |MediaSource.isTypeSupported| to always reject |container|. This is
+   * used when we know that we are on a platform that does not work well with
+   * a given container.
+   *
+   * @param {string} container
+   * @private
+   */
+  static rejectContainer_(container) {
+    const isTypeSupported = MediaSource.isTypeSupported;
+
+    MediaSource.isTypeSupported = (mimeType) => {
+      const actualContainer = shaka.util.MimeUtils.getContainerType(mimeType);
+      return actualContainer != container && isTypeSupported(mimeType);
+    };
+  }
+
   /**
    * Patch |MediaSource.isTypeSupported| to always reject |codec|. This is used
    * when we know that we are on a platform that does not work well with a given

package/lib/text/simple_text_displayer.js

@@ -14,6 +14,7 @@ goog.provide('shaka.text.SimpleTextDisplayer');
 goog.require('goog.asserts');
 goog.require('shaka.log');
 goog.require('shaka.text.Cue');
+goog.require('shaka.text.Utils');
 
 
 /**
@@ -79,70 +80,7 @@ shaka.text.SimpleTextDisplayer = class {
    * @export
    */
   append(cues) {
-    // Flatten nested cue payloads recursively.  If a cue has nested cues,
-    // their contents should be combined and replace the payload of the parent.
-    const flattenPayload = (cue) => {
-      // Handle styles (currently bold/italics/underline).
-      // TODO add support for color rendering.
-      const openStyleTags = [];
-      const bold = cue.fontWeight >= shaka.text.Cue.fontWeight.BOLD;
-      const italics = cue.fontStyle == shaka.text.Cue.fontStyle.ITALIC;
-      const underline = cue.textDecoration.includes(
-          shaka.text.Cue.textDecoration.UNDERLINE);
-      if (bold) {
-        openStyleTags.push('b');
-      }
-      if (italics) {
-        openStyleTags.push('i');
-      }
-      if (underline) {
-        openStyleTags.push('u');
-      }
-
-      // Prefix opens tags, suffix closes tags in reverse order of opening.
-      const prefixStyleTags = openStyleTags.reduce((acc, tag) => {
-        return `${acc}<${tag}>`;
-      }, '');
-      const suffixStyleTags = openStyleTags.reduceRight((acc, tag) => {
-        return `${acc}</${tag}>`;
-      }, '');
-
-      if (cue.lineBreak) {
-        // This is a vertical lineBreak, so insert a newline.
-        return '\n';
-      } else if (cue.nestedCues.length) {
-        return cue.nestedCues.map(flattenPayload).join('');
-      } else {
-        // This is a real cue.
-        return prefixStyleTags + cue.payload + suffixStyleTags;
-      }
-    };
-
-    // We don't want to modify the array or objects passed in, since we don't
-    // technically own them.  So we build a new array and replace certain items
-    // in it if they need to be flattened.
-    // We also don't want to flatten the text payloads starting at a container
-    // element; otherwise, for containers encapsulating multiple caption lines,
-    // the lines would merge into a single cue. This is undesirable when a
-    // subset of the captions are outside of the append time window. To fix
-    // this, we only call flattenPayload() starting at elements marked as
-    // isContainer = false.
-    const getCuesToFlatten = (cues, result) => {
-      for (const cue of cues) {
-        if (cue.isContainer) {
-          // Recurse to find the actual text payload cues.
-          getCuesToFlatten(cue.nestedCues, result);
-        } else {
-          // Flatten the payload.
-          const flatCue = cue.clone();
-          flatCue.nestedCues = [];
-          flatCue.payload = flattenPayload(cue);
-          result.push(flatCue);
-        }
-      }
-      return result;
-    };
-    const flattenedCues = getCuesToFlatten(cues, []);
+    const flattenedCues = shaka.text.Utils.getCuesToFlatten(cues, []);
 
     // Convert cues.
     const textTrackCues = [];

package/lib/text/text_utils.js

@@ -0,0 +1,88 @@
+/*! @license
+ * Shaka Player
+ * Copyright 2016 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+goog.provide('shaka.text.Utils');
+
+goog.require('shaka.text.Cue');
+
+
+shaka.text.Utils = class {
+  /**
+   * Flatten nested cue payloads recursively.  If a cue has nested cues,
+   * their contents should be combined and replace the payload of the parent.
+   *
+   * @param {!shaka.text.Cue} cue
+   * @return {string}
+   * @private
+   */
+  static flattenPayload_(cue) {
+    // Handle styles (currently bold/italics/underline).
+    // TODO: add support for color rendering.
+    const openStyleTags = [];
+    const bold = cue.fontWeight >= shaka.text.Cue.fontWeight.BOLD;
+    const italics = cue.fontStyle == shaka.text.Cue.fontStyle.ITALIC;
+    const underline = cue.textDecoration.includes(
+        shaka.text.Cue.textDecoration.UNDERLINE);
+    if (bold) {
+      openStyleTags.push('b');
+    }
+    if (italics) {
+      openStyleTags.push('i');
+    }
+    if (underline) {
+      openStyleTags.push('u');
+    }
+
+    // Prefix opens tags, suffix closes tags in reverse order of opening.
+    const prefixStyleTags = openStyleTags.reduce((acc, tag) => {
+      return `${acc}<${tag}>`;
+    }, '');
+    const suffixStyleTags = openStyleTags.reduceRight((acc, tag) => {
+      return `${acc}</${tag}>`;
+    }, '');
+
+    if (cue.lineBreak) {
+      // This is a vertical lineBreak, so insert a newline.
+      return '\n';
+    } else if (cue.nestedCues.length) {
+      return cue.nestedCues.map(shaka.text.Utils.flattenPayload_).join('');
+    } else {
+      // This is a real cue.
+      return prefixStyleTags + cue.payload + suffixStyleTags;
+    }
+  }
+
+  /**
+   * We don't want to modify the array or objects passed in, since we don't
+   * technically own them.  So we build a new array and replace certain items
+   * in it if they need to be flattened.
+   * We also don't want to flatten the text payloads starting at a container
+   * element; otherwise, for containers encapsulating multiple caption lines,
+   * the lines would merge into a single cue. This is undesirable when a
+   * subset of the captions are outside of the append time window. To fix
+   * this, we only call flattenPayload() starting at elements marked as
+   * isContainer = false.
+   *
+   * @param {!Array.<!shaka.text.Cue>} cues
+   * @param {!Array.<!shaka.text.Cue>} result
+   * @return {!Array.<!shaka.text.Cue>}
+   */
+  static getCuesToFlatten(cues, result) {
+    for (const cue of cues) {
+      if (cue.isContainer) {
+        // Recurse to find the actual text payload cues.
+        shaka.text.Utils.getCuesToFlatten(cue.nestedCues, result);
+      } else {
+        // Flatten the payload.
+        const flatCue = cue.clone();
+        flatCue.nestedCues = [];
+        flatCue.payload = shaka.text.Utils.flattenPayload_(cue);
+        result.push(flatCue);
+      }
+    }
+    return result;
+  }
+};