shaka-player 3.3.0 → 3.3.1

package/externs/cmcd.js

@@ -0,0 +1,186 @@
+/*! @license
+ * Shaka Player
+ * Copyright 2016 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Externs for CMCD data.
+ * @see https://github.com/google/shaka-player/issues/3619
+ * @see https://cdn.cta.tech/cta/media/media/resources/standards/pdfs/cta-5004-final.pdf
+ *
+ * @externs
+ */
+
+/**
+ * @typedef {{
+ *   br: (number|undefined),
+ *   d: (number|undefined),
+ *   ot: (string|undefined),
+ *   tb: (number|undefined),
+ *   bl: (number|undefined),
+ *   dl: (number|undefined),
+ *   mtp: (number|undefined),
+ *   nor: (string|undefined),
+ *   nrr: (string|undefined),
+ *   su: (boolean|undefined),
+ *   cid: (string|undefined),
+ *   pr: (number|undefined),
+ *   sf: (string|undefined),
+ *   sid: (string|undefined),
+ *   st: (string|undefined),
+ *   v: (number|undefined),
+ *   bs: (boolean|undefined),
+ *   rtp: (number|undefined)
+ * }}
+ *
+ * @description
+ *   Client Media Common Data (CMCD) data.
+ *
+ * @property {number} br
+ *   The encoded bitrate of the audio or video object being requested. This may
+ *   not be known precisely by the player; however, it MAY be estimated based
+ *   upon playlist/manifest declarations. If the playlist declares both peak and
+ *   average bitrate values, the peak value should be transmitted.
+ *
+ * @property {number} d
+ *   The playback duration in milliseconds of the object being requested. If a
+ *   partial segment is being requested, then this value MUST indicate the
+ *   playback duration of that part and not that of its parent segment. This
+ *   value can be an approximation of the estimated duration if the explicit
+ *   value is not known.
+ *
+ * @property {string} ot
+ *   The media type of the current object being requested:
+ *   - `m` = text file, such as a manifest or playlist
+ *   - `a` = audio only
+ *   - `v` = video only
+ *   - `av` = muxed audio and video
+ *   - `i` = init segment
+ *   - `c` = caption or subtitle
+ *   - `tt` = ISOBMFF timed text track
+ *   - `k` = cryptographic key, license or certificate.
+ *   - `o` = other
+ *
+ *   If the object type being requested is unknown, then this key MUST NOT be
+ *   used.
+ *
+ * @property {number} tb
+ *   The highest bitrate rendition in the manifest or playlist that the client
+ *   is allowed to play, given current codec, licensing and sizing constraints.
+ *
+ * @property {number} bl
+ *   The buffer length associated with the media object being requested. This
+ *   value MUST be rounded to the nearest 100 ms. This key SHOULD only be sent
+ *   with an object type of ‘a’, ‘v’ or ‘av’.
+ *
+ * @property {number} dl
+ *   Deadline from the request time until the first sample of this
+ *   Segment/Object needs to be available in order to not create a buffer
+ *   underrun or any other playback problems. This value MUST be rounded to the
+ *   nearest 100ms. For a playback rate of 1, this may be equivalent to the
+ *   player’s remaining buffer length.
+ *
+ * @property {number} mtp
+ *   The throughput between client and server, as measured by the client and
+ *   MUST be rounded to the nearest 100 kbps. This value, however derived,
+ *   SHOULD be the value that the client is using to make its next Adaptive
+ *   Bitrate switching decision. If the client is connected to multiple
+ *   servers concurrently, it must take care to report only the throughput
+ *   measured against the receiving server. If the client has multiple
+ *   concurrent connections to the server, then the intent is that this value
+ *   communicates the aggregate throughput the client sees across all those
+ *   connections.
+ *
+ * @property {string} nor
+ *   Relative path of the next object to be requested. This can be used to
+ *   trigger pre-fetching by the CDN. This MUST be a path relative to the
+ *   current request. This string MUST be URLEncoded. The client SHOULD NOT
+ *   depend upon any pre-fetch action being taken - it is merely a request for
+ *   such a pre-fetch to take place.
+ *
+ * @property {string} nrr
+ *   If the next request will be a partial object request, then this string
+ *   denotes the byte range to be requested. If the ‘nor’ field is not set, then
+ *   the object is assumed to match the object currently being requested. The
+ *   client SHOULD NOT depend upon any pre-fetch action being taken – it is
+ *   merely a request for such a pre-fetch to take place. Formatting is similar
+ *   to the HTTP Range header, except that the unit MUST be ‘byte’, the ‘Range:’
+ *   prefix is NOT required and specifying multiple ranges is NOT allowed. Valid
+ *   combinations are:
+ *
+ *   - `"\<range-start\>-"`
+ *   - `"\<range-start\>-\<range-end\>"`
+ *   - `"-\<suffix-length\>"`
+ *
+ * @property {boolean} su
+ *   Key is included without a value if the object is needed urgently due to
+ *   startup, seeking or recovery after a buffer-empty event. The media SHOULD
+ *   not be rendering when this request is made. This key MUST not be sent if it
+ *   is FALSE.
+ *
+ * @property {string} cid
+ *   A unique string identifying the current content. Maximum length is 64
+ *   characters. This value is consistent across multiple different sessions and
+ *   devices and is defined and updated at the discretion of the service
+ *   provider.
+ *
+ * @property {number} pr
+ *   The playback rate. `1` if real-time, `2` if double speed, `0` if not
+ *   playing. SHOULD only be sent if not equal to `1`.
+ *
+ * @property {string} sf
+ *   The streaming format that defines the current request.
+ *
+ *   - `d` = MPEG DASH
+ *   - `h` = HTTP Live Streaming (HLS)
+ *   - `s` = Smooth Streaming
+ *   - `o` = other
+ *
+ *   If the streaming format being requested is unknown, then this key MUST NOT
+ *   be used.
+ *
+ * @property {string} sid
+ *   A GUID identifying the current playback session. A playback session
+ *   typically ties together segments belonging to a single media asset. Maximum
+ *   length is 64 characters. It is RECOMMENDED to conform to the UUID
+ *   specification.
+ *
+ * @property {string} st
+ *   Stream type
+ *   - `v` = all segments are available – e.g., VOD
+ *   - `l` = segments become available over time – e.g., LIVE
+ *
+ * @property {number} v
+ *   The version of this specification used for interpreting the defined key
+ *   names and values. If this key is omitted, the client and server MUST
+ *   interpret the values as being defined by version 1. Client SHOULD omit this
+ *   field if the version is 1.
+ *
+ * @property {boolean} bs
+ *   Buffer starvation key is included without a value if the buffer was starved
+ *   at some point between the prior request and this object request, resulting
+ *   in the player being in a rebuffering state and the video or audio playback
+ *   being stalled. This key MUST NOT be sent if the buffer was not starved
+ *   since the prior request.
+ *
+ *   If the object type `ot` key is sent along with this key, then the `bs` key
+ *   refers to the buffer associated with the particular object type. If no
+ *   object type is communicated, then the buffer state applies to the current
+ *   session.
+ *
+ * @property {number} rtp
+ *   Requested maximum throughput
+ *
+ *   The requested maximum throughput that the client considers sufficient for
+ *   delivery of the asset. Values MUST be rounded to the nearest 100kbps. For
+ *   example, a client would indicate that the current segment, encoded at
+ *   2Mbps, is to be delivered at no more than 10Mbps, by using rtp=10000.
+ *
+ *   Note: This can benefit clients by preventing buffer saturation through
+ *   over-delivery and can also deliver a community benefit through fair-share
+ *   delivery. The concept is that each client receives the throughput necessary
+ *   for great performance, but no more. The CDN may not support the rtp
+ *   feature.
+ */
+var CmcdData;

