rx-player 3.33.0 → 3.33.1

package/src/core/adaptive/buffer_based_chooser.ts

@@ -1,264 +0,0 @@
-/**
- * Copyright 2015 CANAL+ Group
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import log from "../../log";
-import arrayFindIndex from "../../utils/array_find_index";
-import getBufferLevels from "./utils/get_buffer_levels";
-import {
-  IRepresentationMaintainabilityScore,
-  ScoreConfidenceLevel,
-} from "./utils/representation_score_calculator";
-
-/**
- * Minimum amount of time, in milliseconds, during which we are blocked from
- * raising in quality after it had been considered as too high.
- */
-const MINIMUM_BLOCK_RAISE_DELAY = 6000;
-
-/**
- * Maximum amount of time, in milliseconds, during which we are blocked from
- * raising in quality after it had been considered as too high.
- */
-const MAXIMUM_BLOCK_RAISE_DELAY = 15000;
-
-/**
- * Amount of time, in milliseconds, with which the blocking time in raising
- * the quality will be incremented if the current quality estimate is seen
- * as too unstable.
- */
-const RAISE_BLOCKING_DELAY_INCREMENT = 3000;
-
-/**
- * Amount of time, in milliseconds, with which the blocking time in raising
- * the quality will be dcremented if the current quality estimate is seen
- * as relatively stable, until `MINIMUM_BLOCK_RAISE_DELAY` is reached.
- */
-const RAISE_BLOCKING_DELAY_DECREMENT = 1000;
-
-/**
- * Amount of time, in milliseconds, after the "raise blocking delay" currently
- * in place (during which it is forbidden to raise up in quality), during which
- * we might want to raise the "raise blocking delay" if the last chosen quality
- * seems unsuitable.
- *
- * For example, let's consider that the current raise blocking delay is at
- * `4000`, or 4 seconds, and that this `STABILITY_CHECK_DELAY` is at `5000`, or
- * 5 seconds.
- * Here it means that if the estimated quality is found to be unsuitable less
- * than 4+5 = 9 seconds after it last was, we will increment the raise blocking
- * delay by `RAISE_BLOCKING_DELAY_INCREMENT` (unless `MAXIMUM_BLOCK_RAISE_DELAY`
- * is reached).
- * Else, if takes more than 9 seconds, the raise blocking delay might be
- * decremented.
- */
-const STABILITY_CHECK_DELAY = 9000;
-
-/**
- * Choose a bitrate based on the currently available buffer.
- *
- * This algorithm is based on a deviation of the BOLA algorithm.
- * It is a hybrid solution that also relies on a given bitrate's
- * "maintainability".
- * Each time a chunk is downloaded, from the ratio between the chunk duration
- * and chunk's request time, we can assume that the representation is
- * "maintanable" or not.
- * If so, we may switch to a better quality, or conversely to a worse quality.
- *
- * It also rely on mechanisms to avoid fluctuating too much between qualities.
- *
- * @class BufferBasedChooser
- */
-export default class BufferBasedChooser {
-  private _levelsMap : number[];
-  private _bitrates : number[];
-
-  /**
-   * Current last best Representation's bitrate estimate made by the
-   * `BufferBasedChooser` or `undefined` if it has no such guess for now.
-   *
-   * Might be updated each time `onAddedSegment` is called.
-   */
-  private _currentEstimate: number | undefined;
-
-  /**
-   * Laast timestamp, in terms of `performance.now`, at which the current
-   * quality was seen as too high by this algorithm.
-   * Begins at `undefined`.
-   */
-  private _lastUnsuitableQualityTimestamp: number | undefined;
-
-  /**
-   * After lowering in quality, we forbid raising during a set amount of time.
-   * This amount is adaptive may continue to raise if it seems that quality
-   * is switching too much between low and high qualities.
-   *
-   * `_blockRaiseDelay` represents this time in milliseconds.
-   */
-  private _blockRaiseDelay: number;
-
-  /**
-   * @param {Array.<number>} bitrates
-   */
-  constructor(bitrates : number[]) {
-    this._levelsMap = getBufferLevels(bitrates).map(bl => {
-      return bl + 4; // Add some buffer security as it will be used conjointly with
-                     // other algorithms anyway
-    });
-    this._bitrates = bitrates;
-    this._lastUnsuitableQualityTimestamp = undefined;
-    this._blockRaiseDelay = MINIMUM_BLOCK_RAISE_DELAY;
-    log.debug("ABR: Steps for buffer based chooser.",
-              this._levelsMap.map((l, i) => `bufferLevel: ${l}, bitrate: ${bitrates[i]}`)
-                .join(" ,"));
-  }
-
-  /**
-   * @param {Object} playbackObservation
-   * @returns {number|undefined}
-   */
-  public onAddedSegment(
-    playbackObservation : IBufferBasedChooserPlaybackObservation
-  ) : void {
-    const bufferLevels = this._levelsMap;
-    const bitrates = this._bitrates;
-    const { bufferGap, currentBitrate, currentScore, speed } = playbackObservation;
-    if (currentBitrate == null) {
-      this._currentEstimate = bitrates[0];
-      return ;
-    }
-
-    let currentBitrateIndex = -1;
-    for (let i = 0; i < bitrates.length; i++) {
-      // There could be bitrate duplicates. Only take the last one to simplify
-      const bitrate = bitrates[i];
-      if (bitrate === currentBitrate) {
-        currentBitrateIndex = i;
-      } else if (bitrate > currentBitrate) {
-        break;
-      }
-    }
-
-    if (currentBitrateIndex < 0 || bitrates.length !== bufferLevels.length) {
-      log.error("ABR: Current Bitrate not found in the calculated levels");
-      this._currentEstimate = bitrates[0];
-      return ;
-    }
-
-    let scaledScore : number|undefined;
-    if (currentScore !== undefined) {
-      scaledScore = speed === 0 ? currentScore.score : (currentScore.score / speed);
-    }
-
-    const actualBufferGap = isFinite(bufferGap) ?
-      bufferGap :
-      0;
-
-    const now = performance.now();
-
-    if (
-      actualBufferGap < bufferLevels[currentBitrateIndex] ||
-      (
-        scaledScore !== undefined && scaledScore < 1 &&
-        currentScore?.confidenceLevel === ScoreConfidenceLevel.HIGH
-      )
-    ) {
-      const timeSincePrev = this._lastUnsuitableQualityTimestamp === undefined ?
-        -1 :
-        now - this._lastUnsuitableQualityTimestamp;
-      if (timeSincePrev < this._blockRaiseDelay + STABILITY_CHECK_DELAY) {
-        const newDelay = this._blockRaiseDelay + RAISE_BLOCKING_DELAY_INCREMENT;
-        this._blockRaiseDelay = Math.min(newDelay, MAXIMUM_BLOCK_RAISE_DELAY);
-        log.debug("ABR: Incrementing blocking raise in BufferBasedChooser due " +
-                    "to unstable quality",
-                  this._blockRaiseDelay);
-      } else {
-        const newDelay = this._blockRaiseDelay - RAISE_BLOCKING_DELAY_DECREMENT;
-        this._blockRaiseDelay = Math.max(MINIMUM_BLOCK_RAISE_DELAY, newDelay);
-        log.debug("ABR: Lowering quality in BufferBasedChooser", this._blockRaiseDelay);
-      }
-      this._lastUnsuitableQualityTimestamp = now;
-      // Security if multiple bitrates are equal, we now take the first one
-      const baseIndex = arrayFindIndex(bitrates, (b) => b === currentBitrate);
-      for (let i = baseIndex - 1; i >= 0; i--) {
-        if (actualBufferGap >= bufferLevels[i]) {
-          this._currentEstimate =  bitrates[i];
-          return;
-        }
-      }
-      this._currentEstimate = bitrates[0];
-      return ;
-    }
-
-    if (
-      (
-        this._lastUnsuitableQualityTimestamp !== undefined &&
-        now - this._lastUnsuitableQualityTimestamp < this._blockRaiseDelay
-      ) ||
-      scaledScore === undefined || scaledScore < 1.15 ||
-      currentScore?.confidenceLevel !== ScoreConfidenceLevel.HIGH
-    ) {
-      this._currentEstimate = currentBitrate;
-      return ;
-    }
-
-    const currentBufferLevel = bufferLevels[currentBitrateIndex];
-    const nextIndex = (() => {
-      for (let i = currentBitrateIndex + 1; i < bufferLevels.length; i++) {
-        if (bufferLevels[i] > currentBufferLevel) {
-          return i;
-        }
-      }
-    })();
-    if (nextIndex !== undefined) {
-      const nextBufferLevel = bufferLevels[nextIndex];
-      if (bufferGap >= nextBufferLevel) {
-        log.debug("ABR: Raising quality in BufferBasedChooser", bitrates[nextIndex]);
-        this._currentEstimate = bitrates[nextIndex];
-        return ;
-      }
-    }
-    this._currentEstimate = currentBitrate;
-    return ;
-  }
-
-  /**
-   * Returns the last best Representation's bitrate estimate made by the
-   * `BufferBasedChooser` or `undefined` if it has no such guess for now.
-   *
-   * Might be updated after `onAddedSegment` is called.
-   *
-   * @returns {number|undefined}
-   */
-  public getLastEstimate(): number | undefined {
-    return this._currentEstimate;
-  }
-}
-
-/** Playback observation needed by the `BufferBasedChooser`. */
-export interface IBufferBasedChooserPlaybackObservation {
-  /**
-   * Difference in seconds between the current position and the next
-   * non-buffered position in the buffer for the currently-considered
-   * media type.
-   */
-  bufferGap : number;
-  /** The bitrate of the currently downloaded segments, in bps. */
-  currentBitrate? : number | undefined;
-  /** The "maintainability score" of the currently downloaded segments. */
-  currentScore? : IRepresentationMaintainabilityScore | undefined;
-  /** Playback rate wanted (e.g. `1` is regular playback, `2` is double speed etc.). */
-  speed : number;
-}

