Image Overlay

OvenMediaEngine Enterprise supports the Image Overlay feature starting with version 0.19.1.0-1.

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

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

{
    "message": "OK",
    "statusCode": 200
}

400 Bad Request

Header

Content-Type: application/json

Body

{
    "message": "Could not parse json context",
    "statusCode": 400
}

{
    "message": "No required parameters",
    "statusCode": 400
}

404 Not Found

Header

Content-Type: application/json

Body

{
    "message": "Could not found output stream",
    "statusCode": 404
}

{
    "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

{
    "message": "OK",
    "statusCode": 200
}

400 Bad Request

Header

Content-Type: application/json

Body

{
    "message": "Could not parse json context",
    "statusCode": 400
}

{
    "message": "No required parameters",
    "statusCode": 400
}

404 Not Found

Header

Content-Type: application/json

Body

{
    "message": "Could not found output stream",
    "statusCode": 404
}

{
    "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>
...

PreviousRecording Delivery NextHardware Encoder Support

Last updated 1 day ago

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.

Configuring Image Overlays in `Server.xml`

`OverlayInfo.xml` Configuration Example: