shaka-player 4.2.4 → 4.3.0

package/docs/design/lcevc-integration.md

@@ -0,0 +1,72 @@
+
+# Shaka Player LCEVC integration
+
+# Introduction
+
+This article describes the V-Nova LCEVC Shaka Player integration.
+
+# LCEVC Integration
+
+## Adding V-Nova required files
+### Importing DIL - Decoder Integration Layer
+
+V-Nova LCEVC DIL Libraries are included using the same approach that the other external libraries are currently using. The necessary V-Nova LCEVC DIL files need to be imported in the HTML page that is going to be used by Shaka Player to decode LCEVC. Checks are inplace that make sure the necessary objects are available.
+
+Npm package : <https://www.npmjs.com/package/lcevc_dil.js>
+
+```javascript
+  <!-- MPEG-5 Part2 LCEVC support is enabled by including this: -->
+  <script defer src="../node_modules/lcevc_dil.js/dist/lcevc_dil.min.js"></script>
+```
+
+To allow the Closure compiler to use the objects and methods that are exported by the DIL.js a new `extern` is created.
+
+### Defining an Extern for LCEVC
+
+`externs/lcevc.js` exposes the functions from the LCEVC DIL library required for LCEVC Decoding.
+
+## Integration point
+
+### The shaka.lcevc.Dil class - (DIL : Decoder Integration Layer)
+
+The main logic of the LCEVC integration is located in the `lib/lcevc_dil.min.js` file. In this file the shaka.lcevc.Dil is exported to be used in the project. This class is in charge of creating the Dil object using the mentioned externs, checking if LCEVC DIL library is available, etc.
+
+### Modifications in the player
+
+The shaka.Player class, defined in the `lib/player.js` file, is the main player object for Shaka Player. There is a setter function for setting up a `canvas` element that is received from the user.
+If shaka.ui is used the `canvas` is created in line with the video element in the same container overlaying the video element. If user provides a custom canvas using the setter function, The user is responsible for placing the canvas element in the desired position and resizing it.
+
+`shaka.externs.LcevcConfiguration` is added to the `playerConfiguration` that is used as configuration for the LCEVC DIL Library.
+
+The Dil object is created in the `onLoad_()` event that is triggered when a new video is loaded in Shaka Player. Attaching to a media element is defined as:
+
+-   Registering error listeners to the media element.
+-   Catching the video element for use outside of the load graph.
+
+The Dil object is created only if LCEVC is supported (LCEVC libs are loaded on the page) and also when it was not already created in another `onLoad_()` event execution.
+
+
+### Feeding the Dil
+
+The logic that Shaka Player uses to communicate with the Media Source Extensions (MSE) is located in the `media/media_source_engine.js` file.
+
+![image.png](lcevc-architecture.png)
+
+ `append_()` function that is used to feed the MSE Source Buffer is intercepted and modified to pass the video buffers to the LCEVC DIL Libraries before appending to the MSE Source Buffers. 
+
+## Demo page
+
+The relevant libraries are added in the Demo Page like so: 
+
+```javascript
+  <!-- MPEG-5 Part2 LCEVC support is enabled by including this: -->
+  <script defer src="../node_modules/lcevc_dil.js/dist/lcevc_dil.min.js"></script>
+```
+
+And a new video sample with enhancement data is added to the `demo/common/assets.js` file under a new source `MPEG-5 Part 2 LCEVC`.
+
+After these changes the demo page looks like :
+
+![image.png](lcevc-demo.png)
+
+          

package/docs/tutorials/fairplay.md

@@ -8,6 +8,13 @@ Modern EME yet, you can use legacy Apple Media Keys with:
 shaka.polyfill.PatchedMediaKeysApple.install();
 ```
 
+If you need to use both legacy and Modern EME, for example if you have to support
+multiple DRM providers, it is possible to enable uninstalling the polyfill:
+```js
+shaka.polyfill.PatchedMediaKeysApple.install(/* enableUninstall= */ true);
+shaka.polyfill.PatchedMediaKeysApple.uninstall();
+```
+
 The support in each case would be the following:
 
 |            |Modern EME |legacy Apple Media Keys|

package/docs/tutorials/faq.md

@@ -164,7 +164,7 @@ shaka.net.NetworkingEngine.registerScheme('file', shaka.net.HttpXHRPlugin);
 contain said captions.  Edge and Chromecast, however, have native TS support and
 thus are not required to transmux.
 In order to force those platforms to transmux, set the
-{@link shaka.extern.StreamingConfiguration|`.streaming.forceTransmuxTS`} 
+{@link shaka.extern.StreamingConfiguration|`.streaming.forceTransmux`}
 configuration to true.
 
 <hr>

package/docs/tutorials/ui.md

@@ -30,7 +30,7 @@ Set up controls with HTML data attributes:
          The data-shaka-player-cast-receiver-id tag allows you to provide a Cast Application ID that
            the cast button will cast to; the value provided here is the sample cast receiver. -->
     <div data-shaka-player-container style="max-width:40em"
-         data-shaka-player-cast-receiver-id="07AEE832">
+         data-shaka-player-cast-receiver-id="8D8C71A7">
        <!-- The data-shaka-player tag will make the UI library use this video element.
             If no video is provided, the UI will automatically make one inside the container div. -->
       <video autoplay data-shaka-player id="video" style="width:100%;height:100%"></video>
@@ -111,7 +111,7 @@ set up a listener for the 'caststatuschanged' events.
 <!-- Add a data-shaka-player-cast-receiver-id tag to provide a Cast Application ID that
            the cast button will cast to; the value provided here is the sample cast receiver. -->
     <div data-shaka-player-container style="max-width:40em"
-         data-shaka-player-cast-receiver-id="07AEE832">
+         data-shaka-player-cast-receiver-id="8D8C71A7">
     </div>
 ```
 