package/src/core/adaptive/guess_based_chooser.ts

@@ -1,309 +0,0 @@
-/**
- * Copyright 2015 CANAL+ Group
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import log from "../../log";
-import { Representation } from "../../manifest";
-import arrayFindIndex from "../../utils/array_find_index";
-import { estimateRequestBandwidth } from "./network_analyzer";
-import LastEstimateStorage, {
-  ABRAlgorithmType,
-} from "./utils/last_estimate_storage";
-import { IRequestInfo } from "./utils/pending_requests_store";
-import RepresentationScoreCalculator, {
-  IRepresentationMaintainabilityScore,
-  ScoreConfidenceLevel,
-} from "./utils/representation_score_calculator";
-
-/**
- * Estimate which Representation should be played based on risky "guesses".
- *
- * Basically, this `GuessBasedChooser` will attempt switching to the superior
- * quality when conditions allows this and then check if we're able to maintain
- * this quality. If we're not, it will rollbacks to the previous, maintaninable,
- * guess.
- *
- * The algorithm behind the `GuessBasedChooser` is very risky in terms of
- * rebuffering chances. As such, it should only be used when other approach
- * don't work (e.g.  low-latency contents).
- * @class GuessBasedChooser
- */
-export default class GuessBasedChooser {
-  private _lastAbrEstimate : LastEstimateStorage;
-  private _scoreCalculator : RepresentationScoreCalculator;
-  private _consecutiveWrongGuesses : number;
-  private _blockGuessesUntil : number;
-  private _lastMaintanableBitrate : number | null;
-
-  /**
-   * Create a new `GuessBasedChooser`.
-   * @param {Object} scoreCalculator
-   * @param {Object} prevEstimate
-   */
-  constructor(
-    scoreCalculator : RepresentationScoreCalculator,
-    prevEstimate : LastEstimateStorage
-  ) {
-    this._scoreCalculator = scoreCalculator;
-    this._lastAbrEstimate = prevEstimate;
-    this._consecutiveWrongGuesses = 0;
-    this._blockGuessesUntil = 0;
-    this._lastMaintanableBitrate = null;
-  }
-
-  /**
-   * Perform a "guess", which basically indicates which Representation should be
-   * chosen according to the `GuessBasedChooser`.
-   *
-   * @param {Array.<Object>} representations - Array of all Representation the
-   * GuessBasedChooser can choose from, sorted by bitrate ascending.
-   * /!\ It is very important that Representation in that Array are sorted by
-   * bitrate ascending for this method to work as intented.
-   * @param {Object} observation - Last playback observation performed.
-   * @param {Object} currentRepresentation - The Representation currently
-   * loading.
-   * @param {number} incomingBestBitrate - The bitrate of the Representation
-   * chosen by the more optimistic of the other ABR algorithms currently.
-   * @param {Array.<Object>} requests - Information on all pending requests.
-   * @returns {Object|null} - If a guess is made, return that guess, else
-   * returns `null` (in which case you should fallback to another ABR
-   * algorithm).
-   */
-  public getGuess(
-    representations : Representation[],
-    observation : {
-      /**
-       * For the concerned media buffer, difference in seconds between the next
-       * position where no segment data is available and the current position.
-       */
-      bufferGap: number;
-      /**
-       * Last "playback rate" set by the user. This is the ideal "playback rate" at
-       * which the media should play.
-       */
-      speed: number;
-    },
-    currentRepresentation : Representation,
-    incomingBestBitrate : number,
-    requests : IRequestInfo[]
-  ) : Representation | null {
-    const { bufferGap, speed } = observation;
-    const lastChosenRep = this._lastAbrEstimate.representation;
-    if (lastChosenRep === null) {
-      return null; // There's nothing to base our guess on
-    }
-
-    if (incomingBestBitrate > lastChosenRep.bitrate) {
-      // ABR estimates are already superior or equal to the guess
-      // we'll be doing here, so no need to guess
-      if (this._lastAbrEstimate.algorithmType === ABRAlgorithmType.GuessBased) {
-        if (this._lastAbrEstimate.representation !== null) {
-          this._lastMaintanableBitrate = this._lastAbrEstimate.representation.bitrate;
-        }
-        this._consecutiveWrongGuesses = 0;
-      }
-      return null;
-    }
-
-    const scoreData = this._scoreCalculator.getEstimate(currentRepresentation);
-    if (this._lastAbrEstimate.algorithmType !== ABRAlgorithmType.GuessBased) {
-      if (scoreData === undefined) {
-        return null; // not enough information to start guessing
-      }
-      if (this._canGuessHigher(bufferGap, speed, scoreData)) {
-        const nextRepresentation = getNextRepresentation(representations,
-                                                         currentRepresentation);
-        if (nextRepresentation !== null) {
-          return nextRepresentation;
-        }
-      }
-      return null;
-    }
-
-    // If we reached here, we're currently already in guessing mode
-
-    if (this._isLastGuessValidated(lastChosenRep, incomingBestBitrate, scoreData)) {
-      log.debug("ABR: Guessed Representation validated", lastChosenRep.bitrate);
-      this._lastMaintanableBitrate = lastChosenRep.bitrate;
-      this._consecutiveWrongGuesses = 0;
-    }
-
-    if (currentRepresentation.id !== lastChosenRep.id) {
-      return lastChosenRep;
-    }
-
-    const shouldStopGuess = this._shouldStopGuess(currentRepresentation,
-                                                  scoreData,
-                                                  bufferGap,
-                                                  requests);
-    if (shouldStopGuess) {
-      // Block guesses for a time
-      this._consecutiveWrongGuesses++;
-      this._blockGuessesUntil = performance.now() +
-        Math.min(this._consecutiveWrongGuesses * 15000, 120000);
-      return getPreviousRepresentation(representations, currentRepresentation);
-    } else if (scoreData === undefined) {
-      return currentRepresentation;
-    }
-
-    if (this._canGuessHigher(bufferGap, speed, scoreData)) {
-      const nextRepresentation = getNextRepresentation(representations,
-                                                       currentRepresentation);
-      if (nextRepresentation !== null) {
-        return nextRepresentation;
-      }
-    }
-    return currentRepresentation;
-  }
-
-  /**
-   * Returns `true` if we've enough confidence on the current situation to make
-   * a higher guess.
-   * @param {number} bufferGap
-   * @param {number} speed
-   * @param {Array} scoreData
-   * @returns {boolean}
-   */
-  private _canGuessHigher(
-    bufferGap : number,
-    speed : number,
-    { score, confidenceLevel } : IRepresentationMaintainabilityScore
-  ) : boolean {
-    return isFinite(bufferGap) && bufferGap >= 2.5 &&
-           performance.now() > this._blockGuessesUntil &&
-           confidenceLevel === ScoreConfidenceLevel.HIGH &&
-           score / speed > 1.01;
-  }
-
-  /**
-   * Returns `true` if the pending guess of `lastGuess` seems to not
-   * be maintainable and as such should be stopped.
-   * @param {Object} lastGuess
-   * @param {Array} scoreData
-   * @param {number} bufferGap
-   * @param {Array.<Object>} requests
-   * @returns {boolean}
-   */
-  private _shouldStopGuess(
-    lastGuess : Representation,
-    scoreData : IRepresentationMaintainabilityScore | undefined,
-    bufferGap : number,
-    requests : IRequestInfo[]
-  ) : boolean {
-    if (scoreData !== undefined && scoreData.score < 1.01) {
-      return true;
-    } else if ((scoreData === undefined || scoreData.score < 1.2) && bufferGap < 0.6) {
-      return true;
-    }
-
-    const guessedRepresentationRequests = requests.filter(req => {
-      return req.content.representation.id === lastGuess.id;
-    });
-
-    const now = performance.now();
-    for (const req of guessedRepresentationRequests) {
-      const requestElapsedTime = now - req.requestTimestamp;
-      if (req.content.segment.isInit) {
-        if (requestElapsedTime > 1000) {
-          return true;
-        }
-      } else if (requestElapsedTime > req.content.segment.duration * 1000 + 200) {
-        return true;
-      } else {
-        const fastBw = estimateRequestBandwidth(req);
-        if (fastBw !== undefined && fastBw < lastGuess.bitrate * 0.8) {
-          return true;
-        }
-      }
-    }
-    return false;
-  }
-
-  private _isLastGuessValidated(
-    lastGuess : Representation,
-    incomingBestBitrate : number,
-    scoreData : IRepresentationMaintainabilityScore | undefined
-  ) : boolean {
-    if (scoreData !== undefined &&
-        scoreData.confidenceLevel === ScoreConfidenceLevel.HIGH &&
-        scoreData.score > 1.5)
-    {
-      return true;
-    }
-    return incomingBestBitrate >= lastGuess.bitrate &&
-      (this._lastMaintanableBitrate === null ||
-        this._lastMaintanableBitrate < lastGuess.bitrate);
-  }
-}
-
-/**
- * From the array of Representations given, returns the Representation with a
- * bitrate immediately superior to the current one.
- * Returns `null` if that "next" Representation is not found.
- *
- * /!\ The representations have to be already sorted by bitrate, in ascending
- * order.
- * @param {Array.<Object>} representations - Available representations to choose
- * from, sorted by bitrate in ascending order.
- * @param {Object} currentRepresentation - The Representation currently
- * considered.
- * @returns {Object|null}
- */
-function getNextRepresentation(
-  representations : Representation[],
-  currentRepresentation : Representation
-) : Representation | null {
-  const len = representations.length;
-  let index = arrayFindIndex(representations,
-                             ({ id }) => id === currentRepresentation.id);
-  if (index < 0) {
-    log.error("ABR: Current Representation not found.");
-    return null;
-  }
-
-  while (++index < len) {
-    if (representations[index].bitrate > currentRepresentation.bitrate) {
-      return representations[index];
-    }
-  }
-  return null;
-}
-
-/**
- * From the array of Representations given, returns the Representation with a
- * bitrate immediately inferior.
- * Returns `null` if that "previous" Representation is not found.
- * @param {Array.<Object>} representations
- * @param {Object} currentRepresentation
- * @returns {Object|null}
- */
-function getPreviousRepresentation(
-  representations : Representation[],
-  currentRepresentation : Representation
-) : Representation | null {
-  let index = arrayFindIndex(representations,
-                             ({ id }) => id === currentRepresentation.id);
-  if (index < 0) {
-    log.error("ABR: Current Representation not found.");
-    return null;
-  }
-
-  while (--index >= 0) {
-    if (representations[index].bitrate < currentRepresentation.bitrate) {
-      return representations[index];
-    }
-  }
-  return null;
-}

