Skip to content

Configuring ad insertion

With Flussonic, you can configure SSAI using authorization backend.

To learn how SSAI works, see Modes of Server-Side Ad Insertion.

Note

Streams with ads inserted via SSAI can be played over HLS and DASH protocols only.

  1. Preparing the ad clips
  2. Configuring the ad insertion method
  3. Configuring SSAI via authorization backend
  4. Tracking events of showing ads to viewers
  5. HTTP auth backend examples

Preparing the ad clips

Before inserting the ads into the stream, preprocess the ad clips 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.
  • Plugins such as AdBlock block the ads. If something goes wrong, try disabling the plugins.

Configuring the ad insertion method

You can insert midrolls according to one of the following methods: time intervals or SCTE markers. The method is defined by the midroll_insert_by parameter in the auth script:

  • midroll_insert_by=interval. The ads are inserted at the regular interval. Also add midroll_interval parameter in the auth script, and specify the time interval in seconds. It's the default mode.
  • 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.

Configuring SSAI via authorization backend

To configure SSAI with auth backend, follow these steps:

1) Preprocess the ad clips according to the requirements.

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

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.

vod ad_vod {
  storage /storage;
}

3) Define a list of clips for Flussonic to insert into each viewer's play session. To do this, extend the functionality of the web service responsible for viewer authorization by writing a script and adding the following parameters:

  • Path to the ad clips: VOD_LOCATION/FILENAME.mp4
  • Ad insertion mode:

    • v=1: the ads are inserted into the main stream as separate segments.
    • v=2: the ads are injected into segments of the main stream. It works with HLS, mono and multi-period DASH. Used by default.
  • Ad insertion method:

    • intervals: midroll_insert_by=interval:
    • midroll_interval=180 is the interval for playing midrolls
    • SCTE markers: midroll_insert_by=splicing

Your auth backend should response with the JSON structure described in the API schema. For an example script, see HTTP auth backend examples.

4) Configure the stream by adding the on_play directive to the configuration file and specifying the path to the script:

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 or DASH.

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.

HTTP auth backend examples

Here are the examples of PHP auth scripts for SSAI.

SSAI via regular intervals:

<?php

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));
?>

where

  • "v" => 2 for inserting ads as segments of the main stream
  • "preroll" => "ad_vod/preroll1.mp4" is the path to the preroll
  • "midroll_insert_by" => "interval" is the ad insertion method with regular intervals
  • "midroll_interval" => 180 is the interval to play midrolls
  • "midroll" => ["ad_vod/midroll1.mp4", "ad_vod/midroll2.mp4"] is the midrolls list

Flussonic Media Server uses ad_vod/preroll1.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:

<?php

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

$user_ads = [
    "v" => 1,
    "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));
?>

where

  • "v" => 1 for inserting the ads as separate segments.
  • "preroll" => "ad_vod/preroll1.mp4" is the path to the preroll
  • "midroll_insert_by" => "splicing" is the ad insertion method via SCTE markers
  • "midroll" => ["ad_vod/midroll1.mp4", "ad_vod/midroll2.mp4"] is the midrolls list

Flussonic Media Server uses the file ad_vod/preroll1.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.