HLS¶

HTTP Live Streaming (also known as HLS) is an HTTP-based media streaming communications protocol implemented by Apple Inc. as part of its QuickTime, Safari, OS X, and iOS software. It resembles MPEG-DASH in that it works by breaking the overall stream into a sequence of small HTTP-based file downloads, each download loading one short chunk of an overall potentially unbounded transport stream. As the stream is played, the client may select from a number of different alternate streams containing the same material encoded at a variety of data rates, allowing the streaming session to adapt to the available data rate. At the start of the streaming session, HLS downloads an extended M3U playlist containing the metadata for the various sub-streams which are available.

Shaka Packager supports HLS content packaging. This tutorial covers HLS packaging of VOD content without encryption. For live content packaging, see Live; for content encryption, see DRM.

Synopsis¶

$ packager {stream_descriptor with HLS specific descriptors} \
           [stream_descriptor with HLS specific descriptors] ... \
  --hls_master_playlist_output {master playlist output path} \
  [Other HLS options] \
  [Other options, e.g. DRM options, DASH options]

See HLS specific stream descriptor fields for the available HLS specific stream descriptor fields.

See HLS options for the available HLS related options.

Note

DASH and HLS options can both be specified to output DASH and HLS manifests at the same time. Note that it works only for MP4 outputs.

Examples¶

The examples below uses the H264 streams created in Media Encoding.

TS output:

$ packager \
  'in=h264_baseline_360p_600.mp4,stream=audio,output=audio_$Number$.ts,playlist_name=audio.m3u8,hls_group_id=audio,hls_name=ENGLISH' \
  'in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p_$Number$.ts,playlist_name=h264_360p.m3u8' \
  'in=h264_main_480p_1000.mp4,stream=video,output=h264_480p_$Number$.ts,playlist_name=h264_480p.m3u8' \
  'in=h264_main_720p_3000.mp4,stream=video,output=h264_720p_$Number$.ts,playlist_name=h264_720p.m3u8' \
  'in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p_$Number$.ts,playlist_name=h264_1080p.m3u8' \
  --hls_master_playlist_output h264_master.m3u8

The above packaging command creates five single track TS streams (4 video, 1 audio) and a manifest, which describes the streams.

MP4 output is also supported:

$ packager \
  'in=h264_baseline_360p_600.mp4,stream=audio,init_segment=audio_init.mp4,segment_template=audio_$Number$.m4s,playlist_name=audio.m3u8,hls_group_id=audio,hls_name=ENGLISH' \
  'in=h264_baseline_360p_600.mp4,stream=video,init_segment=h264_360p_init.mp4,segment_template=h264_360p_$Number$.m4s,playlist_name=h264_360p.m3u8' \
  'in=h264_main_480p_1000.mp4,stream=video,init_segment=h264_480p_init.mp4,segment_template=h264_480p_$Number$.m4s,playlist_name=h264_480p.m3u8' \
  'in=h264_main_720p_3000.mp4,stream=video,init_segment=h264_720p_init.mp4,segment_template=h264_720p_$Number$.m4s,playlist_name=h264_720p.m3u8' \
  'in=h264_main_1080p_6000.mp4,stream=video,init_segment=h264_1080p_init.mp4,segment_template=h264_1080p_$Number$.m4s,playlist_name=h264_1080p.m3u8' \
  --hls_master_playlist_output h264_master.m3u8

Single file MP4 output is also supported:

$ packager \
  in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4,playlist_name=audio.m3u8,hls_group_id=audio,hls_name=ENGLISH \
  in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p.mp4,playlist_name=h264_360p.m3u8 \
  in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4,playlist_name=h264_480p.m3u8 \
  in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4,playlist_name=h264_720p.m3u8 \
  in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4,playlist_name=h264_1080p.m3u8 \
  --hls_master_playlist_output h264_master.m3u8

The above packaging command creates five groups of streams (each with an init segment and a series of media segments) and a manifest, which describes the streams.

HLS specific stream descriptor fields¶

hls_name:	Required for audio when outputting HLS. name of the output stream. This is not (necessarily) the same as output. This is used as the NAME attribute for EXT-X-MEDIA.
hls_group_id:	Required for audio when outputting HLS. The group ID for the output stream. This is used as the GROUP-ID attribute for EXT-X-MEDIA.
playlist_name:	Required for HLS output. Name of the playlist for the stream. Usually ends with ‘.m3u8’.

HLS options¶

`--hls_master_playlist_output <file_path>`
	Output path for the master playlist for HLS. This flag must be used to output HLS.
`--hls_base_url <url>`
	The base URL for the Media Playlists and media files listed in the playlists. This is the prefix for the files.
`--hls_playlist_type <type>`
	VOD, EVENT, or LIVE. This defines the EXT-X-PLAYLIST-TYPE in the HLS specification. For hls_playlist_type of LIVE, EXT-X-PLAYLIST-TYPE tag is omitted.

Segment template formatting¶

The implementation is based on Template-based Segment URL construction described in ISO/IEC 23009-1:2014.

Supported identifiers¶
$<Identifier>$	Substitution parameter	Format
$$	is an escape sequence, i.e. “$$” is replaced with a single “$”.	Not applicable.
$Number$	This identifier is substitued with the number of the corresponding Segment.	The format tag may be present. If no format tag is present, a default format tag with width=1 shall be used.
$Time$	This identifier is substituted with the value of the SegmentTimeline@t attribute for the Segment being accessed. Either $Number$ or $Time$ may be used but not both at the same time.	The format tag may be present. If no format tag is present, a default format tag with width=1 shall be used.

Note

Identifiers $RepresentationID$ and $Bandwidth$ are not supported in this version. Please file an issue if you want it to be supported.

In each URL, the identifiers shall be replaced by the substitution parameter per the definition in the above table. Identifier matching is case-sensitive.

Each identifier may be suffixed, within the enclosing ‘$’ characters, with an additional format tag aligned with the printf format tag as defined in IEEE 1003.1-2008 following this prototype:

%0[width]d

The width parameter is an unsigned integer that provides the minimum number of characters to be printed. If the value to be printed is shorter than this number, the result shall be padded with zeros. The value is not truncated even if the result is larger.

Strings outside identifiers shall only contain characters that are permitted within URLs according to RFC 3986.

Table Of Contents

Previous topic

Next topic

This Page