[Proposal] [v4] Errors: Replace trackInfo prop by tracksInfo to group similar errors

doc/api/Player_Errors.md

@@ -99,7 +99,8 @@ parsing) or from the browser itself (content playback).
 They all have a `type` property equal to `"MEDIA_ERROR"`.
 
 Depending on its `code` property (listed below), a `MEDIA_ERROR` may also have
-a supplementary `trackInfo` property, describing the track related to the issue.
+a supplementary `tracksInfo` property, describing the track(s) related to the
+issue.
 The format of that property is decribed in the chapter below listed codes, and
 the codes for which it is set are indicated in the corresponding code's
 description below.
@@ -111,27 +112,27 @@ An error of `type` `MEDIA_ERROR` can have the following codes (`code` property):
 - `"BUFFER_APPEND_ERROR"`: A media segment could not have been added to the
   corresponding media buffer. This often happens with malformed segments.
 
-  For those errors, you may be able to know the characteristics of the track
-  linked to that segment by inspecting the error's `trackInfo` property,
+  For those errors, you may be able to know the characteristics of the track(s)
+  linked to that segment by inspecting the error's `tracksInfo` property,
   described below.
 
 - `"BUFFER_FULL_ERROR"`: The needed segment could not have been added
   because the corresponding media buffer was full.
 
-  For those errors, you may be able to know the characteristics of the track
-  linked to that segment by inspecting the error's `trackInfo` property,
+  For those errors, you may be able to know the characteristics of the track(s)
+  linked to that segment by inspecting the error's `tracksInfo` property,
   described below.
 
 - `"BUFFER_TYPE_UNKNOWN"`: The type of buffer considered (e.g. "audio" /
   "video" / "text") has no media buffer implementation in your build.
 
