Technical Note TN2224

Best Practices for Creating and Deploying HTTP Live Streaming Media for Apple Devices

This Technote discusses some best practices for creating and deploying HTTP Live Streaming Media for the Apple Devices.

Introduction
Decide on Your Variants
Encode your Variants
Segment your Media
Create Master Playlist
Deploy Your Media
Validate Your Media
References
Document Revision History

Introduction

This Technote describes the recommended practices for preparing and deploying your media for use with HTTP Live Streaming. HTTP Live Streaming allows you to send live or prerecorded audio and video to iPhone, iPad, and other devices including desktop computers, using an ordinary Web server. Playback requires iOS 3.0 or later on devices running iOS; Apple TV Software 4.1 or later on 2nd and 3rd generation Apple TVs; tvOS 9.0 or later on 4th generation Apple TVs; QuickTime X or later is required on the desktop.

The HTTP Live Streaming Overview should be considered a prerequisite because it introduces the HTTP Live Streaming technology.

Getting Started

When working with video and audio a good general rule of thumb is to get the highest quality original source material possible. When you compress, very often some information gets lost or thrown away. Therefore, you should only compress material when encoding for the final destination, because each process will lower the quality. Trying to compress from already heavily compressed source material may give poor results.

Always start with the highest quality source video & audio, and make lower bit rate movies from the original source.

Workflow

The typical workflow for preparing and deploying your media for use with HTTP Live Streaming consists of the following steps. The workflow for live content is similar but requires you to create a workflow that will take care of all these steps in real-time.

Figure 1  Workflow for preparing and deploying media for use with HTTP Live Streaming.

Here's a brief overview of the different steps:

  • Decide on your variants

    We recommend you offer multiple media playlist files to provide different encodings of the same presentation at different bit rates, rather than just a single encoding. These encodings at different bit rates are called variants. That way, the client will switch to the most appropriate variant based on the measured network bit rate. The client’s player is tuned to minimize stalling of playback in order to give the user the best experience possible when streaming. If you just provide a single encoding of your presentation your users will not get the best possible experience. See Decide on Your Variants.

    You should always provide a master playlist, even if you have only a single variant. Using a master playlist enables you to communicate the codecs, resolution, and other data about the variant to the client. Also, a master playlist allows you to specify an I-frame playlist for trick play or add subtitles.

  • Encode your media variants

    Based on the different variants you've decided to deploy, encode each of these from your high-quality source media. When encoding your variants you must have at least one I-frame in each segment to facilitate fast startup and seek. For best results segments should start with an I-frame. If your segments all start with I-frames then you can use the EXT-X-INDEPENDENT-SEGMENTS tag which allows the client to optimize its behavior. See Encode your Variants to learn about providing different encodings of the same presentation.

    In addition, we recommend creating separate I-frame variants for trick play support.

  • Segment the media

    HTTP Live Streaming sends audio and video as a series of small files, typically of less than 10 seconds duration, called media segment files. An index file, or media playlist, gives the clients the URLs of the media segment files.

    For video on demand from prerecorded media, Apple provides a free tool to make media segment files and media playlists from MPEG-4 video or QuickTime movies with H.264 video compression, or audio files with AAC or MP3 compression. The media playlists and media segment files can be used for video on demand or streaming radio, for example.

    For live streams, Apple provides a free tool to make media segment files and media playlists from live MPEG-2 transport streams carrying H.264 video, AAC audio, or MP3 audio. See Segment your Media.

  • Create a master playlist

    A master playlist enables delivery of multiple streams of the same content with varying quality levels for different bandwidths or devices. HTTP Live Streaming supports switching between streams dynamically if the available bandwidth changes. The client software uses heuristics to determine appropriate times to switch between the alternates. Currently, these heuristics are based on recent trends in measured network throughput. See Create Master Playlist.

  • Deploy the media

    To deploy HTTP Live Streaming media, you need the use of a web server, and you need to create either an HTML page for browsers or a client app to act as a receiver. You may want to encrypt your streams, in which case you should serve the encryption key files securely over HTTPS, so that only your intended clients can decrypt them. See Deploy Your Media.

  • Validate the media

    You should use the Apple-provided media stream validator prior to deploying your streams, to ensure that they are fully compliant with HTTP Live Streaming. See Validate Your Media.

