rx-player 4.5.0-dev.2026033100 → 4.5.0-dev.2026041501

package/src/main_thread/init/media_source_content_initializer.ts

@@ -190,7 +190,6 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
       manifest: null,
       mediaSourceInfo: null,
       rebufferingController: null,
-      streamEventsEmitter: null,
       initialTime: undefined,
       autoPlay: undefined,
       initialPlayPerformed: null,
@@ -353,21 +352,30 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
     }
 
     let textDisplayer: ITextDisplayer | null = null;
-    if (
-      this._settings.textTrackOptions.textTrackMode === "html" &&
-      features.htmlTextDisplayer !== null
-    ) {
-      assert(this._hasTextBufferFeature());
-      textDisplayer = new features.htmlTextDisplayer(
-        mediaElement,
-        this._settings.textTrackOptions.textTrackElement,
+    try {
+      if (
+        this._settings.textTrackOptions.textTrackMode === "html" &&
+        features.htmlTextDisplayer !== null
+      ) {
+        assert(this._hasTextBufferFeature());
+        textDisplayer = new features.htmlTextDisplayer(
+          mediaElement,
+          this._settings.textTrackOptions.textTrackElement,
+        );
+      } else if (features.nativeTextDisplayer !== null) {
+        assert(this._hasTextBufferFeature());
+        textDisplayer = new features.nativeTextDisplayer(mediaElement);
+      } else {
+        assert(!this._hasTextBufferFeature());
+      }
+    } catch (err) {
+      log.error(
+        "Init",
+        "failed to initialize text displayer",
+        err instanceof Error ? err : "Unknown Error",
       );
-    } else if (features.nativeTextDisplayer !== null) {
-      assert(this._hasTextBufferFeature());
-      textDisplayer = new features.nativeTextDisplayer(mediaElement);
-    } else {
-      assert(!this._hasTextBufferFeature());
     }
+
     this._initCanceller.signal.register((err) => {
       textDisplayer?.stop(err.reason);
     });
@@ -402,12 +410,32 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
       contentInfo.contentDecryptor = contentDecryptor;
     }
 
+    const streamEventsEmitter = new StreamEventsEmitter(playbackObserver);
+    streamEventsEmitter.addEventListener(
+      "event",
+      (payload) => {
+        this.trigger("streamEvent", payload);
+      },
+      this._initCanceller.signal,
+    );
+    streamEventsEmitter.addEventListener(
+      "eventSkip",
+      (payload) => {
+        this.trigger("streamEventSkip", payload);
+      },
+      this._initCanceller.signal,
+    );
+    this._initCanceller.signal.register((err) => {
+      streamEventsEmitter.stop(err.reason);
+    });
+
     const playbackStartParams = {
       mediaElement,
       textDisplayer,
       playbackObserver,
       drmInitializationStatus,
       mediaSourceStatus,
+      streamEventsEmitter,
     };
     mediaSourceStatus.onUpdate(
       (msInitStatus, stopListeningMSStatus) => {
@@ -510,6 +538,7 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
         textDisplayer,
         playbackObserver,
         mediaSourceStatus,
+        streamEventsEmitter,
         position,
         !isPaused,
       );
@@ -921,6 +950,7 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
             return;
           }
           const manifest = msgData.value.manifest;
+          streamEventsEmitter.start(manifest);
           this._currentContentInfo.manifest = manifest;
           this._updateCodecSupport(manifest, mediaElement);
           this._startPlaybackIfReady(playbackStartParams);
@@ -948,8 +978,7 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
               msgData.value.updates,
             );
           }
-          this._currentContentInfo?.streamEventsEmitter?.onManifestUpdate(manifest);
-
+          streamEventsEmitter.onManifestUpdate(manifest);
           this._updateCodecSupport(manifest, mediaElement);
           this.trigger("manifestUpdate", msgData.value.updates);
           break;
@@ -1558,6 +1587,7 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
     textDisplayer: ITextDisplayer | null,
     playbackObserver: IMediaElementPlaybackObserver,
     mediaSourceStatus: SharedReference<MediaSourceInitializationStatus>,
