HLS

Once you complete your Media Services Live: HLS Ingest setup, you need to configure your encoder to capture and push your stream to the entrypoints.

For a list of third-party live encoders and the latest software versions qualified with Media Services Live HLS ingest, see Qualified Encoders (MSL 3.2 & MSL 4.x).

📘

For previously qualified third-party live encoder software versions, contact your account representative.

Media Services Live: HLS Ingest does not honor the live encoder HTTP DELETE requests. The servers return a 200 HTTP status code, but the content is not actually deleted as requested.

To prevent stream vulnerability to potential network problems, you must actively use both primary and backup streams. This adds redundancy by implementing an automatic failover feature should one stream or the other fail. The easiest way to use primary/backup streams is to set them up in a single encoder. Not all third-party encoders support this, however, and with those it becomes necessary to use separate encoders to stream primary and backup.

While primary/backup streaming is possible with dual encoders, it is not automated and requires certain manual steps to enable it. With typical single encoder primary/backup functionality, the encoder automatically creates a variant playlist that includes all primary and backup bitrates. This ensures that the primary and backup streams are always aware of each other's existence and allows for automatic failover from one to the other. With situations that require dual encoders, this automatic playlist generation does not occur. Here, each encoder creates variant playlists for the primary or backup stream only, requiring manual manipulation to create a merged playlist that includes both primary and backup streams. Refer to Create your Media Services Live streams.

In addition, there might be circumstances where you need dual encoders in two separate geographical locations, with one streaming the primary and the other streaming the backup. In this case, even encoders that support primary/backup from a single encoder will require the dual encoder solution with regard to variant playlist generation.

Publish HLS streams

The encoder publishes primary and backup streams for the HLS protocol according to this URL syntax.

Stream typeHostnamePathExample
Primaryp-ep{stream_id}.i.akamaientrypoint.net {stream_id}/{event_name} http://p-ep50002.i.akamaientrypoint.net/50002/test79/master.m3u8
Backupb-ep{stream_id}.i.akamaientrypoint.net {stream_id}-b/{event_name} http://b-ep50002.i.akamaientrypoint.net/50002-b/test79/master.m3u8

📘

To improve security and reduce potential vulnerabilities, ​Akamai​ supports TLS 1.2 and above in accordance with Internet Engineering Task Force recommendations.

The MSL system considers a stream as a combination of stream_idand event_name. All ingested content, such as variant playlists, bitrate playlists, and segments, should have a common event_namein the path.

Play HLS streams

To play HLS streams, construct the URL according to this syntax.

https://amd-property-hostname/hls/live/stream-id/event_name/master.m3u8

The amd-property-hostname depends on the CDN that you use. For ​Akamai​ CDN, the hostname is origin.akamaized.net, so the playback URL is:

http://origin.akamaized.net/hls/live/50002/test79/master.m3u8
StreamPathExample
Primaryhls/live/[stream_id]/[event_name]/[filename].m3u8
http://origin.akamaized.net/hls/live/50002/test79/master.m3u8
Backuphls/live/[stream_id]-b/[event_name]/[filename].m3u8
http://origin.akamaized.net/hls/live/50002-b/test79/master.m3u8

Example .m3u8 file

The playback information is embedded in the variant .m3u8 file. Backup URLs are shown in this example, note the -b in the path.


#EXTM3U
#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=648224,RESOLUTION=640x360,CODECS="avc1.4d401e,mp4a.40.2"
http://origin.akamaized.net/hls/live/50002/test/01.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=648224,RESOLUTION=640x360,CODECS="avc1.4d401e,mp4a.40.2"
http://origin.akamaized.net/hls/live/50002-b/test/01.m3u8 #EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=443680,RESOLUTION=400x224,CODECS="avc1.42e00d,mp4a.40.2"
http://origin.akamaized.net/hls/live/500002/test/02.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=443680,RESOLUTION=400x224,CODECS="avc1.42e00d,mp4a.40.2"
http://origin.akamaized.net/hls/live/50002-b/test/02.m3u8 #EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=956544,RESOLUTION=640x720,CODECS="avc1.4d401f,mp4a.40.2"
http://origin.akamaized.nett/hls/live/50002/test/03.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=956544,RESOLUTION=640x720,CODECS="avc1.4d401f,mp4a.40.2"
http://origin.akamaized.net/hls/live/50002-b/test/03.m3u8 

