# Insert a motion graphic overlay in Elemental Live
<a name="motion-graphic-overlay"></a>

This guide shows you how to insert a motion graphic overlay in AWS Elemental Live for video that it encodes. You can insert one asset into the event so that you can use it as a motion graphic overlay on all video outputs. 

You can set up the event to use one of the following assets:
+ An HTML5 asset
+ A `.mov` file
+ A set of ordered still `.png` files as assets for motion image overlays 

The motion graphic overlay will always be inserted in all outputs in the event.

The motion overlay will be burned into the video after decoding and input-specific processing, and before encoding and creation of individual streams and outputs. 

**License requirement**

To insert a motion overlay in any event, the software installed on the Elemental Live appliance must include the motion graphics license.

**Topics**
+ [How to insert a motion overlay with HTML5](how-to-insert-a-motion-overlay-with-html5.md)
+ [How to insert a motion overlay with QuickTime MOV](how-to-insert-a-motion-overlay-with-quicktime-mov.md)
+ [How to insert a motion overlay with a set of PNG files](how-to-insert-a-motion-overlay-with-png.md)

# How to insert a motion overlay with HTML5
<a name="how-to-insert-a-motion-overlay-with-html5"></a>

You can insert a motion overlay with HTML5. The overlay could be an animated overlay such as a sports scoreboard, a stock price ticker tape, or the current time and temperature. You use an HTML5 *authoring system* to create and publish an HTML asset. This system usually has an authoring component that lets you create the overlay content, and a control component that lets you control how and when the overlay is visible. 

You configure the Elemental Live event with all the information about the motion overlay, including the location of the asset. After the event starts, Elemental Live pulls the asset that is being published, and includes the overlay in the video, when appropriate. Elemental Live doesn't provide any features for manipulating the content or position of the overlay. 

**Topics**
+ [Step A: Choose the method for show/hide](step-design-controls-html5.md)
+ [Step B: Prepare the HTML5 asset](step-prepare-the-html5-asset.md)
+ [Step C: Set up the event](html5-step-set-up-the-event.md)
+ [Step D: Showing and hiding the motion overlay](html5-step-manage-the-overlay-on-a-running-event.md)

# Step A: Choose the method for show/hide
<a name="step-design-controls-html5"></a>

You must speak to the operator of the authoring system and decide how the overlay will be controlled. There are several options.

## Authoring system control
<a name="html5-controls-author-control"></a>

The authoring system might set up the asset so that it controls how and when the motion overlay appears. In the output video, the overlay is always present, but sometimes it contains no content. For example, the authoring system might set up so that when the motion overlay shouldn't appear on the video, the overlay is present but contains no content (it is transparent). 

Your role is to set up in Elemental Live so that the event shows the overlay as soon as the event starts. You never hide the overlay. You (the Elemental Live operator) don't have to coordinate with the operator of the authoring system.

It is the job of the authoring system to make sure that the asset shows content sometimes and appears as transparent (no content) at other times. 

## REST API control
<a name="html5-controls-rest"></a>

The authoring system might set up the asset with the expectation that you (the Elemental Live operator) will show and hide the overlay at the appropriate times. 

Elemental Live continually pulls the asset from the authoring system. 

Your role is to enter REST API commands to show and hide the overlay. You (the Elemental Live operator) and the operator of the authoring system must coordinate the schedule for showing overlays.

## SCTE 35 control
<a name="html5-controls-scte35"></a>

The authoring system might set up the asset with the expectation that the source content includes specific SCTE 35 messages that Elemental Live reads to know when to show or hide the overlay. 

You have no role in showing or hiding the overlay. 

Instead, the overlay is controlled as follows. Elemental Live is continually pulls the asset from the authoring system. In addition, Elemental Live automatically shows or hides the overlay when it encounters the SCTE 35 messages.

To use this method, the content must already contain the appropriate SCTE 35 messages. You can't use Elemental Live to insert these messages.

The authoring system, the content provider (who must insert the SCTE 35 messages in the content), and you (the Elemental Live operator) must coordinate the SCTE 35 messages and the schedule.

Elemental Live reacts to well-formed SCTE 35 messages of type `time_signal`. The message must include the following tags:
+ `segmentation_type_id`: Provider Overlay Placement Opportunity Start (0x38) or Provider Overlay Placement Opportunity End (type 0x39).
+ `segmentation_duration_flag`: true or false
+ `segmentation_duration`: Must be included if the `segmentation_duration_flag` is true.

# Step B: Prepare the HTML5 asset
<a name="step-prepare-the-html5-asset"></a>

You use an authoring system to create the asset and to manage the content, including implementation of features such as fade or opacity. 