Decide on Your Variants

Instead of offering just a single encoding of your presentation, you should offer multiple media playlist files to provide different encodings of the same presentation. The HTTP Live Streaming client will then switch among these stream alternates dynamically as the network bandwidth changes, providing the best possible stream for the current network conditions.

When choosing the bit rates for your master playlist there are a number of things to take into consideration. These are discussed below.

Encoding Hardware, Budget Constraints

You may have a limitation on the number of bit rates that your particular encoding hardware can produce. If your encoding system can only produce a certain number of streams, you should choose variants that work for the most devices. For live streams delivered through a CDN, you should determine how much bandwidth is necessary to get all of your streams uploaded and updating properly at the same time. You may also have financial constraints.

Ability to Switch

You should check the distance between the bitrates of your variants because this will determine the ability of the client to switch to a different bitrate. See Bit rate recommendations for more information.

Device Capabilities

You should also learn as much as you can about the client devices you will be serving, because different devices may have different capabilities. Some may have different screen resolutions, some may support different H.264 profile levels. In certain cases, you might want to provide a different master playlist for different device models; for example, a different master playlist to iPads versus iPhones. These are discussed below:

  • Select Device based on Device Resolution

    Different devices support different resolutions. Because of this, you should add the RESOLUTION attribute to the master playlist to allow the client to select the media playlist based on device resolution. Consider the following master playlist excerpt:

    #EXT-X-STREAM-INF:BANDWIDTH=1280000,RESOLUTION=640x360

    #EXT-X-STREAM-INF:BANDWIDTH=1700000,RESOLUTION=1280x720

    #EXT-X-STREAM-INF:BANDWIDTH=3500000,RESOLUTION=1920x1080

    When delivering to an older device, such as an iPad2, the client will select the 1280x720 media playlist since these devices can't play 1080p content. However, newer devices such as the iPad Air support higher resolutions and will pick the 1080p stream (provided it can handle the bitrate). Note that if you have an app that is delivering video to a smaller 640x360 window rather than the whole screen, the client will select the 640x360 stream. There is no advantage to getting the 1080p stream and downscaling it when you're only showing the video in a small window. This would waste the user's bandwidth. However, if the app then goes to fullscreen the client will switch up to the 1080p stream, if possible.

  • Select Device based on Device codec

    You should also add the CODECS attribute to your master playlist to allow the client to filter based on the codec and the particular profile and level of encoding supported by the device. Here's an example master playlist excerpt. The first entry specifies the H.264 Baseline profile Level 3.1, the second entry specifies the H.264 Main profile Level 4.0 and the third specifies the H.264 High profile Level 4.0:

    #EXT-X-STREAM-INF:BANDWIDTH=1280000,CODECS="avc1.42001f"

    #EXT-X-STREAM-INF:BANDWIDTH=1280000,CODECS="avc1.4d0028"

    #EXT-X-STREAM-INF:BANDWIDTH=1280000,CODECS="avc1.640028"

    When serving such a playlist to a device like the iPhone 4 that doesn't support the H.264 Main Level 4.0 or High profile, the client will select the Baseline profile and ignore the other two variants, whereas the iPhone 4S would select the Main profile.

  • Select based on Device Model (Server-side)

    You can also select a master playlist based on the device model by filtering on the HTTP Header field User-Agent identification string. This is performed on the server side rather than the client side. Here are some example User-Agent strings. The first two strings represent clients delivered over Safari, and the second two strings represent apps:

    Mozilla/5.0 (iPhone; CPU iPhone OS 5_1_1 like Mac OS X) AppleWebKit/ 534.46 (KHTML, like Gecko) Version/5.1 Mobile/9B206 Safari/7534.48.3

    Mozilla/5.0 (iPad; CPU OS 5_1_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9B206 Safari/7534.48.3

    AppleCoreMedia/1.0.0.9B176 (iPhone; U; CPU OS 5_1 like Mac OS X; en_us)

    AppleCoreMedia/1.0.0.9B176 (iPad; U; CPU OS 5_1 like Mac OS X; en_us)

Network Capabilities

You may also want to take into consideration your network capabilities when deciding on your variants.

You can use the SystemConfiguration framework to determine whether or not you are on a cellular or WiFi network (see the Reachability sample code for an example of this). Once you determine what type of network you are on, you may want to request a different URL, or add this as extra information in your request so that the server can provide a different playlist. This is particularly important because it allows you to specify an appropriate entry for the first item in the master playlist based on the network that you are on (see the next section, Bit rate recommendations, to learn more about the importance of the first entry in the master playlist).

Bit rate recommendations

Here are some recommendations for choosing the bit rates in your master playlist:

  • First bit rate should be one that most clients can sustain

    The first entry in the master 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. Therefore, the first bit rate in the playlist should be the one that most clients can sustain.

    You should create multiple master 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 both when the stream is first played and as the client's network environment changes.

    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 speeds

  • Audio/Video Stream Considerations

    Video aspect ratio must be exactly the same, but can have different dimensions (see Recommended Encoding Settings for HTTP Live Streaming Media).

  • Adjacent bit rates should be a factor of 1.5 to 2 apart

    You should keep adjacent bit rates at a factor of 1.5 to 2 apart. If you put them too close together, you will increase your number of variants unnecessarily.. For example, it won't help much if you've got both a 150 kb/s and a 180 kb/s stream. On the other hand, don't make them too far apart either. If they are too far apart, the client may find itself in a situation where it could actually have gotten a better stream but there isn't one available. An example of this is if the client has to go from 500 kb/s to 3000 kb/s. This is a factor of six difference.

  • Keyframes (I-frames)

    You must include at least one keyframe per segment, preferably more. We recommend one every two seconds. If you only include one, put it at the beginning of the segment and make it an IDR frame. An IDR (instantaneous decoder refresh) frame is a special kind of H.264 I-frame that also indicates that no subsequent frame can refer to any previous frame.

  • Don't under report bit rate in master playlist

    To prevent stalls, do not under-report the bit rate in the master playlist. The maximum bit rate should be specified based on the peak bit-rate in the stream. For example, if you've declared a 200 kb/s variant in your playlist, then its maximum bitrate should be 200 kb/s. If your 200 kb/s stream actually peaks at 300 kb/s, the client may stall because you misrepresented how much bandwidth is needed to play a given stream.

  • Specify an average bit rate

    You should include the average bit rate as well as the peak bit rate. This is especially important if your peak is more than 20% different from your average. Specifying the average allows the client to make more intelligent decisions about which variant to play.

Special considerations for cellular

If you are using HTTP Live Streaming in iPhone and iPad applications sold on the App Store there are some special considerations for cellular:

  • Provide a 192 kb/s stream

    If your app uses HTTP Live Streaming over cellular networks, you are required to provide at least one stream at 192 kb/s or lower bandwidth. The low-bandwidth stream may be audio-only, or audio with a still image, but you should strive to have video in your 192kbps stream.

    Some common mistakes when creating the 192 kb/s stream are:

    • Thinking you have a < 192 kb/s stream because the sum of your audio and video bitrates is < 192 kb/s. Remember the 192 kb/s is the bandwidth of the entire stream, including overhead.

    • Putting too large a JPG at the beginning of each segment.

    • Inaccurate EXTINF causing miscalculation.

    As discussed above, we recommend using ADTS elementary streams.  The mediastreamsegmenter and mediafilesegmenter tools can pull the audio out of the transport stream for you.

  • Don't serve media segments from your app

    Apps cannot grab media in some other format over the cellular network and run a local web server to translate and serve that content as an HTTP Live stream. Your app can be rejected if you do.

Encode your Variants

Once you've decided on the different variants you'd like to deploy, encode each of these from your high-quality source media.

To deploy a video on demand (VOD) stream, you must create MPEG-4 or QuickTime media files with H.264 and AAC encoding, or MP3 audio files from your source material. Always start with the highest quality source media, and make any lower bit rate movies from the original source, because subsequent re-encodings may lower the quality.

Live streams must be encoded as MPEG-2 transport streams carrying H.264 video, AAC audio, or MP3 audio.

Recommended Encoding Settings for HTTP Live Streaming Media

Figure 3 below contains recommended encoding settings to use when creating HTTP Live Streaming media.

These are recommended settings, not required settings. For example, if you are targeting movies that have very fast motion (such as sporting events), or if you have concerns about bandwidth, you may need to perform additional compression on your video to get the desired results. If this is the case, use these settings as a starting point, and recompress until you are satisfied with the results.

These settings apply to both live and prerecorded (video on demand, or VOD) encoding. The provided settings are grouped according to whether the content is intended to be streamed over the cellular or Wi-Fi network, whether the content is for iPhone/iPod Touch or iPad, and whether the content is 4:3 or 16:9 aspect ratio.

The following audio and video formats are supported:

  • Video: up to H.264 High Profile Level 5.1.

    Support varies across hardware and OS release, but all modern hardware supports at least High Profile Level 4.1

  • Audio: HE-AAC or AAC-LC up to 48 kHz, stereo audio OR

    MP3 (MPEG-1 Audio Layer 3) 8 kHz to 48 kHz, stereo audio

    In addition, some hardware supports AC-3 or Enhanced AC-3, but only as an alternate. That is, you must also provide AAC.

Some old devices do have limitations as detailed in Figure 2, but these devices are increasingly rare. In practice you should expect that all devices will support HLS version 4 and most will support the latest version. You should also expect that all devices will be able to play content encoded using High Profile Level 4.1.

Figure 2  Limitations on old devices.
Figure 3  Recommended Encoding Settings for HTTP Live Streaming Media.

Segment your Media

HTTP Live Streaming requires that a media stream or file be segmented into a series of small media files of approximately equal duration. This is usually accomplished using a tool that will segment the individual files and create a media 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 Tool

You can use the Media Stream Segmenter (mediastreamsegmenter) tool for deployment of HTTP Live Streaming Media.

The tool is installed to your system disk at /usr/local/bin/mediastreamsegmenter. (The /usr/local/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 a media playlist file containing references to the individual media segments. The media playlist and media segments can be deployed using almost any web server infrastructure for streaming to iOS and OS X. The mediastreamsegmenter produces either live or Video on Demand (VOD) streams.

The 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).

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 239.4.1.5:20103

The -s option defines the number of media file entries that should be kept in the playlist. The default is 5. The -D option (in a live stream) will specify that the media files that are no longer in the playlist will be removed after an expiry period. The -f option specifies the directory to store the media and playlists.

In this example, the playlist will contain 3 items. Media files will be removed after an expiry period. The media and playlist will be stored in /Library/WebServer/Documents/stream.

Media File Segmenter Tool

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.

The mediafilesegmenter also creates a media playlist containing references to the individual media files. The playlist and media files can then be deployed as a VOD stream using common web server infrastructure.

The 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).

