Stschr/20250424 role main (Dash-Industry-Forum#4760)

* filter for RoleMain

* fix unit test

* implement main as default role

* final fixes

* one further unit test

* resolve issues from review

Author: stschr

index.d.ts

@@ -1771,6 +1771,8 @@ declare namespace dashjs {
                 audio?: TrackSwitchMode;
             };
             ignoreSelectionPriority?: boolean;
+            prioritizeRoleMain?: boolean;
+            assumeDefaultRoleAsMain?: boolean;
             selectionModeForInitialTrack?: TrackSelectionMode;
             fragmentRequestTimeout?: number;
             fragmentRequestProgressTimeout?: number;

src/core/Settings.js

@@ -189,6 +189,8 @@ import Events from './events/Events.js';
  *                video: Constants.TRACK_SWITCH_MODE_NEVER_REPLACE
  *            },
  *            ignoreSelectionPriority: false,
+ *            prioritizeRoleMain: true,
+ *            assumeDefaultRoleAsMain: true,
  *            selectionModeForInitialTrack: Constants.TRACK_SELECTION_MODE_HIGHEST_EFFICIENCY,
  *            fragmentRequestTimeout: 20000,
  *            fragmentRequestProgressTimeout: -1,
@@ -1004,6 +1006,12 @@ import Events from './events/Events.js';
  * @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.
  *
+ * @property {} [prioritizeRoleMain: true]
+ * provides the option to disable prioritization of AdaptationSets with their Role set to Main
+ *
+ * @property {} [assumeDefaultRoleAsMain: true]
+ * when no Role descriptor is present, assume main per default
+ * 
  * @property {string} [selectionModeForInitialTrack="highestEfficiency"]
  * Sets the selection mode for the initial track. This mode defines how the initial track will be selected if no initial media settings are set. If initial media settings are set this parameter will be ignored. Available options are:
  *
@@ -1234,6 +1242,8 @@ function Settings() {
                 video: Constants.TRACK_SWITCH_MODE_NEVER_REPLACE
             },
             ignoreSelectionPriority: false,
+            prioritizeRoleMain: true,
+            assumeDefaultRoleAsMain: true,
             selectionModeForInitialTrack: Constants.TRACK_SELECTION_MODE_HIGHEST_EFFICIENCY,
             fragmentRequestTimeout: 20000,
             fragmentRequestProgressTimeout: -1,

src/streaming/controllers/MediaController.js

@@ -399,18 +399,26 @@ function MediaController() {
         return notEmpty ? settings : null;
     }
 
