feat: Adds advanced ABR config options (shaka-project#3706)

Closes shaka-project#3422

demo/common/message_ids.js

@@ -173,6 +173,7 @@ shakaDemo.MessageIds = {
   DRM_SESSION_TYPE: 'DEMO_DRM_SESSION_TYPE',
   DURATION_BACKOFF: 'DEMO_DURATION_BACKOFF',
   ENABLED: 'DEMO_ENABLED',
+  FAST_HALF_LIFE: 'DEMO_FAST_HALF_LIFE',
   FORCE_HTTPS: 'DEMO_FORCE_HTTPS',
   FORCE_TRANSMUX_TS: 'DEMO_FORCE_TRANSMUX_TS',
   FUZZ_FACTOR: 'DEMO_FUZZ_FACTOR',
@@ -206,11 +207,13 @@ shakaDemo.MessageIds = {
   MAX_PIXELS: 'DEMO_MAX_PIXELS',
   MAX_SMALL_GAP_SIZE: 'DEMO_MAX_SMALL_GAP_SIZE',
   MAX_WIDTH: 'DEMO_MAX_WIDTH',
+  MIN_BANDWIDTH: 'DEMO_MIN_BANDWIDTH',
+  MIN_BYTES: 'DEMO_MIN_BYTES',
   MIN_FRAMERATE: 'DEMO_MIN_FRAMERATE',
   MIN_HEIGHT: 'DEMO_MIN_HEIGHT',
   MIN_PIXELS: 'DEMO_MIN_PIXELS',
+  MIN_TOTAL_BYTES: 'DEMO_MIN_TOTAL_BYTES',
   MIN_WIDTH: 'DEMO_MIN_WIDTH',
-  MIN_BANDWIDTH: 'DEMO_MIN_BANDWIDTH',
   NETWORK_INFORMATION: 'DEMO_NETWORK_INFORMATION',
   NUMBER_DECIMAL_WARNING: 'DEMO_NUMBER_DECIMAL_WARNING',
   NUMBER_INTEGER_WARNING: 'DEMO_NUMBER_INTEGER_WARNING',
@@ -224,6 +227,7 @@ shakaDemo.MessageIds = {
   SAFE_SEEK_OFFSET: 'DEMO_SAFE_SEEK_OFFSET',
   SAFE_SKIP_DISTANCE: 'DEMO_SAFE_SKIP_DISTANCE',
   SHAKA_CONTROLS: 'DEMO_SHAKA_CONTROLS',
+  SLOW_HALF_LIFE: 'DEMO_SLOW_HALF_LIFE',
   STALL_DETECTOR_ENABLED: 'DEMO_STALL_DETECTOR_ENABLED',
   STALL_THRESHOLD: 'DEMO_STALL_THRESHOLD',
   STALL_TIMEOUT: 'DEMO_STALL_TIMEOUT',

demo/config.js

@@ -259,6 +259,16 @@ shakaDemo.Config = class {
             /* canBeDecimal= */ true)
         .addNumberInput_(MessageIds.SWITCH_INTERVAL,
             'abr.switchInterval',
+            /* canBeDecimal= */ true)
+        .addNumberInput_(MessageIds.MIN_TOTAL_BYTES,
+            'abr.advanced.minTotalBytes')
+        .addNumberInput_(MessageIds.MIN_BYTES,
+            'abr.advanced.minBytes')
+        .addNumberInput_(MessageIds.FAST_HALF_LIFE,
+            'abr.advanced.fastHalfLife',
+            /* canBeDecimal= */ true)
+        .addNumberInput_(MessageIds.SLOW_HALF_LIFE,
+            'abr.advanced.slowHalfLife',
             /* canBeDecimal= */ true);
     this.addRetrictionsSection_('abr',
         MessageIds.ADAPTATION_RESTRICTIONS_SECTION_HEADER);

demo/locales/en.json

@@ -72,6 +72,7 @@
   "DEMO_EXTRA_SHAKA_PLAYER_CONFIG": "Extra Shaka Player configuration (JSON)",
   "DEMO_EXTRA_TAB": "Extra Config",
   "DEMO_FAIRPLAY": "Fairplay DRM",
+  "DEMO_FAST_HALF_LIFE": "Fast half life",
   "DEMO_FORCE_HTTPS": "Force HTTPS",
   "DEMO_FORCE_TRANSMUX_TS": "Force Transmux TS",
   "DEMO_FRONT_INTRO_DISMISS": "Dismiss",
@@ -137,9 +138,11 @@
   "DEMO_MICROSOFT": "Microsoft",
   "DEMO_MIME_TYPE": "MIME Type",
   "DEMO_MIN_BANDWIDTH": "Min Bandwidth",
+  "DEMO_MIN_BYTES": "Min Bytes",
   "DEMO_MIN_FRAMERATE": "Min Framerate",
   "DEMO_MIN_HEIGHT": "Min Height",
   "DEMO_MIN_PIXELS": "Min Pixels",
+  "DEMO_MIN_TOTAL_BYTES": "Min total Bytes",
   "DEMO_MIN_WIDTH": "Min Width",
   "DEMO_MP2TS": "MPEG-2 TS",
   "DEMO_MP4": "MP4",
@@ -173,6 +176,7 @@
   "DEMO_SAVE_BUTTON": "Save",
   "DEMO_SHAKA": "Shaka",
   "DEMO_SHAKA_CONTROLS": "Shaka Controls",
+  "DEMO_SLOW_HALF_LIFE": "Slow half life",
   "DEMO_SOURCE": "Source on GitHub",
   "DEMO_SOURCE_SEARCH": "Source",
   "DEMO_STALL_DETECTOR_ENABLED": "Stall Detector Enabled",

demo/locales/source.json

@@ -291,6 +291,10 @@
     "description": "Text that describes an asset that is protected with the Fairplay Digital Rights Management system.",
     "message": "[PROPER_NAME:Fairplay] [JARGON:DRM]"
   },
+  "DEMO_FAST_HALF_LIFE": {
+    "description": "The name of a configuration value.",
+    "message": "Fast half life"
+  },
   "DEMO_FORCE_HTTPS": {
     "description": "The name of a configuration value.",
     "message": "Force [JARGON:HTTPS]"
@@ -555,6 +559,10 @@
     "description": "The name of a configuration value.",
     "message": "Min Bandwidth"
   },
+  "DEMO_MIN_BYTES": {
+    "description": "The name of a configuration value.",
+    "message": "Min Bytes"
+  },
   "DEMO_MIN_FRAMERATE": {
     "description": "The name of a configuration value.",
     "message": "Min Framerate"
@@ -567,6 +575,10 @@
     "description": "The name of a configuration value.",
     "message": "Min Pixels"
   },
+  "DEMO_MIN_TOTAL_BYTES": {
+    "description": "The name of a configuration value.",
+    "message": "Min total Bytes"
+  },
   "DEMO_MIN_WIDTH": {
     "description": "The name of a configuration value.",
     "message": "Min Width"
@@ -695,6 +707,10 @@
     "description": "Text that describes an asset that comes from the Shaka Player asset library.",
     "message": "[PROPER_NAME:Shaka]"
   },
+  "DEMO_SLOW_HALF_LIFE": {
+    "description": "The name of a configuration value.",
+    "message": "Slow half life"
+  },
   "DEMO_SHAKA_CONTROLS": {
     "description": "The name of a configuration value.",
     "message": "[PROPER_NAME:Shaka] Controls"

externs/shaka/player.js

@@ -924,7 +924,8 @@ shaka.extern.StreamingConfiguration;
  *   restrictions: shaka.extern.Restrictions,
  *   switchInterval: number,
  *   bandwidthUpgradeTarget: number,
- *   bandwidthDowngradeTarget: number
+ *   bandwidthDowngradeTarget: number,
+ *   advanced: shaka.extern.AdvancedAbrConfiguration
  * }}
  *
  * @property {boolean} enabled
@@ -952,11 +953,43 @@ shaka.extern.StreamingConfiguration;
  * @property {number} bandwidthDowngradeTarget
  *   The largest fraction of the estimated bandwidth we should use. We should
  *   downgrade to avoid this.
+ * @property {shaka.extern.AdvancedAbrConfiguration} advanced
+ *   Advanced ABR configuration.
  * @exportDoc
  */
 shaka.extern.AbrConfiguration;
 
 
+/**
+ * @typedef {{
+ *   minTotalBytes: number,
+ *   minBytes: number,
+ *   fastHalfLife: number,
+ *   slowHalfLife: number
+ * }}
+ *
+ * @property {number} minTotalBytes
+ *   Minimum number of bytes sampled before we trust the estimate.  If we have
+ *   not sampled much data, our estimate may not be accurate enough to trust.
+ * @property {number} minBytes
+ *   Minimum number of bytes, under which samples are discarded.  Our models
+ *   do not include latency information, so connection startup time (time to
+ *   first byte) is considered part of the download time.  Because of this, we
+ *   should ignore very small downloads which would cause our estimate to be
+ *   too low.
+ * @property {number} fastHalfLife
+ *   The quantity of prior samples (by weight) used when creating a new
+ *   estimate, in seconds.  Those prior samples make up half of the
+ *   new estimate.
+ * @property {number} slowHalfLife
+ *   The quantity of prior samples (by weight) used when creating a new
+ *   estimate, in seconds.  Those prior samples make up half of the
+ *   new estimate.
+ * @exportDoc
+ */
+shaka.extern.AdvancedAbrConfiguration;
+
+
 /**
  * @typedef {{
  *   trackSelectionCallback:

lib/abr/ewma.js

@@ -35,6 +35,20 @@ shaka.abr.Ewma = class {
     this.totalWeight_ = 0;
   }
 
+
+  /**
+   * Update the alpha with a new halfLife value.
+   *
+   * @param {number} halfLife The quantity of prior samples (by weight) used
+   *   when creating a new estimate.  Those prior samples make up half of the
+   *   new estimate.
+   */
+  updateAlpha(halfLife) {
+    goog.asserts.assert(halfLife > 0, 'expected halfLife to be positive');
+    this.alpha_ = Math.exp(Math.log(0.5) / halfLife);
+  }
+
+
   /**
    * Takes a sample.
    *

lib/abr/ewma_bandwidth_estimator.js

@@ -47,7 +47,6 @@ shaka.abr.EwmaBandwidthEstimator = class {
      * This specific value is based on experimentation.
      *
      * @private {number}
-     * @const
      */
     this.minTotalBytes_ = 128e3;  // 128kB
 
@@ -60,11 +59,26 @@ shaka.abr.EwmaBandwidthEstimator = class {
      * This specific value is based on experimentation.
      *
      * @private {number}
-     * @const
      */
     this.minBytes_ = 16e3;  // 16kB
   }
 
+
+  /**
+   * Called by the Player to provide an updated configuration any time it
+   * changes.
+   * Must be called at least once before init().
+   *
+   * @param {shaka.extern.AdvancedAbrConfiguration} config
+   */
+  configure(config) {
+    this.minTotalBytes_ = config.minTotalBytes;
+    this.minBytes_ = config.minBytes;
+    this.fast_.updateAlpha(config.fastHalfLife);
+    this.slow_.updateAlpha(config.slowHalfLife);
+  }
+
+
   /**
    * Takes a bandwidth sample.
    *

lib/abr/simple_abr_manager.js

@@ -54,6 +54,9 @@ shaka.abr.SimpleAbrManager = class {
       navigator.connection.addEventListener('change', () => {
         if (this.config_.useNetworkInformation && this.enabled_) {
           this.bandwidthEstimator_ = new shaka.abr.EwmaBandwidthEstimator();
+          if (this.config_) {
+            this.bandwidthEstimator_.configure(this.config_.advanced);
+          }
           const chosenVariant = this.chooseVariant();
           if (chosenVariant) {
             this.switch_(chosenVariant);
@@ -239,6 +242,9 @@ shaka.abr.SimpleAbrManager = class {
    */
   configure(config) {
     this.config_ = config;
+    if (this.bandwidthEstimator_ && this.config_) {
+      this.bandwidthEstimator_.configure(this.config_.advanced);
+    }
   }
 
 

lib/util/player_configuration.js

@@ -238,6 +238,12 @@ shaka.util.PlayerConfiguration = class {
         minBandwidth: 0,
         maxBandwidth: Infinity,
       },
+      advanced: {
+        minTotalBytes: 128e3,
+        minBytes: 16e3,
+        fastHalfLife: 2,
+        slowHalfLife: 5,
+      },
     };
 
     /** @type {shaka.extern.PlayerConfiguration} */