# Ad Replacement

Audalaxy enables precise replacement of specific audio segments within a live stream with advertising. The configuration is managed through our Console UI. Below is a technical overview of the workflow.

## Stream Flow

During ad replacement, the stream follows this structure:

`<-- Stream -- [Metadata: ADBREAK_LENGTH_30000] --- [StartBeepTrigger, removes all frames until end trigger] Playing Ads (Replacement Zone xxxxx) [EndBeepTrigger] [Stream continues] --> Stream <--`

## Requirements

The following components are necessary to enable seamless ad replacement:

### Metadata

**Before** the actual trigger, metadata must be sent to announce the duration of the segment to be replaced. This is required to call the ad server in advance and ensure ads are returned in time.

**The metadata format must be:**

`ADBREAK_LENGTH_xxxxxx`

The duration of the ad break is specified in milliseconds.

*Example:*

`ADBREAK_LENGTH_30000`

This indicates a replacement duration of 30,000 ms (30 seconds).

{% hint style="info" %}
This metadata is used solely to control ad replacement and **is not sent to listeners**.
{% endhint %}

### Start Trigger

An audio trigger is required at the **exact start** of the segment that should be replaced:

* **Frequency:** 18 Hz
* **Duration:** 1500 ms
* **Signal:** Phase-inverted on both left and right channels
* **Note:** This is the same beep used for ad insertion triggers.

{% hint style="info" %}
All frames between the start and end triggers in the original stream will be removed and replaced with ads.If there is not enough buffer and we don't get ads back, we keep the stream as is to avoid interruptions.
{% endhint %}

### End Trigger

An audio trigger is also required at the **exact end** of the segment:

* **Frequency:** 18 Hz
* **Duration:** 500 ms
* **Signal:** Phase-inverted
* **Note:** Identical to the start beep, but shorter.

## Detection & Timing

**Before a break starts:**

Send the replacement length via Icecast metadata using the format:

`ADBREAK_LENGTH_<ms>`

*Example:*

`ADBREAK_LENGTH_30000`

(For 30,000 ms = 30 seconds)

**In the audio stream:**

In the audio, set the frame header copyright bit to 1 starting with the first frame to be replaced and keep it at 1 for all frames in the replacement window. After the last frame, set it back to 0.\
(This will be handled by our Bitflipper service in the future just like we do with injection.)

## Configuration in Console

**To configure ad replacement:**

1. Configure an **ad zone alias** for mid-rolls&#x20;
2. At the same place you can fine tune shifts/delays for the start and end trigger in case this is needed.
3. Set the **trigger** to **Bitflip**
4. In **Advanced Settings**, add this key/value: `"adinjection": "replace"`

## Ad Request Behavior

* We request ads whose **total duration is up to** the declared replacement length.
* The **maximum number of ads** is currently fixed at `replacement_duration / 15` (Hard-coded for now)

This ensures enough inventory so that the ad server can return one or more ads to fill the window up to the total length.

{% hint style="info" %}
If the returned ad duration is too short to fill the declared replacement length and there is not enough buffer for this listener to fill the gap, we will discard the ad and play the original stream content.
{% endhint %}

## Optional Filler

If the returned creatives are shorter than the replacement window, we can fill the remaining duration with audio fillers. Please provide a small library of audio files in various lengths (e.g., 1–30 s+) that can be used to close any remaining gap. The system selects one or more random files that match the required duration and plays them after the ads.

### Pre-Announcement (Metadata)

Before the segment to be replaced, metadata must be sent in the following format:


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://audalaxy.gitbook.io/docs/ad-integration/ad-replacement.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.