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.
Note
Streams with ads inserted via SSAI can be played over HLS and DASH protocols only.
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 hasbunny.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
Note
Replace user and password in curl
commands with the username and password you use to log into the UI.
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.
Warning
Preparation may take some time. First, a file with a .tmp extension will be created on disk. Do not remove or move it. Wait until file_processor finishes and the resulting file appears.
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
.
Note
These JSONs do not perform actual authorization, because they do not check any tokens. They can only be tried on for testing ad insertion. To actually authorize playback sessions, follow the instructions on the Authorization page.
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.
Note
Plugins such as AdBlock block the ads. If something goes wrong, try disabling the plugins.
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.