Insert SEI into H.264 (AVC) Streams | v0.18.0.0+

OvenMediaEngine Enterprise 0.18.0.0-1 버전부터 SEI 삽입 기능을 지원합니다.

OvenMediaEngine은 Live Stream에 SEI (Supplemental Enhancement Information)를 삽입하여 Frame 단위의 정확도로 사용자 정의 데이터를 Video Content와 함께 전달할 수 있습니다.

개요

• OvenMediaEngine의 sendEvents API를 통해 동적으로, XML 설정을 통해 지속적으로 SEI를 삽입할 수 있습니다.

• SEI 삽입 시 사용자 정의 데이터를 추가할 수 있으며 삽입된 SEI에는 UUID와 Timestamp가 자동으로 포함됩니다.

  • 삽입된 SEI는 UUID, Timestamp, 사용자 데이터를 포함한 OvenMediaEngine 전용 포맷으로 생성됩니다.

• OvenPlayer는 OvenMediaEngine이 삽입한 SEI를 수신할 수 있으며 OvenMediaEngine이 정의한 SEI 규격을 자동으로 파싱하는 기능을 제공합니다.

Send Event API를 통한 SEI 삽입하기

API Interface

OvenMediaEngine의 SendEvent REST API를 사용하면 동적으로 Stream에 SEI를 삽입하는 Event를 발생시킬 수 있습니다.

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": "sei",
    "eventType": "video",
    "events": [
        {
            "seiType": "UserDataUnregistered",
            "data": "OvenMediaEngine"
        }
    ]
}

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

Header

Authorization: Basic {credentials}

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

Body

[
  {
      "eventFormat": "sei",
      "eventType": "video",
      "events": [
          {
              "seiType": "UserDataUnregistered",
              "data": "OvenMediaEngine"
          }
      ]
  }
]

Parameter	Required	Description
eventFormat	Y	Event 포맷을 지정합니다: sei 형식 사용.
eventType	N	Event 타입을 지정합니다. Default: video
events	Y	Event 데이터 값을 포함합니다.
event.seiType	N	SEI 타입을 지정합니다. Default: UserDataUnregistered
event.data	Y	실제 전송할 데이터를 입력합니다.

Responses

200 Ok

Header

Content-Type: application/json

Body

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

400 Bad Request

Header

Content-Type: application/json

Body

{
    "message": "eventFormat(string) and events(array) are required",
    "statusCode": 400
}

{
    "message": "eventFormat is not supported: [XXX]",
    "statusCode": 400
}

{
    "message": "Could not make events data",
    "statusCode": 400
}

{
    "message": "eventType must be string",
    "statusCode": 400
}

{
    "message": "eventType is not supported: [XXX]",
    "statusCode": 400
}

500 Internal Server Error

Header

Content-Type: application/json

Body

{
    "message": "Could not inject event: [XXX]",
    "statusCode": 500
}

XML설정을 통한 SEI 삽입하기

지속적인 SEI 삽입이 필요한 경우, XML 설정을 통해 동작을 구성할 수 있습니다. SEI 삽입 Event를 정의한 XML파일을 생성하고 Server.xml에서 EventGenerator를 활성화 합니다.

Configuration 예제

Server.xml: <Application><EventGenerator>를 추가하여 SEI 삽입을 위한 EventGenerator기능을 활성화 할 수 있습니다.

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
  ...
  <VirtualHosts>
    <VirtualHost>
      <Applications>
        <Application>
          ...
          <EventGenerator>
            <Enable>true</Enable>
            <Path>events/send_event_info.xml</Path>
          </EventGenerator>
        </Application>
      </Applications>
    </VirtualHost>
  </VirtualHosts>
</Server>

Element	Required	Description
<Enable>	Y	true 또는 false로 활성화 여부를 설정합니다. Default: false
<Path>	Y	세부 SEI 삽입을 정의한 XML 파일의 경로를 설정합니다. 상대 경로를 지정하면 Server.xml 파일이 있는 디렉토리가 기준이 됩니다.

SEI 삽입 Event를 정의한 XML: Server.xml에서 정의한 경로에 SEI 삽입 Event를 정의한 XML파일을 생성합니다. 아래 예제의 경우 send_event_info.xml입니다.

<?xml version="1.0" encoding="UTF-8"?>
<EventInfo>
  <Event>
    <Enable>true</Enable>
    <SourceStreamName>stream*</SourceStreamName>
    <Interval>2000</Interval>
    <EventFormat>sei</EventFormat>
    <EventType>video</EventType>
    <Values>
      <SeiType>UserDataUnregistered</SeiType>
      <Data>Hi! OvenMediaEngine! CurrentTime:${EpochTime}</Data>
      <KeyframeOnly>true</KeyframeOnly>
    </Values>
  </Event>
</EventInfo>

매개변수	Required	설명
<Enable>	Y	true 또는 false로 활성화 여부를 설정합니다. Default: false
<SourceStreamName>	Y	Event를 삽입할 Stream의 이름을 지정합니다. 패턴 매칭을 위한 Wildcard (*)를 지원합니다.
<Interval>	Y	Event 발생 주기를 밀리초 (ms) 단위로 설정합니다.
<EventFormat>	Y	Event 포맷을 지정합니다: sei 형식 사용.
<EventType>	N	Event 타입을 지정합니다. Default: video
<Values>	Y	Event 데이터 값을 포함합니다.
<Values><SeiType>	N	SEI 타입을 지정합니다. Default: UserDataUnregistered
<Values><Data>	Y	실제 전송할 데이터를 입력합니다. ${EpochTime}을 사용하여 밀리초 단위로 구성된 서버의 현재 Epoch Time으로 대체해서 전송할 수 있는 Macro를 지원합니다 (예시: 1747147513056).
<Values><KeyframeOnly>	N	Event 삽입 대상을 지정합니다. true인 경우 Interval 시간이 지난 후 첫번째 Keyframe에 Event가 삽입됩니다 (0.18.2.0+ 버전부터 지원). Default: false