package/externs/shaka/player.js

@@ -1207,6 +1207,8 @@ shaka.extern.LanguageRole;
 
 /**
  * @typedef {{
+ *   imageHeight: number,
+ *   imageWidth: number,
  *   height: number,
  *   positionX: number,
  *   positionY: number,
@@ -1216,6 +1218,12 @@ shaka.extern.LanguageRole;
  *   width: number
  * }}
  *
+ * @property {number} imageHeight
+ *    The image height in px. The image height could be different to height if
+ *    the layout is different to 1x1.
+ * @property {number} imageWidth
+ *    The image width in px. The image width could be different to width if
+ *    the layout is different to 1x1.
  * @property {number} height
  *    The thumbnail height in px.
  * @property {number} positionX

package/externs/shaka/text.js

@@ -363,6 +363,16 @@ shaka.extern.Cue = class {
      */
     this.nestedCues;
 
+    /**
+     * If true, this represents a container element that is "above" the main
+     * cues. For example, the <body> and <div> tags that contain the <p> tags
+     * in a TTML file. This controls the flow of the final cues; any nested cues
+     * within an "isContainer" cue will be laid out as separate lines.
+     * @type {boolean}
+     * @exportDoc
+     */
+    this.isContainer;
+
     /**
      * Whether or not the cue only acts as a line break between two nested cues.
      * Should only appear in nested cues.

package/lib/hls/hls_parser.js

@@ -1281,6 +1281,30 @@ shaka.hls.HlsParser = class {
     if (this.uriToStreamInfosMap_.has(verbatimImagePlaylistUri)) {
       return this.uriToStreamInfosMap_.get(verbatimImagePlaylistUri);
     }
+
+    // Parse misc attributes.
+    const resolution = tag.getAttributeValue('RESOLUTION');
+    if (resolution) {
+      // The RESOLUTION tag represents the resolution of a single thumbnail, not
+      // of the entire sheet at once (like we expect in the output).
+      // So multiply by the layout size.
+
+      const reference = streamInfo.stream.segmentIndex.get(0);
+      const layout = reference.getTilesLayout();
+      if (layout) {
+        streamInfo.stream.width =
+            Number(resolution.split('x')[0]) * Number(layout.split('x')[0]);
+        streamInfo.stream.height =
+            Number(resolution.split('x')[1]) * Number(layout.split('x')[1]);
+        // TODO: What happens if there are multiple grids, with different
+        // layout sizes, inside this image stream?
+      }
+    }
+    const bandwidth = tag.getAttributeValue('BANDWIDTH');
+    if (bandwidth) {
+      streamInfo.stream.bandwidth = Number(bandwidth);
+    }
+
     this.uriToStreamInfosMap_.set(verbatimImagePlaylistUri, streamInfo);
     return streamInfo;
   }
@@ -1814,6 +1838,7 @@ shaka.hls.HlsParser = class {
     }
 
     let tilesLayout = '';
+    let tileDuration = null;
     if (type == shaka.util.ManifestParserUtils.ContentType.IMAGE) {
       // By default in HLS the tilesLayout is 1x1
       tilesLayout = '1x1';
@@ -1821,6 +1846,10 @@ shaka.hls.HlsParser = class {
           shaka.hls.Utils.getFirstTagWithName(tags, 'EXT-X-TILES');
       if (tilesTag) {
         tilesLayout = tilesTag.getRequiredAttrValue('LAYOUT');
+        const duration = tilesTag.getAttributeValue('DURATION');
+        if (duration) {
+          tileDuration = Number(duration);
+        }
       }
     }
 
@@ -1836,6 +1865,7 @@ shaka.hls.HlsParser = class {
         /* appendWindowEnd= */ Infinity,
         partialSegmentRefs,
         tilesLayout,
