rx-player 3.28.0 → 3.28.1-dev.2022083000

package/src/errors/encrypted_media_error.ts

@@ -28,7 +28,7 @@ import errorMessage from "./error_message";
  */
 export default class EncryptedMediaError extends Error {
   public readonly name : "EncryptedMediaError";
-  public readonly type : string;
+  public readonly type : "ENCRYPTED_MEDIA_ERROR";
   public readonly code : IEncryptedMediaErrorCode;
   public message : string;
   public fatal : boolean;
@@ -36,7 +36,6 @@ export default class EncryptedMediaError extends Error {
   /**
    * @param {string} code
    * @param {string} reason
-   * @Param {Boolean} fatal
    */
   constructor(code : IEncryptedMediaErrorCode, reason : string) {
     super();

package/src/errors/error_codes.ts

@@ -74,12 +74,12 @@ export type INetworkErrorType = "TIMEOUT" |
                                 "PARSE_ERROR" |
                                 "ERROR_HTTP_CODE";
 
-const ErrorTypes : Record<IErrorType, IErrorType> = {
+const ErrorTypes = {
   NETWORK_ERROR: "NETWORK_ERROR",
   MEDIA_ERROR: "MEDIA_ERROR",
   ENCRYPTED_MEDIA_ERROR: "ENCRYPTED_MEDIA_ERROR",
   OTHER_ERROR: "OTHER_ERROR",
-};
+} as const;
 
 const NetworkErrorTypes : Record<INetworkErrorType, INetworkErrorType> = {
   TIMEOUT: "TIMEOUT",

package/src/errors/media_error.ts

@@ -28,7 +28,7 @@ import errorMessage from "./error_message";
  */
 export default class MediaError extends Error {
   public readonly name : "MediaError";
-  public readonly type : string;
+  public readonly type : "MEDIA_ERROR";
   public readonly message : string;
   public readonly code : IMediaErrorCode;
   public fatal : boolean;
@@ -36,7 +36,6 @@ export default class MediaError extends Error {
   /**
    * @param {string} code
    * @param {string} reason
-   * @param {Boolean} fatal
    */
   constructor(code : IMediaErrorCode, reason : string) {
     super();

package/src/errors/network_error.ts

@@ -31,7 +31,7 @@ import RequestError from "./request_error";
  */
 export default class NetworkError extends Error {
   public readonly name : "NetworkError";
-  public readonly type : string;
+  public readonly type : "NETWORK_ERROR";
   public readonly message : string;
   public readonly code : INetworkErrorCode;
   public readonly xhr : XMLHttpRequest | null;
@@ -43,7 +43,6 @@ export default class NetworkError extends Error {
   /**
    * @param {string} code
    * @param {Error} baseError
-   * @param {Boolean} fatal
    */
   constructor(code : INetworkErrorCode, baseError : RequestError) {
     super();

package/src/errors/other_error.ts

@@ -26,7 +26,7 @@ import errorMessage from "./error_message";
  */
 export default class OtherError extends Error {
   public readonly name : "OtherError";
-  public readonly type : string;
+  public readonly type : "OTHER_ERROR";
   public readonly message : string;
   public readonly code : IOtherErrorCode;
   public fatal : boolean;
@@ -34,7 +34,6 @@ export default class OtherError extends Error {
   /**
    * @param {string} code
    * @param {string} reason
-   * @param {Boolean} fatal
    */
   constructor(code : IOtherErrorCode, reason : string) {
     super();

package/src/manifest/__tests__/adaptation.test.ts

@@ -28,13 +28,14 @@ const minimalRepresentationIndex = {
   getInitSegment() { return null; },
   getSegments() { return []; },
   shouldRefresh() { return false; },
-  getFirstPosition() : undefined { return ; },
-  getLastPosition() : undefined { return ; },
+  getFirstAvailablePosition() : undefined { return ; },
+  getLastAvailablePosition() : undefined { return ; },
+  getEnd() : undefined { return ; },
   checkDiscontinuity() { return null; },
   isSegmentStillAvailable() : undefined { return ; },
   canBeOutOfSyncError() : true { return true; },
   isFinished() : true { return true; },
-  areSegmentsChronologicallyGenerated() { return true; },
+  awaitSegmentBetween() : undefined { return ; },
   _replace() { /* noop */ },
   _update() { /* noop */ },
 };

package/src/manifest/__tests__/representation.test.ts

@@ -24,10 +24,11 @@
 const minimalIndex = { getInitSegment() { return null; },
                        getSegments() { return []; },
                        shouldRefresh() { return false; },
-                       getFirstPosition() : undefined { return ; },
-                       getLastPosition() : undefined { return ; },
+                       getFirstAvailablePosition() : undefined { return ; },
+                       getLastAvailablePosition() : undefined { return ; },
+                       getEnd() : undefined { return ; },
+                       awaitSegmentBetween() : undefined { return ; },
                        checkDiscontinuity() { return null; },
-                       areSegmentsChronologicallyGenerated() { return true; },
                        isSegmentStillAvailable() : undefined { return ; },
                        canBeOutOfSyncError() : true { return true; },
                        isFinished() : true { return true; },

package/src/manifest/manifest.ts

@@ -537,7 +537,7 @@ export default class Manifest extends EventEmitter<IManifestEvents> {
    * and mark them as being impossible to decrypt.
    * Then trigger a "decipherabilityUpdate" event to notify everyone of the
    * changes performed.
-   * @param {Object} keyUpdates
+   * @param {Function} isDecipherableCb
    */
   public updateRepresentationsDeciperability(
     isDecipherableCb : (rep : Representation) => boolean | undefined

package/src/manifest/representation_index/__tests__/static.test.ts

@@ -33,17 +33,18 @@ describe("manifest - StaticRepresentationIndex", () => {
                                               duration: Number.MAX_VALUE,
                                               end: Number.MAX_VALUE,
                                               timescale: 1,
+                                              privateInfos: {},
                                               mediaURLs: ["foo"] }]);
   });
 
   it("should return no first position", () => {
     const staticRI = new StaticRepresentationIndex({ media: "foo" });
-    expect(staticRI.getFirstPosition()).toBe(undefined);
+    expect(staticRI.getFirstAvailablePosition()).toBe(undefined);
   });
 
   it("should return no last position", () => {
     const staticRI = new StaticRepresentationIndex({ media: "foo" });
-    expect(staticRI.getLastPosition()).toBe(undefined);
+    expect(staticRI.getLastAvailablePosition()).toBe(undefined);
   });
 
   it("should never be refreshed", () => {
@@ -56,9 +57,9 @@ describe("manifest - StaticRepresentationIndex", () => {
     expect(staticRI.checkDiscontinuity()).toBe(null);
   });
 
-  it("should always be chronologically generated", () => {
+  it("should never be awaiting segments", () => {
     const staticRI = new StaticRepresentationIndex({ media: "foo" });
-    expect(staticRI.areSegmentsChronologicallyGenerated()).toBe(true);
+    expect(staticRI.awaitSegmentBetween()).toBe(false);
   });
 
   it("should never replace and warn when trying to do so", () => {

package/src/manifest/representation_index/static.ts

@@ -59,6 +59,7 @@ export default class StaticRepresentationIndex implements IRepresentationIndex {
               end: Number.MAX_VALUE,
               duration: Number.MAX_VALUE,
               complete: true,
+              privateInfos: {},
               timescale: 1 }];
   }
 
@@ -66,7 +67,7 @@ export default class StaticRepresentationIndex implements IRepresentationIndex {
    * Returns first position in index.
    * @returns {undefined}
    */
-  getFirstPosition() : undefined {
+  getFirstAvailablePosition() : undefined {
     return ;
   }
 
@@ -74,10 +75,35 @@ export default class StaticRepresentationIndex implements IRepresentationIndex {
    * Returns last position in index.
    * @returns {undefined}
    */
-  getLastPosition() : undefined {
+  getLastAvailablePosition() : undefined {
     return ;
   }
 
+  /**
+   * Returns the absolute end in seconds this RepresentationIndex can reach once
+   * all segments are available.
+   * @returns {number|null|undefined}
+   */
+  getEnd() : undefined {
+    return;
+  }
+
+  /**
+   * Returns:
+   *   - `true` if in the given time interval, at least one new segment is
+   *     expected to be available in the future.
+   *   - `false` either if all segments in that time interval are already
+   *     available for download or if none will ever be available for it.
+   *   - `undefined` when it is not possible to tell.
+   *
+   * Always `false` in a `StaticRepresentationIndex` because all segments should
+   * be directly available.
+   * @returns {boolean}
+   */
+  awaitSegmentBetween(): false {
+    return false;
+  }
+
   /**
    * Returns false as a static file never need to be refreshed.
    * @returns {Boolean}
@@ -93,13 +119,6 @@ export default class StaticRepresentationIndex implements IRepresentationIndex {
     return null;
   }
 
-  /**
-   * @returns {boolean}
-   */
-  areSegmentsChronologicallyGenerated() : boolean {
-    return true;
-  }
-
   /**
    * Returns true as a static file should never need lose availability.
    * @returns {Boolean}

package/src/manifest/representation_index/types.ts

@@ -112,11 +112,28 @@ export interface ILocalManifestSegmentPrivateInfos {
  * exploited by the corresponding transport logic.
  */
 export interface IPrivateInfos {
+  /** Smooth-specific information allowing to generate an initialization segment. */
   smoothInitSegment? : ISmoothInitSegmentPrivateInfos | undefined;
+
+  /** Smooth-specific information linked to all Smooth media segments. */
   smoothMediaSegment? : ISmoothSegmentPrivateInfos | undefined;
+
+  /** Information that should be present on all MetaPlaylist segments. */
   metaplaylistInfos? : IMetaPlaylistPrivateInfos | undefined;
+
+  /**
+   * Local Manifest-specific information allowing to request the
+   * initialization segment.
+   */
   localManifestInitSegment? : ILocalManifestInitSegmentPrivateInfos | undefined;
+
+  /** Local Manifest-specific information allowing to request any media segment. */
   localManifestSegment? : ILocalManifestSegmentPrivateInfos | undefined;
+
+  /**
+   * Function allowing to know if a given emsg's event name has been
+   * explicitely authorized.
+   */
   isEMSGWhitelisted? : ((evt: IEMSG) => boolean) | undefined;
 }
 
@@ -142,26 +159,16 @@ export interface ISegment {
    * segments" in the code.
    */
   isInit : boolean;
-  /** URLs where this segment is available. From the most to least prioritary. */
-  mediaURLs : string[]|null;
-  /**
-   * If set, the corresponding byte-range in the downloaded segment will
-   * contain an index describing other Segments
-   * TODO put in privateInfos?
-   */
-  indexRange? : [number, number] | undefined;
   /**
-   * Optional number of the Segment
-   * TODO put in privateInfos?
+   * URLs where this segment is available. From the most to least prioritary.
+   * `null` if no URL exists.
    */
-  number? : number | undefined;
+  mediaURLs : string[]|null;
   /**
    * Allows to store supplementary information on a segment that can be later
    * exploited by the transport logic.
    */
-  privateInfos? : IPrivateInfos | undefined;
-  /** Optional byte range to retrieve the Segment from its URL(s) */
-  range? : [number, number] | undefined;
+  privateInfos : IPrivateInfos | undefined;
   /**
    * Estimated time, in seconds, at which the concerned segment should be
    * offseted when decoded.
@@ -213,7 +220,6 @@ export interface ISegment {
    * As both are always in seconds now, this property became unneeded.
    */
   timescale : 1;
-
   /**
    * If `false`, this segment's `duration` property may not be the duration of
    * the full segment as it could still be in the process of being generated
@@ -224,6 +230,31 @@ export interface ISegment {
    * generated.
    */
   complete : boolean;
+  /**
+   * Optional byte range to retrieve the Segment from its URL(s).
+   * TODO this should probably moved to `privateInfos` as this is
+   * transport-specific metadata only useful for performing requests, but it is
+   * sadly documented in the API, so moving it is actuall a v3.X.X breaking
+   * change.
+   */
+  range? : [number, number] | undefined;
+  /**
+   * If set, the corresponding byte-range in the downloaded segment will
+   * contain an index describing other Segments
+   * TODO this should probably moved to `privateInfos` as this is
+   * transport-specific metadata only useful for performing requests, but it is
+   * sadly documented in the API, so moving it is actuall a v3.X.X breaking
+   * change.
+   */
+  indexRange? : [number, number] | undefined;
+  /**
+   * Optional number of the Segment.
+   * TODO this should probably moved to `privateInfos` as this is
+   * transport-specific metadata only useful for performing requests, but it is
+   * sadly documented in the API, so moving it is actuall a v3.X.X breaking
+   * change.
+   */
+  number? : number | undefined;
 }
 
 /** Interface that should be implemented by any Representation's `index` value. */
@@ -265,7 +296,7 @@ export interface IRepresentationIndex {
    * Returns `undefined` if we cannot know this value.
    * @returns {Number|null}
    */
-  getFirstPosition() : number | null | undefined;
+  getFirstAvailablePosition() : number | null | undefined;
 
   /**
    * Returns the ending time, in seconds, of the last playable position
@@ -279,7 +310,19 @@ export interface IRepresentationIndex {
    * instead.
    * @returns {Number|null|undefined}
    */
-  getLastPosition() : number | null | undefined;
+  getLastAvailablePosition() : number | null | undefined;
+
+  /**
+   * Returns the ending time, in seconds, of the Representation once it is
+   * "finished" (@see isFinished).
+   * Should thus be equivalent to `getLastAvailablePosition` once finished.
+   *
+   * Returns `null` if nothing is in the index
+   * Returns `undefined` if we cannot know this value.
+   *
+   * @returns {number|undefined}
+   */
+  getEnd() : number | null | undefined;
 
   /**
    * Returns `true` if a Segment returned by this index is still considered
@@ -322,35 +365,6 @@ export interface IRepresentationIndex {
    */
   checkDiscontinuity(time : number) : number | null;
 
-  /**
-   * Most RepresentationIndex are linked to segments which are generated in
-   * chronological order: from an initial position (obtainable with
-   * `getFirstPosition`) to the last position of the corresponding Period
-   * (obtainable with `getLastPosition`).
-   *
-   * However, some RepresentationIndex could announce segments in a more random
-   * order.
-   * Examples of such RepresentationIndex are ones for contents which are being
-   * downloaded locally. Here a seek close to the end could schedule the
-   * download of the last segments immediately, which might thus be announced
-   * in this index before segments in the middle are.
-   *
-   * Knowing this value serves for example to check if a discontinuity
-   * encountered in the content can be skipped over, or if it's possible that
-   * this discontinuity is due to a segment not yet being generated.
-   *
-   * You should return `true` only if there is a chance that segments are not
-   * chronologically generated (even if they all have since been generated, this
-   * function is only to know if it's possible, not if it's the case now).
-   *
-   * In other most likely cases, you should return `false`.
-   *
-   * TODO find a better way with the "local" RepresentationIndex, like
-   * explicitely declaring which segments have not been downloaded yet.
-   * @returns {boolean}
-   */
-  areSegmentsChronologicallyGenerated() : boolean;
-
   /**
    * Returns `true` if the last segments in this index have already been
    * generated so that we can freely go to the next period.
@@ -382,6 +396,8 @@ export interface IRepresentationIndex {
    */
   isInitialized() : boolean;
 
+  awaitSegmentBetween(start : number, end : number) : boolean | undefined;
+
   /**
    * Replace the index with another one, such as after a Manifest update.
    * @param {Object} newIndex

package/src/parsers/manifest/dash/common/indexes/base.ts

@@ -274,7 +274,7 @@ export default class BaseRepresentationIndex implements IRepresentationIndex {
    * Returns first position in index.
    * @returns {Number|null}
    */
-  getFirstPosition() : number|null {
+  getFirstAvailablePosition() : number|null {
     const index = this._index;
     if (index.timeline.length === 0) {
       return null;
@@ -288,7 +288,7 @@ export default class BaseRepresentationIndex implements IRepresentationIndex {
    * Returns last position in index.
    * @returns {Number|null}
    */
-  getLastPosition() : number|null {
+  getLastAvailablePosition() : number|null {
     const { timeline } = this._index;
     if (timeline.length === 0) {
       return null;
@@ -301,6 +301,31 @@ export default class BaseRepresentationIndex implements IRepresentationIndex {
     return fromIndexTime(lastTime, this._index);
   }
 
+  /**
+   * Returns the absolute end in seconds this RepresentationIndex can reach once
+   * all segments are available.
+   * @returns {number|null|undefined}
+   */
+  getEnd(): number | null {
+    return this.getLastAvailablePosition();
+  }
+
+  /**
+   * Returns:
+   *   - `true` if in the given time interval, at least one new segment is
+   *     expected to be available in the future.
+   *   - `false` either if all segments in that time interval are already
+   *     available for download or if none will ever be available for it.
+   *   - `undefined` when it is not possible to tell.
+   *
+   * Always `false` in a `BaseRepresentationIndex` because all segments should
+   * be directly available.
+   * @returns {boolean}
+   */
+  awaitSegmentBetween(): false {
+    return false;
+  }
+
   /**
    * Segments in a segmentBase scheme should stay available.
    * @returns {Boolean|undefined}
@@ -317,15 +342,6 @@ export default class BaseRepresentationIndex implements IRepresentationIndex {
     return null;
   }
 
-  /**
-   * `BaseRepresentationIndex` should just already all be generated.
-   * Return `true` as a default value here.
-   * @returns {boolean}
-   */
-  areSegmentsChronologicallyGenerated() : true {
-    return true;
-  }
-
   /**
    * No segment in a `BaseRepresentationIndex` are known initially.
    * It is only defined generally in an "index segment" that will thus need to

package/src/parsers/manifest/dash/common/indexes/list.ts

@@ -60,7 +60,10 @@ export interface IListIndex {
   } | undefined;
   /** Information on the list of segments for this index. */
   list: Array<{
-    /** URLs of the segment. */
+    /**
+     * URLs of the segment.
+     * `null` if no URL exists.
+     */
     mediaURLs : string[] | null;
     /** Possible byte-range of the segment. */
     mediaRange? : [number, number] | undefined;
@@ -188,7 +191,7 @@ export default class ListRepresentationIndex implements IRepresentationIndex {
 
   /**
    * @param {Number} fromTime
-   * @param {Number} duration
+   * @param {Number} dur
    * @returns {Array.<Object>}
    */
   getSegments(fromTime : number, dur : number) : ISegment[] {
@@ -243,7 +246,7 @@ export default class ListRepresentationIndex implements IRepresentationIndex {
    * Returns first position in this index, in seconds.
    * @returns {Number}
    */
-  getFirstPosition() : number {
+  getFirstAvailablePosition() : number {
     return this._periodStart;
   }
 
@@ -251,17 +254,41 @@ export default class ListRepresentationIndex implements IRepresentationIndex {
    * Returns last position in this index, in seconds.
    * @returns {Number}
    */
-  getLastPosition() : number {
+  getLastAvailablePosition() : number {
     const index = this._index;
     const { duration, list } = index;
     return Math.min(((list.length * duration) / index.timescale) + this._periodStart,
                     this._periodEnd ?? Infinity);
   }
 
+  /**
+   * Returns the absolute end in seconds this RepresentationIndex can reach once
+   * all segments are available.
+   * @returns {number|null|undefined}
+   */
+  getEnd(): number | null {
+    return this.getLastAvailablePosition();
+  }
+
+  /**
+   * Returns:
+   *   - `true` if in the given time interval, at least one new segment is
+   *     expected to be available in the future.
+   *   - `false` either if all segments in that time interval are already
+   *     available for download or if none will ever be available for it.
+   *   - `undefined` when it is not possible to tell.
+   *
+   * Always `false` in a `ListRepresentationIndex` because all segments should
+   * be directly available.
+   * @returns {boolean}
+   */
+  awaitSegmentBetween(): false {
+    return false;
+  }
+
   /**
    * Returns true if a Segment returned by this index is still considered
    * available.
-   * @param {Object} segment
    * @returns {Boolean}
    */
   isSegmentStillAvailable() : true {
@@ -277,13 +304,6 @@ export default class ListRepresentationIndex implements IRepresentationIndex {
     return null;
   }
 
-  /**
-   * @returns {boolean}
-   */
-  areSegmentsChronologicallyGenerated() : boolean {
-    return true;
-  }
-
   /**
    * SegmentList should not be updated.
    * @returns {Boolean}
@@ -313,9 +333,6 @@ export default class ListRepresentationIndex implements IRepresentationIndex {
     this._index = newIndex._index;
   }
 
-  /**
-   * @param {Object} newIndex
-   */
   _update() : void {
     log.error("List RepresentationIndex: Cannot update a SegmentList");
   }