Feature MPD Lists #53

sebastianpiq · 2025-02-25T14:11:54Z

List MPD

This feature introduces support for List MPDs (MPD@type="list") and their Linked Periods.

Key aspects of the implementation:

Handling Linked Periods: When a Period contains an ImportedMPD element, it is a Linked Period, meaning its content is imported from an external MPD located at another path.
Playback Order: The first Period in a List MPD starts at PeriodStart = 0. Subsequent Linked Periods are resolved based on ImportedMPD@earliestResolutionTimeOffset.
List MPD Structure: A List MPD can contain both regular and Linked Periods, but Linked Periods can only exist within a List MPD.
Seamless Transitions: The player dynamically fetches and merges imported MPDs, ensuring smooth playback across Linked Periods.

Summary

This PR introduces support for List MPD profiles by implementing necessary parsing, handling, and playback functionalities.

Key changes include:

Recognition of List MPD Profile: Added logic to detect and process List MPDs.
Parsing Imported MPD Periods: Properly parses ImportedMPD tags within the manifest.
ListMpdController implementation:
- Manages ImportedMPD and LinkedPeriod behaviors.
- Handles seamless transitions between different Period types.
EarliestResolutionTimeOffset Handling: Ensures accurate timing of Imported MPDs based on earliestResolutionTimeOffset.
ManifestLoader updates: Now supports requesting Imported MPDs dynamically.
mergeManifest method: Resolves LinkedPeriod timing and merging conflicts.
New List MPD sample page: Provides a visual example for testing.
Unit Tests: Added tests for ListMpdController to validate functionality.

Testing

The following List MPD test cases cover various playback scenarios:

Single Linked Period
- The MPD contains a single Period linking to an Imported MPD.
Multiple Linked Periods
- The MPD has multiple Linked Periods, each referencing a different Imported MPD.
Linked Period + Regular Period
- One Linked Period is followed by a Regular Period.
Regular Period + Linked Period
- A Regular Period appears first, followed by a Linked Period.
EarliestResolutionTime > minBufferTime
- The earliestResolutionTime of the Linked Period is greater than minBufferTime.
EarliestResolutionTime < minBufferTime
- The earliestResolutionTime of the Linked Period is less than minBufferTime.
Different Linked Period & Imported MPD Durations
- The Linked Period references an Imported MPD with a mismatched duration.
First List MPD Period with Start Time ≠ 0
- The MPD type is List, but the first Period has a non-zero start time.
Retry Scenario
- The MPD is of type List, and the Imported MPD should not be downloadable.

Known Issues

Playback Freeze on Low Connectivity Streams
- When switching Periods, if a low-connectivity stream has a low earliestResolutionTimeOffset, the GapController may cause the stream to freeze.
- This issue occurs when handling a gap during a Period switch

Notes

This PR is based on the Dash draft (MDS24421_WG03_N01358_DASH-6th-edition_2nd_DraftFDIS_r17)

Fix list mpd with a regular period as first period

…n-time Mpd lists/zero earliest resolution time

Mpd lists/linked period seek

…-error Fix first period start time error

Deduplicate manifest load logic

Co-authored-by: Sebastian Piquerez <89274285+sebastianpiq@users.noreply.github.com>

Resolve imported mpd url using list mpd BaseURL

Mpd lists/imported period duration

…riod Mpd lists/default start linked period

bug: fix typo on CoreEvents name

