Ad Breaks

Monetize your streams with server-side ad insertion (SSAI).

How it works

Ads are injected server-side — the viewer's player receives a modified HLS playlist that includes ad segments. The viewer cannot skip or block the ads because they are part of the video stream itself.

Camera → xStreams → Ad Worker (inserts ads into playlist) → Viewer

No client-side ad SDK needed. The player SDK handles ad breaks automatically.

Ad break types

Type	Trigger	Description
Pre-roll	First playlist request	Plays before the live stream starts
Mid-roll	Scheduled or frequency-based	Plays during the stream at intervals
Manual	Dashboard button	You trigger it from the Dashboard

Set up ads

1. Create an ad campaign

Go to Dashboard → Advertisements → Create Campaign.

• Upload your ad video (or use a media file from your library).
• Set the campaign as "Active".
• Link it to one or more streams.

2. Configure viewer logic

Dashboard → Advertisements → Viewer Logic.

• Session window — how long a viewer session lasts (e.g., 30 minutes).
• Frequency cap — max ads per session.
• Minimum ad gap — minimum time between ads (e.g., 5 minutes).
• Daily impression cap — max impressions per day per campaign.

3. Trigger a manual ad break

Dashboard → Streams → your stream → click "Trigger Ad Break".

The ad plays for all current viewers within a few seconds.

Player SDK behavior

The player SDK detects ad breaks automatically and fires events:

player.on('adstarted', ({ duration }) => {
  console.log(`Ad break started — ${duration} seconds`);
  // Show "Ad" badge, hide controls, etc.
});

player.on('adended', () => {
  console.log('Ad break ended');
  // Hide "Ad" badge, restore controls
});

You don't need to write any ad-loading logic. The server handles everything.

Shaka vs hls.js ad insertion

	Shaka Edition	hls.js Edition
Method	HLS Interstitials (EXT-X-DATERANGE)	SCTE-35 discontinuity injection
Client logic	None — Shaka handles it natively	Polls Worker for break status
Recommendation	Preferred for new projects	Use if you already use hls.js