| 1 | # DASH Playlist Loader
|
| 2 |
|
| 3 | ## Purpose
|
| 4 |
|
| 5 | The [DashPlaylistLoader][dpl] (DPL) is responsible for requesting MPDs, parsing them and keeping track of the media "playlists" associated with the MPD. The [DPL] is used with a [SegmentLoader] to load fmp4 fragments from a DASH source.
|
| 6 |
|
| 7 | ## Basic Responsibilities
|
| 8 |
|
| 9 | 1. To request an MPD.
|
| 10 | 2. To parse an MPD into a format [videojs-http-streaming][vhs] can understand.
|
| 11 | 3. To refresh MPDs according to their minimumUpdatePeriod.
|
| 12 | 4. To allow selection of a specific media stream.
|
| 13 | 5. To sync the client clock with a server clock according to the UTCTiming node.
|
| 14 | 6. To refresh a live MPD for changes.
|
| 15 |
|
| 16 | ## Design
|
| 17 |
|
| 18 | The [DPL] is written to be as similar as possible to the [PlaylistLoader][pl]. This means that majority of the public API for these two classes are the same, and so are the states they go through and events that they trigger.
|
| 19 |
|
| 20 | ### States
|
| 21 |
|
| 22 | 
|
| 23 |
|
| 24 | - `HAVE_NOTHING` the state before the MPD is received and parsed.
|
| 25 | - `HAVE_MASTER` the state before a media stream is setup but the MPD has been parsed.
|
| 26 | - `HAVE_METADATA` the state after a media stream is setup.
|
| 27 |
|
| 28 | ### API
|
| 29 |
|
| 30 | - `load()` this will either start or kick the loader during playback.
|
| 31 | - `start()` this will start the [DPL] and request the MPD.
|
| 32 | - `parseMasterXml()` this will parse the MPD manifest and return the result.
|
| 33 | - `media()` this will return the currently active media stream or set a new active media stream.
|
| 34 |
|
| 35 | ### Events
|
| 36 |
|
| 37 | - `loadedplaylist` signals the setup of a master playlist, representing the DASH source as a whole, from the MPD; or a media playlist, representing a media stream.
|
| 38 | - `loadedmetadata` signals initial setup of a media stream.
|
| 39 | - `minimumUpdatePeriod` signals that a update period has ended and the MPD must be requested again.
|
| 40 | - `playlistunchanged` signals that no changes have been made to a MPD.
|
| 41 | - `mediaupdatetimeout` signals that a live MPD and media stream must be refreshed.
|
| 42 | - `mediachanging` signals that the currently active media stream is going to be changed.
|
| 43 | - `mediachange` signals that the new media stream has been updated.
|
| 44 |
|
| 45 | ### Interaction with Other Modules
|
| 46 |
|
| 47 | 
|
| 48 |
|
| 49 | ### Special Features
|
| 50 |
|
| 51 | There are a few features of [DPL] that are different from [PL] due to fundamental differences between HLS and DASH standards.
|
| 52 |
|
| 53 | #### MinimumUpdatePeriod
|
| 54 |
|
| 55 | This is a time period specified in the MPD after which the MPD should be re-requested and parsed. There could be any number of changes to the MPD between these update periods.
|
| 56 |
|
| 57 | #### SyncClientServerClock
|
| 58 |
|
| 59 | There is a UTCTiming node in the MPD that allows the client clock to be synced with a clock on the server. This may affect the results of parsing the MPD.
|
| 60 |
|
| 61 | #### Requesting `sidx` Boxes
|
| 62 |
|
| 63 | To be filled out.
|
| 64 |
|
| 65 | ### Previous Behavior
|
| 66 |
|
| 67 | Until version 1.9.0 of [VHS], we thought that [DPL] could skip the `HAVE_NOTHING` and `HAVE_MASTER` states, as no other XHR requests are needed once the MPD has been downloaded and parsed. However, this is incorrect as there are some Presentations that signal the use of a "Segment Index box" or `sidx`. This `sidx` references specific byte ranges in a file that could contain media or potentially other `sidx` boxes.
|
| 68 |
|
| 69 | A DASH MPD that describes a `sidx` is therefore similar to an HLS master manifest, in that the MPD contains references to something that must be requested and parsed first before references to media segments can be obtained. With this in mind, it was necessary to update the initialization and state transitions of [DPL] to allow further XHR requests to be made after the initial request for the MPD.
|
| 70 |
|
| 71 | ### Current Behavior
|
| 72 |
|
| 73 | In [this PR](https://github.com/videojs/http-streaming/pull/386), the [DPL] was updated to go through the `HAVE_NOTHING` and `HAVE_MASTER` states before arriving at `HAVE_METADATA`. If the MPD does not contain `sidx` boxes, then this transition happens quickly after `load()` is called, spending little time in the `HAVE_MASTER` state.
|
| 74 |
|
| 75 | The initial media selection for `masterPlaylistLoader` is made in the `loadedplaylist` handler located in [MasterPlaylistController][mpc]. We now use `hasPendingRequest` to determine whether to automatically select a media playlist for the `masterPlaylistLoader` as a fallback in case one is not selected by [MPC]. The child [DPL]s are created with a media playlist passed in as an argument, so this fallback is not necessary for them. Instead, that media playlist is saved and auto-selected once we enter the `HAVE_MASTER` state.
|
| 76 |
|
| 77 | The `updateMaster` method will return `null` if no updates are found.
|
| 78 |
|
| 79 | The `selectinitialmedia` event is not triggered until an audioPlaylistLoader (which for DASH is always a child [DPL]) has a media playlist. This is signaled by triggering `loadedmetadata` on the respective [DPL]. This event is used to initialize the [Representations API][representations] and setup EME (see [contrib-eme]).
|
| 80 |
|
| 81 | [dpl]: ../src/dash-playlist-loader.js
|
| 82 | [sl]: ../src/segment-loader.js
|
| 83 | [vhs]: intro.md
|
| 84 | [pl]: ../src/playlist-loader.js
|
| 85 | [mpc]: ../src/master-playlist-controller.js
|
| 86 | [representations]: ../README.md#hlsrepresentations
|
| 87 | [contrib-eme]: https://github.com/videojs/videojs-contrib-eme
|