rx-player 3.25.2 → 3.26.3-dev.2022021400

package/src/core/abr/representation_estimator.ts

@@ -17,19 +17,17 @@
 import {
   combineLatest as observableCombineLatest,
   defer as observableDefer,
-  merge as observableMerge,
-  Observable,
-  of as observableOf,
-} from "rxjs";
-import {
   filter,
   ignoreElements,
   map,
+  merge as observableMerge,
+  Observable,
+  of as observableOf,
   startWith,
   switchMap,
   tap,
   withLatestFrom,
-} from "rxjs/operators";
+} from "rxjs";
 import log from "../../log";
 import {
   Adaptation,
@@ -39,13 +37,25 @@ import {
 import { getLeftSizeOfRange } from "../../utils/ranges";
 import BandwidthEstimator from "./bandwidth_estimator";
 import BufferBasedChooser from "./buffer_based_chooser";
-import generateCachedSegmentDetector from "./cached_segment_detector";
-import filterByBitrate from "./filter_by_bitrate";
-import filterByWidth from "./filter_by_width";
+import GuessBasedChooser from "./guess_based_chooser";
+import LastEstimateStorage, {
+  ABRAlgorithmType,
+} from "./last_estimate_storage";
 import NetworkAnalyzer from "./network_analyzer";
-import PendingRequestsStore from "./pending_requests_store";
+import PendingRequestsStore, {
+  IPendingRequestStoreBegin,
+  IPendingRequestStoreProgress,
+} from "./pending_requests_store";
 import RepresentationScoreCalculator from "./representation_score_calculator";
-import selectOptimalRepresentation from "./select_optimal_representation";
+import filterByBitrate from "./utils/filter_by_bitrate";
+import filterByWidth from "./utils/filter_by_width";
+import selectOptimalRepresentation from "./utils/select_optimal_representation";
+
+// NOTE As of now (RxJS 7.4.0), RxJS defines `ignoreElements` default
+// first type parameter as `any` instead of the perfectly fine `unknown`,
+// leading to linter issues, as it forbids the usage of `any`.
+// This is why we're disabling the eslint rule.
+/* eslint-disable @typescript-eslint/no-unsafe-argument */
 
 /**
  * Adaptive BitRate estimate object.
@@ -109,17 +119,20 @@ export interface IABREstimate {
    * have, you will most likely only want to do it when the Representation is
    * known to be maintaninable.
    */
-  knownStableBitrate?: number;
+  knownStableBitrate?: number | undefined;
 }
 
-/** Properties the `RepresentationEstimator` will need at each "clock tick". */
-export interface IRepresentationEstimatorClockTick {
+/** Media properties the `RepresentationEstimator` will need to keep track of. */
+export interface IRepresentationEstimatorPlaybackObservation {
   /**
    * For the concerned media buffer, difference in seconds between the next
    * position where no segment data is available and the current position.
    */
   bufferGap : number;
-  /** The position, in seconds, the media element was in at the time of the tick. */
+  /**
+   * The position, in seconds, the media element was in at the time of the
+   * observation.
+   */
   position : number;
   /**
    * Last "playback rate" set by the user. This is the ideal "playback rate" at
@@ -128,14 +141,22 @@ export interface IRepresentationEstimatorClockTick {
   speed : number;
   /** `duration` property of the HTMLMediaElement on which the content plays. */
   duration : number;
+  /**
+   * For live contents only, difference between the maximum playable position
+   * and the current position.
+   * `undefined` for non-live contents.
+   */
+  liveGap : number | undefined;
 }
 
 /** Content of the `IABRMetricsEvent` event's payload. */
-interface IABRMetricsEventValue {
+export interface IABRMetricsEventValue {
   /** Time the request took to perform the request, in milliseconds. */
-  duration: number;
+  requestDuration: number;
   /** Amount of bytes downloaded with this request. */
   size: number;
+  /** Duration of the loaded segment, in seconds. */
+  segmentDuration: number | undefined;
   /** Context about the segment downloaded. */
   content: { representation: Representation;
              adaptation: Adaptation;
@@ -174,24 +195,7 @@ export interface IABRRepresentationChangeEvent {
  */
 export interface IABRRequestBeginEvent {
   type: "requestBegin";
-  value: {
-    /**
-     * String identifying this request.
-     *
-     * Only one request communicated to the current `RepresentationEstimator`
-     * should have this `id` at the same time.
-     */
-    id: string;
-    /** Presentation time at which the corresponding segment begins, in seconds. */
-    time: number;
-    /**
-     * Difference between the presentation end time and start time of the
-     * corresponding segment, in seconds.
-     */
-    duration: number;
-    /** Value of `performance.now` at the time the request began.  */
-    requestTimestamp: number;
-  };
+  value: IABRRequestBeginEventValue;
 }
 
 /**
@@ -202,24 +206,7 @@ export interface IABRRequestBeginEvent {
  */
 export interface IABRRequestProgressEvent {
   type: "progress";
-  value: {
-    /** Amount of time since the request has started, in seconds. */
-    duration : number;
-    /**
-     * Same `id` value used to identify that request at the time the corresponding
-     * `IABRRequestBeginEvent` event was sent.
-     */
-    id: string;
-    /** Current downloaded size, in bytes. */
-    size : number;
-    /** Value of `performance.now` at the time this progression report was available. */
-    timestamp : number;
-    /**
-     * Total size of the segment to download (including already-loaded data),
-     * in bytes.
-     */
-    totalSize : number;
-  };
+  value: IABRRequestProgressEventValue;
 }
 
 /**
@@ -230,13 +217,22 @@ export interface IABRRequestProgressEvent {
  */
 export interface IABRRequestEndEvent {
   type: "requestEnd";
-  value: {
-    /**
-     * Same `id` value used to identify that request at the time the corresponding
-     * `IABRRequestBeginEvent` event was sent.
-     */
-    id: string;
-  };
+  value: IABRRequestEndEventValue;
+}
+
+/** Value associated with a `IABRRequestBeginEvent`. */
+export type IABRRequestBeginEventValue = IPendingRequestStoreBegin;
+
+/** Value associated with a `IABRRequestProgressEvent`. */
+export type IABRRequestProgressEventValue = IPendingRequestStoreProgress;
+
+/** Value associated with a `IABRRequestEndEvent`. */
+export interface IABRRequestEndEventValue {
+  /**
+   * Same `id` value used to identify that request at the time the corresponding
+   * `IABRRequestBeginEvent` event was sent.
+   */
+  id: string;
 }
 
 /** Object allowing to filter some Representations out based on different attributes. */
@@ -298,7 +294,7 @@ export interface IRepresentationEstimatorArguments {
   /** Events indicating current playback and network conditions. */
   streamEvents$ : Observable<IABRStreamEvents>;
   /** Observable emitting regularly the current playback situation. */
-  clock$ : Observable<IRepresentationEstimatorClockTick>;
+  observation$ : Observable<IRepresentationEstimatorPlaybackObservation>;
   /** Observable allows to filter out Representation in our estimations. */
   filters$ : Observable<IABRFiltersObject>;
   /**
@@ -373,17 +369,17 @@ function getFilteredRepresentations(
   representations : Representation[],
   filters : IABRFiltersObject
 ) : Representation[] {
-  let _representations = representations;
+  let filteredReps = representations;
 
   if (filters.bitrate != null) {
-    _representations = filterByBitrate(_representations, filters.bitrate);
+    filteredReps = filterByBitrate(filteredReps, filters.bitrate);
   }
 
   if (filters.width != null) {
-    _representations = filterByWidth(_representations, filters.width);
+    filteredReps = filterByWidth(filteredReps, filters.width);
   }
 
-  return _representations;
+  return filteredReps;
 }
 
 /**
@@ -400,7 +396,7 @@ function getFilteredRepresentations(
  */
 export default function RepresentationEstimator({
   bandwidthEstimator,
-  clock$,
+  observation$,
   filters$,
   initialBitrate,
   lowLatencyMode,
@@ -415,31 +411,27 @@ export default function RepresentationEstimator({
                                                                        initialBitrate,
                                               lowLatencyMode);
   const requestsStore = new PendingRequestsStore();
-  const shouldIgnoreMetrics = generateCachedSegmentDetector();
 
   /**
    * Callback to call when new metrics are available
    * @param {Object} value
    */
   function onMetric(value : IABRMetricsEventValue) : void {
-    const { duration, size, content } = value;
-
-    if (shouldIgnoreMetrics(content, duration)) {
-      // We already loaded not cached segments.
-      // Do not consider cached segments anymore.
-      return;
-    }
+    const { requestDuration, segmentDuration, size, content } = value;
 
     // calculate bandwidth
-    bandwidthEstimator.addSample(duration, size);
-
-    // calculate "maintainability score"
-    const { segment } = content;
-    const requestDuration = duration / 1000;
-    const segmentDuration = segment.duration;
-
-    const { representation } = content;
-    scoreCalculator.addSample(representation, requestDuration, segmentDuration);
+    bandwidthEstimator.addSample(requestDuration, size);
+
+    if (!content.segment.isInit) {
+      // calculate "maintainability score"
+      const { segment, representation } = content;
+      if (segmentDuration === undefined && !segment.complete) {
+        // We cannot know the real duration of the segment
+        return;
+      }
+      const segDur = segmentDuration ?? segment.duration;
+      scoreCalculator.addSample(representation, requestDuration / 1000, segDur);
+    }
   }
 
   const metrics$ = streamEvents$.pipe(
@@ -498,108 +490,186 @@ export default function RepresentationEstimator({
       }
 
       // -- AUTO mode --
-      let lastEstimatedBitrate : number | undefined;
-      let forceBandwidthMode = true;
+
+      /** Store the previous estimate made here. */
+      const prevEstimate = new LastEstimateStorage();
+
+      let allowBufferBasedEstimates = false;
+      const guessBasedChooser = new GuessBasedChooser(scoreCalculator, prevEstimate);
 
       // Emit each time a buffer-based estimation should be actualized (each
       // time a segment is added).
-      const bufferBasedClock$ = streamEvents$.pipe(
+      const bufferBasedobservation$ = streamEvents$.pipe(
         filter((e) : e is IABRAddedSegmentEvent => e.type === "added-segment"),
-        withLatestFrom(clock$),
+        withLatestFrom(observation$),
         map(([{ value: evtValue }, { speed, position } ]) => {
           const timeRanges = evtValue.buffered;
           const bufferGap = getLeftSizeOfRange(timeRanges, position);
           const { representation } = evtValue.content;
-          const currentScore = scoreCalculator.getEstimate(representation);
+          const scoreData = scoreCalculator.getEstimate(representation);
+          const currentScore = scoreData?.[0];
           const currentBitrate = representation.bitrate;
           return { bufferGap, currentBitrate, currentScore, speed };
         })
       );
 
       const bitrates = representations.map(r => r.bitrate);
-      const bufferBasedEstimation$ = BufferBasedChooser(bufferBasedClock$, bitrates)
-        .pipe(startWith(undefined));
+      const bufferBasedChooser = new BufferBasedChooser(bitrates);
+      const bufferBasedEstimation$ = bufferBasedobservation$.pipe(
+        map(bbo => bufferBasedChooser.getEstimate(bbo)),
+        startWith(undefined)
+      );
 
-      return observableCombineLatest([ clock$,
+      return observableCombineLatest([ observation$,
                                        minAutoBitrate$,
                                        maxAutoBitrate$,
                                        filters$,
                                        bufferBasedEstimation$ ]
       ).pipe(
         withLatestFrom(currentRepresentation$),
-        map(([ [ clock, minAutoBitrate, maxAutoBitrate, filters, bufferBasedBitrate ],
+        map(([ [ observation,
+                 minAutoBitrate,
+                 maxAutoBitrate,
+                 filters,
+                 bufferBasedBitrate ],
                currentRepresentation ]
         ) : IABREstimate => {
-          const _representations = getFilteredRepresentations(representations,
-                                                              filters);
+          const { bufferGap, liveGap } = observation;
+
+          const filteredReps = getFilteredRepresentations(representations,
+                                                          filters);
           const requests = requestsStore.getRequests();
           const { bandwidthEstimate, bitrateChosen } = networkAnalyzer
-            .getBandwidthEstimate(clock,
+            .getBandwidthEstimate(observation,
                                   bandwidthEstimator,
                                   currentRepresentation,
                                   requests,
-                                  lastEstimatedBitrate);
-
-          lastEstimatedBitrate = bandwidthEstimate;
+                                  prevEstimate.bandwidth);
 
           const stableRepresentation = scoreCalculator.getLastStableRepresentation();
-          const knownStableBitrate = stableRepresentation == null ?
+          const knownStableBitrate = stableRepresentation === null ?
             undefined :
-            stableRepresentation.bitrate / (clock.speed > 0 ? clock.speed : 1);
-
-          const { bufferGap } = clock;
-          if (!forceBandwidthMode && bufferGap <= 5) {
-            forceBandwidthMode = true;
-          } else if (forceBandwidthMode && isFinite(bufferGap) && bufferGap > 10) {
-            forceBandwidthMode = false;
+            stableRepresentation.bitrate / (observation.speed > 0 ? observation.speed :
+                                                                    1);
+
+          if (allowBufferBasedEstimates && bufferGap <= 5) {
+            allowBufferBasedEstimates = false;
+          } else if (!allowBufferBasedEstimates &&
+                     isFinite(bufferGap) &&
+                      bufferGap > 10)
+          {
+            allowBufferBasedEstimates = true;
           }
 
-          const chosenRepFromBandwidth = selectOptimalRepresentation(_representations,
+          /**
+           * Representation chosen when considering only [pessimist] bandwidth
+           * calculation.
+           * This is a safe enough choice but might be lower than what the user
+           * could actually profit from.
+           */
+          const chosenRepFromBandwidth = selectOptimalRepresentation(filteredReps,
                                                                      bitrateChosen,
                                                                      minAutoBitrate,
                                                                      maxAutoBitrate);
-          if (forceBandwidthMode) {
-            log.debug("ABR: Choosing representation with bandwidth estimation.",
-                      chosenRepFromBandwidth);
+
+          let currentBestBitrate = chosenRepFromBandwidth.bitrate;
+
+          /**
+           * Representation chosen when considering the current buffer size.
+           * If defined, takes precedence over `chosenRepFromBandwidth`.
+           *
+           * This is a very safe choice, yet it is very slow and might not be
+           * adapted to cases where a buffer cannot be build, such as live contents.
+           *
+           * `null` if this buffer size mode is not enabled or if we don't have a
+           * choice from it yet.
+           */
+          let chosenRepFromBufferSize : Representation | null = null;
+          if (allowBufferBasedEstimates &&
+              bufferBasedBitrate !== undefined &&
+              bufferBasedBitrate > currentBestBitrate)
+          {
+
+            chosenRepFromBufferSize = selectOptimalRepresentation(filteredReps,
+                                                                  bufferBasedBitrate,
+                                                                  minAutoBitrate,
+                                                                  maxAutoBitrate);
+            currentBestBitrate = chosenRepFromBufferSize.bitrate;
+          }
+
+          /**
+           * Representation chosen by the more adventurous `GuessBasedChooser`,
+           * which iterates through Representations one by one until finding one
+           * that cannot be "maintained".
+           *
+           * If defined, takes precedence over both `chosenRepFromBandwidth` and
+           * `chosenRepFromBufferSize`.
+           *
+           * This is the riskiest choice (in terms of rebuffering chances) but is
+           * only enabled when no other solution is adapted (for now, this just
+           * applies for low-latency contents when playing close to the live
+           * edge).
+           *
+           * `null` if not enabled or if there's currently no guess.
+           */
+          let chosenRepFromGuessMode : Representation | null = null;
+          if (lowLatencyMode &&
+              currentRepresentation !== null &&
+              liveGap !== undefined &&
+              liveGap < 40)
+          {
+            chosenRepFromGuessMode = guessBasedChooser.getGuess(representations,
+                                                                observation,
+                                                                currentRepresentation,
+                                                                currentBestBitrate,
+                                                                requests);
+          }
+
+          if (chosenRepFromGuessMode !== null &&
+              chosenRepFromGuessMode.bitrate > currentBestBitrate) {
+            log.debug("ABR: Choosing representation with guess-based estimation.",
+                      chosenRepFromGuessMode.bitrate,
+                      chosenRepFromGuessMode.id);
+            prevEstimate.update(chosenRepFromGuessMode,
+                                bandwidthEstimate,
+                                ABRAlgorithmType.GuessBased);
             return { bitrate: bandwidthEstimate,
-                     representation: chosenRepFromBandwidth,
-                     urgent: networkAnalyzer.isUrgent(chosenRepFromBandwidth.bitrate,
+                     representation: chosenRepFromGuessMode,
+                     urgent: currentRepresentation === null ||
+                       chosenRepFromGuessMode.bitrate < currentRepresentation.bitrate,
+                     manual: false,
+                     knownStableBitrate };
+          } else if (chosenRepFromBufferSize !== null) {
+            log.debug("ABR: Choosing representation with buffer-based estimation.",
+                      chosenRepFromBufferSize.bitrate,
+                      chosenRepFromBufferSize.id);
+            prevEstimate.update(chosenRepFromBufferSize,
+                                bandwidthEstimate,
+                                ABRAlgorithmType.BufferBased);
+            return { bitrate: bandwidthEstimate,
+                     representation: chosenRepFromBufferSize,
+                     urgent: networkAnalyzer.isUrgent(chosenRepFromBufferSize.bitrate,
                                                       currentRepresentation,
                                                       requests,
-                                                      clock),
+                                                      observation),
                      manual: false,
                      knownStableBitrate };
-          }
-          if (bufferBasedBitrate == null ||
-              chosenRepFromBandwidth.bitrate >= bufferBasedBitrate)
-          {
+          } else {
             log.debug("ABR: Choosing representation with bandwidth estimation.",
-                      chosenRepFromBandwidth);
+                      chosenRepFromBandwidth.bitrate,
+                      chosenRepFromBandwidth.id);
+            prevEstimate.update(chosenRepFromBandwidth,
+                                bandwidthEstimate,
+                                ABRAlgorithmType.BandwidthBased);
             return { bitrate: bandwidthEstimate,
                      representation: chosenRepFromBandwidth,
                      urgent: networkAnalyzer.isUrgent(chosenRepFromBandwidth.bitrate,
                                                       currentRepresentation,
                                                       requests,
-                                                      clock),
+                                                      observation),
                      manual: false,
                      knownStableBitrate };
           }
-          const chosenRepresentation = selectOptimalRepresentation(_representations,
-                                                                   bufferBasedBitrate,
-                                                                   minAutoBitrate,
-                                                                   maxAutoBitrate);
-          if (bufferBasedBitrate <= maxAutoBitrate) {
-            log.debug("ABR: Choosing representation with buffer based bitrate ceiling.",
-                      chosenRepresentation);
-          }
-          return { bitrate: bandwidthEstimate,
-                   representation: chosenRepresentation,
-                   urgent: networkAnalyzer.isUrgent(bufferBasedBitrate,
-                                                    currentRepresentation,
-                                                    requests,
-                                                    clock),
-                   manual: false,
-                   knownStableBitrate };
         })
       );
     }));

package/src/core/abr/representation_score_calculator.ts

@@ -16,7 +16,7 @@
 
 import log from "../../log";
 import { Representation } from "../../manifest";
-import EWMA from "./ewma";
+import EWMA from "./utils/ewma";
 
 /**
  * Calculate the "maintainability score" of a given Representation:
@@ -49,7 +49,9 @@ import EWMA from "./ewma";
  */
 export default class RepresentationScoreCalculator {
   private _currentRepresentationData : { representation : Representation;
-                                         ewma : EWMA; } |
+                                         ewma : EWMA;
+                                         loadedSegments : number;
+                                         loadedDuration : number; } |
                                        null;
 
   private _lastRepresentationWithGoodScore : Representation | null;
@@ -73,21 +75,26 @@ export default class RepresentationScoreCalculator {
     segmentDuration : number
   ) : void {
     const ratio = segmentDuration / requestDuration;
-    const oldEwma = this._getEWMA(representation);
+    const currentRep = this._currentRepresentationData;
     let currentEWMA : EWMA;
-    if (oldEwma != null) {
-      currentEWMA = oldEwma;
-      oldEwma.addSample(requestDuration, ratio);
+    if (currentRep !== null && currentRep.representation.id === representation.id) {
+      currentEWMA = currentRep.ewma;
+      currentRep.ewma.addSample(requestDuration, ratio);
+      currentRep.loadedDuration += segmentDuration;
+      currentRep.loadedSegments++;
     } else {
       currentEWMA = new EWMA(5);
       currentEWMA.addSample(requestDuration, ratio);
-      this._currentRepresentationData = { representation, ewma: currentEWMA };
+      this._currentRepresentationData = { representation,
+                                          ewma: currentEWMA,
+                                          loadedDuration: segmentDuration,
+                                          loadedSegments: 0 };
     }
 
     if (currentEWMA.getEstimate() > 1 &&
         this._lastRepresentationWithGoodScore !== representation
     ) {
-      log.debug("ABR: New last stable representation", representation);
+      log.debug("ABR: New last stable representation", representation.bitrate);
       this._lastRepresentationWithGoodScore = representation;
     }
   }
@@ -98,11 +105,21 @@ export default class RepresentationScoreCalculator {
    * @param {Representation} representation
    * @returns {number|undefined}
    */
-  public getEstimate(representation : Representation) : number | undefined {
-    const ewma = this._getEWMA(representation);
-    if (ewma != null) {
-      return ewma.getEstimate();
+  public getEstimate(
+    representation : Representation
+  ) : [number, ScoreConfidenceLevel] | undefined {
+    if (this._currentRepresentationData === null ||
+        this._currentRepresentationData.representation.id !== representation.id)
+    {
+      return undefined;
     }
+    const { ewma, loadedSegments, loadedDuration } = this._currentRepresentationData;
+    const estimate = ewma.getEstimate();
+    const confidenceLevel = loadedSegments >= 5 &&
+                            loadedDuration >= 10 ? ScoreConfidenceLevel.HIGH :
+                                                   ScoreConfidenceLevel.LOW;
+
+    return [estimate, confidenceLevel];
   }
 
   /**
@@ -116,19 +133,9 @@ export default class RepresentationScoreCalculator {
   public getLastStableRepresentation() : Representation | null {
     return this._lastRepresentationWithGoodScore;
   }
+}
 
-  /**
-   * Returns EWMA for the given Representation.
-   * null if no EWMA is currently stored for it.
-   * @param {Representation} representation
-   * @returns {EWMA|null}
-   */
-  private _getEWMA(representation : Representation) : EWMA | null {
-    if (this._currentRepresentationData != null &&
-        this._currentRepresentationData.representation.id === representation.id)
-    {
-      return this._currentRepresentationData.ewma;
-    }
-    return null;
-  }
+export const enum ScoreConfidenceLevel {
+  HIGH = 1,
+  LOW = 0,
 }

package/src/core/abr/{__tests__ → utils/__tests__}/filter_by_bitrate.test.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { Representation } from "../../../manifest";
+import { Representation } from "../../../../manifest";
 import filterByBitrate from "../filter_by_bitrate";
 
 describe("ABR - filterByBitrate", () => {

package/src/core/abr/{__tests__ → utils/__tests__}/filter_by_width.test.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { Representation } from "../../../manifest";
+import { Representation } from "../../../../manifest";
 import filterByWidth from "../filter_by_width";
 
 describe("ABR - filterByWidth", () => {

package/src/core/abr/{__tests__ → utils/__tests__}/select_optimal_representation.test.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { Representation } from "../../../manifest";
+import { Representation } from "../../../../manifest";
 import selectOptimalRepresentation from "../select_optimal_representation";
 
 describe("ABR - selectOptimalRepresentation", () => {

package/src/core/abr/{filter_by_bitrate.ts → utils/filter_by_bitrate.ts}

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 
-import { Representation } from "../../manifest";
-import arrayFindIndex from "../../utils/array_find_index";
+import { Representation } from "../../../manifest";
+import arrayFindIndex from "../../../utils/array_find_index";
 
 /**
  * Get only representations lower or equal to a given bitrate.

package/src/core/abr/{filter_by_width.ts → utils/filter_by_width.ts}

@@ -14,9 +14,9 @@
  * limitations under the License.
  */
 
-import { Representation } from "../../manifest";
-import arrayFind from "../../utils/array_find";
-import takeFirstSet from "../../utils/take_first_set";
+import { Representation } from "../../../manifest";
+import arrayFind from "../../../utils/array_find";
+import takeFirstSet from "../../../utils/take_first_set";
 
 /**
  * Filter representations based on their width: