rx-player 3.25.2 → 3.26.3-dev.2022021400

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

@@ -63,8 +63,8 @@ export default class TextTrackCuesStore {
 
     // begins at the end as most of the time the player will ask for the last
     // CuesGroup
-    for (let i = cuesBuffer.length - 1; i >= 0; i--) {
-      const segment = cuesBuffer[i];
+    for (let cueIdx = cuesBuffer.length - 1; cueIdx >= 0; cueIdx--) {
+      const segment = cuesBuffer[cueIdx];
       if (time < segment.end && time >= segment.start) {
         const cues = segment.cues;
         for (let j = 0; j < cues.length; j++) {
@@ -84,7 +84,7 @@ export default class TextTrackCuesStore {
    * @param {Number} to
    */
   remove(from : number, _to : number) : void {
-    if (__DEV__) {
+    if (__ENVIRONMENT__.CURRENT_ENV === __ENVIRONMENT__.DEV as number) {
       assert(from >= 0);
       assert(_to >= 0);
       assert(_to > from);
@@ -92,10 +92,10 @@ export default class TextTrackCuesStore {
 
     const to = Math.max(from, _to);
     const cuesBuffer = this._cuesBuffer;
-    for (let i = 0; i < cuesBuffer.length; i++) {
-      if (cuesBuffer[i].end > from) {
+    for (let cueIdx = 0; cueIdx < cuesBuffer.length; cueIdx++) {
+      if (cuesBuffer[cueIdx].end > from) {
         // this cuesInfos is concerned by the remove
-        const startCuesInfos = cuesBuffer[i];
+        const startCuesInfos = cuesBuffer[cueIdx];
         if (startCuesInfos.start >= to) {
           // our cuesInfos is strictly after this interval, we have nothing to do
           return;
@@ -112,8 +112,8 @@ export default class TextTrackCuesStore {
                     cuesInfos2 ] = removeCuesInfosBetween(startCuesInfos,
                                                           from,
                                                           to);
-            this._cuesBuffer[i] = cuesInfos1;
-            cuesBuffer.splice(i + 1, 0, cuesInfos2);
+            this._cuesBuffer[cueIdx] = cuesInfos1;
+            cuesBuffer.splice(cueIdx + 1, 0, cuesInfos2);
           }
           // No cuesInfos can be concerned after this one, we can quit
           return;
@@ -122,8 +122,8 @@ export default class TextTrackCuesStore {
         // Else remove all part after `from`
         if (startCuesInfos.start >= from) {
           // all the segment is concerned
-          cuesBuffer.splice(i, 1);
-          i--; // one less element, we have to decrement the loop
+          cuesBuffer.splice(cueIdx, 1);
+          cueIdx--; // one less element, we have to decrement the loop
         } else {
           // only the end is concerned
           startCuesInfos.cues = getCuesBefore(startCuesInfos.cues, from);
@@ -207,8 +207,8 @@ export default class TextTrackCuesStore {
       }
     }
 
-    for (let i = 0; i < cuesBuffer.length; i++) {
-      let cuesInfos = cuesBuffer[i];
+    for (let cueIdx = 0; cueIdx < cuesBuffer.length; cueIdx++) {
+      let cuesInfos = cuesBuffer[cueIdx];
       if (start < cuesInfos.end) {
         if (areNearlyEqual(start, cuesInfos.start)) {
           if (areNearlyEqual(end, cuesInfos.end)) {
@@ -218,7 +218,7 @@ export default class TextTrackCuesStore {
             //   Result:          |AAAAA|
             // Which means:
             //   1. replace the current cue with ours
-            cuesBuffer[i] = cuesInfosToInsert;
+            cuesBuffer[cueIdx] = cuesInfosToInsert;
             return;
           } else if (end < cuesInfos.end) {
             // our cue overlaps with the current one:
@@ -231,7 +231,7 @@ export default class TextTrackCuesStore {
             //   3. add ours before the current one
             cuesInfos.cues = getCuesAfter(cuesInfos.cues, end);
             cuesInfos.start = end;
-            cuesBuffer.splice(i, 0, cuesInfosToInsert);
+            cuesBuffer.splice(cueIdx, 0, cuesInfosToInsert);
             return;
           }
 
@@ -242,10 +242,10 @@ export default class TextTrackCuesStore {
           // Here we have to delete any cuesInfos which end before ours end,
           // and see about the following one.
           do {
-            cuesBuffer.splice(i, 1);
-            cuesInfos = cuesBuffer[i];
+            cuesBuffer.splice(cueIdx, 1);
+            cuesInfos = cuesBuffer[cueIdx];
           } while (cuesInfos !== undefined && end > cuesInfos.end);
-          onIndexOfNextCueFound(i);
+          onIndexOfNextCueFound(cueIdx);
           return;
         } else if (start < cuesInfos.start) {
           if (end < cuesInfos.start) {
@@ -255,7 +255,7 @@ export default class TextTrackCuesStore {
             //   Result:          |AAAAAAA| |BBBB|
             // Which means:
             //   - add ours before the current one
-            cuesBuffer.splice(i, 0, cuesInfosToInsert);
+            cuesBuffer.splice(cueIdx, 0, cuesInfosToInsert);
             return;
           } else if (areNearlyEqual(end, cuesInfos.start)) {
             // our cue goes just before the current one:
@@ -266,14 +266,14 @@ export default class TextTrackCuesStore {
             //   - update start time of the current one to be sure
             //   - add ours before the current one
             cuesInfos.start = end;
-            cuesBuffer.splice(i, 0, cuesInfosToInsert);
+            cuesBuffer.splice(cueIdx, 0, cuesInfosToInsert);
             return;
           } else if (areNearlyEqual(end, cuesInfos.end)) {
             //   ours:            |AAAAAAA|
             //   the current one:    |BBBB|
             //   Result:          |AAAAAAA|
             // Replace
-            cuesBuffer.splice(i, 1, cuesInfosToInsert);
+            cuesBuffer.splice(cueIdx, 1, cuesInfosToInsert);
             return;
           } else if (end < cuesInfos.end) {
             //   ours:            |AAAAAAA|
@@ -281,7 +281,7 @@ export default class TextTrackCuesStore {
             //   Result:          |AAAAAAABB|
             cuesInfos.cues = getCuesAfter(cuesInfos.cues, end);
             cuesInfos.start = end;
-            cuesBuffer.splice(i, 0, cuesInfosToInsert);
+            cuesBuffer.splice(cueIdx, 0, cuesInfosToInsert);
             return;
           }
 
@@ -289,10 +289,10 @@ export default class TextTrackCuesStore {
           //   the current one:   |BBB|...
           //   Result:          |AAAAAAA|...
           do {
-            cuesBuffer.splice(i, 1);
-            cuesInfos = cuesBuffer[i];
+            cuesBuffer.splice(cueIdx, 1);
+            cuesInfos = cuesBuffer[cueIdx];
           } while (cuesInfos !== undefined && end > cuesInfos.end);
-          onIndexOfNextCueFound(i);
+          onIndexOfNextCueFound(cueIdx);
           return;
         }
         // else -> start > cuesInfos.start
@@ -303,7 +303,7 @@ export default class TextTrackCuesStore {
           //   Result:          |BBAAAAAA|
           cuesInfos.cues = getCuesBefore(cuesInfos.cues, start);
           cuesInfos.end = start;
-          cuesBuffer.splice(i + 1, 0, cuesInfosToInsert);
+          cuesBuffer.splice(cueIdx + 1, 0, cuesInfosToInsert);
           return;
         } else if (cuesInfos.end > end) {
           //   ours:              |AAAAAA|
@@ -311,9 +311,9 @@ export default class TextTrackCuesStore {
           //   Result:          |BBAAAAAABBB|
           const [ cuesInfos1,
                   cuesInfos2 ] = removeCuesInfosBetween(cuesInfos, start, end);
-          this._cuesBuffer[i] = cuesInfos1;
-          cuesBuffer.splice(i + 1, 0, cuesInfosToInsert);
-          cuesBuffer.splice(i + 2, 0, cuesInfos2);
+          this._cuesBuffer[cueIdx] = cuesInfos1;
+          cuesBuffer.splice(cueIdx + 1, 0, cuesInfosToInsert);
+          cuesBuffer.splice(cueIdx + 2, 0, cuesInfos2);
           return;
         } else {
           //   ours:              |AAAAAA|
@@ -322,12 +322,13 @@ export default class TextTrackCuesStore {
           cuesInfos.cues = getCuesBefore(cuesInfos.cues, start);
           cuesInfos.end = start;
 
-          cuesInfos = cuesBuffer[i + 1];
+          const nextCueIdx = cueIdx + 1;
+          cuesInfos = cuesBuffer[nextCueIdx];
           while (cuesInfos !== undefined && end > cuesInfos.end) {
-            cuesBuffer.splice(i, 1);
-            cuesInfos = cuesBuffer[i];
+            cuesBuffer.splice(nextCueIdx, 1);
+            cuesInfos = cuesBuffer[nextCueIdx];
           }
-          onIndexOfNextCueFound(i);
+          onIndexOfNextCueFound(nextCueIdx);
           return;
         }
       }

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

@@ -40,14 +40,12 @@ import parseTextTrackToCues from "./parsers";
  * expected behavior to display subtitles synchronized to the video.
  * @class NativeTextSegmentBuffer
  */
-export default class NativeTextSegmentBuffer
-  extends SegmentBuffer<ITextTrackSegmentData>
-{
+export default class NativeTextSegmentBuffer extends SegmentBuffer {
   public readonly bufferType : "text";
 
   private readonly _videoElement : HTMLMediaElement;
   private readonly _track : ICompatTextTrack;
-  private readonly _trackElement? : HTMLTrackElement;
+  private readonly _trackElement : HTMLTrackElement | undefined;
 
   private _buffered : ManualTimeRanges;
 
@@ -77,7 +75,7 @@ export default class NativeTextSegmentBuffer
    * @param {Object} infos
    * @returns {Observable}
    */
-  public pushChunk(infos : IPushChunkInfos<ITextTrackSegmentData>) : Observable<void> {
+  public pushChunk(infos : IPushChunkInfos<unknown>) : Observable<void> {
     return observableDefer(() => {
       log.debug("NTSB: Appending new native text tracks");
       if (infos.data.chunk === null) {
@@ -86,6 +84,7 @@ export default class NativeTextSegmentBuffer
       const { timestampOffset,
               appendWindow,
               chunk } = infos.data;
+      assertChunkIsTextTrackSegmentData(chunk);
       const { start: startTime,
               end: endTime,
               data: dataString,
@@ -207,7 +206,7 @@ export default class NativeTextSegmentBuffer
    */
   public endOfSegment(_infos : IEndOfSegmentInfos) : Observable<void> {
     return observableDefer(() => {
-      this._segmentInventory.completeSegment(_infos);
+      this._segmentInventory.completeSegment(_infos, this._buffered);
       return observableOf(undefined);
     });
   }
@@ -257,3 +256,80 @@ export default class NativeTextSegmentBuffer
     this._buffered.remove(start, end);
   }
 }
+
+/** Data of chunks that should be pushed to the NativeTextSegmentBuffer. */
+export interface INativeTextTracksBufferSegmentData {
+  /** The text track data, in the format indicated in `type`. */
+  data : string;
+  /** The format of `data` (examples: "ttml", "srt" or "vtt") */
+  type : string;
+  /**
+   * Language in which the text track is, as a language code.
+   * This is mostly needed for "sami" subtitles, to know which cues can / should
+   * be parsed.
+   */
+  language? : string | undefined;
+  /** start time from which the segment apply, in seconds. */
+  start? : number | undefined;
+  /** end time until which the segment apply, in seconds. */
+  end? : number | undefined;
+}
+
+/**
+ * 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} chunk
+ */
+function assertChunkIsTextTrackSegmentData(
+  chunk : unknown
+) : asserts chunk is INativeTextTracksBufferSegmentData {
+  if (__ENVIRONMENT__.CURRENT_ENV === __ENVIRONMENT__.PRODUCTION as number) {
+    return;
+  }
+  if (
+    typeof chunk !== "object" ||
+    chunk === null ||
+    typeof (chunk as INativeTextTracksBufferSegmentData).data !== "string" ||
+    typeof (chunk as INativeTextTracksBufferSegmentData).type !== "string" ||
+    (
+      (chunk as INativeTextTracksBufferSegmentData).language !== undefined &&
+      typeof (chunk as INativeTextTracksBufferSegmentData).language !== "string"
+    ) ||
+    (
+      (chunk as INativeTextTracksBufferSegmentData).start !== undefined &&
+      typeof (chunk as INativeTextTracksBufferSegmentData).start !== "number"
+    ) ||
+    (
+      (chunk as INativeTextTracksBufferSegmentData).end !== undefined &&
+      typeof (chunk as INativeTextTracksBufferSegmentData).end !== "number"
+    )
+  ) {
+    throw new Error("Invalid format given to a NativeTextSegmentBuffer");
+  }
+}
+
+/*
+ * The following ugly code is here to provide a compile-time check that an
+ * `INativeTextTracksBufferSegmentData` (type of data pushed to a
+ * `NativeTextSegmentBuffer`) can be derived from a `ITextTrackSegmentData`
+ * (text track data parsed from a segment).
+ *
+ * It doesn't correspond at all to real code that will be called. This is just
+ * a hack to tell TypeScript to perform that check.
+ */
+if (__ENVIRONMENT__.CURRENT_ENV === __ENVIRONMENT__.DEV as number) {
+  /* eslint-disable @typescript-eslint/no-unused-vars */
+  /* eslint-disable @typescript-eslint/ban-ts-comment */
+  // @ts-ignore
+  function _checkType(
+    input : ITextTrackSegmentData
+  ) : void {
+    function checkEqual(_arg : INativeTextTracksBufferSegmentData) : void {
+      /* nothing */
+    }
+    checkEqual(input);
+  }
+  /* eslint-enable @typescript-eslint/no-unused-vars */
+  /* eslint-enable @typescript-eslint/ban-ts-comment */
+}

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

@@ -23,8 +23,10 @@ import {
 } from "../../../manifest";
 import SegmentInventory, {
   IBufferedChunk,
+  IBufferedHistoryEntry,
+  IChunkContext,
   IInsertedChunkInfos,
-} from "../segment_inventory";
+} from "../inventory";
 
 /**
  * Class allowing to push segments and remove data to a buffer to be able
@@ -63,7 +65,7 @@ import SegmentInventory, {
  * If operations happens synchronously, this method will just return an empty
  * array.
  */
-export abstract class SegmentBuffer<T> {
+export abstract class SegmentBuffer {
   /** "Type" of the buffer (e.g. "audio", "video", "text", "image"). */
   public readonly abstract bufferType : IBufferType;
 
@@ -112,7 +114,7 @@ export abstract class SegmentBuffer<T> {
    * @param {Object} infos
    * @returns {Observable}
    */
-  public abstract pushChunk(infos : IPushChunkInfos<T>) : Observable<void>;
+  public abstract pushChunk(infos : IPushChunkInfos<unknown>) : Observable<void>;
 
   /**
    * Remove buffered data (added to the same FIFO queue than `pushChunk`).
@@ -171,11 +173,28 @@ export abstract class SegmentBuffer<T> {
    * processed)
    * @returns {Array.<Object>}
    */
-  public getPendingOperations() : Array<ISBOperation<T>> {
+  public getPendingOperations() : Array<ISBOperation<unknown>> {
     // Return no pending operation by default (for synchronous SegmentBuffers)
     return [];
   }
 
+  /**
+   * Returns a recent history of registered operations performed and event
+   * received linked to the segment given in argument.
+   *
+   * Not all operations and events are registered in the returned history.
+   * Please check the return type for more information on what is available.
+   *
+   * Note that history is short-lived for memory usage and performance reasons.
+   * You may not receive any information on operations that happened too long
+   * ago.
+   * @param {Object} context
+   * @returns {Array.<Object>}
+   */
+  public getSegmentHistory(context : IChunkContext) : IBufferedHistoryEntry[] {
+    return this._segmentInventory.getHistoryFor(context);
+  }
+
   /**
    * Dispose of the resources used by this AudioVideoSegmentBuffer.
    * /!\ You won't be able to use the SegmentBuffer after calling this

package/src/core/segment_buffers/implementations/utils/manual_time_ranges.ts

@@ -39,7 +39,7 @@ export default class ManualTimeRanges implements TimeRanges {
   }
 
   insert(start : number, end : number) : void {
-    if (__DEV__) {
+    if (__ENVIRONMENT__.CURRENT_ENV === __ENVIRONMENT__.DEV as number) {
       assert(start >= 0, "invalid start time");
       assert(end - start > 0, "invalid end time");
     }
@@ -48,7 +48,7 @@ export default class ManualTimeRanges implements TimeRanges {
   }
 
   remove(start : number, end : number) : void {
-    if (__DEV__) {
+    if (__ENVIRONMENT__.CURRENT_ENV === __ENVIRONMENT__.DEV as number) {
       assert(start >= 0, "invalid start time");
       assert(end - start > 0, "invalid end time");
     }

package/src/core/segment_buffers/index.ts

@@ -27,11 +27,14 @@ import {
   SegmentBuffer,
   SegmentBufferOperation,
 } from "./implementations";
+import {
+  IBufferedChunk,
+  IChunkContext,
+} from "./inventory";
 import SegmentBuffersStore, {
   ISegmentBufferOptions,
   ITextTrackSegmentBufferOptions,
 } from "./segment_buffers_store";
-import { IBufferedChunk } from "./segment_inventory";
 
 export default SegmentBuffersStore;
 export {
@@ -43,7 +46,9 @@ export {
   SegmentBuffer,
 
   IBufferType,
+
   IBufferedChunk,
+  IChunkContext,
 
   IPushChunkInfos,
   IPushedChunkData,

package/src/core/segment_buffers/inventory/buffered_history.ts

@@ -0,0 +1,127 @@
+/**
+ * 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 { areSameContent } from "../../../manifest";
+import { IChunkContext } from "./types";
+
+/**
+ * Entry of a `BufferedHistory`, added when the initial buffered range of a
+ * **full segment** (and not just of a sub-chunk of a segment like in some
+ * low-latency streaming usages) in the buffer becomes known.
+ */
+export interface IBufferedHistoryEntry {
+  /** `performance.now()` when the event happened. */
+  date : number;
+  /** Start time at which we observed that segment/chunk starts at, in seconds. */
+  bufferedStart : number;
+  /** *End time at which we observed that segment/chunk ends at, in seconds. */
+  bufferedEnd : number;
+  /** Content metadata linked to the segment, allowing to recognize it. */
+  context : IChunkContext;
+
+}
+
+/**
+ * Register a short-lived history of buffer information.
+ *
+ * This class can be useful to develop heuristics based on short-term buffer
+ * history, such as knowing the real start and end of a buffered segment once
+ * it has been pushed in a buffer.
+ *
+ * By storing in a history important recent actions and events, the
+ * `BufferedHistory` can help other RxPlayer modules detect and work-around
+ * unusual behavior.
+ *
+ * @class BufferedHistory
+ */
+export default class BufferedHistory {
+  /** Complete recent history in chronological order (from oldest to newest) */
+  private _history : IBufferedHistoryEntry[];
+  /** Maximum time a history entry should be retained. */
+  private _lifetime : number;
+  /** Maximum number of entries the `BufferedHistory`'s history should have. */
+  private _maxHistoryLength : number;
+
+  /**
+   * @param {number} lifetime - Maximum time a history entry should be retained.
+   * @param {number} maxHistoryLength - Maximum number of entries the history
+   * should have.
+   */
+  constructor(lifetime : number, maxHistoryLength : number) {
+    this._history = [];
+    this._lifetime = lifetime;
+    this._maxHistoryLength = maxHistoryLength;
+  }
+
+  /**
+   * Add an entry to the `BufferedHistory`'s history indicating the buffered
+   * range of a pushed segment.
+   *
+   * To call when the full range of a given segment becomes known.
+   *
+   * @param {Object} context
+   * @param {number} bufferedStart
+   * @param {number} bufferedEnd
+   */
+  public addBufferedSegment(
+    context : IChunkContext,
+    bufferedStart : number,
+    bufferedEnd : number
+  ) : void {
+    const now = performance.now();
+    this._history.push({ date: now,
+                         bufferedStart,
+                         bufferedEnd,
+                         context });
+    this._cleanHistory(now);
+
+  }
+  /**
+   * Returns all entries linked to the given segment.
+   * @param {Object} context
+   * @returns {Array.<Object>}
+   */
+  public getHistoryFor(
+    context : IChunkContext
+  ) : IBufferedHistoryEntry[] {
+    return this._history.filter(el => areSameContent(el.context, context));
+  }
+
+  /**
+   * If the current history does not satisfy `_lifetime` or `_maxHistoryLength`,
+   * clear older entries until it does.
+   * @param {number} now - Current `performance.now()` result.
+   */
+  private _cleanHistory(now : number) {
+    const historyEarliestLimit = now - this._lifetime;
+    let firstKeptIndex = 0;
+    for (const event of this._history) {
+      if (event.date < historyEarliestLimit) {
+        firstKeptIndex++;
+      } else {
+        break;
+      }
+    }
+    if (firstKeptIndex > 0) {
+      this._history = this._history.splice(firstKeptIndex);
+    }
+
+    if (this._history.length > this._maxHistoryLength) {
+      const toRemove = this._history.length - this._maxHistoryLength;
+      this._history = this._history.splice(toRemove);
+    }
+  }
+}

package/src/core/segment_buffers/inventory/index.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 SegmentInventory, {
+  IBufferedChunk,
+  IInsertedChunkInfos,
+} from "./segment_inventory";
+
+export default SegmentInventory;
+export {
+  IBufferedChunk,
+  IInsertedChunkInfos,
+};
+export { IBufferedHistoryEntry } from "./buffered_history";
+export { IChunkContext } from "./types";