…ds (#61) * Merge mpd level essentaial and suplemental properties to linked periods * bug fix: some elements of imported period always overrides an element of the linked period * rename mergeUniqueProperties and bugfix * bugfix for undefined behaviour * Update src/dash/DashAdapter.js --------- Co-authored-by: Constanza Dibueno <constanzad@qualabs.com> Co-authored-by: cotid-qualabs <121617928+cotid-qualabs@users.noreply.github.com> Co-authored-by: Tatiana Perera <109090910+tatiana-perera@users.noreply.github.com>

emilsas

I would also first sync the changes with the last commit of dash.js in order to have this merged with the last changes in the codebase, it will help to resolve all conflicts before open a PR to dash.js

Also, check that all github actions pass successfully.

emilsas · 2025-03-11T14:48:45Z

samples/list-mpds/list-mpds.html

+                          <a class="dropdown-item" data-url="https://comcast-dash-6-assets.s3.us-east-2.amazonaws.com/ListMPDs/bbb/list0.mpd">Case 0: Single Linked Period</a>
+                          <a class="dropdown-item" data-url="https://comcast-dash-6-assets.s3.us-east-2.amazonaws.com/ListMPDs/bbb/list1.mpd">Case 1: Multiple Linked Period</a>
+                          <a class="dropdown-item" data-url="https://comcast-dash-6-assets.s3.us-east-2.amazonaws.com/ListMPDs/bbb/list2.mpd">Case 2: Linked Period + Regular Period</a>
+                          <a class="dropdown-item" data-url="https://comcast-dash-6-assets.s3.us-east-2.amazonaws.com/ListMPDs/bbb/list3.mpd">Case 3: Regular Period + Linked Period</a>
+                          <a class="dropdown-item" data-url="https://comcast-dash-6-assets.s3.us-east-2.amazonaws.com/ListMPDs/bbb/list4.mpd">Case 4: EarliestResolutionTime &gt; minBufferTime</a>
+                          <a class="dropdown-item" data-url="https://comcast-dash-6-assets.s3.us-east-2.amazonaws.com/ListMPDs/bbb/list5.mpd">Case 5: EarliestResolutionTime &lt; minBufferTime</a>
+                          <a class="dropdown-item" data-url="https://comcast-dash-6-assets.s3.us-east-2.amazonaws.com/ListMPDs/bbb/list6.mpd">Case 6: Different Linked Period and Imported Period durations</a>
+                          <a class="dropdown-item" data-url="https://comcast-dash-6-assets.s3.us-east-2.amazonaws.com/ListMPDs/bbb/list7.mpd">Case 7: First List MPD Period with start time =/ 0</a>
+                          <a class="dropdown-item" data-url="https://comcast-dash-6-assets.s3.us-east-2.amazonaws.com/ListMPDs/bbb/list8.mpd">Case 8: Retry</a>


All this samples will be hosted by us? (Thinking about the PR with the official dash.js repo)

emilsas · 2025-03-11T14:51:13Z

samples/list-mpds/list-mpds.html

+                  if (target.text === "Case 0: Single Linked Period") {
+                    behavior.innerText = "The player should download the Imported MPD and reproduce the unique Period.";
+                  } else if (target.text === "Case 1: Multiple Linked Period") {
+                    behavior.innerText = "The player should download the first Imported MPD, reproduce its first Period, and, upon completion, download the second Imported MPD and reproduce its first Period.";
+                  } else if (target.text === "Case 2: Linked Period + Regular Period") {
+                    behavior.innerText = "The player should download the first Imported MPD, reproduce its first Period, and, upon completion, play the next regular Period.";
+                  } else if (target.text === "Case 3: Regular Period + Linked Period") {
+                    behavior.innerText = "The player should start by playing the first regular Period as usual and, upon its completion, download the linked Imported MPD and reproduce its first Period.";
+                  } else if (target.text === "Case 4: EarliestResolutionTime > minBufferTime") {
+                    behavior.innerText = "The player should start by playing the first regular Period as usual and, upon its completion, download the linked Imported MPD at startTime - earliestResolutionTime and reproduce its first Period";
+                  } else if (target.text === "Case 5: EarliestResolutionTime < minBufferTime") {
+                    behavior.innerText = "The player should start by playing the first regular Period as usual and, upon its completion, download the linked Imported MPD at with earliestResolutionTime = 0 and reproduce its first Period.";
+                  } else if (target.text === "Case 6: Different Linked Period and Imported Period durations") {
+                    behavior.innerText = "The player must respect the shortest duration between the Linked Period in the main manifest and the Imported MPD. Playback should seamlessly stop at the shorter duration, ensuring no content extends beyond the specified boundaries.";
+                  } else if (target.text === "Case 7: First List MPD Period with start time =/ 0") {
+                    behavior.innerText = "The player should throw an error indicating that the start time of the first period in a list type MPD manifest is invalid.";
+                  } else if (target.text === "Case 8: Retry") {
+                    behavior.innerText = "The player should attempt to download the manifest four times before failing.";
+                  }


I think that this could be handled using an id in each option instead of comparing a text.

emilsas · 2025-03-18T14:37:27Z

src/streaming/controllers/StreamController.js

+            .catch(error => {
+                console.error(error);


This should be handled by the errHandler, right?

emilsas · 2025-03-18T14:39:32Z

src/streaming/controllers/ListMpdController.js

+const DEFAULT_EARLIEST_RESOLUTION_TIME_OFFSET = 60;
+
+function ListMpdController() {
+


Suggested change

I checked the other controllers, and they all have this space. I'm going to leave them like this to maintain the code style.

emilsas · 2025-03-18T14:42:46Z

src/streaming/controllers/ListMpdController.js

+        if (manifest.Period[0].start) {
+            throw new Error('The first period in a list MPD must have start time equal to 0');
+        } 


Is this for only checking presence of start attr? In that case the error message is no suggesting that.

In linked periods, the start attribute must be 0. If start has any value greater than 0, an error must be displayed.

The default value of manifest.Period[0].start is 0 if it is not present, so any value greater than 0 will result in an error.

If you want to check if it is 0, it will be preferred to ask specifically for that. As it is right now it is suggesting if the attributte is present or not.

emilsas · 2025-03-18T14:49:14Z

src/streaming/controllers/ListMpdController.js

+                .then((importedManifest) => {
+                    dashAdapter.mergeManifests(manifest, importedManifest, period, mpdHasDuration);
+                }, () => {
+                    dashAdapter.mergeManifests(manifest, null, period, mpdHasDuration);
+                })
+                .then(() => {
+                    eventBus.trigger(Events.MANIFEST_UPDATED, { manifest });
+                    linkedPeriodList = linkedPeriodList.filter((element) => element.id !== period.id);
+                    resolve(manifest);
+                });


Error handling is missing

emilsas · 2025-03-20T13:10:01Z

src/dash/DashAdapter.js

+            if (importedManifest.hasOwnProperty(DashConstants.PROFILES)) {
+                importedPeriod.profiles = importedManifest.profiles;
+            }


This must change to MPD level as it was discussed with Alex G.

emilsas · 2025-03-20T13:13:22Z

src/dash/models/DashManifestModel.js

+
+        if (linkedPeriods.length > 0) {
+            if (mpd.manifest.type !== DashConstants.MPD_LIST) {
+                throw new Error('Linked periods are only allowed in a list MPD');


I would say in an MPD with profile .... (DashConstants.MPD_LIST)

emilsas · 2025-03-20T13:14:35Z

src/streaming/ManifestLoader.js

-    const eventBus = EventBus(context).getInstance();
-    const urlUtils = URLUtils(context).getInstance();
-
+function ManifestLoader() {


Why this change is needed? It is tested that anything else is still working?

This was implemented because the manifestLoader was changed to a singleton. In MediaPlayer, the ListMpdController is initialized before the manifestLoader, and an instance of it is needed.

It shouldn't be an issue that it's a singleton since there isn't another place where a new instance of manifestLoader is created.
Notice that the config code is moved to setConfig.

Anyway, after a quick look at the code, I think it might be possible to change the initialization order so that ListMpdController is initialized after manifestLoader (along with all playbackControllers), avoiding this change. I have to take a deeper look into it.

* Fix merge imported profiles issue * Fix imporetd mpd repeated profiles * Fix wrong profile split by dot * Check multiple profiles in mpd lists

[MpdLists] Minor code review changes

* Fix typos and rename some methods * Update type for minEarliestResolutionTimeOffset in listMpdSettings to number

…d update related methods

…ring reset

…MpdController

sebastianpiq and others added 30 commits November 29, 2024 11:43

POC manifes mpd lists

a79b80a

POC manifes mpd lists

2a1d963

Implement POC of MPD Lists

428b63e

Implement validation for link periods

6c179cf

Fix mpd list validation

fec3f83

Implement mpd list controller

7f963a2

Implement merging of linked periods

9e9b157

Merge earliestResolutionTimeOffset

76c5665

Only update manifest inside controller if list mpd

0a6d1d0

Fix url resolution in imported mpd

e351315

Fix list mpd with a regular period as first period

3c656bb

Fix trying to prebuffer a linked period not yet resolved

126a6b6

Implement seek to linked periods

1c0de11

Add semicolons

ee3494a

Merge pull request #32 from qualabs/mpd-lists/regular-initial-period

84b80e3

Fix list mpd with a regular period as first period

Merge pull request #33 from qualabs/mpd-lists/zero-earliest-resolutio…

c1af5a7

…n-time Mpd lists/zero earliest resolution time

Merge pull request #35 from qualabs/mpd-lists/linked-period-seek

0012008

Mpd lists/linked period seek

Move first period start time check to the regular period getter

2695d13

Deduplicate load logic

93899cd

Merge pull request #36 from qualabs/mpd-lists/first-period-start-time…

f25126f

…-error Fix first period start time error

Address pr comments

c55133f

Merge pull request #37 from qualabs/mpd-lists/manifest-load-refactor

4935505

Deduplicate manifest load logic

Resolve imported mpd url using list mpd BaseURL

5a52f54

Fix NaN duration if no importedMpd duration

61d85e2

Compute list mpd duration on manifest load

ac469ba

Move start check logic to controller and set default

e127715

Simplify start checking expression

9e2b547

Co-authored-by: Sebastian Piquerez <89274285+sebastianpiq@users.noreply.github.com>

Merge pull request #38 from qualabs/mpd-lists/imported-mpd-url

4050e48

Resolve imported mpd url using list mpd BaseURL

Merge pull request #39 from qualabs/mpd-lists/imported-period-duration

4e32b44

Mpd lists/imported period duration

Merge pull request #40 from qualabs/mpd-lists/default-start-linked-pe…

38d7066

…riod Mpd lists/default start linked period

Merge pull request #63 from qualabs/mpd-lists/importedMpdLoaded-typo

1a304fb

bug: fix typo on CoreEvents name

tatiana-perera added DON'T MERGE feature labels Mar 12, 2025

emilsas requested changes Mar 20, 2025

View reviewed changes

sebastianpiq and others added 6 commits March 21, 2025 16:20

Resolve minor code review comments

167ce54

Undo manifestLoader as a singleton

35612d2

Merge development into mpd-lists branch

cb29ea9

Fix sample json

91f9c66

[MpdLists] Fix merge imported profiles issue (#66)

26af4a5

* Fix merge imported profiles issue * Fix imporetd mpd repeated profiles * Fix wrong profile split by dot * Check multiple profiles in mpd lists

Merge pull request #67 from qualabs/mpd-lists/review-changes

1c29fec

[MpdLists] Minor code review changes

emilsas approved these changes Mar 31, 2025

View reviewed changes

sebastianpiq and others added 18 commits April 3, 2025 11:22

Merge branch 'development' into feature/mpd-lists

2321e23

Fix code formatting

4880a6b

Update dashjs path in to the list mpd demo

437210b

Handle empty manifest profiles to prevent errors during parsing

c609b9f

Fix typos and rename some methods (#103)

d30c20d

* Fix typos and rename some methods * Update type for minEarliestResolutionTimeOffset in listMpdSettings to number

Merge branch 'development' into feature/mpd-lists

ea03de7

Merge branch 'development' into feature/mpd-lists

aadfd4f

Fix: update minEarliestResolutionTimeOffset to 0

bfc2218

refactor: rename IMPORTED_MPDS_LOADED event to LINKED_PERIOD_FOUND an…

3894b78

…d update related methods

Fix: reset ListMpdController event listeners during reset

7366dc8

refactor: encapsulate reset logic in resetInitialSettings and call du…

08540d7

…ring reset

refactor: simplify linked period handling in ManifestUpdater and List…

a481798

…MpdController

Fix: validate period ID before seeking to period in StreamController

e3c4a4e

refactor: improve linked period identification in StreamController

72f789d

refactor: rename linked period event to list MPD found for clarity

69c856e

Merge branch 'development' into feature/mpd-lists

ecea7ad

fix: validate availabilityEndTime in manifest merging process

04d9524

refactor: remove handling of 'No Content' response in manifest loading

7683769

		const DEFAULT_EARLIEST_RESOLUTION_TIME_OFFSET = 60;

		function ListMpdController() {

Feature MPD Lists #53

Are you sure you want to change the base?

Feature MPD Lists #53

Uh oh!

Conversation

sebastianpiq commented Feb 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

List MPD

Summary

Key changes include:

Testing

Known Issues

Notes

Uh oh!

emilsas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

sebastianpiq commented Feb 25, 2025 •

edited

Loading