Image Overlay

The Image Overlay feature lets you superimpose visual elements such as logos, watermarks, and banners on top of a stream in real-time. You can add, modify, or clear overlays through the REST API or XML configuration, and precisely control each element’s position, size, and opacity. It provides a simple way to handle scenarios like campaign swaps, emergency notices, brand reinforcement, on-screen information, and more.

Supported formats: PNG (with alpha), JPEG
Image source URI schemes: http, https, file

Image Overlay Configuration (XML)

When the Image Overlay feature is enabled in Server.xml, changes are applied automatically to new streams without restarting OvenMediaEngine Enterprise. Configure the XML as follows.

Configuring Image Overlays in `Server.xml`

In Server.xml, configure <Application><OutputProfiles><MediaOptions><Overlays> as below:

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
  ...
  <VirtualHosts>
    <VirtualHost>
      <Applications>
        <Application>
          <OutputProfiles>
            <MediaOptions>
              <Overlays>
                <Enable>true</Enable>
                <Path>overlay/OverlayInfo.xml</Path>
              </Overlays>
            </MediaOptions>
            ...
          </OutputProfiles>
          ...
        </Application>
      </Applications>
    </VirtualHost>
  </VirtualHosts>
</Server>

Element	Value	Description
Enable	true \| false	Enables or disables the overlay feature.
Path	-	Specifies the path to the XML file that contains the overlay settings. * Please see the `OverlayInfo.xml` example below.

`OverlayInfo.xml` Configuration Example:

<?xml version="1.0" encoding="UTF-8"?>
<OverlayMap>
  <OverlayInfo>
    <Enable>true</Enable>
    <OutputStreamName>stream1*</OutputStreamName>                 <!-- Must -->
    <VariantNames>*_1080p,*_720p</VariantNames>                   <!-- Optional -->
    <Overlay>
      <Url>http://ovenmediaengine.com/overlay/image001.png</Url>  <!-- Must -->
      <Left>10</Left>                                             <!-- Optional -->
      <Top>10</Top>                                               <!-- Optional -->
      <Width>64</Width>                                           <!-- Optional -->
      <Height>64</Height>                                         <!-- Optional -->
      <Opacity>50</Opacity>                                       <!-- Optional -->
    </Overlay>
    <Overlay>
      <Url>http://ovenmediaengine.com/overlay/image002.png</Url>  
      <Left>(MAIN_W - OVER_W)/2</Left> 
      <Top>(MAIN_H - OVER_H)/2</Top>                              
      <Width>OVER_W/10</Width>                                    
      <Height>OVER_H/10</Height>                                  
      <Opacity>50</Opacity>                                       
    </Overlay>
  </OverlayInfo>

  <OverlayInfo>
    <Enable>true</Enable>
    <OutputStreamName>stream2*</OutputStreamName>               
    <VariantNames>h264_1080p</VariantNames>                       
    <Overlay>
      <Url>overlay/image003.png</Url> 
      <Left>10</Left>                              
      <Top>10</Top>                                
      <Width>64</Width>                            
      <Height>64</Height>                          
      <Opacity>50</Opacity>                        
    </Overlay>
  </OverlayInfo>  
  ...
  <OverlayInfo>
  </OverlayInfo>
  ...
</OverlayMap>

Element	Value	Description
Enable	true \| false	Enables or disables the imgae overlay feature.
OutputStreamName	-	Specifies the output stream that will use the image overlay. * Select streams using the wildcard character (`*`).
VariantNames	-	Option to select one or more tracks within the output stream for the image overlay. If omitted, the overlay applies to all video tracks in the output stream. * Select tracks using the wildcard character (``). Separate multiple tracks with commas (`,`).
Url	-	URL (path) of the image file to render as the overlay. * Supported URI schemes: `http`, `https`, `file` * Relative paths are supported and are resolved relative to the configuration file’s location.
Left, Top, Width, Height	-	Sets the position and size of the overlay image. * Original frame size macros: `MAIN_W`, `MAIN_H` * Overlay image size macros: `OVER_W`, `OVER_H` * Values accept arithmetic expressions: `+`, `-`, `*`, `/`, `()`
Opacity	0-100	Sets the opacity of the overlay image. * Closer to `0` means more transparent; closer to `100` means more opaque.

Using Image Overlay in Real-Time (REST API)

You can use the REST API to add, update, or clear overlays on a specific stream or on a track(s) within the stream in real-time. The available options and parameters are identical to those in the XML configuration above.

Add Image Overlay

Request

POST /v1/vhosts{vhost}/apps/{app}/streams/{stream}:startOverlay

// Insert & Update Image
{
  "outputStreamName": "stream",
  "variantNames": ["video_1080","video_720"],
  "overlays" : [
       {
          "url": "http://ovenmediaengine.com/overlay/image001.png",
          "left": "10",
          "top": "10",
          "width": "180",
          "height": "64",  
          "opacity": 50
      },
      {
          "url": "overlay/image003.png",
          "left": "(MAIN_W - OVER_W)/2",
          "top": "(MAIN_H - OVER_H)/2",
          "width": "OVER_W/2",
          "height": "OVER_H/2",  
          "opacity": 50
      } 
  ]
}

Configuration Parameters (same as in the XML configuration)

