Plugin for onQualityChangeRequested

docs/tutorials/Plugins.md

@@ -1,6 +1,7 @@
 Plugins can be created to extend the functionality of the Bigscreen Player by adhering to an interface which propogates non state change events from the player. For example, when an error is raised or cleared.
 
 The full interface is as follows:
+
 - `onError`
 - `onFatalError`
 - `onErrorCleared`
@@ -11,6 +12,7 @@ The full interface is as follows:
 - `onPlayerInfoUpdated`
 - `onManifestLoaded`
 - `onManifestParseError`
+- `onQualityChangeRequested`
 - `onQualityChangedRendered`
 - `onSubtitlesLoadError`
 - `onSubtitlesTimeout`
@@ -23,37 +25,35 @@ The full interface is as follows:
 An example plugin may look like:
 
 ```javascript
-function ExamplePlugin (appName) {
-
-  var name = appName;
+function ExamplePlugin(appName) {
+  var name = appName
 
-  function onFatalError (evt) {
-    console.log('A fatal error has occured in the app: ' + name);
+  function onFatalError(evt) {
+    console.log("A fatal error has occured in the app: " + name)
   }
 
-  function onErrorHandled (evt) {
-    console.log('The ' + name + ' app is handling a playback error');
+  function onErrorHandled(evt) {
+    console.log("The " + name + " app is handling a playback error")
   }
 
   return {
     onFatalError: onFatalError,
-    onErrorHandled: onErrorHandled
-  };
+    onErrorHandled: onErrorHandled,
+  }
 }
 ```
 
 ```javascript
-var bigscreenPlayer = BigscreenPlayer();
+var bigscreenPlayer = BigscreenPlayer()
 
-var examplePlugin = ExamplePlugin('myApp');
+var examplePlugin = ExamplePlugin("myApp")
 
-bigscreenPlayer.registerPlugin(examplePlugin);
+bigscreenPlayer.registerPlugin(examplePlugin)
 
 // initialise bigscreenPlayer - see above
 
 // you should unregister your plugins as part of your playback cleanup
 
 // calling with no argument will unregister all plugins
-bigscreenPlayer.unregisterPlugin(examplePlugin);
-
+bigscreenPlayer.unregisterPlugin(examplePlugin)
 ```

src/playbackstrategy/msestrategy.js

