> For the complete documentation index, see [llms.txt](https://docs.cstplus.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cstplus.org/documentation/guides/ad-insertion-ssai.md).

# Ad Insertion (SSAI)

CST+ supports server-side ad insertion (SSAI): ads are stitched directly into the HLS stream on the server. Viewers cannot skip or block them, and no changes are needed in their app.

{% hint style="warning" %}
Ad insertion requires a **Pro or Business** license. The ad markers toggle is not shown on Starter plans.
{% endhint %}

***

### How it works

When the edge server reaches a break signal in the stream, it:

1. Pauses the main content
2. Fetches an ad from your VAST/VMAP ad server (or picks a house ad)
3. Transcodes the ad to match the channel's output profile
4. Stitches it into the HLS segments seamlessly
5. Resumes the main content
6. Records the impression

From the viewer's side, the ad plays as part of the stream with no buffering or gap.

***

### Enabling ads on a channel

Open a channel and go to **Settings** (gear icon). Under **Ad markers**, enable the toggle. Then choose a break mode:

{% tabs %}
{% tab title="Interval mode" %}
Breaks fire automatically every N minutes. Set the interval and the break duration. Simple and hands-off.

Best for channels where you do not control the schedule tightly.
{% endtab %}

{% tab title="Manual mode" %}
You place breaks at exact timestamps on the channel page.

Best for schedule mode channels where you want ad slots precisely between programmes.
{% endtab %}
{% endtabs %}

Set the **break duration** in seconds. If the fetched ad is shorter than the slot, the remainder is filled with a house ad.

***

### Connecting an ad server

In the **Ad server URL** field, enter your VAST or VMAP endpoint.

{% tabs %}
{% tab title="Supported formats" %}

* VAST 2.0
* VAST 3.0
* VMAP 1.0

The ad server should return an MP4 or HLS creative. CST+ downloads, transcodes, and caches it. The same creative is not re-transcoded twice.
{% endtab %}

{% tab title="Fallback behaviour" %}
{% hint style="warning" %}
If the ad server request fails or returns no fill, CST+ falls back to house ads automatically. If no house ads are configured either, the break slot plays silence. Always set up house ads as a fallback.
{% endhint %}
{% endtab %}
{% endtabs %}

***

### House ads

House ads are your own promotional clips that play when the ad server returns no fill, or when no external ad server is configured at all.

Go to **Settings > Ad insertion** and add the folder or specific files to use. CST+ picks from them randomly to fill any unfilled break time.

{% hint style="success" %}
House ads alone work well for self-promotion between programmes, and guarantee the break slot is never empty.
{% endhint %}

***

### Ad metrics

Go to **Analytics > Ad performance**:

| Metric            | What it shows                                         |
| ----------------- | ----------------------------------------------------- |
| Total impressions | All recorded breaks, split by VAST fill vs house fill |
| Fill rate         | Percentage of breaks that got a paid (VAST) fill      |
| Viewer count      | How many people were watching at impression time      |
| Breakdown         | Per channel and per time range                        |

{% hint style="info" %}
Impressions are deduplicated per break event. Reloads and reconnections during a break do not inflate the count.
{% endhint %}

***

### Server load

SSAI transcodes ad creatives on demand. Your server should have at least 2 CPU cores available during peak ad load.

{% hint style="success" %}
On a 4-core VPS running 3 to 5 channels with ads enabled, render and ad transcoding coexist without issues. Monitor CPU usage during peak hours if you are running more channels.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cstplus.org/documentation/guides/ad-insertion-ssai.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.