Push Publishing

OvenMediaEngine Enterprise supports Push Publishing function that can restreaming live streams to other systems. The protocol supports widely used protocols such as SRT, RTMP, and MPEG-2 TS.

The StreamMap feature has been added, and it now automatically re-streaming based on predefined conditions. You can also use the Rest API to control and monitor it.

Configuring Push Publishing

Push Publisher

To use Push Publishing, you need to configure <Push> under <Applications><Publishers> in Server.xml.

<Applications>
  <Application>
     ...
    <Publishers>
      ... 
      <Push>
         <!-- [Optional] -->
         <StreamMap>
           <Enable>true</Enable>
           <Path>push_info.xml</Path>
         </StreamMap>
         <!-- Connection Timeout -->
         <ConnectionTimeout>1000</ConnectionTimeout>
         <!-- Send Timeout -->
         <SendTimeout>100</SendTimeout>
      </Push>
      ...
    </Publishers>
  </Application>
</Applications>

The RTMP protocol only supports H264 and AAC codecs.

From OvenMediaEngine Enterprise 0.20.2.1-1, the Push Publisher supports the ConnectionTimeout and SendTimeout options.

Element	Description
ConnectionTimeout	The maximum allowed wait time when attempting to establish a connection to the server. Unit: ms
SendTimeout	The maximum allowed wait time when sending data while the connection is established. Unit: ms

StreamMap

<StreamMap> is used for automatically pushing content based on user-defined conditions. The XML file path should be specified relative to <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	Used to match the output stream name. Wildcard characters (*) are supported.
<VariantNames>	Required	Used to select specific tracks. If <VariantNames> is not specified, all tracks are transmitted by default. Multiple variants can be specified using commas (,).
<Protocol>	Required	Supported protocols are srt, mpegts, and rtmp. When using SRT or MPEG-TS, consider the network environment (e.g., firewalls, ports, packet loss, etc.). When using RTMP, using H.264 + AAC is strongly recommended.
<Url>	Required	Specifies the destination address. Macros are supported.
<StreamKey>	Optional	Specifies the stream key when required: RTMP Macros are supported.
<TimestampMode>	Optional (Enterprise Only)	Defines how timestamps are set for outgoing packets. ZeroBased: Sends timestamps starting from 0 (zero) at the beginning of transmission. Original (default): Sends timestamps identical to the original stream’s timestamps.

Macros

To improve automation and operational efficiency, we recommend actively using macros.

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

API Interface

Start 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	A unique ID string used to identify the Push Publishing task. Duplicate IDs are not allowed.
stream	Required	The output target stream information object.
stream.name	Required	Output stream name. Example: "myStreamOut".
stream.variantNames	Optional	A list of track (variant) names to transmit. If omitted or empty, the default behavior applies: all tracks are transmitted, or for RTMP, the first video track and the first audio track are selected.
protocol	Required	The protocol used for Push Publishing. Example: "srt", "mpegts", "rtmp".
url	Required	Destination URL. The format differs by protocol, and query string options can be used.
streamKey	Optional	Stream key for RTMP transmission. Can be omitted for MPEG-TS transmission.
timestampMode	Optional	Configures the timestamp mode for outgoing packets. ZeroBased: Sends timestamps starting from 0 (zero) at the beginning of transmission. Original (default): Sends timestamps identical to the original stream’s timestamps.

Stop 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
}

Get Push Publishing State

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
}

State of 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