Replace Representation deprecation mechanism by Representation avoidance

src/core/main/common/FreezeResolver.ts

@@ -17,8 +17,8 @@ import type { IBufferedChunk } from "../../segment_sinks";
  * In that case, the recommendation is to avoid playing those
  * `Representation` at all.
  */
-export interface IRepresentationDeprecationFreezeResolution {
-  type: "deprecate-representations";
+export interface IRepresentationAvoidanceFreezeResolution {
+  type: "avoid-representations";
   /** The `Representation` to avoid. */
   value: Array<{
     adaptation: IAdaptation;
@@ -59,7 +59,7 @@ export interface IReloadFreezeResolution {
 
 /** Describe a strategy that can be taken to un-freeze playback. */
 export type IFreezeResolution =
-  | IRepresentationDeprecationFreezeResolution
+  | IRepresentationAvoidanceFreezeResolution
   | IFlushFreezeResolution
   | IReloadFreezeResolution;
 
@@ -319,8 +319,8 @@ export default class FreezeResolver {
       "FR: A recent flush seemed to have no effect on freeze, checking for transitions",
     );
 
-    /** Contains Representation we might want to deprecate after the following algorithm */
-    const toDeprecate = [];
+    /** Contains Representation we might want to avoid after the following algorithm */
+    const toAvoid = [];
 
     for (const ttype of ["audio", "video"] as const) {
       const segmentList = this._lastSegmentInfo[ttype];
@@ -383,9 +383,9 @@ export default class FreezeResolver {
         previousRepresentationEntry.segment === null
       ) {
         log.debug(
-          "FR: Freeze when beginning to play a content, try deprecating this quality",
+          "FR: Freeze when beginning to play a content, try avoiding this quality",
         );
-        toDeprecate.push({
+        toAvoid.push({
           adaptation: currentSegment.infos.adaptation,
           period: currentSegment.infos.period,
           representation: currentSegment.infos.representation,
@@ -401,19 +401,19 @@ export default class FreezeResolver {
         previousRepresentationEntry.segment.infos.representation.uniqueId
       ) {
         log.warn(
-          "FR: Freeze when switching Representation, deprecating",
+          "FR: Freeze when switching Representation, avoiding",
           currentSegment.infos.representation.bitrate,
         );
-        toDeprecate.push({
+        toAvoid.push({
           adaptation: currentSegment.infos.adaptation,
           period: currentSegment.infos.period,
           representation: currentSegment.infos.representation,
         });
       }
     }
 
-    if (toDeprecate.length > 0) {
-      return { type: "deprecate-representations", value: toDeprecate };
+    if (toAvoid.length > 0) {
+      return { type: "avoid-representations", value: toAvoid };
     } else {
       log.debug("FR: Reloading because flush doesn't work");
       return { type: "reload", value: null };

src/core/main/worker/content_preparer.ts

@@ -84,13 +84,8 @@ export default class ContentPreparer {
 
       currentMediaSourceCanceller.linkToSignal(contentCanceller.signal);
 
-      const {
-        contentId,
-        url,
-        hasText,
-        transportOptions,
-        enableRepresentationDeprecation,
-      } = context;
+      const { contentId, url, hasText, transportOptions, enableRepresentationAvoidance } =
+        context;
       let manifest: IManifest | null = null;
 
       // TODO better way
@@ -158,7 +153,7 @@ export default class ContentPreparer {
       this._currentContent = {
         cmcdDataBuilder,
         contentId,
-        enableRepresentationDeprecation,
+        enableRepresentationAvoidance,
         freezeResolver,
         mediaSource,
         manifest: null,
@@ -335,11 +330,11 @@ export interface IPreparedContentData {
    */
   cmcdDataBuilder: CmcdDataBuilder | null;
   /**
-   * If `true`, the RxPlayer can enable its "Representation deprecation"
+   * If `true`, the RxPlayer can enable its "Representation avoidance"
    * mechanism, where it avoid loading Representation that it suspect
    * have issues being decoded on the current device.
    */
-  enableRepresentationDeprecation: boolean;
+  enableRepresentationAvoidance: boolean;
   /**
    * Interface to the MediaSource implementation, allowing to buffer audio
    * and video media segments.

src/core/main/worker/worker_main.ts

@@ -518,7 +518,7 @@ function loadOrReloadPreparedContent(
   const {
     contentId,
     cmcdDataBuilder,
-    enableRepresentationDeprecation,
+    enableRepresentationAvoidance,
     manifest,
     mediaSource,
     representationEstimator,
@@ -561,11 +561,11 @@ function loadOrReloadPreparedContent(
             });
             break;
           }
-          case "deprecate-representations": {
-            log.info("WP: Planning Representation deprecation due to freeze");
+          case "avoid-representations": {
+            log.info("WP: Planning Representation avoidance due to freeze");
             const content = freezeResolution.value;
-            if (enableRepresentationDeprecation) {
-              manifest.deprecateRepresentations(content);
+            if (enableRepresentationAvoidance) {
+              manifest.addRepresentationsToAvoid(content);
             }
             handleMediaSourceReload({
               timeOffset: 0,

src/core/stream/adaptation/adaptation_stream.ts

@@ -161,7 +161,7 @@ export default function AdaptationStream(
 
       // NOTE: We expect that the rest of the RxPlayer code is already handling
       // cases where the list of playable `Representation` changes:
-      // decipherability updates, `Representation` deprecation etc.
+      // decipherability updates, "`Representation` avoidance" etc.
       const newRepresentations = getRepresentationList(
         content.adaptation.representations,
         newRepIds,
@@ -547,13 +547,13 @@ function getRepresentationList(
     (r) =>
       arrayIncludes(authorizedRepIds, r.id) &&
       r.decipherable !== false &&
-      !r.deprecated &&
+      !r.shouldBeAvoided &&
       r.isSupported !== false,
   );
   if (filteredRepresentations.length > 0) {
     return filteredRepresentations;
   }
-  // Retry without deprecated `Representation`
+  // Retry without "`Representation` avoidance"
   return availableRepresentations.filter(
     (r) =>
       arrayIncludes(authorizedRepIds, r.id) &&

src/main_thread/api/option_utils.ts

@@ -112,7 +112,7 @@ interface IParsedLoadVideoOptionsBase {
   cmcd: ICmcdOptions | undefined;
   /** @see ILoadVideoOptions.experimentalOptions */
   experimentalOptions: {
-    enableRepresentationDeprecation: boolean;
+    enableRepresentationAvoidance: boolean;
   };
   __priv_manifestUpdateUrl?: string | undefined;
   __priv_patchLastSegmentInSidx?: boolean | undefined;
@@ -488,8 +488,8 @@ function parseLoadVideoOptions(options: ILoadVideoOptions): IParsedLoadVideoOpti
     url,
     cmcd: options.cmcd,
     experimentalOptions: {
-      enableRepresentationDeprecation:
-        options.experimentalOptions?.enableRepresentationDeprecation === true,
+      enableRepresentationAvoidance:
+        options.experimentalOptions?.enableRepresentationAvoidance === true,
     },
   };
 }

src/main_thread/api/public_api.ts

@@ -936,8 +936,8 @@ class Player extends EventEmitter<IPublicAPIEvent> {
           autoPlay,
           bufferOptions,
           cmcd,
-          enableRepresentationDeprecation:
-            experimentalOptions.enableRepresentationDeprecation,
+          enableRepresentationAvoidance:
+            experimentalOptions.enableRepresentationAvoidance,
           keySystems,
           lowLatencyMode,
           transport: transportPipelines,
@@ -980,8 +980,8 @@ class Player extends EventEmitter<IPublicAPIEvent> {
           autoPlay,
           bufferOptions,
           cmcd,
-          enableRepresentationDeprecation:
-            experimentalOptions.enableRepresentationDeprecation,
+          enableRepresentationAvoidance:
+            experimentalOptions.enableRepresentationAvoidance,
           keySystems,
           lowLatencyMode,
           transportOptions,

src/main_thread/init/media_source_content_initializer.ts

@@ -730,10 +730,10 @@ export default class MediaSourceContentInitializer extends ContentInitializer {
             playbackObserver.setCurrentTime(wantedSeekingTime);
             break;
           }
-          case "deprecate-representations": {
+          case "avoid-representations": {
             const contents = freezeResolution.value;
-            if (this._initSettings.enableRepresentationDeprecation) {
-              manifest.deprecateRepresentations(contents);
+            if (this._initSettings.enableRepresentationAvoidance) {
+              manifest.addRepresentationsToAvoid(contents);
             }
             triggerReload();
             break;
@@ -1212,11 +1212,11 @@ export interface IInitializeArguments {
    */
   cmcd?: ICmcdOptions | undefined;
   /**
-   * If `true`, the RxPlayer can enable its "Representation deprecation"
+   * If `true`, the RxPlayer can enable its "Representation avoidance"
    * mechanism, where it avoid loading Representation that it suspect
    * have issues being decoded on the current device.
    */
-  enableRepresentationDeprecation: boolean;
+  enableRepresentationAvoidance: boolean;
   /** Every encryption configuration set. */
   keySystems: IKeySystemOption[];
   /** `true` to play low-latency contents optimally. */

src/main_thread/init/multi_thread_content_initializer.ts

@@ -170,7 +170,7 @@ export default class MultiThreadContentInitializer extends ContentInitializer {
       value: {
         contentId,
         cmcd: this._settings.cmcd,
-        enableRepresentationDeprecation: this._settings.enableRepresentationDeprecation,
+        enableRepresentationAvoidance: this._settings.enableRepresentationAvoidance,
         url: this._settings.url,
         hasText: this._hasTextBufferFeature(),
         transportOptions,
@@ -1897,11 +1897,11 @@ export interface IInitializeArguments {
    */
   cmcd?: ICmcdOptions | undefined;
   /**
-   * If `true`, the RxPlayer can enable its "Representation deprecation"
+   * If `true`, the RxPlayer can enable its "Representation avoidance"
    * mechanism, where it avoid loading Representation that it suspect
    * have issues being decoded on the current device.
    */
-  enableRepresentationDeprecation: boolean;
+  enableRepresentationAvoidance: boolean;
   /** Every encryption configuration set. */
   keySystems: IKeySystemOption[];
   /** `true` to play low-latency contents optimally. */

src/manifest/classes/manifest.ts

@@ -79,10 +79,10 @@ export interface IManifestEvents {
   /** Some Representation's support status has been updated */
   supportUpdate: null;
   /**
-   * Some `Representation` have been "deprecated", meaning we should avoid
-   * playing them.
+   * Some `Representation`'s avoidance status has been updated, meaning that we
+   * might have to avoid playing them due to playback issues.
    */
-  deprecationUpdate: IUpdatedRepresentationInfo[];
+  representationAvoidanceUpdate: IUpdatedRepresentationInfo[];
 }
 
 /**
@@ -547,11 +547,11 @@ export default class Manifest
   }
 
   /**
-   * Mark some `Representation` as being "deprecated", meaning we should not
-   * attempt to load it anymore, unless forced.
+   * Indicate that some `Representation` needs to be avoided due to playback
+   * issues.
    * @param {Array.<Object>} items
    */
-  public deprecateRepresentations(
+  public addRepresentationsToAvoid(
     items: Array<{
       period: Period;
       adaptation: Adaptation;
@@ -572,7 +572,7 @@ export default class Manifest
       if (representation === undefined) {
         continue;
       }
-      representation.deprecated = true;
+      representation.shouldBeAvoided = true;
       updates.push({
         manifest: this,
         period,
@@ -581,7 +581,7 @@ export default class Manifest
       });
     }
     if (updates.length > 0) {
-      this.trigger("deprecationUpdate", updates);
+      this.trigger("representationAvoidanceUpdate", updates);
     }
   }
 

src/manifest/classes/representation.ts

@@ -120,7 +120,7 @@ class Representation implements IRepresentationMetadata {
    * instanciated `Representation`, you are supposed to rely on
    * `Manifest` methods for this.
    */
-  public deprecated: boolean;
+  public shouldBeAvoided: boolean;
 
   /**
    * @param {Object} args
@@ -133,7 +133,7 @@ class Representation implements IRepresentationMetadata {
   ) {
     this.id = args.id;
     this.uniqueId = generateRepresentationUniqueId();
-    this.deprecated = false;
+    this.shouldBeAvoided = false;
     this.bitrate = args.bitrate;
     this.codecs = [];
     this.trackType = trackType;

src/multithread_types.ts

@@ -109,11 +109,11 @@ export interface IContentInitializationData {
    */
   cmcd?: ICmcdOptions | undefined;
   /**
-   * If `true`, the RxPlayer can enable its "Representation deprecation"
+   * If `true`, the RxPlayer can enable its "Representation avoidance"
    * mechanism, where it avoid loading Representation that it suspect
    * have issues being decoded on the current device.
    */
-  enableRepresentationDeprecation: boolean;
+  enableRepresentationAvoidance: boolean;
   /**
    * URL at which the content's Manifest is accessible.
    * `undefined` if unknown.

src/public_types.ts

@@ -192,11 +192,11 @@ export interface ILoadVideoOptions {
   experimentalOptions?:
     | {
         /**
-         * If `true`, the RxPlayer can enable its "Representation deprecation"
+         * If `true`, the RxPlayer can enable its "Representation avoidance"
          * mechanism, where it avoid loading Representation that it suspect
          * have issues being decoded on the current device.
          */
-        enableRepresentationDeprecation: boolean | undefined;
+        enableRepresentationAvoidance: boolean | undefined;
       }
     | undefined;
 }