rx-player 4.0.0-dev.2023111400 → 4.0.0-dev.2023121900

package/src/core/api/playback_observer.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import isSeekingApproximate from "../../compat/is_seeking_approximate";
 import config from "../../config";
 import log from "../../log";
 import getMonotonicTimeStamp from "../../utils/monotonic_timestamp";
@@ -68,6 +69,14 @@ export default class PlaybackObserver {
    */
   private _lowLatencyMode : boolean;
 
+  /**
+   * If set, position which could not yet be seeked to as the HTMLMediaElement
+   * had a readyState of `0`.
+   * This position should be seeked to as soon as the HTMLMediaElement is able
+   * to handle it.
+   */
+  private _pendingSeek : number | null;
+
   /**
    * The RxPlayer usually wants to differientate when a seek was sourced from
    * the RxPlayer's internal logic vs when it was sourced from an outside
@@ -88,7 +97,7 @@ export default class PlaybackObserver {
   /**
    * Stores the last playback observation produced by the `PlaybackObserver`.:
    */
-  private _observationRef : IReadOnlySharedReference<IPlaybackObservation>;
+  private _observationRef : SharedReference<IPlaybackObservation>;
 
   /**
    * `TaskCanceller` allowing to free all resources and stop producing playback
@@ -96,6 +105,22 @@ export default class PlaybackObserver {
    */
   private _canceller : TaskCanceller;
 
+  /**
+   * On some devices (right now only seen on Tizen), seeking through the
+   * `currentTime` property can lead to the browser re-seeking once the
+   * segments have been loaded to improve seeking performances (for
+   * example, by seeking right to an intra video frame).
+   * In that case, we risk being in a conflict with that behavior: if for
+   * example we encounter a small discontinuity at the position the browser
+   * seeks to, we will seek over it, the browser would seek back and so on.
+   *
+   * This variable allows to store the maximum known position we were seeking to
+   * so we can detect when the browser seeked back (to avoid performing another
+   * seek after that). When browsers seek back to a position behind a
+   * discontinuity, they are usually able to skip them without our help.
+   */
+  private _expectedSeekingPosition : number | null;
+
   /**
    * Create a new `PlaybackObserver`, which allows to produce new "playback
    * observations" on various media events and intervals.
@@ -113,6 +138,20 @@ export default class PlaybackObserver {
     this._lowLatencyMode = options.lowLatencyMode;
     this._canceller = new TaskCanceller();
     this._observationRef = this._createSharedReference();
+    this._expectedSeekingPosition = null;
+    this._pendingSeek = null;
+
+    const onLoadedMetadata = () => {
+      if (this._pendingSeek !== null) {
+        const positionToSeekTo = this._pendingSeek;
+        this._pendingSeek = null;
+        this._actuallySetCurrentTime(positionToSeekTo);
+      }
+    };
+    mediaElement.addEventListener("loadedmetadata", onLoadedMetadata);
+    this._canceller.signal.register(() => {
+      mediaElement.removeEventListener("loadedmetadata", onLoadedMetadata);
+    });
   }
 
   /**
@@ -167,9 +206,13 @@ export default class PlaybackObserver {
    * @param {number} time
    */
   public setCurrentTime(time: number) : void {
-    this._internalSeeksIncoming.push(time);
-    log.info("API: Seeking internally", time);
-    this._mediaElement.currentTime = time;
+    if (this._mediaElement.readyState >= 1) {
+      this._actuallySetCurrentTime(time);
+    } else {
+      this._internalSeeksIncoming = [];
+      this._pendingSeek = time;
+      this._generateObservationForEvent("manual");
+    }
   }
 
   /**
@@ -251,112 +294,53 @@ export default class PlaybackObserver {
     return generateReadOnlyObserver(this, transform, this._canceller.signal);
   }
 
+  private _actuallySetCurrentTime(time: number) : void {
+    log.info("API: Seeking internally", time);
+    this._internalSeeksIncoming.push(time);
+    this._mediaElement.currentTime = time;
+  }
+
   /**
    * Creates the `IReadOnlySharedReference` that will generate playback
    * observations.
    * @returns {Object}
    */
-  private _createSharedReference() : IReadOnlySharedReference<IPlaybackObservation> {
+  private _createSharedReference() : SharedReference<IPlaybackObservation> {
     if (this._observationRef !== undefined) {
       return this._observationRef;
     }
 
-    let lastObservation : IPlaybackObservation | null;
     const { SAMPLING_INTERVAL_MEDIASOURCE,
             SAMPLING_INTERVAL_LOW_LATENCY,
             SAMPLING_INTERVAL_NO_MEDIASOURCE } = config.getCurrent();
-
-    const getCurrentObservation = (
-      event : IPlaybackObserverEventType
-    ) : IPlaybackObservation => {
-      let tmpEvt: IPlaybackObserverEventType = event;
-      let startedInternalSeekTime : number | undefined;
-      if (tmpEvt === "seeking" && this._internalSeeksIncoming.length > 0) {
-        tmpEvt = "internal-seeking";
-        startedInternalSeekTime = this._internalSeeksIncoming.shift();
-      }
-      const _lastObservation = lastObservation ?? this._generateInitialObservation();
-      const mediaTimings = getMediaInfos(this._mediaElement,
-                                         tmpEvt,
-                                         this._withMediaSource);
-      let pendingInternalSeek : number | null = null;
-      if (mediaTimings.seeking) {
-        if (typeof startedInternalSeekTime === "number") {
-          pendingInternalSeek = startedInternalSeekTime;
-        } else if (_lastObservation.pendingInternalSeek !== null && event !== "seeking") {
-          pendingInternalSeek = _lastObservation.pendingInternalSeek;
-        }
-      }
-      const rebufferingStatus = getRebufferingStatus(
-        _lastObservation,
-        mediaTimings,
-        { lowLatencyMode: this._lowLatencyMode,
-          withMediaSource: this._withMediaSource });
-
-      const freezingStatus = getFreezingStatus(_lastObservation, mediaTimings);
-      const timings = objectAssign(
-        {},
-        { rebuffering: rebufferingStatus,
-          freezing: freezingStatus,
-          pendingInternalSeek },
-        mediaTimings);
-      if (log.hasLevel("DEBUG")) {
-        log.debug("API: current media element state tick",
-                  "event", timings.event,
-                  "position", timings.position,
-                  "seeking", timings.seeking,
-                  "internalSeek", timings.pendingInternalSeek,
-                  "rebuffering", timings.rebuffering !== null,
-                  "freezing", timings.freezing !== null,
-                  "ended", timings.ended,
-                  "paused", timings.paused,
-                  "playbackRate", timings.playbackRate,
-                  "readyState", timings.readyState);
-      }
-      return timings;
-    };
-
-    const returnedSharedReference = new SharedReference(getCurrentObservation("init"),
-                                                        this._canceller.signal);
-
-    const generateObservationForEvent = (event : IPlaybackObserverEventType) => {
-      const newObservation = getCurrentObservation(event);
-      if (log.hasLevel("DEBUG")) {
-        log.debug("API: current playback timeline:\n" +
-                  prettyPrintBuffered(newObservation.buffered,
-                                      newObservation.position),
-                  `\n${event}`);
-      }
-      lastObservation = newObservation;
-      returnedSharedReference.setValue(newObservation);
-    };
-
+    const returnedSharedReference = new SharedReference(
+      this._getCurrentObservation("init"),
+      this._canceller.signal
+    );
     const interval = this._lowLatencyMode  ? SAMPLING_INTERVAL_LOW_LATENCY :
                      this._withMediaSource ? SAMPLING_INTERVAL_MEDIASOURCE :
                                              SAMPLING_INTERVAL_NO_MEDIASOURCE;
+    const onInterval = () => {
+      this._generateObservationForEvent("timeupdate");
+    };
     let intervalId = setInterval(onInterval, interval);
     const removeEventListeners = SCANNED_MEDIA_ELEMENTS_EVENTS.map((eventName) => {
-      this._mediaElement.addEventListener(eventName, onMediaEvent);
-      function onMediaEvent() {
+      const onMediaEvent = () => {
         restartInterval();
-        generateObservationForEvent(eventName);
-      }
+        this._generateObservationForEvent(eventName);
+      };
+      this._mediaElement.addEventListener(eventName, onMediaEvent);
       return () => {
         this._mediaElement.removeEventListener(eventName, onMediaEvent);
       };
     });
-
     this._canceller.signal.register(() => {
       clearInterval(intervalId);
       removeEventListeners.forEach(cb => cb());
       returnedSharedReference.finish();
     });
-
     return returnedSharedReference;
 
-    function onInterval() {
-      generateObservationForEvent("timeupdate");
-    }
 
     function restartInterval() {
       clearInterval(intervalId);
@@ -364,20 +348,123 @@ export default class PlaybackObserver {
     }
   }
 
-  private _generateInitialObservation() : IPlaybackObservation {
-    return objectAssign(getMediaInfos(this._mediaElement,
-                                      "init",
-                                      this._withMediaSource),
-                        { rebuffering: null,
-                          freezing: null,
-                          pendingInternalSeek: null });
+  private _getCurrentObservation(
+    event : IPlaybackObserverEventType
+  ) : IPlaybackObservation {
+    /** Actual event emitted through an observation. */
+    let tmpEvt: IPlaybackObserverEventType = event;
+
+    // NOTE: `this._observationRef` may be `undefined` because we might here be
+    // called in the constructor when that property is not yet set.
+    const previousObservation = this._observationRef === undefined ?
+      getInitialObservation(this._mediaElement, this._withMediaSource) :
+      this._observationRef.getValue();
+
+    /**
+     * If `true`, there is a seek operation ongoing but it was done from the
+     * `PlaybackObserver`'s `setCurrentTime` method, not from external code.
+     */
+    let isInternalSeeking = false;
+
+    /** If set, the position for which we plan to seek to as soon as possible. */
+    let pendingPosition: number | null = this._pendingSeek;
+
+    /** Initially-polled playback observation, before adjustments. */
+    const mediaTimings = getMediaInfos(this._mediaElement, this._withMediaSource);
+
+    if (tmpEvt === "seeking") {
+      // We just began seeking.
+      // Let's find out if the seek is internal or external and handle approximate
+      // seeking
+      if (this._internalSeeksIncoming.length > 0) {
+        isInternalSeeking = true;
+        tmpEvt = "internal-seeking";
+        const startedInternalSeekTime = this._internalSeeksIncoming.shift();
+        this._expectedSeekingPosition = isSeekingApproximate ?
+          Math.max(mediaTimings.position, startedInternalSeekTime ?? 0) :
+          mediaTimings.position;
+      } else {
+        this._expectedSeekingPosition = mediaTimings.position;
+      }
+    } else if (mediaTimings.seeking) {
+      // we're still seeking, this time without a "seeking" event so it's an
+      // already handled one, keep track of the last wanted position we wanted
+      // to seek to, to work-around devices re-seeking silently.
+      this._expectedSeekingPosition = Math.max(mediaTimings.position,
+                                               this._expectedSeekingPosition ?? 0);
+    } else if (isSeekingApproximate &&
+               this._expectedSeekingPosition !== null &&
+                 mediaTimings.position < this._expectedSeekingPosition)
+    {
+      // We're on a target with aproximate seeking, we're not seeking anymore, but
+      // we're not yet at the expected seeking position.
+      // Signal to the rest of the application that the intented position is not
+      // the current position but the one contained in `this._expectedSeekingPosition`
+      pendingPosition = this._expectedSeekingPosition;
+    } else {
+      this._expectedSeekingPosition = null;
+    }
+
+    if (mediaTimings.seeking &&
+        previousObservation.seeking === SeekingState.Internal &&
+        event !== "seeking")
+    {
+      isInternalSeeking = true;
+    }
+    const rebufferingStatus = getRebufferingStatus(
+      previousObservation,
+      mediaTimings,
+      tmpEvt,
+      { lowLatencyMode: this._lowLatencyMode,
+        withMediaSource: this._withMediaSource });
+
+    const freezingStatus = getFreezingStatus(previousObservation, mediaTimings, tmpEvt);
+
+    const seeking = isInternalSeeking    ? SeekingState.Internal :
+                    mediaTimings.seeking ? SeekingState.External :
+                                           SeekingState.None;
+    const timings: IPlaybackObservation = objectAssign(
+      {},
+      mediaTimings,
+      { position: new ObservationPosition(mediaTimings.position, pendingPosition),
+        event: tmpEvt,
+        seeking,
+        rebuffering: rebufferingStatus,
+        freezing: freezingStatus });
+    if (log.hasLevel("DEBUG")) {
+      log.debug("API: current media element state tick",
+                "event", timings.event,
+                "position", timings.position.getPolled(),
+                "seeking", timings.seeking,
+                "internalSeek", isInternalSeeking,
+                "rebuffering", timings.rebuffering !== null,
+                "freezing", timings.freezing !== null,
+                "ended", timings.ended,
+                "paused", timings.paused,
+                "playbackRate", timings.playbackRate,
+                "readyState", timings.readyState);
+    }
+    return timings;
+  }
+
+  private _generateObservationForEvent(event : IPlaybackObserverEventType): void {
+    const newObservation = this._getCurrentObservation(event);
+    if (log.hasLevel("DEBUG")) {
+      log.debug("API: current playback timeline:\n" +
+                prettyPrintBuffered(newObservation.buffered,
+                                    newObservation.position.getPolled()),
+                `\n${event}`);
+    }
+    this._observationRef.setValue(newObservation);
   }
 }
 
 /** "Event" that triggered the playback observation. */
 export type IPlaybackObserverEventType =
   /** First playback observation automatically emitted. */
-  "init" | // set once on first emit
+  "init" |
+  /** Observation manually forced by the PlaybackObserver. */
+  "manual" |
   /** Regularly emitted playback observation when no event happened in a long time. */
   "timeupdate" |
   /** On the HTML5 event with the same name */
@@ -439,8 +526,19 @@ interface IMediaInfos {
   readyState : number;
   /** Current `seeking` value on the mediaElement. */
   seeking : boolean;
-   /** Event that triggered this playback observation. */
-  event : IPlaybackObserverEventType;
+}
+
+/** Categorize a pending seek operation. */
+export const enum SeekingState {
+  /** We're not currently seeking. */
+  None,
+  /**
+   * We're currently seeking due to an internal logic of the RxPlayer (e.g.
+   * discontinuity skipping).
+   */
+  Internal,
+  /** We're currently seeking due to a regular seek wanted by the application. */
+  External,
 }
 
 /**
@@ -483,7 +581,16 @@ export interface IFreezingStatus {
 }
 
 /** Information emitted on each playback observation. */
-export interface IPlaybackObservation extends IMediaInfos {
+export interface IPlaybackObservation extends Omit<IMediaInfos, "position" | "seeking"> {
+   /** Event that triggered this playback observation. */
+  event : IPlaybackObserverEventType;
+  /** Current seeking state. */
+  seeking : SeekingState;
+  /**
+   * Information on the current position being played, the position for which
+   * media is wanted etc.
+   */
+  position : IObservationPosition;
   /**
    * Set if the player is short on audio and/or video media data and is a such,
    * rebuffering.
@@ -498,11 +605,103 @@ export interface IPlaybackObservation extends IMediaInfos {
    * `null` if the player is not frozen.
    */
   freezing : IFreezingStatus | null;
+}
+
+export type IObservationPosition = ObservationPosition;
+
+class ObservationPosition {
+  /**
+   * Known position at the time the Observation was emitted, in seconds.
+   *
+   * Note that it might have changed since. If you want truly precize
+   * information, you should recuperate it from the HTMLMediaElement directly
+   * through another mean.
+   */
+  private _last: number;
+  /**
+   * Actually wanted position in seconds that is not yet reached.
+   *
+   * This might for example be set to the initial position when the content is
+   * loading (and thus potentially at a `0` position) but which will be seeked
+   * to a given position once possible. It may also be the position of a seek
+   * that has not been properly accounted for by the current device.
+   */
+  private _wanted: number | null;
+  constructor(last: number, wanted: number | null) {
+    this._last = last;
+    this._wanted = wanted;
+  }
+
   /**
-   * If `true`, an "internal seek" (a seeking operation triggered by the
-   * RxPlayer code) is currently pending.
+   * Returns the playback position actually observed on the media element at
+   * the time the playback observation was made.
+   *
+   * Note that it may be different than the position for which media data is
+   * wanted in rare scenarios where the goal position is not yet set on the
+   * media element.
+   *
+   * You should use this value when you want to obtain the actual position set
+   * on the media element for browser compatibility purposes. Note that this
+   * position was calculated at observation time, it might thus not be
+   * up-to-date if what you want is milliseconds-accuracy.
+   *
+   * If what you want is the actual position which the player is intended to
+   * play, you should rely on `getWanted` instead`.
+   * @returns {number}
    */
-  pendingInternalSeek : number | null;
+  public getPolled(): number {
+    return this._last;
+  }
+
+  /**
+   * Returns the position which the player should consider to load media data
+   * at the time the observation was made.
+   *
+   * It can be different than the value returned by `getPolled` in rare
+   * scenarios:
+   *
+   *   - When the initial position has not been set yet.
+   *
+   *   - When the current device do not let the RxPlayer peform precize seeks,
+   *     usually for perfomance reasons by seeking to a previous IDR frame
+   *     instead (for now only Tizen may be like this), in which case we
+   *     prefer to generally rely on the position wanted by the player (this
+   *     e.g. prevents issues where the RxPlayer logic and the device are
+   *     seeking back and forth in a loop).
+   *
+   *   - When a wanted position has been "forced" (@see forceWantedPosition).
+   * @returns {number}
+   */
+  public getWanted(): number {
+    return this._wanted ?? this._last;
+  }
+
+  /**
+   * Method to call if you want to overwrite the currently wanted position.
+   * @param {number} pos
+   */
+  public forceWantedPosition(pos: number): void {
+    this._wanted = pos;
+  }
+
+  /**
+   * Returns `true` when the position wanted returned by `getWanted` and the
+   * actual position returned by `getPolled` may be different, meaning that
+   * we're currently not at the position we want to reach.
+   *
+   * This is a relatively rare situation which only happens when either the
+   * initial seek has not yet been performed. on specific targets where the
+   * seeking behavior is a little broken (@see getWanted) or when the wanted
+   * position has been forced (@see forceWantedPosition).
+   *
+   * In those situations, you might temporarily refrain from acting upon the
+   * actual current media position, as it may change soon.
+   *
+   * @returns {boolean}
+   */
+  public isAwaitingFuturePosition(): boolean {
+    return this._wanted !== null;
+  }
 }
 
 /**
@@ -640,12 +839,10 @@ function hasLoadedUntilTheEnd(
 /**
  * Get basic playback information.
  * @param {HTMLMediaElement} mediaElement
- * @param {string} event
  * @returns {Object}
  */
 function getMediaInfos(
   mediaElement : HTMLMediaElement,
-  event : IPlaybackObserverEventType,
   withMediaSource : boolean
 ) : IMediaInfos {
   const { buffered,
@@ -682,8 +879,7 @@ function getMediaInfos(
            paused,
            playbackRate,
            readyState,
-           seeking,
-           event };
+           seeking };
 }
 
 /**
@@ -695,18 +891,19 @@ function getMediaInfos(
  * @param {Object} currentInfo - Current set of basic information on the
  * `HTMLMediaElement`. This does not need every single property from a regular
  * playback observation.
+ * @param {string} currentEvt
  * @param {Object} options
  * @returns {Object|null}
  */
 function getRebufferingStatus(
   prevObservation : IPlaybackObservation,
   currentInfo : IMediaInfos,
+  currentEvt : IPlaybackObserverEventType,
   { withMediaSource, lowLatencyMode } : IPlaybackObserverOptions
 ) : IRebufferingStatus | null {
 
   const { REBUFFERING_GAP } = config.getCurrent();
-  const { event: currentEvt,
-          position: currentTime,
+  const { position: currentTime,
           bufferGap,
           currentRange,
           duration,
@@ -777,7 +974,7 @@ function getRebufferingStatus(
           (
             !paused &&
             currentEvt === "timeupdate" && prevEvt === "timeupdate" &&
-            currentTime === prevTime
+            currentTime === prevTime.getPolled()
           ) ||
           (
             currentEvt === "seeking" && (
@@ -790,7 +987,7 @@ function getRebufferingStatus(
     } else if (
       prevRebuffering !== null &&
       (
-        (currentEvt !== "seeking" && currentTime !== prevTime) ||
+        (currentEvt !== "seeking" && currentTime !== prevTime.getPolled()) ||
         currentEvt === "canplay" ||
         (bufferGap === undefined && readyState >= 3) ||
         (
@@ -840,11 +1037,13 @@ function getRebufferingStatus(
  * `null` if not.
  * @param {Object} prevObservation
  * @param {Object} currentInfo
+ * @param {string} currentEvt
  * @returns {Object|null}
  */
 function getFreezingStatus(
   prevObservation : IPlaybackObservation,
-  currentInfo : IMediaInfos
+  currentInfo : IMediaInfos,
+  currentEvt : IPlaybackObserverEventType
 ) : IFreezingStatus | null {
   const { MINIMUM_BUFFER_AMOUNT_BEFORE_FREEZING } = config.getCurrent();
   if (prevObservation.freezing) {
@@ -852,21 +1051,21 @@ function getFreezingStatus(
         currentInfo.paused ||
         currentInfo.readyState === 0 ||
         currentInfo.playbackRate === 0 ||
-        prevObservation.position !== currentInfo.position)
+        prevObservation.position.getPolled() !== currentInfo.position)
     {
       return null; // Quit freezing status
     }
     return prevObservation.freezing; // Stay in it
   }
 
-  return currentInfo.event === "timeupdate" &&
+  return currentEvt === "timeupdate" &&
          currentInfo.bufferGap !== undefined &&
          currentInfo.bufferGap > MINIMUM_BUFFER_AMOUNT_BEFORE_FREEZING &&
          !currentInfo.ended &&
          !currentInfo.paused &&
          currentInfo.readyState >= 1 &&
          currentInfo.playbackRate !== 0 &&
-         currentInfo.position === prevObservation.position ?
+         currentInfo.position === prevObservation.position.getPolled() ?
            { timestamp: getMonotonicTimeStamp() } :
            null;
 }
@@ -999,3 +1198,24 @@ function generateReadOnlyObserver<TSource, TDest>(
     },
   };
 }
+
+/**
+ * Generate the initial playback observation for when no event has yet been
+ * emitted to lead to one.
+ * @param {HTMLMediaElement} mediaElement
+ * @param {boolean} withMediaSource
+ * @returns {Object}
+ */
+function getInitialObservation(
+  mediaElement: HTMLMediaElement,
+  withMediaSource: boolean
+) : IPlaybackObservation {
+  const mediaTimings = getMediaInfos(mediaElement, withMediaSource);
+  return objectAssign(mediaTimings,
+                      { rebuffering: null,
+                        event: "init",
+                        seeking: SeekingState.None,
+                        position: { last: mediaTimings.position,
+                                    pending: undefined },
+                        freezing: null });
+}