HLS

UCDN
2019-11-04 11:48

INTRODUCTION

The usage of VOD service is available for CDN zones for big objects, which are such by default.

In order to use HLS you need to create a zone for big objects (they are such by default) and generate m3u8 link for the mp4 file to be played. This is done by prefixing '/hls' to the path and appending /index.m3u8 at the end. Please note that you need to only upload your full mp4 files and segmentation is done by the CDN. 

Example:

mp4_file: /video/012345.mp4
m3u8_path: /hls/video/012345.mp4/index.m3u8

The returned m3u8 file will have the corresponding segments for the mp4 file. The default values for  first segment and the other segmens are 5 seconds and 10 seconds respectively.

You can change them by using parameters bsd (first few segments) and sd(other segments) in the URL.

Example:

mp4_file: /video/012345.mp4
m3u8_path: /hls/bsd/10000-10000-15000/sd/20000/video/012345.mp4/index.m3u8

In the provided example we set the initial segment to be 10 seconds, the second again 10 seconds, the third is 15 seconds  and the rest to be 20 seconds. Please note that the values should be in milliseconds.

 Another important thing to notice is that the segment are with relative paths as per the specification: 
https://tools.ietf.org/html/draft-pantos-http-live-streaming-17.

Which means that the absolute path for segment 'seg-5-v1-a1.ts' is /hls/video/012345.mp4/seg-5-v1-a1.ts, not /seg-5-v1-a1.ts.

URLSET

Additionally there is functionality to build a playlist from multiple files. This can be used when for a given video source there are multiple resolutions, and we would like the user to be able to change between them without changing the page.

For the example let's say that we have the previous file /video/012345.mp4 in 3 resolutions 240p, 360p and 480p and we have named them /012345_240p.mp4 , /012345_360p.mp4 and /012345_480p.mp4 accordingly.

If we request: 
/hls/video/012345_,24,36,48,0p.mp4/urlset/master.m3u8,
where you can see that the common parts are "012345_" and "0p.mp4" and we divide by commas the three different bitrates - 24,36,48

we will get a playlist which looks like:

#EXTM3U
#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=368981,RESOLUTION=426x240,FRAME-RATE=24.000,CODECS="avc1.4d4015,mp4a.40.2"
/hls/012345_240p.mp4/index.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=460061,RESOLUTION=640x360,FRAME-RATE=24.000,CODECS="avc1.4d401e,mp4a.40.2"
/hls/012345_360p.mp4/index.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=789049,RESOLUTION=854x480,FRAME-RATE=24.000,CODECS="avc1.4d401e,mp4a.40.2"
/hls/012345_480p.mp4/index.m3u8

This is the master playlist which has a playlist for each of the files provided with additional info for the streams in each of the playlist.

It's important  that the end is master.m3u8 not index.m3u8 as with playlist for only one file.

It should be also noted that the playlist inside the master playlist, have the same url as the one that can be used for the individual urls. 

VTT Subtitles

UCDN supports multi-language subtitles in VTT format for HLS streaming. In order to demonstrate the feature we will use the same example /video/012345.mp4. In addition we will assume that the subtitles are in the same folder /video or in subfolder /video/subs/.

Example:

/hls/video/,lang/eng/012345_eng.vtt,lang/ger/012345_ger.vtt,012345.mp4,/urlset/master.m3u8
/hls/video/,subs/lang/eng/012345_eng.vtt,subs/lang/ger/012345_ger.vtt,012345.mp4,/urlset/master.m3u8

There should be noted several things for the above request path:

  • we use urlset and master.m3u8 to load the subtitles in the playlist, not standard playlist index.m3u8
  • we specify the common path first, which in the example is /video
  • required part for the URL is lang/ISO 639-2  which is three-letter country code. You can find all codes on this page:
    https://www.loc.gov/standards/iso639-2/php/code_list.php
  • if the subtitles are in subfolder, the folder should be before the require part.
  • all commas are intentional

SECURITY TOKEN

Our HLS functionallity supports the use of security token in order to block any hotlinking attemps. You can check for more information here:
https://help.ucdn.com/content/44/9/en/limit-access.html#token

Combining all features in order to generate security token you should include the following part:

/video/bsd/10000-10000-15000/sd/20000/,lang/eng/012345_eng.vtt,lang/ger/012345_ger.vtt,012345_,24,36,48,0p.mp4,

Note that the prefix /hls and suffixes urlset/master.m3u8 and /index.m3u8 are excluded

All the segments have security tokens attached to them when returned inside the m3u8 file. So there is no need to recalculate it for each of them before requesting them. 

Because the security token is the same one (including all parameters) for the m3u8 file it's important to note that for longer videos it's possible that the security token can expire before a request for the given segment is made.