Source: lib/abr/ewma_bandwidth_estimator.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.abr.EwmaBandwidthEstimator');
  9. goog.require('shaka.abr.Ewma');
  12. /**
  13.  * @summary
  14.  * This class tracks bandwidth samples and estimates available bandwidth.
  15.  * Based on the minimum of two exponentially-weighted moving averages with
  16.  * different half-lives.
  17.  *
  18.  */
  19. shaka.abr.EwmaBandwidthEstimator = class {
  20.   constructor() {
  21.     /**
  22.      * A fast-moving average.
  23.      * Half of the estimate is based on the last 2 seconds of sample history.
  24.      * @private {!shaka.abr.Ewma}
  25.      */
  26.     this.fast_ = new shaka.abr.Ewma(2);
  28.     /**
  29.      * A slow-moving average.
  30.      * Half of the estimate is based on the last 5 seconds of sample history.
  31.      * @private {!shaka.abr.Ewma}
  32.      */
  33.     this.slow_ = new shaka.abr.Ewma(5);
  35.     /**
  36.      * Number of bytes sampled.
  37.      * @private {number}
  38.      */
  39.     this.bytesSampled_ = 0;
  42.     /**
  43.      * Minimum number of bytes sampled before we trust the estimate.  If we have
  44.      * not sampled much data, our estimate may not be accurate enough to trust.
  45.      * If bytesSampled_ is less than minTotalBytes_, we use defaultEstimate_.
  46.      * This specific value is based on experimentation.
  47.      *
  48.      * @private {number}
  49.      */
  50.     this.minTotalBytes_ = 128e3;  // 128kB
  52.     /**
  53.      * Minimum number of bytes, under which samples are discarded.  Our models
  54.      * do not include latency information, so connection startup time (time to
  55.      * first byte) is considered part of the download time.  Because of this, we
  56.      * should ignore very small downloads which would cause our estimate to be
  57.      * too low.
  58.      * This specific value is based on experimentation.
  59.      *
  60.      * @private {number}
  61.      */
  62.     this.minBytes_ = 16e3;  // 16kB
  63.   }
  66.   /**
  67.    * Called by the Player to provide an updated configuration any time it
  68.    * changes.
  69.    * Must be called at least once before init().
  70.    *
  71.    * @param {shaka.extern.AdvancedAbrConfiguration} config
  72.    */
  73.   configure(config) {
  74.     this.minTotalBytes_ = config.minTotalBytes;
  75.     this.minBytes_ = config.minBytes;
  76.     this.fast_.updateAlpha(config.fastHalfLife);
  77.     this.slow_.updateAlpha(config.slowHalfLife);
  78.   }
  81.   /**
  82.    * Takes a bandwidth sample.
  83.    *
  84.    * @param {number} durationMs The amount of time, in milliseconds, for a
  85.    *   particular request.
  86.    * @param {number} numBytes The total number of bytes transferred in that
  87.    *   request.
  88.    */
  89.   sample(
  90.       durationMs, numBytes) {
  91.     if (numBytes < this.minBytes_) {
  92.       return;
  93.     }
  95.     const bandwidth = 8000 * numBytes / durationMs;
  96.     const weight = durationMs / 1000;
  98.     this.bytesSampled_ += numBytes;
  99.     this.fast_.sample(weight, bandwidth);
  100.     this.slow_.sample(weight, bandwidth);
  101.   }
  104.   /**
  105.    * Gets the current bandwidth estimate.
  106.    *
  107.    * @param {number} defaultEstimate
  108.    * @return {number} The bandwidth estimate in bits per second.
  109.    */
  110.   getBandwidthEstimate(defaultEstimate) {
  111.     if (this.bytesSampled_ < this.minTotalBytes_) {
  112.       return defaultEstimate;
  113.     }
  115.     // Take the minimum of these two estimates.  This should have the effect
  116.     // of adapting down quickly, but up more slowly.
  117.     return Math.min(this.fast_.getEstimate(), this.slow_.getEstimate());
  118.   }
  121.   /**
  122.    * @return {boolean} True if there is enough data to produce a meaningful
  123.    *   estimate.
  124.    */
  125.   hasGoodEstimate() {
  126.     return this.bytesSampled_ >= this.minTotalBytes_;
  127.   }
  128. };