1. Choose an authoring system and create the asset – Use the authoring system to create the asset. The HTML5 content must meet these requirements:
   + It can be any HTML5 authoring system that uses standard browser-based rendering techniques. 
   + It can use any HTML5 tags except video and audio.
   + It can incorporate javascript that interacts with a backend system to dynamically control the asset that is being published to the source URL. You should size the content to be the same size or smaller than the width and height of the largest video rendition in your channel. You can also use responsive HTML (HTML that resizes automatically to different frame sizes).

   See the list after this procedure for more guidelines for preparing the asset.

1. Make a note of the URL of the asset. This URL must be accessible to Elemental Live.

1. If the location of the motion graphics asset requires login in order for Elemental Live to download the asset, make a note of the user name and password.

**Supported authoring features**

The asset can include features that are supported in Chrome version 84.0.4147.125. If you include features that are supported only in a later version, the asset might not render properly in Elemental Live.

**CPU requirements**

An HTML5 asset increases CPU utilization for each enabled event by *up to * 20%, depending on complexity of the asset. For example, if your event currently uses 30% of CPU (without HTML5 motion graphics), it might use approximately 36% with HTML5 motion graphics.

**Resolution**

Elemental Live renders the asset to match full-frame for the resolution of the first video input. If the input resolution changes during the event, Elemental Live will continue to render at the initial resolution, but will scale up or down to match the asset's new resolution. 

We recommend that you set up the asset to have the same pixel ratio as the video. The resolution of the asset can change through the life of the event, but its ratio shouldn't change.

**Color space**

If you set up the event to [convert the color space](hdr-working-with.md) of the video, Elemental Live will convert the asset in the same way. For example, it will convert the color space to HDR10. To perform this conversion, Elemental Live will assume that the asset color space is SDR.

# Step C: Set up the event
<a name="html5-step-set-up-the-event"></a>

You configure the event with all the information about the motion overlay. After you start the event, you won't be able to change any information about the motion overlay. You can only show or hide it. 

You can configure the information using the web interface or the REST API. 

# Using the web interface
<a name="html5-set-up-event-web-interface"></a>

**To configure the event using the web interface**

1. Obtain the asset URL and user credentials (if required) from the administrator of the authoring system that is publishing the HTML5 asset.

1. In the **Global Processors** section, go to the **Image Inserter** field and choose **On**. More fields appear.

1. Complete these fields:
   + **Insertion Mode**: Choose **HTML**.
   + **Input**: Enter the location of the HTML5 asset.

     If access to your local or mounted directory requires authentication, enter the user name and password.

1. Set the following fields to match the control that you're using.    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elemental-live/latest/ug/html5-set-up-event-web-interface.html)

For detailed information about the fields, see [Fields for an HTML5 asset](html5-set-up-event-fields.md).

# Using the REST API
<a name="html5-set-up-event-fields-api"></a>

This description assumes that you are familiar with using the REST API and with the XML body for a `live_event`.

**To configure the event using the REST API**

1. Enter a POST or PUT command in the usual way. Use POST to create a new event. Use PUT to modify an existing event:

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

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

1. In the body of the request, include one `motion_image_inserter` element inside the `live_event` tag. Complete these tags:
   + `insertion_mode`: Set to HTML.
   + `motion_image_inserter_input`: Enter the location and file name of the HTML5 asset. 

     If access to your local or mounted directory requires authentication, enter the user name and password.

1. Set the following tags to match the control you are using.    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elemental-live/latest/ug/html5-set-up-event-fields-api.html)

   For detailed information about the tags, see [Fields for an HTML5 asset](html5-set-up-event-fields.md).

   ```
   <motion_image_inserter>
       <active>
       <enable_rest>
       <enable_scte35>
       <insertion_mode>
       <motion_image_inserter_input>
         <uri>
         <password>
         <username>
       </motion_image_inserter_input>
   </motion_image_inserter>
   ```

1. 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`

**Example**  
The following request creates an event with the name myLiveEvent and turns on the REST API control option.

```
POST http://198.51.100.22/live_events
-----------------------------------
  <?xml version="1.0" encoding="UTF-8"?>
      <live_event>
          <name>myLiveEvent</name>
          . . .
          <motion_image_inserter>
              <active>true</active>
              <enable_rest>true</enable_rest>
              <insertion_mode>html</insertion_mode>
              <motion_image_inserter_input>
                  <uri>http://myAuthorSystem/output/output?aspect=16.9</uri>
              </motion_image_inserter_input>
          </motion_image_inserter>
      </live_event>
