Live API: Cue Points and Ad Beacons with SSAI

Overview

Server-side ad insertion (SSAI) allows you display ads during a live streaming event at specified times. For general information, see the Live API: Server-Side Ad Insertion (SSAI) document.

Cue points

Ad breaks are triggered by cue points, which can be specified in two ways:

• Sent to Brightcove by the encoder
• Immediate cue points created via the Live API

From the encoder

The Brightcove live delivery system can interpret cue points submitted by the encoder in the AMF format:

      AMFDataList
        [0]:onCuePoint
        [1]:{Obj[]:
        time: 1.9889, //Difference from PTS of THIS packet to the first PTS of the 1st video frame in the adbreak
        name: "scte35",
        type: "event",
        ad_server_data: "eyJrZXkiOiJ2YWx1ZSJ9", // optional introduced by Brightcove. It is a base64 encoded json map of
        parameters e.g. {"key":"value"}
        parameters: {Obj[]:
        type: "avail_in",
        duration: 12.0
        }
        }
    

Notes:

• Since timecodes are expressed in HH:MM:SS, there is no notion of what day is meant. This can lead to problems such as sending cue point at 23:55:00 for an ad break to start at 00:01:00 and having the server interpret that as almost 24 hours ago. Brightcove has implemented a fix for this as follows: for cue points arriving between 23:50:00 and 00:00:00 only, we will assume you are scheduling an ad break for the following day.
• Up to 128 cue points can be stacked in a single request, but given the rules around "rollover" explained above, cue points cannot be sent in this manner for the following day.
• Since SMPTE timecodes are associated with the stream, it is possible that a cue could arrive after the scheduled time in the stream. Brightcove will allow up to a 5 seconds tolerance after the cue to still insert a Cue point.
• Only avail_in and avail_out type cue points are currently supported in RTMP input.
• SCTE-35 cue points are supported in RTP and SRT inputs.

Manual cue point insertion

You can create immediate cue points for a job or a redundant group using the Live API by sending a POST request:

Include a request body specifying the following:

Duration example

The duration of the cue point being inserted needs to be at least twice the length of the segments in the job.

For example, inserting a 10 second cue point in a job with "segment_seconds"=4, will work fine. However, inserting the same cue point in a job with "segment_seconds"=6 will result in the following error:

      "error": "The parameter duration should be greater than
        or equal to (2 * target duration) of the job"
      
    

Sample request body

      {
        "duration": 30,
        "timecode": "15:50:49:16",
        "ad_server_data" : {
        "adbreakid": 12312
        "breaktheme": "fitness"
        }
        }
    

Notes

1. Software encoders such as Wirecast and OBS do not support the sending timecode via OnFI packets in the RTMP stream
2. Elemental hardware encoders do support the sending timecode via OnFI packets in the RTMP stream

Sample response

      {
        "id": "Job_ID",
        "cue_point": {
        "id": "adBreak-2f58393ada1442d98eca0817fa565ba4",
        "duration": 30,
        "accuracy": "segment", [Can be segment or frame ]
        "inserted_at": "2017-07-21T09:30:46.307Z" [ Time when the cue point was inserted in the stream]
        },
        }
    

Beacons

Beacons are data points on playback sent to third-party analytics to track whether and how much of ads were played. In this section we will look at the beacon types that can be set using the Live API, and variables that can be used to provide the data. The next section will detail the API requests use to create and manage beacon sets.

Beacon types

Beacon/Ad variables

The table below shows the variables you can use to provide data for the beacon URLs. To include a variable, surround with double curly braces, like this: {{job.job_id}}. See the next section on managing beacon sets for full examples.

SCTE-35 ad variables

The Society of Cable Telecommunications Engineers (SCTE) defines a standard for dynamic ad insertion for live streams. An SCTE-35 ad marker defines the timestamp and duration where an ad can be inserted into the stream.

If parsed from SCTE-35, the following configuration variables can be applied to your ad tags:

As part of the HLS manifests, the SCTE-35 messages are also base64 with the variables in JSON. For example:

      {"scte35_eventID": somevalue, "scte35_programID":
        somevalue}
    

Managing beacon sets

This section provides details on the API requests to manage beacon sets. See the previous section for beacon types and variables.

