PricingAdd-onSupport ProgramBlog

AMF0 Message Insertion

OvenMediaEngine Enterprise supports the AMF0 messgaes insertion feature starting with 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.

onTextData

Inserting the onTextData via the Send Event API | 0.17.3.0+

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

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 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
Description

<Enable>

Sets activation status to true or false.

  • Default: false

<Path>

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
Description

<Enable>

Sets activation status to true or false.

  • Default: false

<SourceStreamName>

Specifies the target stream name.

  • It supports wildcards (*) for pattern matching.

<Interval>

Sets event occurrence interval in milliseconds (ms).

<EventFormat>

Specifies event format (use amf format).

<EventType>

Specifies the event type.

  • Default: video

<Values>

Contains the value of the event data.

<Values><amfType>

Specifies AMF0 message type (use onTextData format).

<Values><Data>

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.

AMF0.onTextData Payload Format

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

onUserDataEvent

Inserting the onUserDataEvent via the Send Event API | 0.19.1.1+

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

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": "onUserDataEvent",
                "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": "amf",
        "events": [
            {
                "amfType": "onUserDataEvent",
                "data": "<XMLTag>{\"time\":\"2026-09-09T02:07:42.934Z\",\"program\":\"adsection\"}<\/XMLTag>"
            }
        ]
    }
]

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 onUserDataEvent through XML Configuration | 0.19.1.1+

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

Configuration Example

Server.xml: You can enable the EventGenerator functionality for the onUserDataEvent 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
Description

<Enable>

Sets activation status to true or false.

  • Default: false

<Path>

Sets the path to the XML file defining the onUserDataEvent 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 onUserDataEvent 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>
  <!-- Simple -->
  <Event>
    <SourceStreamName>schedule*</SourceStreamName>
    <Interval>1000</Interval>
    <EventFormat>amf</EventFormat>
    <Values>
      <AmfType>onUserDataEvent</AmfType>
      <Data>
         <key1>value</key1>,    // String Type, Default
         <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]
      </Data>
    </Values>
  </Event>
  
  <!-- Single value data format below (Example: inserting XML data) --> 
  <Event>
    <SourceStreamName>schedule*</SourceStreamName>
    <Interval>1000</Interval>
    <EventFormat>amf</EventFormat>
    <Values>
      <AmfType>onUserDataEvent</AmfType>
      <Data><![CDATA[<XMLTag>{"json":"value"}</XMLTag>]]></Data>
    </Values>
  </Event>
</EventInfo>
Parameter
Description

<SourceStreamName>

Specifies the target stream name.

  • It supports wildcards (*) for pattern matching.

<Interval>

Sets event occurrence interval in milliseconds (ms).

<EventFormat>

Specifies event format (use amf format).

<Values>

Contains the value of the event data.

<Values><amfType>

Specifies AMF0 message type (use onUserDataEvent format).

<Values><Data>

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.

AMF0.onUserDataEvent Payload Format

This is an example of an AMF0-encoded onUserDataEvent message payload. It can be structured as a Common Object (ECMA Array) or as a single value, and the value type can be String, Number, or Boolean.

[KV Array Form]

string-maker "onUserDataEvent"      // 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-master

[Single Value Form]

string-maker "onUserDataEvent"     // Command Name ECMA Array: 
[string|number-boolean]-maker "value"  // String Type | Number Type [Double] | Boolean Type [1 | 0]
PreviousSEI InsertionNextHLS Markers

Last updated

Was this helpful?