Create or Modify a Non-Running Event with MOV Motion Overlay - AWS Elemental Live

This is version 2.19 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.

Create or Modify a Non-Running Event with MOV Motion Overlay

When you create an AWS Elemental Live event, you can include one or more static overlays and one motion overlay. To include the motion overlay, use the REST commands in this section. This description assumes that you are familiar with the XML body for a live_event aside from the data for the motion graphic overlay.

HTTP Request and Response

HTTP URL

POST http://<Live IP Address>/live_events

or:

PUT http://<Live IP Address>/live_events/<live event id>

Body of Request

XML content consisting of one live_event element that contains:

  • All the usual elements and tags.

  • One motion_image_inserter element directly inside the live_event. This element contains the tags listed in the table in the section Create or Modify a Non-Running Event with MOV Motion Overlay.

Response

The response repeats back the data that you posted with <ID> tags for many elements including IDs for the following motion image inserter elements

  • motion_image_inserter

  • motion_image_inserter_input

Child Elements of <motion_image_inserter>

Element Type Description
<action_time> String The start time for the motion overlay. Specify the start time in one of the formats described below this table.
<active> Boolean

Always set to true when initially setting up the motion overlay.

After the initial setup, the value of this tag can be changed (possibly in combination with action_time) to start and stop the motion overlay.

Note: <active> is distinct from <activate>, which is used for static image overlays.

<enable_rest> Boolean

When creating or modifying a non-running event, set to true if you plan to manage motion overlays via the REST API, after the initial setup.

When modifying the motion overlay in a running event, you typically want to leave this tag set to true. Set to false only if you want to block the ability to work with motion overlay in a running event.

<full_frame> Boolean

Expand the overlay to fit the video frame. In this case, make sure Left and Top are set to 0 or left blank.

If this field is checked and the motion overlay has a different aspect ratio to the underlying video, the motion overlay will be scaled until either:

  • • The motion overlay fits in the length. The overlay will then be positioned with equal space on the left and right.

  • • The motion overlay fits in the width. The overlay will then be positioned with equal space above and below.

Note that the “Stretch to output” field in the Stream section does not affect the motion overlay; even if the video is stretched, the overlay is not stretched.

<image_x> Integer

Placement of the left edge of the motion overlay relative to the left edge of the video frame, in pixels. 0 is the left edge of the frame. When creating an event, cannot be omitted.

Take note of the width of the motion overlay and make sure that the position of the left edge of the motion overlay does not cause the right edge to be cropped.

<image_y> Integer

Placement of the top edge of the motion overlay relative to the top edge of the video frame, in pixels. 0 is the top edge of the frame. When creating an event, cannot be omitted.

Take note of the height of the motion overlay and make sure that the position of the top edge of the motion overlay does not cause the bottom edge to be cropped.

<insertion_mode> String Enter mov.
<loop_input> Boolean
  • True to loop the motion overlay indefinitely. The motion overlay will run until the event ends. To stop the overlay earlier, send the Modify MOV Motion Overlay command with <active> set to false.

  • False to run the motion overlay once.

<motion_image_inserter_ input> Child element <motion_image_inserter_input> contains only the <uri> element, described in the next row.
<uri> String The path and filename of the MOV asset.

Action Time Formats

Option 1: Timecode format (HH:MM:SS:FF). If Timecode Source field is System Clock or Local System Clock (AWS Elemental Live only): The timecode of each frame in the input is the system time at which the frame is decoded.

The overlay start is compared to the output timecode (which is shared by all outputs). The source for the output timecode is specified for the entire event, in the Timecode Config > Source field. The output timecode is calculated as follows:

  • If Source is Embedded: The timecode is extracted from the timecode carried with the input media. That timecode becomes the output timecode for the first transcoded frame. Then the output timecode counts up with each successive frame in the entire output.

  • If Source is Start at 0: The output timecode for the first frame is 00:00:00:00 and then the output timecode counts up with each successive frame in the entire output.

  • If Source is System Clock or Local System Clock (AWS Elemental Live only): The output timecode for the first frame is the system time at which the frame is decoded. Then the output timecode counts up with each successive frame in the entire output.

  • If Source is Specified Start: The output timecode for the first frame is the time you specified when you selected this option as the timecode source. Then the output timecode counts up with each successive frame in the entire output.

  • If Source is External Reference Connector (AWS Elemental Live only): The timecode is extracted from external LTC source. That timecode becomes the output timecode for the first transcoded frame. Then the output timecode counts up with each successive frame in the entire output.

Option 2: ISO 8601 UTC time with no dashes or colons. For example, 20160102T030405.678Z. In this case, the start time for every overlay will be the UTC time.

Option 3: You can only use this while adding or modifying an overlay in a running event. Set this tag to an empty string to set the start time to “now”. With this option, the start time is never exact. You cannot use this option when creating an event or modifying a non-running event.

Example

The following request creates an event with the name myLiveEvent and includes a motion_image_inserter section that inserts the motion overlay represented by a set of logo.png files:

POST http://198.51.100.22/live_events ----------------------------------- <?xml version="1.0" encoding="UTF-8"?> <live_event> <name>myLiveEvent</name> . . . <motion_image_inserter> <action_time>10:16:23:10</action_time> <active>true</active> <enable_rest>true</enable_rest> <framerate_denominator>1001</framerate_denominator> <framerate_numerator>30000</framerate_numerator> <full_frame>false</full_frame> <left>100</left> <top>200</top> <insertion_mode>mov</insertion_mode> <loop_input>true</loop_input> <motion_image_inserter_input> <uri>/data/logo001.mov</uri> </motion_image_inserter_input> </motion_image_inserter> </live_event>