To add a beacon set to a Live job, first create the beacon set, and then include the id when you create the job, like this:

      {
        "live_stream": true,
        "region": "us-west-2",
        "reconnect_time": 30,
        "ad_insertion": true,
        "beacon_set": "beacon_set_id", ...
    

Create a beacon set

To create a beacon set, send a POST request:

Sample request body

      {
        "account_id": "User's Account ID [Optional]",
        "beacon_urls": [
        {
        "beacon_url":
        "https://myserver.com/beaconRX/{{job.job_id}}/load?position=load&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
        "beacon_type": "Load"
        },
        {
        "beacon_url":
        "https://myserver.com/beaconRX/{{job.job_id}}/play?position=play&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
        "beacon_type": "Play"
        }
        ]
        }
    

Sample response

      {
        "beacon_set": {
        "beacon_urls": [{
        "beacon_url":
        "https://myserver.com/beaconRX/{{job.job_id}}/load?position=load&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
        "beacon_type": "Load"
        },
        {
        "beacon_url":
        "https://myserver.com/beaconRX/{{job.job_id}}/play?position=play&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
        "beacon_type": "Play"
        }],
        "beacon_set_id": "Inserted Beacon Set ID",
        "account_id": "USER's ACCOUNT ID"
        }
        "inserted": true
        }
    

Update a beacon set

Updating a beacon set is similar to creating one. Submit a PUT request:

Sample request body

      {
        "account_id": "User's Account ID [Optional]",
        "beacon_urls": [
        {
        "beacon_url": "https://myserver.com/beaconRX/load",
        "beacon_type": "Load"
        },
        {
        "beacon_url": "https://myserver.com/beaconRX/play",
        "beacon_type": "Play"
        }
        ]
        }
    

Sample response

      {
        "beacon_set": {
        "account_id": "User's Account ID",
        "beacon_set_id": "Beacon set ID",
        "beacon_urls": [{
        "beacon_url": "https://myserver.com/beaconRX/load",
        "beacon_type": "Load"
        },
        {
        "beacon_url": "https://myserver.com/beaconRX/play",
        "beacon_type": "Play"
        }],
        "updated_beacon_set": {
        "beacon_set_id": "Beacon set ID",
        "beacon_urls": [{
        "beacon_url": "https://myserver.com/beaconRX/load",
        "beacon_type": "Load"
        },
        {
        "beacon_url": "https://myserver.com/beaconRX/play",
        "beacon_type": "Play"
        }],
        "account_id": "User's Account ID"
        }
        }
        }
    

Get beacon sets

To retrieve the beacon sets for an account, submit a GET request:

Sample response

      [{
        "account_id": "User's Account ID",
        "beacon_set_id": "Beacon set ID1",
        "beacon_urls": [{
        "beacon_url": "https://myserver.com/beaconRX/load",
        "beacon_type": "Load"
        }]
        },
        {
        "account_id": "User's Account ID",
        "beacon_set_id": "Beacon set ID2",
        "beacon_urls": [{
        "beacon_url": "https://myserver.com/beaconRX2/load",
        "beacon_type": "Load"
        },
        {
        "beacon_url": "https://myserver.com/beaconRX2/play",
        "beacon_type": "Play"
        }]
        }]
    

Get beacon sets for requesting user

You can also get the beacon sets for the account of the requesting user without including the account id in the request URL:

Sample response

      [{
        "account_id": "User's Account ID",
        "beacon_set_id": "Beacon set ID1",
        "beacon_urls": [{
        "beacon_url": "https://myserver.com/beaconRX/load",
        "beacon_type": "Load"
        }]
        },
        {
        "account_id": "User's Account ID",
        "beacon_set_id": "Beacon set ID2",
        "beacon_urls": [{
        "beacon_url": "https://myserver.com/beaconRX2/load",
        "beacon_type": "Load"
        },
        {
        "beacon_url": "https://myserver.com/beaconRX2/play",
        "beacon_type": "Play"
        }]
        }]
    

Get a beacon set by id

To retrieve a single beacon set by its id, submit a GET request:

Sample response

      {
        "account_id": "User account ID",
        "beacon_set_id": "Beacon set ID",
        "beacon_urls": [{
        "beacon_type": "Load",
        "beacon_url": "https://myserver.com/beaconRX2/load"
        },
        {
        "beacon_type": "Play",
        "beacon_url": "https://myserver.com/beaconRX2/play"
        }]
        }
    

Delete a beacon set

Finally, to delete a beacon set, send a DELETE request:

Sample response

The response will look like this:

      {
        "beacon_set_id": "Beacon set ID",
        "deleted": true
        }
    

Appendix

Below is a screenshot to show a sample cue point setup for the Elemental encoder.