```

# Fields for an HTML5 asset
<a name="html5-set-up-event-fields"></a>


| Field on web interface | Tag in the XML | Type | Description | 
| --- | --- | --- | --- | 
| Insertion Mode | <insertion\$1mode> | String | Choose HTML. | 
| Input | <uri> | String |  | 
| Username Password | <username><password> | String |  | 
| Active | <active> | Boolean |  Always select this box.  | 
| Enable REST Control | <enable\$1rest> | Boolean | Select this field only if you chose to use the REST API to [control the asset](step-design-controls-html5.md). | 
| Enable SCTE 35 Control | <enable\$1scte35> | Boolean | Select this field only if you chose to use SCTE 35 messages in the source content to [control the asset](step-design-controls-html5.md). | 

# Step D: Showing and hiding the motion overlay
<a name="html5-step-manage-the-overlay-on-a-running-event"></a>

If you have configured the motion overlay for [REST control](step-design-controls-html5.md#html5-controls-rest), start the event , then enter REST API commands to show and hide the motion overlay.

If you have configured the motion overlay for authoring system control or SCTE 35 control, Elemental Live automatically shows and hides the motion overlay. You don't have to intervene. You can stop reading this section.

**To show or hide the motion overlay on a running event**

1. Enter a POST command as follows:

   ```
   POST http://<Live IP Address>/live_events/<live event id>/motion_image_inserter
   ```

1. In the body of the request, include one `motion_image_inserter` element that contains only the `active` tag. Set the `active` to true to show the motion overlay, or set it to `false` to hide the motion overlay. See the examples after this procedure.

1. The response repeats back the data that you posted with `<ID>` tags for `motion_image_inserter` and `motion_image_inserter_input`. 

****Example 1****  
The following example shows the motion overlay immediately.

```
POST http://198.51.100.22/live_events/33/motion_image_inserter
-------------------------------------------------------------
<motion_image_inserter>
    <active>true</active>
</motion_image_inserter>
```

****Example 2****  
The following example hides the motion overlay immediately.

```
POST http://198.51.100.22/live_events/33/motion_image_inserter
-------------------------------------------------------------
<motion_image_inserter>
    <active>false</active>
</motion_image_inserter>
```

# How to insert a motion overlay with QuickTime MOV
<a name="how-to-insert-a-motion-overlay-with-quicktime-mov"></a>

You can use a `.mov` file as an asset for the motion image overlay. 

Here are some examples of how motion image overlay works with a MOV file:
+ Example 1: “Coming up” motion overlay – You want to insert an asset that will run as a 10-second motion overlay 59 minutes into the runtime of the event. You want the motion overlay to be placed in the lower right corner of the video frame.
+ Example 2: Animated corporate logo – You want to insert an asset and run it every 5 minutes, starting 20 minutes into the runtime of the event. You specify the single asset in the event and specify the first runtime. You start the event and, after the motion overlay has run once, you send a REST API command to modify the start time of the asset to a new time. You repeat this command (each time with a new start time) as many times as you want. 

Typically, you set up the event as follows:
+ You prepare a MOV file and store it at a location that is accessible to Elemental Live.
+ You configure the event with the location URL and start time of the first motion overlay you want to run, with position and size information, and with an instruction to run the motion overlay once or to loop it. You set up the motion overlay to be active when the event starts, and you enable control via the REST API.
+ When you're ready, you start the event. The motion overlay configured in the event runs at the specified time. You then enter REST API commands to specify different content (a different URL), a start time, and a new position and size. After that motion overlay plays, you can enter another command to run different content, as required, for the duration of the event. 

# Step A: Prepare the MOV asset
<a name="step-prepare-the-mov-asset"></a>

1. Create a file – Use a third-party process to create a MOV file encoded with Apple QuickTime Run Length Encoding. Other codecs in the MOV container are not supported. Take care with the following settings:
   + Aspect ratio: The motion overlay can have any aspect ratio. It does not have to match the aspect ratio of the video output.
   + Frame rate: The frame rate of the motion overlay asset must match the frame rate of the underlying video. 
   + Size: The motion overlay can be any size, in pixels, up to the size of the underlying video. The motion overlay must be prepared in the desired size; there is no way to resize it when setting it up in the event.
   + Position: The motion overlay cannot be positioned so that part of the motion overlay runs beyond the right edge or bottom edge of the underlying video.
     +  If you set up a motion overlay so that it is too big or it overruns and Elemental Live can identify this error at event creation time, then an error message will appear.
     + If Elemental Live cannot identify the error in advance, an error message will appear while the event is running. The event will not stop but the insertion request will fail.

1. Place the file – Place the MOV file in a location accessible to the Elemental Live: on a local directory, on a remote filesystem accessible via mount point, or in an Amazon S3 bucket. 

   You can specify the location in one of the following ways:
   + Local to the Elemental Live appliance. For example, `/data/assets/motion overlay.mov`
   + A remote server via a mount point. For example, `/data/mnt/assets/motion overlay.mov`
   + An Amazon S3 bucket, using SSL. For example, `Amazon S3ssl://company.test/DOC-EXAMPLE-BUCKET/motion overlay.mov`
   + An Amazon S3 bucket, without SSL. For example, `S3://company.test/DOC-EXAMPLE-BUCKET/motion overlay.mov`

# Step B: Set up the event
<a name="mov-step-set-up-the-event"></a>

You configure the event with information about the first motion overlay. You can configure this information when creating an event. Or you can change the existing motion overlay configuration on a non-running event. You can configure the information using the web interface or the REST API. 

