Guides and Sample Code

Developer

HLS Authoring Specification for Apple Devices

On This Page

General Authoring Requirements

A stream that matches these requirements should be compatible with iOS, tvOS, or OS X.

Video

  • 1. Video encoding requirements

    • 1.1. All video MUST be encoded using AVC/H.264.

      1.2. Profile and Level MUST be less than or equal to High Profile, Level 4.2.

      1.3. You SHOULD use High Profile in preference to Main or Baseline Profile.

      1.4. For backward compatibility content SHOULD NOT use a higher level than required by the content resolution and frame rate.

      1.5. Key frames (IDRs) SHOULD be present every two seconds.

      1.6. All interlaced source content MUST be de-interlaced.

      1.7. You SHOULD de-interlace 30i content to 60p instead of 30p.

      1.8. Live/linear video from NSTC or ATSC source SHOULD be 60 or 59.94 fps.

      1.9. Live/linear video from PAL source SHOULD be 50 fps.

      1.10. VOD content SHOULD use a natural frame rate for the content. Any of the typical frame rates: 23.976, 24, 25, 29.97, 30, 50, 59.94, and 60 fps are supported.

      1.11. Frame rates above 60 fps SHALL NOT be used.

      1.12. Streams SHOULD use a single color space, either Rec. 601 or Rec. 709.

      1.13. For VOD, the color space SHOULD be the original color space of the material.

      1.14. Recommended variants are according to the following table:

      Table 2-1Bit rate variant table

      Video average bit rate (kb/s)

      Resolution

      Frame rate

      145

      416 x 234

      ≤ 30 fps

      365

      480 x 270

      ≤ 30 fps

      730

      640 x 360

      ≤ 30 fps

      1100

      768 x 432

      ≤ 30 fps

      2000

      960 x 540

      same as source

      3000

      1280 x 720

      same as source

      4500

      same as source

      same as source

      6000

      same as source

      same as source

      7800

      same as source

      same as source

      1.15. For VOD content, the average segment bit rate MUST be within 10% of the AVERAGE-BANDWIDTH attribute. (See also Appendix.)

      1.16. For VOD content, the measured peak bit rate MUST be within 10% of the BANDWIDTH attribute.

      1.17. For live/linear content, the average segment bit rate over a long (~1 hour) period of time MUST be less than 110% of the AVERAGE-BANDWIDTH attribute.

      1.18. For live/linear content, the measured peak bit rate MUST be within 25% of the BANDWIDTH attribute.

      1.19. For VOD content the peak bit rate SHOULD be no more than 200% of the average bit rate.

      1.20. Different variants MAY have different frame rates.

      1.21. The default video variant(s) SHOULD be the 2000 kb/s variant. (Defaults are the first variant listed in the master playlist within a group of variants having compatible audio.)

      1.22. All video variants SHOULD have identical aspect ratios.

