rx-player 4.1.0-dev.2024040900 → 4.1.0-dev.2024070800

package/src/core/stream/adaptation/types.ts

@@ -0,0 +1,210 @@
+import type { IManifest, IAdaptation, IPeriod, IRepresentation } from "../../../manifest";
+import type { IReadOnlyPlaybackObserver } from "../../../playback_observer";
+import type {
+  IAudioTrackSwitchingMode,
+  IVideoTrackSwitchingMode,
+} from "../../../public_types";
+import type { IReadOnlySharedReference } from "../../../utils/reference";
+import type { IRepresentationEstimator } from "../../adaptive";
+import type { SegmentFetcherCreator } from "../../fetchers";
+import type { IBufferType, SegmentSink } from "../../segment_sinks";
+import type {
+  IRepresentationsChoice,
+  IRepresentationStreamCallbacks,
+  IRepresentationStreamPlaybackObservation,
+} from "../representation";
+
+/** Callbacks called by the `AdaptationStream` on various events. */
+export interface IAdaptationStreamCallbacks
+  extends Omit<IRepresentationStreamCallbacks, "terminating" | "addedSegment"> {
+  /** Called as new bitrate estimates are done. */
+  bitrateEstimateChange(payload: IBitrateEstimateChangePayload): void;
+  /**
+   * Called when a new `RepresentationStream` is created to load segments from a
+   * `Representation`.
+   */
+  representationChange(payload: IRepresentationChangePayload): void;
+  /**
+   * Callback called when a stream cannot go forward loading segments because it
+   * needs the `MediaSource` to be reloaded first.
+   *
+   * The MediaSource will only be reloaded once the communicated Period is the
+   * current one.
+   */
+  waitingMediaSourceReload(payload: IWaitingMediaSourceReloadPayload): void;
+  /**
+   * Some situations might require the browser's buffers to be refreshed.
+   * This callback is called when such situation arised.
+   *
+   * Generally flushing/refreshing low-level buffers can be performed simply by
+   * performing a very small seek.
+   */
+  needsBufferFlush(payload?: INeedsBufferFlushPayload): void;
+}
+
+/** Payload for the `bitrateEstimateChange` callback. */
+export interface IBitrateEstimateChangePayload {
+  /** The type of buffer for which the estimation is done. */
+  type: IBufferType;
+  /**
+   * The bitrate estimate, in bits per seconds. `undefined` when no bitrate
+   * estimate is currently available.
+   */
+  bitrate: number | undefined;
+}
+
+/** Payload for the `representationChange` callback. */
+export interface IRepresentationChangePayload {
+  /** The type of buffer linked to that `RepresentationStream`. */
+  type: IBufferType;
+  /** The `Period` linked to the `RepresentationStream` we're creating. */
+  period: IPeriod;
+  /** The `Adaptation` linked to the `RepresentationStream` we're creating. */
+  adaptation: IAdaptation;
+  /**
+   * The `Representation` linked to the `RepresentationStream` we're creating.
+   * `null` when we're choosing no Representation at all.
+   */
+  representation: IRepresentation | null;
+}
+
+/** Payload for the `waitingMediaSourceReload` callback. */
+export interface IWaitingMediaSourceReloadPayload {
+  /**
+   * Period asking for the reload.
+   *
+   * The MediaSource will only be reloaded if that Period becomes the current
+   * one.
+   */
+  period: IPeriod;
+  /** Buffer type concerned. */
+  bufferType: IBufferType;
+  /**
+   * Relative position, compared to the current position, at which we should
+   * restart playback after reloading. For example `-2` will reload 2 seconds
+   * before the current position.
+   */
+  timeOffset: number;
+  /**
+   * If `true`, we will control that the position we reload at, after applying
+   * `timeOffset`, is still part of the Period `period`.
+   *
+   * If it isn't we will re-calculate that reloaded position to be:
+   *   - either the Period's start if the calculated position is before the
+   *     Period's start.
+   *   - either the Period'end start if the calculated position is after the
+   *     Period's end.
+   */
+  stayInPeriod: boolean;
+}
+
+export interface INeedsBufferFlushPayload {
+  /** Relative resuming position after a track change */
+  relativeResumingPosition: number;
+  /** `false` if the user manually set relativeResumingPosition value.
+   *  `true` if the API assigned a default value to relativeResumingPosition.
+   *  This setting allows to respect exactly the specified relativeResumingPosition
+   *  that has been set by the user, while still providing the flexibility to modify it
+   *  for slight adjustments when needed if it was defaulted by the API."
+   */
+  relativePosHasBeenDefaulted: boolean;
+}
+
+/** Regular playback information needed by the AdaptationStream. */
+export interface IAdaptationStreamPlaybackObservation
+  extends IRepresentationStreamPlaybackObservation {
+  /**
+   * For the current SegmentSink, difference in seconds between the next position
+   * where no segment data is available and the current position.
+   */
+  bufferGap: number;
+  /** `duration` property of the HTMLMediaElement on which the content plays. */
+  duration: number;
+  /** Theoretical maximum position on the content that can currently be played. */
+  maximumPosition: number;
+}
+
+/** Arguments given when creating a new `AdaptationStream`. */
+export interface IAdaptationStreamArguments {
+  /** Regularly emit playback conditions. */
+  playbackObserver: IReadOnlyPlaybackObserver<IAdaptationStreamPlaybackObservation>;
+  /** Content you want to create this Stream for. */
+  content: {
+    manifest: IManifest;
+    period: IPeriod;
+    adaptation: IAdaptation;
+    representations: IReadOnlySharedReference<IRepresentationsChoice>;
+  };
+  options: IAdaptationStreamOptions;
+  /** Estimate the right Representation to play. */
+  representationEstimator: IRepresentationEstimator;
+  /** SourceBuffer wrapper - needed to push media segments. */
+  segmentSink: SegmentSink;
+  /** Module used to fetch the wanted media segments. */
+  segmentFetcherCreator: SegmentFetcherCreator;
+  /**
+   * "Buffer goal" wanted, or the ideal amount of time ahead of the current
+   * position in the current SegmentSink. When this amount has been reached
+   * this AdaptationStream won't try to download new segments.
+   */
+  wantedBufferAhead: IReadOnlySharedReference<number>;
+  /**
+   *  The buffer size limit in memory that we can reach for the video buffer.
+   *
+   *  Once reached, no segments will be loaded until it goes below that size
+   *  again
+   */
+  maxVideoBufferSize: IReadOnlySharedReference<number>;
+}
+
+/**
+ * Various specific stream "options" which tweak the behavior of the
+ * AdaptationStream.
+ */
+export interface IAdaptationStreamOptions {
+  /**
+   * Hex-encoded DRM "system ID" as found in:
+   * https://dashif.org/identifiers/content_protection/
+   *
+   * Allows to identify which DRM system is currently used, to allow potential
+   * optimizations.
+   *
+   * Set to `undefined` in two cases:
+   *   - no DRM system is used (e.g. the content is unencrypted).
+   *   - We don't know which DRM system is currently used.
+   */
+  drmSystemId: string | undefined;
+  /**
+   * If `true`, the AdaptationStream might replace segments of a lower-quality
+   * (with a lower bitrate) with segments of a higher quality (with a higher
+   * bitrate). This allows to have a fast transition when network conditions
+   * improve.
+   * If `false`, this strategy will be disabled: segments of a lower-quality
+   * will not be replaced.
+   *
+   * Some targeted devices support poorly segment replacement in a
+   * SourceBuffer.
+   * As such, this option can be used to disable that unnecessary behavior on
+   * those devices.
+   */
+  enableFastSwitching: boolean;
+}
+
+/** Object indicating a choice of Adaptation made by the user. */
+export interface IAdaptationChoice {
+  /** The Adaptation choosen. */
+  adaptationId: string;
+
+  /** "Switching mode" in which the track switch should happen. */
+  switchingMode: ITrackSwitchingMode;
+
+  /** Relative resuming position after a track change */
+  relativeResumingPosition: number | undefined;
+  /**
+   * Shared reference allowing to indicate which Representations from
+   * that Adaptation are allowed.
+   */
+  representations: IReadOnlySharedReference<IRepresentationsChoice>;
+}
+
+export type ITrackSwitchingMode = IAudioTrackSwitchingMode | IVideoTrackSwitchingMode;