**Topics**
+ [Using the web interface](mov-set-up-event-web-interface.md)
+ [Using the REST API](mov-set-up-event-fields-api.md)
+ [Fields for a MOV asset](mov-set-up-event-fields.md)

# Using the web interface
<a name="mov-set-up-event-web-interface"></a>

**To configure the event using the web interface**

1. In the **Global Processors** section, go to the **Image Inserter** field and choose **On**. More fields appear.

1. Complete the fields. You can configure some or all the information in the non-running event, but you must at least set the following fields:
   + **Insertion Mode**
   + **Enable REST Control**

   You must also configure the motion overlay behavior when the event first starts:
   + If you want the motion overlay to appear as soon as the event starts, specify all the fields. Make sure that you check **Active**, and make sure that you leave the **Action Time** empty.
   + If you don't want the motion overlay to appear as soon as the event starts, leave **Active** unchecked.

   You can configure the remaining fields after you've started the event, when you want to run the first motion overlay.

   For detailed information about the fields, see [Fields for a MOV asset](mov-set-up-event-fields.md).

# Using the REST API
<a name="mov-set-up-event-fields-api"></a>

This description assumes that you are familiar with using the REST API and with the XML body for a `live_event`.

**To configure the event using the REST API**

1. Enter a POST or PUT command in the usual way. Use POST to create a new event. Use PUT to modify an existing event:

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

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

1. In the body of the request, include one `motion_image_inserter `element inside the `live_event `tag. The XML is structured as follows. 

   You can configure some or all the information in the non-running event, but you must at least set the following tags:
   + `insertion_mode`
   + `enable_rest`

   Make sure that you configure for the desired motion overlay behavior when the event first starts:
   + If you want the motion overlay to appear as soon as the event starts, specify all the tags. Make sure that you set `active` to `true`, and make sure that you leave `action_time` empty.
   + If you don't want the motion overlay to appear as soon as the event starts, set `active` to `false`.

   You can configure the remaining tags after you've started the event, when you want to run the first motion overlay.

   For detailed information about the tags, see [Fields for a MOV asset](mov-set-up-event-fields.md).

   ```
   <motion_image_inserter>
       <action_time>
       <active>
       <enable_rest>
       <full_frame>
       <image_x>
       <image_y>
       <insertion_mode>
       <loop_input>
       <motion_image_inserter_input>
         <uri>
         <password>
         <username>
       </motion_image_inserter_input>
   </motion_image_inserter>
   ```

1. 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`

**Example**  
The following request creates an event with the name myLiveEvent. The event includes a `motion_image_inserter `section that inserts the motion overlay at a specific time:

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

# Fields for a MOV asset
<a name="mov-set-up-event-fields"></a>


| Field on web interface | Tag in the XML | Type | Description | 
| --- | --- | --- | --- | 
| Insertion Mode | <insertion\$1mode> | String | Choose MOV. | 
| Input | <uri> | String |  The location and file name of the MOV file. For Amazon S3, use `sse=true` to turn on Amazon S3 Server Side Encryption (SSE) and `rrs=true `to turn on Reduced Redundancy Storage (RRS). Default values for RRS and SSE are `false`.  | 
| Username Password | <username><password> |  |  If access to your local or mounted directory requires a user name and password, click the lock icon next to the **Input** field to show the **Username** and **Password** fields. For Amazon S3, enter the access key ID in the user name field. Enter the secret access key in the password field.  | 
| Left | <image\$1x> | 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. 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.  | 
| Top | <image\$1y> | 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. Default 0. 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.  | 
| ActionTime | <action\$1time> | String | The start time for the motion overlay. Specify the start time in one of the formats discussed in detail below this table. | 
| Loop Input | <loop\$1input> | Boolean |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elemental-live/latest/ug/mov-set-up-event-fields.html)  | 
| Full Frame | <full\$1frame> | Boolean |  Expand the motion overlay to fit the video frame. In this case, make sure Left and Top are set to 0. If this field is selected and the motion overlay has a different aspect ratio to the underlying video, the motion overlay will be scaled until one of the following applies: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elemental-live/latest/ug/mov-set-up-event-fields.html) Note that the **Stretch to output** field in the **Stream** section does not affect the motion overlay; even if the video is stretched, the motion overlay is not stretched.  | 
| Active | <active> | Boolean |  Always select this box when initially setting up the motion overlay. After the initial setup, the value of this tag can be changed via the REST API to manage the content and behavior of the motion overlay.  | 
| Enable REST Control | <enable\$1rest> | Boolean | Check this field only if you plan to manage motion overlays via the REST API, after this initial setup via the web interface. Typically, you will want this tag to be true. | 

**Action time formats**

**Option 1: ** Timecode format (HH:MM:SS:FF). 

The value to enter for HH:MM:SS:FF depends on the method used to calculate the *output timecode*. This method is specified in the **Timecode Config > Source** field. Identify the Source method set for your event, then set the action time to match the timecode of the frame where you want the action to occur.
+ If **Source** is **Embedded**: The output timecode is extracted from the timecode that is 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. For example, 10:24:25:20, 10:24:25:21, and so on.
+  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. For example, 00:00:00;01: 00;00:00:02, and so on.
+ If **Source** is **System Clock **or **Local System Clock**: 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. For example, if the first frame is decoded at 09:45:51, then that timecode is 09:45:51:01. The timecode for the next frame is 09:45:51:02, and so on.
+ 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. For example, if you set the time to 15:30;00, then the timecode for the first frame is 15;30:00:01, and so on. 
+ If **Source** is **External Reference Connector**: 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. For example, the timecode for the first frame is 20:03:19:01, then 20:03:19:01, and so on.

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

**Option 3:** You can only use this option while adding or modifying a motion overlay in a running event. Set the `action_time` 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. 

# Step C: Manage the motion overlay on a running event
<a name="mov-step-manage-the-overlay-on-a-running-event"></a>

After the event starts, the motion overlay that is configured in the event runs at the specified time. When the event is running, you can work with the motion overlay only via the REST API. You can enter REST API commands to make the following changes:
+ A different URL, to specify different content.
+ A start time, the new position and size, and the specified loop behavior.

**Note**  
Commands sent during an event change the event XML. Therefore, if you export the XML and create a new event with it, the new event will have any motion overlays set up as they were set during the course of the event, not as they were when the event was created. 

**To modify the motion overlay on a running event**

1. Decide which fields you want to modify. For information about the types of changes that you can make, see the table [later in this section](#mov_api_changes).

1. Enter a POST command to modify any of the image overlay parameters in the running event:

   ```
   POST http://<Live IP Address>/live_events/<live event id>/motion_image_inserter
   ```

1. In the body of the request, include one `motion_image_inserter` element that contains the required tags. For more information about the tags, see [Using the REST API](mov-set-up-event-fields-api.md). 

1. The response repeats back the data that you posted with `<ID>` tags for `motion_image_inserter` and `motion_image_inserter_input`. 

****Example 1****  
The following example request modifies the running event with the ID 33. It sets up the currently defined motion overlay MOV to run again at 20160102T030405.678Z.

```
POST http://198.51.100.22/live_events/33/motion_image_inserter
-------------------------------------------------------------
<motion_image_inserter>
    <action_time>20160102T030405.678Z</action_time>
    <active>true</active>
