Publisher Extension

OvenMediaEngine의 다양한 Publisher를 활용해 서비스를 운영하는 사용자에게 도움이 될 수 있는 Publisher Extension 기능들을 소개합니다.

#1. 모든 Publishers

Stream에 Delay 추가하기

Stream Delay 기능을 사용하면 모든 <Publishers>에 Latency를 강제로 추가 할 수 있습니다. 이 기능은 라이브 서비스 운영 시 돌발 상황에 대처하는 데 도움이 될 수 있습니다.

다음과 같이 Server.xml 에서 <Publishers><DelayBufferTimeMs> 값을 설정하십시오:

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
  ...
  <VirtualHosts>
    <VirtualHost>
      <Applications>
        <Application>
          <Publishers>
            ...
            <!-- milliseconds -->
            <DelayBufferTimeMs>10000</DelayBufferTimeMs>
            ...
          </Publishers>
        </Application>
      </Applications>
    </VirtualHost>
  </VirtualHosts>
</Server>

#2. (LL)-HLS와 WebRTC

기본 Playlist 생성 제어하기

사용자는 각 재생 프로토콜 (LL-HLS, Legacy HLS, WebRTC)이 기본적으로 생성하는 Playlist (llhls, playlist, webrtc)의 생성 여부를 제어하고 싶은 경우, <CreateDefaultPlaylist> 옵션을 사용하여 시스템을 보다 용이하게 관리할 수 있습니다.

Server.xml 내 <Publishers><LLHLS><CreateDefaultPlaylist> ( 또는 <Publishers><HLS><CreateDefaultPlaylist>, 또는 <Publishers><WebRTC><CreateDefaultPlaylist>)에서 다음과 같이 설정하여 사용할 수 있습니다:

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
  ...
  <VirtualHosts>
    <VirtualHost>
      <Applications>
        <Application>
          <Publishers>
            ...
            <LLHLS>
              <CreateDefaultPlaylist>true</CreateDefaultPlaylist>
            </LLHLS>
          </Publishers>
        </Application>
      </Applications>
    </VirtualHost>
  </VirtualHosts>
</Server>

Element

Value

Description

CreateDefaultPlaylsit

true | false * Default: ture

각 Publisher 내 <CreateDefaultPlaylist>를 false로 설정하면, 기본 Playlist가 생성되지 않습니다.

#3. (LL)-HLS

Origin 이중화 설정하기

OvenMediaEngine의 Low-Latency HLS Origin Server (또는 HLS Origin Server)를 이중화로 구성하는 경우, Origin 이중화 설정을 통해 Primary Origin Server와 Secondary Origin Server의 Segment 파일명을 동일하게 만들 수 있습니다. 이를 통해, Edge Server 또는 CDN Cache Server는 Primary Origin Server에 장애가 발생하면 Primary Origin Server 대신 Secondary Origin Server를 연결하여 동일한 콘텐츠를 다운로드 받을 수 있습니다.

다음과 같이 Server.xml에서 <Publishers><LLHLS><ServerTimeBasedSegmentNumbering> ( 또는 <Publishers><HLS><ServerTimeBasedSegmentNumbering>)을 활성화 하십시오:

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
  ...
  <VirtualHosts>
    <VirtualHost>
      <Applications>
        <Application>
          <Publishers>
            ...
            <LLHLS>
              <ServerTimeBasedSegmentNumbering>true</ServerTimeBasedSegmentNumbering>
            </LLHLS>
          </Publishers>
        </Application>
      </Applications>
    </VirtualHost>
  </VirtualHosts>
</Server>

이 기능은 서버 시간을 기준으로 Segment 파일명을 생성하므로 Primary Origin Server와 Secondary Origin Server의 시간을 동기화 해야 합니다.

Default Query String 사용하기

사용자는 Low-Latency HLS (또는 Legacy HLS)의 기본 동작 방식을 <DefaultQueryString>을 통해 제어 할 수 있습니다.

다음과 같이 Server.xml의 <Publishers><LLHLS><DefaultQueryString> (또는 <Publishers><HLS><DefaultQueryString>)에서 설정 할 수 있습니다:

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
  ...
  <VirtualHosts>
    <VirtualHost>
      <Applications>
        <Application>
          <Publishers>
            ...
            <LLHLS>
              <DefaultQueryString>
		        <Query>
				  <Key>_HLS_legacy</Key>
				  <Value>NO</Value>
		        </Query>
		        <Query>
				  <Key>_HLS_rewind</Key>
				  <Value>YES</Value>
			    </Query>
			  </DefaultQueryString>
            </LLHLS>
          </Publishers>
        </Application>
      </Applications>
    </VirtualHost>
  </VirtualHosts>