-    function filterTracksBySettings(tracks, filterFn, settings) {
+    function filterTracksBySettings(tracks, filterFn, preferences) {
         let tracksAfterMatcher = [];
         tracks.forEach(function (track) {
-            if (filterFn(settings, track)) {
+            if (filterFn(preferences, track)) {
                 tracksAfterMatcher.push(track);
             }
         });
         if (tracksAfterMatcher.length !== 0) {
             return tracksAfterMatcher;
-        } else {
-            logger.info('Filter-Function (' + filterFn.name + ') resulted in no tracks; setting ignored');
         }
+
+        if (filterFn === matchSettingsRole && settings.get().streaming.assumeDefaultRoleAsMain && _compareDescriptorType(preferences.role, {schemeIdUri:Constants.DASH_ROLE_SCHEME_ID, value:DashConstants.MAIN} )) {
+            logger.info('no track with Role set to main - assuming main as default and searching again');
+            tracksAfterMatcher = filterTracksBySettings(tracks, _matchRoleAbsent, null);
+            if (tracksAfterMatcher.length !== 0) {
+                return tracksAfterMatcher;
+            }
+        } 
+
+        logger.info('Filter-Function (' + filterFn.name + ') resulted in no tracks; setting ignored');
         return tracks;
     }
 
@@ -441,12 +449,19 @@ function MediaController() {
     }
 
     function matchSettingsRole(settings, track, isTrackActive = false) {
+        if ( !track.roles) {
+            return false;
+        }
         const matchRole = !settings.role || !!track.roles.filter(function (item) {
             return _compareDescriptorType(item, settings.role);
         })[0];
         return (matchRole || (track.type === Constants.AUDIO && isTrackActive));
     }
 
+    function _matchRoleAbsent(_, track) {
+        return (!track.roles) || (track.roles.length === 0);
+    }
+
     function matchSettingsAccessibility(settings, track) {
         let matchAccessibility;
         if (!settings.accessibility) {
@@ -685,9 +700,15 @@ function MediaController() {
         // Use the track selection function that is defined in the settings
         else {
             if (!settings.get().streaming.ignoreSelectionPriority) {
+                logger.info('Trying to find track with highest selectionPriority');
                 tmpArr = _trackSelectionModeHighestSelectionPriority(tmpArr);
             }
+            if (tmpArr.length > 1 && settings.get().streaming.prioritizeRoleMain) {
+                logger.info('Trying to find a main track');
+                tmpArr = filterTracksBySettings(tmpArr, matchSettingsRole, {role: {schemeIdUri:Constants.DASH_ROLE_SCHEME_ID, value:DashConstants.MAIN} });
+            }
             if (tmpArr.length > 1) {
+                logger.info('Selecting track based on selectionModeForInitialTrack');
                 let mode = settings.get().streaming.selectionModeForInitialTrack;
                 switch (mode) {
                     case Constants.TRACK_SELECTION_MODE_HIGHEST_BITRATE:

test/unit/test/streaming/streaming.controllers.MediaController.js

@@ -700,6 +700,20 @@ describe('MediaController', function () {
             expect(objectUtils.areEqual(currentTrack, frTrack)).to.be.true;
         });
 
+        it('should check initial media settings to choose initial track based on role', function () {
+            mediaController.addTrack(enTrack);
+            mediaController.addTrack(esTrack);
+            mediaController.addTrack(enADTrack);
+
+            mediaController.setInitialSettings(trackType, {
+                role: { schemeIdUri: 'urn:mpeg:dash:role:2011', value: 'dub' }
+            });
+            mediaController.setInitialMediaSettingsForType(trackType, streamInfo);
+
+            let currentTrack = mediaController.getCurrentTrackFor(trackType, streamInfo.id);
+            expect(objectUtils.areEqual(currentTrack, esTrack)).to.be.true;
+        });
+
         it('should not check initial media settings to choose initial track when it has already selected a track', function () {
             mediaController.addTrack(frTrack);
             mediaController.addTrack(qtzTrack);
@@ -775,7 +789,8 @@ describe('MediaController', function () {
                     representationCount: track.bitrateList.length,
                     audioChannelConfiguration: track.audioChannelConfiguration ? track.audioChannelConfiguration : [],
                     selectionPriority: !isNaN(track.selectionPriority) ? track.selectionPriority : 1,
-                    supplementalProperties: track.supplementalProperties ? track.supplementalProperties : []
+                    supplementalProperties: track.supplementalProperties ? track.supplementalProperties : [],
+                    roles: track.roles ? track.roles : []
                 };
             });
             const selection = mediaController.selectInitialTrack(type, tracks);
@@ -805,6 +820,83 @@ describe('MediaController', function () {
             });
         })
 
+        describe('roleMain flag' ,function () {
+            beforeEach(function () {
+                settings.update({ 
+                    streaming: { 
+                        selectionModeForInitialTrack: Constants.TRACK_SELECTION_MODE_HIGHEST_BITRATE,
+                        prioritizeRoleMain: true
+                    }
+                });
+            });
+
+            it('should select track with role set to main if no selectionPriority is provided', function () {
+                testSelectInitialTrack(
+                    'video',
+                    { bitrateList: [{ bandwidth: 1000 }], roles: [{ schemeIdUri: 'urn:mpeg:dash:role:2011', value: 'main' }] },
+                    { bitrateList: [{ bandwidth: 2000 }], roles: [{ schemeIdUri: 'urn:mpeg:dash:role:2011', value: 'dub' }] }
+                );
+            });
+
+            it('should select track with role set to main if other tracks have no role', function () {
+                testSelectInitialTrack(
+                    'video',
+                    { bitrateList: [{ bandwidth: 1000 }], roles: [{ schemeIdUri: 'urn:mpeg:dash:role:2011', value: 'main' }] },
+                    { bitrateList: [{ bandwidth: 2000 }], roles: [] }
+                );
+            });
+
+            it('should select track with role set to main with multiple role descriptors', function () {
+                testSelectInitialTrack(
+                    'video',
+                    { bitrateList: [{ bandwidth: 1000 }], roles: [{ schemeIdUri: 'urn:mpeg:dash:role:2011', value: 'main' },{ schemeIdUri: 'urn:mpeg:dash:role:2011', value: 'dub' }] },
+                    { bitrateList: [{ bandwidth: 2000 }], roles: [{ schemeIdUri: 'urn:mpeg:dash:role:2011', value: 'dub' }] }
+                );
+            });
+
+            it('should select track with no role if other tracks have role not main', function () {
+                testSelectInitialTrack(
+                    'video',
+                    { bitrateList: [{ bandwidth: 1000 }], roles: [] },
+                    { bitrateList: [{ bandwidth: 2000 }], roles: [{ schemeIdUri: 'urn:mpeg:dash:role:2011', value: 'dub' }] }
+                );
+            });
+
+            it('should not select track with no role if other tracks have role not main, when disabled in Settings', function () {
+                settings.update({ 
+                    streaming: { 
+                        assumeDefaultRoleAsMain: false
+                    }
+                });
+                testSelectInitialTrack(
+                    'video',
+                    { bitrateList: [{ bandwidth: 2000 }], roles: [{ schemeIdUri: 'urn:mpeg:dash:role:2011', value: 'dub' }] },
+                    { bitrateList: [{ bandwidth: 1000 }], roles: [] }
+                );
+            });
+
+            it('should select track based on selectionPriority, if provided, and disregard role main', function () {
+                testSelectInitialTrack(
+                    'video',
+                    { bitrateList: [{ bandwidth: 1000 }], roles: [{ schemeIdUri: 'urn:mpeg:dash:role:2011', value: 'dub' }], selectionPriority: 2 },
+                    { bitrateList: [{ bandwidth: 2000 }], roles: [{ schemeIdUri: 'urn:mpeg:dash:role:2011', value: 'main' }], selectionPriority: 1 }
+                );
+            });
+
+            it('should select track based on selectionModeForInitialTrack if roleMain flag is false', function () {
+                settings.update({ streaming: { 
+                    prioritizeRoleMain: false, 
+                    selectionModeForInitialTrack: Constants.TRACK_SELECTION_MODE_HIGHEST_BITRATE } 
+                });
+                
+                testSelectInitialTrack(
+                    'video',
+                    { bitrateList: [{ bandwidth: 2000 }], roles: [{ schemeIdUri: 'urn:mpeg:dash:role:2011', value: 'dub' }] },
+                    { bitrateList: [{ bandwidth: 1000 }], roles: [{ schemeIdUri: 'urn:mpeg:dash:role:2011', value: 'main' }] }
+                );
+            });
+        })
+
         describe('"highestSelectionPriority" mode', function () {
             beforeEach(function () {
                 settings.update({ streaming: { selectionModeForInitialTrack: Constants.TRACK_SELECTION_MODE_HIGHEST_EFFICIENCY } });