rx-player 4.0.0-beta.0 → 4.0.0-beta.2

package/src/core/segment_buffers/implementations/audio_video/audio_video_segment_buffer.ts

@@ -21,10 +21,8 @@ import {
 import config from "../../../../config";
 import log from "../../../../log";
 import { getLoggableSegmentId } from "../../../../manifest";
-import areArraysOfNumbersEqual from "../../../../utils/are_arrays_of_numbers_equal";
 import assertUnreachable from "../../../../utils/assert_unreachable";
-import { toUint8Array } from "../../../../utils/byte_parsing";
-import hashBuffer from "../../../../utils/hash_buffer";
+import createCancellablePromise from "../../../../utils/create_cancellable_promise";
 import noop from "../../../../utils/noop";
 import objectAssign from "../../../../utils/object_assign";
 import TaskCanceller, {
@@ -138,20 +136,26 @@ export default class AudioVideoSegmentBuffer extends SegmentBuffer {
   private _pendingTask : IAVSBPendingTask | null;
 
   /**
-   * Keep track of the of the latest init segment pushed in the linked
-   * SourceBuffer.
+   * Keep track of the unique identifier of the  of the latest init segment
+   * pushed to the linked SourceBuffer.
    *
-   * This allows to be sure the right initialization segment is pushed before
-   * any chunk is.
+   * Such identifiers are first declared through the `declareInitSegment`
+   * method and the corresponding initialization segment is then pushed through
+   * the `pushChunk` method.
+   *
+   * Keeping track of this allows to be sure the right initialization segment is
+   * pushed before any chunk is.
    *
    * `null` if no initialization segment have been pushed to the
    * `AudioVideoSegmentBuffer` yet.
    */
-  private _lastInitSegment : { /** The init segment itself. */
-                               data : Uint8Array;
-                               /** Hash of the initSegment for fast comparison */
-                               hash : number; } |
-                             null;
+  private _lastInitSegmentUniqueId : string | null;
+
+  /**
+   * Link unique identifiers for initialization segments (as communicated by
+   * `declareInitSegment`) to the corresponding initialization data.
+   */
+  private _initSegmentsMap : Map<string, BufferSource>;
 
   /**
    * @constructor
@@ -173,8 +177,9 @@ export default class AudioVideoSegmentBuffer extends SegmentBuffer {
     this._sourceBuffer = sourceBuffer;
     this._queue = [];
     this._pendingTask = null;
-    this._lastInitSegment = null;
+    this._lastInitSegmentUniqueId = null;
     this.codec = codec;
+    this._initSegmentsMap = new Map();
 
     const onError = this._onPendingTaskError.bind(this);
     const reCheck = this._flush.bind(this);
@@ -197,6 +202,20 @@ export default class AudioVideoSegmentBuffer extends SegmentBuffer {
     });
   }
 
+  public declareInitSegment(
+    uniqueId : string,
+    initSegmentData : unknown
+  ) : void {
+    assertDataIsBufferSource(initSegmentData);
+    this._initSegmentsMap.set(uniqueId, initSegmentData);
+  }
+
+  public freeInitSegment(
+    uniqueId : string
+  ) : void {
+    this._initSegmentsMap.delete(uniqueId);
+  }
+
   /**
    * Push a chunk of the media segment given to the attached SourceBuffer, in a
    * FIFO queue.
@@ -228,12 +247,12 @@ export default class AudioVideoSegmentBuffer extends SegmentBuffer {
     infos : IPushChunkInfos<unknown>,
     cancellationSignal : CancellationSignal
   ) : Promise<void> {
-    assertPushedDataIsBufferSource(infos);
+    assertDataIsBufferSource(infos.data.chunk);
     log.debug("AVSB: receiving order to push data to the SourceBuffer",
               this.bufferType,
               getLoggableSegmentId(infos.inventoryInfos));
     return this._addToQueue({ type: SegmentBufferOperation.Push,
-                              value: infos },
+                              value: infos as IPushChunkInfos<BufferSource> },
                             cancellationSignal);
   }
 
@@ -349,7 +368,7 @@ export default class AudioVideoSegmentBuffer extends SegmentBuffer {
    * @param {Event} err
    */
   private _onPendingTaskError(err : unknown) : void {
-    this._lastInitSegment = null; // initialize init segment as a security
+    this._lastInitSegmentUniqueId = null; // initialize init segment as a security
     if (this._pendingTask !== null) {
       const error = err instanceof Error ?
                       err :
@@ -369,15 +388,15 @@ export default class AudioVideoSegmentBuffer extends SegmentBuffer {
     operation : ISBOperation<BufferSource>,
     cancellationSignal : CancellationSignal
   ) : Promise<void> {
-    return new Promise((resolve, reject) => {
-      if (cancellationSignal.cancellationError !== null) {
-        return reject(cancellationSignal.cancellationError);
-      }
+    return createCancellablePromise(cancellationSignal, (resolve, reject) => {
       const shouldRestartQueue = this._queue.length === 0 &&
                                  this._pendingTask === null;
       const queueItem = objectAssign({ resolve, reject }, operation);
       this._queue.push(queueItem);
-      cancellationSignal.register((error : CancellationError) => {
+      if (shouldRestartQueue) {
+        this._flush();
+      }
+      return () => {
         // Remove the corresponding element from the AudioVideoSegmentBuffer's
         // queue.
         // If the operation was a pending task, it should still continue to not
@@ -388,12 +407,7 @@ export default class AudioVideoSegmentBuffer extends SegmentBuffer {
         }
         queueItem.resolve = noop;
         queueItem.reject = noop;
-        reject(error);
-      });
-
-      if (shouldRestartQueue) {
-        this._flush();
-      }
+      };
     });
   }
 
@@ -451,7 +465,7 @@ export default class AudioVideoSegmentBuffer extends SegmentBuffer {
           const error = e instanceof Error ?
             e :
             new Error("An unknown error occured when preparing a push operation");
-          this._lastInitSegment = null; // initialize init segment as a security
+          this._lastInitSegmentUniqueId = null; // initialize init segment as a security
           nextItem.reject(error);
           return;
         }
@@ -561,15 +575,17 @@ export default class AudioVideoSegmentBuffer extends SegmentBuffer {
       this._sourceBuffer.appendWindowEnd = appendWindow[1];
     }
 
-    if (data.initSegment !== null &&
-        (hasUpdatedSourceBufferType || !this._isLastInitSegment(data.initSegment)))
+    if (data.initSegmentUniqueId !== null &&
+        (hasUpdatedSourceBufferType ||
+         !this._isLastInitSegment(data.initSegmentUniqueId)))
     {
       // Push initialization segment before the media segment
-      const segmentData = data.initSegment;
+      const segmentData = this._initSegmentsMap.get(data.initSegmentUniqueId);
+      if (segmentData === undefined) {
+        throw new Error("Invalid initialization segment uniqueId");
+      }
       dataToPush.push(segmentData);
-      const initU8 = toUint8Array(segmentData);
-      this._lastInitSegment = { data: initU8,
-                                hash: hashBuffer(initU8) };
+      this._lastInitSegmentUniqueId = data.initSegmentUniqueId;
     }
 
     if (data.chunk !== null) {
@@ -580,28 +596,16 @@ export default class AudioVideoSegmentBuffer extends SegmentBuffer {
   }
 
  /**
-  * Return `true` if the given `segmentData` is the same segment than the last
+  * Return `true` if the given `uniqueId` is the identifier of the last
   * initialization segment pushed to the `AudioVideoSegmentBuffer`.
-  * @param {BufferSource} segmentData
+  * @param {string} uniqueId
   * @returns {boolean}
   */
-  private _isLastInitSegment(segmentData : BufferSource) : boolean {
-    if (this._lastInitSegment === null) {
+  private _isLastInitSegment(uniqueId : string) : boolean {
+    if (this._lastInitSegmentUniqueId === null) {
       return false;
     }
-    if (this._lastInitSegment.data === segmentData) {
-      return true;
-    }
-    const oldInit = this._lastInitSegment.data;
-    if (oldInit.byteLength === segmentData.byteLength) {
-      const newInitU8 = toUint8Array(segmentData);
-      if (hashBuffer(newInitU8) === this._lastInitSegment.hash &&
-          areArraysOfNumbersEqual(oldInit, newInitU8))
-      {
-        return true;
-      }
-    }
-    return false;
+    return this._lastInitSegmentUniqueId === uniqueId;
   }
 }
 
@@ -609,27 +613,20 @@ export default class AudioVideoSegmentBuffer extends SegmentBuffer {
  * Throw if the given input is not in the expected format.
  * Allows to enforce runtime type-checking as compile-time type-checking here is
  * difficult to enforce.
- * @param {Object} pushedData
+ * @param {Object} data
  */
-function assertPushedDataIsBufferSource(
-  pushedData : IPushChunkInfos<unknown>
-) : asserts pushedData is IPushChunkInfos<BufferSource> {
+function assertDataIsBufferSource(
+  data : unknown
+) : asserts data is BufferSource {
   if (__ENVIRONMENT__.CURRENT_ENV === __ENVIRONMENT__.PRODUCTION as number) {
     return;
   }
-  const { chunk, initSegment } = pushedData.data;
   if (
-    typeof chunk !== "object" ||
-    typeof initSegment !== "object" ||
-    (
-      chunk !== null &&
-      !(chunk instanceof ArrayBuffer) &&
-      !((chunk as ArrayBufferView).buffer instanceof ArrayBuffer)
-    ) ||
+    typeof data !== "object" ||
     (
-      initSegment !== null &&
-      !(initSegment instanceof ArrayBuffer) &&
-      !((initSegment as ArrayBufferView).buffer instanceof ArrayBuffer)
+      data !== null &&
+      !(data instanceof ArrayBuffer) &&
+      !((data as ArrayBufferView).buffer instanceof ArrayBuffer)
     )
   ) {
     throw new Error("Invalid data given to the AudioVideoSegmentBuffer");

package/src/core/segment_buffers/implementations/text/html/html_text_segment_buffer.ts

@@ -137,6 +137,22 @@ export default class HTMLTextSegmentBuffer extends SegmentBuffer {
     this.autoRefreshSubtitles(this._canceller.signal);
   }
 
+  /**
+   * @param {string} uniqueId
+   */
+  public declareInitSegment(uniqueId : string): void {
+    log.warn("ISB: Declaring initialization segment for image SegmentBuffer",
+             uniqueId);
+  }
+
+  /**
+   * @param {string} uniqueId
+   */
+  public freeInitSegment(uniqueId : string): void {
+    log.warn("ISB: Freeing initialization segment for image SegmentBuffer",
+             uniqueId);
+  }
+
   /**
    * Push text segment to the HTMLTextSegmentBuffer.
    * @param {Object} infos
@@ -353,7 +369,8 @@ export default class HTMLTextSegmentBuffer extends SegmentBuffer {
                                element : HTMLElement; } => cue.resolution !== null);
 
     if (proportionalCues.length > 0) {
-      this._sizeUpdateCanceller = new TaskCanceller({ cancelOn: this._canceller.signal });
+      this._sizeUpdateCanceller = new TaskCanceller();
+      this._sizeUpdateCanceller.linkToSignal(this._canceller.signal);
       const { TEXT_TRACK_SIZE_CHECKS_INTERVAL } = config.getCurrent();
       // update propertionally-sized elements periodically
       const heightWidthRef = onHeightWidthChange(this._textTrackElement,
@@ -382,7 +399,8 @@ export default class HTMLTextSegmentBuffer extends SegmentBuffer {
 
     const startAutoRefresh = () => {
       stopAutoRefresh();
-      autoRefreshCanceller = new TaskCanceller({ cancelOn: cancellationSignal });
+      autoRefreshCanceller = new TaskCanceller();
+      autoRefreshCanceller.linkToSignal(cancellationSignal);
       const intervalId = setInterval(() => this.refreshSubtitles(),
                                      MAXIMUM_HTML_TEXT_TRACK_UPDATE_INTERVAL);
       autoRefreshCanceller.signal.register(() => {

package/src/core/segment_buffers/implementations/text/native/native_text_segment_buffer.ts

@@ -61,6 +61,22 @@ export default class NativeTextSegmentBuffer extends SegmentBuffer {
     this._trackElement = trackElement;
   }
 
+  /**
+   * @param {string} uniqueId
+   */
+  public declareInitSegment(uniqueId : string): void {
+    log.warn("ISB: Declaring initialization segment for image SegmentBuffer",
+             uniqueId);
+  }
+
+  /**
+   * @param {string} uniqueId
+   */
+  public freeInitSegment(uniqueId : string): void {
+    log.warn("ISB: Freeing initialization segment for image SegmentBuffer",
+             uniqueId);
+  }
+
   /**
    * @param {Object} infos
    * @returns {Promise}

package/src/core/segment_buffers/implementations/types.ts

@@ -87,6 +87,13 @@ export abstract class SegmentBuffer {
     this._segmentInventory = new SegmentInventory();
   }
 
+  public abstract declareInitSegment(
+    uniqueId : string,
+    initSegmentData : unknown
+  ) : void;
+
+  public abstract freeInitSegment(uniqueId : string) : void;
+
   /**
    * Push a chunk of the media segment given to the attached buffer, in a
    * FIFO queue.
@@ -96,7 +103,8 @@ export abstract class SegmentBuffer {
    * pushed.
    *
    * Depending on the type of data appended, the pushed chunk might rely on an
-   * initialization segment, given through the `data.initSegment` property.
+   * initialization segment, which had to be previously declared through the
+   * `declareInitSegment` method.
    *
    * Such initialization segment will be first pushed to the buffer if the
    * last pushed segment was associated to another initialization segment.
@@ -106,7 +114,7 @@ export abstract class SegmentBuffer {
    * reference).
    *
    * If you don't need any initialization segment to push the wanted chunk, you
-   * can just set `data.initSegment` to `null`.
+   * can just set the corresponding property to `null`.
    *
    * You can also only push an initialization segment by setting the
    * `data.chunk` argument to null.
@@ -229,12 +237,16 @@ export type IBufferType = "audio" |
  */
 export interface IPushedChunkData<T> {
   /**
-   * The whole initialization segment's data related to the chunk you want to
+   * The `uniqueId` of the initialization segment linked to the data you want to
    * push.
+   *
+   * That identifier should previously have been declared through the
+   * `declareInitSegment` method and not freed.
+   *
    * To set to `null` either if no initialization data is needed, or if you are
    * confident that the last pushed one is compatible.
    */
-  initSegment: T | null;
+  initSegmentUniqueId : string | null;
   /**
    * Chunk you want to push.
    * This can be the whole decodable segment's data or just a decodable sub-part

package/src/core/segment_buffers/index.ts

@@ -30,6 +30,7 @@ import {
 import {
   IBufferedChunk,
   IChunkContext,
+  IInsertedChunkInfos,
   getFirstSegmentAfterPeriod,
   getLastSegmentBeforePeriod,
 } from "./inventory";
@@ -51,6 +52,7 @@ export {
 
   IBufferedChunk,
   IChunkContext,
+  IInsertedChunkInfos,
 
   IPushChunkInfos,
   IPushedChunkData,

package/src/core/segment_buffers/segment_buffers_store.ts

@@ -17,10 +17,8 @@
 import { MediaError } from "../../errors";
 import features from "../../features";
 import log from "../../log";
-import {
-  CancellationError,
-  CancellationSignal,
-} from "../../utils/task_canceller";
+import createCancellablePromise from "../../utils/create_cancellable_promise";
+import { CancellationSignal } from "../../utils/task_canceller";
 import {
   AudioVideoSegmentBuffer,
   IBufferType,
@@ -189,21 +187,26 @@ export default class SegmentBuffersStore {
     if (this._areNativeBuffersUsable()) {
       return Promise.resolve();
     }
-    return new Promise((res, rej) => {
-      const onAddedOrDisabled = () => {
+    return createCancellablePromise(cancelWaitSignal, (res) => {
+      /* eslint-disable-next-line prefer-const */
+      let onAddedOrDisabled : () => void;
+
+      const removeCallback = () => {
+        const indexOf = this._onNativeBufferAddedOrDisabled.indexOf(onAddedOrDisabled);
+        if (indexOf >= 0) {
+          this._onNativeBufferAddedOrDisabled.splice(indexOf, 1);
+        }
+      };
+
+      onAddedOrDisabled = () => {
         if (this._areNativeBuffersUsable()) {
+          removeCallback();
           res();
         }
       };
       this._onNativeBufferAddedOrDisabled.push(onAddedOrDisabled);
 
-      cancelWaitSignal.register((error : CancellationError) => {
-        const indexOf = this._onNativeBufferAddedOrDisabled.indexOf(onAddedOrDisabled);
-        if (indexOf >= 0) {
-          this._onNativeBufferAddedOrDisabled.splice(indexOf, 1);
-        }
-        rej(error);
-      });
+      return removeCallback;
     });
   }
 

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

@@ -3,6 +3,8 @@ import { formatError } from "../../../errors";
 import log from "../../../log";
 import { Representation } from "../../../manifest";
 import assertUnreachable from "../../../utils/assert_unreachable";
+import cancellableSleep from "../../../utils/cancellable_sleep";
+import noop from "../../../utils/noop";
 import objectAssign from "../../../utils/object_assign";
 import {
   createMappedReference,
@@ -69,7 +71,8 @@ export default function AdaptationStream<T>(
   const { manifest, period, adaptation } = content;
 
   /** Allows to cancel everything the `AdaptationStream` is doing. */
-  const adapStreamCanceller = new TaskCanceller({ cancelOn: parentCancelSignal });
+  const adapStreamCanceller = new TaskCanceller();
+  adapStreamCanceller.linkToSignal(parentCancelSignal);
 
   /**
    * The buffer goal ratio base itself on the value given by `wantedBufferAhead`
@@ -144,9 +147,10 @@ export default function AdaptationStream<T>(
       cancelCurrentStreams.cancel();
     }
     representationsList.setValueIfChanged(val.representations);
-    cancelCurrentStreams = new TaskCanceller({ cancelOn: adapStreamCanceller.signal });
+    cancelCurrentStreams = new TaskCanceller();
+    cancelCurrentStreams.linkToSignal(adapStreamCanceller.signal);
     onRepresentationsChoiceChange(val, cancelCurrentStreams.signal).catch((err) => {
-      if (cancelCurrentStreams?.isUsed === true &&
+      if (cancelCurrentStreams?.isUsed() === true &&
           TaskCanceller.isCancellationError(err))
       {
         return;
@@ -195,13 +199,13 @@ export default function AdaptationStream<T>(
       case "clean-buffer": // Just clean
         for (const range of switchStrat.value) {
           await segmentBuffer.removeBuffer(range.start, range.end, fnCancelSignal);
-          if (fnCancelSignal.isCancelled) {
+          if (fnCancelSignal.isCancelled()) {
             return;
           }
         }
         if (switchStrat.type === "flush-buffer") {
           callbacks.needsBufferFlush();
-          if (fnCancelSignal.isCancelled) {
+          if (fnCancelSignal.isCancelled()) {
             return;
           }
         }
@@ -229,7 +233,8 @@ export default function AdaptationStream<T>(
      * terminating and as such the next one might be immediately created
      * recursively.
      */
-    const repStreamTerminatingCanceller = new TaskCanceller({ cancelOn: fnCancelSignal });
+    const repStreamTerminatingCanceller = new TaskCanceller();
+    repStreamTerminatingCanceller.linkToSignal(fnCancelSignal);
     const { representation } = estimateRef.getValue();
     if (representation === null) {
       return;
@@ -263,11 +268,11 @@ export default function AdaptationStream<T>(
 
     const repInfo = { type: adaptation.type, period, representation };
     currentRepresentation.setValue(representation);
-    if (adapStreamCanceller.isUsed) {
+    if (adapStreamCanceller.isUsed()) {
       return ; // previous callback has stopped everything by side-effect
     }
     callbacks.representationChange(repInfo);
-    if (adapStreamCanceller.isUsed) {
+    if (adapStreamCanceller.isUsed()) {
       return ; // previous callback has stopped everything by side-effect
     }
 
@@ -284,13 +289,13 @@ export default function AdaptationStream<T>(
       },
       addedSegment(segmentInfo) {
         abrCallbacks.addedSegment(segmentInfo);
-        if (adapStreamCanceller.isUsed) {
+        if (adapStreamCanceller.isUsed()) {
           return;
         }
         callbacks.addedSegment(segmentInfo);
       },
       terminating() {
-        if (repStreamTerminatingCanceller.isUsed) {
+        if (repStreamTerminatingCanceller.isUsed()) {
           return; // Already handled
         }
         repStreamTerminatingCanceller.cancel();
@@ -322,7 +327,8 @@ export default function AdaptationStream<T>(
     representationStreamCallbacks : IRepresentationStreamCallbacks<T>,
     fnCancelSignal : CancellationSignal
   ) : void {
-    const bufferGoalCanceller = new TaskCanceller({ cancelOn: fnCancelSignal });
+    const bufferGoalCanceller = new TaskCanceller();
+    bufferGoalCanceller.linkToSignal(fnCancelSignal);
     const bufferGoal = createMappedReference(wantedBufferAhead, prev => {
       return prev * getBufferGoalRatio(representation);
     }, bufferGoalCanceller.signal);
@@ -339,19 +345,27 @@ export default function AdaptationStream<T>(
           defaultCode: "NONE",
           defaultReason: "Unknown `RepresentationStream` error",
         });
-        if (formattedError.code === "BUFFER_FULL_ERROR") {
+        if (formattedError.code !== "BUFFER_FULL_ERROR") {
+          representationStreamCallbacks.error(err);
+        } else {
           const wba = wantedBufferAhead.getValue();
           const lastBufferGoalRatio = bufferGoalRatioMap.get(representation.id) ?? 1;
-          if (lastBufferGoalRatio <= 0.25 || wba * lastBufferGoalRatio <= 2) {
+          // 70%, 49%, 34.3%, 24%, 16.81%, 11.76%, 8.24% and 5.76%
+          const newBufferGoalRatio = lastBufferGoalRatio * 0.7;
+          if (newBufferGoalRatio <= 0.05 || wba * newBufferGoalRatio <= 2) {
             throw formattedError;
           }
-          bufferGoalRatioMap.set(representation.id, lastBufferGoalRatio - 0.25);
-          return createRepresentationStream(representation,
-                                            terminateCurrentStream,
-                                            representationStreamCallbacks,
-                                            fnCancelSignal);
+          bufferGoalRatioMap.set(representation.id, newBufferGoalRatio);
+
+          // We wait 4 seconds to let the situation evolve by itself before
+          // retrying loading segments with a lower buffer goal
+          cancellableSleep(4000, adapStreamCanceller.signal).then(() => {
+            return createRepresentationStream(representation,
+                                              terminateCurrentStream,
+                                              representationStreamCallbacks,
+                                              fnCancelSignal);
+          }).catch(noop);
         }
-        representationStreamCallbacks.error(err);
       },
       terminating() {
         bufferGoalCanceller.cancel();

package/src/core/stream/adaptation/utils/create_representation_estimator.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 { MediaError } from "../../../../errors";
+import Manifest, {
+  Adaptation,
+  Period,
+  Representation,
+} from "../../../../manifest";
+import { IPlayerError } from "../../../../public_types";
+import createSharedReference, {
+  IReadOnlySharedReference,
+} from "../../../../utils/reference";
+import { CancellationSignal } from "../../../../utils/task_canceller";
+import {
+  IABREstimate,
+  IRepresentationEstimatorPlaybackObservation,
+  IRepresentationEstimator,
+  IRepresentationEstimatorCallbacks,
+} from "../../../adaptive";
+import { IReadOnlyPlaybackObserver } from "../../../api";
+
+/**
+ * Produce estimates to know which Representation should be played.
+ * @param {Object} content - The Manifest, Period and Adaptation wanted.
+ * @param {Object} representationEstimator - `IRepresentationEstimator` which
+ * will produce Representation estimates.
+ * @param {Object} currentRepresentation - Reference emitting the
+ * currently-loaded Representation.
+ * @param {Object} playbackObserver - Allows to observe the current playback
+ * conditions.
+ * @param {Function} onFatalError - Callback called when a fatal error was
+ * thrown. Once this callback is called, no estimate will be produced.
+ * @param {Object} cancellationSignal - `CancellationSignal` allowing to abort
+ * the production of estimates (and clean-up all linked resources).
+ * @returns {Object} - Returns an object with the following properties:
+ *   - `estimateRef`: Reference emitting the last estimate
+ *   - `abrCallbacks`: Callbacks allowing to report back network and playback
+ *     activities to improve the estimates given.
+ */
+export default function getRepresentationEstimate(
+  content : { manifest : Manifest;
+              period : Period;
+              adaptation : Adaptation; },
+  representationEstimator : IRepresentationEstimator,
+  currentRepresentation : IReadOnlySharedReference<Representation | null>,
+  playbackObserver : IReadOnlyPlaybackObserver<
+    IRepresentationEstimatorPlaybackObservation
+  >,
+  onFatalError: (err : IPlayerError) => void,
+  cancellationSignal : CancellationSignal
+) : { estimateRef : IReadOnlySharedReference<IABREstimate>;
+      abrCallbacks : IRepresentationEstimatorCallbacks; }
+{
+  const { manifest, adaptation } = content;
+  const representations = createSharedReference<Representation[]>(
+    [],
+    cancellationSignal);
+  updateRepresentationsReference();
+  manifest.addEventListener("decipherabilityUpdate", updateRepresentationsReference);
+  const unregisterCleanUp = cancellationSignal.register(cleanUp);
+  const { estimates: estimateRef,
+          callbacks: abrCallbacks } = representationEstimator(content,
+                                                              currentRepresentation,
+                                                              representations,
+                                                              playbackObserver,
+                                                              cancellationSignal);
+  return { abrCallbacks, estimateRef };
+
+  function updateRepresentationsReference() : void {
+    /** Representations for which a `RepresentationStream` can be created. */
+    const newRepr = adaptation.getPlayableRepresentations();
+    if (newRepr.length === 0) {
+      const noRepErr = new MediaError("NO_PLAYABLE_REPRESENTATION",
+                                      "No Representation in the chosen " +
+                                      adaptation.type + " Adaptation can be played",
+                                      { adaptation });
+      cleanUp();
+      onFatalError(noRepErr);
+      return;
+    }
+
+    const prevRepr = representations.getValue();
+    if (prevRepr.length === newRepr.length) {
+      if (prevRepr.every((r, idx) => r.id === newRepr[idx].id)) {
+        return ;
+      }
+    }
+    representations.setValue(newRepr);
+  }
+
+  /** Clean-up all resources taken here. */
+  function cleanUp() : void {
+    manifest.removeEventListener("decipherabilityUpdate", updateRepresentationsReference);
+
+    // check to protect against the case where it is not yet defined.
+    if (typeof unregisterCleanUp !== "undefined") {
+      unregisterCleanUp();
+    }
+  }
+}