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:

2. Prerequisites

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

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:

• Inserting ads by Nimble Advertizer using SCTE-35 markers article shows how you can use SCTE-35 insertion in your streaming scenarios.
• SCTE-35 markers forwarding and passthrough article shows how you can pass through SCTE-35 markers via Nimble Streamer and Live Transcoder.
• Trigger SCTE-35 marker insertion by Nimble API article described how you can inject SCTE-35 Out and SCTE-35 In markers into live stream via Nimble API to initiate immediate ads insertion.
• SCTE-35 markers can be recorded to DVR and transmitted via HLS.
• PlayDeck made a tutorial for how to generate SCTE-35 markers from their product and use them with Nimble Streamer HLS output.

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.