Refactor/Rename PlaybackObserver to MediaElementMonitor

**TL;DR: This is a code simplification proposal to set a single
interface for all `HTMLMediaElement` interactions, under a class named
`MediaElementMonitor`. This is just a merge of the previous
`PlaybackObserver` module (which monitors playback) and of previously
direct `HTMLMediaElement` access (which would now be avoided in profit
of calling `MediaElementMonitor` methods).**

---

I worked on multiple R&D subjects recently that needed a re-thinking of
how we interact with the media element in the core logic:

- The "preload" work (to preload a content in-memory before playback).

  Here the idea was to make most core RxPlayer modules work optionally
  "headlessly" during a preloading phase (without an actual media
  element to play on), and to then be able to "hot swap" the media
  element at any point if the content needed to be actually played -
  with the intent of speeding up loading time for future contents.

- The "Core Dump" work (a planned API to output an extensive snapshot
  of the RxPlayer state and playback conditions on playback errors - for
  debugging, logging and advanced experimental mitigations purposes of
  platform issues).

  Here I needed to be able to access many media properties at once and
  both their current states but also their last pre-error status.

On both of those subjects, I found that passing around both the media
element and a `PlaybackObserver` everywhere was awkward and unnecessary:
the `PlaybackObserver` already contains the media element and has to be
used for some side-effects: e.g. seeking has to go through it.

So I propose here to just define a single interface to the media
element.

The most difficult step has been to know what to name that thing.
Initially I went with `MediaElementInterface`, but it didn't seem to be
really indicative of what 99% of its use is, which is to monitor
playback conditions.
So in the end I just went with `MediaElementMonitor`. Though it also
allows side-effect on the media element (seeking, setting `src`...)

Not everything is simplified yet (there are still places when I rely on
the two), but it's a good first step.

Author: peaBerberian

src/README.md

@@ -182,9 +182,9 @@ For the subdirectories and files in this directory not represented in that schem
 - `manifest` (_./manifest_): Defines a `Manifest` structure and its properties, a central
   structure of the player describing a content.
 
-- `PlaybackObserver` (./playback_observer): Defines `PlaybackObserver` instances, used by
-  many modules to obtain playback-related properties (such as the playing position, the
-  current playback speed etc.).
+- `MediaElementMonitor` (./media_element_monitor): Defines the `MediaElementMonitor` ,
+  used by many modules to poll the `HTMLMediaElement` for playback-related properties
+  (such as the playing position, the current playback speed etc.).
 
 - `parsers` (_./parsers_): Various parsers for several formats
 

src/core/adaptive/adaptive_representation_selector.ts

@@ -25,8 +25,8 @@ import type {
 } from "../../manifest";
 import type {
   ObservationPosition,
-  IReadOnlyPlaybackObserver,
-} from "../../playback_observer";
+  IReadOnlyMediaElementMonitor,
+} from "../../media_element_monitor";
 import isNullOrUndefined from "../../utils/is_null_or_undefined";
 import noop from "../../utils/noop";
 import type { IRange } from "../../utils/ranges";
