HTTP Live Streaming or HLS video requires that a media stream or file be segmented into a series of small media files of equal duration. This is usually accomplished using a tool that will segment the individual files and create a playlist.
This architecture allows for a live stream that has already been segmented to be quickly converted to a VOD stream just by updating the playlist.
There are two command-line tools available to you from Apple for segmentation of HTTP Live Streaming media. The tools are:
- Media Stream Segmenter
- Media File Segmenter
IMPORTANT: Both tools are frequently updated. If you are an iPhone Developer Program member or a Mac or ADC Select or Premier member, you can download the latest versions from the Apple Developer Connection website. To download, go to http://connect.apple.com, click on the ‘Downloads’ link, click on ‘QuickTime’, scroll down to the ‘HTTP Live Streaming Tools’, download and install the ‘HTTP Live Streaming Tools’.
Media Stream Segmenter Tool
You can use the Media Stream Segmenter (
mediastreamsegmenter) tool for deployment of HTTP Live Streaming Media.
mediastreamsegmenter is also included with Mac OS X, version 10.6 and later. It can be found on your system disk at
/usr/bin/mediastreamsegmenter. ( The
/usr/bin directory is hidden from the Finder, but is accessible using the Terminal application, located in the Utilities folder.)
This tool receives an MPEG-2 transport stream over a UDP network connection or from
stdin and divides it into a series of small media segments of equal duration. It then creates an index file containing references to the individual media segments. The index file and media segments can be deployed using almost any web server infrastructure for streaming to iPhone OS and Mac OS X 10.6 Snow Leopard. The
mediastreamsegmenter produces either live or Video on Demand (VOD) streams.
mediastreamsegmenter tool accepts different command line arguments (you can obtain a list of the command line arguments and their meanings by typing
man mediastreamsegmenter from the Terminal application, or see the online man page). This tool can produce an audio-only stream if you specify the following argument:
-a | -audio-only
This strips the audio elementary stream (AAC/ADTS or MP3) and writes it into the media file. You could, for example, run the
mediastreamsegmenter on an existing audio/video stream to get an audio-only stream.
Here’s an example showing how to use the
mediastreamsegmenter to capture and create an unencrypted live stream:
mediastreamsegmenter -s 3 -D -f /Library/WebServer/Documents/stream 188.8.131.52:20103
-s option defines the number of media file entries that should be kept in the index file. The default is 5. The
-D option (in a live stream) will specify that the media files that are no longer in the index file will be removed after an expiry period. The
-f option specifies the directory to store the media and index files.
In this example, the index file will contain 3 items. Media files will be removed after an expiry period. The media and index files will be stored in
Media File Segmenter Tool for HLS video
The media file segmenter (
mediafilesegmenter) is a command-line tool that segments media files for deployment using HTTP Live Streaming. The
mediafilesegmenter takes media from the specified file, multiplexes it into MPEG-2 Transport streams if required, and divides it into a series of small media files of approximately equal duration.
mediafilesegmenter accepts media from a file. Use the Media Stream Segmenter Tool to receive a stream over a network connection or from
mediafilesegmenter also creates an index file containing references to the individual media files. The index file and media files can then be deployed as a VOD stream using common web server infrastructure.
mediafilesegmenter tool accepts many different command line arguments (you can obtain a list of the command line arguments and their meanings by typing
man mediafilesegmenter from the Terminal application).
Note: Previous versions of the tool required you specify the
-optimize option to turn on optimization, otherwise it was off by default. With the new tool, optimization is on by default, and you must now specify
no as a qualifier as shown here:
[-O | -optimize [yes | no]]
A streaming multimedia presentation is specified by a Playlist file, which is a list of media file resources, each of which refers to a segment of a single contiguous stream. A server may offer multiple Playlist files to provide different encodings of the same presentation when HTTP Live Streaming. If it does, it should provide a Variant Playlist file (also known as a Stream Alternate) that lists each variant stream to allow clients to switch between encodings dynamically if the available bandwidth changes.
See the HTTP Live Streaming Overview and the HTTP Live Streaming Protocol Specification for additional information about Variant Playlists.
Variant Playlist Creator Tool
The Variant Playlist Creator (
variantplaylistcreator) is a command line tool that will create a variant playlist in the m3u8 format for stream switching for HTTP Live Streaming segments created by
mediafilesegmenter. iPhone Developer Program members and Mac and ADC Select or Premier members can download the tool as part of the HTTP Live Streaming Tools package as described in Media Segmentation.
variantplaylistcreator takes pairs of URLs and plist files generated using the
-generate-variant-info option from
mediafilesegmenter and creates a variant stream playlist. You can obtain a list of all the command line arguments and their meanings by typing
man variantplaylistcreator from the Terminal application.
Important considerations when creating Variant Playlists
Here are some important points to consider when creating your own Variant Playlists:
- Choosing the initial variant to be playedThe first entry in the Variant Playlist will be played at the initiation of a stream and is used as part of a test to determine which stream is most appropriate. The order of the other streams is irrelevant.
You should create multiple playlists that have the same set of streams, but each with a different first entry that is appropriate for the target network. This ensures the user has a good experience when the stream is first played.
We recommend you point to a 150k stream for the cellular Variant Playlist.
We recommend you point to a 240k or 440k stream for the Wi-Fi Variant Playlist.
See Recommended Encoding Settings for HTTP Live Streaming Media.
- Where possible, encode enough variants to provide the best quality stream across a wide range of connection speedsFor example, encode variants at 150 kbps, 350 kbps, 550 kbps, 900 kbps, 1500 kbps.
- When possible, use relative path names in Variant Playlists and in the individual .m3u8 Playlist files
- HLS Video and Audio Stream ConsiderationsThe audio streams should be exactly the same.
Video aspect ratio must be exactly the same, but can be different dimensions.
We recommend 400 x 224 for 16:9 content and 400 x 300 for 4:3 content (see Recommended Encoding Settings for HTTP Live Streaming Media).
Note: One easy way to synchronize different VOD stream files is to copy the audio track of one Variant Playlist member file into each of the other member files.
HTML5 video element
We recommend you use the HTML5
video element to display video in Safari on iPhone OS. For more information about the
video element, see the Safari Guide to HTML5 Audio and Video and the
HTMLAudioElement class references in the Safari DOM Extensions Reference.
The source code example in Listing 1 demonstrates how to use the
video element to display HTTP Live Streaming video in a web page.
Listing 1: HTML5 video element example.
This browser does not support HTML5 video.
See also Technical Note TN2262, ‘Preparing Your Web Content for iPad’ which describes platform-specific considerations for web content in Safari on iPhone OS devices, with specific information for iPad.
Web Server Configuration
The distribution system for HTTP Live Streaming media is a web server or a web caching system that delivers the media files and index files to the client over HTTP (see the HTTP Live Streaming Overview for more information). No custom server modules are required to deliver the content, and typically very little configuration is needed on the web server.
Recommended configuration is typically limited to specifying MIME-type associations for
.M3U8 files and
Table 1 : MIME-type associations for
.M3U8 files and
|vnd.apple.mpegURL or application/x-mpegURL
Servers that are constrained for compatibility can serve files ending in
.m3u with MIME type
Tuning time-to-live (TTL) values for
.M3U8 files may also be necessary to achieve desired caching behavior for downstream web caches, as these files are frequently overwritten, and the latest version should be downloaded for each request. Check with your content delivery service provider for specific recommendations.
Media Stream Validation
Media Stream Validator Tool
The Media Stream Validator (
mediastreamvalidator) is a command-line tool to validate HTTP Live Streaming streams and servers. iPhone Developer Program members and Mac and ADC Select or Premier members can download the tool as part of the HTTP Live Streaming Tools package as described in Media Segmentation.
This tool simulates an HTTP Live Streaming session and verifies that the index file and media segments conform to the HTTP Live Streaming specification. It performs several checks to ensure reliable streaming. If any errors or problems are found, a detailed diagnostic report is displayed.
IMPORTANT: You should always run the
mediastreamvalidator tool on your stream to verify that it conforms to the HTTP Live Streaming specification.
Here’s example output from the
Listing 2: Example validator tool output.
Validating http://devimages.apple.com/iphone/samples/bipbop/gear3/prog_index.m3u8 against iPhone OS 3.1.0
Average segment duration: 8.77 seconds
Average segment bitrate: 510.05 kbit/s
Average segment structural overhead: 96.37 kbit/s (18.89 %)
Video codec: avc1
Video resolution: 480x360 pixels
Video frame rate: 29.97 fps
Average video bitrate: 407.76 kbit/s
H.264 profile: Baseline
H.264 level: 2.1
Audio codec: aac
Audio sample rate: 22050 Hz
Average audio bitrate: 5.93 kbit/s
mediastreamvalidator will first show a listing of the streams you provide, followed by the timing results for each of those streams. However, it may take a few minutes for the
mediastreamvalidator to calculate the actual timing results.
For variant playlists, it is important that the bitrates specified in the playlist are very close to the actual measured rates. If not, a warning will be issued by the
mediastreamvalidator. The bitrates are specified in the
EXT-X-STREAM INF tag using the
Listing 3: Example Variant Playlist showing the BANDWIDTH attribute.
See the HTTP Live Streaming Protocol Specification for more information about the
Back to Top