package/src/core/stream/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright 2015 CANAL+ Group
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type {
+  INeedsMediaSourceReloadPayload,
+  IStreamOrchestratorOptions,
+  IStreamOrchestratorPlaybackObservation,
+  IStreamOrchestratorCallbacks,
+} from "./orchestrator";
+import StreamOrchestrator from "./orchestrator";
+import type { IPausedPlaybackObservation } from "./period";
+export type {
+  IRepresentationsChoice,
+  IInbandEvent,
+  IStreamStatusPayload,
+} from "./representation";
+export type {
+  IAdaptationChoice,
+  INeedsBufferFlushPayload,
+  ITrackSwitchingMode,
+  IWaitingMediaSourceReloadPayload,
+} from "./adaptation";
+
+export default StreamOrchestrator;
+export type {
+  IPausedPlaybackObservation,
+  INeedsMediaSourceReloadPayload,
+  IStreamOrchestratorPlaybackObservation,
+  IStreamOrchestratorOptions,
+  IStreamOrchestratorCallbacks,
+};

package/src/core/stream/orchestrator/README.md

@@ -0,0 +1,337 @@
+# StreamOchestrator
+
+| Consideration           | Status                            |
+| ----------------------- | --------------------------------- |
+| Preferred import style  | Directory-only _[1]_              |
+| Multithread environment | Should be runnable in a WebWorker |
+
+_[1]_ Only the `orchestrator` directory itself should be imported and relied on by the
+rest of the code, not its inner files (thus `./index.ts` should export everything that may
+be imported by outside code).
+
+## Overview
+
+To be able to play a content, the player has to be able to download chunks of media data -
+called segments - and has to push them to media buffers, called `SegmentSinks` in the
+RxPlayer code.
+
+In the RxPlayer, the _StreamOrchestrator_ is the entry point for performing all those
+tasks.
+
+Basically, the _StreamOrchestrator_:
+
+- dynamically creates various `SegmentSinks` depending on the needs of the given content
+
+- orchestrates segment downloading and "pushing" to allow the content to play in the best
+  conditions possible.
+
+## Multiple types handling
+
+More often than not, content are divised into multiple "types": "audio", "video" and
+"text" segments, for example. They are often completely distinct in a Manifest and as
+such, have to be downloaded and decoded separately.
+
+Each type has its own media buffer. For "audio"/"video" contents, we use regular
+browser-defined _MSE_ SourceBuffers. For any other types, such as "text", those buffers
+are entirely defined in the code of the RxPlayer.
+
+We then create a different Stream for each type. Each will progressively download and push
+content of their respective type to their respective media buffer:
+
+```
+- AUDIO STREAM -
+|======================    |
+
+- VIDEO STREAM -
+|==================        |
+
+- TEXT STREAM -
+|========================  |
+```
+
+_(the `|` sign delimits the temporal start and end of the buffer linked to a given Stream,
+the `=` sign represent a pushed segment in the corresponding buffer)_
+
+## A special case: SourceBuffers
+
+Media buffers created for the audio and/or video types rely on a _native_ (implemented by
+the browser) `SourceBuffer` Object implementation.
+
+Media buffers relying on native SourceBuffers have several differences with the other
+"custom" (entirely defined in the RxPlayer) types of media buffers:
+
+- They are managed by the browser where custom ones are implemented in JS. As such, they
+  must obey to various browser rules, among which:
+
+  1. They cannot be lazily created as the content plays. We have to initialize all of them
+     beforehand.
+
+  2. They have to be linked to a specific codec.
+
+  3. The `SourceBuffer` has to be linked to the MediaSource, and they have to the
+     MediaSource after the media HTMLElement has been linked to the MediaSource
+
+- They are in a way more "important" than custom ones. If a problem happens with a
+  SourceBuffer, we interrupt playback. For a custom media buffer, we can just deactivate
+  it for the rest of the content.
+
+  For example, a problem with subtitles would just disable those with a warning. For a
+  video problem however, we fail immediately.
+
+- They affect buffering when custom media buffers do not (no text segment for a part of
+  the content means we will just not have subtitles, no audio segment means we will
+  completely stop, to await them)
+
+- They affect various API linked to the media element in the DOM. Such as
+  `HTMLMediaElement.prototype.buffered`. Custom media buffers do not.
+
+Due to these differences, media buffers relying on SourceBuffers are often managed in a
+less permissive way than custom ones:
+
+- They will be created at the very start of the content
+
+- An error coming from one of them will lead us to completely stop the content on a fatal
+  error
+
+## PeriodStreams
+
+The _DASH_ streaming technology has a concept called _Period_. Simply put, it allows to
+set various types of content successively in the same manifest.
+
+For example, let's take a manifest describing a live content with chronologically:
+
+1.  an english TV Show
+2.  an old italian film with subtitles
+3.  an American film with closed captions.
+
+Example:
+
+```
+08h05              09h00                       10h30                now
+  |==================|===========================|===================|
+        TV Show               Italian Film            American film
+```
+
+Those contents are drastically different (they have different languages, the american film
+might have more available bitrates than the old italian one).
+
+Moreover, even a library user might want to be able to know when the italian film is
+finished, to report about it immediately in a graphical interface.
+
+As such, they have to be considered separately - in a different Period:
+
+```
+        Period 1                Period 2                Period 3
+08h05              09h00                       10h30                now
+  |==================|===========================|===================|
+        TV Show               Italian Film            American film
+```
+
+In the RxPlayer, we create one _PeriodStream_ per Period **and** per type.
+
+_PeriodStreams_ are automatically created/destroyed during playback. The job of a single
+_PeriodStream_ is to process and download optimally the content linked to a single
+_Period_ and to a single type:
+
+```
+- VIDEO BUFFER -
+
+     PERIOD STREAM
+08h05              09h00
+  |=========         |
+        TV Show
+
+
+- AUDIO BUFFER -
+
+     PERIOD STREAM
+08h05              09h00
+  |=============     |
+        TV Show
+
+
+- TEXT BUFFER -
+
+     PERIOD STREAM
+08h05              09h00
+  |======            |
+        TV Show
+```
+
+To allow smooth transitions between them, we also might want to preload content defined by
+a subsequent _Period_ once we lean towards the end of the content described by the
+previous one. Thus, multiple _PeriodStreams_ might be active at the same time:
+
+```
++----------------------------   AUDIO   ----------------------------------+
+|                                                                         |
+|      PERIOD STREAM 1        PERIOD STREAM 2         PERIOD STREAM 3     |
+| 08h05              09h00                       10h30                now |
+|   |=============     |=================          |================   |  |
+|         TV Show               Italian Film            American film     |
++-------------------------------------------------------------------------+
+
++------------------------------   VIDEO   --------------------------------+
+|                                                                         |
+|      PERIOD STREAM 1        PERIOD STREAM 2         PERIOD STREAM 3     |
+| 08h05              09h00                       10h30                now |
+|   |=====             |===                        |===                |  |
+|         TV Show               Italian Film            American film     |
++-------------------------------------------------------------------------+
+
++------------------------------   TEXT   ---------------------------------+
+|                                                                         |
+|      PERIOD STREAM 1        PERIOD STREAM 2         PERIOD STREAM 3     |
+| 08h05              09h00                       10h30                now |
+|     (NO SUBTITLES)   |=========================  |=================  |  |
+|         TV Show               Italian Film            American film     |
++-------------------------------------------------------------------------+
+```
+
+### Multi-Period management
+
+The creation/destruction of _PeriodStreams_ is actually done in a very precize and optimal
+way, which gives a higher priority to immediate content.
+
+To better grasp how it works, let's imagine a regular use-case, with two periods for a
+single type of buffer:
+
+---
+
+Let's say that the _PeriodStream_ for the first _Period_ (named P1) is currently actively
+downloading segments (the "^" sign is the current position):
+
+```
+   P1
+|====  |
+   ^
+```
+
+Once P1 is full (it has no segment left to download):
+
+```
+   P1
+|======|
+   ^
+```
+
+We will be able to create a new _PeriodStream_, P2, for the second _Period_:
+
+```
+   P1     P2
+|======|      |
+   ^
+```
+
+Which will then also download segments:
+
+```
+   P1     P2
+|======|==    |
+   ^
+```
+
+If P1 needs segments again however (e.g. when the bitrate or the language is changed):
+
+```
+   P1     P2
+|===   |==    |
+   ^
+```
+
+Then we will destroy P2, to keep it from downloading segments:
+
+```
+   P1
+|===   |
+   ^
+```
+
+---
+
+Once P1, goes full again, we re-create P2:
+
+```
+   P1     P2
+|======|==    |
+   ^
+```
+
+_Note that we still have the segment pushed to P2 available in the corresponding media
+buffer_
+
+When the current position go ahead of a _PeriodStream_ (here ahead of P1):
+
+```
+   P1     P2
+|======|===   |
+        ^
+```
+
+This _PeriodStream_ is destroyed to free up ressources:
+
+```
+          P2
+       |===   |
+        ^
+```
+
+---
+
+When the current position goes behind the first currently defined _PeriodStream_:
+
+```
+          P2
+       |===   |
+    ^
+```
+
+Then we destroy all previous _PeriodStreams_ and [re-]create the one needed:
+
+```
+   P1
+|======|
+    ^
+```
+
+In this example, P1 is full (as we already downloaded its segments) so we also can
+re-create P2, which will also keep its already-pushed segments:
+
+```
+   P1     P2
+|======|===   |
+    ^
+```
+
+---
+
+For multiple types of buffers (example: _audio_ and _video_) the same logic is repeated
+(and separated) as many times. An _audio_ _PeriodStream_ will not influence a _video_ one:
+
+```
+---------------------------   AUDIO   --------------------------------
+     Period 1         Period 2
+|================|=============   |
+     ^
+
+---------------------------   VIDEO   --------------------------------
+     Period 1
+|=======         |
+     ^
+
+----------------------------   TEXT   --------------------------------
+     Period 1         Period 2          Period 3
+|================| (NO SUBTITLES) |================   |
+     ^
+```
+
+At the end, we should only have _PeriodStream[s]_ for consecutive Period[s]:
+
+- The first chronological one is the one currently seen by the user.
+- The last chronological one is the only one downloading content.
+- In between, we only have full consecutive _PeriodStreams_.
+
+### Communication with the API
+
+Any "Stream" communicates to the API about creations and destructions of _PeriodStreams_
+respectively through `"periodStreamReady"` and `"periodStreamCleared"` callbacks.

