rx-player 4.4.1 → 4.5.0-dev.2026012301

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

@@ -195,8 +195,11 @@ export abstract class SegmentSink {
    * Dispose of the resources used by this SegmentSink.
    * /!\ You won't be able to use the SegmentSink after calling this
    * function.
+   * @param {string | undefined} reason - Human-inspectable reason behind the
+   * dispose. Used for debugging matters, especially for debug log
+   * inspection.
    */
-  public abstract dispose(): void;
+  public abstract dispose(reason: string | undefined): void;
 }
 
 /** Every SegmentSink types. */

package/src/core/segment_sinks/segment_sinks_store.ts

@@ -334,8 +334,11 @@ export default class SegmentSinksStore {
   /**
    * Dispose of the active SegmentSink for the given type.
    * @param {string} bufferType
+   * @param {string | undefined} reason - Human-inspectable reason behind the
+   * dispose. Used for debugging matters, especially for debug log
+   * inspection.
    */
-  public disposeSegmentSink(bufferType: IBufferType): void {
+  public disposeSegmentSink(bufferType: IBufferType, reason: string | undefined): void {
     const memorizedSegmentSink = this._initializedSegmentSinks[bufferType];
     if (isNullOrUndefined(memorizedSegmentSink)) {
       log.warn("Stream", "Trying to dispose a SegmentSink that does not exist", {
@@ -345,17 +348,20 @@ export default class SegmentSinksStore {
     }
 
     log.info("Stream", "Aborting SegmentSink", { bufferType });
-    memorizedSegmentSink.dispose();
+    memorizedSegmentSink.dispose(reason);
     delete this._initializedSegmentSinks[bufferType];
   }
 
   /**
    * Dispose of all SegmentSink created on this SegmentSinksStore.
+   * @param {string | undefined} reason - Human-inspectable reason behind the
+   * dispose. Used for debugging matters, especially for debug log
+   * inspection.
    */
-  public disposeAll(): void {
+  public disposeAll(reason: string | undefined): void {
     POSSIBLE_BUFFER_TYPES.forEach((bufferType: IBufferType) => {
       if (this.getStatus(bufferType).type === "initialized") {
-        this.disposeSegmentSink(bufferType);
+        this.disposeSegmentSink(bufferType, reason);
       }
     });
   }

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

@@ -68,7 +68,7 @@ export default function AdaptationStream(
   const { manifest, period, adaptation } = content;
 
   /** Allows to cancel everything the `AdaptationStream` is doing. */
-  const adapStreamCanceller = new TaskCanceller();
+  const adapStreamCanceller = new TaskCanceller("AdaptationStream " + adaptation.type);
   adapStreamCanceller.linkToSignal(parentCancelSignal);
 
   /**
@@ -175,7 +175,7 @@ export default function AdaptationStream(
   content.representations.onUpdate(
     (val) => {
       if (cancelCurrentStreams !== undefined) {
-        cancelCurrentStreams.cancel();
+        cancelCurrentStreams.cancel("locked representations changed");
       }
       const newRepIds = content.representations.getValue().representationIds;
 
@@ -187,7 +187,9 @@ export default function AdaptationStream(
         newRepIds,
       );
       representationsList.setValueIfChanged(newRepresentations);
-      cancelCurrentStreams = new TaskCanceller();
+      cancelCurrentStreams = new TaskCanceller(
+        "AdaptationStream: RepresentationStream Group " + adaptation.type,
+      );
       cancelCurrentStreams.linkToSignal(adapStreamCanceller.signal);
       onRepresentationsChoiceChange(val, cancelCurrentStreams.signal).catch((err) => {
         if (
@@ -196,7 +198,7 @@ export default function AdaptationStream(
         ) {
           return;
         }
-        adapStreamCanceller.cancel();
+        adapStreamCanceller.cancel("RepresentationStream err");
         callbacks.error(err);
       });
     },
@@ -213,12 +215,12 @@ export default function AdaptationStream(
    * error or on some cancellation.
    * @param {Object} choice - The last Representations choice that has been
    * made.
-   * @param {Object} fnCancelSignal - `CancellationSignal` allowing to cancel
-   * everything this function is doing and free all related resources.
+   * @param {Object} repsChoiceCancelSignal - `CancellationSignal` allowing to
+   * cancel everything this function is doing and free all related resources.
    */
   async function onRepresentationsChoiceChange(
     choice: IRepresentationsChoice,
-    fnCancelSignal: CancellationSignal,
+    repsChoiceCancelSignal: CancellationSignal,
   ): Promise<void> {
     // First check if we should perform any action regarding what was previously
     // in the buffer
@@ -241,7 +243,7 @@ export default function AdaptationStream(
         return queueMicrotask(() => {
           playbackObserver.listen(
             () => {
-              if (fnCancelSignal.isCancelled()) {
+              if (repsChoiceCancelSignal.isCancelled()) {
                 return;
               }
               const { DELTA_POSITION_AFTER_RELOAD } = config.getCurrent();
@@ -253,7 +255,7 @@ export default function AdaptationStream(
                 stayInPeriod: true,
               });
             },
-            { includeLastObservation: true, clearSignal: fnCancelSignal },
+            { includeLastObservation: true, clearSignal: repsChoiceCancelSignal },
           );
         });
 
@@ -261,13 +263,13 @@ export default function AdaptationStream(
       case "clean-buffer": // Just clean
         for (const range of switchStrat.value) {
           await segmentSink.removeBuffer(range.start, range.end);
-          if (fnCancelSignal.isCancelled()) {
+          if (repsChoiceCancelSignal.isCancelled()) {
             return;
           }
         }
         if (switchStrat.type === "flush-buffer") {
           callbacks.needsBufferFlush();
-          if (fnCancelSignal.isCancelled()) {
+          if (repsChoiceCancelSignal.isCancelled()) {
             return;
           }
         }
@@ -276,7 +278,7 @@ export default function AdaptationStream(
         assertUnreachable(switchStrat);
     }
 
-    recursivelyCreateRepresentationStreams(fnCancelSignal);
+    recursivelyCreateRepresentationStreams(repsChoiceCancelSignal);
   }
 
   /**
@@ -295,7 +297,9 @@ export default function AdaptationStream(
      * terminating and as such the next one might be immediately created
      * recursively.
      */
-    const repStreamTerminatingCanceller = new TaskCanceller();
+    const repStreamTerminatingCanceller = new TaskCanceller(
+      "AdaptationStream: RepresentationStream creation " + adaptation.type,
+    );
     repStreamTerminatingCanceller.linkToSignal(fnCancelSignal);
     const { representation } = estimateRef.getValue();
     if (representation === null) {
@@ -328,7 +332,10 @@ export default function AdaptationStream(
             prevRepresentationBitrate: representation.bitrate,
             newRepresentationBitrate: estimate.representation.bitrate,
           });
-          return terminateCurrentStream.setValue({ urgent: true });
+          return terminateCurrentStream.setValue({
+            urgent: true,
+            reason: "Urgent Representation switch",
+          });
         } else {
           log.info("Stream", "slow Representation switch", {
             bufferType: adaptation.type,
@@ -336,7 +343,10 @@ export default function AdaptationStream(
             prevRepresentationBitrate: representation.bitrate,
             newRepresentationBitrate: estimate.representation.bitrate,
           });
-          return terminateCurrentStream.setValue({ urgent: false });
+          return terminateCurrentStream.setValue({
+            urgent: false,
+            reason: "Non-urgent Representation switch",
+          });
         }
       },
       {
@@ -368,7 +378,7 @@ export default function AdaptationStream(
       inbandEvent: callbacks.inbandEvent,
       warning: callbacks.warning,
       error(err: unknown) {
-        adapStreamCanceller.cancel();
+        adapStreamCanceller.cancel("RepresentationStream err cb");
         callbacks.error(err);
       },
       addedSegment(segmentInfo) {
@@ -378,7 +388,7 @@ export default function AdaptationStream(
         if (repStreamTerminatingCanceller.isUsed()) {
           return; // Already handled
         }
-        repStreamTerminatingCanceller.cancel();
+        repStreamTerminatingCanceller.cancel("RepresentationStream terminating");
         return recursivelyCreateRepresentationStreams(fnCancelSignal);
       },
     };
@@ -400,20 +410,34 @@ export default function AdaptationStream(
    * indicating that the `RepresentationStream` should stop what it's doing.
    * @param {Object} representationStreamCallbacks - Callbacks to call on
    * various `RepresentationStream` events.
-   * @param {Object} fnCancelSignal - `CancellationSignal` which will abort
-   * anything this function is doing and free allocated resources.
+   * @param {Object} globalCancelSignal - `CancellationSignal` which will
+   * immediately clean every resources allocated by this function.
    */
   function createRepresentationStream(
     representation: IRepresentation,
     terminateCurrentStream: IReadOnlySharedReference<ITerminationOrder | null>,
     representationStreamCallbacks: IRepresentationStreamCallbacks,
-    fnCancelSignal: CancellationSignal,
+    globalCancelSignal: CancellationSignal,
   ): void {
     /** Set to `true` if we've encountered an error with this `RepresentationStream` */
     let hasEncounteredError = false;
 
-    const bufferGoalCanceller = new TaskCanceller();
-    bufferGoalCanceller.linkToSignal(fnCancelSignal);
+    /**
+     * Construct a `TaskCanceller`, triggered once the `RepresentationStream` we
+     * will create here announces that it is "terminating" (implies that it is
+     * done loading new data and will clean itself automatically once it has
+     * pushed all loaded segments).
+     *
+     * We keep it distinct from `globalCancelSignal` as the latter's lifetime may
+     * be much much longer than our `RepresentationStream`'s.
+     * Thus it wouldn't be adapted as a canceller for the listeners we're
+     * registering here.
+     */
+    const terminatingCanceller = new TaskCanceller(
+      "RepresentationStream-linked listeners in AdaptationStream - " +
+        `periodStart=${period.start} type=${adaptation.type}`,
+    );
+    terminatingCanceller.linkToSignal(globalCancelSignal);
 
     /** Actually built buffer size, in seconds. */
     const bufferGoal = createMappedReference(
@@ -421,7 +445,7 @@ export default function AdaptationStream(
       (prev) => {
         return getBufferGoal(representation, prev);
       },
-      bufferGoalCanceller.signal,
+      terminatingCanceller.signal,
     );
 
     const maxBufferSize =
@@ -468,20 +492,21 @@ export default function AdaptationStream(
 
           // We wait 4 seconds to let the situation evolve by itself before
           // retrying loading segments with a lower buffer goal
-          cancellableSleep(4000, fnCancelSignal)
+          // If the `RepresentationStream` was terminating anyway, just exits
+          cancellableSleep(4000, terminatingCanceller.signal)
             .then(() => {
               return createRepresentationStream(
                 representation,
                 terminateCurrentStream,
                 representationStreamCallbacks,
-                fnCancelSignal,
+                globalCancelSignal,
               );
             })
             .catch(noop);
         }
       },
       terminating() {
-        bufferGoalCanceller.cancel();
+        terminatingCanceller.cancel("Representation terminating");
         representationStreamCallbacks.terminating();
       },
     });
@@ -500,7 +525,16 @@ export default function AdaptationStream(
         },
       },
       updatedCallbacks,
-      fnCancelSignal,
+      // NOTE: We give the long-lived `globalCancelSignal` here (and not
+      // `terminatingCanceller.signal`) on purpose.
+      // `RepresentationStream` should clean-up themselves automatically based
+      // on their `terminate` parameter.
+      //
+      // This `CancellationSignal` is a killswitch which if triggered too
+      // soon might interrupt some async operations done when this
+      // `RepresentationStream` is terminating: e.g. stop pushing the segments
+      // it has just loaded.
+      globalCancelSignal,
     );
 
     // reload if the Representation disappears from the Manifest
@@ -513,7 +547,7 @@ export default function AdaptationStream(
               if (updated.adaptation === adaptation.id) {
                 for (const rep of updated.removedRepresentations) {
                   if (rep === representation.id) {
-                    if (fnCancelSignal.isCancelled()) {
+                    if (terminatingCanceller.isUsed()) {
                       return;
                     }
                     return callbacks.waitingMediaSourceReload({
@@ -531,7 +565,7 @@ export default function AdaptationStream(
           }
         }
       },
-      fnCancelSignal,
+      terminatingCanceller.signal,
     );
   }
 

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

@@ -163,7 +163,9 @@ export default function StreamOrchestrator(
     let enableOutOfBoundsCheck = false;
 
     /** Cancels currently created `PeriodStream`s. */
-    let currentCanceller = new TaskCanceller();
+    let currentCanceller = new TaskCanceller(
+      "StreamOrchestrator Streams for " + bufferType,
+    );
     currentCanceller.linkToSignal(orchestratorCancelSignal);
 
     // Restart the current Stream when the wanted time is in another period
@@ -196,8 +198,10 @@ export default function StreamOrchestrator(
           periodList.removeElement(period);
           callbacks.periodStreamCleared({ type: bufferType, manifest, period });
         }
-        currentCanceller.cancel();
-        currentCanceller = new TaskCanceller();
+        currentCanceller.cancel("PeriodStream is out of bounds");
+        currentCanceller = new TaskCanceller(
+          "StreamOrchestrator Streams for " + bufferType,
+        );
         currentCanceller.linkToSignal(orchestratorCancelSignal);
 
         // As previous callbacks may have performed unknown side-effects, just
@@ -223,7 +227,7 @@ export default function StreamOrchestrator(
           if (orchestratorCancelSignal.isCancelled()) {
             return;
           }
-          currentCanceller.cancel();
+          currentCanceller.cancel("decipherabilityUpdate event");
           callbacks.error(err);
         });
       },
@@ -265,7 +269,7 @@ export default function StreamOrchestrator(
           callbacks.periodStreamCleared(payload);
         },
         error(err: unknown): void {
-          currentCanceller.cancel();
+          currentCanceller.cancel("PeriodStream err callback");
           callbacks.error(err);
         },
       };
@@ -360,8 +364,10 @@ export default function StreamOrchestrator(
         callbacks.periodStreamCleared({ type: bufferType, manifest, period });
       }
 
-      currentCanceller.cancel();
-      currentCanceller = new TaskCanceller();
+      currentCanceller.cancel("decipherability update");
+      currentCanceller = new TaskCanceller(
+        "StreamOrchestrator Streams for " + bufferType,
+      );
       currentCanceller.linkToSignal(orchestratorCancelSignal);
 
       /** Remove from the `SegmentSink` all the concerned time ranges. */
@@ -495,7 +501,9 @@ export default function StreamOrchestrator(
     } | null = null;
 
     /** Emits when the `PeriodStream` linked to `basePeriod` should be destroyed. */
-    const currentStreamCanceller = new TaskCanceller();
+    const currentStreamCanceller = new TaskCanceller(
+      "StreamOrchestrator current consecutive Streams " + bufferType,
+    );
     currentStreamCanceller.linkToSignal(cancelSignal);
 
     // Stop current PeriodStream when the current position goes over the end of
@@ -525,7 +533,7 @@ export default function StreamOrchestrator(
             manifest,
             period: basePeriod,
           });
-          currentStreamCanceller.cancel();
+          currentStreamCanceller.cancel("Position ahead of PeriodStream");
         }
       },
       { clearSignal: cancelSignal, includeLastObservation: true },
@@ -568,17 +576,17 @@ export default function StreamOrchestrator(
             manifest,
             period: nextStreamInfo.period,
           });
-          nextStreamInfo.canceller.cancel();
+          nextStreamInfo.canceller.cancel("previous PeriodStream is active");
           nextStreamInfo = null;
         }
         consecutivePeriodStreamCb.streamStatusUpdate(value);
       },
       error(err: unknown): void {
         if (nextStreamInfo !== null) {
-          nextStreamInfo.canceller.cancel();
+          nextStreamInfo.canceller.cancel("previous PeriodStream err");
           nextStreamInfo = null;
         }
-        currentStreamCanceller.cancel();
+        currentStreamCanceller.cancel("PeriodStream err");
         consecutivePeriodStreamCb.error(err);
       },
     };
@@ -608,9 +616,11 @@ export default function StreamOrchestrator(
           manifest,
           period: nextStreamInfo.period,
         });
-        nextStreamInfo.canceller.cancel();
+        nextStreamInfo.canceller.cancel("PeriodStream recreation");
       }
-      const nextStreamCanceller = new TaskCanceller();
+      const nextStreamCanceller = new TaskCanceller(
+        "StreamOrchestrator next PeriodStream " + bufferType,
+      );
       nextStreamCanceller.linkToSignal(cancelSignal);
       nextStreamInfo = { canceller: nextStreamCanceller, period: nextPeriod };
       manageConsecutivePeriodStreams(
@@ -682,7 +692,7 @@ export default function StreamOrchestrator(
                   manifest,
                   period: nextStreamInfo.period,
                 });
-                nextStreamInfo.canceller.cancel();
+                nextStreamInfo.canceller.cancel("Next Period changed");
                 nextStreamInfo = null;
               }
             }