Audio

  • 2. Audio encoding requirements (see also Appendix)

    • 2.1. Audio data SHOULD be provided as an elementary audio stream.

      2.2. Stereo audio formats are:

      • AAC-LC

      • HE-AAC v1

      • HE-AAC v2

      2.3. Stereo audio MUST be provided.

      2.4. You SHOULD NOT use HE-AAC if your audio bit rate is above 64 kb/s.

      2.5. Supported multichannel audio formats (see also Appendix) are:

      • Dolby Digital (AC-3)

      • Dolby Digital Plus (E-AC-3)

      2.6. If Dolby Digital Plus is provided then Dolby Digital MUST be provided also.

      2.7. Stereo audio MAY be provided at multiple bit rates

      2.8. Multichannel audio MUST be provided at a single bit rate. (For example, don’t provide Dolby Digital 5.1 at two bit rates, but you may provide Dolby Digital 5.1 and Dolby Digital Plus 5.1.)

      2.9. Overall bit rate recommendations are as follows:

      Table 2-2Bit rate recommendations

      Audio channels

      Format

      Total (kb/s)

      2.0 (stereo)

      AAC

      32 to 160

      2.0 (stereo)

      Dolby Digital Plus

      96 to 160

      5.1 (surround)

      Dolby Digital

      384

      5.1 (surround)

      Dolby Digital Plus

      192

      7.1 (surround)

      Dolby Digital Plus

      384

      2.10. You MAY change channel layout within a stream.

      2.11. Channel layout changes MUST be in conjunction with an EXT-X-DISCONTINUITY tag.

      2.12. If you provide Descriptive Video Service (DVS), also called Audio Description, it MUST be marked with the attribute CHARACTERISTICS="public.accessibility.describes-video".

      2.13. If you provide DVS, the AUTOSELECT attribute MUST have a value of “YES”.

      2.14. The name of DVS audio SHOULD indicate that the stream is DVS content.

      2.15. If you provide alternate audio or DVS, you MUST provide it for the entire content duration even if it only really exists for a portion of the main content.

      2.16. Alternate audio or DVS MAY reuse the audio segments of regular content when the alternate content is not available.

      2.17. A single media segment MUST NOT contain multiple audio streams.

      2.18. Loudness management/Dynamic Range Control SHOULD be present unless all content (including ads) has been encoded at the same audio levels.

      2.19. Dolby Digital and Dolby Digital Plus loudness SHOULD be specified by the dialnorm field (ATSC A/52:2012). 

      2.20. AAC dialog loudness SHOULD be specified by either AAC prog_ref_level (ISO 14496-3 sub-clause 4.5.2.7), as specified by SCTE 193-1 section 7.4.1; OR by the loudnessInfo() payload as specified by ISO 23003-4, in which case samplePeakLevel or truePeakLevel MUST be present, measurementSystem MUST be 2, and methodDefinition MUST be 1 or 2.

Ads and Pre-/Mid-/Post-Rolls

  • 3. Ad requirements (see also Media Playlists section)

    • 3.1. Your ads and other inserted media SHOULD be included in the media playlists.

      3.2. Inserted media SHOULD be encoded with the same codecs and aspect ratio as the other content in the Media Playlist.

      3.3. Inserted media SHOULD be at or under the specified bandwidths for that variant.

Accessibility

  • 4. Accessibility requirements

    • 4.1. Captions SHOULD be provided with your streams to make content accessible to the deaf or hard of hearing.

      4.2. Supported caption formats are:

      • CEA-608 closed captions

      • CEA-708 closed captions

      • WebVTT subtitles

      4.3. Closed captions (if any) MUST be included in the video media segments.

      4.4. The presence of closed captions MUST be declared via an EXT-X-MEDIA tag that contains a LANGUAGE attribute.

      4.5. If a subtitles track is intended to provide accessibility for the deaf and hard of hearing it MUST be marked with the attribute CHARACTERISTICS="public.accessibility.describes-music-and-sound". (Subtitles with this attribute value are treated the same as closed captions.)

      4.6. If a subtitles track is intended to provide accessibility for the deaf and hard of hearing the AUTOSELECT attribute MUST have a value of “YES”.

      4.7. The LANGUAGE attribute MUST be included in the EXT-X-MEDIA tag for a subtitles track.

      4.8. For information on including Audio Descriptions with your streams, see items 2.12 through 2.16.

Subtitles

  • 5. Subtitle requirements

    • 5.1. Subtitles MAY be provided.

      5.2. Subtitles MUST be WebVTT according to the HLS specification.

      5.3. The subtitle playlist MUST exist for the entirety of the main content, even if the actual subtitles only exist for a portion of the content.

      5.4. For live/linear content, target durations for subtitle playlists MUST be identical to other media.

      5.5. For VOD content, target durations of subtitle playlists MAY be longer than the other media.

      5.6. If content has forced subtitles and regular subtitles in a given language, the regular subtitles track in that language MUST contain both the forced subtitles and the regular subtitles for that language.

      5.7. If your videos contain text burnt into the video and you have access to a version without the burn-in, you SHOULD use Forced Subtitles instead. (This allows you to easily translate into multiple languages. An example of when you might use forced subtitles is a science fiction film, where alien languages are translated into English.)

