# Image Overlay

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

* **지원하는 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
<?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>
```

<table><thead><tr><th width="156">Element</th><th width="135">Value</th><th>Description</th></tr></thead><tbody><tr><td>Enable</td><td>true | false</td><td>Overlay 기능을 활성화할지 여부를 설정합니다.</td></tr><tr><td>Path</td><td>-</td><td>Overlay 설정 정보가 담긴 XML 파일 경로를 지정합니다.<br><mark style="color:orange;">* <code>OverlayInfo.xml</code> 파일은 아래 예제 참조.</mark></td></tr></tbody></table>

#### `OverlayInfo.xml` 설정 예제:

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

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

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

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

### Overlay 적용하기

> **Request**

<details>

<summary><mark style="color:blue;">POST</mark> /v1/vhosts{vhost}/apps/{app}/streams/{stream}:startOverlay</summary>

```json
// 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과 동일)

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

</details>

> **Responses**

<details>

<summary><mark style="color:blue;">200</mark> OK</summary>

**Header**

```http
Content-Type: application/json
```

**Body**

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "message": "OK",
    "statusCode": 200
}
</code></pre>

</details>

<details>

<summary><mark style="color:red;">400</mark> Bad Request</summary>

**Header**

```http
Content-Type: application/json
```

**Body**

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "message": "Could not parse json context",
    "statusCode": 400
}
</code></pre>

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "message": "No required parameters",
    "statusCode": 400
}
</code></pre>

</details>

<details>

<summary><mark style="color:red;">404</mark> Not Found</summary>

**Header**

```http
Content-Type: application/json
```

**Body**

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "message": "Could not found output stream",
    "statusCode": 404
}
</code></pre>

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "message": "Could not found track by variant",
    "statusCode": 404
}
</code></pre>

</details>

### Overlay 제거하기

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

> **Request**

<details>

<summary><mark style="color:blue;">POST</mark> /v1/vhosts{vhost}/apps/{app}/streams/{stream}:stopOverlay</summary>

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

#### Configuration Parameters (XML과 동일)

<table><thead><tr><th width="156">Element</th><th width="135">Value</th><th>Description</th></tr></thead><tbody><tr><td>OutputStreamName</td><td>-</td><td>Image Overlay 기능을 해제할 Output Stream을 지정합니다.<br><mark style="color:yellow;">* Wildcard Character (<code>*</code>)로 매칭하여 Stream 선택 가능.</mark></td></tr><tr><td>VariantNames</td><td>array</td><td><p>지정한 Output Stream 내 Image Overlay를 해제할 하나 이상의 Track을 선택하는 Option입니다. Track을 지정하지 않은 경우 모든 Video Track이 선택됩니다.<br><mark style="color:yellow;">* Wildcard Character (<code>*</code>)로 매칭하여 Track 선택 가능.</mark></p><p><mark style="color:yellow;">* 여러 Track을 선택할 경우 Comma (<code>,</code>)로 구분하여 사용.</mark></p></td></tr></tbody></table>

</details>

> **Responses**

<details>

<summary><mark style="color:blue;">200</mark> OK</summary>

**Header**

```http
Content-Type: application/json
```

**Body**

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "message": "OK",
    "statusCode": 200
}
</code></pre>

</details>

<details>

<summary><mark style="color:red;">400</mark> Bad Request</summary>

**Header**

```http
Content-Type: application/json
```

**Body**

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "message": "Could not parse json context",
    "statusCode": 400
}
</code></pre>

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "message": "No required parameters",
    "statusCode": 400
}
</code></pre>

</details>

<details>

<summary><mark style="color:red;">404</mark> Not Found</summary>

**Header**

```http
Content-Type: application/json
```

**Body**

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "message": "Could not found output stream",
    "statusCode": 404
}
</code></pre>

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "message": "Could not found track by variant",
    "statusCode": 404
}
</code></pre>

</details>

## Overlay 활용 예제

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

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

* Size: 500\*250
* Opacity: 70

```xml
...          
  <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>
...
```

<figure><img src="https://2184736704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ6NWzeQyKbSWkDFSGwGx%2Fuploads%2Fy41Rz68VTS7kf3HvoOi9%2Fimage.png?alt=media&#x26;token=19509290-3dd1-4c16-81ce-dc4a7e82a73d" alt=""><figcaption></figcaption></figure>

#### #02. 원본 Image를 Screen 중앙에 Overlay.

* Size: 원본
* Opacity: 100

```xml
...          
  <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>
...
```

<figure><img src="https://2184736704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ6NWzeQyKbSWkDFSGwGx%2Fuploads%2FWgx1j65hjoi4vf70wIds%2Fimage.png?alt=media&#x26;token=08493680-b445-40cc-9432-4e7db00ce629" alt=""><figcaption></figcaption></figure>

#### #03. Image Size를 50%로지정하고 Screen 우측 상단에 Overlay.

* Size: ½ (원본에서 절반)
* Opacity: 100

```xml
...          
  <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>
...
```

<figure><img src="https://2184736704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ6NWzeQyKbSWkDFSGwGx%2Fuploads%2FVunECHr1cCtUWkKF9OOo%2Fimage.png?alt=media&#x26;token=f5b7540d-0688-42be-b511-36e14db07cab" alt=""><figcaption></figcaption></figure>