👍

To check the quality of your HLS streaming content, you can use any iOS device or: http://players.akamai.com/players/hlsjs.

Create a merged variant playlist

To create a merged playlist, you must extract the variant playlists from each encoder and manually merge them. For example, assume a primary variant playlist URL of:

http://origin.akamaized.net/hls/live/50002/event/master.m3u8

Start your encoder, and then use the UNIX curl command to acquire the variant playlist's contents.

curl http://origin.akamaized.net/hls/live/50002/event/master.m3u8

#EXTM3U
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=165135
http://origin.akamaized.net/hls/live/50002/event/iphone110.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=262346
http://origin.akamaized.net/hls/live/50002/event/iphone200.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=481677
http://origin.akamaized.net/hls/live/50002/event/iphone400.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=688301
http://origin.akamaized.net/hls/live/50002/event/ipad600.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=894877
http://origin.akamaized.net/hls/live/50002/event/ipad800.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=1308077
http://origin.akamaized.net/hls/live/50002/event/ipad1200.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=40000
http://origin.akamaized.net/hls/live/50002/event/iphone110audio.m3u8

👍

Notice that each line denotes a different bitrate.

Now, do the same for the backup variant playlist URL:

http://origin.akamaized.net/hls/live/50002-b/event/master.m3u8


curl http://origin.akamaized.net/hls/live/50002-b/event/master.m3u8

#EXTM3U
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=165135
http://origin.akamaized.net/hls/live/50002-b/event/iphone110.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=262346
http://origin.akamaized.net/hls/live/50002-b/event/iphone200.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=481677
http://origin.akamaized.net/hls/live/50002-b/event/iphone400.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=688301
http://origin.akamaized.net/hls/live/50002-b/event/ipad600.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=894877
http://origin.akamaized.net/hls/live/50002-b/event/ipad800.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=1308077
http://origin.akamaized.net/hls/live/50002-b/event/ipad1200.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=40000
http://origin.akamaized.net/hls/live/50002-b/event/iphone110audio.m3u8

Manually merge the contents of each of these files to produce the following:


#EXTM3U
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=165135
http://origin.akamaized.net/hls/live/50002/event/iphone110.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=165135
http://origin.akamaized.net/hls/live/50002-b/event/iphone110.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=262346
http://origin.akamaized.net/hls/live/50002/event/iphone200.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=262346
http://origin.akamaized.net/hls/live/50002-b/event/iphone200.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=481677
http://origin.akamaized.net/hls/live/50002/event/iphone400.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=481677
http://origin.akamaized.net/hls/live/50002-b/event/iphone400.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=688301
http://origin.akamaized.net/hls/live/50002/event/ipad600.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=688301
http://origin.akamaized.net/hls/live/50002-b/event/ipad600.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=894877
http://origin.akamaized.net/hls/live/50002/event/ipad800.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=894877
http://origin.akamaized.net/hls/live/50002-b/event/ipad800.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=1308077
http://origin.akamaized.net/hls/live/50002/event/ipad1200.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=1308077
http://origin.akamaized.net/hls/live/50002-b/event/ipad1200.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=40000
http://origin.akamaized.net/hls/live/50002/event/iphone110audio.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=40000
http://origin.akamaized.net/hls/live/50002-b/event/iphone110audio.m3u8

Notice that each bitrate in the list has a primary and a backup associated with it.

Finally, use the curl command to post the file to the primary ingress URL.


