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('goog.asserts');
  10. goog.require('shaka.abr.EwmaBandwidthEstimator');
  11. goog.require('shaka.log');
  12. goog.require('shaka.util.EventManager');
  13. goog.require('shaka.util.IReleasable');
  14. goog.require('shaka.util.StreamUtils');
  15. goog.require('shaka.util.Timer');
  17. goog.requireType('shaka.util.CmsdManager');
  20. /**
  21.  * @summary
  22.  * <p>
  23.  * This defines the default ABR manager for the Player.  An instance of this
  24.  * class is used when no ABR manager is given.
  25.  * </p>
  26.  * <p>
  27.  * The behavior of this class is to take throughput samples using
  28.  * segmentDownloaded to estimate the current network bandwidth.  Then it will
  29.  * use that to choose the streams that best fit the current bandwidth.  It will
  30.  * always pick the highest bandwidth variant it thinks can be played.
  31.  * </p>
  32.  * <p>
  33.  * After initial choices are made, this class will call switchCallback() when
  34.  * there is a better choice.  switchCallback() will not be called more than once
  35.  * per ({@link shaka.abr.SimpleAbrManager.SWITCH_INTERVAL_MS}).
  36.  * </p>
  37.  *
  38.  * @implements {shaka.extern.AbrManager}
  39.  * @implements {shaka.util.IReleasable}
  40.  * @export
  41.  */
  42. shaka.abr.SimpleAbrManager = class {
  43.   /** */
  44.   constructor() {
  45.     /** @private {?shaka.extern.AbrManager.SwitchCallback} */
  46.     this.switch_ = null;
  48.     /** @private {boolean} */
  49.     this.enabled_ = false;
  51.     /** @private {shaka.abr.EwmaBandwidthEstimator} */
  52.     this.bandwidthEstimator_ = new shaka.abr.EwmaBandwidthEstimator();
  54.     /** @private {!shaka.util.EventManager} */
  55.     this.eventManager_ = new shaka.util.EventManager();
  57.     // Some browsers implement the Network Information API, which allows
  58.     // retrieving information about a user's network connection. We listen
  59.     // to the change event to be able to make quick changes in case the type
  60.     // of connectivity changes.
  61.     if (navigator.connection && navigator.connection.addEventListener) {
  62.       this.eventManager_.listen(
  63.           /** @type {EventTarget} */(navigator.connection),
  64.           'change',
  65.           () => {
  66.             if (this.enabled_ && this.config_.useNetworkInformation) {
  67.               this.bandwidthEstimator_ = new shaka.abr.EwmaBandwidthEstimator();
  68.               if (this.config_) {
  69.                 this.bandwidthEstimator_.configure(this.config_.advanced);
  70.               }
  71.               const chosenVariant = this.chooseVariant();
  72.               if (chosenVariant && navigator.onLine) {
  73.                 this.switch_(chosenVariant, this.config_.clearBufferSwitch,
  74.                     this.config_.safeMarginSwitch);
  75.               }
  76.             }
  77.           });
  78.     }
  80.     /**
  81.      * A filtered list of Variants to choose from.
  82.      * @private {!Array.<!shaka.extern.Variant>}
  83.      */
  84.     this.variants_ = [];
  86.     /** @private {number} */
  87.     this.playbackRate_ = 1;
  89.     /** @private {boolean} */
  90.     this.startupComplete_ = false;
  92.     /**
  93.      * The last wall-clock time, in milliseconds, when streams were chosen.
  94.      *
  95.      * @private {?number}
  96.      */
  97.     this.lastTimeChosenMs_ = null;
  99.     /** @private {?shaka.extern.AbrConfiguration} */
  100.     this.config_ = null;
  102.     /** @private {HTMLMediaElement} */
  103.     this.mediaElement_ = null;
  105.     /** @private {ResizeObserver} */
  106.     this.resizeObserver_ = null;
  108.     /** @private {shaka.util.Timer} */
  109.     this.resizeObserverTimer_ = new shaka.util.Timer(() => {
  110.       if (this.config_.restrictToElementSize) {
  111.         const chosenVariant = this.chooseVariant();
  112.         if (chosenVariant) {
  113.           this.switch_(chosenVariant, this.config_.clearBufferSwitch,
  114.               this.config_.safeMarginSwitch);
  115.         }
  116.       }
  117.     });
  119.     /** @private {?shaka.util.CmsdManager} */
  120.     this.cmsdManager_ = null;
  121.   }
  124.   /**
  125.    * @override
  126.    * @export
  127.    */
  128.   stop() {
  129.     this.switch_ = null;
  130.     this.enabled_ = false;
  131.     this.variants_ = [];
  132.     this.playbackRate_ = 1;
  133.     this.lastTimeChosenMs_ = null;
  134.     this.mediaElement_ = null;
  136.     if (this.resizeObserver_) {
  137.       this.resizeObserver_.disconnect();
  138.       this.resizeObserver_ = null;
  139.     }
  141.     this.resizeObserverTimer_.stop();
  143.     this.cmsdManager_ = null;
  145.     // Don't reset |startupComplete_|: if we've left the startup interval, we
  146.     // can start using bandwidth estimates right away after init() is called.
  147.   }
  149.   /**
  150.    * @override
  151.    * @export
  152.    */
  153.   release() {
  154.     // stop() should already have been called for unload
  155.     this.eventManager_.release();
  156.     this.resizeObserverTimer_ = null;
  157.   }
  160.   /**
  161.    * @override
  162.    * @export
  163.    */
  164.   init(switchCallback) {
  165.     this.switch_ = switchCallback;
  166.   }
  169.   /**
  170.    * @param {boolean=} preferFastSwitching
  171.    * @return {shaka.extern.Variant}
  172.    * @override
  173.    * @export
  174.    */
  175.   chooseVariant(preferFastSwitching = false) {
  176.     let maxHeight = Infinity;
  177.     let maxWidth = Infinity;
  179.     if (this.config_.restrictToScreenSize) {
  180.       const devicePixelRatio =
  181.           this.config_.ignoreDevicePixelRatio ? 1 : window.devicePixelRatio;
  182.       maxHeight = window.screen.height * devicePixelRatio;
  183.       maxWidth = window.screen.width * devicePixelRatio;
  184.     }
  186.     if (this.resizeObserver_ && this.config_.restrictToElementSize) {
  187.       const devicePixelRatio =
  188.           this.config_.ignoreDevicePixelRatio ? 1 : window.devicePixelRatio;
  189.       maxHeight = Math.min(
  190.           maxHeight, this.mediaElement_.clientHeight * devicePixelRatio);
  191.       maxWidth = Math.min(
  192.           maxWidth, this.mediaElement_.clientWidth * devicePixelRatio);
  193.     }
  195.     let normalVariants = this.variants_.filter((variant) => {
  196.       return variant && !shaka.util.StreamUtils.isFastSwitching(variant);
  197.     });
  198.     if (!normalVariants.length) {
  199.       normalVariants = this.variants_;
  200.     }
  202.     let variants = normalVariants;
  203.     if (preferFastSwitching &&
  204.         normalVariants.length != this.variants_.length) {
  205.       variants = this.variants_.filter((variant) => {
  206.         return variant && shaka.util.StreamUtils.isFastSwitching(variant);
  207.       });
  208.     }
  210.     // Get sorted Variants.
  211.     let sortedVariants = this.filterAndSortVariants_(
  212.         this.config_.restrictions, variants,
  213.         /* maxHeight= */ Infinity, /* maxWidth= */ Infinity);
  215.     if (maxHeight != Infinity || maxWidth != Infinity) {
  216.       const resolutions = this.getResolutionList_(sortedVariants);
  217.       for (const resolution of resolutions) {
  218.         if (resolution.height >= maxHeight && resolution.width >= maxWidth) {
  219.           maxHeight = resolution.height;
  220.           maxWidth = resolution.width;
  221.           break;
  222.         }
  223.       }
  225.       sortedVariants = this.filterAndSortVariants_(
  226.           this.config_.restrictions, variants, maxHeight, maxWidth);
  227.     }
  229.     const currentBandwidth = this.getBandwidthEstimate();
  231.     if (variants.length && !sortedVariants.length) {
  232.       // If we couldn't meet the ABR restrictions, we should still play
  233.       // something.
  234.       // These restrictions are not "hard" restrictions in the way that
  235.       // top-level or DRM-based restrictions are.  Sort the variants without
  236.       // restrictions and keep just the first (lowest-bandwidth) one.
  237.       shaka.log.warning('No variants met the ABR restrictions. ' +
  238.                         'Choosing a variant by lowest bandwidth.');
  239.       sortedVariants = this.filterAndSortVariants_(
  240.           /* restrictions= */ null, variants,
  241.           /* maxHeight= */ Infinity, /* maxWidth= */ Infinity);
  242.       sortedVariants = [sortedVariants[0]];
  243.     }
  245.     // Start by assuming that we will use the first Stream.
  246.     let chosen = sortedVariants[0] || null;
  248.     for (let i = 0; i < sortedVariants.length; i++) {
  249.       const item = sortedVariants[i];
  250.       const playbackRate =
  251.           !isNaN(this.playbackRate_) ? Math.abs(this.playbackRate_) : 1;
  252.       const itemBandwidth = playbackRate * item.bandwidth;
  253.       const minBandwidth =
  254.           itemBandwidth / this.config_.bandwidthDowngradeTarget;
  255.       let next = {bandwidth: Infinity};
  256.       for (let j = i + 1; j < sortedVariants.length; j++) {
  257.         if (item.bandwidth != sortedVariants[j].bandwidth) {
  258.           next = sortedVariants[j];
  259.           break;
  260.         }
  261.       }
  262.       const nextBandwidth = playbackRate * next.bandwidth;
  263.       const maxBandwidth = nextBandwidth / this.config_.bandwidthUpgradeTarget;
  264.       shaka.log.v2('Bandwidth ranges:',
  265.           (itemBandwidth / 1e6).toFixed(3),
  266.           (minBandwidth / 1e6).toFixed(3),
  267.           (maxBandwidth / 1e6).toFixed(3));
  269.       if (currentBandwidth >= minBandwidth &&
  270.           currentBandwidth <= maxBandwidth &&
  271.           (chosen.bandwidth != item.bandwidth ||
  272.           this.isSameBandwidthAndHigherResolution_(chosen, item))) {
  273.         chosen = item;
  274.       }
  275.     }
  277.     this.lastTimeChosenMs_ = Date.now();
  278.     return chosen;
  279.   }
  282.   /**
  283.    * @override
  284.    * @export
  285.    */
  286.   enable() {
  287.     this.enabled_ = true;
  288.   }
  291.   /**
  292.    * @override
  293.    * @export
  294.    */
  295.   disable() {
  296.     this.enabled_ = false;
  297.   }
  300.   /**
  301.    * @param {number} deltaTimeMs The duration, in milliseconds, that the request
  302.    *     took to complete.
  303.    * @param {number} numBytes The total number of bytes transferred.
  304.    * @param {boolean} allowSwitch Indicate if the segment is allowed to switch
  305.    *     to another stream.
  306.    * @param {shaka.extern.Request=} request
  307.    *     A reference to the request
  308.    * @override
  309.    * @export
  310.    */
  311.   segmentDownloaded(deltaTimeMs, numBytes, allowSwitch, request) {
  312.     if (deltaTimeMs < this.config_.cacheLoadThreshold) {
  313.       // The time indicates that it could be a cache response, so we should
  314.       // ignore this value.
  315.       return;
  316.     }
  317.     shaka.log.v2('Segment downloaded:',
  318.         'contentType=' + (request && request.contentType),
  319.         'deltaTimeMs=' + deltaTimeMs,
  320.         'numBytes=' + numBytes,
  321.         'lastTimeChosenMs=' + this.lastTimeChosenMs_,
  322.         'enabled=' + this.enabled_);
  323.     goog.asserts.assert(deltaTimeMs >= 0, 'expected a non-negative duration');
  324.     this.bandwidthEstimator_.sample(deltaTimeMs, numBytes);
  326.     if (allowSwitch && (this.lastTimeChosenMs_ != null) && this.enabled_) {
  327.       this.suggestStreams_();
  328.     }
  329.   }
  332.   /**
  333.    * @override
  334.    * @export
  335.    */
  336.   trySuggestStreams() {
  337.     if ((this.lastTimeChosenMs_ != null) && this.enabled_) {
  338.       this.suggestStreams_();
  339.     }
  340.   }
  343.   /**
  344.    * @override
  345.    * @export
  346.    */
  347.   getBandwidthEstimate() {
  348.     const defaultBandwidthEstimate = this.getDefaultBandwidth_();
  349.     const bandwidthEstimate = this.bandwidthEstimator_.getBandwidthEstimate(
  350.         defaultBandwidthEstimate);
  351.     if (this.cmsdManager_) {
  352.       return this.cmsdManager_.getBandwidthEstimate(bandwidthEstimate);
  353.     }
  354.     return bandwidthEstimate;
  355.   }
  358.   /**
  359.    * @override
  360.    * @export
  361.    */
  362.   setVariants(variants) {
  363.     this.variants_ = variants;
  364.   }
  367.   /**
  368.    * @override
  369.    * @export
  370.    */
  371.   playbackRateChanged(rate) {
  372.     this.playbackRate_ = rate;
  373.   }
  376.   /**
  377.    * @override
  378.    * @export
  379.    */
  380.   setMediaElement(mediaElement) {
  381.     this.mediaElement_ = mediaElement;
  382.     if (this.resizeObserver_) {
  383.       this.resizeObserver_.disconnect();
  384.       this.resizeObserver_ = null;
  385.     }
  386.     if (this.mediaElement_ && 'ResizeObserver' in window) {
  387.       this.resizeObserver_ = new ResizeObserver(() => {
  388.         const SimpleAbrManager = shaka.abr.SimpleAbrManager;
  389.         // Batch up resize changes before checking them.
  390.         this.resizeObserverTimer_.tickAfter(
  391.             /* seconds= */ SimpleAbrManager.RESIZE_OBSERVER_BATCH_TIME);
  392.       });
  393.       this.resizeObserver_.observe(this.mediaElement_);
  394.     }
  395.   }
  398.   /**
  399.    * @override
  400.    * @export
  401.    */
  402.   setCmsdManager(cmsdManager) {
  403.     this.cmsdManager_ = cmsdManager;
  404.   }
  407.   /**
  408.    * @override
  409.    * @export
  410.    */
  411.   configure(config) {
  412.     this.config_ = config;
  413.     if (this.bandwidthEstimator_ && this.config_) {
  414.       this.bandwidthEstimator_.configure(this.config_.advanced);
  415.     }
  416.   }
  419.   /**
  420.    * Calls switch_() with the variant chosen by chooseVariant().
  421.    *
  422.    * @private
  423.    */
  424.   suggestStreams_() {
  425.     shaka.log.v2('Suggesting Streams...');
  426.     goog.asserts.assert(this.lastTimeChosenMs_ != null,
  427.         'lastTimeChosenMs_ should not be null');
  429.     if (!this.startupComplete_) {
  430.       // Check if we've got enough data yet.
  431.       if (!this.bandwidthEstimator_.hasGoodEstimate()) {
  432.         shaka.log.v2('Still waiting for a good estimate...');
  433.         return;
  434.       }
  435.       this.startupComplete_ = true;
  437.       this.lastTimeChosenMs_ -=
  438.           (this.config_.switchInterval - this.config_.minTimeToSwitch) * 1000;
  439.     }
  441.     // Check if we've left the switch interval.
  442.     const now = Date.now();
  443.     const delta = now - this.lastTimeChosenMs_;
  444.     if (delta < this.config_.switchInterval * 1000) {
  445.       shaka.log.v2('Still within switch interval...');
  446.       return;
  447.     }
  449.     const chosenVariant = this.chooseVariant();
  450.     const bandwidthEstimate = this.getBandwidthEstimate();
  451.     const currentBandwidthKbps = Math.round(bandwidthEstimate / 1000.0);
  453.     if (chosenVariant) {
  454.       shaka.log.debug(
  455.           'Calling switch_(), bandwidth=' + currentBandwidthKbps + ' kbps');
  456.       // If any of these chosen streams are already chosen, Player will filter
  457.       // them out before passing the choices on to StreamingEngine.
  458.       this.switch_(chosenVariant, this.config_.clearBufferSwitch,
  459.           this.config_.safeMarginSwitch);
  460.     }
  461.   }
  464.   /**
  465.    * @private
  466.    */
  467.   getDefaultBandwidth_() {
  468.     let defaultBandwidthEstimate = this.config_.defaultBandwidthEstimate;
  470.     // Some browsers implement the Network Information API, which allows
  471.     // retrieving information about a user's network connection.  Tizen 3 has
  472.     // NetworkInformation, but not the downlink attribute.
  473.     if (navigator.connection && navigator.connection.downlink &&
  474.         this.config_.useNetworkInformation) {
  475.       // If it's available, get the bandwidth estimate from the browser (in
  476.       // megabits per second) and use it as defaultBandwidthEstimate.
  477.       defaultBandwidthEstimate = navigator.connection.downlink * 1e6;
  478.     }
  479.     return defaultBandwidthEstimate;
  480.   }
  483.   /**
  484.    * @param {?shaka.extern.Restrictions} restrictions
  485.    * @param {!Array.<shaka.extern.Variant>} variants
  486.    * @param {!number} maxHeight
  487.    * @param {!number} maxWidth
  488.    * @return {!Array.<shaka.extern.Variant>} variants filtered according to
  489.    *   |restrictions| and sorted in ascending order of bandwidth.
  490.    * @private
  491.    */
  492.   filterAndSortVariants_(restrictions, variants, maxHeight, maxWidth) {
  493.     if (this.cmsdManager_) {
  494.       const maxBitrate = this.cmsdManager_.getMaxBitrate();
  495.       if (maxBitrate) {
  496.         variants = variants.filter((variant) => {
  497.           if (!variant.bandwidth || !maxBitrate) {
  498.             return true;
  499.           }
  500.           return variant.bandwidth <= maxBitrate;
  501.         });
  502.       }
  503.     }
  505.     if (restrictions) {
  506.       variants = variants.filter((variant) => {
  507.         // This was already checked in another scope, but the compiler doesn't
  508.         // seem to understand that.
  509.         goog.asserts.assert(restrictions, 'Restrictions should exist!');
  511.         return shaka.util.StreamUtils.meetsRestrictions(
  512.             variant, restrictions,
  513.             /* maxHwRes= */ {width: maxWidth, height: maxHeight});
  514.       });
  515.     }
  517.     return variants.sort((v1, v2) => {
  518.       return v1.bandwidth - v2.bandwidth;
  519.     });
  520.   }
  522.   /**
  523.    * @param {!Array.<shaka.extern.Variant>} variants
  524.    * @return {!Array.<{height: number, width: number}>}
  525.    * @private
  526.    */
  527.   getResolutionList_(variants) {
  528.     const resolutions = [];
  529.     for (const variant of variants) {
  530.       const video = variant.video;
  531.       if (!video || !video.height || !video.width) {
  532.         continue;
  533.       }
  534.       resolutions.push({
  535.         height: video.height,
  536.         width: video.width,
  537.       });
  538.     }
  540.     return resolutions.sort((v1, v2) => {
  541.       return v1.width - v2.width;
  542.     });
  543.   }
  545.   /**
  546.    * @param {shaka.extern.Variant} chosenVariant
  547.    * @param {shaka.extern.Variant} newVariant
  548.    * @return {boolean}
  549.    * @private
  550.    */
  551.   isSameBandwidthAndHigherResolution_(chosenVariant, newVariant) {
  552.     if (chosenVariant.bandwidth != newVariant.bandwidth) {
  553.       return false;
  554.     }
  555.     if (!chosenVariant.video || !newVariant.video) {
  556.       return false;
  557.     }
  558.     return chosenVariant.video.width < newVariant.video.width ||
  559.         chosenVariant.video.height < newVariant.video.height;
  560.   }
  561. };
  564. /**
  565.  * The amount of time, in seconds, we wait to batch up rapid resize changes.
  566.  * This allows us to avoid multiple resize events in most cases.
  567.  * @type {number}
  568.  */
  569. shaka.abr.SimpleAbrManager.RESIZE_OBSERVER_BATCH_TIME = 1;