Insert AMF0 messages in RTMP Push Publisher | 0.17.3.0+

OvenMediaEngine Enterprise 0.17.3.0-1 버전부터 AMF0 messages 삽입 기능을 지원합니다.

Live Stream을 RTMP 프로토콜로 다른 시스템에 재스트리밍 (Push Publishing)할 때, AMF0 message를 삽입 할 수 있습니다. 이 기능을 활용하여 자막 삽입, 광고 Maker 삽입과 같은 message를 다른 시스템에 전달 할 수 있습니다. message를 삽입하는 방법은 아래와 같습니다.

• RTMP Provider를 통해 입력받은 Media Source에 message가 포함되어 있는 경우 자동으로 삽입 됩니다.

• OvenMediaEngine의 Send Event API를 사용하여 동적으로, XML 설정을 통해 지속적으로 message를 삽입 할 수 있습니다.

Send Event API를 통한 onTextData message 삽입하기

onTextData message는 자막 삽입, 광고 마커 삽입 등 다양한 목적으로 사용되고 있습니다.

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": "amf",
  "events":[
    {
      "amfType": "onTextData",
      "data": {
        "key1": "value",  // String Type
        "key2": 354.1,    // Number Type [Double]
        "key3": true     // Boolean Type [true | false]
      }
    }
  ]
}

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": "amf",
    "events":[
      {
        "amfType": "onTextData",
        "data": {
          "key1": "value",  // String Type
          "key2": 354.1,    // Number Type [Double]
          "key3": true     // Boolean Type [true | false]
        }
      }
    ]
  }
]

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
}

XML설정을 통한 onTextData message 삽입하기 | 0.18.2.0+

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

Configuration 예제

Server.xml: <Application><EventGenerator>를 추가하여 onTextData message 삽입을 위한 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	세부 onTextData message 삽입을 정의한 XML 파일의 경로를 설정합니다. 상대 경로를 지정하면 Server.xml 파일이 있는 디렉토리가 기준이 됩니다.

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

<?xml version="1.0" encoding="UTF-8"?>
<EventInfo>
  <Event>
    <Enable>true</Enable>
    <SourceStreamName>stream*</SourceStreamName>
    <Interval>2000</Interval>
    <EventFormat>amf</EventFormat>
    <EventType>video</EventType>
    <Values>
      <AmfType>onTextData</AmfType>
      <Data>
        <key1 type="string">value</key1>    // String Type
        <key2 type="double">354.1</key2>    // Number Type [Double]
        <key3 type="boolean">true</key3>    // Boolean Type [true | false]
        <key4>${EpochTime}</key4>
      </Data>
    </Values>
  </Event>
</EventInfo>

매개변수	Required	설명
<Enable>	Y	true 또는 false로 활성화 여부를 설정합니다. Default: false
<SourceStreamName>	Y	onTextData message를 삽입할 Stream의 이름을 지정합니다. 패턴 매칭을 위한 Wildcard (*)를 지원합니다.
<Interval>	Y	Event 발생 주기를 밀리초 (ms) 단위로 설정합니다.
<EventFormat>	Y	Event 포맷을 지정합니다: amf 형식 사용.
<EventType>	N	Event 타입을 지정합니다. Default: video
<Values>	Y	Event 데이터 값을 포함합니다.
<Values><amfType>	N	message 타입을 지정합니다: onTextData 형식 사용.
<Values><Data>	Y	실제 전송할 데이터의 배열을 지정합니다. key 태그를 사용할 수 있으며, Type Attribute가지정되지 않은 경우 기본 String으로 판단합니다. ${EpochTime}을 사용하여 밀리초 단위로 구성된 서버의 현재 Epoch Time으로 대체해서 전송할 수 있는 Macro를 지원합니다 (예시: 1747147513056).

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

Payload 예제

AMF0로 인코딩 된 onTextData message payload의 예제입니다. Common Object (ECMA Array) 는 Key와 Value 리스트로 구성되며, Value 타입은 String, Number, Boolean 입니다.

string-maker "onTextData"         // Command Name ECMA Array: 
ecma-array-maker
"key1" string-maker "value"       // String Type
"key2" number-maker 354.1         // Number Type [Double]
"key3" boolean-maker 1            // Boolean Type [1 | 0]
...
object-end-marker