@@ -88,15 +88,15 @@ export default function createAdaptiveRepresentationSelector(
    * @param {Object} context
    * @param {Object} currentRepresentation
    * @param {Object} representations
-   * @param {Object} playbackObserver
+   * @param {Object} mediaElementMonitor
    * @param {Object} stopAllEstimates
    * @returns {Array.<Object>}
    */
   return function getEstimates(
     context: { manifest: IManifest; period: IPeriod; adaptation: IAdaptation },
     currentRepresentation: IReadOnlySharedReference<IRepresentation | null>,
     representations: IReadOnlySharedReference<IRepresentation[]>,
-    playbackObserver: IReadOnlyPlaybackObserver<IRepresentationEstimatorPlaybackObservation>,
+    mediaElementMonitor: IReadOnlyMediaElementMonitor<IRepresentationEstimatorMediaObservation>,
     stopAllEstimates: CancellationSignal,
   ): IRepresentationEstimatorResponse {
     const { type } = context.adaptation;
@@ -113,7 +113,7 @@ export default function createAdaptiveRepresentationSelector(
         currentRepresentation,
         filters,
         initialBitrate,
-        playbackObserver,
+        mediaElementMonitor,
         representations,
         lowLatencyMode,
       },
@@ -165,7 +165,7 @@ function getEstimateReference(
     filters,
     initialBitrate,
     lowLatencyMode,
-    playbackObserver,
+    mediaElementMonitor,
     representations: representationsRef,
   }: IRepresentationEstimatorArguments,
   stopAllEstimates: CancellationSignal,
@@ -263,25 +263,25 @@ function getEstimateReference(
     const guessBasedChooser = new GuessBasedChooser(scoreCalculator, prevEstimate);
 
     // get initial observation for initial estimate
-    let lastPlaybackObservation = playbackObserver.getReference().getValue();
+    let lastMediaObservation = mediaElementMonitor.getReference().getValue();
 
     /** Reference through which estimates are emitted. */
     const innerEstimateRef = new SharedReference<IABREstimate>(getCurrentEstimate());
 
-    // Listen to playback observations
-    playbackObserver.listen(
+    // Listen to media observations
+    mediaElementMonitor.listen(
       (obs) => {
-        lastPlaybackObservation = obs;
+        lastMediaObservation = obs;
         updateEstimate();
       },
       { includeLastObservation: false, clearSignal: innerCancellationSignal },
     );
 
     onAddedSegment = function (val: IAddedSegmentCallbackPayload) {
-      if (lastPlaybackObservation === null) {
+      if (lastMediaObservation === null) {
         return;
       }
-      const { position, speed } = lastPlaybackObservation;
+      const { position, speed } = lastMediaObservation;
       const timeRanges = val.buffered;
       const bufferGap = getLeftSizeOfRange(timeRanges, position.getWanted());
       const { representation } = val.content;
@@ -310,7 +310,7 @@ function getEstimateReference(
 
     /** Returns the actual estimate based on all methods and algorithm available. */
     function getCurrentEstimate(): IABREstimate {
-      const { bufferGap, position, maximumPosition } = lastPlaybackObservation;
+      const { bufferGap, position, maximumPosition } = lastMediaObservation;
       const resolutionLimit = filters.limitResolution.getValue();
       const bitrateThrottle = filters.throttleBitrate.getValue();
       const currentRepresentationVal = currentRepresentation.getValue();
@@ -322,7 +322,7 @@ function getEstimateReference(
       );
       const requests = requestsStore.getRequests();
       const { bandwidthEstimate, bitrateChosen } = networkAnalyzer.getBandwidthEstimate(
-        lastPlaybackObservation,
+        lastMediaObservation,
         bandwidthEstimator,
         currentRepresentationVal,
         requests,
@@ -334,7 +334,7 @@ function getEstimateReference(
         stableRepresentation === null
           ? undefined
           : stableRepresentation.bitrate /
-            (lastPlaybackObservation.speed > 0 ? lastPlaybackObservation.speed : 1);
+            (lastMediaObservation.speed > 0 ? lastMediaObservation.speed : 1);
 
       const { ABR_ENTER_BUFFER_BASED_ALGO, ABR_EXIT_BUFFER_BASED_ALGO } =
         config.getCurrent();
@@ -415,7 +415,7 @@ function getEstimateReference(
       ) {
         chosenRepFromGuessMode = guessBasedChooser.getGuess(
           sortedRepresentations,
-          lastPlaybackObservation,
+          lastMediaObservation,
           currentRepresentationVal,
           currentBestBitrate,
           requests,
@@ -460,7 +460,7 @@ function getEstimateReference(
             chosenRepFromBufferSize.bitrate,
             currentRepresentationVal,
             requests,
-            lastPlaybackObservation,
+            lastMediaObservation,
           ),
           knownStableBitrate,
         };
@@ -481,7 +481,7 @@ function getEstimateReference(
             chosenRepFromBandwidth.bitrate,
             currentRepresentationVal,
             requests,
-            lastPlaybackObservation,
+            lastMediaObservation,
           ),
           knownStableBitrate,
         };
@@ -634,15 +634,15 @@ export interface IABREstimate {
 }
 
 /** Media properties `getEstimateReference` will need to keep track of. */
-export interface IRepresentationEstimatorPlaybackObservation {
+export interface IRepresentationEstimatorMediaObservation {
   /**
    * For the concerned media buffer, difference in seconds between the next
    * position where no segment data is available and the current position.
    */
   bufferGap: number;
   /**
    * Information on the current media position in seconds at the time of a
-   * Playback Observation.
+   * media observation.
    */
   position: ObservationPosition;
   /**
@@ -744,7 +744,7 @@ export interface IRepresentationEstimatorArguments {
   /** Class allowing to estimate the current network bandwidth. */
   bandwidthEstimator: BandwidthEstimator;
   /** Emit regular playback information. */
-  playbackObserver: IReadOnlyPlaybackObserver<IRepresentationEstimatorPlaybackObservation>;
+  mediaElementMonitor: IReadOnlyMediaElementMonitor<IRepresentationEstimatorMediaObservation>;
   /**
    * The Representation currently loaded.
    * `null` if no Representation is currently loaded.
@@ -794,7 +794,7 @@ export type IRepresentationEstimator = (
   /** Reference emitting the list of available Representations to choose from. */
   representations: IReadOnlySharedReference<IRepresentation[]>,
   /** Regularly emits playback conditions */
-  playbackObserver: IReadOnlyPlaybackObserver<IRepresentationEstimatorPlaybackObservation>,
+  mediaElementMonitor: IReadOnlyMediaElementMonitor<IRepresentationEstimatorMediaObservation>,
   /**
    * After this `CancellationSignal` emits, resources will be disposed and
    * estimates will stop to be emitted.

src/core/adaptive/buffer_based_chooser.ts

@@ -130,15 +130,13 @@ export default class BufferBasedChooser {
   }
 
   /**
-   * @param {Object} playbackObservation
+   * @param {Object} mediaObservation
    * @returns {number|undefined}
    */
-  public onAddedSegment(
-    playbackObservation: IBufferBasedChooserPlaybackObservation,
-  ): void {
+  public onAddedSegment(mediaObservation: IBufferBasedChooserMediaObservation): void {
     const bufferLevels = this._levelsMap;
     const bitrates = this._bitrates;
-    const { bufferGap, currentBitrate, currentScore, speed } = playbackObservation;
+    const { bufferGap, currentBitrate, currentScore, speed } = mediaObservation;
     if (isNullOrUndefined(currentBitrate)) {
       this._currentEstimate = bitrates[0];
       return;
@@ -256,8 +254,8 @@ export default class BufferBasedChooser {
   }
 }
 
-/** Playback observation needed by the `BufferBasedChooser`. */
-export interface IBufferBasedChooserPlaybackObservation {
+/** media observation needed by the `BufferBasedChooser`. */
+export interface IBufferBasedChooserMediaObservation {
   /**
    * Difference in seconds between the current position and the next
    * non-buffered position in the buffer for the currently-considered

src/core/adaptive/guess_based_chooser.ts

@@ -70,7 +70,7 @@ export default class GuessBasedChooser {
    * 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} observation - Last media observation performed.
    * @param {Object} currentRepresentation - The Representation currently
    * loading.
    * @param {number} incomingBestBitrate - The bitrate of the Representation

src/core/adaptive/index.ts

@@ -21,7 +21,7 @@ import type {
   IMetricsCallbackPayload,
   IRepresentationEstimator,
   IRepresentationEstimatorCallbacks,
-  IRepresentationEstimatorPlaybackObservation,
+  IRepresentationEstimatorMediaObservation,
   IRepresentationEstimatorThrottlers as IABRThrottlers,
   IRequestBeginCallbackPayload,
   IRequestEndCallbackPayload,
@@ -39,7 +39,7 @@ export type {
   IABREstimate,
   IMetricsCallbackPayload,
   IRepresentationEstimatorCallbacks,
-  IRepresentationEstimatorPlaybackObservation,
+  IRepresentationEstimatorMediaObservation,
   IRequestBeginCallbackPayload,
   IRequestProgressCallbackPayload,
   IRequestEndCallbackPayload,

src/core/adaptive/network_analyzer.ts

@@ -20,7 +20,7 @@ import type { IRepresentation } from "../../manifest";
 import arrayFind from "../../utils/array_find";
 import isNullOrUndefined from "../../utils/is_null_or_undefined";
 import getMonotonicTimeStamp from "../../utils/monotonic_timestamp";
-import type { IRepresentationEstimatorPlaybackObservation } from "./adaptive_representation_selector";
+import type { IRepresentationEstimatorMediaObservation } from "./adaptive_representation_selector";
 import type BandwidthEstimator from "./utils/bandwidth_estimator";
 import EWMA from "./utils/ewma";
 import type {
@@ -30,7 +30,7 @@ import type {
 
 /** Object describing the current playback conditions. */
 type IPlaybackConditionsInfo = Pick<
-  IRepresentationEstimatorPlaybackObservation,
+  IRepresentationEstimatorMediaObservation,
   "bufferGap" | "position" | "speed" | "duration"
 >;
 

src/core/cmcd/cmcd_data_builder.ts

@@ -7,10 +7,10 @@ import type {
   ISegment,
 } from "../../manifest";
 import type {
-  IReadOnlyPlaybackObserver,
+  IReadOnlyMediaElementMonitor,
   IRebufferingStatus,
   ObservationPosition,
-} from "../../playback_observer";
+} from "../../media_element_monitor";
 import type { ICmcdOptions, ICmcdPayload, ITrackType } from "../../public_types";
 import createUuid from "../../utils/create_uuid";
 import isNullOrUndefined from "../../utils/is_null_or_undefined";
@@ -60,10 +60,10 @@ export interface ICmcdSegmentInfo {
 }
 
 /**
- * Media playback observation's properties the `CmcdDataBuilder` wants to have
+ * Media media observation's properties the `CmcdDataBuilder` wants to have
  * access to.
  */
-export interface ICmcdDataBuilderPlaybackObservation {
+export interface ICmcdDataBuilderMediaObservation {
   /**
    * Ranges of buffered data per type of media.
    * `null` if no buffer exists for that type of media.
@@ -81,7 +81,7 @@ export interface ICmcdDataBuilderPlaybackObservation {
    * status.
    * "Rebuffering" is a status where the player has not enough buffer ahead to
    * play reliably.
-   * The RxPlayer should pause playback when a playback observation indicates the
+   * The RxPlayer should pause playback when a media observation indicates the
    * rebuffering status.
    */
   rebuffering: IRebufferingStatus | null;
@@ -98,7 +98,7 @@ export default class CmcdDataBuilder {
   private _contentId: string;
   private _typePreference: TypePreference;
   private _lastThroughput: Partial<Record<ITrackType, number | undefined>>;
-  private _playbackObserver: IReadOnlyPlaybackObserver<ICmcdDataBuilderPlaybackObservation> | null;
+  private _mediaElementMonitor: IReadOnlyMediaElementMonitor<ICmcdDataBuilderMediaObservation> | null;
   private _bufferStarvationToggle: boolean;
   private _canceller: TaskCanceller | null;
 
@@ -115,28 +115,28 @@ export default class CmcdDataBuilder {
         ? TypePreference.Headers
         : TypePreference.QueryString;
     this._bufferStarvationToggle = false;
-    this._playbackObserver = null;
+    this._mediaElementMonitor = null;
     this._lastThroughput = {};
     this._canceller = null;
   }
 
   /**
-   * Start listening to the given `playbackObserver` so the `CmcdDataBuilder`
+   * Start listening to the given `mediaElementMonitor` so the `CmcdDataBuilder`
    * can extract some playback-linked metadata that it needs.
    *
    * It will keep listening for media data until `stopMonitoringPlayback` is called.
    *
    * If `startMonitoringPlayback` is called again, the previous monitoring is
    * also cancelled.
-   * @param {Object} playbackObserver
+   * @param {Object} mediaElementMonitor
    */
   public startMonitoringPlayback(
-    playbackObserver: IReadOnlyPlaybackObserver<ICmcdDataBuilderPlaybackObservation>,
+    mediaElementMonitor: IReadOnlyMediaElementMonitor<ICmcdDataBuilderMediaObservation>,
   ): void {
     this._canceller?.cancel();
     this._canceller = new TaskCanceller();
-    this._playbackObserver = playbackObserver;
-    playbackObserver.listen(
+    this._mediaElementMonitor = mediaElementMonitor;
+    mediaElementMonitor.listen(
       (obs) => {
         if (obs.rebuffering !== null) {
           this._bufferStarvationToggle = true;
@@ -153,7 +153,7 @@ export default class CmcdDataBuilder {
   public stopMonitoringPlayback(): void {
     this._canceller?.cancel();
     this._canceller = null;
-    this._playbackObserver = null;
+    this._mediaElementMonitor = null;
   }
 
   /**
@@ -184,7 +184,7 @@ export default class CmcdDataBuilder {
         : undefined;
     props.sid = this._sessionId;
 
-    const lastObservation = this._playbackObserver?.getReference().getValue();
+    const lastObservation = this._mediaElementMonitor?.getReference().getValue();
     props.pr =
       lastObservation === undefined || lastObservation.speed === 1
         ? undefined
@@ -229,7 +229,7 @@ export default class CmcdDataBuilder {
    * @returns {Object}
    */
   public getCmcdDataForSegmentRequest(content: ICmcdSegmentInfo): ICmcdPayload {
-    const lastObservation = this._playbackObserver?.getReference().getValue();
+    const lastObservation = this._mediaElementMonitor?.getReference().getValue();
 
     const props = this._getCommonCmcdData(this._lastThroughput[content.adaptation.type]);
     props.br = Math.round(content.representation.bitrate / 1000);
@@ -286,7 +286,7 @@ export default class CmcdDataBuilder {
       if (!isNullOrUndefined(bufferedForType)) {
         // TODO more precize position estimate?
         const position =
-          this._playbackObserver?.getCurrentTime() ??
+          this._mediaElementMonitor?.getCurrentTime() ??
           lastObservation.position.getWanted() ??
           lastObservation.position.getPolled();
         for (const range of bufferedForType) {

src/core/cmcd/index.ts

@@ -2,6 +2,6 @@ import CmcdDataBuilder from "./cmcd_data_builder";
 
 export type {
   ICmcdSegmentInfo,
-  ICmcdDataBuilderPlaybackObservation,
+  ICmcdDataBuilderMediaObservation,
 } from "./cmcd_data_builder";
 export default CmcdDataBuilder;