Push Publishing

OvenMediaEngine Enterprise는 Live Stream을 다른 System으로 Re-streaming할 수 있는 Push Publishing 기능을 제공합니다. 지원 Protocol은 널리 사용되는 SRT, RTMP, MPEG-2 TS입니다.

OvenMediaEngine의 StreamMap 기능을 활용하여 사전 정의된 조건에 따라 Re-streaming을 자동으로 수행할 수 있습니다. 또한, REST API을 통한 Controling 및 Monitoring을 지원합니다.

Push Publishing 설정하기

Push Publisher

Push Publishing을 사용하려면 Server.xml 내 <Applications><Publishers>에서 <Push>를 설정해야합니다.

<Applications>
  <Application>
     ...
    <Publishers>
      ... 
      <Push>
         <!-- [Optional] -->
         <StreamMap>
           <Enable>false</Enable>
           <Path>path/to/map.xml</Path>
         </StreamMap>
      </Push>
      ...
    </Publishers>
  </Application>
</Applications>

RTMP Protocol은 H264 (Video Codec)와 AAC (Audio Codec)만 지원합니다.

StreamMap

<StreamMap>은 사용자 정의 조건에 따라 콘텐츠를 자동으로 Push Publishing하기 위해 사용합니다. XML File Path는 <ApplicationPath>/conf를 기준으로 한 상대 경로를 지정해야 합니다.

<?xml version="1.0" encoding="UTF-8"?>
<PushInfo>
  <Push>
    <Enable>true</Enable>
    <StreamName>stream_a_*</StreamName>
    <VariantNames>video_h264,audio_aac</VariantNames>
    <Protocol>rtmp</Protocol>
    <Url>rtmp://1.2.3.4:1935/app/${SourceStream}</Url>
    <StreamKey></StreamKey>
    <TimestampMode>ZeroBased</TimestampMode>
  </Push>
  <Push>
    <Enable>true</Enable>
    <StreamName>stream_b_*</StreamName>
    <VariantNames></VariantNames>
    <Protocol>srt</Protocol>
    <Url>srt://1.2.3.4:9999?streamid=srt%3A%2F%2F1.2.3.4%3A9999%2Fapp%2Fstream</Url>
    <TimestampMode>Original</TimestampMode>
  </Push>
  <Push>
    <Enable>false</Enable>
    <StreamName>stream_c_*</StreamName>
    <VariantNames></VariantNames>
    <Protocol>mpegts</Protocol>
    <Url>udp://1.2.3.4:2400</Url>
  </Push>
</PushInfo>

XML Elements

Element	Requirement	Description
<StreamName>	Required	Output Stream을 매칭하는 데 사용합니다. Wildcard characters (*)를 지원합니다.
<VariantNames>	Required	특정 Track을 선택할 때 사용합니다. <VariantNames>를 지정하지 않으면 기본적으로 모든 Track이 전송됩니다. 여러 Variant는 콤마(,)로 구분하여 지정할 수 있습니다.
<Protocol>	Required	지원 Protocol은 srt, mpegts, rtmp입니다. SRT 또는 MPEG-TS 전송 시, Network 및 환경(예: Firewall, Port, Packet Loss 등)을 고려해야 합니다. RTMP 전송 시, H.264 + AAC 사용을 권장합니다.
<Url>	Required	Destination Address를 지정합니다. Macro를 지원합니다.
<StreamKey>	Optional	필요 시 Stream Key를 지정합니다 (RTMP). Macro를 지원합니다.
<TimestampMode>	Optional (Enterprise Only)	Outgoing Packet의 Timestamp Mode를 설정합니다. ZeroBased: 전송 시작 시점부터 Timestamp를 0으로 설정하여 전달합니다. Original (default): 원본 Stream과 동일한 Timestamp를 전달합니다.

Macros

자동화 및 운영 효율 향상을 위해 Macro 활용을 권장합니다.

Macro	Description
${Application}	Application name
${SourceStream}	Source stream name
${Stream}	Output stream name

API Interface

Push Publishing 시작하기

Request

POST /v1/vhosts/{vhost}/apps/{app}:startPush

Header

Authorization: Basic {credentials}

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

Body : SRT

{
  "id": "{unique_push_id}",
  "stream": {
    "name": "{output_stream_name}",
    "variantNames": []
  },
  "protocol": "srt",
  "url": "srt://{host}[:port]?mode=caller&latency=120000&timeout=500000",
  "streamKey": ""
}

# id (required)
    unique ID to identify the task
    
# stream (required)
    ## name (required)
        output stream name
        
    ## variantNames (optional)
        Array of track names to publsh. 
        This value is Encodes.[Video|Audio|Data].Name in the OutputProfile
        setting.
        
        If empty, all tracks will be sent.

# protocol (required)
    srt
    
# url (required) 
    address of destination.
    options can be set in query-string format.
    
# streamKey (optional)
    not used with mpegts

In SRT Push Publisher, only the caller connection mode is supported.

Body : RTMP

{
  "id": "{unique_push_id}",
  "stream": {
    "name": "{output_stream_name}",
    "variantNames": [ "h264_fhd", "aac" ]
  },
  "protocol": "rtmp",
  "url":"rtmp://{host}[:port]/{app_name}",
  "streamKey":"{stream_name}"
}

# id (required)
    unique ID to identify the task
    
