shaka-player 3.3.17 → 3.3.19

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

@@ -25,14 +25,14 @@ is used by the browser to generate the license request.  If you don't use the
 default content ID derivation, you need to specify a custom init data transform:
 
 ```js
-player.configure('drm.initDataTransform', (initData, initDataType) => {
+player.configure('drm.initDataTransform', (initData, initDataType, drmInfo) => {
   if (initDataType != 'skd')
     return initData;
 
   // 'initData' is a buffer containing an 'skd://' URL as a UTF-8 string.
   const skdUri = shaka.util.StringUtils.fromBytesAutoDetect(initData);
   const contentId = getMyContentId(skdUri);
-  const cert = player.drmInfo().serverCertificate;
+  const cert = drmInfo.serverCertificate;
   return shaka.util.FairPlayUtils.initDataTransform(initData, contentId, cert);
 });
 ```

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

@@ -501,6 +501,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/externs/shaka/net.js

@@ -100,6 +100,7 @@ shaka.extern.Request;
 /**
  * @typedef {{
  *   uri: string,
+ *   originalUri: string,
  *   data: BufferSource,
  *   status: (number|undefined),
  *   headers: !Object.<string, string>,

package/externs/shaka/player.js

@@ -613,9 +613,7 @@ shaka.extern.AdvancedDrmConfiguration;
  *   clearKeys: !Object.<string, string>,
  *   delayLicenseRequestUntilPlayed: boolean,
  *   advanced: Object.<string, shaka.extern.AdvancedDrmConfiguration>,
- *   initDataTransform:
- *       ((function(!Uint8Array, string, ?shaka.extern.DrmInfo):!Uint8Array)|
- *         undefined),
+ *   initDataTransform:(shaka.extern.InitDataTransform|undefined),
  *   logLicenseExchange: boolean,
  *   updateExpirationTime: number,
  *   preferredKeySystems: !Array.<string>
@@ -639,10 +637,7 @@ shaka.extern.AdvancedDrmConfiguration;
  *   <i>Optional.</i> <br>
  *   A dictionary which maps key system IDs to advanced DRM configuration for
  *   those key systems.
- * @property
- *     {((function(!Uint8Array, string, ?shaka.extern.DrmInfo):!Uint8Array)|
- *        undefined)}
- *   initDataTransform
+ * @property {shaka.extern.InitDataTransform|undefined} initDataTransform
  *   <i>Optional.</i><br>
  *   If given, this function is called with the init data from the
  *   manifest/media and should return the (possibly transformed) init data to
@@ -664,6 +659,17 @@ shaka.extern.AdvancedDrmConfiguration;
  */
 shaka.extern.DrmConfiguration;
 
+/**
+ * @typedef {function(!Uint8Array, string, ?shaka.extern.DrmInfo):!Uint8Array}
+ *
+ * @description
+ * A callback function to handle custom content ID signaling for FairPlay
+ * content.
+ *
+ * @exportDoc
+ */
+shaka.extern.InitDataTransform;
+
 
 /**
  * @typedef {{

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();
-    };
+    });
   }
 
   /**
@@ -212,9 +212,9 @@ shaka.ads.ClientSideAdManager = class {
       // seen the ads actually play until requestAds() is called.
       // Note: We listen for a play event to avoid autoplay issues that might
       // crash IMA.
-      this.video_.addEventListener('play', () => {
+      this.eventManager_.listenOnce(this.video_, 'play', () => {
         this.imaAdsManager_.start();
-      }, {once: true});
+      });
     } catch (adError) {
       // If there was a problem with the VAST response,
       // we we won't be getting an ad. Hide ad UI if we showed it already
@@ -402,6 +402,10 @@ shaka.ads.ClientSideAdManager = class {
     if (this.ad_.isLinear()) {
       this.adContainer_.setAttribute('ad-active', 'true');
       this.video_.pause();
+      this.ad_.setVolume(this.video_.volume);
+      if (this.video_.muted) {
+        this.ad_.setMuted(true);
+      }
     }
   }
 
@@ -414,7 +418,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/dash_parser.js

@@ -1278,55 +1278,56 @@ shaka.dash.DashParser = class {
         context.period.id + ',' + context.representation.id : '';
 
     /** @type {shaka.extern.Stream} */
