Encoder integration for HLS

HTTP Live Streaming (HLS) version

Ad Manager DAI supports HLS version 3. Any features not part of HLS version 3 must be discussed with your Ad Manager account team.

See which features are supported

Feature Linear / Live Video on demand (VOD)
EXTINF
EXT-X-DATERANGE
SCTE35-IN x
SCTE35-OUT x
EXT-X-DISCONTINUITY
EXT-X-DISCONTINUITY-SEQUENCE
EXT-X-ENDLIST
EXT-X-I-FRAME-STREAM-INF
EXT-X-I-FRAMES-ONLY
EXT-X-INDEPENDENT-SEGMENTS x
EXT-X-KEY
EXT-X-MEDIA (Rendition Groups)
EXT-X-MEDIA-SEQUENCE
EXT-X-PLAYLIST-TYPE
EXT-X-PROGRAM-DATE-TIME
EXT-X-STREAM-INF
AUDIO
AVERAGE-BANDWIDTH
BANDWIDTH
CLOSED CAPTIONS
CODECS
FRAMERATE
RESOLUTION
SUBTITLES
VIDEO
EXT-X-TARGETDURATION
EXT-X-VERSION

Playlists and Rendition Groups

Deliver playlists using GZIP content-encoding (recommended). Variants in master playlists and segments can use either absolute URLs or relative URLs.

All ad assets are transcoded to include I-FRAME playlists, including slates. Ad Manager DAI does not generate I-FRAME playlists from the content or generate new Rendition Groups based on combinations of video/audio.

  • For live linear: I-FRAME playlists must be generated and conditioned by the encoder/packager. Rendition Groups are delivered as they're generated from the Live encoder.
  • For video on demand (VOD): If required, I-FRAME playlists must be supplied in the master manifest at ingest. Ad Manager will only raise an error if the provided I-FRAME playlist file cannot be accessed or parsed. Rendition Groups are delivered as they are provided in the master manifest.

Codecs and Resolution

HLS master playlists for live streams and video on demand (VOD) assets must include the optional CODECS and RESOLUTION attributes. These attributes are used to find suitable ads that match these encoding settings. If these values are not provided, ads are matched based on bandwidth alone and may result in a mismatch of resolution and codecs between ad and content. This can lead to poor user experience and playback issues across different devices.

The CODECS attribute must contain both the audio and the video codecs. Your encoder may add or remove variants to your master playlist URL at any time.

Audio codecs

DAI supports the AAC audio codec. DAI also supports the AC-3 and E-AC-3 (Beta)  codecs, currently in beta.

Keep variant stream URLs consistent for each CODECS and RESOLUTION combination.
You should ensure that your encoder is configured to maintain consistent URLs for each variant URL to prevent playback problems for your users.

Example

A master playlist with CODECS and RESOLUTION


#EXTM3U
#EXT-X-VERSION:3
#EXT-X-STREAM-INF:BANDWIDTH=694272,CODECS="avc1.77.41,mp4a.40.2",RESOLUTION=768x432
chunklist_b694272.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=202752,CODECS="avc1.66.31,mp4a.40.2",RESOLUTION=480x270
Chunklist_b202752.m3u8

Segment duration

HLS media playlists must have media segment durations declared as decimal-floating-point numbers. The duration should have floating point accuracy to help determine the precise time when an ad break will start and end. The less accurate the duration values, the less accurately the system is able to determine when ad breaks occur in the resulting stream.

Example

A media playlist with #EXTINF


#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:10
#EXT-X-MEDIA-SEQUENCE:26
#EXTINF:9.901,
http://media.example.com/wifi/segment26.ts
#EXTINF:9.901,
http://media.example.com/wifi/segment27.ts
#EXTINF:9.501,
http://media.example.com/wifi/segment28.ts

Timestamp alignment

The Presentation Timestamp (PTS) across segments in variant media playlists must align. P-frame and B-frame refers other frames to decode a frame.The H.264 codec also references frames that are not adjacent for better compression. Since these frames depend on other frames for decoding and presentation, Decode Timestamp (DTS) gives sequence by which frames are decoded and PTS gives sequence by which frames are presented. Aligning PTS is important when you adapt to different bitrate while playback of an asset. Ad insertion uses PTS to find the ad insertion position.

Discontinuity

Any EXT-X-DISCONTINUITY in the media playlist must have EXT-X-DISCONTINUITY-SEQUENCE. The EXT‑X‑DISCONTINUITY‑SEQUENCE tag allows synchronization between different renditions of the same variant stream or different variant streams.

Media encryption

If you want to encrypt the media content, its must be encrypted with AES-128 or SAMPLE-AES. AES-128 encrypts or scrambles the TS while SAMPLE‑AES scrambles individual media (audio or video). Apple Fairplay stream uses SAMPLE‑AES.

Ad Manager DAI supports FairPlay DRM technology for HLS streams.

Example

A media playlist with #EXT-X-KEY


