rx-player 3.25.2 → 3.26.3-dev.2022021400

package/src/core/abr/buffer_based_chooser.ts

@@ -14,13 +14,9 @@
  * limitations under the License.
  */
 
-import { Observable } from "rxjs";
-import { map } from "rxjs/operators";
 import log from "../../log";
+import arrayFindIndex from "../../utils/array_find_index";
 import getBufferLevels from "./get_buffer_levels";
-import getEstimateFromBufferLevels, {
-  IBufferBasedChooserClockTick,
-} from "./get_estimate_from_buffer_levels";
 
 /**
  * Choose a bitrate based on the currently available buffer.
@@ -33,18 +29,89 @@ import getEstimateFromBufferLevels, {
  * "maintanable" or not.
  * If so, we may switch to a better quality, or conversely to a worse quality.
  *
- * @param {Observable} update$
- * @param {Array.<number>} bitrates
- * @returns {Observable}
+ * @class BufferBasedChooser
  */
-export default function BufferBasedChooser(
-  update$ : Observable<IBufferBasedChooserClockTick>,
-  bitrates: number[]
-) : Observable<number|undefined> {
-  const levelsMap = getBufferLevels(bitrates);
-  log.debug("ABR: Steps for buffer based chooser.",
-            levelsMap.map((l, i) => ({ bufferLevel: l, bitrate: bitrates[i] })));
-  return update$.pipe(map((clockTick) => {
-    return getEstimateFromBufferLevels(clockTick, bitrates, levelsMap);
-  }));
+export default class BufferBasedChooser {
+  private _levelsMap : number[];
+  private _bitrates : number[];
+
+  /**
+   * @param {Array.<number>} number;
+   */
+  constructor(bitrates : number[]) {
+    this._levelsMap = getBufferLevels(bitrates);
+    this._bitrates = bitrates;
+    log.debug("ABR: Steps for buffer based chooser.",
+              this._levelsMap.map((l, i) => ({ bufferLevel: l, bitrate: bitrates[i] })));
+  }
+
+  /**
+   * @param {Object} playbackObservation
+   * @returns {number|undefined}
+   */
+  public getEstimate(
+    playbackObservation : IBufferBasedChooserPlaybackObservation
+  ) : number | undefined {
+    const bufferLevels = this._levelsMap;
+    const bitrates = this._bitrates;
+    const { bufferGap, currentBitrate, currentScore, speed } = playbackObservation;
+    if (currentBitrate == null) {
+      return bitrates[0];
+    }
+    const currentBitrateIndex = arrayFindIndex(bitrates, b => b === currentBitrate);
+    if (currentBitrateIndex < 0 || bitrates.length !== bufferLevels.length) {
+      log.error("ABR: Current Bitrate not found in the calculated levels");
+      return bitrates[0];
+    }
+
+    let scaledScore : number|undefined;
+    if (currentScore != null) {
+      scaledScore = speed === 0 ? currentScore : (currentScore / speed);
+    }
+
+    if (scaledScore != null && scaledScore > 1) {
+      const currentBufferLevel = bufferLevels[currentBitrateIndex];
+      const nextIndex = (() => {
+        for (let i = currentBitrateIndex + 1; i < bufferLevels.length; i++) {
+          if (bufferLevels[i] > currentBufferLevel) {
+            return i;
+          }
+        }
+      })();
+      if (nextIndex != null) {
+        const nextBufferLevel = bufferLevels[nextIndex];
+        if (bufferGap >= nextBufferLevel) {
+          return bitrates[nextIndex];
+        }
+      }
+    }
+
+    if (scaledScore == null || scaledScore < 1.15) {
+      const currentBufferLevel = bufferLevels[currentBitrateIndex];
+      if (bufferGap < currentBufferLevel) {
+        for (let i = currentBitrateIndex - 1; i >= 0; i--) {
+          if (bitrates[i] < currentBitrate) {
+            return bitrates[i];
+          }
+        }
+        return currentBitrate;
+      }
+    }
+    return currentBitrate;
+  }
+}
+
+/** Playback observation needed by the `BufferBasedChooser`. */
+export interface IBufferBasedChooserPlaybackObservation {
+  /**
+   * Difference in seconds between the current position and the next
+   * non-buffered position
+   */
+  bufferGap : number;
+  /** The bitrate of the currently downloaded segments, in bps. */
+  currentBitrate? : number | undefined;
+  /** The "maintainability score" of the currently downloaded segments. */
+  currentScore? : number | undefined;
+  /** Playback rate wanted */
+  speed : number;
 }

package/src/core/abr/get_buffer_levels.ts

@@ -40,6 +40,9 @@ export default function getBufferLevels(bitrates : number[]) : number[] {
       return 0;
     }
     const boundedIndex = Math.min(Math.max(1, index), bitrates.length - 1);
+    if (bitrates[boundedIndex] === bitrates[boundedIndex - 1]) {
+      return minBufferLevelForBitrate(index - 1);
+    }
     return Vp * (gp + (bitrates[boundedIndex] * utilities[boundedIndex - 1] -
       bitrates[boundedIndex - 1] * utilities[boundedIndex]) / (bitrates[boundedIndex] -
       bitrates[boundedIndex - 1])) + 4;

package/src/core/abr/guess_based_chooser.ts

@@ -0,0 +1,308 @@
+/**
+ * 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 LastEstimateStorage, {
+  ABRAlgorithmType,
+} from "./last_estimate_storage";
+import { estimateRequestBandwidth } from "./network_analyzer";
+import { IRequestInfo } from "./pending_requests_store";
+import RepresentationScoreCalculator, {
+  ScoreConfidenceLevel,
+} from "./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, scoreConfidenceLevel] : [number, ScoreConfidenceLevel]
+  ) : boolean {
+    return isFinite(bufferGap) && bufferGap >= 2.5 &&
+           performance.now() > this._blockGuessesUntil &&
+           scoreConfidenceLevel === 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 : [number, ScoreConfidenceLevel] | undefined,
+    bufferGap : number,
+    requests : IRequestInfo[]
+  ) : boolean {
+    if (scoreData !== undefined && scoreData[0] < 1.01) {
+      return true;
+    } else if ((scoreData === undefined || scoreData[0] < 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 : [number, ScoreConfidenceLevel] | undefined
+  ) : boolean {
+    if (scoreData !== undefined &&
+        scoreData[1] === ScoreConfidenceLevel.HIGH &&
+        scoreData[0] > 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} representation
+ * @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/abr/index.ts

@@ -16,21 +16,25 @@
 
 import ABRManager, {
   IABRManagerArguments,
-  IABRManagerClockTick,
+  IABRManagerPlaybackObservation,
 } from "./abr_manager";
 export {
   IABRAddedSegmentEvent,
-  IABRStreamEvents,
   IABREstimate,
   IABRMetricsEvent,
+  IABRMetricsEventValue,
   IABRRepresentationChangeEvent,
   IABRRequestBeginEvent,
+  IABRRequestBeginEventValue,
   IABRRequestEndEvent,
+  IABRRequestEndEventValue,
   IABRRequestProgressEvent,
+  IABRRequestProgressEventValue,
+  IABRStreamEvents,
 } from "./representation_estimator";
 
 export default ABRManager;
 export {
   IABRManagerArguments,
-  IABRManagerClockTick,
+  IABRManagerPlaybackObservation,
 };

package/src/core/abr/last_estimate_storage.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 { Representation } from "../../manifest";
+
+/** Stores the last estimate made by the `RepresentationEstimator`. */
+export default class LastEstimateStorage {
+  /**
+   * Estimated bandwitdh in the last estimate.
+   * `undefined` either if no estimate has been performed yet or if the
+   * bandwidth was unknown during the last estimate.
+   */
+  public bandwidth : number | undefined;
+  /**
+   * Estimated Representation in the last estimate.
+   * `null` if no estimate has been performed yet.
+   */
+  public representation : Representation | null;
+
+  /** Algorithm type used to make the last Representation estimate. */
+  public algorithmType : ABRAlgorithmType;
+
+  constructor() {
+    this.bandwidth = undefined;
+    this.representation = null;
+    this.algorithmType = ABRAlgorithmType.None;
+  }
+
+  /**
+   * Update this `LastEstimateStorage` with new values.
+   * @param {Object} representation - Estimated Representation.
+   * @param {number|undefined} bandwidth - Estimated bandwidth.
+   * @param {boolean} wasGuessed - If `true`, this estimate was a guess made by
+   * the `GuessingEstimator`.
+   */
+  public update(
+    representation : Representation,
+    bandwidth : number | undefined,
+    algorithmType : ABRAlgorithmType
+  ) : void {
+    this.representation = representation;
+    this.bandwidth = bandwidth;
+    this.algorithmType = algorithmType;
+  }
+}
+
+/** Identify an algorithm used to perform a Representation estimate.  */
+export const enum ABRAlgorithmType {
+ /**
+  * Buffer-based algorithm using mostly the size of the buffer to determine the
+  * best Representation.
+  */
+  BufferBased,
+  /**
+   * Bandwidth-based algorithm using mostly the speed at which segments are
+   * downloaded to determine the best Representation.
+   */
+  BandwidthBased,
+  /**
+   * Guess-based algorithm, which iterates through Representation and
+   * try to find the best one empirically.
+   */
+  GuessBased,
+    /** None of the other or no algorithm was used yet. */
+  None,
+}