Player URLs¶
Table of Contents
Once you have prepared a VOD presentation (or started a LIVE presentation), the webserver module makes a variety of URLs available for that presentation.
The structure of the URLs is the same for VOD and LIVE. The only difference
is the extension of the server manifest file. In the examples below for VOD
it is .ism. For LIVE presentations you have to change this to .isml.
Device/Player URLs¶
The base URL for the different devices/players is identical. Only the last part of the URL varies depending on the device and the playout format.
Let’s assume that your DOCUMENT_ROOT is /var/www and the VOD presentation
is stored in the directory /var/www/video/tears-of-steel.
| Device/Player URL | Description |
|---|---|
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/Manifest | The HTTP Smooth Streaming client manifest. |
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/.m3u8 | The master .m3u8 playlist for HTTP Live Streaming |
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/.f4m | The HTTP Dynamic Streaming manifest. |
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/.mpd | The MPEG DASH manifest. |
The part of the URL after /tears-of-steel.ism/ is a so-called ‘virtual’ path.
The Manifest, tears-of-steel.m3u8, tears-of-steel.f4m and
tears-of-steel.mpd are not actually stored on disk (you won’t see them listed
in the /var/www/video/tears-of-steel directory). They are generated on-the-fly
by the Origin on request.
Note
With HDS (.f4m) HLS (.m3u8) or MPEG_DASH (.mpd) it is not necessary to repeat the filename as the manifest name. Example: tears-of-steel.ism/tears-of-steel.m3u8 can also be addressed as tears-of-steel.ism/another-name.m3u8 or even tears-of-steel.ism/.m3u8.
Since adaptive streaming players request the media in small fragments, there is also a URL for each fragment (which differ for each type of adaptive streaming format). So a single client requests a single manifest file, but this is followed by tens/hundreds of fragment requests.
| URL to the fragments | Description |
|---|---|
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/QualityLevels(755000)/Fragments(video_eng=0) | A Smooth Streaming fragment. |
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/tears-of-steel-audio_eng=134998-video_eng=407000-1.ts | An HTTP Live Streaming MPEG-TS fragment. |
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/tears-of-steel-audio_eng=134998-video_eng=755000-Seg1-Frag1 | An HTTP Dynamic Streaming fragment. |
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/tears-of-steel-audio_eng=134998-video_eng=407000-0.dash | An MPEG DASH fragment. |
The URL can be extended by adding query parameters at the end of the URL (using ? and &). Any options unknown to the webserver module are passed along to all the underlying URLs. For example you can tag on a unique session_id to the media presentation URL.
| URL to the media presentation | Description |
|---|---|
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/Manifest?session_id=4157 | The Smooth Streaming client manifest. |
The following returns a similar manifest file as previously, but adds
?session_id=4157 to any underlying requests made by the player.
| URL to the fragments | Description |
|---|---|
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/QualityLevels(755000)/Fragments(video_eng=1)?session_id=4157 | A Smooth Streaming fragment. |
Virtual subclips¶
The ability to request a time bounded manifest/playlist. We call this ‘virtual video clips’ and this allows you to create multiple subclips from one larger archived presentation.
Creating a preview clip is an obvious example.
When requesting the manifest file you can add the virtual beginning (vbegin) and virtual ending (vend) to specify the timespan of the manifest file generated.
| URL to the media presentation | Description |
|---|---|
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/.mpd?vbegin=60&vend=90 | A 60 seconds clip starting at 00:01:00 and ending at 00:01:30. |
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/.mpd?vbegin=60 | The whole presentation, but the first 60 seconds are skipped. |
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/.mpd?vend=90 | The first 1.5 minutes of the presentation. |
Some player frameworks have an issue parsing multiple query parameters.
Using the t parameter to specify a time range is the preferred method:
| URL to the media presentation | Description |
|---|---|
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/Manifest?t=00:01:00-00:01:30 | A 30 seconds clip starting after the first minute. |
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/Manifest?t=00:01:00 | The whole presentation, but the first 60 seconds are skipped. |
If you are using a Silverlight player framework that supports Composite Manifest
you can request the virtual subclip with the .csm extension.
| URL to the media presentation | Description |
|---|---|
| http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/tears-of-steel.csm?t=00:01:00-00:01:30 | A 30 seconds clip starting after the first minute. |
Attention
Accurate subclipping of live streams requires coordinated universal time. See: Coordinated Universal Time (UTC).
Player configuration for virtual subclips¶
Note
To avoid the below problem altogether, make sure that the start of each GOP is also the start of an audio frame, as described in Stream alignment.
A subclip might start with a short audio or video gap, which can cause problems for certain players:
DASH.js¶
When an audio gap is present at the start of a clip, DASH.js 2.6.6 and above will not play back the clip. To solve this issue, the maximum gap tolerance needs to be set explicitly:
player.setSegmentOverlapToleranceTime(2);
The value of this setting should be higher than the fragment duration of your DASH stream.
Shaka Player¶
When a gap is present at the start of clip Shaka Player will start playback,
but get stuck when seeking to the start of the clip. To solve this issue,
the configuration for jumpLargeGaps needs to be set to ‘true’, as explained
in the Shaka Player Gap Jumping documentation.
Pass a player URL to a player¶
If you have constructed a player URL (taking into account the URL escaping rules
for query parameters) you may want to pass the full player URL as a query parameter
to a player. This is for example how the provided players at
http://demo.unified-streaming.com are setup.
They use the following template:
http://demo.unified-streaming.com/players/{PLAYER}/player.html?file=<player_URL>
Since the player URL is passed as a query parameter to the player HTML page, the previously constructed player URL needs to be properly escaped.
For example, say you create a subclip of a presentation with beginning and ending parameters:
http://demo.unified-streaming.com/video/tears-of-steel/tears-of-steel.ism/.f4m?t=00:06:00-00:07:30
and using the flowplayer player available at:
http://demo.unified-streaming.com/players/flowplayer/player.html?file=<player_URL>
the resulting URL is:
Note that all the reserved characters in the player URL are escaped since it is passed as a query parameter.
In JavaScript you should use the encodeURIComponent function, in PHP you
should use the urlencode function.