package/src/core/stream/orchestrator/get_time_ranges_for_content.ts

@@ -0,0 +1,75 @@
+/**
+ * Copyright 2015 CANAL+ Group
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import log from "../../../log";
+import type {
+  IAdaptationMetadata,
+  IPeriodMetadata,
+  IRepresentationMetadata,
+} from "../../../manifest";
+import type { IRange } from "../../../utils/ranges";
+import type { SegmentSink } from "../../segment_sinks";
+
+/**
+ * Returns the buffered ranges which hold the given content.
+ * Returns the whole buffered ranges if some of it is unknown.
+ * @param {Object} segmentSink
+ * @param {Array.<Object>} contents
+ * @returns {Array.<Object>}
+ */
+export default function getTimeRangesForContent(
+  segmentSink: SegmentSink,
+  contents: Array<{
+    adaptation: IAdaptationMetadata;
+    period: IPeriodMetadata;
+    representation: IRepresentationMetadata;
+  }>,
+): IRange[] {
+  if (contents.length === 0) {
+    return [];
+  }
+  const accumulator: IRange[] = [];
+  const inventory = segmentSink.getLastKnownInventory();
+
+  for (let i = 0; i < inventory.length; i++) {
+    const chunk = inventory[i];
+    const hasContent = contents.some((content) => {
+      return (
+        chunk.infos.period.id === content.period.id &&
+        chunk.infos.adaptation.id === content.adaptation.id &&
+        chunk.infos.representation.id === content.representation.id
+      );
+    });
+    if (hasContent) {
+      const { bufferedStart, bufferedEnd } = chunk;
+      if (bufferedStart === undefined || bufferedEnd === undefined) {
+        log.warn("SO: No buffered start or end found from a segment.");
+        return [{ start: 0, end: Number.MAX_VALUE }];
+      }
+
+      const previousLastElement = accumulator[accumulator.length - 1];
+      if (
+        previousLastElement !== undefined &&
+        previousLastElement.end === bufferedStart
+      ) {
+        previousLastElement.end = bufferedEnd;
+      } else {
+        accumulator.push({ start: bufferedStart, end: bufferedEnd });
+      }
+    }
+  }
+  return accumulator;
+}

package/src/core/stream/orchestrator/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright 2015 CANAL+ Group
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type {
+  INeedsMediaSourceReloadPayload,
+  IStreamOrchestratorCallbacks,
+  IStreamOrchestratorOptions,
+  IStreamOrchestratorPlaybackObservation,
+} from "./stream_orchestrator";
+import StreamOrchestrator from "./stream_orchestrator";
+
+export default StreamOrchestrator;
+export type {
+  INeedsMediaSourceReloadPayload,
+  IStreamOrchestratorCallbacks,
+  IStreamOrchestratorOptions,
+  IStreamOrchestratorPlaybackObservation,
+};