이벤트 정의 XML 파일의 내용을 변경하면 OvenMediaEngine을 재시작하지 않아도 변경 사항이 바로 적용됩니다.

OvenMediaEngine-Specific SEI Payload Data 규격

OvenMediaEngine이 생성한 SEI의 Payload는 다음과 같은 구조로 UUID와Timestamp 값이 항상 포함되어 있습니다.

0                   1                   2                   3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| uuid_iso_iec_11578(128)                                       |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Timestamp (64)                                                |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Data (Payload Size - UUID(128) - Timestamp(64))               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ...                                                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Field	Size (bits)	Description
UUID	128	SEI Payload가 OvenMediaEngine이 정의한 규격임을 나타내는 값으로,항상 464d4c47-5241-494e-434f-4c4f554201입니다.
Timestamp	64	밀리초 (ms) 단위의 Epoch Time입니다.
Data	사용자 정의 데이터에 따라 다름	사용자 정의 데이터입니다.

SEI Data 수신

OvenPlayer는 OvenMediaEngine이 삽입한 SEI를 파싱해서 포함되어있는 UUID, TimeStamp, 사용자 정의 데이터를 Application에 전달할 수 있습니다.

Code 예제

var player = OvenPlayer.create('player', {
  sources: [
    {
      type: 'webrtc', // WebRTC 스트림 재생
      file: 'wss://[YOUR_OvenMediaEngine]:3333/app/stream'
    }
  ],
  parseStream: {
    enabled: true // H.264 NAL 파싱 활성화
  }
});

function toAsciiString(byteArray) {
  return String.fromCharCode.apply(null, byteArray);
}

player.on('metaData', function (metadata) {
  console.log('MetaData:', metadata);
  /* 출력:
    {
      type: 'sei',
      nalu: Unit8Array(33),
      sei: {
        type: 5,
        size: 39,
        payload: Unit8Array(39)
      },
      registered: true,
      uuid: '464d4c47-5241-494e-434f-4c4f-55524201',
      timecode: 1739851602778,
      userdata: Unit8Array(15)
    }
  */

  console.log(`사용자 데이터 문자열 변환: ${toAsciiString(metadata.userdata)}`);
  /* 출력:
    사용자 데이터 문자열 변환: OvenMediaEngine
  */
});

플레이어 초기화:

• OvenPlayer.create() 함수를 호출하여 지정된 div에 플레이어를 생성합니다.

• sources 배열에서 재생할 Stream의 유형과 URL을 지정합니다. SEI는 WebRTC Stream에서만 지원됩니다.

• parseStream.enabled: true 설정을 통해 H.264의 NAL (Network Abstraction Layer)파싱을 활성화합니다. 이는 SEI 메타데이터 처리를 위한 필수 설정입니다.

SEI 데이터 처리:

• player.on('metaData', callback) Event Listener를 등록하여 SEI가 수신될 때마다 처리합니다.

• Event Callback에 전달되는 Parameter에서 OvenMediaEngine이 삽입한 UUID, Timestamp, 사용자 정의데이터를 얻어올 수 있습니다.

metaData Event Callback Parameter

필드	설명
type	항상 sei로 설정되며, 이것이 SEI 메타데이터임을 나타냅니다.
nalu	SEI의 원시 NALU (Network Abstraction Layer Unit) 데이터를 포함하는 Uint8Array입니다.
sei	SEI Parsing 결과로, 다음 하위 필드들을 포함합니다: type: SEI 타입 size: Payload 크기 payload: 원시 SEI Paylosd 데이터 (Uint8Array)
registered	OvenMediaEngine에서 정의한 형식으로 SEI가 생성되었는지 여부를 나타냅니다. true인 경우 아래의 추가 필드들이 포함됩니다.
uuid	(registered=true인 경우) OvenMediaEngine이 SEI에 삽입한 고유 식별자입니다.
timecode	(registered=true인 경우) SEI가 삽입된 시점의 Timestamp (밀리초; ms)입니다.
userdata	(registered=true인 경우) 사용자 정의 데이터가 포함된 Uint8Array입니다. 이 데이터는 Application의 요구에 맞게 Parsing해야 합니다.

부록: OvenPlayer 설치하기

OvenPlayer 0.10.39 버전부터 WebRTC Stream 재생 시 Video에 포함된 SEI 데이터를 수신할 수 있습니다.

1. OvenPlayer는 OvenPlayer GitHub에서 다운로드할 수 있습니다.

2. 다운로드한 파일의 압축을 푼 후, dist 디렉토리 내의 모든 파일을 프로젝트의 라이브러리 폴더로 복사합니다:

├─.github
├─demo
├─dist
│      ovenplayer.js
│      ovenplayer.js.map
│      RTCTransformWorker.worker.worker.js
│      RTCTransformWorker.worker.worker.js.map
├─docs
├─packages
└─src

복사할 주요 파일:

• ovenplayer.js: OvenPlayer 코어 라이브러리

• RTCTransformWorker.worker.worker.js: WebRTC 처리를 위한 Worker Script

Web Worker의 CORS정책으로 인해 ovenplayer.js는 자체 호스팅이 되어야 하며, RTCTransformWorker.worker.worker.js 파일은 반드시 ovenplayer.js와 같은 경로에 존재해야 합니다.