Creating an audio only stream

Both tools can produce an audio-only stream if you specify the following argument:

-a or --audio-only

This strips the audio elementary stream (AAC/ADTS or MP3) and writes it into the media file. For example, you could run the mediastreamsegmenter on an existing audio/video stream to get an audio-only stream.

If you'd also like to include a poster image in your audio only stream, just create a small jpg or png (20 to 30k), and use the --audio-only setting of the mediafilesegmenter, with the --meta-file=your-jpg-file and --meta-type=picture (read the man page for details).

Transport Stream Structural Overhead

MPEG transport streams contain a certain amount of overhead and padding. Depending upon how your transport stream is created, you might have more overhead than in other cases. The Apple media file and stream segmenters have been optimized to produce very little overhead, typically less than 10% (and in most cases, less than 5%). Streams produced by some third-party encoders contain overhead as high as 45%.

To put that into perspective, if your stream is 100 kb/s, and you've got 45% overhead, only 55 kb/s of actual video data that is making it through. If your overhead is 5%, then you have 95 kb/s of video. Obviously, you can produce a much better stream if you've got 95 kb/s of video data versus 55 kb/s, so you'll want to minimize that overhead if you can. If you are working with a third-party vendor, we suggest you take your original content, encode it with the Apple stream segmenter, and compare to see what kind of overhead you are getting.