package/src/core/stream/period/period_stream.ts

@@ -125,9 +125,11 @@ export default function PeriodStream(
           return;
         }
 
-        const streamCanceller = new TaskCanceller();
+        const streamCanceller = new TaskCanceller(
+          "PeriodStream: Adaptation choice " + bufferType,
+        );
         streamCanceller.linkToSignal(parentCancelSignal);
-        currentStreamCanceller?.cancel(); // Cancel previously created stream if one
+        currentStreamCanceller?.cancel("PeriodStream: Adaptation update"); // Cancel previously created stream if one
         currentStreamCanceller = streamCanceller;
 
         if (choice === null) {
@@ -192,7 +194,7 @@ export default function PeriodStream(
           (a) => a.id === choice.adaptationId,
         );
         if (adaptation === undefined) {
-          currentStreamCanceller.cancel();
+          currentStreamCanceller.cancel("PeriodStream: Adaptation not found");
           log.warn("Stream", "Unfound chosen Adaptation choice", {
             adaptationId: choice.adaptationId,
           });
@@ -332,7 +334,7 @@ export default function PeriodStream(
         if (err instanceof CancellationError) {
           return;
         }
-        currentStreamCanceller?.cancel();
+        currentStreamCanceller?.cancel("PeriodStream err");
         callbacks.error(err);
       });
     },
