Refactor/Rename PlaybackObserver to MediaElementMonitor

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/index.ts";
 import type {
   ObservationPosition,
-  IReadOnlyPlaybackObserver,
-} from "../../playback_observer/index.ts";
+  IReadOnlyMediaElementMonitor,
+} from "../../media_element_monitor/index.ts";
 import isNullOrUndefined from "../../utils/is_null_or_undefined.ts";
 import noop from "../../utils/noop.ts";
 import type { IRange } from "../../utils/ranges.ts";
@@ -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/index.ts";
 import arrayFind from "../../utils/array_find.ts";
 import isNullOrUndefined from "../../utils/is_null_or_undefined.ts";
 import getMonotonicTimeStamp from "../../utils/monotonic_timestamp.ts";
-import type { IRepresentationEstimatorPlaybackObservation } from "./adaptive_representation_selector.ts";
+import type { IRepresentationEstimatorMediaObservation } from "./adaptive_representation_selector.ts";
 import type BandwidthEstimator from "./utils/bandwidth_estimator.ts";
 import EWMA from "./utils/ewma.ts";
 import type {
@@ -30,7 +30,7 @@ import type {
 
 /** Object describing the current playback conditions. */
 export 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/index.ts";
 import type {
-  IReadOnlyPlaybackObserver,
+  IReadOnlyMediaElementMonitor,
   IRebufferingStatus,
   ObservationPosition,
-} from "../../playback_observer/index.ts";
+} from "../../media_element_monitor/index.ts";
 import type { ICmcdOptions, ICmcdPayload, ITrackType } from "../../public_types.ts";
 import createUuid from "../../utils/create_uuid.ts";
 import isNullOrUndefined from "../../utils/is_null_or_undefined.ts";
@@ -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("CmcdDataBuilder start");
     this._canceller = new TaskCanceller("CMCD monitoring");
-    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("CmcdDataBuilder stop");
     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 ||
       !isFinite(lastObservation.speed) ||
@@ -232,7 +232,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);
@@ -289,7 +289,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.ts";
 
 export type {
   ICmcdSegmentInfo,
-  ICmcdDataBuilderPlaybackObservation,
+  ICmcdDataBuilderMediaObservation,
 } from "./cmcd_data_builder.ts";
 export default CmcdDataBuilder;