Efficient tools to build your streaming infrastructure


Nimble Advertizer Specifications

Nimble Advertizer is a server-side advertisement insertion (SSAI) framework that allows personalized advertisements to be dynamically inserted into live streaming and video-on-demand (VOD) content. It is based on the Nimble Streamer media server and supports HLS, RTMP, SLDP, and Icecast live outputs, as well as MPEG-TS and fMP4 VOD HLS. The technology operates by processing incoming streams and obtaining ads information from a handler web application or JSON file. The ads are then inserted into the original media and packaged into the outgoing stream, which the end-user can access and watch.

Take a look at Nimble Advertizer live demo to see it in action.

The full technical specifications provide a detailed description of the features and capabilities of Nimble Advertizer, including flexible timing control, personalization options, and insertion logging.

1. Basic workflow

Ads insertion technology workflow works as follows:

  • For live streaming, Nimble Streamer media server processes incoming streams to get content. See section 2 for prerequisites.
  • For video-on-demand, a viewer requests an HLS stream from Nimble Streamer. See section 2 for prerequisites.
  • Nimble Advertizer requests your handler web application or JSON config file (see section 4), handler location is defined in Nimble Streamer config file (see section 3).
  • Nimble Advertizer gets response from handler with ads scenarios (see section 5).
  • Advertizer gets files with advertisements to process them via Nimble Streamer according to ads scenarios logic defined by handler response.
  • Nimble inserts the ads into original media and packages it into outgoing stream.
  • End user connects to Nimble and gets media stream containing original content mixed with advertisements.
  • Session-specific ads insertion can be applicable, see description below.
  • For live streaming,HLS,RTMP,SLDP andIcecast are supported as output protocols while all protocols supported by Nimble Streamer can be used as input.
  • For VOD,HLS with MPEG-TS and fMP4 containers is supported.

2. Prerequisites

Before following the description below please make sure you comply with the following prerequisites:

  1. You have WMSPanel account which has active subscription. Trial accounts have no access to this feature.
  2. Your WMSPanel login has admin privileges.
  3. You have Nimble Streamerinstalled and running.
  4. You subscribed for Nimble Streamer Addenda package, got active license and registered it (see instruction below in this section).
  5. Advertising video files are packaged into MP4 container. You may use ffmpeg to re-package files into MP4.
  6. Advertising audio files are packaged into MP4 container.
  7. If you have audio-only streaming, you can also use AAC or MP3 containers for audio ads files.
  8. Advertising video is encoded to H.264.
  9. Advertising audio has the same codec and sample rate as your input stream. E.g. if your stream is AAC 44.1KHz, your ads will be packaged into MP4 file with AAC audio with 44.1KHz sample rate.
  10. Advertising files must either be available via local path or be accessible for download from Nimble instance via HTTP/HTTPS URL.
  11. For live streaming, input streams are set up and their content is available.
  12. For VOD, content files are available and VOD processing routes are properly set and tested.
  13. For SLDP output: the output stream is set up and is publicly available. Use proper instruction from SLDP page to perform the setup.
  14. For RTMP output: the output stream is set up and is publicly available. Use proper instruction from RTMP page to perform the setup.
  15. For HLS output: the output stream is set up and is publicly available. Use proper instruction for your input protocols to set up HLS output.
    Notice that Nimble Streamer application setting must have "HLS" output enabled; "HLS MPEGTS" or "HLS fMP4" are not yet supported.
  16. For Icecast ads: input stream has either AAC or MP3 encoded audio. The output will have the same codec.
  17. The Icecast output stream is set up and is publicly available. Use proper instruction fromaudio streaming page to perform the setup.

To obtain and register the Nimble Streamer Addenda license follow these steps:

  1. Go to Settings menu and open Addenda licenses tab
  2. Click on Add Addenda license and select number of licenses, then click Next and once you see final cost, click on Pay now button.
  3. Follow the payment procedure and once you complete it, you’ll see your active licenses.
  4. Click on the license to see the registration procedure.
  5. Log into the server which has Nimble Streamer installed and which you will use as your Nimble Advertizer host. Then use the registration procedure to make it work.

That’s it, you may now proceed with your Advertizer setup.


3. Config file setup

Nimble Advertizer behavior on server side is defined via Nimble Streamer configuration file. Its general parameters and usage are described on this page. The following settings must be used for serve setup.

advertising_url
advertising_url=http://server_addr/handler_app
or
advertising_url=https://server_addr/handler_app
or
advertising_url=file://path/to/file/handler.json
Defines either the URL of handler app (it can use HTTP as well as HTTPS) or the location of local file containing configuration.
Example: advertising_url=http://testradiowebsite.com/ads_handler.php

