Insert a New Splice Insert Message - AWS Elemental Live

This is version 2.18 of the AWS Elemental Live documentation. This is the latest version. For prior versions, see the Previous Versions section of AWS Elemental Live and AWS Elemental Statmux Documentation.

Insert a New Splice Insert Message

Inserts a SCTE-35 message of type splice_insert in the stream either immediately or at a specified time. The command always includes a start time. It may also include or omit a duration (which implies an end time).

The command does not support inclusion of a segmentation descriptor, which means that the message is always considered to be an “ad avail.”

HTTP URL

POST <IP address of Live node>/live_events/<ID of event>/cue_point

Body of HTTP

The XML body contains one cue_point elements containing the following tags:

Tag Sub-tag Type Value
event_id integer

Specify an ID for this SCTE-35 request to allow for canceling of the insertion later (Cancel a Pending Ad Avail).

Or leave blank, in which case an ID is generated and returned in the response.

splice_time

Include this in order to specify the insertion point relative to the stream timecode. Include either splice_time or splice_offset, not both.

See Specifying Time with splice_time Tag for details.

Specify the time by including the hours, minutes, seconds, and frames tags.

hours integer

The start time of the ad avail. All fields are required.

Enter the time in 24-hour format.

To insert the ad avail immediately (taking into account that there is a small delay while the request is processed), enter 0 in all fields.

minutes integer
seconds integer
frames integer

The frame within the specified seconds at which to insert the ad avail.

If blank, the start time is the first frame in the specified second.

splice_offset integer

The start time of the ad avail. Include either splice_time or splice_offset, not both.

Include in order to specify the start time for the ad avail as the specified milliseconds after the request is received. See Specifying Time with splice_offset Tag.

Specify the milliseconds. The number cannot be negative.

duration integer

Optional. See Duration.

Enter the duration of the ad avail in seconds.

Or omit and enter an end time separately.

Specifying Time with "splice_time" Tag

Use the splice_offset tag to specify the start time as a specific clock time, for example, at 10:20:33. The time you specify must match the timecode format in the event, as specified by the Timecode Config Source field in the event or profile. For example, if you specify 10:20:33 and the event uses system clock, the message is inserted at 10:20:33 UTC. If the event uses local time, the message is inserted at 10:20:33 for the time zone of the node.

To verify the timecode format in the event, submit a GET live_events request and (in the response) read the value in the timecodeconfig tag.

Splice Time requires either knowing in advance to insert an ad avail at a given time, or obtaining the current time and inserting an offset so that the time is not missed. It is easier to use Splice Time when you know start times in advance. You can obtain the timecode of the content currently being encoded; see Get Current Time.


                  The file images/splice-insert-splice-time.png.

Specifying Time with "splice_offset" Tag

You can use the splice_offset tag to specify time as a number of milliseconds into the future from the moment at which the command is executed. This offset may be 0, which means to insert immediately.

Note

Splice Offset is the recommended method if adding ad avails “on the fly” because it does not require knowing the current time of the video.

Time of Insertion of the Message and Time for the Ad Avail

The time the message is inserted and the start time for the ad avail are typically not identical. For example, you insert a message that says “insert an ad avail at 10:35:15:0”. The message is actually inserted in the content close to the moment that you enter the request. The message may actually be inserted at 10:35:00:0.

So you can insert the message in advance of its actual “targeted time.” In fact, it is a good idea to include some offset although take care when calculating offset.

  • Too little offset: If you do not add enough offset, the specified time may have already passed. The ad avail may still be inserted in the video (at the current frame) but will be inserted too late for AWS Elemental Live to act upon it.

    For example, the command says “insert an ad avail at 10:35:15.0” but, if that time has passed, the message is inserted at 10:35:40.0 (for example). AWS Elemental Live inserts the message if its request time is less than 1 hour after the targeted time. Otherwise, it discards the message. Note that the message is inserted in the content but it has a start time that has already passed.

  • Too much offset: The maximum offset is 6 hours. Within that range, the ad avail will be inserted at a timepoint (for example 10:35:20), and the command is “insert ad avail at 10:36:00.0, that is, in 40 seconds from now.”

Duration of the Message and Time for the Ad Avail

You can include a duration so that a start time is included and an end time is implied by the length of time for the duration. Or you can omit the duration so that only a start time is included. If you omit the duration, enter an end time separately.

Response

The body of the response is XML content consisting of one response element containing the following tags:

Tag Sub-tag Sub-sub-tag Type Description
event_id integer The event ID of this SCTE-35 request.
splice_time hours integer

If splice_time was specified, the hour, minutes, seconds and frame at which to insert the ad avail.

If splice_offset was specified, all tags specify “0.”

minutes integer
seconds integer
frames integer
splice_offset integer

If splice_offset was specified, the time at which to insert the ad avail.

If splice_time was specified, this tag has a null value.

message string A description of the action taken.
errors Included only in an error response.
error code An error code.
error message string A human-readable error message.

A success response does not include the <errors> element. A failure response contains only the <event_id> and <errors> elements.

Example Message

The following shows an example message:

<message>Inserted event [32] at event time[08:02:38], PTS[00:02:20.982]. Avail time[08:02:38 0f] PTS[08:02:38.023], duration[01:00:00.000]. Current NTP [15:18:05.712]</message>
Data Description
Inserted event [n] The event ID for the ad avail request.
event time

The requested start time of the ad avail, as per the original request.


                                 The file images/timecode-config.png.
PTS (first occurrence) The time at which the SCTE-35 message insertion request was received by AWS Elemental Live, in a clock representation of the presentation timestamp (PTS). This PTS is a “timer”, not a clock time.
Avail Time

The requested start time of the ad avail, including the frame. This time is in the timecode specified in the event or profile. For more information, see About Timecode Configuration and Timers.

This time is in the timecode specified in the event or profile. If the timecode configuration source is Clock time, Local time, and Specified time, this time is a “clock time.”

PTS (second occurrence) The requested start time of the ad avail (with the frame converted to milliseconds).
duration The duration of the ad avail, if specified, in 24-hour format.
Current NTP The network time protocol (NTP) when the SCTE-35 message insertion request was received by AWS Elemental Live.

Splice Insert Examples

Splice Time

Insert a message into the event with the ID 3. Insert the message at 10 hours, 32 minutes, and 10 seconds, and give it a duration of 30 seconds. (The implied end time will be 10 hours ,32 minutes, and 40 seconds.)

POST 10.4.136.95/live_events/3/cue_point ---------------------------------------- <cue_point> <splice_time> <hours>10</hours> <minutes>32</minutes> <seconds>10</seconds> <frames>0</frames> </splice_time> <duration>30</duration> </cue_point>

The following shows a success response where splice_offset was used in the request. The SCTE-35 request has an ID of 8.

<response value="cue_point"> <event_id>8</event_id> <splice_time> <hours>0</hours> <minutes>0</minutes> <seconds>0</seconds> <frames>0</frames> </splice_time> <splice_offset>8000</splice_offset> <message> Inserted at PTS[1234]. Avail time[00:00:05.000] PTS[2345], duration[30]. </message> </response>

The following shows a failure response:

<response value="cue_point"> <event_id>8</event_id> <errors> <error> <code>1040</code> <message>Preroll time must be positive integer</message> </error> <errors> </response>

Splice Offset

Insert a message into the event with the ID 3. Insert the message 8000 milliseconds from the moment the command is executed. The message has a duration of 30 seconds.

POST 10.4.136.95/live_events/3/cue_point ---------------------------------------- <cue_point> <splice_offset>8000</splice_offset> <duration>30</duration> </cue_point>