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.enabled_ && (this.config_.restrictToElementSize ||
  111.           this.config_.restrictToScreenSize)) {
  112.         const chosenVariant = this.chooseVariant();
  113.         if (chosenVariant) {
  114.           this.switch_(chosenVariant, this.config_.clearBufferSwitch,
  115.               this.config_.safeMarginSwitch);
  116.         }
  117.       }
  118.     });
  120.     /** @private {Window} */
  121.     this.windowToCheck_ = window;
  123.     if ('documentPictureInPicture' in window) {
  124.       this.eventManager_.listen(
  125.           window.documentPictureInPicture, 'enter', () => {
  126.             this.windowToCheck_ = window.documentPictureInPicture.window;
  127.             if (this.resizeObserverTimer_) {
  128.               this.resizeObserverTimer_.tickNow();
  129.             }
  130.             this.eventManager_.listenOnce(
  131.                 this.windowToCheck_, 'pagehide', () => {
  132.                   this.windowToCheck_ = window;
  133.                   if (this.resizeObserverTimer_) {
  134.                     this.resizeObserverTimer_.tickNow();
  135.                   }
  136.                 });
  137.           });
  138.     }
  140.     /** @private {PictureInPictureWindow} */
  141.     this.pictureInPictureWindow_ = null;
  143.     /** @private {?shaka.util.CmsdManager} */
  144.     this.cmsdManager_ = null;
  145.   }
  148.   /**
  149.    * @override
  150.    * @export
  151.    */
  152.   stop() {
  153.     this.switch_ = null;
  154.     this.enabled_ = false;
  155.     this.variants_ = [];
  156.     this.playbackRate_ = 1;
  157.     this.lastTimeChosenMs_ = null;
  158.     this.mediaElement_ = null;
  160.     if (this.resizeObserver_) {
  161.       this.resizeObserver_.disconnect();
  162.       this.resizeObserver_ = null;
  163.     }
  165.     this.resizeObserverTimer_.stop();
  167.     this.pictureInPictureWindow_ = null;
  169.     this.cmsdManager_ = null;
  171.     // Don't reset |startupComplete_|: if we've left the startup interval, we
  172.     // can start using bandwidth estimates right away after init() is called.
  173.   }
  175.   /**
  176.    * @override
  177.    * @export
  178.    */
  179.   release() {
  180.     // stop() should already have been called for unload
  181.     this.eventManager_.release();
  182.     this.resizeObserverTimer_ = null;
  183.   }
  186.   /**
  187.    * @override
  188.    * @export
  189.    */
  190.   init(switchCallback) {
  191.     this.switch_ = switchCallback;
  192.   }
  195.   /**
  196.    * @return {shaka.extern.Variant}
  197.    * @override
  198.    * @export
  199.    */
  200.   chooseVariant() {
  201.     let maxHeight = Infinity;
  202.     let maxWidth = Infinity;
  204.     if (this.config_.restrictToScreenSize) {
  205.       const devicePixelRatio = this.config_.ignoreDevicePixelRatio ?
  206.           1 : this.windowToCheck_.devicePixelRatio;
  207.       maxHeight = this.windowToCheck_.screen.height * devicePixelRatio;
  208.       maxWidth = this.windowToCheck_.screen.width * devicePixelRatio;
  209.     }
  211.     if (this.resizeObserver_ && this.config_.restrictToElementSize) {
  212.       const devicePixelRatio = this.config_.ignoreDevicePixelRatio ?
  213.           1 : this.windowToCheck_.devicePixelRatio;
  214.       let height = this.mediaElement_.clientHeight;
  215.       let width = this.mediaElement_.clientWidth;
  216.       if (this.pictureInPictureWindow_ && document.pictureInPictureElement &&
  217.           document.pictureInPictureElement == this.mediaElement_) {
  218.         height = this.pictureInPictureWindow_.height;
  219.         width = this.pictureInPictureWindow_.width;
  220.       }
  221.       maxHeight = Math.min(maxHeight, height * devicePixelRatio);
  222.       maxWidth = Math.min(maxWidth, width * devicePixelRatio);
  223.     }
  225.     let normalVariants = this.variants_.filter((variant) => {
  226.       return variant && !shaka.util.StreamUtils.isFastSwitching(variant);
  227.     });
  228.     if (!normalVariants.length) {
  229.       normalVariants = this.variants_;
  230.     }
  232.     let variants = normalVariants;
  233.     if (normalVariants.length != this.variants_.length) {
  234.       variants = this.variants_.filter((variant) => {
  235.         return variant && shaka.util.StreamUtils.isFastSwitching(variant);
  236.       });
  237.     }
  239.     // Get sorted Variants.
  240.     let sortedVariants = this.filterAndSortVariants_(
  241.         this.config_.restrictions, variants,
  242.         /* maxHeight= */ Infinity, /* maxWidth= */ Infinity);
  244.     if (maxHeight != Infinity || maxWidth != Infinity) {
  245.       const resolutions = this.getResolutionList_(sortedVariants);
  246.       for (const resolution of resolutions) {
  247.         if (resolution.height >= maxHeight && resolution.width >= maxWidth) {
  248.           maxHeight = resolution.height;
  249.           maxWidth = resolution.width;
  250.           break;
  251.         }
  252.       }
  254.       sortedVariants = this.filterAndSortVariants_(
  255.           this.config_.restrictions, variants, maxHeight, maxWidth);
  256.     }
  258.     const currentBandwidth = this.getBandwidthEstimate();
  260.     if (variants.length && !sortedVariants.length) {
  261.       // If we couldn't meet the ABR restrictions, we should still play
  262.       // something.
  263.       // These restrictions are not "hard" restrictions in the way that
  264.       // top-level or DRM-based restrictions are.  Sort the variants without
  265.       // restrictions and keep just the first (lowest-bandwidth) one.
  266.       shaka.log.warning('No variants met the ABR restrictions. ' +
  267.                         'Choosing a variant by lowest bandwidth.');
  268.       sortedVariants = this.filterAndSortVariants_(
  269.           /* restrictions= */ null, variants,
  270.           /* maxHeight= */ Infinity, /* maxWidth= */ Infinity);
  271.       sortedVariants = [sortedVariants[0]];
  272.     }
  274.     // Start by assuming that we will use the first Stream.
  275.     let chosen = sortedVariants[0] || null;
  277.     for (let i = 0; i < sortedVariants.length; i++) {
  278.       const item = sortedVariants[i];
  279.       const playbackRate =
  280.           !isNaN(this.playbackRate_) ? Math.abs(this.playbackRate_) : 1;
  281.       const itemBandwidth = playbackRate * item.bandwidth;
  282.       const minBandwidth =
  283.           itemBandwidth / this.config_.bandwidthDowngradeTarget;
  284.       let next = {bandwidth: Infinity};
  285.       for (let j = i + 1; j < sortedVariants.length; j++) {
  286.         if (item.bandwidth != sortedVariants[j].bandwidth) {
  287.           next = sortedVariants[j];
  288.           break;
  289.         }
  290.       }
  291.       const nextBandwidth = playbackRate * next.bandwidth;
  292.       const maxBandwidth = nextBandwidth / this.config_.bandwidthUpgradeTarget;
  293.       shaka.log.v2('Bandwidth ranges:',
  294.           (itemBandwidth / 1e6).toFixed(3),
  295.           (minBandwidth / 1e6).toFixed(3),
  296.           (maxBandwidth / 1e6).toFixed(3));
  298.       if (currentBandwidth >= minBandwidth &&
  299.           currentBandwidth <= maxBandwidth &&
  300.           (chosen.bandwidth != item.bandwidth ||
  301.           this.isSameBandwidthAndHigherResolution_(chosen, item))) {
  302.         chosen = item;
  303.       }
  304.     }
  306.     this.lastTimeChosenMs_ = Date.now();
  307.     return chosen;
  308.   }
  311.   /**
  312.    * @override
  313.    * @export
  314.    */
  315.   enable() {
  316.     this.enabled_ = true;
  317.   }
  320.   /**
  321.    * @override
  322.    * @export
  323.    */
  324.   disable() {
  325.     this.enabled_ = false;
  326.   }
  329.   /**
  330.    * @param {number} deltaTimeMs The duration, in milliseconds, that the request
  331.    *     took to complete.
  332.    * @param {number} numBytes The total number of bytes transferred.
  333.    * @param {boolean} allowSwitch Indicate if the segment is allowed to switch
  334.    *     to another stream.
  335.    * @param {shaka.extern.Request=} request
  336.    *     A reference to the request
  337.    * @param {shaka.extern.RequestContext=} context
  338.    *     A reference to the request context
  339.    * @override
  340.    * @export
  341.    */
  342.   segmentDownloaded(deltaTimeMs, numBytes, allowSwitch, request, context) {
  343.     let realTimeMs = deltaTimeMs;
  344.     if (this.config_.removeLatencyFromFirstPacketTime &&
  345.         request && request.packetNumber === 1 && request.timeToFirstByte) {
  346.       realTimeMs = deltaTimeMs - request.timeToFirstByte;
  347.     }
  348.     if (realTimeMs < this.config_.cacheLoadThreshold) {
  349.       // The time indicates that it could be a cache response, so we should
  350.       // ignore this value.
  351.       return;
  352.     }
  353.     shaka.log.v2('Segment downloaded:',
  354.         'contentType=' + (request && request.contentType),
  355.         'deltaTimeMs=' + realTimeMs,
  356.         'numBytes=' + numBytes,
  357.         'lastTimeChosenMs=' + this.lastTimeChosenMs_,
  358.         'enabled=' + this.enabled_);
  359.     goog.asserts.assert(realTimeMs >= 0, 'expected a non-negative duration');
  360.     this.bandwidthEstimator_.sample(realTimeMs, numBytes);
  362.     if (allowSwitch && (this.lastTimeChosenMs_ != null) && this.enabled_) {
  363.       this.suggestStreams_();
  364.     }
  365.   }
  368.   /**
  369.    * @override
  370.    * @export
  371.    */
  372.   trySuggestStreams() {
  373.     if ((this.lastTimeChosenMs_ != null) && this.enabled_) {
  374.       this.suggestStreams_();
  375.     }
  376.   }
  379.   /**
  380.    * @override
  381.    * @export
  382.    */
  383.   getBandwidthEstimate() {
  384.     const defaultBandwidthEstimate = this.getDefaultBandwidth_();
  385.     if (navigator.connection && navigator.connection.downlink &&
  386.         this.config_.useNetworkInformation &&
  387.         this.config_.preferNetworkInformationBandwidth) {
  388.       return defaultBandwidthEstimate;
  389.     }
  390.     const bandwidthEstimate = this.bandwidthEstimator_.getBandwidthEstimate(
  391.         defaultBandwidthEstimate);
  392.     if (this.cmsdManager_) {
  393.       return this.cmsdManager_.getBandwidthEstimate(bandwidthEstimate);
  394.     }
  395.     return bandwidthEstimate;
  396.   }
  399.   /**
  400.    * @override
  401.    * @export
  402.    */
  403.   setVariants(variants) {
  404.     this.variants_ = variants;
  405.   }
  408.   /**
  409.    * @override
  410.    * @export
  411.    */
  412.   playbackRateChanged(rate) {
  413.     this.playbackRate_ = rate;
  414.   }
  417.   /**
  418.    * @override
  419.    * @export
  420.    */
  421.   setMediaElement(mediaElement) {
  422.     this.mediaElement_ = mediaElement;
  423.     if (this.resizeObserver_) {
  424.       this.resizeObserver_.disconnect();
  425.       this.resizeObserver_ = null;
  426.     }
  427.     const onResize = () => {
  428.       const SimpleAbrManager = shaka.abr.SimpleAbrManager;
  429.       // Batch up resize changes before checking them.
  430.       this.resizeObserverTimer_.tickAfter(
  431.           /* seconds= */ SimpleAbrManager.RESIZE_OBSERVER_BATCH_TIME);
  432.     };
  433.     if (this.mediaElement_ && 'ResizeObserver' in window) {
  434.       this.resizeObserver_ = new ResizeObserver(onResize);
  435.       this.resizeObserver_.observe(this.mediaElement_);
  436.     }
  438.     this.eventManager_.listen(mediaElement, 'enterpictureinpicture', (e) => {
  439.       const event = /** @type {PictureInPictureEvent} */(e);
  440.       if (event.pictureInPictureWindow) {
  441.         this.pictureInPictureWindow_ = event.pictureInPictureWindow;
  442.         this.eventManager_.listen(
  443.             this.pictureInPictureWindow_, 'resize', onResize);
  444.       }
  445.     });
  446.     this.eventManager_.listen(mediaElement, 'leavepictureinpicture', () => {
  447.       if (this.pictureInPictureWindow_) {
  448.         this.eventManager_.unlisten(
  449.             this.pictureInPictureWindow_, 'resize', onResize);
  450.       }
  451.       this.pictureInPictureWindow_ = null;
  452.     });
  453.   }
  456.   /**
  457.    * @override
  458.    * @export
  459.    */
  460.   setCmsdManager(cmsdManager) {
  461.     this.cmsdManager_ = cmsdManager;
  462.   }
  465.   /**
  466.    * @override
  467.    * @export
  468.    */
  469.   configure(config) {
  470.     this.config_ = config;
  471.     if (this.bandwidthEstimator_ && this.config_) {
  472.       this.bandwidthEstimator_.configure(this.config_.advanced);
  473.     }
  474.   }
  477.   /**
  478.    * Calls switch_() with the variant chosen by chooseVariant().
  479.    *
  480.    * @private
  481.    */
  482.   suggestStreams_() {
  483.     shaka.log.v2('Suggesting Streams...');
  484.     goog.asserts.assert(this.lastTimeChosenMs_ != null,
  485.         'lastTimeChosenMs_ should not be null');
  487.     if (!this.startupComplete_) {
  488.       // Check if we've got enough data yet.
  489.       if (!this.bandwidthEstimator_.hasGoodEstimate()) {
  490.         shaka.log.v2('Still waiting for a good estimate...');
  491.         return;
  492.       }
  493.       this.startupComplete_ = true;
  495.       this.lastTimeChosenMs_ -=
  496.           (this.config_.switchInterval - this.config_.minTimeToSwitch) * 1000;
  497.     }
  499.     // Check if we've left the switch interval.
  500.     const now = Date.now();
  501.     const delta = now - this.lastTimeChosenMs_;
  502.     if (delta < this.config_.switchInterval * 1000) {
  503.       shaka.log.v2('Still within switch interval...');
  504.       return;
  505.     }
  507.     const chosenVariant = this.chooseVariant();
  508.     const bandwidthEstimate = this.getBandwidthEstimate();
  509.     const currentBandwidthKbps = Math.round(bandwidthEstimate / 1000.0);
  511.     if (chosenVariant) {
  512.       shaka.log.debug(
  513.           'Calling switch_(), bandwidth=' + currentBandwidthKbps + ' kbps');
  514.       // If any of these chosen streams are already chosen, Player will filter
  515.       // them out before passing the choices on to StreamingEngine.
  516.       this.switch_(chosenVariant, this.config_.clearBufferSwitch,
  517.           this.config_.safeMarginSwitch);
  518.     }
  519.   }
  522.   /**
  523.    * @private
  524.    */
  525.   getDefaultBandwidth_() {
  526.     let defaultBandwidthEstimate = this.config_.defaultBandwidthEstimate;
  528.     // Some browsers implement the Network Information API, which allows
  529.     // retrieving information about a user's network connection.  Tizen 3 has
  530.     // NetworkInformation, but not the downlink attribute.
  531.     if (navigator.connection && navigator.connection.downlink &&
  532.         this.config_.useNetworkInformation) {
  533.       // If it's available, get the bandwidth estimate from the browser (in
  534.       // megabits per second) and use it as defaultBandwidthEstimate.
  535.       defaultBandwidthEstimate = navigator.connection.downlink * 1e6;
  536.     }
  537.     return defaultBandwidthEstimate;
  538.   }
  541.   /**
  542.    * @param {?shaka.extern.Restrictions} restrictions
  543.    * @param {!Array<shaka.extern.Variant>} variants
  544.    * @param {!number} maxHeight
  545.    * @param {!number} maxWidth
  546.    * @return {!Array<shaka.extern.Variant>} variants filtered according to
  547.    *   |restrictions| and sorted in ascending order of bandwidth.
  548.    * @private
  549.    */
  550.   filterAndSortVariants_(restrictions, variants, maxHeight, maxWidth) {
  551.     if (this.cmsdManager_) {
  552.       const maxBitrate = this.cmsdManager_.getMaxBitrate();
  553.       if (maxBitrate) {
  554.         variants = variants.filter((variant) => {
  555.           if (!variant.bandwidth || !maxBitrate) {
  556.             return true;
  557.           }
  558.           return variant.bandwidth <= maxBitrate;
  559.         });
  560.       }
  561.     }
  563.     if (restrictions) {
  564.       variants = variants.filter((variant) => {
  565.         // This was already checked in another scope, but the compiler doesn't
  566.         // seem to understand that.
  567.         goog.asserts.assert(restrictions, 'Restrictions should exist!');
  569.         return shaka.util.StreamUtils.meetsRestrictions(
  570.             variant, restrictions,
  571.             /* maxHwRes= */ {width: maxWidth, height: maxHeight});
  572.       });
  573.     }
  575.     return variants.sort((v1, v2) => {
  576.       return v1.bandwidth - v2.bandwidth;
  577.     });
  578.   }
  580.   /**
  581.    * @param {!Array<shaka.extern.Variant>} variants
  582.    * @return {!Array<{height: number, width: number}>}
  583.    * @private
  584.    */
  585.   getResolutionList_(variants) {
  586.     const resolutions = [];
  587.     for (const variant of variants) {
  588.       const video = variant.video;
  589.       if (!video || !video.height || !video.width) {
  590.         continue;
  591.       }
  592.       resolutions.push({
  593.         height: video.height,
  594.         width: video.width,
  595.       });
  596.     }
  598.     return resolutions.sort((v1, v2) => {
  599.       return v1.width - v2.width;
  600.     });
  601.   }
  603.   /**
  604.    * @param {shaka.extern.Variant} chosenVariant
  605.    * @param {shaka.extern.Variant} newVariant
  606.    * @return {boolean}
  607.    * @private
  608.    */
  609.   isSameBandwidthAndHigherResolution_(chosenVariant, newVariant) {
  610.     if (chosenVariant.bandwidth != newVariant.bandwidth) {
  611.       return false;
  612.     }
  613.     if (!chosenVariant.video || !newVariant.video) {
  614.       return false;
  615.     }
  616.     return chosenVariant.video.width < newVariant.video.width ||
  617.         chosenVariant.video.height < newVariant.video.height;
  618.   }
  619. };
  622. /**
  623.  * The amount of time, in seconds, we wait to batch up rapid resize changes.
  624.  * This allows us to avoid multiple resize events in most cases.
  625.  * @type {number}
  626.  */
  627. shaka.abr.SimpleAbrManager.RESIZE_OBSERVER_BATCH_TIME = 1;