</motion_image_inserter>
```

****Example 2****  
The following example request modifies the running event with the ID 33. It stops the motion overlay. Notice that you include **action\$1time** with an empty value so that you clear the time currently specified in the XML. If you forget to do this, Elemental Live might try to apply that time to the next show/hide request.

```
POST http://198.51.100.22/live_events/33/motion_image_inserter
-------------------------------------------------------------
<motion_image_inserter>
    <action_time></action_time>
    <active>false</active>
</motion_image_inserter>
```<a name="mov_api_changes"></a>

**Types of changes**

This table provides information about some of the changes you can make to a running event via the REST API:


| State of motion overlay | Desired action | How to use the `motion_image_inserter` command | Tags to change | 
| --- | --- | --- | --- | 
| Not running | Run the motion overlay immediately. | Enter the command to set the active tag to true and set the <action\$1time> tag to empty. | active`action_time` | 
| Not running | Run the motion overlay again at a specified time. | Enter the command to set the active tag to true and set the <action\$1time> tag to the desired start time. | active`action_time` | 
| Not running | Run a different motion overlay of the same file type. |  Enter the command to change the motion overlay to point to a different asset.  Set the `<active>` tag to `true` and set the `<action_time>` tag to the time you want the start the new motion overlay. Set the `<loop>` tag to `true` or `false`.  | All tags that apply to the current motion overlay type. | 
| Running | Stop the running motion overlay. | Just before you want the motion overlay to stop, enter the command to set the active tag to false. | active | 
| Running | Start the motion overlay. |  To start the motion overlay again, enter the command to set the `<active>` tag to `true` and the `<action_time>` tag set to the time you want the motion overlay to begin.  | active | 
| Running | Change to a different motion overlay. | Enter the command to change the motion overlay to a different file. | All tags, not just the ones you want to change. If you exclude a tag, the default value will apply. | 

# Step D: Run the event again
<a name="mov-step-run-again"></a>

You might want to run the same event again. If you do so, make sure that the motion overlay is set up correctly. You must do this because when you enter REST API commands to control the motion overlay when the event is running, the event XML for the motion overlay changes.

For example, you might set up the event with motion overlay A and a start time of 9:00 am. You then run the event and change the content and start time of the motion overlay several times. The last motion overlay to run in the event is motion overlay B with a start time of 4:00 pm. That is the information now in the event XML. Before you start the event the next day, review and modify the motion overlay information.

# How to insert a motion overlay with a set of PNG files
<a name="how-to-insert-a-motion-overlay-with-png"></a>

You can use a set of `.png` files as an asset for the motion image overlay. 

Here are some examples of how motion image overlay works with a set of PNG files:
+ Example 1: “Coming up” motion overlay – You want to insert an asset that will run as a 10-second motion overlay 59 minutes into the runtime of the event. You want the motion overlay to be placed in the lower right corner of the video frame. 
+ Example 2: Animated corporate logo – You want to insert an asset and run it every 5 minutes, starting 20 minutes into the runtime of the event. You specify the single asset in the event and specify the first runtime. You start the event. After the motion overlay has run once, you send a REST API command to modify the start time of the asset to a new time. You repeat this command (each time with a new start time) as many times as you want. 

Typically, you set up the event as follows:
+ You prepare a set of PNG files and store them at a location that is accessible to Elemental Live.
+ You configure the event with the location URL and start time of the first motion overlay you want to run, with position and size information, and with an instruction to run the motion overlay once or to loop it. You set up the motion overlay to be active when the event starts, and you enable control via the REST API.
+ When you're ready, you start the event. The motion overlay configured in the event runs at the specified time. You then enter REST API commands to specify different content (a different URL), a start time, and a new position and size. After that motion overlay plays, you can enter another command to run different content, as required, for the duration of the event. 

# Step A: Prepare the png asset
<a name="step-prepare-the-png-asset"></a>

1. Create a file – Use a third-party process to convert an animation asset to a series of PNG files. 

1. Take care with these aspects of the conversion:
   + File count: When you insert the files into the video, you will specify the frame rate for the motion overlay. Therefore, make sure that the conversion results in a file count that aligns with the intended frame rate. (The frame rate of the motion overlay does not necessarily have to match the frame rate of the underlying video.) For example, if the motion overlay will run for 10 seconds at 30 frames/second, make sure that the conversion produces 300 files. If the file count and frame rate do not align, the quality of the animation might suffer.
   + The PNG files must contain RGB and one alpha channel. The alpha channel will be used for per-pixel blending.
   + File names: Make sure that the file names of the converted files include a sequential number. Numbering must start at 0. There can be any number of digits in the numerical part of the file name, as long as it is the same for each file. For example, 000 to 200 (three digits in both files) but not 00 to 200 (two digits in one file and three digits in the other file). 
   + Aspect ratio: The motion overlay can have any aspect ratio. It does not have to match the aspect ratio of the video output.
   +  Size: The motion overlay can be any size, in pixels, up to the size of the underlying video. The motion overlay must be prepared in the desired size; there is no way to resize it when setting it up in the event.
   + Position: The motion overlay cannot be positioned so that part of the motion overlay runs beyond the right edge or bottom edge of the underlying video.
     +  If you set up a motion overlay so that it is too big or it overruns and Elemental Live can identify this error at event creation time, then an error message will appear.
     + If Elemental Live cannot identify the error in advance, an error message will appear while the event is running. The event will not stop but the insertion request will fail.

1. Place the file – Place the converted file in a location accessible to Elemental Live: On a local directory, on a remote filesystem accessible via mount point, or in an Amazon S3 bucket. Choose a location as described in [Fields for a PNG asset](png-set-up-event-fields.md), then note the location for setting up the motion overlay in the event.

   You can specify the location in one of the following ways: 
   + Local to the Elemental Live appliance. For example, `/data/assets/motion overlay_001.png`
   + A remote server via a mount point. For example, `/data/mnt/assets/motion overlay_001.png`
   + An Amazon S3 bucket, using SSL. For example, `Amazon S3ssl://company.test/DOC-EXAMPLE-BUCKET/motion overlay_001.png`
   + An Amazon S3 bucket, without SSL. For example, `S3://company.test/DOC-EXAMPLE-BUCKET/motion overlay_001.png`