@@ -87,6 +87,7 @@ function MSEStrategy(mediaSources, windowType, mediaKind, playbackElement, isUHD
     DOWNLOAD_INIT_SEGMENT_ERROR_CODE: 28,
     UNSUPPORTED_CODEC: 30,
     MANIFEST_VALIDITY_CHANGED: "manifestValidityChanged",
+    QUALITY_CHANGE_REQUESTED: "qualityChangeRequested",
     QUALITY_CHANGE_RENDERED: "qualityChangeRendered",
     BASE_URL_SELECTED: "baseUrlSelected",
     SERVICE_LOCATION_AVAILABLE: "serviceLocationUnblacklisted",
@@ -354,25 +355,31 @@ function MSEStrategy(mediaSources, windowType, mediaKind, playbackElement, isUHD
     return parseInt(bitrateInfoList[index].bitrate / 1000)
   }
 
-  function onQualityChangeRendered(event) {
-    function logBitrate(event) {
-      const { mediaType, oldQuality, newQuality } = event
-
-      const oldBitrate = isNaN(oldQuality) ? "--" : playbackBitrateForRepresentationIndex(oldQuality, mediaType)
-      const newBitrate = isNaN(newQuality) ? "--" : playbackBitrateForRepresentationIndex(newQuality, mediaType)
+  function logBitrate(abrType, { mediaType, oldQuality, newQuality }) {
+    const oldBitrate = isNaN(oldQuality) ? "--" : playbackBitrateForRepresentationIndex(oldQuality, mediaType)
+    const newBitrate = isNaN(newQuality) ? "--" : playbackBitrateForRepresentationIndex(newQuality, mediaType)
 
-      const oldRepresentation = isNaN(oldQuality) ? "Start" : `${oldQuality} (${oldBitrate} kbps)`
-      const newRepresentation = `${newQuality} (${newBitrate} kbps)`
+    const oldRepresentation = isNaN(oldQuality) ? "Start" : `${oldQuality} (${oldBitrate} kbps)`
+    const newRepresentation = `${newQuality} (${newBitrate} kbps)`
 
-      DebugTool.dynamicMetric(`representation-${mediaType}`, [newQuality, newBitrate])
+    DebugTool.info(
+      `${mediaType} ABR Change ${abrType} From Representation ${oldRepresentation} to ${newRepresentation}`
+    )
+  }
 
-      DebugTool.info(
-        `${mediaType} ABR Change Rendered From Representation ${oldRepresentation} To ${newRepresentation}`
-      )
+  function onQualityChangeRequested(event) {
+    if (event.newQuality !== undefined) {
+      logBitrate("Requested", event)
     }
 
+    event.throughput = mediaPlayer.getAverageThroughput(mediaKind)
+
+    Plugins.interface.onQualityChangeRequested(event)
+  }
+
+  function onQualityChangeRendered(event) {
     if (event.newQuality !== undefined) {
-      logBitrate(event)
+      logBitrate("Rendered", event)
     }
 
     emitPlayerInfo()
@@ -544,6 +551,7 @@ function MSEStrategy(mediaSources, windowType, mediaKind, playbackElement, isUHD
     mediaPlayer.on(DashJSEvents.MANIFEST_LOADED, onManifestLoaded)
     mediaPlayer.on(DashJSEvents.STREAM_INITIALIZED, onStreamInitialised)
     mediaPlayer.on(DashJSEvents.MANIFEST_VALIDITY_CHANGED, onManifestValidityChange)
+    mediaPlayer.on(DashJSEvents.QUALITY_CHANGE_REQUESTED, onQualityChangeRequested)
     mediaPlayer.on(DashJSEvents.QUALITY_CHANGE_RENDERED, onQualityChangeRendered)
     mediaPlayer.on(DashJSEvents.BASE_URL_SELECTED, onBaseUrlSelected)
     mediaPlayer.on(DashJSEvents.METRIC_ADDED, onMetricAdded)
@@ -654,6 +662,7 @@ function MSEStrategy(mediaSources, windowType, mediaKind, playbackElement, isUHD
       mediaPlayer.off(DashJSEvents.MANIFEST_VALIDITY_CHANGED, onManifestValidityChange)
       mediaPlayer.off(DashJSEvents.STREAM_INITIALIZED, onStreamInitialised)
       mediaPlayer.off(DashJSEvents.QUALITY_CHANGE_RENDERED, onQualityChangeRendered)
+      mediaPlayer.off(DashJSEvents.QUALITY_CHANGE_REQUESTED, onQualityChangeRequested)
       mediaPlayer.off(DashJSEvents.METRIC_ADDED, onMetricAdded)
       mediaPlayer.off(DashJSEvents.BASE_URL_SELECTED, onBaseUrlSelected)
       mediaPlayer.off(DashJSEvents.LOG, onDebugLog)

src/plugins.js

@@ -40,6 +40,7 @@ export default {
     onPlayerInfoUpdated: (evt) => callOnAllPlugins("onPlayerInfoUpdated", evt),
     onManifestLoaded: (manifest) => callOnAllPlugins("onManifestLoaded", manifest),
     onManifestParseError: (evt) => callOnAllPlugins("onManifestParseError", evt),
+    onQualityChangeRequested: (evt) => callOnAllPlugins("onQualityChangeRequested", evt),
     onQualityChangedRendered: (evt) => callOnAllPlugins("onQualityChangedRendered", evt),
     onSubtitlesLoadError: (evt) => callOnAllPlugins("onSubtitlesLoadError", evt),
     onSubtitlesTimeout: (evt) => callOnAllPlugins("onSubtitlesTimeout", evt),