Trick Play

  • 6. Trick play requirements

    • 6.1. I-frame playlists (EXT-X-I-FRAME-STREAM-INF) MUST be provided to support scrubbing and scanning UI.

      6.2. You SHOULD have one frame per second “dense” I-frame renditions. These are dedicated renditions that only contain I-frames.

      6.3. Alternatively, you MAY use the I-frames from your normal content, but trick play performance is improved with a higher density of I-frames.

      6.4. If you provide multiple bit rates at the same spatial resolution for your regular video then you SHOULD create the I-frame playlist for that resolution from the same source used for the lowest bit rate in that group.

      6.5. The bit rate of I-frame playlists SHOULD be the bit rate of a normal playlist of the same resolution times the fps of the I-frame playlist divided by eight. (See also Appendix.)

      6.6. You SHOULD provide multiple I-frame Media Playlists with different bit rates.

      6.7. Recommendations for producing dense I-frame variants are as follows:

      Table 2-3I-frame variants

      Trick play peak video bit rate (kb/s)

      16:9 aspect

      50

      480 x 270

      100

      640 x 360

      275

      960 x 540

      412

      1280 x 720

      625

      1920 x 1080

      6.8. I-frame playlists MUST contain the EXT-X-I-FRAMES-ONLY tag.

      6.9. The peak segment bit rate MUST be calculated according to the HLS specification.

      6.10. If using fragmented MPEG-4 (fMP4), I-frame segments MUST include the 'moof' header associated with the I-frame.

      6.11. For live/linear content, target durations for I-frame playlists MUST be identical to other media.

      6.12. For VOD content, target durations of I-frame playlists MAY be different from the other media.

Media Segmentation

  • 7. Media segmentation requirements

    • 7.1. Your media MUST be continuous across segments, with the exception of transitions for ads and other inserted material.

      7.2. If using a transport stream, continuity counters and timestamps MUST be sequential.

      7.3. If using fMP4, the track fragment decode time MUST be consistent with the decode time and duration of the previous segment.

      7.4. Video segments MUST start with an IDR frame.

      7.5. Target durations SHOULD be 6 seconds.

      7.6. Segment durations SHOULD be nominally 6 seconds (e.g., NTSC 29.97 may be 6.006 seconds).

      7.7. Media segments MUST NOT exceed the target duration by more than 0.5 seconds.

Media Playlists

  • 8. Media playlist requirements

    • 8.1. You MUST use sufficiently accurate segment durations to insure that the sum of the EXTINF durations of any contiguous group of segments is within one video frame duration of the actual duration of the content.

      8.2. Audio and video playlists MUST all use the same target duration.

      8.3. Audio and video playlists MUST contain the same duration of content.

      8.4. The EXT-X-PROGRAM-DATE-TIME tag MUST be present in every live/linear media playlist.

      8.5. The date-time value of an EXT-X-PROGRAM-DATE-TIME tag SHOULD be aligned with the airtime of the content.

      8.6. If your media playlists are created from static source content (VOD), you MUST add the EXT-X-PLAYLIST-TYPE with the value VOD.

      8.7. Within one asset, all media playlists with an EXT-X-PLAYLIST-TYPE of VOD MUST cover exactly the same media time range.

      8.8. If your media playlists are event style (start from a fixed point with segments never removed), you MUST add the EXT-X-PLAYLIST-TYPE with the value EVENT.

      8.9. Separate audio streams MUST be declared using EXT-X-MEDIA tags.

      8.10. The LANGUAGE attribute MUST be included in every EXT-X-MEDIA tag that does not have TYPE=VIDEO.

      8.11. You MUST provide at least 6 segments in a live/linear playlist.

      8.12. You SHOULD provide at least 15 minutes of content in a live/linear playlist.

      8.13. Breaks of encoding continuity MUST be indicated with the EXT-X-DISCONTINUITY tag.

      8.14. Video frame rate changes MUST be marked as a discontinuity using EXT-X-DISCONTINUITY tags.

      8.15. All variants and renditions MUST have discontinuities at the same points in time.

      8.16. If live/linear content will ever contain an EXT-X-DISCONTINUITY tag then the EXT-X-DISCONTINUITY-SEQUENCE tag MUST always be present.

      8.17. Your media requests MUST NOT use HTTP redirects, with the exception of ad content to allow dynamic selection of ads.

      8.18. You SHOULD identify interstitial and program boundaries using the EXT-X-DATERANGE tag.

      8.19. If using fMP4, EXT-X-MAP tags MUST be present.