Use at least one IDR-frame per segment (preferably at the start)

In order to have fast startup and seek, you need to have an IDR frame in your segment. In H.264 video, IDR refers to Instantaneous Decoder Refresh frames, a special kind of I-frame. These indicate to the decoder that no frame occurring after an IDR frame depends on any frame that occurs before it. We recommend you have at least one IDR frame at the beginning of your segment, because when seeking or starting up partway through a live stream the client needs an IDR frame to get started. If you put your IDR frames partway into the segment, the client cannot start until it finds an IDR frame. (Use the -start-segments-with-iframe option with mediafilesegmenter.)

Use 6 second Target Durations

The value you specify in the EXT-X-TARGETDURATION tag for the maximum media segment duration will have an effect on startup. We strongly recommend a 6 second target duration. If you use a smaller target duration, you increase the likelihood of a stall. Here's why: if you've got live content being delivered through a CDN, there will be propagation delays, and for this content to make it all the way out to the edge nodes on the CDN it will be variable. In addition, if the client is fetching the data over the cellular network there will be higher latencies. Both of these factors make it much more likely you'll encounter a stall if you use a small target duration.

Create Master Playlist

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 Media Playlist files to provide different encodings of the same presentation when HTTP Live Streaming. If it does, it must provide a Master Playlist file 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 Master Playlists.

