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

https://demo.unified-streaming.com/k8s/features/stable/video/tears-of-steel/tears-of-steel.ism/Manifest

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

https://demo.unified-streaming.com/k8s/features/stable/video/tears-of-steel/tears-of-steel.ism/QualityLevels(751000)/Fragments(video_eng=0)

A Smooth Streaming fragment.

https://demo.unified-streaming.com/k8s/features/stable/video/tears-of-steel/tears-of-steel.ism/tears-of-steel-audio_eng=64008-video_eng=401000-1.ts

An HTTP Live Streaming MPEG-TS fragment.

https://demo.unified-streaming.com/k8s/features/stable/video/tears-of-steel/tears-of-steel.ism/tears-of-steel-audio_eng=64008-video_eng=751000-Seg1-Frag1

An HTTP Dynamic Streaming fragment.

https://demo.unified-streaming.com/k8s/features/stable/video/tears-of-steel/tears-of-steel.ism/tears-of-steel-audio_eng=64008-video_eng=401000-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

https://demo.unified-streaming.com/k8s/features/stable/video/tears-of-steel/tears-of-steel.ism/Manifest

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

https://demo.unified-streaming.com/k8s/features/stable/video/tears-of-steel/tears-of-steel.ism/QualityLevels(751000)/Fragments(video_eng=0)

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

https://demo.unified-streaming.com/k8s/features/stable/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.

https://demo.unified-streaming.com/k8s/features/stable/video/tears-of-steel/tears-of-steel.ism/.mpd?vbegin=60

The whole presentation, but the first 60 seconds are skipped.

https://demo.unified-streaming.com/k8s/features/stable/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

https://demo.unified-streaming.com/k8s/features/stable/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.

https://demo.unified-streaming.com/k8s/features/stable/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

https://demo.unified-streaming.com/k8s/features/stable/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: 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.