Master Playlist

  • 9. Master playlist requirements

    • 9.1. Your EXT-X-STREAM-INF tag MUST always provide the CODECS attribute.

      9.2. Your EXT-X-STREAM-INF tag MUST always provide the RESOLUTION attribute if the rendition(s) include video.

      9.3. Your EXT-X-I-FRAME-STREAM-INF tag MUST always provide the CODECS attribute.

      9.4. Your EXT-X-I-FRAME-STREAM-INF tag MUST always provide the RESOLUTION attribute.

      9.5. You SHOULD deliver video and audio as separate streams.

      9.6. If you have multichannel audio, you MUST use separate audio streams.

      9.7. If you have alternate audio content (languages/commentary/DVS), you MUST use separate audio streams.

      9.8. If you have different video angles, you MUST use separate audio streams.

      9.9. You MUST provide multiple bit rates of video (aka variants).

      9.10. For HD content, there SHOULD be at least two variants encoded at the highest-available resolution.

      9.11. If your video segments start with an IDR then you SHOULD use the EXT-X-INDEPENDENT-SEGMENTS tag in the master playlist. (See item 7.4.)

      9.12. If your video segments start with an IDR and the EXT-X-INDEPENDENT-SEGMENTS tag is not in the master playlist, then you MUST use the EXT-X-INDEPENDENT-SEGMENTS tag in all video media playlists. (See item 7.4.)

      9.13. The BANDWIDTH attribute MUST be the largest sum of peak segment bit rates that is produced by any playable combination of renditions.

      9.14. You MUST include the AVERAGE-BANDWIDTH attribute.

      9.15. Each EXT-X-STREAM-INF tag MUST have a FRAME-RATE attribute.

Delivery

  • 10. Delivery requirements

    • 10.1. The server MUST deliver playlists using gzip content-encoding.

      10.2. You SHOULD support stream failover, for example by listing duplicate streams in the Master Playlist.

      10.3. Media data SHOULD NOT be delivered to the application through a local server.

Privacy

  • 11. Privacy requirements

    • 11.1. Master playlists SHOULD be delivered using Transport Layer Security (TLS).

      11.2. Media playlists SHOULD be delivered using TLS.

      11.3. Media Segments SHOULD be delivered using TLS.

      11.4. Media Segment URLs requested over unencrypted transport SHOULD NOT contain revealing strings such as movie title, show title, episode name, episode number, genre, advertiser, or product.

Security

  • 12. Security requirements

    • 12.1. Transport Layer Security (TLS) MUST be version 1.2 with forward security.

      12.2. TLS MUST NOT use known-insecure cryptographic primitives (e.g., RC4 encryption, SHA-1 certificate signatures).

      12.3. Within TLS, key sizes MUST be 2048 bits for RSA and 256 bits for EC.

      12.4. The URLs for Media Segments SHOULD not be completely static. URLs should be issued per device or changed over time.

Content Protection

  • 13. Content protection requirements

    • 13.1. Content protection SHOULD follow the FairPlay Streaming (FPS) specification.

      13.2. If content is encrypted with FPS the method MUST be SAMPLE-AES.

      13.3. If content is encrypted with FPS  the key format MUST be "com.apple.streamingkeydelivery".

      13.4. The IV attribute SHOULD NOT be used with FPS unless necessary for interoperability.