Variant (Master) Playlist Creator Tool

The Variant Playlist Creator (variantplaylistcreator) is a command line tool that will create a master playlist in the m3u8 format for stream switching for HTTP Live Streaming segments created by mediafilesegmenter. (The name is a holdover, Master Playlists used to be called Variant Playlists.) Apple Developer Program members can download the tool as part of the HTTP Live Streaming Tools package as described in Segment your Media.

The variantplaylistcreator uses pairs of URLs and plist files to create a master playlist. The plist files are generated using the -I or --generate-variant-info option on mediafilesegmenter. You can obtain a list of all the command line arguments and their meanings by typing man variantplaylistcreator from the Terminal application.

Deploy Your Media

HTML5 video element

We recommend you use the HTML5 video element to display video in Safari on iOS. For more information about the video element, see the Safari Guide to HTML5 Audio and Video and the HTMLMediaElement, HTMLVideoElement, and 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.

<video src="http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8">
        This browser does not support HTML5 video.
</video>

See also Technical Note TN2262, 'Preparing Your Web Content for iPad' which describes platform-specific considerations for web content in Safari on iOS 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 playlists 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 .ts files.

Table 1  MIME-type associations for .m3u8 files and .ts files.

File Extension

MIME Type

.m3u8

vnd.apple.mpegURL or application/x-mpegURL

.ts

video/MP2T

Servers that are constrained for compatibility can serve files ending in .m3u with MIME type audio/mpegURL.

Tuning time-to-live (TTL) values for .m3u8 files may also be necessary to achieve desired caching behavior for downstream web caches in the live streaming case, 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.

Serve playlists using gzip

You should always serve your playlist using gzip. VOD Playlists can have hundreds of entries. Even in a live playlist, you can have hundreds of entries if you are delivering a large window of content. gzip reduces the size dramatically, and it is very easy to add to your server (it is typically a one line change in your server configuration).

Keep Track of your Performance

After deploying your streams, you should track actual performance in the field to verify your assumptions about the bitrates you've chosen. Use the MediaPlayer framework client access and error logs for this purpose. There are a number of different fields in the access log. You should pay attention to the fields that tell you what streams you are actually getting, how long are they playing, where the stream switching is occurring, and whether or not you are getting stalls.