@@ -139,7 +139,7 @@ casting to an Android receiver app.
 
 ```html
     <div data-shaka-player-container style="max-width:40em"
-         data-shaka-player-cast-receiver-id="E7271BEC"
+         data-shaka-player-cast-receiver-id="8D8C71A7"
          data-shaka-player-cast-android-receiver-compatible="true">
       <!-- The manifest url in the src attribute will be automatically loaded -->
       <video autoplay data-shaka-player id="video" style="width:100%;height:100%"
@@ -154,7 +154,7 @@ or a `<source>` tag inside it to enable auto loading of the specified content.
 
 ```html
     <div data-shaka-player-container style="max-width:40em"
-         data-shaka-player-cast-receiver-id="07AEE832">
+         data-shaka-player-cast-receiver-id="8D8C71A7">
       <!-- The manifest url in the src attribute will be automatically loaded -->
       <video autoplay data-shaka-player id="video" style="width:100%;height:100%"
        src="https://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mpd"></video>
@@ -165,7 +165,7 @@ or
 
 ```html
     <div data-shaka-player-container style="max-width:40em"
-         data-shaka-player-cast-receiver-id="07AEE832">
+         data-shaka-player-cast-receiver-id="8D8C71A7">
       <video autoplay data-shaka-player id="video" style="width:100%;height:100%">
         <!-- The manifest url in the src attribute will be auto loaded -->
        <source src="https://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mpd"/>
@@ -178,7 +178,7 @@ call to the first one fails.
 
 ```html
     <div data-shaka-player-container style="max-width:40em"
-         data-shaka-player-cast-receiver-id="07AEE832">
+         data-shaka-player-cast-receiver-id="8D8C71A7">
       <video autoplay data-shaka-player id="video" style="width:100%;height:100%">
         <!-- Try this first -->
         <source src="https://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mpd"/>
@@ -222,7 +222,7 @@ const video = controls.getVideo();
 // Receiver Compatability.
 ui.configure({
   // Set the castReceiverAppId
-  'castReceiverAppId': '07AEE832',
+  'castReceiverAppId': '8D8C71A7',
   // Enable casting to native Android Apps (e.g. Android TV Apps)
   'castAndroidReceiverCompatible': true,
 });

package/docs/tutorials/upgrade.md

@@ -90,3 +90,9 @@ application:
       clearly-named `lineBreak` (deprecated in v3.1.0)
     - `IUIElement` plugins must have a `release()` method (not `destroy()`)
       (deprecated in v3.0.0)
+
+## v5.0 (unreleased)
+
+  - Configuration changes:
+    - `streaming.forceTransmuxTS` has been renamed to `streaming.forceTransmux`
+      (deprecated in v4.3.0)

package/externs/ima.js

