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