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 can also include 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:

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.

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 performed. This offset can be 0, which means to insert immediately.

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 downstream system won't act on the instruction (it won't insert the ad avail) until the specified time.

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

Splice offset and clock changes

When you use splice offsets in a splice insert, you must restart the event whenever the clocks change to or from Standard Time. If you don’t restart the event, your splice inserts will permanently either be inserted at the wrong time or not be inserted at all.

These rules apply only if the event uses the local system clock, because this is the only type of clock that is affected by the clock change.

If you don't plan for any splice inserts in the first few minutes after the clocks change, you can simply restart the event as soon as the clocks change in the region and time zone that the Elemental Live appliance is configured for.

If your workflow does include plans for splice inserts just after the clocks change, follow these steps:

Response

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

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

<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>

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 performed. 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>