@@ -143,7 +143,7 @@ google.ima.AdsManagerLoadedEvent.Type = {
 
 /** @const */
 google.ima.AdEvent = class extends Event {
-  /** @return {!google.ima.Ad } */
+  /** @return {?google.ima.Ad} */
   getAd() {}
 };
 
@@ -167,6 +167,12 @@ google.ima.Ad = class {
 
   /** @return {boolean} */
   isLinear() {}
+
+  /** @return {string} */
+  getTitle() {}
+
+  /** @return {string} */
+  getDescription() {}
 };
 
 
@@ -389,6 +395,12 @@ google.ima.dai.api.Ad = class {
 
   /** @return {boolean} */
   isSkippable() {}
+
+  /** @return {string} */
+  getTitle() {}
+
+  /** @return {string} */
+  getDescription() {}
 };
 
 

package/externs/lcevc.js

@@ -0,0 +1,81 @@
+/**
+* @fileoverview Externs for LcevcDil
+* compiler.
+*
+* @externs
+*/
+
+// This empty namespace is declared to check if LcevcDil libraries are loaded.
+var libDPIModule = {};
+var LcevcDil = {};
+
+/**
+* LCEVC DIL constructor
+* @constructor
+*/
+LcevcDil.LcevcDIL = class {
+  /**
+   * @param {HTMLVideoElement} media
+   * @param {HTMLCanvasElement} canvas
+   * @param {shaka.extern.LcevcConfiguration} dilConfig
+   */
+  constructor(media, canvas, dilConfig) {
+  }
+
+  /**
+   * Append the video buffers before they are appended to
+   * Media Source Extensions SourceBuffer. Here the lcevc data
+   * will be parsed and managed to enhance frames based on timestamps.
+   *
+   * @param {!BufferSource} data Video Buffer Data.
+   * @param {string} type Type of Video Buffer Data.
+   * @param {number} variantId Variant that the fragment belongs to.
+   */
+  appendBuffer(data, type, variantId) {}
+
+  /**
+   * Set current variant as variantId to the LCEVC decoder
+   * @param {!number} variantId
+   * @param {!boolean} autoBufferSwitch is lcevcDil mode that switches variant
+   * when the downloaded buffer from last variant has finished playing and
+   * buffers from the new variant starts to play.
+   */
+  setLevelSwitching(variantId, autoBufferSwitch) {}
+
+  /**
+   * Set container Format for LCEVC Data Parsing.
+   * @param {!number} containerFormat container type of the stream.
+   */
+  setContainerFormat(containerFormat) {}
+
+  /**
+   * Close LCEVC DIL
+   */
+  close() {}
+};
+
+/**
+ * LCEVC Support Check
+ */
+LcevcDil.SupportObject = {
+
+  /**
+   * Check if canvas has WebGL support
+   * @param {HTMLCanvasElement} canvas
+   * @return {boolean} true if requirements are met.
+   */
+  webGLSupport(canvas) {},
+
+};
+
+/**
+ * LCEVC Support Checklist Result
+ * @type {boolean}
+ */
+LcevcDil.SupportObject.SupportStatus;
+
+/**
+ * LCEVC Support CheckList Error if any.
+ * @type {string}
+ */
+LcevcDil.SupportObject.SupportError;

package/externs/mux.js

@@ -84,15 +84,13 @@ muxjs.mp4.Transmuxer = class {
  * @typedef {{
  *   initSegment: !Uint8Array,
  *   data: !Uint8Array,
- *   captions: !Array,
- *   metadata: !Array
+ *   captions: !Array
  * }}
  *
  * @description Transmuxed data from mux.js.
  * @property {!Uint8Array} initSegment
  * @property {!Uint8Array} data
  * @property {!Array} captions
- * @property {!Array} metadata
  * @exportDoc
  */
 muxjs.mp4.Transmuxer.Segment;
@@ -173,42 +171,3 @@ muxjs.mp4.ParsedClosedCaptions;
  */
 muxjs.mp4.ClosedCaption;
 
-
-/**
- * @typedef {{
- *   cueTime: number,
- *   data: !Uint8Array,
- *   dispatchType: string,
- *   dts: number,
- *   frames: !Array.<muxjs.mp4.MetadataFrame>,
- *   pts: number
- * }}
- *
- * @description metadata parsed from mux.js.
- * @property {number} cueTime
- * @property {number} data
- * @property {number} dispatchType
- * @property {number} dts
- * @property {string} frames
- * @property {string} pts
- */
-muxjs.mp4.Metadata;
-
-
-/**
- * @typedef {{
- *   data: string,
- *   description: string,
- *   id: string,
- *   key: string,
- *   value: string
- * }}
- *
- * @description metadata parsed from mux.js.
- * @property {number} data
- * @property {number} description
- * @property {number} id
- * @property {number} key
- * @property {string} value
- */
-muxjs.mp4.MetadataFrame;

package/externs/shaka/ads.js

@@ -120,7 +120,7 @@ shaka.extern.IAdManager = class extends EventTarget {
   onHlsTimedMetadata(metadata, timestampOffset) {}
 
   /**
-   * @param {shaka.extern.ID3Metadata} value
+   * @param {shaka.extern.MetadataFrame} value
    */
   onCueMetadataChange(value) {}
 };
@@ -227,4 +227,14 @@ shaka.extern.IAd = class {
    * @return {number}
    */
   getPositionInSequence() {}
+
+  /**
+   * @return {string}
+   */
+  getTitle() {}
+
+  /**
+   * @return {string}
+   */
+  getDescription() {}
 };

package/externs/shaka/manifest_parser.js

@@ -112,7 +112,8 @@ shaka.extern.ManifestParser = class {
  *   isLowLatencyMode: function():boolean,
  *   isAutoLowLatencyMode: function():boolean,
  *   enableLowLatencyMode: function(),
- *   updateDuration: function()
+ *   updateDuration: function(),
+ *   newDrmInfo: function(shaka.extern.Stream)
  * }}
  *
  * @description
@@ -150,6 +151,9 @@ shaka.extern.ManifestParser = class {
  *   Enable low latency streaming mode.
  * @property {function()} updateDuration
  *   Update the presentation duration based on PresentationTimeline.
+ * @property {function(shaka.extern.Stream)} newDrmInfo
+ *   Inform the player of new DRM info that needs to be processed for the given
+ *   stream.
  * @exportDoc
  */
 shaka.extern.ManifestParser.PlayerInterface;