# Step B: Set up the event
<a name="png-step-set-up-the-event"></a>

You configure the event with information about the first motion overlay. You can configure this information when creating an event. Or you can change the existing motion overlay configuration on a non-running event. You can configure the information using the web interface or the REST API. 

**Topics**
+ [Using the web interface](png-set-up-event-web-interface.md)
+ [Using the REST API](png-set-up-event-fields-api.md)
+ [Fields for a PNG asset](png-set-up-event-fields.md)

# Using the web interface
<a name="png-set-up-event-web-interface"></a>

**To configure the event using the web interface**

1. In the **Global Processors** section, go to the **Image Inserter** field and choose **On**. More fields appear.

1. Complete the fields. You can configure some or all the information in the non-running event, but you must at least set the following fields:
   + **Insertion Mode**
   + **Enable REST Control**

   You must also configure the motion overlay behavior when the event first starts:
   + If you want the motion overlay to appear as soon as the event starts, specify all the fields. Make sure that you check **Active**, and make sure that you leave the **Action Time** empty.
   + If you don't want the motion overlay to appear as soon as the event starts, leave **Active** unchecked.

   You can configure the remaining fields after you've started the event, when you want to run the first motion overlay.

   For detailed information about the fields, see [Fields for a PNG asset](png-set-up-event-fields.md).

