Docs/SSAI/HLS Protocol

HLS Protocol Support

RFC 8216 compliant HLS manifest generation with proper live sliding window behavior, discontinuity handling, and CDN-safe caching for SSAI.

RFC 8216 Compliance

ApexMediation generates HLS playlists that fully comply with RFC 8216 (HTTP Live Streaming). Every aspect of the specification is validated during manifest generation.

Master Playlist Structure

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-INDEPENDENT-SEGMENTS

#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="aac",NAME="English",DEFAULT=YES,AUTOSELECT=YES,LANGUAGE="en",URI="audio/en/playlist.m3u8"

#EXT-X-STREAM-INF:BANDWIDTH=2800000,CODECS="avc1.64001f,mp4a.40.2",RESOLUTION=1280x720,AUDIO="aac"
video/720p/playlist.m3u8

#EXT-X-STREAM-INF:BANDWIDTH=5000000,CODECS="avc1.640028,mp4a.40.2",RESOLUTION=1920x1080,AUDIO="aac"
video/1080p/playlist.m3u8

Compliance Checkpoints

#EXTM3U Required

Every playlist starts with the required #EXTM3U tag

EXT-X-VERSION Consistency

Version tag matches features used (v6+ for EXT-X-DATERANGE)

EXTINF Precision

Every segment has nonzero duration with correct precision

TARGETDURATION Accuracy

EXT-X-TARGETDURATION is ceiling of longest segment (never exceeded)

Live Sliding Window Behavior

Live HLS playlists use a sliding window that maintains a fixed duration of content. As new segments are added, old segments are removed. The SSAI system handles this correctly even with ad breaks in the window.

✅ Correct Behavior

EXT-X-MEDIA-SEQUENCE is monotonically increasing
Sequence increments by exactly 1 per removed segment
No EXT-X-PLAYLIST-TYPE tag in live playlists
Window doesn't shrink too aggressively (prevents drift)

❌ Avoided Problems

Media sequence jumping or decreasing (causes player errors)
Adding EVENT/VOD type to live streams
Discontinuity drift from aggressive window shrinking
Segments falling out mid-ad break

Live Media Playlist Example

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:2847
#EXT-X-DISCONTINUITY-SEQUENCE:12
#EXT-X-PROGRAM-DATE-TIME:YYYY-MM-DDTHH:MM:SSZ

#EXTINF:6.000,
https://cdn.example.com/content/seg2847.ts
#EXTINF:6.000,
https://cdn.example.com/content/seg2848.ts
#EXTINF:6.000,
https://cdn.example.com/content/seg2849.ts

#EXT-X-DATERANGE:ID="ad-pod-1",CLASS="com.apple.hls.interstitial",START-DATE="YYYY-MM-DDTHH:MM:SSZ",DURATION=30
#EXT-X-DISCONTINUITY

#EXTINF:6.000,
https://ssai.apexmediation.ee/session/abc123/ad/slot1-seg1.ts
#EXTINF:6.000,
https://ssai.apexmediation.ee/session/abc123/ad/slot1-seg2.ts
#EXTINF:6.000,
https://ssai.apexmediation.ee/session/abc123/ad/slot1-seg3.ts
#EXTINF:6.000,
https://ssai.apexmediation.ee/session/abc123/ad/slot1-seg4.ts
#EXTINF:6.000,
https://ssai.apexmediation.ee/session/abc123/ad/slot1-seg5.ts

#EXT-X-DISCONTINUITY

#EXTINF:6.000,
https://cdn.example.com/content/seg2850.ts
#EXTINF:6.000,
https://cdn.example.com/content/seg2851.ts

EXT-X-DATERANGE for Ad Markers

Ad breaks are signaled using EXT-X-DATERANGE tags per the Apple HLS interstitials specification. This allows players to identify ad content and provide appropriate UI treatment.

DATERANGE Attributes

Attribute	Description	Example
`ID`	Unique pod identifier	`"ad-pod-1"`
`CLASS`	Apple interstitial class	`"com.apple.hls.interstitial"`
`START-DATE`	ISO 8601 start time	`"YYYY-MM-DDTHH:MM:SSZ"`
`DURATION`	Pod duration in seconds	`30`
`X-SLOT-COUNT`	Number of ads in pod	`2`

Player Detection

The ApexMediation SDK parses DATERANGE tags to identify ad boundaries:

// Web SDK (TypeScript)
import { SSAIManifestParser } from '@apexmediation/web-sdk';

const parser = new SSAIManifestParser();
const adBreaks = parser.parseHLSManifest(manifestContent);

adBreaks.forEach(adBreak => {
  console.log('Ad break:', adBreak.id);
  console.log('  Start:', adBreak.startTime);
  console.log('  Duration:', adBreak.duration);
  console.log('  Slots:', adBreak.slotCount);
});

Discontinuity Handling

Ad content typically has different encoding parameters than program content. The SSAI system correctly handles discontinuities to ensure seamless playback.

EXT-X-DISCONTINUITY

Inserted at content-to-ad and ad-to-content transitions when encoding parameters (codec, timescale, resolution) differ.

EXT-X-DISCONTINUITY-SEQUENCE

Maintained monotonically across manifest updates. Increments correctly when discontinuity tags slide out of the live window.

Cross-Rendition Consistency

All renditions have matching discontinuity counts at equivalent playback positions to prevent ABR switching issues.

Common Integration Issues

hls.js warnings: Usually caused by discontinuity sequence mismatch or aggressive window shrinking. The SSAI system avoids these patterns.
Player "reset" at ad boundaries: Often caused by missing discontinuity tags. All ad transitions include proper markers.
ABR issues during ads: Caused by inconsistent discontinuity counts across renditions. Our system ensures cross-rendition consistency.

CDN Caching Strategy

Session manifests contain personalized ad content and must not be cached at CDN edges. Segments, however, are cacheable.

Session Manifests

Cache-Control: private, no-store, max-age=0
Vary: Accept-Encoding, Cookie

• private: Not cached by shared caches
• no-store: Never cached
• Tokenized URLs for additional protection

Segment Files

Cache-Control: public, max-age=31536000, immutable

• public: Cacheable by all caches
• Long TTL with immutable content
• Unique URLs per segment version

Cache Poisoning Prevention

Session manifests are protected from cache poisoning attacks. Even if a CDN were misconfigured, the signed session token in the URL helps reduce the risk of cross-user cache poisoning. You should still configure your CDN to bypass caching for session manifests.

VOD-Specific Requirements

EXT-X-ENDLIST Required

VOD playlists always end with #EXT-X-ENDLIST to signal finite content. This is critical for player seek behavior and progress UI.

EXT-X-PLAYLIST-TYPE:VOD

VOD playlists include the EXT-X-PLAYLIST-TYPE:VOD tag to indicate immutable content (no segments will be added or removed).

Complete Timeline

VOD manifests include all content and ad segments from the start. Ads are pre-stitched at session creation time.

Player Compatibility

Player	Live	VOD	DATERANGE	CMAF	Notes
hls.js	✓	✓	✓	✓	Web, most browsers
Safari AVPlayer	✓	✓	✓	✓	Native HLS support
tvOS AVPlayer	✓	✓	✓	✓	Apple TV native
ExoPlayer (HLS)	✓	✓	✓	✓	Android, Fire TV
Shaka Player (HLS)	✓	✓	✓	✓	Cross-platform