Player URLs
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 |
|---|---|
The HTTP Smooth Streaming client manifest. |
|
https://demo.unified-streaming.com/k8s/features/stable/video/tears-of-steel/tears-of-steel.ism/.m3u8 |
The master .m3u8 playlist for HTTP Live Streaming |
https://demo.unified-streaming.com/k8s/features/stable/video/tears-of-steel/tears-of-steel.ism/.f4m |
The HTTP Dynamic Streaming manifest. |
https://demo.unified-streaming.com/k8s/features/stable/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 |
|---|---|
A Smooth Streaming fragment. |
|
An HTTP Live Streaming MPEG-TS fragment. |
|
An HTTP Dynamic Streaming fragment. |
|
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 |
|---|---|
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 |
|---|---|
A Smooth Streaming fragment. |
Virtual subclips
Request a stream with a specified time range to generate a new stream that represents that time range. We call such a new stream a 'virtual subclip'. They can be generated from Live and VOD sources. Virtual subclips are GOP accurate and inclusive, so that a Origin will include the full GOP if a start or end time of a time range falls within a GOP instead of on a GOP boundary.
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 |
|---|---|
A 60 seconds clip starting at 00:01:00 and ending at 00:01:30. |
|
The whole presentation, but the first 60 seconds are skipped. |
|
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 |
|---|---|
A 30 seconds clip starting after the first minute. |
|
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 |
|---|---|
A 30 seconds clip starting after the first minute. |
Attention
Accurate subclipping of live streams requires coordinated universal time. See: Must Fix: use of UTC timestamps.
Note
Some smart TV's do not properly handle virtual subclips generated from a
livestream and delivered as Smooth, in scenarios where both the start and end
time of the subclip are in the past (making the clip 'static' instead of
'dynamic'). The reason for this is that such clips have a very high starting
time (indicated by the high value for the t parameter at start of media's
timeline in the Smooth client manifest). This can be worked around with a
rewrite on the edge (i.e., rewriting said client manifest and also the segment
requests to make the clip start at '0'). Another solution is to use
Unified Remix - nPVR instead, as the VOD clips generated from livestreams by that
solution start at '0' by default.
Player configuration for virtual subclips
Note
To avoid the problem described below altogether, make sure that the start of each GOP is also the start of an audio frame, as described in Content Preparation.
A subclip might start with a short audio or video gap (due to misalignment between audio and video segments) 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 a clip Shaka Player will appear to start playback, but get stuck when seeking to the start of the clip. In the JavaScript console, a message will be logged similar to:
gap_jumping_controller.js:226 Ignoring large gap at 0 size 1.907336
To solve this issue, the configuration for jumpLargeGaps needs to be set to
'true', as explained in the Shaka Player Gap Jumping documentation.
URI encoding required
If you have constructed a playout URL you may want to pass the full playout URL as a query parameter to a player.
Since the playout URL is passed as a query parameter to the player HTML page, the previously constructed player URL needs to be properly escaped (see RFC 3986 for the details).
For example, say you create a subclip of a presentation with beginning and ending parameters:
https://demo.unified-streaming.com/k8s/features/stable/video/tears-of-steel/tears-of-steel.ism/.f4m?t=00:06:00-00:07:30
and your player is embedded in a file called 'player.html' accepting URLs:
https://example.com/player.html?url=<URL>
the URL passed should look like:
https://example.com/player.html?url=http%3A%2F%2Fdemo.unified-streaming.com%2Fvideo%2Ftears-of-steel%2Ftears-of-steel.ism%2F.f4m%3Ft%3D00%3A06%3A00-00%3A07%3A30
All the reserved characters in the playout URL are escaped since it is passed as a query parameter.
JavaScript for instance has the encodeURIComponent function, in PHP there
is the urlencode function - other programming or script languages will have
an equivalent function.