curl -T master.m3u8 http://p-ep50002.i.akamaientrypoint.net/50002/event/index.m3u8

📘

As shown in the curl upload example, ensure that the merged variant playlist name is different from existing playlist names so that it is not overwritten. For example, if master.m3u8 is used by your primary and backup, you can rename the merged playlist to index.m3u8 or playlist.m3u8. If master.m3u8 is used by your primary and playlist.m3u8 is used by your backup, you could rename the merged playlist to index.m3u8.

Options for HLS streams

Use HTTPS

Media Services Live lets you ingest and deliver all content over HTTPS or HTTP. Live encoders that are able to broadcast using the HTTPS protocol are compatible with Media Services Live: HLS Ingest under these conditions.

  • Ingest. You can upload the master variant playlist, child playlist, audio and video (ts, aac) segments, and keys over both HTTP and HTTPS.

  • Playback. You can deliver all content over HTTP or HTTPS. You can deliver the child playlist and audio and video content over HTTP or HTTPS and the keys and master variant playlist over HTTPS. Token authentication for delivery is supported. Primary/backup failover is supported.

📘

Once your key file is published, it is cached for 24 hours. If you need to upload a new key, use a different file name. If you fail to do this, your stream viewers may experience temporary playback failures. You should rotate your keys either every 30 segments if you are using 10-second segments, or every 5 minutes of stream time.

Add subtitles

Subtitling is a process of overlaying video with text. This can be done for accessibility for hearing-impaired people, language translation, or any other reason a producer chooses. Subtitles can be passed to a viewer in an accompanying "sidecar" file.

The supported file formats are WebVTT (Web Video Text Tracks) and VTT. The sidecar format WebVTT or VTT is specified by W3C at: http://dev.w3.org/html5/webvtt/.

Unique segment numbering

Segments generated by the encoder must be created with sequentially increasing segment numbers such as 1, 2, and 3. For example:

https://p-ep{stream_id}.i.akamaientrypoint.net/<stream_id>/<uniquesourcename>/<sessionID>/<bitrateID>/<OPTIONAL_PATH>/<somename>_<sequence#>.ts

https://p-ep{stream_id}.i.akamaientrypoint.net/<stream_id>/<uniquesourcename>/<sessionID>/<bitrateID>/<OPTIONAL_PATH>/segment_0001.ts
https://p-ep{stream_id}.i.akamaientrypoint.net/<stream_id>/<uniquesourcename>/<sessionID>/<bitrateID>/<OPTIONAL_PATH>/segment_0002.ts
https://p-ep{stream_id}.i.akamaientrypoint.net/<stream_id>/<uniquesourcename>/<sessionID>/<bitrateID>/<OPTIONAL_PATH>/segment_0003.ts

The segment number must be extractable from the upload URL using regex. Ensure that you separate the string and the numbers of a segment. Segment names can contain alphanumeric characters and the hyphen (-) as delimiters. Other special characters are not supported. The last item before the prefix must be a unique, sequentially increasing number. You cannot use symbols, special characters, or alphabets. For example:

bitrate1000-00012.ts

<sessionId>/bitrateA_12.ts

<sessionId>/1-123.ts

<sessionId>_1_123.ts

<sessionId>/P2-2-1001.ts(with directory rollover)

The path and segment number are treated as one entity; therefore, they must not repeat. Archived data becomes corrupted when the encoder restarts and attempts to use the previous sequence number and path.

You can use either a unique segment number or a unique session ID. The encoder must not introduce any other changing parameters such as frequently changing time stamps in the URL path. For example, if the URL path format was: eventname/sessionID/bitrateID/post-timestamp_sequence#.ts

Introducing the post-timestampparameter creates another set of directories for each .ts file — a condition that would cause excess directories and possible timeouts over long periods of time.

Ideally, create the URL path like this: eventname/sessionID/bitrateID/somename-starttime-sequence#.ts

In this case, only the sequence# changes, which is the desired behavior.


Did this page help you?