Source: lib/abr/simple_abr_manager.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.abr.SimpleAbrManager');
  9. goog.require('shaka.util.IReleasable');
  10. goog.require('goog.asserts');
  11. goog.require('shaka.abr.EwmaBandwidthEstimator');
  12. goog.require('shaka.log');
  13. goog.require('shaka.util.StreamUtils');
  14. goog.require('shaka.util.Timer');
  17. /**
  18.  * @summary
  19.  * <p>
  20.  * This defines the default ABR manager for the Player.  An instance of this
  21.  * class is used when no ABR manager is given.
  22.  * </p>
  23.  * <p>
  24.  * The behavior of this class is to take throughput samples using
  25.  * segmentDownloaded to estimate the current network bandwidth.  Then it will
  26.  * use that to choose the streams that best fit the current bandwidth.  It will
  27.  * always pick the highest bandwidth variant it thinks can be played.
  28.  * </p>
  29.  * <p>
  30.  * After initial choices are made, this class will call switchCallback() when
  31.  * there is a better choice.  switchCallback() will not be called more than once
  32.  * per ({@link shaka.abr.SimpleAbrManager.SWITCH_INTERVAL_MS}).
  33.  * </p>
  34.  *
  35.  * @implements {shaka.extern.AbrManager}
  36.  * @implements {shaka.util.IReleasable}
  37.  * @export
  38.  */
  39. shaka.abr.SimpleAbrManager = class {
  40.   /** */
  41.   constructor() {
  42.     /** @private {?shaka.extern.AbrManager.SwitchCallback} */
  43.     this.switch_ = null;
  45.     /** @private {boolean} */
  46.     this.enabled_ = false;
  48.     /** @private {shaka.abr.EwmaBandwidthEstimator} */
  49.     this.bandwidthEstimator_ = new shaka.abr.EwmaBandwidthEstimator();
  51.     /** @private {?function():void} */
  52.     this.onNetworkInformationChange_ = null;
  54.     // Some browsers implement the Network Information API, which allows
  55.     // retrieving information about a user's network connection. We listen
  56.     // to the change event to be able to make quick changes in case the type
  57.     // of connectivity changes.
  58.     if (navigator.connection && navigator.connection.addEventListener) {
  59.       this.onNetworkInformationChange_ = () => {
  60.         if (this.enabled_ && this.config_.useNetworkInformation) {
  61.           this.bandwidthEstimator_ = new shaka.abr.EwmaBandwidthEstimator();
  62.           if (this.config_) {
  63.             this.bandwidthEstimator_.configure(this.config_.advanced);
  64.           }
  65.           const chosenVariant = this.chooseVariant();
  66.           if (chosenVariant && navigator.onLine) {
  67.             this.switch_(chosenVariant);
  68.           }
  69.         }
  70.       };
  72.       navigator.connection.addEventListener(
  73.           'change', this.onNetworkInformationChange_);
  74.     }
  76.     /**
  77.      * A filtered list of Variants to choose from.
  78.      * @private {!Array.<!shaka.extern.Variant>}
  79.      */
  80.     this.variants_ = [];
  82.     /** @private {number} */
  83.     this.playbackRate_ = 1;
  85.     /** @private {boolean} */
  86.     this.startupComplete_ = false;
  88.     /**
  89.      * The last wall-clock time, in milliseconds, when streams were chosen.
  90.      *
  91.      * @private {?number}
  92.      */
  93.     this.lastTimeChosenMs_ = null;
  95.     /** @private {?shaka.extern.AbrConfiguration} */
  96.     this.config_ = null;
  98.     /** @private {HTMLMediaElement} */
  99.     this.mediaElement_ = null;
  101.     /** @private {ResizeObserver} */
  102.     this.resizeObserver_ = null;
  104.     /** @private {shaka.util.Timer} */
  105.     this.resizeObserverTimer_ = new shaka.util.Timer(() => {
  106.       if (this.config_.restrictToElementSize) {
  107.         const chosenVariant = this.chooseVariant();
  108.         if (chosenVariant) {
  109.           this.switch_(chosenVariant);
  110.         }
  111.       }
  112.     });
  113.   }
  116.   /**
  117.    * @override
  118.    * @export
  119.    */
  120.   stop() {
  121.     this.switch_ = null;
  122.     this.enabled_ = false;
  123.     this.variants_ = [];
  124.     this.playbackRate_ = 1;
  125.     this.lastTimeChosenMs_ = null;
  126.     this.mediaElement_ = null;
  128.     if (this.resizeObserver_) {
  129.       this.resizeObserver_.disconnect();
  130.       this.resizeObserver_ = null;
  131.     }
  133.     this.resizeObserverTimer_.stop();
  135.     // Don't reset |startupComplete_|: if we've left the startup interval, we
  136.     // can start using bandwidth estimates right away after init() is called.
  137.   }
  139.   /**
  140.    * @override
  141.    * @export
  142.    */
  143.   release() {
  144.     // stop() should already have been called for unload
  146.     if (navigator.connection && navigator.connection.removeEventListener) {
  147.       navigator.connection.removeEventListener(
  148.           'change', this.onNetworkInformationChange_);
  149.       this.onNetworkInformationChange_ = null;
  150.     }
  152.     this.resizeObserverTimer_ = null;
  153.   }
  156.   /**
  157.    * @override
  158.    * @export
  159.    */
  160.   init(switchCallback) {
  161.     this.switch_ = switchCallback;
  162.   }
  165.   /**
  166.    * @override
  167.    * @export
  168.    */
  169.   chooseVariant() {
  170.     const SimpleAbrManager = shaka.abr.SimpleAbrManager;
  172.     let maxHeight = Infinity;
  173.     let maxWidth = Infinity;
  175.     if (this.config_.restrictToScreenSize) {
  176.       const devicePixelRatio =
  177.           this.config_.ignoreDevicePixelRatio ? 1 : window.devicePixelRatio;
  178.       maxHeight = window.screen.height * devicePixelRatio;
  179.       maxWidth = window.screen.width * devicePixelRatio;
  180.     }
  182.     if (this.resizeObserver_ && this.config_.restrictToElementSize) {
  183.       const devicePixelRatio =
  184.           this.config_.ignoreDevicePixelRatio ? 1 : window.devicePixelRatio;
  185.       maxHeight = this.mediaElement_.clientHeight * devicePixelRatio;
  186.       maxWidth = this.mediaElement_.clientWidth * devicePixelRatio;
  187.     }
  189.     // Get sorted Variants.
  190.     let sortedVariants = SimpleAbrManager.filterAndSortVariants_(
  191.         this.config_.restrictions, this.variants_, maxHeight, maxWidth);
  193.     const defaultBandwidthEstimate = this.getDefaultBandwidth_();
  194.     const currentBandwidth = this.bandwidthEstimator_.getBandwidthEstimate(
  195.         defaultBandwidthEstimate);
  197.     if (this.variants_.length && !sortedVariants.length) {
  198.       // If we couldn't meet the ABR restrictions, we should still play
  199.       // something.
  200.       // These restrictions are not "hard" restrictions in the way that
  201.       // top-level or DRM-based restrictions are.  Sort the variants without
  202.       // restrictions and keep just the first (lowest-bandwidth) one.
  203.       shaka.log.warning('No variants met the ABR restrictions. ' +
  204.                         'Choosing a variant by lowest bandwidth.');
  205.       sortedVariants = SimpleAbrManager.filterAndSortVariants_(
  206.           /* restrictions= */ null, this.variants_,
  207.           /* maxHeight= */ Infinity, /* maxWidth= */ Infinity);
  208.       sortedVariants = [sortedVariants[0]];
  209.     }
  211.     // Start by assuming that we will use the first Stream.
  212.     let chosen = sortedVariants[0] || null;
  214.     for (let i = 0; i < sortedVariants.length; i++) {
  215.       const item = sortedVariants[i];
  216.       const playbackRate =
  217.           !isNaN(this.playbackRate_) ? Math.abs(this.playbackRate_) : 1;
  218.       const itemBandwidth = playbackRate * item.bandwidth;
  219.       const minBandwidth =
  220.           itemBandwidth / this.config_.bandwidthDowngradeTarget;
  221.       let next = {bandwidth: Infinity};
  222.       for (let j = i + 1; j < sortedVariants.length; j++) {
  223.         if (item.bandwidth != sortedVariants[j].bandwidth) {
  224.           next = sortedVariants[j];
  225.           break;
  226.         }
  227.       }
  228.       const nextBandwidth = playbackRate * next.bandwidth;
  229.       const maxBandwidth = nextBandwidth / this.config_.bandwidthUpgradeTarget;
  230.       shaka.log.v2('Bandwidth ranges:',
  231.           (itemBandwidth / 1e6).toFixed(3),
  232.           (minBandwidth / 1e6).toFixed(3),
  233.           (maxBandwidth / 1e6).toFixed(3));
  235.       if (currentBandwidth >= minBandwidth &&
  236.           currentBandwidth <= maxBandwidth &&
  237.           chosen.bandwidth != item.bandwidth) {
  238.         chosen = item;
  239.       }
  240.     }
  242.     this.lastTimeChosenMs_ = Date.now();
  243.     return chosen;
  244.   }
  247.   /**
  248.    * @override
  249.    * @export
  250.    */
  251.   enable() {
  252.     this.enabled_ = true;
  253.   }
  256.   /**
  257.    * @override
  258.    * @export
  259.    */
  260.   disable() {
  261.     this.enabled_ = false;
  262.   }
  265.   /**
  266.    * @override
  267.    * @export
  268.    */
  269.   segmentDownloaded(deltaTimeMs, numBytes) {
  270.     shaka.log.v2('Segment downloaded:',
  271.         'deltaTimeMs=' + deltaTimeMs,
  272.         'numBytes=' + numBytes,
  273.         'lastTimeChosenMs=' + this.lastTimeChosenMs_,
  274.         'enabled=' + this.enabled_);
  275.     goog.asserts.assert(deltaTimeMs >= 0, 'expected a non-negative duration');
  276.     this.bandwidthEstimator_.sample(deltaTimeMs, numBytes);
  278.     if ((this.lastTimeChosenMs_ != null) && this.enabled_) {
  279.       this.suggestStreams_();
  280.     }
  281.   }
  284.   /**
  285.    * @override
  286.    * @export
  287.    */
  288.   getBandwidthEstimate() {
  289.     const defaultBandwidthEstimate = this.getDefaultBandwidth_();
  290.     return this.bandwidthEstimator_.getBandwidthEstimate(
  291.         defaultBandwidthEstimate);
  292.   }
  295.   /**
  296.    * @override
  297.    * @export
  298.    */
  299.   setVariants(variants) {
  300.     this.variants_ = variants;
  301.   }
  304.   /**
  305.    * @override
  306.    * @export
  307.    */
  308.   playbackRateChanged(rate) {
  309.     this.playbackRate_ = rate;
  310.   }
  313.   /**
  314.    * @override
  315.    * @export
  316.    */
  317.   setMediaElement(mediaElement) {
  318.     this.mediaElement_ = mediaElement;
  319.     if (this.resizeObserver_) {
  320.       this.resizeObserver_.disconnect();
  321.       this.resizeObserver_ = null;
  322.     }
  323.     if (this.mediaElement_ && 'ResizeObserver' in window) {
  324.       this.resizeObserver_ = new ResizeObserver(() => {
  325.         const SimpleAbrManager = shaka.abr.SimpleAbrManager;
  326.         // Batch up resize changes before checking them.
  327.         this.resizeObserverTimer_.tickAfter(
  328.             /* seconds= */ SimpleAbrManager.RESIZE_OBSERVER_BATCH_TIME);
  329.       });
  330.       this.resizeObserver_.observe(this.mediaElement_);
  331.     }
  332.   }
  335.   /**
  336.    * @override
  337.    * @export
  338.    */
  339.   configure(config) {
  340.     this.config_ = config;
  341.     if (this.bandwidthEstimator_ && this.config_) {
  342.       this.bandwidthEstimator_.configure(this.config_.advanced);
  343.     }
  344.   }
  347.   /**
  348.    * Calls switch_() with the variant chosen by chooseVariant().
  349.    *
  350.    * @private
  351.    */
  352.   suggestStreams_() {
  353.     shaka.log.v2('Suggesting Streams...');
  354.     goog.asserts.assert(this.lastTimeChosenMs_ != null,
  355.         'lastTimeChosenMs_ should not be null');
  357.     if (!this.startupComplete_) {
  358.       // Check if we've got enough data yet.
  359.       if (!this.bandwidthEstimator_.hasGoodEstimate()) {
  360.         shaka.log.v2('Still waiting for a good estimate...');
  361.         return;
  362.       }
  363.       this.startupComplete_ = true;
  364.     } else {
  365.       // Check if we've left the switch interval.
  366.       const now = Date.now();
  367.       const delta = now - this.lastTimeChosenMs_;
  368.       if (delta < this.config_.switchInterval * 1000) {
  369.         shaka.log.v2('Still within switch interval...');
  370.         return;
  371.       }
  372.     }
  374.     const chosenVariant = this.chooseVariant();
  375.     const defaultBandwidthEstimate = this.getDefaultBandwidth_();
  376.     const bandwidthEstimate = this.bandwidthEstimator_.getBandwidthEstimate(
  377.         defaultBandwidthEstimate);
  378.     const currentBandwidthKbps = Math.round(bandwidthEstimate / 1000.0);
  380.     if (chosenVariant) {
  381.       shaka.log.debug(
  382.           'Calling switch_(), bandwidth=' + currentBandwidthKbps + ' kbps');
  383.       // If any of these chosen streams are already chosen, Player will filter
  384.       // them out before passing the choices on to StreamingEngine.
  385.       this.switch_(chosenVariant);
  386.     }
  387.   }
  390.   /**
  391.    * @private
  392.    */
  393.   getDefaultBandwidth_() {
  394.     let defaultBandwidthEstimate = this.config_.defaultBandwidthEstimate;
  396.     // Some browsers implement the Network Information API, which allows
  397.     // retrieving information about a user's network connection.  Tizen 3 has
  398.     // NetworkInformation, but not the downlink attribute.
  399.     if (navigator.connection && navigator.connection.downlink &&
  400.         this.config_.useNetworkInformation) {
  401.       // If it's available, get the bandwidth estimate from the browser (in
  402.       // megabits per second) and use it as defaultBandwidthEstimate.
  403.       defaultBandwidthEstimate = navigator.connection.downlink * 1e6;
  404.     }
  405.     return defaultBandwidthEstimate;
  406.   }
  409.   /**
  410.    * @param {?shaka.extern.Restrictions} restrictions
  411.    * @param {!Array.<shaka.extern.Variant>} variants
  412.    * @param {!number} maxHeight
  413.    * @param {!number} maxWidth
  414.    * @return {!Array.<shaka.extern.Variant>} variants filtered according to
  415.    *   |restrictions| and sorted in ascending order of bandwidth.
  416.    * @private
  417.    */
  418.   static filterAndSortVariants_(restrictions, variants, maxHeight, maxWidth) {
  419.     if (restrictions) {
  420.       variants = variants.filter((variant) => {
  421.         // This was already checked in another scope, but the compiler doesn't
  422.         // seem to understand that.
  423.         goog.asserts.assert(restrictions, 'Restrictions should exist!');
  425.         return shaka.util.StreamUtils.meetsRestrictions(
  426.             variant, restrictions,
  427.             /* maxHwRes= */ {width: maxWidth, height: maxHeight});
  428.       });
  429.     }
  431.     return variants.sort((v1, v2) => {
  432.       return v1.bandwidth - v2.bandwidth;
  433.     });
  434.   }
  435. };
  438. /**
  439.  * The amount of time, in seconds, we wait to batch up rapid resize changes.
  440.  * This allows us to avoid multiple resize events in most cases.
  441.  * @type {number}
  442.  */
  443. shaka.abr.SimpleAbrManager.RESIZE_OBSERVER_BATCH_TIME = 1;