rx-player 3.26.1 → 3.26.2

package/src/core/abr/pending_requests_store.ts

@@ -15,38 +15,14 @@
  */
 
 import log from "../../log";
+import Manifest, {
+  Adaptation,
+  ISegment,
+  Period,
+  Representation,
+} from "../../manifest";
 import objectValues from "../../utils/object_values";
 
-export interface IProgressEventValue {
-  duration : number; // current duration for the request, in ms
-  id: string|number; // unique ID for the request
-  size : number; // current downloaded size, in bytes
-  timestamp : number; // timestamp of the progress event since unix epoch, in ms
-  totalSize : number; // total size to download, in bytes
-}
-
-export interface IBeginRequestValue {
-  id: string|number;
-  time: number;
-  duration: number;
-  requestTimestamp: number;
-}
-
-export interface IRequestInfo {
-  duration : number; // duration of the corresponding chunk, in seconds
-  progress: IProgressEventValue[]; // progress events for this request
-  requestTimestamp: number; // unix timestamp at which the request began, in ms
-  time: number; // time at which the corresponding segment begins, in seconds
-}
-
-export interface IProgressEventValue {
-  duration : number; // current duration for the request, in ms
-  id: string|number; // unique ID for the request
-  size : number; // current downloaded size, in bytes
-  timestamp : number; // timestamp of the progress event since unix epoch, in ms
-  totalSize : number; // total size to download, in bytes
-}
-
 /**
  * Store information about pending requests, like information about:
  *   - for which segments they are
@@ -65,22 +41,21 @@ export default class PendingRequestsStore {
    * @param {string} id
    * @param {Object} payload
    */
-  public add(payload : IBeginRequestValue) : void {
-    const { id, time, duration, requestTimestamp } = payload;
-    this._currentRequests[id] = { time,
-                                  duration,
-                                  requestTimestamp,
-                                  progress: [] };
+  public add(payload : IPendingRequestStoreBegin) : void {
+    const { id, requestTimestamp, content } = payload;
+    this._currentRequests[id] = { requestTimestamp,
+                                  progress: [],
+                                  content };
   }
 
   /**
    * Notify of the progress of a currently pending request.
    * @param {Object} progress
    */
-  public addProgress(progress : IProgressEventValue) : void {
+  public addProgress(progress : IPendingRequestStoreProgress) : void {
     const request = this._currentRequests[progress.id];
     if (request == null) {
-      if (__DEV__) {
+      if (__ENVIRONMENT__.CURRENT_ENV === __ENVIRONMENT__.DEV as number) {
         throw new Error("ABR: progress for a request not added");
       }
       log.warn("ABR: progress for a request not added");
@@ -95,9 +70,11 @@ export default class PendingRequestsStore {
    */
   public remove(id : string) : void {
     if (this._currentRequests[id] == null) {
-      if (__DEV__) {
-        throw new Error("ABR: can't remove unknown request");
-      }
+      // TODO This breaks github actions.
+      // Find why
+      // if (__ENVIRONMENT__.CURRENT_ENV === __ENVIRONMENT__.DEV as number) {
+      //   throw new Error("ABR: can't remove unknown request");
+      // }
       log.warn("ABR: can't remove unknown request");
     }
     delete this._currentRequests[id];
@@ -111,6 +88,63 @@ export default class PendingRequestsStore {
   public getRequests() : IRequestInfo[] {
     return objectValues(this._currentRequests)
       .filter((x) : x is IRequestInfo => x != null)
-      .sort((reqA, reqB) => reqA.time - reqB.time);
+      .sort((reqA, reqB) => reqA.content.segment.time - reqB.content.segment.time);
   }
 }
+
+/**
+ * Payload needed to add progress information for a request to the
+ * PendingRequestsStore.
+ */
+export interface IPendingRequestStoreProgress {
+  /** 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
+   * `IABRRequestBeginEventValue` 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;
+}
+
+/** Payload needed to add a request to the PendingRequestsStore. */
+export interface IPendingRequestStoreBegin {
+  /**
+   * String identifying this request.
+   *
+   * Only one request communicated to the current `RepresentationEstimator`
+   * should have this `id` at the same time.
+   */
+  id: string;
+  /** Value of `performance.now` at the time the request began.  */
+  requestTimestamp: number;
+  /** Context associated to the segment. */
+  content: IRequestInfoContent;
+}
+
+/** Information linked to a segment request, stored in the PendingRequestsStore. */
+export interface IRequestInfo {
+  /** Information on the current progress made by this request. */
+  progress: IPendingRequestStoreProgress[];
+  /** `Performance.now()` corresponding to the time at which the request began. */
+  requestTimestamp: number;
+  /** Context associated to the segment. */
+  content: IRequestInfoContent;
+}
+
+/** Content linked to a segment request. */
+export interface IRequestInfoContent {
+  manifest : Manifest;
+  period : Period;
+  adaptation : Adaptation;
+  representation : Representation;
+  segment : ISegment;
+}

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,12 +37,25 @@ import {
 import { getLeftSizeOfRange } from "../../utils/ranges";
 import BandwidthEstimator from "./bandwidth_estimator";
 import BufferBasedChooser from "./buffer_based_chooser";
-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.
@@ -111,14 +122,17 @@ export interface IABREstimate {
   knownStableBitrate?: number;
 }
 
-/** 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
@@ -127,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;
@@ -173,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;
 }
 
 /**
@@ -201,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;
 }
 
 /**
@@ -229,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. */
@@ -297,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>;
   /**
@@ -372,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;
 }
 
 /**
@@ -399,7 +396,7 @@ function getFilteredRepresentations(
  */
 export default function RepresentationEstimator({
   bandwidthEstimator,
-  clock$,
+  observation$,
   filters$,
   initialBitrate,
   lowLatencyMode,
@@ -420,18 +417,21 @@ export default function RepresentationEstimator({
    * @param {Object} value
    */
   function onMetric(value : IABRMetricsEventValue) : void {
-    const { duration, size, content } = value;
+    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(
@@ -490,108 +490,183 @@ 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)
+      const bufferBasedEstimation$ = BufferBasedChooser(bufferBasedobservation$, bitrates)
         .pipe(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 };
         })
       );
     }));