# Using the REST API
<a name="png-set-up-event-fields-api"></a>

This description assumes that you are familiar with using the REST API and with the XML body for a `live_event`.

**To configure the event using the REST API**

1. Enter a POST or PUT command in the usual way. Use POST to create a new event. Use PUT to modify an existing event:

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

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

1. In the body of the request, include one `motion_image_inserter` element inside the `live_event` tag. You can configure some or all the information in the non-running event, but you must at least set the following tags:
   + `insertion_mode`
   + `enable_rest`

   Make sure that you configure for the desired motion overlay behavior when the event first starts:
   + If you want the motion overlay to appear as soon as the event starts, specify all the tags. Make sure that you set `active` to `true`, and make sure that you leave `action_time `empty.
   + If you don't want the motion overlay to appear as soon as the event starts, set `active` to `false`.

   You can configure the remaining tags after you've started the event, when you want to run the first motion overlay.

   For detailed information about the tags, see [Fields for a PNG asset](png-set-up-event-fields.md).

   ```
   <motion_image_inserter>
       <action_time>
       <active>
       <enable_rest>
       <duration>
       <framerate_denominator>
       <framerate_numerator>
       <full_frame>
       <image_x>
       <image_y>
       <insertion_mode>
       <loop_input>
       <motion_image_inserter_input>
         <uri>
         <password>
         <username>
       </motion_image_inserter_input>
   </motion_image_inserter>
   ```

1. 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`

**Example**  
The following request creates an event with the name myLiveEvent. The event includes a `motion_image_inserter` section that inserts the motion overlay at a specific time:

```
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>png</insertion_mode>
              <loop_input>true</loop_input>
              <motion_image_inserter_input>
                  <uri>/data/logo001.png</uri>
              </motion_image_inserter_input>
          </motion_image_inserter>
      </live_event>
```

# Fields for a PNG asset
<a name="png-set-up-event-fields"></a>


| Field on web interface | Tag in the XML | Type | Description | 
| --- | --- | --- | --- | 
| Insertion Mode | <insertion\$1mode> | String | Choose png. | 
| Input | <uri> | String |  The path and file name of the PNG files.  Provide the path and file name of the first PNG file in the series. All files in the series must have the same number of digits in the numerical part of the file name. For example, if the files are stored on /mnt/storage/motion\$1logos/ and the files are named logo\$1hi\$1001 to logo\$1hi\$1357, enter **/mnt/storage/motion\$1logos/logo\$1hi\$1001**. When using Amazon S3, you can optionally append the path as follows: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elemental-live/latest/ug/png-set-up-event-fields.html) Default values for RRS and SSE are `false`.  | 
| Username Password | <username><password> |  |  If access to your local or mounted directory requires a user name and password, click the lock icon next to the **Input** field to show the **Username** and **Password** fields. For Amazon S3, enter the access key ID in the username field. Enter the secret access key in the password field.  | 
| Left | <image\$1x> | 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. 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.  | 
| Top | <image\$1y> | 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. Default 0. 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.  | 
| ActionTime | <action\$1time> | String | The start time for the motion overlay. Specify the start time in one of the formats discussed in detail below this table. | 
| Numerator Denominator | framerate\$1numeratorframerate\$1denominator | Integer | On the web interface, enter the frame rate as a numerator over a denominator. For example, 29.97 fps is a numerator of 30000 and a denominator of 1001. Enter numbers that give a frame rate ratio between 1 and 120. When using the REST API, enter the numerator and denominator separately. | 
| Loop Input | <loop\$1input> | Boolean |  • Select to loop the motion overlay indefinitely. The motion overlay will run until the event ends. To stop the motion overlay earlier, see [Step C: Manage the motion overlay on a running event](png-step-manage-the-overlay-on-a-running-event.md). • Clear the check box to run the motion overlay only once.  | 
| Full Frame | <full\$1frame> | Boolean |  Expand the motion overlay to fit the video frame. In this case, make sure **Left** and **Top** are set to 0. If this field is selected and the motion overlay has a different aspect ratio to the underlying video, the motion overlay will be scaled until one of the following applies: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elemental-live/latest/ug/png-set-up-event-fields.html) Note that the **Stretch to output** field in the **Stream** section does not affect the motion overlay; even if the video is stretched, the motion overlay is not stretched.  | 
| Active | <active> | Boolean |  Always select this box when initially setting up the motion overlay. After the initial setup, the value of this tag can be changed via the REST API to manage the content and behavior of the motion overlay.  | 
| Enable REST Control | <enable\$1rest> | Boolean | Select this field only if you plan to manage motion overlays via the REST API, after this initial setup via the web interface. Typically, you will want this tag to be true. | 

**Action time formats**

**Option 1: ** Timecode format (HH:MM:SS:FF). 

The value to enter for HH:MM:SS:FF depends on the method used to calculate the *output timecode*. This method is specified in the **Timecode Configuration > Source** field. Identify the source method set for your event, then set the action time to match the timecode of the frame where you want the action to occur.
+ If **Source** is **Embedded**: The output timecode is extracted from the timecode that is 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. For example, 10:24:25:20, 10:24:25:21, and so on.
+  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. For example, 00:00:00;01: 00;00:00:02, and so on.
+ If **Source** is **System Clock **or **Local System Clock**: 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. For example, if the first frame is decoded at 09:45:51, then that timecode is 09:45:51:01. The timecode for the next frame is 09:45:51:02, and so on.
+ 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. For example, if you set the time to 15:30;00, then the timecode for the first frame is 15;30:00:01, and so on. 
+ If **Source** is **External Reference Connector**: 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. For example, the timecode for the first frame is 20:03:19:01, then 20:03:19:01, and so on.

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

**Option 3:** You can only use this option while adding or modifying a motion overlay in a running event. Set the `action_time` 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. 

# Step C: Manage the motion overlay on a running event
<a name="png-step-manage-the-overlay-on-a-running-event"></a>

After the event starts, the motion overlay configured in the event runs at the specified time. When the event is running, you can work with the motion overlay only via the REST API. You can enter REST API commands to make the following changes:
+ A different URL, to specify different content.
+ A start time, the new position and size, and the specified loop behavior.

**Note**  
Commands sent during an event change the event XML. Therefore, if you export the XML and create a new event with it, the new event will have any motion overlays set up as they were set during the course of the event, not as they were when the event was created. 

**To modify the motion overlay on a running event**

1. Decide which fields you want to modify. For information about the types of changes that you can make, see [Fields for a PNG asset](png-set-up-event-fields.md).

1. Enter a POST command to modify any of the image overlay parameters in the running event:

   ```
   POST http://<Live IP Address>/live_events/<live event id>/motion_image_inserter
   ```

1. In the body of the request, include one **motion\$1image\$1inserter** element that contains the required tags. For more information about the tags, see [Using the REST API](png-set-up-event-fields-api.md). 

1. The response repeats back the data that you posted with `<ID>` tags for `motion_image_inserter` and `motion_image_inserter_input`. 

****Example 1****  
The following example request modifies the running event with the ID 33. It sets up the currently defined motion overlay png to run again at 20160102T030405.678Z.

```
POST http://198.51.100.22/live_events/33/motion_image_inserter
-------------------------------------------------------------
<motion_image_inserter>
    <action_time>20160102T030405.678Z</action_time>
    <active>true</active>