See the AVPlayerItemAccessLogEvent, AVPlayerItemAccessLog, AVPlayerItemErrorLogEvent, and AVPlayerItemErrorLog classes for more information.

Content protection

You may want to encrypt your media. This can be done by encrypting the segments or encrypting the data within the segments and delivering the keys via HTTPS. See Example Playlist Files for use with HTTP Live Streaming and MPEG-2 Stream Encryption Format for HTTP Live Streaming.

You can secure the delivery of streaming media using FairPlay Streaming (FPS) technology. With FPS, content providers, encoding vendors, and delivery networks can encrypt content, securely exchange keys, and protect playback on iOS, tvOS, and Safari on macOS. See FairPlay Streaming Resources

Validate Your Media

Media Stream Validator Tool

The Media Stream Validator (mediastreamvalidator) is a command-line tool to validate HTTP Live Streaming streams and servers. Apple Developer Program members can download the tool as part of the HTTP Live Streaming Tools package as described in Segment your Media.

This tool simulates an HTTP Live Streaming session and verifies that the playlists 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.

Here's example output from the mediastreamvalidator tool.

Listing 2  Example validator tool output.

mediastreamvalidator: Version 1.2(160525)
 
[/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8] Started root playlist download
[gear2/prog_index.m3u8] Started media playlist download
[gear1/prog_index.m3u8] Started media playlist download
[gear0/prog_index.m3u8] Started media playlist download
[gear4/prog_index.m3u8] Started media playlist download
[gear3/prog_index.m3u8] Started media playlist download
[gear1/prog_index.m3u8] parsed media segment count: 30, duration: 309.277
[gear0/prog_index.m3u8] parsed media segment count: 30, duration: 309.986
[gear4/prog_index.m3u8] parsed media segment count: 30, duration: 309.277
[gear0/prog_index.m3u8] parsed media segment count: 60, duration: 609.988
[gear1/prog_index.m3u8] parsed media segment count: 61, duration: 618.552
[gear2/prog_index.m3u8] parsed media segment count: 30, duration: 309.277
[gear3/prog_index.m3u8] parsed media segment count: 30, duration: 309.277
[gear0/prog_index.m3u8] parsed media segment count: 90, duration: 909.990
[gear4/prog_index.m3u8] parsed media segment count: 61, duration: 618.552
[gear0/prog_index.m3u8] parsed media segment count: 120, duration: 1209.992
[gear1/prog_index.m3u8] parsed media segment count: 92, duration: 927.829
[gear2/prog_index.m3u8] parsed media segment count: 61, duration: 618.552
[gear0/prog_index.m3u8] parsed media segment count: 150, duration: 1509.994
[gear3/prog_index.m3u8] parsed media segment count: 61, duration: 618.552
[gear1/prog_index.m3u8] parsed media segment count: 123, duration: 1237.105
[gear0/prog_index.m3u8] All media files delivered and have end tag, stopping
[gear4/prog_index.m3u8] parsed media segment count: 92, duration: 927.829
[gear1/prog_index.m3u8] parsed media segment count: 154, duration: 1546.381
[gear2/prog_index.m3u8] parsed media segment count: 92, duration: 927.829
[gear3/prog_index.m3u8] parsed media segment count: 92, duration: 927.829
[gear1/prog_index.m3u8] All media files delivered and have end tag, stopping
[gear2/prog_index.m3u8] parsed media segment count: 123, duration: 1237.105
[gear3/prog_index.m3u8] parsed media segment count: 123, duration: 1237.105
[gear4/prog_index.m3u8] parsed media segment count: 123, duration: 1237.105
[gear2/prog_index.m3u8] parsed media segment count: 154, duration: 1546.381
[gear3/prog_index.m3u8] parsed media segment count: 154, duration: 1546.381
[gear4/prog_index.m3u8] parsed media segment count: 154, duration: 1546.381
[gear2/prog_index.m3u8] All media files delivered and have end tag, stopping
[gear3/prog_index.m3u8] All media files delivered and have end tag, stopping
[gear4/prog_index.m3u8] All media files delivered and have end tag, stopping
 
 
--------------------------------------------------------------------------------
gear2/prog_index.m3u8
--------------------------------------------------------------------------------
Processed 181 out of 181 segments
Average segment duration: 9.944755
Total segment bitrates (all discontinuities): average: 650.19 kb/s, max: 667.68 kb/s
Playlist max bitrate: 649.879000 kb/s
Audio Group ID: AUDIO
 
 
 
 
Discontinuity: sequence: 0, parsed segment count: 181 of 181, duration: 1800.001 sec, average: 650.19 kb/s, max: 667.68 kb/s
Track ID: 3
Track ID: 1
Video Codec: avc1
Video profile: Main
Video level: 3.0
Video resolution: 640x480
Video average IDR interval: 0.800801, Standard deviation: 0.000833
Video frame rate: 29.970
Track ID: 2
Audio Codec: AAC-LC
Audio sample rate: 22050 Hz
Audio channel layout: Stereo (L R)
 
 
--------------------------------------------------------------------------------
gear1/prog_index.m3u8
--------------------------------------------------------------------------------
Processed 181 out of 181 segments
Average segment duration: 9.944755
Total segment bitrates (all discontinuities): average: 232.68 kb/s, max: 241.20 kb/s
Playlist max bitrate: 232.370000 kb/s
Audio Group ID: AUDIO
 
 
 
 
Discontinuity: sequence: 0, parsed segment count: 181 of 181, duration: 1800.001 sec, average: 232.68 kb/s, max: 241.20 kb/s
Track ID: 3
Track ID: 1
Video Codec: avc1
Video profile: Main
Video level: 2.1
Video resolution: 400x300
Video average IDR interval: 0.800801, Standard deviation: 0.000833
Video frame rate: 29.970
Track ID: 2
Audio Codec: AAC-LC
Audio sample rate: 22050 Hz
Audio channel layout: Stereo (L R)
 
 
--------------------------------------------------------------------------------
gear0/prog_index.m3u8
--------------------------------------------------------------------------------
Processed 180 out of 180 segments
Average segment duration: 9.999803
Total segment bitrates (all discontinuities): average: 6.23 kb/s, max: 6.61 kb/s
Playlist max bitrate: 41.457000 kb/s
Audio Group ID: AUDIO
 
 
 
 
Discontinuity: sequence: 0, parsed segment count: 180 of 180, duration: 1799.965 sec, average: 6.23 kb/s, max: 6.61 kb/s
Track ID: 100
Audio Codec: AAC-LC
Audio sample rate: 22050 Hz
Audio channel layout: Stereo (L R)
 
 
--------------------------------------------------------------------------------
gear4/prog_index.m3u8
--------------------------------------------------------------------------------
Processed 181 out of 181 segments
Average segment duration: 9.944755
Total segment bitrates (all discontinuities): average: 1505.39 kb/s, max: 1545.66 kb/s
Playlist max bitrate: 1927.833000 kb/s
Audio Group ID: AUDIO
 
 
 
 
Discontinuity: sequence: 0, parsed segment count: 181 of 181, duration: 1800.001 sec, average: 1505.39 kb/s, max: 1545.66 kb/s
Track ID: 3
Track ID: 1
Video Codec: avc1
Video profile: Main
Video level: 3.1
Video resolution: 960x720
Video average IDR interval: 3.003005, Standard deviation: 0.000663
Video frame rate: 29.970
Track ID: 2
Audio Codec: AAC-LC
Audio sample rate: 22050 Hz
Audio channel layout: Stereo (L R)
 
 
--------------------------------------------------------------------------------
gear3/prog_index.m3u8
--------------------------------------------------------------------------------
Processed 181 out of 181 segments
Average segment duration: 9.944755
Total segment bitrates (all discontinuities): average: 992.03 kb/s, max: 1013.65 kb/s
Playlist max bitrate: 991.714000 kb/s
Audio Group ID: AUDIO
 
 
 
 
Discontinuity: sequence: 0, parsed segment count: 181 of 181, duration: 1800.001 sec, average: 992.03 kb/s, max: 1013.65 kb/s
Track ID: 3
Track ID: 1
Video Codec: avc1
Video profile: Main
Video level: 3.0
Video resolution: 640x480
Video average IDR interval: 0.800801, Standard deviation: 0.000833
Video frame rate: 29.970
Track ID: 2
Audio Codec: AAC-LC
Audio sample rate: 22050 Hz
Audio channel layout: Stereo (L R)
 
 
--------------------------------------------------------------------------------
MUST fix issues
--------------------------------------------------------------------------------
 
 
Error: Measured peak bitrate compared to master playlist declared value exceeds error tolerance
--> Detail: Measured: 6.61 kb/s, Master playlist: 41.46 kb/s, Error: 527.65%
--> Source: https://devimages.apple.com.edgekey.net/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8
--> Compare: gear0/prog_index.m3u8
 
 
--> Detail: Measured: 1545.66 kb/s, Master playlist: 1927.83 kb/s, Error: 24.73%
--> Source: https://devimages.apple.com.edgekey.net/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8
--> Compare: gear4/prog_index.m3u8
 
 
Error: Different target durations detected
--> Detail: Target duration: 11 vs Target duration: 10
--> Source: gear0/prog_index.m3u8
--> Compare: gear2/prog_index.m3u8
 
 
--> Detail: Target duration: 11 vs Target duration: 10
--> Source: gear0/prog_index.m3u8
--> Compare: gear1/prog_index.m3u8
 
 
--> Detail: Target duration: 11 vs Target duration: 10
--> Source: gear0/prog_index.m3u8
--> Compare: gear3/prog_index.m3u8
 
 
--> Detail: Target duration: 11 vs Target duration: 10
--> Source: gear0/prog_index.m3u8
--> Compare: gear4/prog_index.m3u8