# stream (required)
    ## name (required)
        output stream name
        
    ## variantNames (optional)
        Array of track names to publsh. 
        This value is Encodes.[Video|Audio|Data].Name in the OutputProfile
        setting.
        
        If empty, The first track among video tracks (by ID) and the first 
        track among audio tracks (by ID) are selected automatically.

# protocol (required)
    rtmp
    
# url (required) 
    address of destination
    
# streamKey (required)
    RTMP stream key

Body : MPEG2-TS

{
  "id": "{unique_push_id}",
  "stream": {
    "name": "{output_stream_name}",
    "variantNames": []
  },
  "protocol": "mpegts",
  "url": "udp://{host}[:port]",
  "streamKey": ""
}

# id (required)
    unique ID to identify the task
    
# stream (required)
    ## name (required)
        output stream name
        
    ## variantNames (optional)
        Array of track names to publsh. 
        This value is Encodes.[Video|Audio|Data].Name in the OutputProfile
        setting.
        
        If empty, all tracks will be sent.

# protocol (required)
    mpegts
    
# url (required) 
    address of destination
    
# streamKey (optional)
    not used with mpegts

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

Please note that responses are incorrectly returned in Json array format for version 0.15.3 and earlier.

{
    "statusCode": 200,
    "message": "OK",
    "response": {
        "id": "{unique_push_id}",
        "state": "ready",
            
        "vhost": "default",
        "app": "app",
        "stream": {
            "name": "{output_stream_name}",
            "trackIds": [],
            "variantNames": []
        },
            
        "protocol": "rtmp",
        "url": "rtmp://{host}[:port]/{app_name}",
        "streamKey": "{stream_name}",
            
        "sentBytes": 0,
        "sentTime": 0,
        "sequence": 0,
        "totalsentBytes": 0,
        "totalsentTime": 0,
            
        "createdTime": "2023-03-15T23:02:34.371+09:00",
        "startTime": "1970-01-01T09:00:00.000+09:00",
        "finishTime": "1970-01-01T09:00:00.000+09:00"
    }
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code
# response
    Created push publishing task information

400 Bad Request

Invalid request.

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 or application name could not be found.

Body

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

409 Conflict

duplicate ID

Parameter	Requirement	Description
id	Required	Push Publishing Task를 식별하기 위한 고유 ID 문자열입니다. ID 중복은 허용되지 않습니다.
stream	Required	Output Target Stream Information Object입니다.
stream.name	Required	Output Stream의 Name입니다. 예시: "myStreamOut".
stream.variantNames	Optional	전송할 Track (Variant) Name 목록입니다. variantNames를 생략하거나 지정하지 않으면, 모든 Track이 전송되거나, RTMP의 경우 첫번째 Video Track과 Audio Track이 선택됩니다.
protocol	Required	Push Publishing에 사용할 Protocol입니다. 예시: "srt", "mpegts", "rtmp".
url	Required	Destination URL입니다. Protocol별로 형식이 다르며 Query String 옵션을 사용할 수 있습니다.
streamKey	Optional	RTMP 전송 시 필요한Stream Key입니다. MPEG-TS 전송 시, 생략할 수 있습니다.
timestampMode	Optional (Enterprise Only)	Outgoing Packet의 Timestamp Mode를 설정합니다. ZeroBased: 전송 시작 시점부터 Timestamp를 0으로 설정하여 전달합니다. Original (default): 원본 Stream과 동일한 Timestamp를 전달합니다.

Push Publishing 중지하기

Request

POST /v1/vhosts/{vhost}/apps/{app}:stopPush

Header

Authorization: Basic {credentials}

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

Body

{
    "id": "{unique_push_id}"
}

# id (required)
    unique ID to identify the push publishing task

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

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

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code

400 Bad Request

Invalid request.

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/application name or id of recording task could not be found.

Body

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

Push Publishing 상태 조회하기

Request

POST /v1/vhosts/{vhost}/apps/{app}:pushes

Header

Authorization: Basic {credentials}

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

Body

{
    "id": "{unique_push_id}"
}

# id (optional)
    unique ID to identify the push publishing task. If no id is given in the request, the full list is returned.

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

The response is Json array format.

{
    "statusCode": 200,
    "message": "OK",
    "response": [
        {
            "id": "{unique_push_id}",
            "state": "started",
            
            "vhost": "default",
            "app": "app",
            "stream": {
                "name": "{output_stream_name}",
                "trackIds": [],
                "variantNames": []
            },
            
            "protocol": "rtmp",
            "url": "rtmp://{host}[:port]/{app_name}",
            "streamKey": "{stream_name}",
            
            "sentBytes": 0,
            "sentTime": 0,
            "sequence": 0,
            "totalsentBytes": 0,
            "totalsentTime": 0,
            
            "createdTime": "2023-03-15T23:02:34.371+09:00",
            "startTime": "1970-01-01T09:00:00.000+09:00",
            "finishTime": "1970-01-01T09:00:00.000+09:00"
        },
        {
            "id": "4",
            ...
        }
    ]
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Information of recording tasks. If there is no recording task, 
	response with empty array ("response": [])

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 or application name could not be found.

Body

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

Push Publishing 상태 목록

State	Description
ready	Waiting for the stream to be created.
connecting	Connecting to destination
pushing	Connected and streaming
stopping	Disconnection / stop in progress
stopped	Push is disconnected / stopped
error	Push encountered an error