</Server>

Playback URL에 이미 Query 문자열이 추가 되어 있는 경우 이 설정은 무시됩니다.

Key

Value

Description

_HLS_legacy

YES | NO * Default: NO

_HLS_legacy 값을 YES로 설정하면, LL-HLS Playlist 내에 Partial Segment 정보를 제거하여 Legacy HLS (HLSv6 등)와 동일하게 동작합니다. * LL-HLS Only

_HLS_rewind

YES | NO * Default: YES

_HLS_rewind 값이 YES로 설정되어 있고 기능이 활성화 된 경우, Playlist 내에 이전 Segment 정보가 포함됩니다.

Query String 승계하기

사용자가 <PropagateQueryString> 을 활성화하면, 최초 Master Playlist 요청에 포함된 Query String이 하위 모든 요청 (Media Playlist, Segment, Partial Segment)에 자동으로 포함됩니다. Query String에 Session Key, Authentication Token 등을 포함시켜 이 기능을 활용한다면, 모든 요청을 CDN에서 검사할 수 있기 때문에 콘텐츠 접근 제어가 용이합니다.

다음과 같이 Server.xml의 <Publishers><LLHLS><PropagateQueryString> (또는 <Publishers><HLS><PropagateQueryString>)에서 설정 할 수 있습니다:

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
  ...
  <VirtualHosts>
    <VirtualHost>
      <Applications>
        <Application>
          <Publishers>
            ...
            <LLHLS>
              <OriginMode>true</OriginMode>
              <PropagateQueryString>true</PropagateQueryString>
            </LLHLS>
          </Publishers>
        </Application>
      </Applications>
    </VirtualHost>
  </VirtualHosts>
</Server>

Query String에 민감한 정보를 직접 포함시키지 않도록 주의가 필요합니다.

Cache 유효성 검사

이 기능을 활성화 하면 캐시된 리소스 버전이 OvenMediaEngine의 리소스와 동일한지 여부를 식별 할 수 있습니다. HTTP 요청에 If-None-Match: "<etag_value>" 헤더가 포함되어 있을 때 OvenMediaEngine의 리소스 Etag 와 비교하여 값이 일치 할 경우 304 Not-Modified를 반환합니다.

다음과 같이 Server.xml의 <Modules><ETag>에서 활성화 할 수 있습니다.

<Server>
  <Modules>
    <ETag>
      <Enable>true</Enable>
    </ETag>
  </Modules>
</Server>

활성화 시 모든 HTTP 응답에 Etag 헤더가 추가됩니다.

#4. LL-HLS

Origin Cache 제어하기

HTTP Response에 Cache-Control Header를 추가하여 Edge Server 또는 CDN Cache Server에서 콘텐츠를 Cache에 보관하는 시간을 지정 할 수 있습니다.

다음과 같이 Server.xml의 <Publishers><LLHLS><CacheControl>에서 설정 할 수 있습니다:

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
  ...
  <VirtualHosts>
    <VirtualHost>
      <Applications>
        <Application>
          <Publishers>
            ...
            <LLHLS>
              <OriginMode>true</OriginMode>
              <CacheControl>
                <MasterPlaylistMaxAge>0</MasterPlaylistMaxAge>
                <ChunklistMaxAge>0</ChunklistMaxAge>
                <ChunklistWithDirectivesMaxAge>60</ChunklistWithDirectivesMaxAge>
                <SegmentMaxAge>-1</SegmentMaxAge>
                <PartialSegmentMaxAge>-1</PartialSegmentMaxAge>
              </CacheControl>
            </LLHLS>
          </Publishers>
        </Application>
      </Applications>
    </VirtualHost>
  </VirtualHosts>
</Server>

Element

Description

MasterPlaylistMaxAge

Master Playlist의 max-age를 지정합니다. 이것은 Stream이 생성되어 있는 동안 변경되지 않습니다.

ChunklistMaxAge

Media Playlist의 max-age를 지정합니다. 이것은 항상 최신 상태의 Media Playlist를 응답해야 하는 URL이며 LL-HLS의 Delivery Directives가 없습니다. 따라서 이것은 가능한 짧게 Cache하거나 또는 Cache하지 않아야 합니다.

ChunklistWithDirectivesMaxAge

가 포함 된 Media Playlist의 max-age를 지정합니다. 현재 지원되는 Delivery Directives는 _HLS_msn과 _HLS_part입니다. 이것은 Segment 번호와 Partial Segment 번호가 지정된 Playlist이며, 이 URL은 Stream이 생성되어 있는 동안 유일하며, 같은 URL의 콘텐츠는 변경되지 않기 때문에 오랜 시간 Cache할 수 있습니다.