+    streamEventsEmitter: StreamEventsEmitter,
     position: number,
     autoPlay: boolean,
   ) {
@@ -1565,6 +1595,7 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
     this._currentMediaSourceCanceller = new TaskCanceller("Init MediaSource");
     this._currentMediaSourceCanceller.linkToSignal(this._initCanceller.signal);
     mediaSourceStatus.setValue(MediaSourceInitializationStatus.AttachNow);
+    streamEventsEmitter.pause();
     this.trigger("reloadingMediaSource", { position, autoPlay });
 
     mediaSourceStatus.onUpdate(
@@ -1580,6 +1611,7 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
             mediaElement,
             textDisplayer,
             playbackObserver,
+            streamEventsEmitter,
           },
           this._currentMediaSourceCanceller.signal,
         );
@@ -1635,6 +1667,7 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
       mediaElement: IMediaElement;
       textDisplayer: ITextDisplayer | null;
       playbackObserver: IMediaElementPlaybackObserver;
+      streamEventsEmitter: StreamEventsEmitter;
     },
     cancelSignal: CancellationSignal,
   ): IReadOnlyPlaybackObserver<ICorePlaybackObservation> | null {
@@ -1652,10 +1685,17 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
 
     const { manifest, mediaSourceInfo } = this._currentContentInfo;
     const { speed } = this._settings;
-    const { initialTime, autoPlay, mediaElement, textDisplayer, playbackObserver } =
-      parameters;
+    const {
+      initialTime,
+      autoPlay,
+      mediaElement,
+      textDisplayer,
+      playbackObserver,
+      streamEventsEmitter,
+    } = parameters;
     this._currentContentInfo.initialTime = initialTime;
     this._currentContentInfo.autoPlay = autoPlay;
+    streamEventsEmitter.pause(); // Only start polling events once ready to play
 
     const { autoPlayResult, initialPlayPerformed } = performInitialSeekAndPlay(
       {
@@ -1669,6 +1709,15 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
       cancelSignal,
     );
     this._currentContentInfo.initialPlayPerformed = initialPlayPerformed;
+    initialPlayPerformed.onUpdate(
+      (isPerformed, stopListening) => {
+        if (isPerformed) {
+          stopListening();
+          streamEventsEmitter.resume(); // We can now start polling events
+        }
+      },
+      { clearSignal: cancelSignal, emitCurrentValue: true },
+    );
     const corePlaybackObserver = createCorePlaybackObserver(
       playbackObserver,
       {
@@ -1711,36 +1760,6 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
     rebufferingController.start();
     this._currentContentInfo.rebufferingController = rebufferingController;
 
-    const currentContentInfo = this._currentContentInfo;
-    initialPlayPerformed.onUpdate(
-      (isPerformed, stopListening) => {
-        if (isPerformed) {
-          stopListening();
-          const streamEventsEmitter = new StreamEventsEmitter(manifest, playbackObserver);
-          currentContentInfo.streamEventsEmitter = streamEventsEmitter;
-          streamEventsEmitter.addEventListener(
-            "event",
-            (payload) => {
-              this.trigger("streamEvent", payload);
-            },
-            cancelSignal,
-          );
-          streamEventsEmitter.addEventListener(
-            "eventSkip",
-            (payload) => {
-              this.trigger("streamEventSkip", payload);
-            },
-            cancelSignal,
-          );
-          streamEventsEmitter.start();
-          cancelSignal.register((err) => {
-            streamEventsEmitter.stop(err.reason);
-          });
-        }
-      },
-      { clearSignal: cancelSignal, emitCurrentValue: true },
-    );
-
     const _getSegmentSinkMetrics = async (): Promise<ISegmentSinkMetrics | undefined> => {
       this._awaitingRequests.nextRequestId++;
       const requestId = this._awaitingRequests.nextRequestId;
@@ -1855,6 +1874,7 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
     playbackObserver: IMediaElementPlaybackObserver;
     drmInitializationStatus: IReadOnlySharedReference<IDrmInitializationStatus>;
     mediaSourceStatus: IReadOnlySharedReference<MediaSourceInitializationStatus>;
+    streamEventsEmitter: StreamEventsEmitter;
   }): boolean {
     if (this._currentContentInfo === null || this._currentContentInfo.manifest === null) {
       return false;
@@ -1884,6 +1904,7 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
         mediaElement: parameters.mediaElement,
         textDisplayer: parameters.textDisplayer,
         playbackObserver: parameters.playbackObserver,
+        streamEventsEmitter: parameters.streamEventsEmitter,
       },
       this._currentMediaSourceCanceller.signal,
     );
@@ -2055,13 +2076,6 @@ export interface IMediaSourceContentInitializerContentInfos {
    * `null` if none is currently created for the content.
    */
   rebufferingController: RebufferingController | null;
-  /**
-   * Current `StreamEventsEmitter` linked to the content, allowing to
-   * send events found in the Manifest.
-   *
-   * `null` if none is currently created for the content.
-   */
-  streamEventsEmitter: StreamEventsEmitter | null;
   /**
    * The initial position to seek to in seconds once the content is loadeed.
    * `undefined` if unknown yet.

package/src/main_thread/init/utils/__tests__/stream_events_emitter.test.ts

@@ -0,0 +1,175 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { IManifestMetadata } from "../../../../manifest";
+import type {
+  IPlaybackObservation,
+  IReadOnlyPlaybackObserver,
+} from "../../../../playback_observer";
+import { SeekingState } from "../../../../playback_observer";
+import SharedReference from "../../../../utils/reference";
+import type { CancellationSignal } from "../../../../utils/task_canceller";
+import TaskCanceller from "../../../../utils/task_canceller";
+import StreamEventsEmitter from "../stream_events_emitter/stream_events_emitter";
+
+describe("init - StreamEventsEmitter", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("should not send skipped events for positions crossed while the media is not ready", () => {
+    vi.useFakeTimers();
+
+    const observationRef = new SharedReference(generateObservation(4));
+    const playbackObserver = createPlaybackObserver(observationRef);
+    const streamEventsEmitter = new StreamEventsEmitter(playbackObserver);
+    const skippedEvents: unknown[] = [];
+    const regularEvents: unknown[] = [];
+    const stopCanceller = new TaskCanceller("test");
+
+    streamEventsEmitter.addEventListener(
+      "event",
+      (evt) => {
+        regularEvents.push(evt);
+      },
+      stopCanceller.signal,
+    );
+    streamEventsEmitter.addEventListener(
+      "eventSkip",
+      (evt) => {
+        skippedEvents.push(evt);
+      },
+      stopCanceller.signal,
+    );
+
+    streamEventsEmitter.start(generateManifest());
+    streamEventsEmitter.pause();
+
+    observationRef.setValue(generateObservation(9));
+    vi.advanceTimersByTime(200);
+
+    streamEventsEmitter.resume();
+    observationRef.setValue(generateObservation(9.1));
+    vi.advanceTimersByTime(200);
+
+    expect(regularEvents).toHaveLength(0);
+    expect(skippedEvents).toHaveLength(0);
+
+    streamEventsEmitter.stop("test end");
+    stopCanceller.cancel("test end");
+  });
+
+  it("should compare from the current position immediately after resuming", () => {
+    vi.useFakeTimers();
+
+    const observationRef = new SharedReference(generateObservation(4));
+    const playbackObserver = createPlaybackObserver(observationRef);
+    const streamEventsEmitter = new StreamEventsEmitter(playbackObserver);
+    const regularEvents: unknown[] = [];
+    const stopCanceller = new TaskCanceller("test");
+
+    streamEventsEmitter.addEventListener(
+      "event",
+      (evt) => {
+        regularEvents.push(evt);
+      },
+      stopCanceller.signal,
+    );
+
+    streamEventsEmitter.start(generateManifest());
+    streamEventsEmitter.pause();
+
+    observationRef.setValue(generateObservation(4.5));
+    streamEventsEmitter.resume();
+    observationRef.setValue(generateObservation(8.5));
+    vi.advanceTimersByTime(200);
+
+    expect(regularEvents).toHaveLength(1);
+
+    streamEventsEmitter.stop("test end");
+    stopCanceller.cancel("test end");
+  });
+});
+
+function createPlaybackObserver(
+  observationRef: SharedReference<IPlaybackObservation>,
+): IReadOnlyPlaybackObserver<IPlaybackObservation> {
+  return {
+    getCurrentTime() {
+      return observationRef.getValue().position.getPolled();
+    },
+    getPlaybackRate() {
+      return 1;
+    },
+    getReadyState() {
+      return 4;
+    },
+    getIsPaused() {
+      return false;
+    },
+    getReference() {
+      return observationRef;
+    },
+    listen(
+      cb: (observation: IPlaybackObservation, stopListening: () => void) => void,
+      options: {
+        includeLastObservation?: boolean | undefined;
+        clearSignal: CancellationSignal;
+      },
+    ) {
+      observationRef.onUpdate(cb, {
+        clearSignal: options.clearSignal,
+        emitCurrentValue: options.includeLastObservation,
+      });
+    },
+    deriveReadOnlyObserver() {
+      throw new Error("unused in this test");
+    },
+  } as unknown as IReadOnlyPlaybackObserver<IPlaybackObservation>;
+}
+
+function generateManifest(): IManifestMetadata {
+  return {
+    periods: [
+      {
+        start: 0,
+        streamEvents: [
+          {
+            start: 5,
+            end: 8,
+            id: "evt",
+            data: {
+              type: "dash-event-stream",
+              value: {
+                schemeIdUri: "urn:test",
+                timescale: 1,
+                xmlData: { data: "<Event />", namespaces: [] },
+              },
+            },
+          },
+        ],
+      },
+    ],
+  } as unknown as IManifestMetadata;
+}
+
+function generateObservation(currentTime: number): IPlaybackObservation {
+  return {
+    event: "timeupdate",
+    seeking: SeekingState.None,
+    rebuffering: null,
+    freezing: null,
+    duration: 100,
+    ended: false,
+    paused: false,
+    playbackRate: 1,
+    readyState: 4,
+    bufferGap: 10,
+    fullyLoaded: false,
+    currentRange: { start: 0, end: 20 },
+    buffered: {} as TimeRanges,
+    position: {
+      getPolled() {
+        return currentTime;
+      },
+    } as IPlaybackObservation["position"],
+  };
+}

package/src/main_thread/init/utils/stream_events_emitter/stream_events_emitter.ts

@@ -16,11 +16,11 @@
 
 import config from "../../../../config";
 import type { IManifestMetadata } from "../../../../manifest";
-import { SeekingState } from "../../../../playback_observer";
 import type {
   IPlaybackObservation,
   IReadOnlyPlaybackObserver,
 } from "../../../../playback_observer";
+import { SeekingState } from "../../../../playback_observer";
 import EventEmitter from "../../../../utils/event_emitter";
 import SharedReference from "../../../../utils/reference";
 import type { CancellationSignal } from "../../../../utils/task_canceller";
@@ -42,27 +42,34 @@ interface IStreamEventsEmitterEvent {
  * Get events from manifest and emit each time an event has to be emitted
  */
 export default class StreamEventsEmitter extends EventEmitter<IStreamEventsEmitterEvent> {
-  private _manifest: IManifestMetadata;
+  /** Regularly emit playback metrics such as the position. */
   private _playbackObserver: IReadOnlyPlaybackObserver<IPlaybackObservation>;
+  /** Current stream events tracked for the whole content. */
   private _scheduledEventsRef: SharedReference<
     Array<IStreamEventPayload | INonFiniteStreamEventPayload>
   >;
+  /** Events currently considered active, to only emit their enter/exit once. */
   private _eventsBeingPlayed: WeakMap<
     IStreamEventPayload | INonFiniteStreamEventPayload,
     true
   >;
+  /** Whether event evaluation is temporarily suspended, e.g. during a reload. */
+  private _isPaused: boolean;
+  /** Last observation used as comparison point for the next event check. */
+  private _previousObservation: {
+    /** Media position that is being played. */
+    currentTime: number;
+    /** If `true`, we're currently seeking in the media. */
+    isSeeking: boolean;
+  } | null;
+  /** Cancels the current emitter lifecycle. */
   private _canceller: TaskCanceller | null;
 
   /**
-   * @param {Object} manifest
    * @param {Object} playbackObserver
    */
-  constructor(
-    manifest: IManifestMetadata,
-    playbackObserver: IReadOnlyPlaybackObserver<IPlaybackObservation>,
-  ) {
+  constructor(playbackObserver: IReadOnlyPlaybackObserver<IPlaybackObservation>) {
     super();
-    this._manifest = manifest;
     this._playbackObserver = playbackObserver;
     this._canceller = null;
     this._scheduledEventsRef = new SharedReference<
@@ -72,22 +79,36 @@ export default class StreamEventsEmitter extends EventEmitter<IStreamEventsEmitt
       IStreamEventPayload | INonFiniteStreamEventPayload,
       true
     >();
+    this._isPaused = true;
+    this._previousObservation = null;
   }
 
-  public start(): void {
+  /**
+   * Initialize the emitter for the given content manifest.
+   *
+   * The emitter starts in a paused state so the caller can resume it only once
+   * the corresponding media instance is actually ready.
+   * @param {Object} manifest
+   */
+  public start(manifest: IManifestMetadata): void {
     if (this._canceller !== null) {
       return;
     }
     this._canceller = new TaskCanceller("StreamEventsEmitter");
 
     const cancelSignal = this._canceller.signal;
-    const playbackObserver = this._playbackObserver;
+    this._isPaused = true;
+    this._previousObservation = null;
+    this._eventsBeingPlayed = new WeakMap<
+      IStreamEventPayload | INonFiniteStreamEventPayload,
+      true
+    >();
 
     let isPollingEvents = false;
     let cancelCurrentPolling = new TaskCanceller("StreamEventsEmitter Polling");
     cancelCurrentPolling.linkToSignal(cancelSignal);
 
-    this._scheduledEventsRef.setValue(refreshScheduledEventsList([], this._manifest));
+    this._scheduledEventsRef.setValue(refreshScheduledEventsList([], manifest));
 
     this._scheduledEventsRef.onUpdate(
       ({ length: scheduledEventsLength }) => {
@@ -103,16 +124,22 @@ export default class StreamEventsEmitter extends EventEmitter<IStreamEventsEmitt
           return;
         }
         isPollingEvents = true;
-        let oldObservation = constructObservation();
         const checkStreamEvents = () => {
-          const newObservation = constructObservation();
+          if (this._isPaused) {
+            return;
+          }
+          const newObservation = this._constructObservation();
+          if (this._previousObservation === null) {
+            this._previousObservation = newObservation;
+            return;
+          }
           this._emitStreamEvents(
             this._scheduledEventsRef.getValue(),
-            oldObservation,
+            this._previousObservation,
             newObservation,
             cancelCurrentPolling.signal,
           );
-          oldObservation = newObservation;
+          this._previousObservation = newObservation;
         };
 
         const { STREAM_EVENT_EMITTER_POLL_INTERVAL } = config.getCurrent();
@@ -120,7 +147,7 @@ export default class StreamEventsEmitter extends EventEmitter<IStreamEventsEmitt
           checkStreamEvents,
           STREAM_EVENT_EMITTER_POLL_INTERVAL,
         );
-        playbackObserver.listen(checkStreamEvents, {
+        this._playbackObserver.listen(checkStreamEvents, {
           includeLastObservation: false,
           clearSignal: cancelCurrentPolling.signal,
         });
@@ -128,20 +155,34 @@ export default class StreamEventsEmitter extends EventEmitter<IStreamEventsEmitt
         cancelCurrentPolling.signal.register(() => {
           clearInterval(intervalId);
         });
-
-        function constructObservation() {
-          const lastObservation = playbackObserver.getReference().getValue();
-          const currentTime =
-            playbackObserver.getCurrentTime() ??
-            playbackObserver.getReference().getValue().position.getPolled();
-          const isSeeking = lastObservation.seeking !== SeekingState.None;
-          return { currentTime, isSeeking };
-        }
       },
       { emitCurrentValue: true, clearSignal: cancelSignal },
     );
   }
 
+  /**
+   * Suspend event evaluation until `resume` has been called.
+   *
+   * To use when playback metrics should be temporarily ignored, for example
+   * while reloading a content.
+   */
+  public pause(): void {
+    this._isPaused = true;
+    this._previousObservation = null;
+  }
+
+  /**
+   * Resume event evaluation from the current playback state.
+   */
+  public resume(): void {
+    this._isPaused = false;
+
+    // Take a snapshot right now to avoid comparing a post-reload position
+    // with a stale pre-reload observation.
+    this._previousObservation = this._constructObservation();
+  }
+
+  /** Refresh the tracked stream-event list after a manifest update. */
   public onManifestUpdate(man: IManifestMetadata) {
     const prev = this._scheduledEventsRef.getValue();
     this._scheduledEventsRef.setValue(refreshScheduledEventsList(prev, man));
@@ -156,12 +197,35 @@ export default class StreamEventsEmitter extends EventEmitter<IStreamEventsEmitt
     if (this._canceller !== null) {
       this._canceller.cancel(reason ?? "StreamEventsEmitter stop");
       this._canceller = null;
+      this._previousObservation = null;
+      this._eventsBeingPlayed = new WeakMap<
+        IStreamEventPayload | INonFiniteStreamEventPayload,
+        true
+      >();
     }
   }
 
+  /**
+   * Construct observation object relied on by the `StreamEventsEmitted` by
+   * generating it from this instance's `PlaybackObserver`.
+   */
+  private _constructObservation(): {
+    /** Current media position that is being played. */
+    currentTime: number;
+    /** If `true`, we're currently seeking in the media. */
+    isSeeking: boolean;
+  } {
+    const lastObservation = this._playbackObserver.getReference().getValue();
+    const currentTime =
+      this._playbackObserver.getCurrentTime() ??
+      this._playbackObserver.getReference().getValue().position.getPolled();
+    const isSeeking = lastObservation.seeking !== SeekingState.None;
+    return { currentTime, isSeeking };
+  }
+
   /**
    * Examine playback situation from playback observations to emit stream events and
-   * prepare set onExit callbacks if needed.
+   * prepare `onExit` callbacks if needed.
    * @param {Array.<Object>} scheduledEvents
    * @param {Object} oldObservation
    * @param {Object} newObservation

package/src/main_thread/render_thumbnail.ts

@@ -218,6 +218,10 @@ export default async function renderThumbnail(
       );
       throw error;
     }
+    if (srcError instanceof ThumbnailRenderingError) {
+      onFinished();
+      throw srcError;
+    }
     const formattedErr = formatError(srcError, {
       defaultCode: "NONE",
       defaultReason: "Unknown error",

package/src/main_thread/tracks_store/README.md

@@ -16,6 +16,18 @@ curtains.
 
 ## `TracksStore`
 
+`TracksStore` is the main implementation used for Manifest-based contents. It centralizes
+the currently chosen tracks and qualities and exposes simple operations for the API to
+switch them.
+
 ## `TrackDispatcher`
 
+`TrackDispatcher` links track decisions to the underlying streaming logic for a given
+type. It is responsible for propagating updated choices and constraints when the selected
+track or representations change.
+
 ## `MediaElementTracksStore`
+
+`MediaElementTracksStore` is the directfile-oriented counterpart. It relies on the media
+element's native track APIs (`audioTracks`, `videoTracks`, `textTracks`) instead of the
+Manifest-based track model used by `TracksStore`.