</motion_image_inserter>
```

****Example 2****  
The following example request modifies the running event with the ID 33. It stops the motion overlay. Notice that you include `<action_time>` with an empty value so that you clear the time currently specified in the XML. If you forget to do this, Elemental Live might try to apply that time to the next show/hide request.

```
POST http://198.51.100.22/live_events/33/motion_image_inserter
-------------------------------------------------------------
<motion_image_inserter>
    <action_time></action_time>
    <active>false</active>
</motion_image_inserter>
```

**Types of changes**

This table provides information about some of the changes you can make to a running event in the REST API:


| State of motion overlay | Desired action | How to use the `motion_image_inserter` command | Tags to change | 
| --- | --- | --- | --- | 
| Not running | Run the motion overlay immediately | Enter the command to set the active tag to true and set the <action\$1time> tag to empty. | active`action_time` | 
| Not running | Run the motion overlay again at a specified time | Enter the command to set the active tag to true and set the <action\$1time> tag to the desired start time. | active`action_time` | 
| Not running | Run a different motion overlay of the same file type. |  Enter the command to change the motion overlay to point to a different asset.  Set the `<active>` tag to `true` and set the `<action_time>` tag to the time you want the start the new motion overlay. Set the `<loop>` tag to `true` or `false`.  | All tags that apply to the current motion overlay type. | 
| Running | Stop the running motion overlay | Just before you want the motion overlay to stop, enter the command to set the active tag to false. | active | 
| Running | Start the motion overlay |  To start the motion overlay again, enter the command to set the `<active>` tag to `true` and the `<action_time>` tag set to the time you want the motion overlay to begin.  | active | 
| Running | Change to a different motion overlay. | Enter the command to change the motion overlay to a different file. | All tags, not just the ones you want to change. If you exclude a tag, the default value will apply. | 

# Step D: Run the event again
<a name="png-step-run-again"></a>

You might want to run the same event again. If you do so, make sure that the motion overlay is set up correctly. You must do this because when you enter REST API commands to control the motion overlay when the event is running, the event XML for the motion overlay changes.

For example, you might set up the event with motion overlay A and a start time of 9:00 am. You then run the event and change the content and start time of the motion overlay several times. The last motion overlay to run in the event is motion overlay B with a start time of 4:00 pm. That is the information now in the event XML. Before you start the event the next day, review and modify the motion overlay information.