Insert AMF0 messages in RTMP Push Publisher | 0.17.3.0+

OvenMediaEngine Enterprise supports AMF0 messgaes insertion starting from version 0.17.3.0-1.

When re-streaming (Push Publishing) a live stream to another system using the RTMP protocol, you can insert AMF0 messages. Utilizing this feature, you can deliver messages such as subtitle insertions and advertisement markers to another system. The method for inserting messages is as follows:

• If the Media Source received through the RTMP Provider includes a message, it will be automatically inserted.

• You can insert messages dynamically through the OvenMediaEngine's Send Event API or continuously through XML configuration.

Inserting the onTextData message via the Send Event API

The onTextData message is used for various purposes, such as subtitle insertion and ad marker insertion.

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
}

Inserting the onTextData message through XML Configuration | 0.18.2.0+

For scenarios requiring continuous onTextData message insertion, you can configure this behavior through XML configuration. Create an XML file defining the onTextData message insertion events and enable EventGenerator in Server.xml.

Configuration Example

Server.xml: You can enable the EventGenerator functionality for the onTextData message insertion by adding <Application><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	Sets activation status to true or false. Default: false
<Path>	Y	Sets the path to the XML file defining the onTextData message insertion details. If a relative path is specified, the directory containing the Server.xml file is used as the base.

XML Defining the onTextData message Insertion Events: Create an XML file defining onTextData message insertion events at the path specified in Server.xml. In this example, it's 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>

Parameter	Required	Description
<Enable>	Y	Sets activation status to true or false. Default: false
<SourceStreamName>	Y	Specifies the target stream name. It supports wildcards (*) for pattern matching.
<Interval>	Y	Sets event occurrence interval in milliseconds (ms).
<EventFormat>	Y	Specifies event format (use amf format).
<EventType>	N	Specifies the event type. Default: video
<Values>	Y	Contains the value of the event data.
<Values><amfType>	N	Specifies message type (use onTextData format).
<Values><Data>	Y	Specifies the array of data to be transmitted You can use the <key> tag, and if the type attribute is not specified, it defaults to string. It supports the macro ${EpochTime}, which is replaced with the server's current epoch time in milliseconds when transmitted (e.g., 1747147513056).

Changes made to the event definition XML file are immediately applied without needing to restart OvenMediaEngine.

Payload Example

Here’s an example of an onTextData message payload encoded in AMF0. A Common Object (ECMA Array) consists of a list of key and value, where the value type can be String, Number, or 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