-    const stream = {
-      id: this.globalId_++,
-      originalId: context.representation.id,
-      createSegmentIndex: async () => {
-        // If we have a stream with the same context id stored in the map
-        // that has no segmentIndex, we should set the segmentIndex for it.
-        const storedInMap = contextId && context.dynamic &&
-              this.streamMap_[contextId];
-
-        const currentStream = storedInMap ? this.streamMap_[contextId] : stream;
-        if (!currentStream.segmentIndex) {
-          currentStream.segmentIndex = await streamInfo.generateSegmentIndex();
-        }
-      },
+    let stream;
 
-      closeSegmentIndex: () => {
-        if (stream.segmentIndex) {
-          stream.segmentIndex.release();
-          stream.segmentIndex = null;
-        }
-      },
-      segmentIndex: null,
-      mimeType: context.representation.mimeType,
-      codecs: context.representation.codecs,
-      frameRate: context.representation.frameRate,
-      pixelAspectRatio: context.representation.pixelAspectRatio,
-      bandwidth: context.bandwidth,
-      width: context.representation.width,
-      height: context.representation.height,
-      kind,
-      encrypted: contentProtection.drmInfos.length > 0,
-      drmInfos: contentProtection.drmInfos,
-      keyIds,
-      language,
-      label,
-      type: context.adaptationSet.contentType,
-      primary: isPrimary,
-      trickModeVideo: null,
-      emsgSchemeIdUris:
-          context.representation.emsgSchemeIdUris,
-      roles,
-      forced: forced,
-      channelsCount: context.representation.numChannels,
-      audioSamplingRate: context.representation.audioSamplingRate,
-      spatialAudio: spatialAudio,
-      closedCaptions,
-      hdr,
-      tilesLayout,
-      matchedStreams: [],
+    if (contextId && this.streamMap_[contextId]) {
+      stream = this.streamMap_[contextId];
+    } else {
+      stream = {
+        id: this.globalId_++,
+        originalId: context.representation.id,
+        createSegmentIndex: () => Promise.resolve(),
+        closeSegmentIndex: () => {
+          if (stream.segmentIndex) {
+            stream.segmentIndex.release();
+            stream.segmentIndex = null;
+          }
+        },
+        segmentIndex: null,
+        mimeType: context.representation.mimeType,
+        codecs: context.representation.codecs,
+        frameRate: context.representation.frameRate,
+        pixelAspectRatio: context.representation.pixelAspectRatio,
+        bandwidth: context.bandwidth,
+        width: context.representation.width,
+        height: context.representation.height,
+        kind,
+        encrypted: contentProtection.drmInfos.length > 0,
+        drmInfos: contentProtection.drmInfos,
+        keyIds,
+        language,
+        label,
+        type: context.adaptationSet.contentType,
+        primary: isPrimary,
+        trickModeVideo: null,
+        emsgSchemeIdUris:
+            context.representation.emsgSchemeIdUris,
+        roles,
+        forced,
+        channelsCount: context.representation.numChannels,
+        audioSamplingRate: context.representation.audioSamplingRate,
+        spatialAudio,
+        closedCaptions,
+        hdr,
+        tilesLayout,
+        matchedStreams: [],
+      };
+    }
+
+    stream.createSegmentIndex = async () => {
+      if (!stream.segmentIndex) {
+        stream.segmentIndex = await streamInfo.generateSegmentIndex();
+      }
     };
 
     if (contextId && context.dynamic && !this.streamMap_[contextId]) {

package/lib/hls/hls_parser.js

@@ -2990,6 +2990,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',
 
   // Raw formats:
   'aac': 'audio/aac',
@@ -3027,6 +3028,7 @@ shaka.hls.HlsParser.VIDEO_EXTENSIONS_TO_MIME_TYPES_ = {
   'm4f': 'video/mp4',
   'cmfv': 'video/mp4',
   'ts': 'video/mp2t',
+  'tsv': 'video/mp2t',
 };
 
 

package/lib/media/media_source_engine.js

@@ -182,6 +182,9 @@ shaka.media.MediaSourceEngine = class {
       'audio/mp4; codecs="ec-3"',
       'audio/mp4; codecs="opus"',
       'audio/mp4; codecs="flac"',
+      'audio/mp4; codecs="dtsc"', // DTS Digital Surround
+      'audio/mp4; codecs="dtse"', // DTS Express
+      'audio/mp4; codecs="dtsx"', // DTS:X
       // WebM types
       'video/webm; codecs="vp8"',
       'video/webm; codecs="vp9"',
@@ -515,7 +518,7 @@ shaka.media.MediaSourceEngine = class {
       // For HLS CEA-608/708 CLOSED-CAPTIONS, text data is embedded in
       // the video stream, so textEngine may not have been initialized.
       if (!this.textEngine_) {
-        this.reinitText('text/vtt');
+        this.reinitText(shaka.util.MimeUtils.CEA608_CLOSED_CAPTION_MIMETYPE);
       }
 
       if (transmuxedData.metadata) {
@@ -542,7 +545,7 @@ shaka.media.MediaSourceEngine = class {
           contentType, () => this.append_(contentType, transmuxedSegment));
     } else if (hasClosedCaptions) {
       if (!this.textEngine_) {
-        this.reinitText('text/vtt');
+        this.reinitText(shaka.util.MimeUtils.CEA608_CLOSED_CAPTION_MIMETYPE);
       }
       // If it is the init segment for closed captions, initialize the closed
       // caption parser.
@@ -711,8 +714,10 @@ shaka.media.MediaSourceEngine = class {
   async endOfStream(reason) {
     await this.enqueueBlockingOperation_(() => {
       // If endOfStream() has already been called on the media source,
-      // don't call it again.
-      if (this.ended()) {
+      // don't call it again. Also do not call if readyState is
+      // 'closed' (not attached to video element) since it is not a
+      // valid operation.
+      if (this.ended() || this.mediaSource_.readyState === 'closed') {
         return;
       }
       // Tizen won't let us pass undefined, but it will let us omit the

package/lib/media/streaming_engine.js

@@ -77,6 +77,9 @@ shaka.media.StreamingEngine = class {
     /** @private {?shaka.extern.Stream} */
     this.currentTextStream_ = null;
 
+    /** @private {number} */
+    this.textStreamSequenceId_ = 0;
+
     /**
      * Maps a content type, e.g., 'audio', 'video', or 'text', to a MediaState.
      *
@@ -220,6 +223,8 @@ shaka.media.StreamingEngine = class {
     const ContentType = shaka.util.ManifestParserUtils.ContentType;
     goog.asserts.assert(!this.mediaStates_.has(ContentType.TEXT),
         'Should not call loadNewTextStream_ while streaming text!');
+    this.textStreamSequenceId_++;
+    const currentSequenceId = this.textStreamSequenceId_;
 
     try {
       // Clear MediaSource's buffered text, so that the new text stream will
@@ -241,7 +246,7 @@ shaka.media.StreamingEngine = class {
     const streamText =
         textDisplayer.isTextVisible() || this.config_.alwaysStreamText;
 
-    if (streamText) {
+    if (streamText && (this.textStreamSequenceId_ == currentSequenceId)) {
       const state = this.createMediaState_(stream);
       this.mediaStates_.set(ContentType.TEXT, state);
       this.scheduleUpdate_(state, 0);
@@ -1488,10 +1493,10 @@ shaka.media.StreamingEngine = class {
           'waiting for another stream to recover...');
     }
 
-    // QuotaExceededError gets thrown if evication didn't help to make room
+    // QuotaExceededError gets thrown if eviction didn't help to make room
     // for a segment. We want to wait for a while (4 seconds is just an
     // arbitrary number) before updating to give the playhead a chance to
-    // advance, so we don't immidiately throw again.
+    // advance, so we don't immediately throw again.
     this.scheduleUpdate_(mediaState, 4);
   }
 

package/lib/media/transmuxer.js

@@ -29,9 +29,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;
@@ -48,16 +46,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();
   }
@@ -156,6 +160,8 @@ shaka.media.Transmuxer = class {
    *                     metadata: !Array.<!Object>}>}
    */
   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);
   }