#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:10
#EXT-X-MEDIA-SEQUENCE:26
#EXT-X-KEY:METHOD=AES-128,URI="https://media.example.com/asset/key1.php?id=<signature>",IV=<initialization vector>
#EXTINF:9.901,
http://media.example.com/wifi/segment26.ts
#EXTINF:9.901,
http://media.example.com/wifi/segment27.ts
#EXT-X-KEY:METHOD=AES-128,URI="https://media.example.com/asset/key2.php?id=<signature>"
#EXTINF:9.501,
http://media.example.com/wifi/segment28.ts

Video on demand encoding

Conditioning for mid-rolls

If you need to serve mid-roll ads in your content, the video segments must either be pre-conditioned or conditioned.

Mid-roll ad breaks for DAI may not fall on the typical video segment boundaries for your stream. For example, your content may normally be divided into 10-second segments, but you may require an ad break at 0:36 (36 seconds). In this case, you need to divide a 10-second video into 2 separate segments that are 6 seconds and 4 seconds, respectively, allowing for an ad to be inserted at the correct time. The process of dividing a video segment to enable an ad break is called "content conditioning".

In order to support the insertion of ads at the desired ad break locations, you must either provide content that is preconditioned or content that is able to be conditioned by Ad Manager.

GOP size

Media must be encoded with a keyframe every 2 seconds or GOP (group of pictures) size of 2 seconds. Content is prepared for mid-roll ad break insertion at the closest keyframe. If there is no keyframe with in one second of cue point, insertion of ads beyond a second from cue point will lead to a poor user experience during playback. To prevent this, if a keyframe cannot be found within one second of the indicated cue point, an ad break will not be inserted.

It is recommended that you provide 1-2 seconds of creative blacks around the cue points for seamless transition between content and ads. This gives a fade-to-black TV experience around the ad breaks.

Closed captions

The following closed caption formats are supported:

  • Input formats: TTML (sidecar), WebVTT (sidecar), CEA 608/708
  • Output formats: TTML (sidecar), WebVTT (sidecar), WebVTT - HLS

Ad Manager converts the input format to output format.

Live linear encoding

HLS linear ad insertion

Create OUT and IN cue points in the playlist representing the ad insertion splice points for a linear broadcast or live feed:

#EXT-X-CUE-OUT:DURATION=<time>
#EXT-X-CUE-IN

The EXT-X-CUE-OUT tag represents the splice start point and EXT-X-CUE-IN represents the splice end point.

The EXT-X-CUE-OUT tag should be terminated by an EXT-X-CUE-IN tag indicating the end of the ad break.

The ad server replaces the entire section between the EXT-X-CUE-OUT tag and EXT-X-CUE-IN with video ad content.

The DURATION=<time> is required, and is the approximate duration in seconds or floating point of the ad break (in other words, the difference in the time between the EXT-X-CUE-IN and EXT-X-CUE-OUT). Alternately, EXT-X-CUE-OUT:<time> can be substituted for #EXT-X-CUE-OUT:DURATION=<time>.

The duration can be an integer or a floating-point value and should have a value expressed in seconds.

Example

Splice start point and end point


#EXTINF:10,
http://media.example.com/fileSequence7796.ts
#EXTINF:6,
http://media.example.com/fileSequence7797.ts
#EXT-X-CUE-OUT:DURATION=30
#EXTINF:4,
http://media.example.com/fileSequence7798.ts
#EXTINF:10,
http://media.example.com/fileSequence7799.ts
#EXTINF:10,
http://media.example.com/fileSequence7800.ts
#EXTINF:6,
http://media.example.com/fileSequence7801.ts
#EXT-X-CUE-IN
#EXTINF:4,
http://media.example.com/fileSequence7802.ts
#EXTINF:10,
http://media.example.com/fileSequence7803.ts
#EXTINF:3,
http://media.example.com/fileSequence7804.ts

Example

Content between OUT and IN is replaced by the DAI ad server with 30 seconds of ad video content


#EXTINF:10,
http://media.example.com/fileSequence7796.ts
#EXTINF:6,
http://media.example.com/fileSequence7797.ts
#EXT-X-CUE-OUT:DURATION=30
#EXTINF:10,
http://ads.example.com/fileSequence0001.ts
#EXTINF:10,
http://ads.example.com/fileSequence0002.ts
#EXTINF:10,
http://ads.example.com/fileSequence0003.ts
#EXT-X-CUE-IN

#EXTINF:4,
http://media.example.com/fileSequence7802.ts
#EXTINF:10,
http://media.example.com/fileSequence7803.ts
#EXTINF:3,
http://media.example.com/fileSequence7804.ts

Frequently asked questions

  • How do I end an ad break early?
    The encoder should send in a "CUE-IN" in the stream to indicate that the DAI streams should immediately end the ad break and begin showing the raw content again.
  • How do I make an ad break longer?
    There is no way to make an ad break longer while the ad break is playing to users, but an encoder may send an additional a "CUE-OUT" in the stream immediately after the previous ad break’s "CUE-IN", which would create an additional ad break with freshly decisioned ads.
  • What happens if there are no ads to show?
    The user will either see slate content or the underlying content, depending on the setting that was chosen when the live stream was configured in Ad Manager DAI.
Was this helpful?
How can we improve it?