Source: externs/shaka/abr_manager.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  8. /**
  9.  * @externs
  10.  */
  13. /**
  14.  * An object which selects Streams from a set of possible choices.  This also
  15.  * watches for system changes to automatically adapt for the current streaming
  16.  * requirements.  For example, when the network slows down, this class is in
  17.  * charge of telling the Player which streams to switch to in order to reduce
  18.  * the required bandwidth.
  19.  *
  20.  * This class is given a set of streams to choose from when the Player starts
  21.  * up.  This class should store these and use them to make future decisions
  22.  * about ABR.  It is up to this class how those decisions are made.  All the
  23.  * Player will do is tell this class what streams to choose from.
  24.  *
  25.  * @interface
  26.  * @exportDoc
  27.  */
  28. shaka.extern.AbrManager = class {
  29.   constructor() {}
  31.   /**
  32.    * Initializes the AbrManager.
  33.    *
  34.    * @param {shaka.extern.AbrManager.SwitchCallback} switchCallback
  35.    * @exportDoc
  36.    */
  37.   init(switchCallback) {}
  39.   /**
  40.    * Stops any background timers and frees any objects held by this instance.
  41.    * This will only be called after a call to init.
  42.    *
  43.    * @exportDoc
  44.    */
  45.   stop() {}
  47.   /**
  48.    * Request that this object release all internal references.
  49.    * @exportDoc
  50.    */
  51.   release() {}
  53.   /**
  54.    * Updates manager's variants collection.
  55.    * Returns true if the variants are updated. Returns false if the variants
  56.    * are equal.
  57.    *
  58.    * @param {!Array<!shaka.extern.Variant>} variants
  59.    * @return {boolean}
  60.    * @exportDoc
  61.    */
  62.   setVariants(variants) {}
  64.   /**
  65.    * Chooses one variant to switch to.  Called by the Player.
  66.    *
  67.    * @param {boolean=} preferFastSwitching If not provided meant "avoid fast
  68.    * switching if possible".
  69.    * @return {shaka.extern.Variant}
  70.    * @exportDoc
  71.    */
  72.   chooseVariant(preferFastSwitching) {}
  74.   /**
  75.    * Enables automatic Variant choices from the last ones passed to setVariants.
  76.    * After this, the AbrManager may call switchCallback() at any time.
  77.    *
  78.    * @exportDoc
  79.    */
  80.   enable() {}
  82.   /**
  83.    * Disables automatic Stream suggestions. After this, the AbrManager may not
  84.    * call switchCallback().
  85.    *
  86.    * @exportDoc
  87.    */
  88.   disable() {}
  90.   /**
  91.    * Notifies the AbrManager that a segment has been downloaded (includes MP4
  92.    * SIDX data, WebM Cues data, initialization segments, and media segments).
  93.    *
  94.    * @param {number} deltaTimeMs The duration, in milliseconds, that the request
  95.    *     took to complete.
  96.    * @param {number} numBytes The total number of bytes transferred.
  97.    * @param {boolean} allowSwitch Indicate if the segment is allowed to switch
  98.    *     to another stream.
  99.    * @param {shaka.extern.Request=} request
  100.    *     A reference to the request
  101.    * @param {shaka.extern.RequestContext=} context
  102.    *     A reference to the request context
  103.    * @exportDoc
  104.    */
  105.   segmentDownloaded(deltaTimeMs, numBytes, allowSwitch, request, context) {}
  107.   /**
  108.    * Notifies the ABR that it is a time to suggest new streams. This is used by
  109.    * the Player when it finishes adding the last partial segment of a fast
  110.    * switching stream.
  111.    *
  112.    * @exportDoc
  113.    */
  114.   trySuggestStreams() {}
  116.   /**
  117.    * Gets an estimate of the current bandwidth in bit/sec.  This is used by the
  118.    * Player to generate stats.
  119.    *
  120.    * @return {number}
  121.    * @exportDoc
  122.    */
  123.   getBandwidthEstimate() {}
  125.   /**
  126.    * Updates manager playback rate.
  127.    *
  128.    * @param {number} rate
  129.    * @exportDoc
  130.    */
  131.   playbackRateChanged(rate) {}
  133.   /**
  134.    * Set media element.
  135.    *
  136.    * @param {HTMLMediaElement} mediaElement
  137.    * @exportDoc
  138.    */
  139.   setMediaElement(mediaElement) {}
  141.   /**
  142.    * Set CMSD manager.
  143.    *
  144.    * @param {shaka.util.CmsdManager} cmsdManager
  145.    * @exportDoc
  146.    */
  147.   setCmsdManager(cmsdManager) {}
  149.   /**
  150.    * Sets the ABR configuration.
  151.    *
  152.    * It is the responsibility of the AbrManager implementation to implement the
  153.    * restrictions behavior described in shaka.extern.AbrConfiguration.
  154.    *
  155.    * @param {shaka.extern.AbrConfiguration} config
  156.    * @exportDoc
  157.    */
  158.   configure(config) {}
  159. };
  162. /**
  163.  * A callback into the Player that should be called when the AbrManager decides
  164.  * it's time to change to a different variant.
  165.  *
  166.  * The first argument is a variant to switch to.
  167.  *
  168.  * The second argument is an optional boolean. If true, all data will be removed
  169.  * from the buffer, which will result in a buffering event. Unless a third
  170.  * argument is passed.
  171.  *
  172.  * The third argument in an optional number that specifies how much data (in
  173.  * seconds) should be retained when clearing the buffer. This can help achieve
  174.  * a fast switch that doesn't involve a buffering event. A minimum of two video
  175.  * segments should always be kept buffered to avoid temporary hiccups.
  176.  *
  177.  * @typedef {function(shaka.extern.Variant, boolean=, number=)}
  178.  * @exportDoc
  179.  */
  180. shaka.extern.AbrManager.SwitchCallback;
  183. /**
  184.  * A factory for creating the abr manager.
  185.  *
  186.  * @typedef {function():!shaka.extern.AbrManager}
  187.  * @exportDoc
  188.  */
  189. shaka.extern.AbrManager.Factory;