package/src/core/adaptive/index.ts

@@ -1,45 +0,0 @@
-/**
- * Copyright 2015 CANAL+ Group
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import AdaptiveRepresentationSelector, {
-  IABREstimate,
-  IAdaptiveRepresentationSelectorArguments,
-  IAddedSegmentCallbackPayload,
-  IMetricsCallbackPayload,
-  IRepresentationEstimator,
-  IRepresentationEstimatorCallbacks,
-  IRepresentationEstimatorPlaybackObservation,
-  IRepresentationEstimatorThrottlers as IABRThrottlers,
-  IRequestBeginCallbackPayload,
-  IRequestEndCallbackPayload,
-  IRequestProgressCallbackPayload,
-} from "./adaptive_representation_selector";
-
-export default AdaptiveRepresentationSelector;
-export {
-  IAdaptiveRepresentationSelectorArguments,
-  IABRThrottlers,
-  IRepresentationEstimator,
-
-  IAddedSegmentCallbackPayload,
-  IABREstimate,
-  IMetricsCallbackPayload,
-  IRepresentationEstimatorCallbacks,
-  IRepresentationEstimatorPlaybackObservation,
-  IRequestBeginCallbackPayload,
-  IRequestProgressCallbackPayload,
-  IRequestEndCallbackPayload,
-};