Update documentation with a glossary and intro page, added DASH background #94
Conversation
ldayananda
commented
May 3, 2018
•
ldayananda
commented
- added intro.md as a starting point for new contributors
- added a DASH explanation to the intro.md
- added glossary.md for quick explanations of common terms
- removed some out of date documentation
docs/intro.md
Outdated
| @@ -0,0 +1,29 @@ | |||
| # HLS Overview | |||
There was a problem hiding this comment.
Might be good to add a DASH overview that's similar at some point, since this project supports that as well (not necessary in this PR, more of a note for the future).
There was a problem hiding this comment.
💯 yeah, at some point I hope to actually add DASH into the depths of the documentation we do have
docs/glossary.md
Outdated
|
|
||
| **Media Playlist**: This is a manifest that represents a single rendition of the source. | ||
|
|
||
| **Segment Loader**: This controlls the requesting and appending of segments on to the browser's [SourceBuffers](https://developer.mozilla.org/en-US/docs/Web/API/SourceBuffer). |
There was a problem hiding this comment.
typo : controlls -> controls
ldayananda
changed the title
ldayananda
changed the title
docs/glossary.md
Outdated
|
|
||
| **Master Playlist Controller**: This acts as the main controller for the playback engine. It interacts with the SegmentLoaders, PlaylistLoaders, PlaybackWatcher, etc. | ||
|
|
||
| **Playlist Loader**: This will request the source and load the master manifest. It also interacts with the ABR algorithm to pick a media playlist or wraps a media playlist if it is provided as the source. There are more details about the playlist loader [here](./arch.md). |
There was a problem hiding this comment.
The ABR algorithm should be called through Master Playlist Controller. Playlist Loader is just told what playlist was selected.
There was a problem hiding this comment.
changing this to It is also instructed by the ABR algorithm to load a media playlist or wraps a media playlist if it is provided as the source
docs/glossary.md
Outdated
|
|
||
| **Playlist Loader**: This will request the source and load the master manifest. It also interacts with the ABR algorithm to pick a media playlist or wraps a media playlist if it is provided as the source. There are more details about the playlist loader [here](./arch.md). | ||
|
|
||
| **Media Playlist**: This is a manifest that represents a single rendition of the source. |
There was a problem hiding this comment.
Probably should move this up below Playlist.
docs/glossary.md
Outdated
|
|
||
| **Media Playlist**: This is a manifest that represents a single rendition of the source. | ||
|
|
||
| **Segment Loader**: This controls the requesting and appending of segments on to the browser's [SourceBuffers](https://developer.mozilla.org/en-US/docs/Web/API/SourceBuffer). |
There was a problem hiding this comment.
Technically Segment Loader figures out which segment to request, and requests it via Media Segment Request. It then decrypts (if necessary) and sends the segment bytes to the Source Updater, which manages the source buffers.
docs/glossary.md
Outdated
|
|
||
| **Segment Loader**: This controls the requesting and appending of segments on to the browser's [SourceBuffers](https://developer.mozilla.org/en-US/docs/Web/API/SourceBuffer). | ||
|
|
||
| **ABR(Adaptive Bitrate) Algorithm**: This is defined in selectPlaylist and is described more [here](./bitrate-switching.md). |
There was a problem hiding this comment.
ABR is a more generic term. We may want to point to https://en.wikipedia.org/wiki/Adaptive_bitrate_streaming and say that our "chosen" ABR algorithm is referenced by selectPlaylist (can also point to the README where it shows instructions for overriding it).
docs/glossary.md
Outdated
|
|
||
| **ABR(Adaptive Bitrate) Algorithm**: This is defined in selectPlaylist and is described more [here](./bitrate-switching.md). | ||
|
|
||
| **Playback Watcher**: This handles seeking to live when playing a live source with a live window, or skipping over gaps in content. This is described in detail [here](). |
There was a problem hiding this comment.
May want a link here, but can more generically say that Playback Watcher tries to resolve common playback stalls caused by improper seeking, gaps in content, browser issues, and other problematic events.
There was a problem hiding this comment.
heh, good catch. I forgot I didn't write that doc yet. 👍
docs/intro.md
Outdated
| - Delivered over HTTP(S): it uses the standard application protocol of the web to deliver all its data | ||
| - Segmented: longer videos are broken up into smaller chunks which can be downloaded independently and switched between at runtime | ||
|
|
||
| A standard HLS stream consists of a *Master Playlist* which references one or more *Media Playlists*. Each Media Playlist contains references one or more sequential video segments. All these components form a logical hierarchy that informs the player of the different quality levels of the video available and how to address the individual segments of video at each of those levels: |
There was a problem hiding this comment.
s/contains references/contains/
docs/intro.md
Outdated
| ## Dynamic Adaptive Streaming over HTTP | ||
| Similar to HLS, [DASH][dash-wiki] content is segmented and is delivered over HTTP(s). | ||
|
|
||
| A DASH stream consits of a *Media Presentation Description*(MPD) that describes segment metadata. Each segment must contain either ISO base media file format(e.g MP4) or MPEG-2 TS data. Typically the MPD will describe the various *Representations* that map to collections of segments at different bitrates to allow bitrate selection. |
There was a problem hiding this comment.
I don't know if segment links is technically a part of "segment metadata," but it is a bit hard to glean that info from just metadata. May want to expand on the contents.
docs/intro.md
Outdated
| @@ -20,7 +20,7 @@ If you're interested in a more in-depth treatment of the HLS format, check out [ | |||
| ## Dynamic Adaptive Streaming over HTTP | |||
| Similar to HLS, [DASH][dash-wiki] content is segmented and is delivered over HTTP(s). | |||
|
|
|||
| A DASH stream consits of a *Media Presentation Description*(MPD) that describes segment metadata. Each segment must contain either ISO base media file format(e.g MP4) or MPEG-2 TS data. Typically the MPD will describe the various *Representations* that map to collections of segments at different bitrates to allow bitrate selection. | |||
| A DASH stream consits of a *Media Presentation Description*(MPD) that describes segment metadata and includes links to the segments themselves. Each segment can contain either ISO base media file format(e.g MP4) or MPEG-2 TS data. Typically the MPD will describe the various *Representations* that map to collections of segments at different bitrates to allow bitrate selection. | |||
There was a problem hiding this comment.
It might be easiest to go with something like the wikipedia description: "A media presentation description (MPD) describes segment information (timing, URL, media characteristics like video resolution and bit rates), and can be organized in different ways such as SegmentList, SegmentTemplate, SegmentBase and SegmentTimeline, depending on the use case."
docs/glossary.md
Outdated
|
|
||
| **Playback Watcher**: This handles seeking to live when playing a live source with a live window, or skipping over gaps in content. This is described in detail [here](). | ||
| **Playback Watcher**: This attemps to resolve common playback stalls caused by improper seeking, gaps in content and browser issues. Some examples of the ways these issues are handled is by seeking to live when playing a live source with a live window, or skipping over gaps in content. |
There was a problem hiding this comment.
"Some examples of the ways these issues are handled is by seeking to live when playing a live source with a live window" is a bit confusing, as it doesn't describe when playback watcher would make such a decision. We may be able to forego the second sentence entirely, or provide some of the cases from playback watcher.
There was a problem hiding this comment.
You're right, that sentence would probably be better replaced by a full doc on Playback Watcher
docs/glossary.md
Outdated
|
|
||
| **Media Playlist**: This is a manifest that represents a single rendition of the source. | ||
| **Segment Loader**: This determines which segment should be loaded via the Media Segment Loader, decrypts the segment if necessary and passes the result to the Source Updater. |
There was a problem hiding this comment.
Might read a bit easier as "This determines which segment should be loaded, requests it via the Media Segment Loader, and passes the result to the Source Updater." (Also, Media Segment Request will decrypt the bytes, but that was my comment's fault.)
