Skip to content

Advertisement Insertion

On this page:

  1. Description
  2. Aspects of ad insertion in Flussonic
  3. Flussonic ad insertion mechanisms
  4. When to insert mid-roll videos
  5. How to configure advertisement insertion with auth backend
    1. HTTP auth backend examples


Flussonic allows you to embed ads (commercials) in play sessions and configure the display of the ads through the authorization backend.

You can do the following:

  1. Specify pre-roll and mid-roll videos.

  2. Choose when to insert mid-roll videos: via regular intervals or according to SCTE-35 markers.

  3. Set an interval for inserting mid-roll videos.

  4. Specify ads that are unique for each user/view.

Aspects of ad insertion in Flussonic

It is necessary to preprocess the ad clips before using them in ad insertion in Flussonic. Here are a few aspects and requirements to consider:

  • Main stream and advertisement stream characteristics (media_info) must be identical. Otherwise, Flussonic ignores the ad stream and will not perform the ad insertion.

  • An advertising video must have a GOP size equal to one second.

  • HLS players usually skip the first 1-5 seconds of the pre-roll video (it is the feature of HLS players). However, adding black frames in the beginning of the video solves the issue.

  • Plugins such as AdBlock block the commercials. If something goes wrong, try disabling the plugins.

Flussonic ad insertion mechanisms

There are two ad insertion mechanisms in Flussonic:

The first mechanism of ad insertion is an extension of the authorization system, so please read the documentation on it first. It works with HLS and DASH protocols. So to play the stream with embedded advertising clips, you should access it over HLS or DASH. Otherwise, it will not work. Plugins such as AdBlock can block the advertisement.

The second mechanism is the upgraded version of the first one and is used by default. It complicates the work of ad blockers. It replaces the stream segments within the play session so that it is impossible to distinguish whether it is a main stream segment or an ad segment. It also allows you to customize the advertisements for a particular user. Besides, it works with a single-period as well as a multi-period DASH.

Here is an example of the URL for an HLS main stream segment compared to the URL of an ad segment:

HLS main stream segment URL http://FLUSSONIC-IP/STREAM_NAME/tracks-v1a1/2021/09/28/09/27/25-05000.ts?token=adv2user-12312324342
Ad segment URL http://FLUSSONIC-IP/STREAM_NAME/tracks-v1a1/2021/09/28/09/27/30-05000.ts?token=adv2user-12312324342

You can enable the first or the second mechanism adding the v=1 or v=2 parameter correspondingly in the ad_inject section of the auth backend response. (See the API schema and the PHP examples).

Both mechanisms require the above-mentioned requirements to be met.


You must use files with advertisement videos that are located in configured VOD locations on the Flussonic server. Don't specify a path to the local file system or an HTTP source. It is critical to create a VOD location and place the files there.

When to insert mid-roll videos

You can insert mid-roll advertising videos in two ways that are defined by the midroll_insert_by parameter in the auth script:

  • midroll_insert_by=interval. The videos are inserted via the regular interval. In this case you should specify midroll_interval parameter in the auth script. This mode is used by default.
  • midroll_insert_by=splicing. The videos are inserted according to the SCTE-35 markers, if they are present in the original stream. Read how to get SCTE-35 markers from the input stream.

How to configure advertisement insertion with auth backend

To configure advertisement insertion with auth backend:

1) Choose the programming language option that suits you best: PHP or another one that you like.

2) Configure a VOD location and place the ad videos there.


Make sure your advert videos meet the requirements.

vod ad_vod {
  storage /storage;

3) Add the location of the clips to your script and specify when should mid-roll videos be inserted. Your auth backend should response with the JSON structure described in the API schema. See the PHP examples.

4) Configure the stream adding the on_play directive with a path to the script to the configuration file:

stream example_stream {
  input file://vod/bunny.mp4;
  on_play http://IP-ADDRESS:PORT/php-auth-script2.php;

5) Ensure that it works by playing the stream over HLS/DASH.

HTTP auth backend examples

Here are the examples of PHP auth scripts for ad insertion. The second mechanism with v=2 parameter is used (the configuration for the first mechanism will be the same, but with v=1).

Ad insertion via regular intervals:


header('Content-type: application/json');

$user_ads = [
    "v" => 2,
    "preroll" => "ad_vod/preroll1.mp4",
    "midroll_interval" => 180,
    "midroll" => ["ad_vod/midroll1.mp4", "ad_vod/midroll2.mp4"]

echo json_encode(array("ad_inject" => $user_ads));

Flussonic Media Server will show the file ad_vod/preroll1.mp4 as pre-roll and then show all the specified mid-roll files every three minutes (180 seconds) in random order.

Ad insertion via SCTE-35 markers:


header('Content-type: application/json');

$user_ads = [
    "v" => 2,
    "preroll" => "ad_vod/preroll1.mp4",
    "midroll_insert_by" => "splicing",
    "midroll" => ["ad_vod/midroll1.mp4", "ad_vod/midroll2.mp4"]

echo json_encode(array("ad_inject" => $user_ads));

Flussonic Media Server will show the file ad_vod/preroll1.mp4 as pre-roll. Then when the SCTE-35 markers appear, Flussonic will show all the specified mid-roll files in random order until the end splice point of an ad break.