Element	Value	Description
Enable	true \| false	Enables or disables the imgae overlay feature.
OutputStreamName	-	Specifies the output stream that will use the image overlay. * Select streams using the wildcard character (`*`).
VariantNames	array	Option to select one or more tracks within the output stream for the image overlay. If omitted, the overlay applies to all video tracks in the output stream. * Select tracks using the wildcard character (``). Separate multiple tracks with commas (`,`).
Url	-	URL (path) of the image file to render as the overlay. * Supported URI schemes: `http`, `https`, `file` * Relative paths are supported and are resolved relative to the configuration file’s location.
Left, Top, Width, Height	-	Sets the position and size of the overlay image. * Original frame size macros: `MAIN_W`, `MAIN_H` * Overlay image size macros: `OVER_W`, `OVER_H` * Values accept arithmetic expressions: `+`, `-`, `*`, `/`, `()`
Opacity	0-100	Sets the opacity of the overlay image. * Closer to `0` means more transparent; closer to `100` means more opaque.

Responses

200 OK

Header

Content-Type: application/json

Body

<strong>{
</strong>    "message": "OK",
    "statusCode": 200
}

400 Bad Request

Header

Content-Type: application/json

Body

<strong>{
</strong>    "message": "Could not parse json context",
    "statusCode": 400
}

<strong>{
</strong>    "message": "No required parameters",
    "statusCode": 400
}

404 Not Found

Header

Content-Type: application/json

Body

<strong>{
</strong>    "message": "Could not found output stream",
    "statusCode": 404
}

<strong>{
</strong>    "message": "Could not found track by variant",
    "statusCode": 404
}

Clear Image Overlay

You can clear all overlays applied to a specific stream or to a track(s) within that stream using the REST API.

Request

POST /v1/vhosts{vhost}/apps/{app}/streams/{stream}:stopOverlay

// Clear Overlays
{
  "outputStreamName": "stream",
  "variantNames": ["video_1080","video_720"],
}

Configuration Parameters (same as in the XML configuration)

Element	Value	Description
OutputStreamName	-	Specifies the output stream for which to disable the image overlay. * Select streams using the wildcard character (`*`).
VariantNames	array	Option to select one or more tracks within the specified output stream for which to disable the image overlay. If omitted, the overlay applies to all video tracks in the output stream. * Select tracks using the wildcard character (``). Separate multiple tracks with commas (`,`).

Responses

200 OK

Header

Content-Type: application/json

Body

<strong>{
</strong>    "message": "OK",
    "statusCode": 200
}

400 Bad Request

Header

Content-Type: application/json

Body

<strong>{
</strong>    "message": "Could not parse json context",
    "statusCode": 400
}

<strong>{
</strong>    "message": "No required parameters",
    "statusCode": 400
}

404 Not Found

Header

Content-Type: application/json

Body

<strong>{
</strong>    "message": "Could not found output stream",
    "statusCode": 404
}

<strong>{
</strong>    "message": "Could not found track by variant",
    "statusCode": 404
}

Image Overlay Usage Examples

The examples below either use explicit values or leverage macros and expressions.

#01. Overlay an image with a fixed size at the top-left of the screen.

Size: 500*250
Opacity: 70

...          
  <Overlay>
    <Url>http://ovenmediaengine.com/overlay/ome.png</Url>  
    <Left>32</Left> 
    <Top>32</Top>                              
    <Width>500</Width>                                    
    <Height>250</Height>                                  
    <Opacity>70</Opacity>                    
    </Overlay>
...

#02. Overlay the original image centered on the screen.

Size: Original
Opacity: 100

...          
  <Overlay>
    <Url>http://ovenmediaengine.com/overlay/ome.png</Url>  
    <Left>MAIN_W/2 - OVER_W/2</Left> 
    <Top>MAIN_H/2 - OVER_H/2</Top>                              
    <Width>OVER_W</Width>                                    
    <Height>OVER_H</Height>                                  
    <Opacity>100</Opacity>                    
    </Overlay>
...

#03. Overlay the image at 50% size at the top-right of the screen.

Size: ½ (half of the original)
Opacity: 100

...          
  <Overlay>
    <Url>http://ovenmediaengine.com/overlay/ome.png</Url>  
    <Left>MAIN_W - (OVER_W/2) - 32</Left> 
    <Top>32</Top>                              
    <Width>OVER_W/2</Width>                                    
    <Height>OVER_H/2</Height>                                  
    <Opacity>100</Opacity>                    
    </Overlay>
...

Image Overlay Configuration (XML)​

Configuring Image Overlays in Server.xml​

OverlayInfo.xml Configuration Example:​

Using Image Overlay in Real-Time (REST API)​

Add Image Overlay​

Configuration Parameters (same as in the XML configuration)​

Clear Image Overlay​

Configuration Parameters (same as in the XML configuration)​

Image Overlay Usage Examples​

#01. Overlay an image with a fixed size at the top-left of the screen.​

#02. Overlay the original image centered on the screen.​

#03. Overlay the image at 50% size at the top-right of the screen.​

Image Overlay Configuration (XML)

Configuring Image Overlays in `Server.xml`

`OverlayInfo.xml` Configuration Example:

Using Image Overlay in Real-Time (REST API)

Add Image Overlay

Configuration Parameters (same as in the XML configuration)

Clear Image Overlay

Configuration Parameters (same as in the XML configuration)

Image Overlay Usage Examples

#01. Overlay an image with a fixed size at the top-left of the screen.

#02. Overlay the original image centered on the screen.

#03. Overlay the image at 50% size at the top-right of the screen.