add support for Preselection element (Dash-Industry-Forum#4790)

* add support for Preselection element parsing and codecs string replacement

* address review comments

* one more fix from review

* unify getProperty functions

* adding id

* more updates to index.d.ts

* improve preselections capability check with MediaCapabilitiesAPI

* missing fix from last commit

* improve robustness

* rename settings element for preselection to MediaInfo mapping

* setting Preselection@id to the default value per spec

* move code to helper function

* remove currently unsed code

* remove declarations from index.d.ts, where respective items were removed from code

Author: stschr

contrib/akamai/controlbar/ControlBar.js

@@ -577,7 +577,7 @@ var ControlBar = function (dashjsMediaPlayer, displayUTCTimeCodes) {
                     var info = '';
 
                     if (element.lang) {
-                        info += 'Language - ' + element.lang + ' ';
+                        info += 'Language: ' + element.lang + ' ';
                     }
 
                     if (element.roles && element.roles.length > 0) {
@@ -596,6 +596,10 @@ var ControlBar = function (dashjsMediaPlayer, displayUTCTimeCodes) {
                         info += '- Id: ' + element.id + ' ';
                     }
 
+                    if (element.isPreselection) {
+                        info += '- Preselection';
+                    }
+
                     return label || info
                 };
                 trackSwitchMenu = createMenu(availableTracks, contentFunc);
@@ -785,6 +789,9 @@ var ControlBar = function (dashjsMediaPlayer, displayUTCTimeCodes) {
     };
 
     var isTracksEqual = function (t1, t2) {
+        if (!t1 && !t2) return true;
+        if (!t1 || !t2) return false;
+        if (t1.isPreselection !== t2.isPreselection) return false;
         var sameId = t1.id === t2.id;
         var sameViewpoint = t1.viewpoint === t2.viewpoint;
         var sameLang = t1.lang === t2.lang;

index.d.ts

@@ -415,6 +415,8 @@ declare namespace dashjs {
 
         getCodec(adaptation: object, representationIndex: number, addResolutionInfo: boolean): string;
 
+        getCodecForPreselection(preselection: Preselection, adaptations: AdaptationSet[], addResolutionInfo: boolean): string;
+
         getContentProtectionByAdaptation(adaptation: object): any;
 
         getContentProtectionByManifest(manifest: object): any[];
@@ -427,7 +429,7 @@ declare namespace dashjs {
 
         getEndTimeForLastPeriod(voPeriod: Period): number;
 
-        getEssentialPropertiesForRepresentation(realRepresentation: object): { schemeIdUri: string, value: string }
+        getEssentialProperties(element: object): DescriptorType | [];
 
         getEventStreamForAdaptationSet(manifest: object, adaptation: object): EventStream[];
 
@@ -467,12 +469,22 @@ declare namespace dashjs {
 
         getLoction(manifest: object): MpdLocation | [];
 
+        getMainAdaptationSetForPreselection(preselection: Preselection, adaptations: AdaptationSet[]): AdaptationSet | undefined;
+
+        getCommonRepresentationForPreselection(preselection: Preselection, adaptations: AdaptationSet[]): Representation | undefined;
+
         getManifestUpdatePeriod(manifest: object, latencyOfLastUpdate?: number): number;
 
         getMimeType(adaptation: object): object;
 
         getMpd(manifest: object): Mpd;
 
+        getPatchLocation(manifest: object): PatchLocation[];
+
+        getPreselectionIsTypeOf(preselection: Preselection, adaptations: AdaptationSet[], type: MediaType): boolean;
+
+        getPreselectionsForPeriod(voPeriod: object): Preselection[];
+
         getPeriodId(realPeriod: Period, i: number): string;
 
         getProducerReferenceTimesForAdaptation(adaptation: object): any[];
@@ -509,9 +521,7 @@ declare namespace dashjs {
 
         getSuggestedPresentationDelay(mpd: Mpd): any;
 
-        getSupplementalPropertiesForAdaptation(adaptation: object): DescriptorType | [];
-
-        getSupplementalPropertiesForRepresentation(representation: Representation): DescriptorType | [];
+        getSupplementalProperties(element: object): DescriptorType | [];
 
         getUTCTimingSources(manifest: object): any[];
 
@@ -672,6 +682,7 @@ declare namespace dashjs {
 
     export class AdaptationSet {
         period: Period | null;
+        id: string | null;
         index: number;
         type: string | null;
     }
@@ -879,6 +890,7 @@ declare namespace dashjs {
         index: number | null;
         isEmbedded: any | null;
         isFragmented: any | null;
+        isPreselection: boolean;
         isText: boolean;
         labels: { text: string, lang?: string }[];
         lang: string | null;
@@ -944,6 +956,16 @@ declare namespace dashjs {
         start: number;
     }
 
+    export interface Preselection {
+        period: Period | null;
+        index: number;
+        id: string | null;
+        order: string | null;
+        preselectionComponents: any[];
+        tag: string | null;
+        type: string | null;
+    }
+
     export interface ProducerReferenceTime {
         UTCTiming: any;
         applicationSchme: any;
@@ -1056,13 +1078,15 @@ declare namespace dashjs {
 
         getCodec(adaptation: object, representationIndex: number, addResolutionInfo: boolean): string;
 
+        getCodecForPreselection(preselection: Preselection, adaptations: AdaptationSet[]): string;
+
+        getCommonRepresentationForPreselection(preselection: Preselection, adaptations: AdaptationSet[]): Representation | null;
+        
         getContentSteering(manifest: object): object;
 
         getDuration(externalManifest?: object): number;
 
-        getEssentialPropertiesAdaptationSet(adaptationSet: AdaptationSet): object | [];
-
-        getEssentialPropertiesForRepresentation(representation: Representation): any[];
+        getEssentialProperties(element: AdaptationSet | Representation | Preselection): DescriptorType | [];
 
         getEvent(eventBox: object, eventStreams: object, mediaStartTime: number, voRepresentation: object): null | Event;
 
@@ -1086,6 +1110,10 @@ declare namespace dashjs {
 
         getLocation(manifest: object): MpdLocation[];
 
+        getMainAdaptationForType(type: string, streamInfo: object): object;
+        
+        getMainAdaptationSetForPreselection(preselection: Preselection, adaptations: AdaptationSet[]): AdaptationSet | undefined; 
+
         getManifestUpdatePeriod(manifest: object, latencyOfLastUpdate?: number): number;
 
         getMediaInfoForType(streamInfo: object, type: MediaType): MediaInfo | null;
@@ -1096,6 +1124,8 @@ declare namespace dashjs {
 
         getPeriodById(id: string): Period | null;
 
+        getPreselectionIsTypeOf(preselection: Preselection, adaptations: AdaptationSet[], type: MediaType): boolean;
+
         getProducerReferenceTime(streamInfo: StreamInfo, mediaInfo: MediaInfo): object | [];
 
         getPublishTime(manifest: object): number | null;
@@ -1112,7 +1142,7 @@ declare namespace dashjs {
 
         getSuggestedPresentationDelay(): string;
 
-        getSupplementalCodex(representation: Representation): Array<any>;
+        getSupplementalCodecs(representation: Representation): Array<any>;
 
         getUTCTimingSources(): any[];
 
@@ -1771,6 +1801,8 @@ declare namespace dashjs {
                 video?: TrackSwitchMode;
                 audio?: TrackSwitchMode;
             };
+            includePreselectionsInMediainfo?: boolean;
+            includePreselectionsForInitialTrackSelection?: boolean;
             ignoreSelectionPriority?: boolean;
             prioritizeRoleMain?: boolean;
             assumeDefaultRoleAsMain?: boolean;

src/core/Settings.js

@@ -189,6 +189,8 @@ import Events from './events/Events.js';
  *                audio: Constants.TRACK_SWITCH_MODE_ALWAYS_REPLACE,
  *                video: Constants.TRACK_SWITCH_MODE_NEVER_REPLACE
  *            },
+ *            includePreselectionsInMediainfoArray: true,
+ *            includePreselectionsForInitialTrackSelection: false,
  *            ignoreSelectionPriority: false,
  *            prioritizeRoleMain: true,
  *            assumeDefaultRoleAsMain: true,
@@ -1007,6 +1009,12 @@ import Events from './events/Events.js';
  * - Constants.TRACK_SWITCH_MODE_NEVER_REPLACE
  * Do not replace existing segments in the buffer
  *
+ * @property {} [includePreselectionsInMediainfoArray: true]
+ * provides the option to include Preselections in the MediaInfo object
+ *
+ * @property {} [includePreselectionsForInitialTrackSelection: false]
+ * provides the option to include Preselections for initial track selection
+ *
  * @property {} [ignoreSelectionPriority: false]
  * provides the option to disregard any signalled selectionPriority attribute. If disabled and if no initial media settings are set, track selection is accomplished as defined by selectionModeForInitialTrack.
  *
@@ -1246,6 +1254,8 @@ function Settings() {
                 audio: Constants.TRACK_SWITCH_MODE_ALWAYS_REPLACE,
                 video: Constants.TRACK_SWITCH_MODE_NEVER_REPLACE
             },
+            includePreselectionsInMediainfoArray: true,
+            includePreselectionsForInitialTrackSelection: false,
             ignoreSelectionPriority: false,
             prioritizeRoleMain: true,
             assumeDefaultRoleAsMain: true,