@@ -381,7 +383,7 @@ export default function PeriodStream(
           `${bufferType} Stream crashed. Aborting it.`,
           error instanceof Error ? error : "",
         );
-        segmentSinksStore.disposeSegmentSink(bufferType);
+        segmentSinksStore.disposeSegmentSink(bufferType, "AdaptationStream err");
 
         const formattedError = formatError(error, {
           defaultCode: "NONE",

package/src/core/stream/representation/representation_stream.ts

@@ -102,7 +102,7 @@ export default function RepresentationStream<TSegmentDataType>(
   const bufferType = adaptation.type;
 
   /** `TaskCanceller` stopping operations performed by the `RepresentationStream` */
-  const canceller = new TaskCanceller();
+  const canceller = new TaskCanceller("RepresentationStream " + bufferType);
   canceller.linkToSignal(parentCancelSignal);
 
   /** Saved initialization segment state for this representation. */
@@ -154,13 +154,17 @@ export default function RepresentationStream<TSegmentDataType>(
     }
   }
 
-  segmentQueue.addEventListener("error", (err) => {
-    if (canceller.signal.isCancelled()) {
-      return; // ignore post requests-cancellation loading-related errors,
-    }
-    canceller.cancel(); // Stop every operations
-    callbacks.error(err);
-  });
+  segmentQueue.addEventListener(
+    "error",
+    (err) => {
+      if (canceller.signal.isCancelled()) {
+        return; // ignore post requests-cancellation loading-related errors,
+      }
+      canceller.cancel("RepresentationStream: SegmentQueue err"); // Stop every operations
+      callbacks.error(err);
+    },
+    canceller.signal,
+  );
   segmentQueue.addEventListener("parsedInitSegment", onParsedChunk, canceller.signal);
   segmentQueue.addEventListener("parsedMediaSegment", onParsedChunk, canceller.signal);
   segmentQueue.addEventListener("emptyQueue", checkStatus, canceller.signal);
@@ -192,10 +196,14 @@ export default function RepresentationStream<TSegmentDataType>(
   );
 
   /** Emit the last scheduled downloading queue for segments. */
-  const segmentsToLoadRef = segmentQueue.resetForContent(content, hasInitSegment);
+  const segmentsToLoadRef = segmentQueue.resetForContent(
+    content,
+    hasInitSegment,
+    "new RepresentationStream linked to SegmentQueue",
+  );
 
-  canceller.signal.register(() => {
-    segmentQueue.stop();
+  canceller.signal.register((err) => {
+    segmentQueue.stop(err.reason);
   });
 
   playbackObserver.listen(checkStatus, {
@@ -290,7 +298,7 @@ export default function RepresentationStream<TSegmentDataType>(
       });
       segmentsToLoadRef.setValue({ initSegment: null, segmentQueue: [] });
       segmentsToLoadRef.finish();
-      canceller.cancel();
+      canceller.cancel(terminateVal.reason);
       callbacks.terminating();
       return;
     } else {
@@ -321,7 +329,7 @@ export default function RepresentationStream<TSegmentDataType>(
           representationBitrate: content.representation.bitrate,
         });
         segmentsToLoadRef.finish();
-        canceller.cancel();
+        canceller.cancel(terminateVal.reason);
         callbacks.terminating();
         return;
       }
@@ -482,7 +490,7 @@ export default function RepresentationStream<TSegmentDataType>(
       },
       err instanceof Error ? err : null,
     );
-    canceller.cancel();
+    canceller.cancel("RepresentationStream: fatal buffer err");
     callbacks.error(err);
   }
 }

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

@@ -253,6 +253,11 @@ export interface ITerminationOrder {
    * finished.
    */
   urgent: boolean;
+  /**
+   * Human-readable string describing the reason for the change.
+   * This is useful when debugging.
+   */
+  reason: string;
 }
 
 /** Arguments to give to the RepresentationStream. */