Contents

Delivering ad interstitials in podcast streams

Insert ad interstitials into HTTP Live Streaming (HLS) media playlists.

Overview

An HLS interstitial is alternate content, such as an advertisement, that the player inserts into a stream at a specific point without altering the primary media. Use the #EXT-X-DATERANGE tag in your HLS media playlists to deliver client-side interstitial advertising. Place an exact segment boundary at each interstitial cue point in your encoded media when possible. Use X-SNAP to let the player correct splice timing automatically. Include CUE=POST when you deliver a post-roll interstitial.

Use the following attributes with #EXT-X-DATERANGE for interstitial delivery:

#

Attribute

Description

Required

Example Value

1

CLASS

Identifies the DATERANGE as an interstitial. Must be set to com.apple.hls.interstitial.

Required

CLASS="com.apple.hls.interstitial"

2

START-DATE

A timestamp indicating the exact point in time, relative to the #EXT-X-PROGRAM-DATE-TIME of the playlist, where the interstitial should begin playback.

Required

START-DATE="2023-10-27T10:00:00Z"

3

PLANNED-DURATION

A float value representing the intended (but not-to-exceed) duration of the interstitial.

See Note below.

PLANNED-DURATION=30.0

4

DURATION

A float value representing the known, exact duration of the interstitial. If both PLANNED-DURATION and DURATION are present, DURATION takes precedence.

See Note below.

DURATION=28.5

5

X-SNAP

Instructs the player to snap the interstitial splice point to the nearest segment boundary in the primary content. Accepts OUT, IN, or OUT,IN to apply snapping at the exit point, resume point, or both.

Recommended

X-SNAP="OUT,IN"

6

X-RESUME-OFFSET

Specifies the offset time from the primary media. For interstitials, this is typically set to 0.

Required for Podcasts

X-RESUME-OFFSET=0

7

X-TIMELINE-OCCUPIES

Indicates how the interstitial is displayed within the episode timeline. For seamless integration, set to RANGE.

Required for Podcasts

X-TIMELINE-OCCUPIES="RANGE"

8

X-TIMELINE-STYLE

Defines the style of the interstitial’s timeline representation. For primary media, set to PRIMARY.

Required for Podcasts

X-TIMELINE-STYLE="PRIMARY"

Interstitial media can be delivered using one of two methods:

Reference the interstitial directly with the asset URI

Use X-ASSET-URI when you know the interstitial media playlist and it’s available when you create the HLS playlist. This attribute points directly to the interstitial’s HLS media playlist.

#EXT-X-DATERANGE:ID="ad_break_1",CLASS="com.apple.hls.interstitial",START-DATE="2023-10-27T10:00:00Z",PLANNED-DURATION=30.0,X-ASSET-URI="https://ad-server.example.com/ads/midroll1.m3u8",X-RESUME-OFFSET=0,X-TIMELINE-OCCUPIES="RANGE",X-TIMELINE-STYLE="PRIMARY"

Resolve interstitials at playback

Use X-ASSET-LIST when you need flexibility to determine the interstitial media at playback or download time, or when no interstitial may be available. This attribute points to a JSON response that contains the interstitial media playlist information.

#EXT-X-DATERANGE:ID="ad_break_1",CLASS="com.apple.hls.interstitial",START-DATE="2023-10-27T10:00:00Z",PLANNED-DURATION=30.0,X-ASSET-LIST="https://ad-server.example.com/ads/midroll1.json",X-RESUME-OFFSET=0,X-TIMELINE-OCCUPIES="RANGE",X-TIMELINE-STYLE="PRIMARY"

The JSON response specified by X-ASSET-LIST must contain an ASSETS array. Each object in the array represents an interstitial asset and includes the following keys:

URI

The URL of the interstitial’s HLS media playlist.

DURATION

A float value indicating the exact duration of the interstitial in seconds.

{
  "ASSETS": [
    {
      "URI": "https://example.com/ads/interstitial_1.m3u8",
      "DURATION": 15.0
    }
  ]
}

When you have no ad to place, use an empty list. The player skips the ad break and continues playing the main media.

{
  "ASSETS": []
}

See Also