RSAS can dynamically insert preroll and midroll ads into a live audio stream. During an ad break, live audio is replaced with the audio from one or more ads. The list of ads to play is programmable
Ad audio files must be hosted at a publicly accessible URL, and can be hosted on the same RSAS instance that is serving the stream. Ad audio files must precisely match the audio format of the stream in order for playback to work. Specifically, the codec, container, bitrate, channel count, and samplerate must match. With some codecs, there may be additional parameters that must match (eg. MP3 stereo mode).
We currently recommend using ad insertion with AAC-family codecs. AAC ad files must be ADTS-encapsulated (.aac, not .m4a).
MP3 is supported but has not been extensively tested.
A preroll ad is a short audio clip that plays when a listener first connects, before your live audio is played.
To configure a static preroll ad, which is the same for all listeners, add a <preroll> section to your mount configuration:
<mount>
<mount-name>/radio</mount-name>
<preroll>preroll.aac</preroll> <!-- The preroll must be a relative path to a file inside your webroot directory. -->
</mount>
The preroll value can be either a path on disk or a remote URL. Preroll files on disk must be located inside your webroot
path and the preroll path must be relative to the webroot. For remote URLs, prerolls are downloaded and cached on-demand.
Dynamic preroll ads allow each listener to hear a different ad. You can customize preroll ads on a per-listener
by using Webhook Listener Authentication and
providing a different preroll response header for each listener.
A postroll ad is a short audio clip that plays after a listener has exceeded the max listener session duration. This is used to impose a time limit on a listener, with a postroll ad used as a call to action.
To configure a static postroll ad, which is the same for all listeners, add a <postroll> section to your mount configuration:
<mount>
<mount-name>/radio</mount-name>
<!-- Play this postroll ad after an hour -->
<postroll>postroll.aac</postroll>
<max-listener-duration>3600</max-listener-duration>
</mount>
See the section above on preroll for allowable values of the <postroll> field.
Dynamic postroll ads can be inserted by using Webhook Listener Authentication, which also allows customizing the time limit for each listener.
Midroll ads are audio clips played in the middle of a stream. Insertion of midroll ads can be triggered by special metadata from your encoder, which indicates an ad break, or via the Manage API.
Midroll ad insertion is a powerful feature that gives broadcasters the flexibility to build custom dynamic audio replacement, for use cases such as:
RSAS does not (yet) integrate directly with an ad network, but instead provides the necessary integration hooks for a developer to build that integration.
Ads can be inserted for all listeners on a mount using a simple HTTP request to the Manage API:
curl -v -u admin:adminpass http://127.0.0.1:8000/radio/manage -d action=midroll -d json='{"ads":[{"duration_msec":5000,"url":"http://127.0.0.1:8011/bongo.aac","title":"Ad 1"},{"duration_msec":5000,"url":"http://127.0.0.1:8011/bongo.aac","title":"Ad 2"}]}'
The HTTP request is an HTTP POST, with two form encoded parameters:
action=midrolljson=...where json should contain the same fields as the midroll webhook handler response described below.
Ad insertion can be triggered by RSAS receiving a special metadata keyword from the encoder that is broadcasting on a mount. In typical usage, a broadcaster would schedule a silent ad placeholder AAC file containing the ad trigger metadata in your radio automation software.
In the <mount> section of your config, specify the URL to your midroll webhook handler:
<mount>
<mount-name>/radio</mount-name>
<midroll-webhook>http://mywebsite.com/midroll</midroll-webhook>
</mount>
(You must specify this for each <mount>)
To trigger ad insertion via metadata, use RSAD#####, where ##### is the duration of the ad break in milliseconds. (eg. Having RSAD30000 in the artist or title metadata will trigger a 30 second ad break.)
After the ad insertion metadata trigger is received, RSAS will make an HTTP request to the midroll webhook URL. The request is an HTTP POST request with the following parameters:
action - Must be midroll_reqmountduration_msec - the duration of the requested ad break. serverportipcontent-typeice-bitrateice-samplerateice-channelssong - the ad trigger metadata received by RSAS from the encoder, which initiated this request The response from the webhook handler should be a list of ads formatted as JSON (content-type: application/json), like so:
{
"ads": [
{
"duration_msec": 5000,
"url": "http://127.0.0.1:8011/ad1.aac",
"title": "Ad 1"
},
{
"duration_msec": 5000,
"url": "http://127.0.0.1:8011/ad2.aac",
"title": "Ad 2"
}
]
}
RSAS will download each ad and insert them into the stream of each listener on the mount. The ads will play back to back with no gap in between. After the ad break, the listener will hear about 2 seconds of silence before the audio resumes. (RSAS cuts back to the live audio 2 seconds early.)
It is the responsibility of the webhook handler to ensure the total duration of the ads list returned is equal to the requested ad break duration.
During ad playback, the metadata specified in the title field in the JSON will be sent to listeners as in-stream metadata
and appear as the "Now Playing" track in their player.
If no title is specified, RSAS will display the metadata that is specified in the top-level <default-midroll-title> setting
in your RSAS config file. The default is an empty string.
For production deployments, we recommend specifying a custom default midroll title in your RSAS configuration, such as:
<default-midroll-title>Thank you for listening</default-midroll-title>
When scheduling ad breaks in your radio automation software for online streaming, it is recommended to use silent AAC files with metadata that matches the duration of the file.
An example playlist with an ad break could look like:
1. Song 1
2. Jingle
3. RSAD30000.m4a (silence)
4. Jingle
5. Song 2
Remember that during an ad break, multiple shorter ads may be inserted as directed by response of the midroll webhook.
These silent audio files can be scheduled in your radio automation software to trigger midroll ad breaks of a given duration:
Ad insertion is designed to be high performance and work at scale. Ads are cached on disk but stored in-memory during ad insertion. The performance profile of inserting ads is designed to be similar to that of serving live audio, in order to avoid spikes in CPU usage at high listener levels.