feat: Add media quality change events (shaka-project#3700)

Closes #shaka-project#3431

build/types/core

@@ -28,6 +28,7 @@
 +../../lib/media/playhead.js
 +../../lib/media/playhead_observer.js
 +../../lib/media/presentation_timeline.js
++../../lib/media/quality_observer.js
 +../../lib/media/region_observer.js
 +../../lib/media/region_timeline.js
 +../../lib/media/segment_index.js

demo/common/message_ids.js

@@ -170,6 +170,7 @@ shakaDemo.MessageIds = {
   DISABLE_VIDEO: 'DEMO_DISABLE_VIDEO',
   DISABLE_XLINK_PROCESSING: 'DEMO_DISABLE_XLINK_PROCESSING',
   DISPATCH_ALL_EMSG_BOXES: 'DEMO_DISPATCH_ALL_EMSG_BOXES',
+  OBSERVE_QUALITY_CHANGES: 'DEMO_OBSERVE_QUALITY_CHANGES',
   DRM_RETRY_SECTION_HEADER: 'DEMO_DRM_RETRY_SECTION_HEADER',
   DRM_SECTION_HEADER: 'DEMO_DRM_SECTION_HEADER',
   DRM_SESSION_TYPE: 'DEMO_DRM_SESSION_TYPE',

demo/config.js

@@ -390,7 +390,9 @@ shakaDemo.Config = class {
             'streaming.updateIntervalSeconds',
             /* canBeDecimal= */ true)
         .addBoolInput_(MessageIds.DISPATCH_ALL_EMSG_BOXES,
-            'streaming.dispatchAllEmsgBoxes');
+            'streaming.dispatchAllEmsgBoxes')
+        .addBoolInput_(MessageIds.OBSERVE_QUALITY_CHANGES,
+            'streaming.observeQualityChanges');
 
     if (!shakaDemoMain.getNativeControlsEnabled()) {
       this.addBoolInput_(MessageIds.ALWAYS_STREAM_TEXT,

demo/locales/en.json

@@ -158,6 +158,7 @@
   "DEMO_NUMBER_INTEGER_WARNING": "Must be a positive integer.",
   "DEMO_NUMBER_NONZERO_DECIMAL_WARNING": "Must be a positive, nonzero number.",
   "DEMO_NUMBER_NONZERO_INTEGER_WARNING": "Must be a positive, nonzero integer.",
+  "DEMO_OBSERVE_QUALITY_CHANGES": "Observe media quality changes",
   "DEMO_OFFLINE": "Downloadable",
   "DEMO_OFFLINE_SEARCH": "Filters for assets that can be stored offline.",
   "DEMO_OFFLINE_SECTION_HEADER": "Offline",

demo/locales/source.json

@@ -639,6 +639,10 @@
     "description": "A warning on number inputs, telling the user what the expected input format is.",
     "message": "Must be a positive, nonzero integer."
   },
+  "DEMO_OBSERVE_QUALITY_CHANGES": {
+    "description": "The name of a configuration value.",
+    "message": "Observe media quality changes"
+  },
   "DEMO_OFFLINE": {
     "description": "A tag that marks an asset as being possible to download.",
     "message": "Downloadable"

externs/shaka/player.js

@@ -468,6 +468,48 @@ shaka.extern.ID3Metadata;
  */
 shaka.extern.TimelineRegionInfo;
 
+/**
+ * @typedef {{
+ *   audioSamplingRate: ?number,
+ *   bandwidth: number,
+ *   codecs: string,
+ *   contentType: string,
+ *   frameRate: ?number,
+ *   height: ?number,
+ *   mimeType: ?string,
+ *   channelsCount: ?number,
+ *   pixelAspectRatio: ?string,
+ *   width: ?number
+ * }}
+ *
+ * @description
+ * Contains information about the quality of an audio or video media stream.
+ *
+ * @property {?number} audioSamplingRate
+ *   Specifies the maximum sampling rate of the content.
+ * @property {number} bandwidth
+ *   The bandwidth in bits per second.
+ * @property {string} codecs
+ *   The Stream's codecs, e.g., 'avc1.4d4015' or 'vp9', which must be
+ * compatible with the Stream's MIME type.
+ * @property {string} contentType
+ *   The type of content, which may be "video" or "audio".
+ * @property {?number} frameRate
+ *   The video frame rate.
+ * @property {?number} height
+ *   The video height in pixels.
+ * @property {string} mimeType
+ *   The MIME type.
+ * @property {?number} channelsCount
+ *   The number of audio channels, or null if unknown.
+ * @property {?string} pixelAspectRatio
+ *   The pixel aspect ratio value; e.g "1:1".
+ * @property {?number} width
+ *   The video width in pixels.
+ * @exportDoc
+ */
+shaka.extern.MediaQualityInfo;
+
 
 /**
  * @typedef {{
@@ -799,7 +841,8 @@ shaka.extern.ManifestConfiguration;
  *   forceHTTPS: boolean,
  *   preferNativeHls: boolean,
  *   updateIntervalSeconds: number,
- *   dispatchAllEmsgBoxes: boolean
+ *   dispatchAllEmsgBoxes: boolean,
+ *   observeQualityChanges: boolean
  * }}
  *
  * @description
@@ -910,7 +953,9 @@ shaka.extern.ManifestConfiguration;
  *   The minimum number of seconds to see if the manifest has changes.
  * @property {boolean} dispatchAllEmsgBoxes
  *   If true, all emsg boxes are parsed and dispatched.
- *
+ * @property {boolean} observeQualityChanges
+ *   If true, monitor media quality changes and emit
+ *   <code.shaka.Player.MediaQualityChangedEvent</code>.
  * @exportDoc
  */
 shaka.extern.StreamingConfiguration;

lib/dash/segment_base.js

@@ -61,7 +61,9 @@ shaka.dash.SegmentBase = class {
     }
 
     const getUris = () => resolvedUris;
-    return new shaka.media.InitSegmentReference(getUris, startByte, endByte);
+    const qualityInfo = shaka.dash.SegmentBase.createQualityInfo(context);
+    return new shaka.media.InitSegmentReference(
+        getUris, startByte, endByte, qualityInfo);
   }
 
   /**
@@ -346,4 +348,26 @@ shaka.dash.SegmentBase = class {
         indexRange.start, indexRange.end,
         scaledPresentationTimeOffset);
   }
+
+  /**
+   * Create a MediaQualityInfo object from a Context object.
+   *
+   * @param {!shaka.dash.DashParser.Context} context
+   * @return {!shaka.extern.MediaQualityInfo}
+   */
+  static createQualityInfo(context) {
+    const representation = context.representation;
+    return {
+      bandwidth: context.bandwidth,
+      audioSamplingRate: representation.audioSamplingRate,
+      codecs: representation.codecs,
+      contentType: representation.contentType,
+      frameRate: representation.frameRate || null,
+      height: representation.height || null,
+      mimeType: representation.mimeType,
+      channelsCount: representation.numChannels,
+      pixelAspectRatio: representation.pixelAspectRatio || null,
+      width: representation.width || null,
+    };
+  }
 };

lib/dash/segment_template.js

@@ -582,8 +582,8 @@ shaka.dash.SegmentTemplate = class {
           baseUris, [filledTemplate]);
       return resolvedUris;
     };
-
-    return new shaka.media.InitSegmentReference(getUris, 0, null);
+    const qualityInfo = shaka.dash.SegmentBase.createQualityInfo(context);
+    return new shaka.media.InitSegmentReference(getUris, 0, null, qualityInfo);
   }
 };