advertising_sync_interval
advertising_sync_interval=seconds
Defines how frequent Nimble Advertizer will request the main handler for updates of ads scenarios. It’s 60 seconds by default.
Example: advertising_sync_interval=3

max_advertising_download_sessions
max_advertising_download_sessions=number
Defines how many concurrent sessions Nimble Advertizer will use for downloading the files which contain ads. It’s 10 sessions by default. If handler specifies more files that defined in this parameter, the extra files will be queued and downloaded in their turn.
Example: max_advertising_download_sessions=20

advertising_session_rules_request_interval
advertising_session_rules_request_interval=seconds
Defines how frequent Nimble Advertizer will request the session handler for updates of ads scenarios. It’s 30 seconds by default.
Example: advertising_session_rules_request_interval=20

Once you define settings in config file, please restart Nimble Streamer. For Linux it’s done by "sudo service nimble restart" command.

Read this page to find more details regarding Nimble config.


4. Handler application and static configuration

Nimble Advertizer business logic for ads insertion is defined by a configuration file or handler app.

Handler is a REST controller which is called by Nimble Advertizer and responds with ads scenarios. It’s called periodically as defined in Nimble config file, see section 3 for details. Handler app must be available via HTTP/HTTPS protocol and accessible from Nimble instance.
You may use any language and framework to create a handler application. Handler response must be a valid JSON text, its grammar is described below.

Besides creating handler application you may create a JSON config text file containing all setup. It neds to be either available via local path or be accessible via HTTP. See section 6 to find a link to our github with JSON sample files.


5. Handler response grammar

Handler application returns a JSON text as a response to server sync-up call. This response describes advertising scenarios for Nimble Advertizer to follow.
Here is a formatted example of response which shows its structure and elements.

{
  "session_handler":
  {
    "apps": ["ppv"],
    "url":"http://192.168.232.120/session-handler"
  },
  "contents":
  [
    {"id":"11","uri":"http://192.168.232.129/SampleAudio_0.4mb_5s.aac.mp4"},
    {"id":"22","uri":"https://192.168.232.129/testt.mp4"},
    {"id":"33","uri":"file://home/user/ads/SampleAudio_0.4mb_5s.mp3.mp4"}
  ],
  "rules":
  [
    {
    "id":"1",
    "protocols":["icecast", "sldp", "rtmp", "hls"],
    "users":[],
    "type":"global",
    "time_sync":"stream",
    "time_offset":0,
    "time_interval":600,
    "contents":[{"id":"11","onerror":"stop","wait":"10"}, {"id":"22","onerror":"skip","wait":"2"}]
    }
  ]
}


Response has 3 general elements: session_handler , contents and rules.


The session_handler element is needed only if you'd like to do per-session ads insertion or statistics' collection.
Advertizer per-session ads insertion and stats article to learn more about it.


The contents element describes the ads files to be used in advertising rules. It’s an array of ads, each having id for ad’s ID and uri for ad location URI.


The ID is a unique identifier of an ad. Once new ID appears in handler response, it’s downloaded and put into Nimble cache for further insertion into streams. If you’d like to update the ad over time, you need to update your ad file and add it to your response with new ID. In this case the old file will be removed from cache and the new one will be uploaded. Removing ID from response means this ad will be played for all clients where it started to play already and then it will be removed from cache.


The URI is either a local file (via "file://" scheme) or any valid web location available via HTTP or HTTPS (via "http://" or "https://" schemes respectively).


The rules element describes the ads insertion logic. Each rule describes applicability of certain ads for certain set of streams or users. If several rules can be applied to the same stream, then all those rules will be applied one by one. The application order is defined by the time of ad appearance defined in each rule. If several ads apply for the same time, then they will be queued and played one after another.


Each rule has its id element to define its ID. If new ID appears in rules, this rules starts working. If it’s removed then the rule is removed too and it stops working. If you change the rule without changing the ID, this rule’s change will not be applied. So if you’d like to modify the rule - just assign new ID to it.


The protocols element describes which protocols this rule will apply to. Currently icecast, sldp, rtmp and hls values are supported.


The users element is populated in case you want to insert personalized ads. It’s a list of IDs of users to apply this rule for. It’s defined by pay-per-view framework available with Nimble. If you don’t want to personalize ads, just keep this list empty in all rules.


The type element defines what type of entity this rule is applied. Possible values are global, app and stream.

  • global type means this rule is applied to all streams on current server.
  • app type means this rule will be applied to a certain streaming application. In this case you also need to add app element with application name. E.g. if you have streams like live/stream1, live/stream2 etc. then you can add these elements: "type":"app","app":"live"
  • stream type means the rule will be applied to exact stream. It needs app and stream elements added to describe the stream. E.g. if you want to apply a rule to live/radio1 stream, then you’ll need to use these elements: "type":"stream","app":"live","stream":"radio1".
    It may also be applied to a number of streams using array: "type":"stream","app":"live","stream": ["stream1", "stream2", "etc"]

