rx-player 4.4.0 → 4.4.1-dev.2025101500

package/src/core/types.ts

@@ -1,8 +1,26 @@
+// NOTE: Only types and const enums should be exported by this file
+
+import type {
+  ISerializedMediaError,
+  ISerializedNetworkError,
+  ISerializedEncryptedMediaError,
+  ISerializedOtherError,
+} from "../errors";
+import type { IContentProtection, ITextDisplayerData } from "../main_thread/types";
+import type { IManifestMetadata, IPeriodsUpdateResult } from "../manifest";
+import type {
+  ISourceBufferInterfaceAppendBufferParameters,
+  SourceBufferType,
+} from "../mse";
+import type { ITrackType } from "../public_types";
+import type { IThumbnailResponse } from "../transports";
+import type { ILoggerLevel, ILogNamespace } from "../utils/logger";
 import type {
   IAdaptiveRepresentationSelectorArguments,
   IABRThrottlers,
   IResolutionInfo,
 } from "./adaptive";
+import type { IMessageReceiverCallback } from "./entry";
 import type {
   IManifestFetcherSettings,
   ISegmentQueueCreatorBackoffOptions,
@@ -13,6 +31,7 @@ import type {
   ITextDisplayerInterface,
 } from "./segment_sinks";
 import type SegmentSinksStore from "./segment_sinks";
+import type { ISegmentSinkMetrics } from "./segment_sinks/segment_sinks_store";
 import type {
   IAdaptationChoice,
   IPausedPlaybackObservation,
@@ -22,9 +41,6 @@ import type {
   ITrackSwitchingMode,
 } from "./stream";
 
-// NOTE: Only types should be exported by this file: Importing it should
-// not increase a JavaScript bundle's size
-
 /** Type of an `SegmentSinksStore` class. */
 export type ISegmentSinksStore = SegmentSinksStore;
 
@@ -33,6 +49,7 @@ export type {
   IAdaptiveRepresentationSelectorArguments,
   IABRThrottlers,
   IResolutionInfo,
+
   // Fetchers Metadata
   IManifestFetcherSettings,
   ISegmentQueueCreatorBackoffOptions,
@@ -41,6 +58,7 @@ export type {
   IBufferType,
   IBufferedChunk,
   ITextDisplayerInterface,
+
   // Stream Metadata
   IAdaptationChoice,
   IInbandEvent,
@@ -48,4 +66,614 @@ export type {
   IStreamOrchestratorPlaybackObservation,
   IRepresentationsChoice,
   ITrackSwitchingMode,
+
+  // CoreEntry
+  IMessageReceiverCallback,
 };
+
+/**
+ * Format of an RxPlayer error that has been serialized to be able to be
+ * easily cloned and be communicated through the `postMessage` API if
+ * needed.
+ */
+export type ISentError =
+  | ISerializedNetworkError
+  | ISerializedMediaError
+  | ISerializedEncryptedMediaError
+  | ISerializedOtherError;
+
+/**
+ * Message sent by the Core when its initialization finished succesfully.
+ *
+ * Once that message has been received, you can ensure that no
+ * `IInitErrorCoreMessage` will ever be received for that same core instance.
+ *
+ * Note that receiving this message is not a requirement before preparing and
+ * loading a content, both initialization and content loading can be started in
+ * parallel.
+ */
+export interface IInitSuccessCoreMessage {
+  type: CoreMessageType.InitSuccess;
+  value: null;
+}
+
+/**
+ * Message sent by the Core when its initialization finished with an error.
+ *
+ * Once that message has been received, you can ensure that no
+ * `IInitErrorCoreMessage` will ever be received for the same core instance.
+ *
+ * Note that you may received this message while preparing and/or loading a
+ * content, both initialization and content loading can be started in
+ * parallel.
+ * As such, this message may be coupled with a content error.
+ */
+export interface IInitErrorCoreMessage {
+  type: CoreMessageType.InitError;
+  value: {
+    /** A string describing the error encountered. */
+    errorMessage: string;
+
+    kind: "dashWasmInitialization";
+  };
+}
+
+/**
+ * Message sent by the Core when it want the low-level buffers to be "flushed".
+ *
+ * A "flush" is an operation which tries to "refresh" the content of low-level
+ * media buffers, either to ensure an update to it has been taken into account
+ * or to fix a problematic situation.
+ *
+ * NOTE: This message should not be sent if you want to flush the buffer due to
+ * a new decipherability context (e.g. pushed data just became un-decipherable).
+ * For that special situation, a specific message,
+ * `INeedsDecipherabilityFlushCoreMessage` should be relied on instead.
+ *
+ * This is most often done via a very small seek.
+ */
+export interface INeedsBufferFlushCoreMessage {
+  /** Identify an `INeedsBufferFlushCoreMessage`. */
+  type: CoreMessageType.NeedsBufferFlush;
+  /** The `contentId` linked to the content that has asked for this flush. */
+  contentId: string;
+  value:
+    | {
+        /**
+         * The position, relative to the current one in seconds, we should
+         * restart playback from after the flush.
+         * If set to `0`, we should keep the exact same position. If set to `1`,
+         * we should restart playback one second later etc.
+         */
+        relativeResumingPosition: number;
+        /**
+         * If `true`, `relativeResumingPosition` is just a default value
+         * proposed as an hint by default by the RxPlayer and can be ignored if
+         * not practical in the current context.
+         *
+         * If `false`, the `relativeResumingPosition` has been explicitly set
+         * and should thus be respected.
+         */
+        relativePosHasBeenDefaulted: boolean;
+      }
+    | undefined;
+}
+
+/**
+ * Message sent by the Core when an Error that did not interrupt playback just
+ * arised.
+ *
+ * This can for example be minor request errors.
+ */
+export interface IWarningCoreMessage {
+  /** Identify an `IWarningCoreMessage`. */
+  type: CoreMessageType.Warning;
+  /** Identifier of the content linked to that warning. */
+  contentId: string | undefined;
+  /** Serialized format for that error. */
+  value: ISentError;
+}
+
+/**
+ * Message sent by the Core when an Error that interrupted playback of the
+ * current content just happened.
+ *
+ * It should be assumed that the content is not playing anymore once this
+ * message has been sent.
+ */
+export interface IErrorCoreMessage {
+  /** Identify an `IErrorCoreMessage`. */
+  type: CoreMessageType.Error;
+  /** Identifier of the content linked to that error. */
+  contentId: string | undefined;
+  /** Serialized format for that error. */
+  value: ISentError;
+}
+
+/**
+ * Message sent by the Core when it created the `MediaSource` itself and ask it
+ * to be attached by the main thread to the media element.
+ *
+ * This is one of the two ways a `MediaSource` can be created by the RxPlayer,
+ * the other one being through an `ICreateMediaSourceCoreMessage` (in which case
+ * the `MediaSource` would be created by `Main Thread`, not `Core`). Choosing
+ * one or the other depends on browser capabilities and settings.
+ *
+ * When an `IAttachMediaSourceCoreMessage` is sent, it is understood by the main
+ * thread that the role of managing the `MediaSource` itself is handled by the
+ * `Core` for the current content, and as such `Core` won't send any
+ * `IAddSourceBufferCoreMessage`, `IAppendBufferCoreMessage`,
+ * `IRemoveBufferCoreMessage`, `IAbortBufferCoreMessage`,
+ * `IUpdateMediaSourceDurationCoreMessage` and other such events that imply a
+ * side effect on `MediaSource`-linked API. All those actions should instead be
+ * taken by `Core` directly in this scenario.
+ */
+export interface IAttachMediaSourceCoreMessage {
+  /** Identify an `IAttachMediaSourceCoreMessage`. */
+  type: CoreMessageType.AttachMediaSource;
+  /** The `contentId` linked to the current content. */
+  contentId: string | undefined;
+  /**
+   * A unique identifier linked to that `MediaSource`.
+   * Will be used to be able to ensure the right `MediaSource` is referred to
+   * in future messages.
+   */
+  mediaSourceId: string;
+  /** Information on the `MediaSource` to attach to the media element. */
+  value: IAttachMediaSourceCoreMessagePayload;
+}
+
+/** Payload sent alongside an `IAttachMediaSourceCoreMessage` */
+export type IAttachMediaSourceCoreMessagePayload =
+  | {
+      /**
+       * Identifies a `MediaSource` of the type "handle", in which case the
+       * `MediaSource` can be linked to the media element as an object directly.
+       */
+      type: "handle";
+      /** The corresponding object that should be linked to the media element. */
+      value: MediaProvider;
+    }
+  | {
+      /**
+       * Identifies a `MediaSource` of the type "url", in which case the `value`
+       * will communicate an "object url" that has to be linked to the media
+       * element.
+       */
+      type: "url";
+      /** The object URL that refers to the created `MediaSource`. */
+      value: string;
+    };
+
+export interface ICreateMediaSourceCoreMessage {
+  type: CoreMessageType.CreateMediaSource;
+  mediaSourceId: string;
+  contentId: string;
+}
+
+export interface IAddSourceBufferCoreMessage {
+  type: CoreMessageType.AddSourceBuffer;
+  mediaSourceId: string;
+  value: {
+    sourceBufferType: SourceBufferType;
+    codec: string;
+  };
+}
+
+export interface IAppendBufferCoreMessage {
+  type: CoreMessageType.SourceBufferAppend;
+  mediaSourceId: string;
+  sourceBufferType: SourceBufferType;
+  operationId: string;
+  value: {
+    data: BufferSource;
+    params: ISourceBufferInterfaceAppendBufferParameters;
+  };
+}
+
+export interface IRemoveBufferCoreMessage {
+  type: CoreMessageType.SourceBufferRemove;
+  mediaSourceId: string;
+  sourceBufferType: SourceBufferType;
+  operationId: string;
+  value: {
+    /** Start time we should remove data from, in seconds. */
+    start: number;
+    /** End time we should remove data at, in seconds. */
+    end: number;
+  };
+}
+
+export interface IAbortBufferCoreMessage {
+  type: CoreMessageType.AbortSourceBuffer;
+  mediaSourceId: string;
+  sourceBufferType: SourceBufferType;
+  value: null;
+}
+
+export interface IUpdateMediaSourceDurationCoreMessage {
+  type: CoreMessageType.UpdateMediaSourceDuration;
+  mediaSourceId: string;
+  value: {
+    duration: number;
+    isRealEndKnown: boolean;
+  };
+}
+
+export interface IInterruptMediaSourceDurationCoreMessage {
+  type: CoreMessageType.InterruptMediaSourceDurationUpdate;
+  mediaSourceId: string;
+  value: null;
+}
+
+export interface IEndOfStreamCoreMessage {
+  type: CoreMessageType.EndOfStream;
+  mediaSourceId: string;
+  value: null;
+}
+
+export interface IStopEndOfStreamCoreMessage {
+  type: CoreMessageType.InterruptEndOfStream;
+  mediaSourceId: string;
+  value: null;
+}
+
+export interface IDisposeMediaSourceCoreMessage {
+  type: CoreMessageType.DisposeMediaSource;
+  mediaSourceId: string;
+  value: null;
+}
+
+export interface IActivePeriodChangedCoreMessage {
+  type: CoreMessageType.ActivePeriodChanged;
+  contentId: string;
+  value: {
+    periodId: string;
+  };
+}
+
+export interface IAdaptationChangeCoreMessage {
+  type: CoreMessageType.AdaptationChanged;
+  contentId: string;
+  value: {
+    adaptationId: string | null;
+    periodId: string;
+    type: ITrackType;
+  };
+}
+
+export interface IRepresentationChangeCoreMessage {
+  type: CoreMessageType.RepresentationChanged;
+  contentId: string;
+  value: {
+    adaptationId: string;
+    representationId: string | null;
+    periodId: string;
+    type: ITrackType;
+  };
+}
+
+/** Message sent by the Core when the Manifest is first loaded. */
+export interface IManifestReadyCoreMessage {
+  /** Identify this particular message. */
+  type: CoreMessageType.ManifestReady;
+  /** The `contentId` linked to this Manifest. */
+  contentId: string;
+  value: {
+    /**
+     * The actual `Manifest` loaded.
+     *
+     * When possible, this should be a `Manifest` instance.
+     *
+     * Only if this is not possible (e.g. because the `Manifest` cannot be
+     * communicated as is between both core and main_thread) might you convert
+     * it to another object also respecting the `IManifestMetadata` interface.
+     *
+     * However doing this might lead to some loss of performance and minor
+     * features.
+     */
+    manifest: IManifestMetadata;
+  };
+}
+
+/** Message sent by the Core everytime the Manifest is updated. */
+export interface IManifestUpdateCoreMessage {
+  /** Identify this particular message. */
+  type: CoreMessageType.ManifestUpdate;
+  /** The `contentId` linked to this Manifest. */
+  contentId: string | undefined;
+  value: {
+    /**
+     * The new manifest once updated.
+     *
+     * When possible, this should be a `Manifest` instance to improve
+     * performance and allow some advanced features.
+     *
+     * Only if this is not possible (e.g. because the `Manifest` cannot be
+     * communicated as is between both core and main_thread) might you convert
+     * it to another object also respecting the `IManifestMetadata` interface.
+     * In that last case, you're also authorized to reset the `periods` property
+     * of that `IManifestMetadata` to an empty array to save up message-passing
+     * performance.
+     */
+    manifest: IManifestMetadata;
+    /**
+     * Object describing what has changed in this update.
+     */
+    updates: IPeriodsUpdateResult;
+  };
+}
+
+export interface IEncryptionDataEncounteredCoreMessage {
+  type: CoreMessageType.EncryptionDataEncountered;
+  contentId: string | undefined;
+  value: IContentProtection;
+}
+
+export interface IUpdatePlaybackRateCoreMessage {
+  type: CoreMessageType.UpdatePlaybackRate;
+  contentId: string | undefined;
+  value: number;
+}
+
+export interface IReloadingMediaSourceCoreMessage {
+  type: CoreMessageType.ReloadingMediaSource;
+  /** Identify the MediaSource concerned by this message. */
+  mediaSourceId: string;
+  value: {
+    timeOffset: number;
+    minimumPosition?: number | undefined;
+    maximumPosition?: number | undefined;
+  };
+}
+
+/**
+ * Message sent by the Core when it want the low-level buffers to be "flushed"
+ * with the important caveat that this is linked to a change in decipherability
+ * matters (e.g. content just became un-decipherable).
+ *
+ * A "flush" is an operation which tries to "refresh" the content of low-level
+ * media buffers, either to ensure an update to it has been taken into account
+ * or to fix a problematic situation.
+ *
+ * Flush asked in this scenario may lead to aggressive strategies such as
+ * switching the `MediaSource` - as the less disruptive scenarios (seeking,
+ * play/pause etc.) are often not enough when decipherability is involved.
+ *
+ * In any case, the `Core` shouldn't care what strategy is chosen to flush. The
+ * usual main thread's messages will be enough to handle any scenario without any
+ * special effort from Core.
+ */
+export interface INeedsDecipherabilityFlushCoreMessage {
+  /** Identify an `INeedsDecipherabilityFlushCoreMessage`. */
+  type: CoreMessageType.NeedsDecipherabilityFlush;
+  /** The `contentId` linked to the content that has asked for this flush. */
+  contentId: string;
+  value: null;
+}
+
+export interface ILockedStreamCoreMessage {
+  type: CoreMessageType.LockedStream;
+  contentId: string;
+  value: {
+    /** Period concerned. */
+    periodId: string;
+    /** Buffer type concerned. */
+    bufferType: ITrackType;
+  };
+}
+
+export interface IBitrateEstimateChangeCoreMessage {
+  type: CoreMessageType.BitrateEstimateChange;
+  contentId: string;
+  value: {
+    bitrate: number | undefined;
+    bufferType: ITrackType;
+  };
+}
+
+export interface IInbandEventCoreMessage {
+  type: CoreMessageType.InbandEvent;
+  contentId: string;
+  value: IInbandEvent[];
+}
+
+export interface IPeriodStreamReadyCoreMessage {
+  type: CoreMessageType.PeriodStreamReady;
+  contentId: string;
+  value: {
+    /** Period concerned. */
+    periodId: string;
+    /** Buffer type concerned. */
+    bufferType: ITrackType;
+  };
+}
+
+export interface IPeriodStreamClearedCoreMessage {
+  type: CoreMessageType.PeriodStreamCleared;
+  contentId: string;
+  value: {
+    /** `id` of the Period concerned. */
+    periodId: string;
+    /** Buffer type concerned. */
+    bufferType: ITrackType;
+  };
+}
+
+export interface IPushTextDataCoreMessage {
+  type: CoreMessageType.PushTextData;
+  contentId: string;
+  value: ITextDisplayerData;
+}
+
+export interface IRemoveTextDataCoreMessage {
+  type: CoreMessageType.RemoveTextData;
+  contentId: string;
+  value: {
+    start: number;
+    end: number;
+  };
+}
+
+export interface IStopTextDisplayerCoreMessage {
+  type: CoreMessageType.StopTextDisplayer;
+  contentId: string;
+  value: null;
+}
+
+export interface IResetTextDisplayerCoreMessage {
+  type: CoreMessageType.ResetTextDisplayer;
+  contentId: string;
+  value: null;
+}
+
+type ISentLogValueBase = boolean | string | number | null | undefined;
+
+export type ISentLogValue =
+  | ISentLogValueBase
+  | ISentError
+  | Partial<Record<string, ISentLogValueBase>>;
+
+export interface ILogMessageCoreMessage {
+  type: CoreMessageType.LogMessage;
+  value: {
+    namespace: ILogNamespace;
+    logLevel: ILoggerLevel;
+    logs: ISentLogValue[];
+  };
+}
+
+export interface IDiscontinuityUpdateCoreMessage {
+  type: CoreMessageType.DiscontinuityUpdate;
+  contentId: string;
+  value: IDiscontinuityUpdateCoreMessagePayload;
+}
+
+export interface IDiscontinuityUpdateCoreMessagePayload {
+  periodId: string;
+  bufferType: ITrackType;
+  discontinuity: IDiscontinuityTimeInfo | null;
+  position: number;
+}
+
+/** Information on a found discontinuity. */
+export interface IDiscontinuityTimeInfo {
+  /**
+   * Start time of the discontinuity.
+   * `undefined` for when the start is unknown but the discontinuity was
+   * currently encountered at the position we were in when this event was
+   * created.
+   */
+  start: number | undefined;
+  /**
+   * End time of the discontinuity, in seconds.
+   * If `null`, no further segment can be loaded for the corresponding Period.
+   */
+  end: number | null;
+}
+
+export interface ISegmentSinkStoreUpdateMessage {
+  type: CoreMessageType.SegmentSinkStoreUpdate;
+  contentId: string;
+  value: {
+    segmentSinkMetrics: ISegmentSinkMetrics;
+    requestId: number;
+  };
+}
+
+export interface IThumbnailDataResponseCoreMessage {
+  type: CoreMessageType.ThumbnailDataResponse;
+  contentId: string;
+  value:
+    | {
+        status: "error";
+        requestId: number;
+        error: ISentError;
+      }
+    | {
+        status: "success";
+        requestId: number;
+        data: IThumbnailResponse;
+      };
+}
+
+export const enum CoreMessageType {
+  AbortSourceBuffer = "abort-source-buffer",
+  ActivePeriodChanged = "active-period-changed",
+  AdaptationChanged = "adaptation-changed",
+  AddSourceBuffer = "add-source-buffer",
+  AttachMediaSource = "attach-media-source",
+  BitrateEstimateChange = "bitrate-estimate-change",
+  CreateMediaSource = "create-media-source",
+  DiscontinuityUpdate = "discontinuity-update",
+  DisposeMediaSource = "dispose-media-source",
+  EncryptionDataEncountered = "encryption-data-encountered",
+  EndOfStream = "end-of-stream",
+  Error = "error",
+  InbandEvent = "inband-event",
+  InitError = "init-error",
+  InitSuccess = "init-success",
+  InterruptEndOfStream = "stop-end-of-stream",
+  InterruptMediaSourceDurationUpdate = "stop-media-source-duration",
+  LockedStream = "locked-stream",
+  LogMessage = "log",
+  ManifestReady = "manifest-ready",
+  ManifestUpdate = "manifest-update",
+  NeedsBufferFlush = "needs-buffer-flush",
+  NeedsDecipherabilityFlush = "needs-decipherability-flush",
+  PeriodStreamCleared = "period-stream-cleared",
+  PeriodStreamReady = "period-stream-ready",
+  PushTextData = "push-text-data",
+  ReloadingMediaSource = "reloading-media-source",
+  RemoveTextData = "remove-text-data",
+  RepresentationChanged = "representation-changed",
+  ResetTextDisplayer = "reset-text-displayer",
+  SourceBufferAppend = "source-buffer-append",
+  SourceBufferRemove = "source-buffer-remove",
+  StopTextDisplayer = "stop-text-displayer",
+  UpdateMediaSourceDuration = "update-media-source-duration",
+  UpdatePlaybackRate = "update-playback-rate",
+  Warning = "warning",
+  SegmentSinkStoreUpdate = "segment-sink-store-update",
+  ThumbnailDataResponse = "thumbnail-response",
+}
+
+export type ICoreMessage =
+  | IAbortBufferCoreMessage
+  | IActivePeriodChangedCoreMessage
+  | IAdaptationChangeCoreMessage
+  | IAddSourceBufferCoreMessage
+  | IPushTextDataCoreMessage
+  | IAppendBufferCoreMessage
+  | IAttachMediaSourceCoreMessage
+  | IBitrateEstimateChangeCoreMessage
+  | ICreateMediaSourceCoreMessage
+  | IDiscontinuityUpdateCoreMessage
+  | IDisposeMediaSourceCoreMessage
+  | IEncryptionDataEncounteredCoreMessage
+  | IEndOfStreamCoreMessage
+  | IErrorCoreMessage
+  | IInbandEventCoreMessage
+  | IInitSuccessCoreMessage
+  | IInitErrorCoreMessage
+  | IInterruptMediaSourceDurationCoreMessage
+  | ILockedStreamCoreMessage
+  | ILogMessageCoreMessage
+  | IManifestReadyCoreMessage
+  | IManifestUpdateCoreMessage
+  | INeedsBufferFlushCoreMessage
+  | INeedsDecipherabilityFlushCoreMessage
+  | IPeriodStreamClearedCoreMessage
+  | IPeriodStreamReadyCoreMessage
+  | IReloadingMediaSourceCoreMessage
+  | IRemoveBufferCoreMessage
+  | IRemoveTextDataCoreMessage
+  | IRepresentationChangeCoreMessage
+  | IResetTextDisplayerCoreMessage
+  | IStopEndOfStreamCoreMessage
+  | IStopTextDisplayerCoreMessage
+  | IUpdateMediaSourceDurationCoreMessage
+  | IUpdatePlaybackRateCoreMessage
+  | IWarningCoreMessage
+  | ISegmentSinkStoreUpdateMessage
+  | IThumbnailDataResponseCoreMessage;

package/src/experimental/features/__tests__/local.test.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect } from "vitest";
+import initializeCoreEntry from "../../../core/entry";
 import type { IFeaturesObject } from "../../../features/types";
+import { MonoThreadCoreInterface } from "../../../main_thread/core_interface/monothread";
 import MediaSourceContentInitializer from "../../../main_thread/init/media_source_content_initializer";
 import local from "../../../transports/local";
 import addLocalManifestFeature from "../local";
@@ -10,9 +12,16 @@ describe("Features list - LOCAL_MANIFEST", () => {
     addLocalManifestFeature(featureObject);
     expect(featureObject).toEqual({
       transports: { local },
-      mainThreadMediaSourceInit: MediaSourceContentInitializer,
+      monothread: {
+        init: MediaSourceContentInitializer,
+        coreInterface: MonoThreadCoreInterface,
+        initializeCoreEntry,
+      },
     });
     expect(featureObject.transports.local).toBe(local);
-    expect(featureObject.mainThreadMediaSourceInit).toBe(MediaSourceContentInitializer);
+    expect(featureObject.monothread).not.toBe(null);
+    expect(featureObject.monothread?.init).toBe(MediaSourceContentInitializer);
+    expect(featureObject.monothread?.coreInterface).toBe(MonoThreadCoreInterface);
+    expect(featureObject.monothread?.initializeCoreEntry).toBe(initializeCoreEntry);
   });
 });