# How to insert a motion overlay with a set of PNG files
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
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
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
**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
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_events
```
```
PUT http:///live_events/
```
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).
```
```
1. The response repeats back the data that you posted with `` 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
-----------------------------------
myLiveEvent
. . .
10:16:23:10
true
true
1001
30000
false
100
200
png
true
/data/logo001.png
```
# Fields for a PNG asset
| Field on web interface | Tag in the XML | Type | Description |
| --- | --- | --- | --- |
| Insertion Mode | | String | Choose png. |
| Input | | 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 | | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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
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_events//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 `` 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
-------------------------------------------------------------
20160102T030405.678Z
true
```
****Example 2****
The following example request modifies the running event with the ID 33. It stops the motion overlay. Notice that you include `` 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
-------------------------------------------------------------
false
```
**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 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 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 `` tag to `true` and set the `` tag to the time you want the start the new motion overlay. Set the `` 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 `` tag to `true` and the `` 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
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.