# SCTE-35 message insertion into currently running events You can use the Elemental Live REST API to insert SCTE-35 messages into an Elemental Live event that is currently running. The API supports insertion of a SCTE-35 message of type **splice\$1insert** or **time signal **([Working with time signals](working-with-time-signals.md)). **Topics** + [ # Working with splice inserts ](working-with-splice-inserts.md) + [ # Working with time signals ](working-with-time-signals.md) # Working with splice inserts Splice inserts inserted by the REST API are always of type “ad avail.” You can: + Insert a SCTE-35 ad avail of type splice\$1insert. See [Insert a new splice insert message](insert-a-new-splice-insert-message.md). + Get the timecode of the content that is currently being processed. This data can be useful to determine the start time you need to enter in the command. See [Get current time](get-current-time.md). + Insert an end time in an ad avail. See [Insert an end time in an existing ad avail](insert-an-end-time-in-an-existing-ad-avail.md). + Cancel a SCTE-35 ad avail that is pending (the start time has not yet been reached). See [Cancel a pending ad avail](cancel-a-pending-ad-avail.md). **Effect of these commands** These commands modify the data stream as it is being encoded. Their precise effect on other parts of the content depends on how the event is set up, as described in earlier chapters of this guide. So it depends on the Ad Avail mode, whether manifest decoration is enabled, blanking and blackout are enabled, and whether passthrough is enabled. **Topics** + [ # Insert a new splice insert message ](insert-a-new-splice-insert-message.md) + [ # Get current time ](get-current-time.md) + [ # Insert an end time in an existing ad avail ](insert-an-end-time-in-an-existing-ad-avail.md) + [ # Cancel a pending ad avail ](cancel-a-pending-ad-avail.md) # Insert a new splice insert message Inserting splice inserts on the day the clocks change This section now includes information about using the REST API to insert a splice insert, specifically on the day that the clocks change to or from Standard Time. Inserts a SCTE-35 message of type splice\$1insert 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 /live_events//cue_point ``` **Body of HTTP** The XML body contains one cue\$1point elements containing the following tags: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elemental-live/latest/ug/insert-a-new-splice-insert-message.html) **Specifying time with "splice\$1time" tag** Use the splice\$1offset 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\$1events 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](get-current-time.md). **Specifying Time with "splice\$1offset" Tag** You can use the **splice\$1offset** 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. + **Too little offset**: If you do not add enough offset, the specified time might have already passed. The ad avail might still be inserted in the video (at the current frame) but will be inserted too late for 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). 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.” **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: + Determine the date and time that the clocks change,in the region and time zone that the Elemental Live appliance is configured for. + Identify all the splice insert commands that you plan to enter *before* the clocks change, and where the splice insert has an intended start time that is *after* the clocks change. For example, you plan to enter a command at 1:15 a.m. for a splice insert with a start time that is after the clocks change. Don't enter any of these commands. + As soon as the clocks change (so at approximately 2:00.01 a.m.), restart the event. Restart each event where the problem scenario applies. + After the event restarts, you can insert the splice insert commands that you previously didn’t enter. It's possible that the intended start time of one or more splice inserts has already passed. You might want to reschedule the start time for the splice inserts, or you might want to skip these splice inserts. + You can then continue entering splice insert commands in the usual way. **Response** The body of the response is XML content consisting of one **response** element containing the following tags: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elemental-live/latest/ug/insert-a-new-splice-insert-message.html) A success response does not include the element. A failure response contains only the and elements. **Example Message** The following shows an example 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] ``` | 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. | | PTS (first occurrence) | The time at which the SCTE-35 message insertion request was received by 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](processing-options.md#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 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 ---------------------------------------- 10 32 10 0 30 ``` The following shows a success response where splice\$1offset was used in the request. The SCTE-35 request has an ID of 8. ``` 8 0 0 0 0 8000 Inserted at PTS[1234]. Avail time[00:00:05.000] PTS[2345], duration[30]. ``` The following shows a failure response: ``` 8 1040 Preroll time must be positive integer ``` **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 ---------------------------------------- 8000 30 ``` # Get current time You can obtain the timecode of the frame that is currently being processed in the specified event. Refer to the following tables. **HTTP URL** ``` POST /live_events//cue_point ``` **Body of HTTP** The XML body contains one `cue_point` element containing the following tag: | Tag | Type | Value | | --- | --- | --- | | get\$1current\$1time | Integer | Always 1 | **Response** The body of the response contains one **response** element containing the following tags: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elemental-live/latest/ug/get-current-time.html) The response is provided in this format so that you could take the entire response, clean it up a bit (for example, changing the “tag” tag to “event\$1id”), and use it as the body of a request to insert a spliceinsert (see [Insert a new splice insert message](insert-a-new-splice-insert-message.md). ## Get current time example The following shows a request for the current timecode in the event that has the ID 15: ``` POST 10.4.136.95/live_events/15/cue_point ----------------------------------- 1 ``` The following shows an example response for the request: ``` 1 0 0 2 23 PTS[00:00:02.969]. Current NTP [16:21:23.573]. 0 cue_point ``` # Insert an end time in an existing ad avail You can insert an end time in the following situations: + To add an end time to a message that has not yet started if an end time was not initially included. + To cut short an ad avail that is in progress. The command can be used in this way if no end time was initially included or if it was included but you want to end early. **HTTP URL** ``` PUT /live_events//cue_point ``` **Body of HTTP** The XML body contains one `cue_point` element containing the following tags: | Tag | Sub-tag | Type | Value | | --- | --- | --- | --- | | event\$1id | | integer | The event ID of the original POST cue\$1point (the request that did not include a duration). | | return\$1offset | integer | | The number of milliseconds to wait before inserting the ad avail. | ## Insert an End Time in an Existing Ad Avail Example Insert an end time immediately into the event with the ID 4. The original SCTE-35 ad avail has an ID of 38. ``` PUT 10.4.136.96/live_events/4/cue_point ---------------------------------------- 38 0 ``` # Cancel a pending ad avail If you inserted an ad avail the start time has not yet passed, you can cancel the insertion. No SCTE-35 message will be inserted. **HTTP URL** ``` POST /live_events//cue_point ``` **Body of HTTP** The XML body contains one `cue_point` element containing the following tag: | Tag | Sub-tag | Type | Value | | --- | --- | --- | --- | | cancel\$1event\$1id | | integer | The event ID of the original SCTE-35 request. | **Response** The response includes a message that identifies the event ID of the original request. ## Cancel a Pending Ad Avail Example The following shows a request to cancel the insertion of a pending ad avail in the event with the ID 4. The original SCTE-35 ad avail has an ID of 38: ``` POST 10.4.136.96/live_events/4/cue_point ---------------------------------------- 38 ``` The following shows an example response for the request: ``` 13 5 Canceled eventID [5] cue_point ``` # Working with time signals Time signals inserted by the REST API can be one of the “ad avail” types, or some other type, depending on what you specify in the segmentation descriptor in the request. **Effect of creating a time signal** Insertion of a time signal modifies the data stream as it is being encoded. The effect of time signals on other parts of the content depends on how the event is set up, as described in earlier chapters of this guide. So it depends on the Ad Avail mode, whether manifest decoration is enabled, blanking and blackout are enabled, and whether passthrough is enabled. ## Insert a new time signal message Inserts a SCTE-35 message of type time\$1signal in the stream either immediately or at a specified time. The command always includes a start time (in the time tag) and a duration (included in the segmentation descriptor). **HTTP URL** ``` POST /live_events//time_signal ``` **Body of HTTP** The XML body contains one **time\$1signal** element containing the following tags: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elemental-live/latest/ug/working-with-time-signals.html) **Response** The body of the response is XML content consisting of one **response** element containing the following tags: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elemental-live/latest/ug/working-with-time-signals.html) A success response does not include the element. A failure response contains only the and elements. **Example Message** The following shows an example 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] ``` | 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. | | PTS (first occurrence) | The time at which the SCTE-35 message insertion request was received by 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. This time is in the timecode specified in the event or profile. If 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 Elemental Live. | ## Insert a new time signal message example The following shows a request to insert a SCTE-35 message immediately into the event that has ID 3. ``` POST 10.4.136.95/live_events/3/time_signal ---------------------------------------- 021B43554549000000027FBF030C54564E413130303030303031300000 ``` The following shows an example success response for the request: ``` Inserted time signal at event time[1234], PTS[1234]. Signal time[1234] PTS[1234]. 1 0 0 0 ``` The following shows an example failure response for the request: ``` 1 1040 Invalid time signal message ```