Configuring ad insertion¶

With Flussonic, you can configure Server-Side Ad Insertion (SSAI) using authorization backend. There are two SSAI modes: by a schedule and by SCTE markers. To learn more about those modes, see Modes of Server-Side Ad Insertion.

Step 1. Settings in Flussonic config file¶

Add the following config to /etc/flussonic/flussonic.conf:

vod ad_vod {
  storage /opt/flussonic/priv;
}
stream example_stream {
  input fake://fake;
  on_play http://localhost/ad_backend.json;
}
file_processor { 
    path /opt/flussonic/priv; 
}

Reload the config file after editing so that the changes were applied:

service flussonic reload

This configuration includes the following features:

• vod directive sets the VOD location. The example uses /opt/flussonic/priv, and this directory already has bunny.mp4 file that we will use further on the page. When you will add the real ad clips, add them to your own VOD location.

  Danger

  Store the ad clips in the VOD locations on the Flussonic server. Don't specify a path to the local file system or an HTTP source.

• on_play directive sets the authorization backend. We will run it in step 3.

• file_processor directive sets the directory for file_processor to store the prepared files (see next step).

Step 2. Preparing the ad clips¶

Before inserting the ads into the stream, you should preprocess them. It can be done in any video editor or with Flussonic file_processor API.

In a video editor¶

Prepare ad clips in a third party video editor according to the following requirements:

• Main stream and advertisement stream parameters (media_info) must match. Otherwise, Flussonic ignores the ad stream and doesn't insert it into the main stream.
• An advertising video must have a GOP size equal to one second.
• HLS players usually skip the first 1-5 seconds of the preroll. It is the feature of HLS players. To fix the issue, add some black frames to the beginning of the video.

With Flussonic file_processor API¶

First of all, you need to get media_info of the stream you are going to inject the ads to. Use GET /{name}/info.json:

curl http://user:password@localhost/streamer/api/v3/streams/example_stream | jq .stats.media_info >> fp.json

The result will be saved in fp.json file. Open it with any text editor and add the following lines:

{
  "input_files": ["/opt/flussonic/priv/bunny.mp4"],
  "output_file": "bunny_fp",
  "filters": [{
    "group": "transcoder",
    "transcoder":

---
your media_info
---

  }]
}

Now you can use fp.json for passing it to POST /file_processor/jobs:

curl -X POST http://user:password@localhost/streamer/api/v3/file_processor/jobs --data @fp.json --header "Content-Type: application/json"

In the last command output, find the value of the output_file parameter. It looks like bunny_fp.processed.1711966939428660.mp4. This is the name of the prepared ad clip that you need to indicate in the authorization backend. The file is already put in the VOD location that you specified for file_processor in the configuration file.

Step 3. Authorization backend for SSAI¶

To use SSAI, implement an auth backend. Your auth backend should response with the JSON structure described in the API schema.

Below you will find two examples of JSON for two modes of SSAI. Since the example_stream stream that we used in the config on step 1 does not have SCTE markers, use the script for SSAI via regular intervals.

Save JSON to the file in /opt/flussonic/wwwroot/ directory, for example name it ad_backend.json.

SSAI via regular intervals¶

{
    "ad_inject": {
        "v": 2,
        "preroll": "ad_vod/bunny_fp.processed.1711966939428660.mp4",
        "midroll_interval": 180,
        "midroll": ["ad_vod/bunny_fp.processed.1711966939428660.mp4", "ad_vod/bunny_fp.processed.1711966939428660.mp4"]
    }
}

The following parameters are used:

• "v" => 2 for inserting ads as segments of the main stream
• "preroll" => "ad_vod/bunny_fp.processed.1711966939428660.mp4" is the path to the preroll. Replace the file name with the one returned by preparation script on step 2.
• "midroll_insert_by" => "interval" is the ad insertion method with regular intervals
• "midroll_interval" => 180 is the interval in seconds to play midrolls
• "midroll" => ["ad_vod/bunny_fp.processed.1711966939428660.mp4", "ad_vod/bunny_fp.processed.1711966939428660.mp4"] is the midrolls list. Replace the file names with the ones returned by preparation script on step 2.

Flussonic Media Server uses ad_vod/bunny_fp.processed.1711966939428660.mp4 as preroll and then plays all the specified midroll files every three minutes (180 seconds) in the order they appear in the midroll list.

SSAI via SCTE-35 markers¶

{
    "ad_inject": 
    {
        "v": 1,
        "preroll": "ad_vod/bunny_fp.processed.1711966939428660.mp4",
        "midroll_insert_by": "splicing",
        "midroll": ["ad_vod/bunny_fp.processed.1711966939428660.mp4", "ad_vod/bunny_fp.processed.1711966939428660.mp4"]
    }
}

The following parameters are used:

• "v" => 1 for inserting the ads as separate segments.
• "preroll" => "ad_vod/bunny_fp.processed.1711966939428660.mp4" is the path to the preroll. Replace the file name with the one returned by preparation script on step 2.
• "midroll_insert_by" => "splicing" is the ad insertion method via SCTE markers
• "midroll" => ["ad_vod/bunny_fp.processed.1711966939428660.mp4", "ad_vod/bunny_fp.processed.1711966939428660.mp4"] is the midrolls list. Replace the file names with the ones returned by preparation script on step 2.

Flussonic Media Server uses the file ad_vod/bunny_fp.processed.1711966939428660.mp4 as pre-roll. When the SCTE-35 markers appear, Flussonic plays all the specified midroll files until the end splice point of an ad break. The files are played looped in the order they appear in the midroll list.

Step 4. Testing the ad injection¶

Ensure that it works by playing the stream over HLS or DASH. For example, use the Embed link on the Output tab of the stream.

https://FLUSSONIC-IP/example_stream/embed.html

If everything is fine, you will see the Big Buck Bunny clip before the example_stream stream.

Tracking events of showing ads to viewers¶

Collect statistics on showing ads by configuring logging of the ad_inject event with the help of event_sink.