Image Overlay

OvenMediaEngine Enterprise 0.19.1.0-1 버전부터 Image Overlay 기능을 지원합니다.

Image Overlay 기능은 Stream Video 위에 Logo, Watermark, Banner 등 시각 요소를 실시간으로 겹쳐 표시할 수 있도록 합니다. 운영자는 REST API 또는 XML 설정을 통해 Overlay를 추가·수정·삭제할 수 있으며, 각 요소의 좌표 (위치), 크기, 투명도를 세밀하게 제어할 수 있습니다. 캠페인 교체, 긴급 안내, 브랜드 강화, 시각 정보 제공 등 다양한 활용 시나리오를 간결한 방식으로 지원합니다.

• 지원하는 Format: PNG (Alpha 지원), JPEG

• Image 연동 방법: http, https, file URI 방식

기본 Overlay 설정하기 (XML)

Server.xml에 Image Overlay 기능이 활성화되면 OvenMediaEngine Enterprise 재시작 없이 새로운 Stream부터 자동으로 반영됩니다. 아래 내용을 참고하여 XML을 설정하십시오.

Server.xml 설정

Server.xml 내 <Application><OutputProfiles><MediaOptions><Overlays>에서 다음과 같이 설정하여 사용할 수 있습니다:

<?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	Overlay 기능을 활성화할지 여부를 설정합니다.
Path	-	Overlay 설정 정보가 담긴 XML 파일 경로를 지정합니다. * OverlayInfo.xml 파일은 아래 예제 참조.

OverlayInfo.xml 설정 예제:

<?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	Image Overlay 기능을 활성화할지 여부를 설정합니다.
OutputStreamName	-	Image Overlay 기능을 사용할 Output Stream을 지정합니다. * Wildcard Character (*)로 매칭하여 Stream 선택 가능.
VariantNames	-	지정한 Output Stream 내 Image Overlay를 적용할 하나 이상의 Track을 선택하는 Option입니다. Track을 지정하지 않은 경우 모든 Video Track이 선택됩니다. * Wildcard Character (*)로 매칭하여 Track 선택 가능. * 여러 Track을 선택할 경우 Comma (,)로 구분하여 사용.
Url	-	Overlay로 출력할 Image File의 URL (Path)입니다. * 지원하는 Schema: http, https, file * Configuration File 경로 기준 상대 경로 지정 가능.
Left, Top, Width, Height	-	Overlay로 출력될 Image의 좌표 (위치)와 크기를 설정합니다. * 원본 Frame Size Macro: MAIN_W, MAIN_H * Overlay Image Size Macro: OVER_W, OVER_H * +, -, *, /, () 수식을 사용하여 설정 가능.
Opacity	0-100	Overlay로 출력될 Image의 투명도를 설정합니다. * 0에 가까울 수록 투명, 100에 가까울 수록 불투명.

실시간 Overlay 사용하기 (REST API)

REST API를 사용하여 특정 Stream 및 특정 Stream 내 Track에 Overaly를 실시간으로 적용하거나 해제합니다. 사용되는 Option과 Parameter는 위 XML 설정과 동일합니다.

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 (XML과 동일)

Element	Value	Description
Enable	true | false	Image Overlay 기능을 활성화할지 여부를 설정합니다.
OutputStreamName	-	Image Overlay 기능을 사용할 Output Stream을 지정합니다. * Wildcard Character (*)로 매칭하여 Stream 선택 가능.
VariantNames	array	지정한 Output Stream 내 Image Overlay를 적용할 하나 이상의 Track을 선택하는 Option입니다. Track을 지정하지 않은 경우 모든 Video Track이 선택됩니다. * Wildcard Character (*)로 매칭하여 Track 선택 가능. * 여러 Track을 선택할 경우 Comma (,)로 구분하여 사용.
Url	-	Overlay로 출력할 Image File의 URL (Path)입니다. * 지원하는 Schema: http, https, file * Configuration File 경로 기준 상대 경로 지정 가능.
Left, Top, Width, Height	-	Overlay로 출력될 Image의 좌표 (위치)와 크기를 설정합니다. * 원본 Frame Size Macro: MAIN_W, MAIN_H * Overlay Image Size Macro: OVER_W, OVER_H * +, -, *, /, () 수식을 사용하여 설정 가능.
Opacity	0-100	Overlay로 출력될 Image의 투명도를 설정합니다. * 0에 가까울 수록 투명, 100에 가까울 수록 불투명.

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
}

Overlay 제거하기

특정 Stream 및 특정 Stream 내 Track에 적용된 모든Overlay를 삭제합니다.

Request

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

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

Configuration Parameters (XML과 동일)

Element	Value	Description
OutputStreamName	-	Image Overlay 기능을 해제할 Output Stream을 지정합니다. * Wildcard Character (*)로 매칭하여 Stream 선택 가능.
VariantNames	array	지정한 Output Stream 내 Image Overlay를 해제할 하나 이상의 Track을 선택하는 Option입니다. Track을 지정하지 않은 경우 모든 Video Track이 선택됩니다. * Wildcard Character (*)로 매칭하여 Track 선택 가능. * 여러 Track을 선택할 경우 Comma (,)로 구분하여 사용.

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
}

Overlay 활용 예제

아래는 수치를 직접 기입하여 사용하거나, Macro와 수식을 활용한 예제입니다.

#01. Image Size를 지정하고 Screen 좌측 상단에 Overlay.

• 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. 원본 Image를 Screen 중앙에 Overlay.

• Size: 원본

• 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. Image Size를 50%로지정하고 Screen 우측 상단에 Overlay.

• Size: ½ (원본에서 절반)

• 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>
...