SegmentMaxAge

Segment File의 max-age를 지정합니다. Segment File의 URL은 Stream이 생성되어 있는 동안 유일하며, 같은 URL의 콘텐츠는 변경되지 않기 때문에 오랜 시간 Cache할 수 있습니다.

PartialSegmentMaxAge

Partial Segment File의 max-age를 지정합니다. Partial Segment File의 URL은 Stream이 생성되어 있는 동안 유일하며, 같은 URL의 콘텐츠는 변경되지 않기 때문에 오랜 시간 Cache할 수 있습니다.

`<CacheControl>` Element의 의미

Element

Description

CacheControl: no-cache, no-store

콘텐츠를 절대 캐시하지 말 것을 지시하여 매 요청마다 새로운 데이터를 Server에서 받아옵니다.

양수 (0 초과)

CacheControl: max-age=<seconds>

지정된 시간 동안 Cache가 유효하도록 지시합니다.

-1

CacheControl 헤더 미포함

Origin에서 명시적인 Cache Header를 보내지 않도록 지시합니다. 이 값을 통해 Cache를 사용하지 않거나, CDN이나 Cache 서버의 자체 정책을 적용하거나, Client나 Browser의 기본 Cache 동작을 따를 수 있습니다.

<CacheControl>에 0 값 사용 시 서버 부하가 증가할 수 있고, -1 값 사용 시 예상치 못한 캐싱 동작이 발생할 수 있으므로 테스트가 필요합니다.

#5. HLS

광고 마커(EXT-X-CUE-OUT/EXT-X-CUE-IN) 삽입하기

REST API를 사용하여 HLS playlist 내에 동적으로 광고 마커를 삽입 할 수 있습니다.

CUE-OUT 이벤트를 호출하게 되면 playlist 내에 아래와 같이 태그가 추가됩니다.

#EXT-X-CUE-OUT:DURATION=<time>
…
#EXT-X-CUE-IN

#EXT-X-CUE-OUT과 #EXT-X-CUE-IN은 한쌍이며, 두 태그 사이의 전체 섹션은 광고 서버에 의해 광고 컨텐츠로 대체됩니다.

DURATION=<time> 은 필수이며, 광고의 유지 시간을 나타냅니다.

CUE-IN 이벤트를 호출하여 삽입된 광고를 조기에 종료 할 수 있습니다. 이벤트 호출 시 playlist 내에 #EXT-X-CUE-IN 태그가 즉시 추가되며 기존에 추가되어 있던 #EXT-X-CUE-IN 태그는 삭제됩니다.

API Interface

Request

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

Header

Authorization: Basic {credentials}

# Authorization
Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{
  "eventFormat": "cue",
  "events":[
    {
      "cueType": "out", // out | in
      "duration": 60500 // milliseconds, only available when cueType is out
    }
  ]
}

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

Header

Authorization: Basic {credentials}

# Authorization
Credentials for HTTP Basic Authentication created with <AccessToken>

Body

[
  {
    "eventFormat": "id3v2",
    "eventType": "video", // "eventTarget": "video" is same
    "events":[
      {
        "frameType": "TXXX",
        "info": "AirenSoft",
        "data": "OvenMediaEngine"
      },
      {
        "frameType": "TIT2",
        "data": "OvenMediaEngine 123"
      }
    ]
  },
  {
    "eventFormat": "cue",
    "events":[
      {
        "cueType": "out", // out | in
        "duration": 60500 // milliseconds, only available when cueType is out
      }
    ]
  }
]

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

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

400 Bad Request

Invalid request. Body is not a Json Object or does not have a required value

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or application name could not be found.

Body

{
    "message": "[HTTP] Could not find the application: [default/app2] (404)",
    "statusCode": 404
}

PreviousRestart Application | 0.17.0.0+NextRTMP Authentication | 0.17.2.0+

Last updated 19 days ago

#1. 모든 Publishers

Stream에 Delay 추가하기

#2. (LL)-HLS와 WebRTC

기본 Playlist 생성 제어하기

#3. (LL)-HLS

Origin 이중화 설정하기

Default Query String 사용하기

Query String 승계하기

Cache 유효성 검사

#4. LL-HLS

Origin Cache 제어하기

<CacheControl> Element의 의미

#5. HLS

광고 마커(EXT-X-CUE-OUT/EXT-X-CUE-IN) 삽입하기

API Interface

`<CacheControl>` Element의 의미