The time_sync element defines the reference point for this rule to define time for ads insertion. It defines time_offset element usage.
If you use "time_sync":"gmt" value then your ad insertion will be defined by exact time point. "time_offset" will define time of insertion in "%Y-%m-%d %T" format, e.g. 2018-01-01 10:00:00. In case of VOD, this time will be calculated based on content length.
If you use "time_sync":"stream" value then you will define start time for your ads relatively to the time when a user is connected to the stream. In case of stream value, start time is defined in seconds. In this case "time_offset" will set when to start the ad after a user is connected. If it’s "time_offset":"0" then it’s inserted right after the user has connected.
If you use "time_sync":"scte35" value then start and end time for your ads will be completely defined by SCTE-35 markers that are delivered within incoming stream. "time_offset" and "time_interval" parameters are not used in this case. Read section "7. Working with SCTE-35" below to see how you can enable this capability.


The time_interval element defined the time period for next ads insertions. It’s defined in seconds. E.g. if it’s "3600" this means it will be played every hour. If it’s "0" then it will not be repeated.


The combination of these 3 elements allows defining different timing scenarios.
If you need to define the pre-roll ad, you will use "time_sync":"stream","time_offset":"0","time_interval":"0"
If you need to start ads 5 minutes before the end of each hour, you will use "time_sync":"gmt","time_offset":"2018-01-01 00:55:00","time_interval":"3600".


If you want to break the ad insertion when "SCTE-35 In" marker is received, use this parameter:
"break_on_splice_in": true
for the respective rule. Check Section 7 below to find out more about handling SCTE-35.


The contents element defines a list of elements, each describing one ad to insert at the time point defined by previous elements.
Each element has id which is the ID of an ad described in starting contents element of handler response.
The onerror element defined what to do if the ad is not yet in Nimble Streamer cache. Possible values are stop or skip. stop means Advertizer will stop the original stream for this user and skip means Advertizer will continue playing original stream without an ad. The wait element defines time in seconds which Nimble Advertizer will wait until the ad in downloaded.
So "id":"11","onerror":"stop","wait":"10" means Nimble will wait for 10 seconds trying to download the "11" ad and will stop the streaming if it fails to download during that time.
And "id":"22","onerror":"skip","wait":"2" means Nimble will wait for 2 seconds while it downloads "22" ad and if it doesn’t get the ad, then the playback will resume.
If several ads IDs are listed in the "contents" element, then those ads will be played one by one once the ad insertion is triggered.


This is basic grammar covering major use cases. Let’s see some examples of responses for typical situations.


6. Some examples

You can find handler and responses examples in respective Advertizer repository on github.


7. Working with SCTE-35

To enable the processing of SCTE-35 markers on Nimble Streamer instance, you need to add the following parameter into Nimble Streamer config file:
scte35_processing_enabled = true
You'll need to re-start Nimble Streamer instance and input stream to make the changes work.Read this page to learn more about making changes to Nimble Streamer config.


The following articles will give all information about SCTE-35 markers usage in Nimble Streamer:

Also take a look at break_on_splice_in parameter usage above.



8. Ads logging and stats

You can track your ads performance using either ads logging or session handler.


Ads logging
To enable ads logs, go to nimble.conf and add log_advertisements=true line. Once you restart Nimble Streamer, you will get ads logs saved to advertisements.log file. Each line in the log represents a single ad insertion. Visit config description page to learn more about making changes to Nimble Streamer config.


All lines in the log file will have the following format:
"result_stream" "ad_id" "ad_rule_id" "ad_url" client_ip "ppv_user_id" "user-agent"

  • result_stream is the output stream which has the ad, it’s formatted as “/application_name/stream_name/”
  • ad_id is the ID of the ad from “content” element of JSON which is being inserted
  • ad_rule_id is the ID of the rule which was applied to make insertion
  • ad_url is full URL of the ad being inserted
  • client_ip is the IP address of the viewer
  • ppv_user_id is the user ID being used for per-user ads insertion
  • user-agent is the User-Agent of a viewer

Session handler
Per-session handler allows getting detailed per-session statistics in your own handler.
Advertizer per-session ads insertion and stats article describes this approach in more details.

9. Demonstration

Watch live demo

Demo page shows live streams with ads insertion, with full details on Advertizer setup.

We've made a quick video showing the setup process for a simple use case: adding a pre-roll ad into a live stream.


If you have any questions on Nimble Advertizer usage, please contact us viacompany helpdesk.