+        tileDuration,
     );
   }
 

package/lib/media/segment_index.js

@@ -347,7 +347,8 @@ shaka.media.SegmentIndex = class {
             lastReference.appendWindowStart,
             lastReference.appendWindowEnd,
             lastReference.partialReferences,
-            lastReference.tilesLayout);
+            lastReference.tilesLayout,
+            lastReference.tileDuration);
   }
 
 

package/lib/media/segment_reference.js

@@ -155,11 +155,15 @@ shaka.media.SegmentReference = class {
    *   The value is a grid-item-dimension consisting of two positive decimal
    *   integers in the format: column-x-row ('4x3'). It describes the
    *   arrangement of Images in a Grid. The minimum valid LAYOUT is '1x1'.
+   * @param {?number=} tileDuration
+   *  The explicit duration of an individual tile within the tiles grid.
+   *  If not provided, the duration should be automatically calculated based on
+   *  the duration of the reference.
    */
   constructor(
       startTime, endTime, uris, startByte, endByte, initSegmentReference,
       timestampOffset, appendWindowStart, appendWindowEnd,
-      partialReferences = [], tilesLayout = '') {
+      partialReferences = [], tilesLayout = '', tileDuration = null) {
     // A preload hinted Partial Segment has the same startTime and endTime.
     goog.asserts.assert(startTime <= endTime,
         'startTime must be less than or equal to endTime');
@@ -206,6 +210,9 @@ shaka.media.SegmentReference = class {
 
     /** @type {?string} */
     this.tilesLayout = tilesLayout;
+
+    /** @type {?number} */
+    this.tileDuration = tileDuration;
   }
 
   /**
@@ -290,6 +297,17 @@ shaka.media.SegmentReference = class {
   getTilesLayout() {
     return this.tilesLayout;
   }
+
+  /**
+   * Returns the segment's explicit tile duration.
+   * Only defined in image segments.
+   *
+   * @return {?number}
+   * @export
+   */
+  getTileDuration() {
+    return this.tileDuration;
+  }
 };
 
 

package/lib/media/streaming_engine.js

@@ -628,7 +628,7 @@ shaka.media.StreamingEngine = class {
 
         // Don't clear the buffer unless something is buffered.  This extra
         // check prevents extra, useless calls to clear the buffer.
-        if (somethingBuffered) {
+        if (somethingBuffered || mediaState.performingUpdate) {
           this.forceClearBuffer_(mediaState);
           streamCleared = true;
         }
@@ -988,7 +988,10 @@ shaka.media.StreamingEngine = class {
         unscaledBufferingGoal * this.bufferingGoalScale_;
 
     // Check if we've buffered to the end of the presentation.
-    if (timeNeeded >= this.manifest_.presentationTimeline.getDuration()) {
+    const timeUntilEnd =
+        this.manifest_.presentationTimeline.getDuration() - timeNeeded;
+    const oneMicrosecond = 1e-6;
+    if (timeUntilEnd < oneMicrosecond) {
       // We shouldn't rebuffer if the playhead is close to the end of the
       // presentation.
       shaka.log.debug(logPrefix, 'buffered to end of presentation');

package/lib/player.js

@@ -2817,14 +2817,13 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    * @private
    */
   createCmcd_() {
-    const abr = this.abrManager_;
-
     /** @type {shaka.util.CmcdManager.PlayerInterface} */
     const playerInterface = {
-      getBandwidthEstimate: () => abr ? abr.getBandwidthEstimate() : NaN,
+      getBandwidthEstimate: () => this.abrManager_ ?
+        this.abrManager_.getBandwidthEstimate() : NaN,
       getBufferedInfo: () => this.getBufferedInfo(),
       getCurrentTime: () => this.video_ ? this.video_.currentTime : 0,
-      getManifest: () => this.manifest_,
+      getVariantTracks: () => this.getVariantTracks(),
       getPlaybackRate: () => this.getPlaybackRate(),
       isLive: () => this.isLive(),
     };
@@ -3613,7 +3612,8 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
       const height = fullImageHeight / rows;
       const totalImages = columns * rows;
       const segmentDuration = reference.trueEndTime - reference.startTime;
-      const thumbnailDuration = segmentDuration / totalImages;
+      const thumbnailDuration =
+          reference.getTileDuration() || (segmentDuration / totalImages);
       let thumbnailTime = reference.startTime;
       let positionX = 0;
       let positionY = 0;
@@ -3636,6 +3636,8 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
         positionY = Math.floor(thumbnailPosition / columns) * height;
       }
       return {
+        imageHeight: fullImageHeight,
+        imageWidth: fullImageWidth,
         height: height,
         positionX: positionX,
         positionY: positionY,
@@ -4037,20 +4039,24 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     const LanguageUtils = shaka.util.LanguageUtils;
     const inputlanguage = LanguageUtils.normalize(language);
     const chaptersTracks = this.getChaptersTracks_();
-    const chaptersTrack = chaptersTracks
-        .find((t) => LanguageUtils.normalize(t.language) == inputlanguage);
-    if (!chaptersTrack || !chaptersTrack.cues) {
+    const chaptersTracksWithLanguage = chaptersTracks
+        .filter((t) => LanguageUtils.normalize(t.language) == inputlanguage);
+    if (!chaptersTracksWithLanguage || !chaptersTracksWithLanguage.length) {
       return [];
     }
     const chapters = [];
-    for (const cue of chaptersTrack.cues) {
-      /** @type {shaka.extern.Chapter} */
-      const chapter = {
-        title: cue.text,
-        startTime: cue.startTime,
-        endTime: cue.endTime,
-      };
-      chapters.push(chapter);
+    for (const chaptersTrack of chaptersTracksWithLanguage) {
+      if (chaptersTrack && chaptersTrack.cues) {
+        for (const cue of chaptersTrack.cues) {
+          /** @type {shaka.extern.Chapter} */
+          const chapter = {
+            title: cue.text,
+            startTime: cue.startTime,
+            endTime: cue.endTime,
+          };
+          chapters.push(chapter);
+        }
+      }
     }
     return chapters;
   }
@@ -6530,7 +6536,7 @@ shaka.Player.TYPICAL_BUFFERING_THRESHOLD_ = 0.5;
  * @define {string} A version number taken from git at compile time.
  * @export
  */
-shaka.Player.version = 'v3.3.0-uncompiled';
+shaka.Player.version = 'v3.3.1-uncompiled';
 
 // Initialize the deprecation system using the version string we just set
 // on the player.

package/lib/polyfill/media_capabilities.js

@@ -24,8 +24,6 @@ shaka.polyfill.MediaCapabilities = class {
    * @export
    */
   static install() {
-    shaka.log.debug('MediaCapabilities: install');
-
     // Since MediaCapabilities is not fully supported on Chromecast yet, we
     // should always install polyfill for Chromecast.
     // TODO: re-evaluate MediaCapabilities in the future versions of Chromecast.
@@ -40,21 +38,28 @@ shaka.polyfill.MediaCapabilities = class {
     // TODO: re-evaluate MediaCapabilities in the future versions of PS5
     // Browsers.
     if (!shaka.util.Platform.isChromecast() &&
-      !shaka.util.Platform.isApple() &&
-      !shaka.util.Platform.isPS5() &&
-      navigator.mediaCapabilities) {
-      shaka.log.debug(
+        !shaka.util.Platform.isApple() &&
+        !shaka.util.Platform.isPS5() &&
+        navigator.mediaCapabilities) {
+      shaka.log.info(
           'MediaCapabilities: Native mediaCapabilities support found.');
-    } else {
-      if (!navigator.mediaCapabilities) {
-        navigator.mediaCapabilities = /** @type {!MediaCapabilities} */ ({});
-      }
-      navigator.mediaCapabilities.decodingInfo =
-          shaka.polyfill.MediaCapabilities.decodingInfo_;
+      return;
+    }
+
+    shaka.log.info('MediaCapabilities: install');
+
+    if (!navigator.mediaCapabilities) {
+      navigator.mediaCapabilities = /** @type {!MediaCapabilities} */ ({});
     }
-    // Workaround because in Apple browsers there is no way to overwrite
-    // MediaCapabilities.
-    window.shakaMediaCapabilities = navigator.mediaCapabilities;
+
+    // Keep the patched MediaCapabilities object from being garbage-collected in
+    // Safari.
+    // See https://github.com/google/shaka-player/issues/3696#issuecomment-1009472718
+    shaka.polyfill.MediaCapabilities.originalMcap =
+        navigator.mediaCapabilities;
+
+    navigator.mediaCapabilities.decodingInfo =
+        shaka.polyfill.MediaCapabilities.decodingInfo_;
   }
 
   /**
@@ -182,6 +187,16 @@ shaka.polyfill.MediaCapabilities = class {
   }
 };
 
+/**
+ * A copy of the MediaCapabilities instance, to prevent Safari from
+ * garbage-collecting the polyfilled method on it.  We make it public and export
+ * it to ensure that it is not stripped out by the compiler.
+ *
+ * @type {MediaCapabilities}
+ * @export
+ */
+shaka.polyfill.MediaCapabilities.originalMcap = null;
+
 // Install at a lower priority than MediaSource polyfill, so that we have
 // MediaSource available first.
 shaka.polyfill.register(shaka.polyfill.MediaCapabilities.install, -1);

package/lib/text/cue.js

@@ -222,6 +222,12 @@ shaka.text.Cue = class {
      */
     this.nestedCues = [];
 
+    /**
+     * @override
+     * @exportInterface
+     */
+    this.isContainer = false;
+
     /**
      * @override
      * @exportInterface