-- `"MANIFEST_INCOMPATIBLE_CODECS_ERROR"`: An
-  [Adaptation](../Getting_Started/Glossary.md#adaptation) (or track) has none of its
-  [Representations](../Getting_Started/Glossary.md#representation) (read quality) in a supported
-  codec.
+- `"MANIFEST_INCOMPATIBLE_CODECS_ERROR"`: One or multiple
+  [Adaptation](../Getting_Started/Glossary.md#adaptation) (or track) parsed from
+  the Manifest has none of its [Representations](../Getting_Started/Glossary.md#representation)
+  (read: quality) in a supported codec.
 
-  For those errors, you may be able to know the characteristics of the track
-  linked to that codec by inspecting the error's `trackInfo` property, described below.
+  For those errors, you may be able to know the characteristics of the track(s)
+  linked to that codec by inspecting the error's `tracksInfo` property, described below.
 
 - `"MANIFEST_PARSE_ERROR"`: Generic error to signal than the
   [Manifest](../Getting_Started/Glossary.md#structure_of_a_manifest_object) could not be parsed.
@@ -206,8 +207,8 @@ An error of `type` `MEDIA_ERROR` can have the following codes (`code` property):
   Representation has been blacklisted due to encryption limitations.
 
   For those errors, you may be able to know the characteristics of the
-  corresponding track by inspecting the error's `trackInfo` property, described
-  below.
+  corresponding track(s) by inspecting the error's `tracksInfo` property,
+  described below.
 
 - `"MANIFEST_UPDATE_ERROR"`: This error should never be emitted as it is
   handled internally by the RxPlayer. Please open an issue if you encounter
@@ -223,31 +224,37 @@ An error of `type` `MEDIA_ERROR` can have the following codes (`code` property):
   It is triggered when a time we initially thought to be in the bounds of the
   Manifest actually does not link to any "Period" of the Manifest.
 
-#### `trackInfo` property
+#### `tracksInfo` property
 
 As described in the corresponding code's documentation, A aupplementary
-`trackInfo` property may be set on `MEDIA_ERROR` depending on its `code`
+`tracksInfo` property may be set on `MEDIA_ERROR` depending on its `code`
 property.
 
-Note that even if the code may be linked to a `trackInfo` property, that
+Note that even if the code may be linked to a `tracksInfo` property, that
 property may well also be unset.
 
-That `trackInfo` describes, when it makes sense, the characteristics of the track
-linked to an error. For example, you may want to know which video track led to a
+That `tracksInfo` describes, when it makes sense, the characteristics of the
+track(s) linked to an error.
+
+For example, you may want to know which video track led to a
 `BUFFER_APPEND_ERROR` and thus might be linked to corrupted segments.
 
-The `trackInfo` property has itself two sub-properties:
+The `tracksInfo` property is an array of objects, each describing a track for
+which that error applies (in many case, the error only applies to one track and
+thus there is only one object inside that array).
+
+Each object has two sub-properties:
 
   - `type`: The type of track: `"audio"` for an audio track, `"text"` for a text
     track, or `"video"` for a video track.
 
   - `track`: Characteristics of the track. Its format depends on the
-    `trackInfo`'s `type` property and is described below.
+    `type` property and is described below.
 
 ##### For video tracks
 
-When `trackInfo.type` is set to `"video"`, `track` describes a video track. It
-contains the following properties:
+When `tracksInfo[].type` is set to `"video"`, `track` describes a video track.
+It contains the following properties:
 
   - `id` (`string`): The id used to identify this track. No other
     video track for the same [Period](../Getting_Started/Glossary.md#period)
@@ -312,8 +319,8 @@ contains the following properties:
 
 ##### For audio tracks
 
-When `trackInfo.type` is set to `"audio"`, `track` describes an audio track. It
-contains the following properties:
+When `tracksInfo[].type` is set to `"audio"`, `track` describes an audio track.
+It contains the following properties:
 
 - `id` (`Number|string`): The id used to identify this track. No other
   audio track for the same [Period](../Getting_Started/Glossary.md#period)
@@ -366,7 +373,7 @@ contains the following properties:
 
 ##### For text tracks
 
-When `trackInfo.type` is set to `"text"`, `track` describes a text track. It
+When `tracksInfo[].type` is set to `"text"`, `track` describes a text track. It
 contains the following properties:
 
 - `id` (`string`): The id used to identify this track. No other

src/core/api/track_management/tracks_store.ts

@@ -348,7 +348,7 @@ export default class TracksStore extends EventEmitter<ITracksStoreEvents> {
       if (nextAdaptation === undefined) {
         const noRepErr = new MediaError("NO_PLAYABLE_REPRESENTATION",
                                         `No ${bufferType} Representation can be played`,
-                                        { adaptation: undefined });
+                                        { adaptations: undefined });
         this.trigger("error", noRepErr);
         this.dispose();
         return;

src/core/fetchers/manifest/manifest_fetcher.ts

@@ -302,10 +302,10 @@ export default class ManifestFetcher extends EventEmitter<IManifestFetcherEvent>
                                                 cancelSignal,
                                                 scheduleRequest);
       if (!isPromise(res)) {
-        return finish(res.manifest);
+        return finish(res.manifest, res.warnings);
       } else {
-        const { manifest } = await res;
-        return finish(manifest);
+        const { manifest, warnings } = await res;
+        return finish(manifest, warnings);
       }
     } catch (err) {
       const formattedError = formatError(err, {
@@ -356,8 +356,11 @@ export default class ManifestFetcher extends EventEmitter<IManifestFetcherEvent>
      * To call once the Manifest has been parsed.
      * @param {Object} manifest
      */
-    function finish(manifest : Manifest) : IManifestFetcherParsedResult {
-      onWarnings(manifest.contentWarnings);
+    function finish(
+      manifest : Manifest,
+      warnings: IPlayerError[]
+    ) : IManifestFetcherParsedResult {
+      onWarnings(warnings);
       const parsingTime = performance.now() - parsingTimeStart;
       log.info(`MF: Manifest parsed in ${parsingTime}ms`);
 

src/core/stream/period/period_stream.ts

@@ -411,7 +411,7 @@ function getFirstDeclaredMimeType(adaptation : Adaptation) : string {
     const noRepErr = new MediaError("NO_PLAYABLE_REPRESENTATION",
                                     "No Representation in the chosen " +
                                     adaptation.type + " Adaptation can be played",
-                                    { adaptation });
+                                    { adaptations: [adaptation] });
     throw noRepErr;
   }
   return representations[0].getMimeTypeString();

src/core/stream/representation/utils/append_segment_to_buffer.ts

@@ -58,7 +58,7 @@ export default async function appendSegmentToBuffer<T>(
         "An unknown error happened when pushing content";
       throw new MediaError("BUFFER_APPEND_ERROR",
                            reason,
-                           { adaptation: dataInfos.inventoryInfos.adaptation });
+                           { adaptations: [dataInfos.inventoryInfos.adaptation] });
     }
     const { position } = playbackObserver.getReference().getValue();
     const currentPos = position.pending ?? position.last;
@@ -71,7 +71,7 @@ export default async function appendSegmentToBuffer<T>(
 
       throw new MediaError("BUFFER_FULL_ERROR",
                            reason,
-                           { adaptation: dataInfos.inventoryInfos.adaptation });
+                           { adaptations: [dataInfos.inventoryInfos.adaptation] });
     }
   }
 }

src/errors/media_error.ts

@@ -61,7 +61,7 @@ export default class MediaError extends Error {
   public readonly type : "MEDIA_ERROR";
   public readonly message : string;
   public readonly code : IMediaErrorCode;
-  public readonly trackInfo : IMediaErrorTrackContext | undefined;
+  public readonly tracksInfo : IMediaErrorTrackContext[] | undefined;
   public fatal : boolean;
 
   /**
@@ -73,7 +73,7 @@ export default class MediaError extends Error {
     code : ICodeWithAdaptationType,
     reason : string,
     context: {
-      adaptation : Adaptation | undefined;
+      adaptations : Adaptation[] | undefined;
     }
   );
   constructor(
@@ -84,7 +84,7 @@ export default class MediaError extends Error {
     code : IMediaErrorCode,
     reason : string,
     context? : {
-      adaptation? : Adaptation | undefined;
+      adaptations? : Adaptation[] | undefined;
     } | undefined
   ) {
     super();
@@ -97,22 +97,28 @@ export default class MediaError extends Error {
     this.code = code;
     this.message = errorMessage(this.name, this.code, reason);
     this.fatal = false;
-    const adaptation = context?.adaptation;
-    if (adaptation !== undefined) {
-      switch (adaptation.type) {
-        case "audio":
-          this.trackInfo = { type: "audio",
-                             track: adaptation.toAudioTrack(false) };
-          break;
-        case "video":
-          this.trackInfo = { type: "video",
-                             track: adaptation.toVideoTrack(false) };
-          break;
-        case "text":
-          this.trackInfo = { type: "text",
-                             track: adaptation.toTextTrack() };
-          break;
-      }
+    const adaptations = context?.adaptations;
+    if (adaptations !== undefined && adaptations.length > 0) {
+      this.tracksInfo = adaptations.reduce((
+        acc: IMediaErrorTrackContext[],
+        adaptation: Adaptation
+      ) => {
+        switch (adaptation.type) {
+          case "audio":
+            acc.push({ type: "audio",
+                       track: adaptation.toAudioTrack(false) });
+            break;
+          case "video":
+            acc.push({ type: "video",
+                       track: adaptation.toVideoTrack(false) });
+            break;
+          case "text":
+            acc.push({ type: "text",
+                       track: adaptation.toTextTrack() });
+            break;
+        }
+        return acc;
+      }, []);
     }
   }
 }