For master 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 BANDWIDTH attribute.

Listing 3  Example Master Playlist showing the BANDWIDTH & CODECS attributes.

#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=235000,CODECS="mp4a.40.2, avc1.4d4015"
gear1/prog_index.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=649000,CODECS="mp4a.40.2, avc1.4d401e"
gear2/prog_index.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=991000,CODECS="mp4a.40.2, avc1.4d401e"
gear3/prog_index.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1927000,CODECS="mp4a.40.2, avc1.4d401f"
gear4/prog_index.m3u8

See the HTTP Live Streaming Protocol Specification for more information about the BANDWIDTH attribute.

HLS Report Tool

The mediastreamvalidator produces a JSON file contains the validation data extracted from the stream. This file defaults to the name validation_data.json, but the name can be altered by means of the -O or --validation-data-path option.

The HLS Report (hlsreport.py) is a command-line tool to condense and tabulate the JSON data produced by the Media Stream Validator Tool. Apple Developer Program members can download the tool as part of the HTTP Live Streaming Tools package as described in Segment your Media.

This tool produces a summary report in the form of an HTML document. The report outputs several tables with details about variants, renditions, and I-frame variants. It also includes a list of issues is divided into 'Must Fix' and 'Should Fix' categories according to the HLS Authoring Specification for Apple Devices.

A portion of the hlsreport output is shown in Figure 4.

You can get more detail about the command line arguments and more complete description of the output by typing man hlsreport from the Terminal application.

Figure 4  Sample hlsreport excerpt.

References



Document Revision History


DateNotes
2016-08-02

Reconcile content with HLS Authoring Specification.

2015-05-04

Updated special considerations for cellular section to reflect current App Store Review Guidelines.

2014-02-28

Updated the recommended encoding settings to include newer devices. Other miscellaneous changes.

2012-08-14

Includes new and updated recommendations for deciding on variants, encoding, segmenting and deploying your media.

2011-08-03

Editorial

2011-07-08

Revised encoder settings recommendations to include Apple TV.

2010-04-19

Updated recommended encoding settings to include iPad only values.

2010-03-19

New document that discusses best practices for creating and deploying HTTP Live Streaming Media for Apple Devices