Technical Q&A QA1752

Understanding the EXT-X-VERSION tag

Q:  When specifying a protocol version value for the EXT-X-VERSION tag in my .m3u8 playlist, which features of HTTP Live Streaming can I use, and what minimum version of iOS should I target?

A: The EXT-X-VERSION tag indicates the compatibility version of the Playlist file. The Playlist file, its associated media, and its server must comply with all provisions of the IETF Internet Draft of the HTTP Live Streaming Protocol Specification - 2nd Edition (or earlier specifications) describing the protocol version indicated by the tag value. A Playlist file that does not contain an EXT-X-VERSION tag must comply with version 1 of this protocol.

Figure 1 lists the protocol version where a given feature was introduced.

Figure 1  Protocol versions and features.

You need only specify the protocol version that is required for backward compatibility of a given feature.

For example, you do not have to specify protocol version 5 if you've just added SUBTITLES. If you do not, older clients will simply ignore the SUBTITLES but still play the content in some form.

However, the following features are not backward compatible. Older clients may fail to play the content if you use these features but do not specify the protocol version where they were introduced:

You must use at least protocol version 2 if you have IV in EXT-X-KEY.

You must use at least protocol version 3 if you have floating point EXTINF duration values.

You must use at least protocol version 4 if you have EXT-X-BYTERANGE or EXT-X-IFRAME-ONLY.

You must use at least protocol version 5 if you specify the SAMPLE-AES encryption method in EXT-X-KEY, or if you have KEYFORMAT and KEYFORMATVERSIONS attributes in EXT-X-KEY, or if you have EXT-X-MAP.

You must use at least protocol version 6 if you have EXT-X-MAP in a Media Playlist that does not contain EXT-X-I-FRAMES-ONLY.

You must use at least protocol version 7 if you specify "SERVICE" values for the INSTREAM-ID attribute of EXT-X-MEDIA.

You must use at least protocol version 8 if you use variable substitution.

Figure 2 lists the versions of specifications where specific features are described, along with the corresponding iOS release that supports those features. Note that over time HLS has been described by three different documents: draft-pantos-http-live-streaming, RFC 8216, and now draft-pantos-hls-rfc8216bis.

Figure 2  Versions of specifications where features are described, and the iOS release supporting those features.

The tools are frequently updated. If you are an iPhone or Mac Developer Program member, you can download the latest versions from the Apple Developer Connection website. To download, go to Downloads for Apple Developers, look for the 'HTTP Live Streaming Tools', download, and install the 'HTTP Live Streaming Tools'.



Document Revision History


DateNotes
2017-12-18

Updated to reflect the most recent versions of HTTP Live Streaming Protocol Specification, including the first version of the 2nd edition.

2016-05-16

Updated for IETF Internet Drafts 12 through 19 of the HTTP Live Streaming Protocol Specification.

2013-05-28

Updated for IETF Internet Drafts 9, 10 and 11 of the HTTP Live Streaming Protocol Specification. Added table showing protocol version and features, along with information about backward compatibility of features.

2012-08-31

New document that discusses what to specify for the EXT-X-VERSION protocol version value and which features of HTTP Live Streaming you can use.