ApsaraVideo Live:CreateRtcMPUEventSub

You can call this operation to create a subscription to mixed-stream relay events. You can configure parameters such as the callback URL, application to which you want to subscribe, and channel information when you create a subscription.

QPS limit

You can call this operation up to 50 times per second per account. Requests that exceed this limit are dropped and you will experience service interruptions. We recommend that you take note of this limit when you call this operation.

Sample callback

Callbacks are sent to your application server as HTTP or HTTPS POST requests. The request is encoded in UTF-8 and the request body is a JSON struct. The callback request is successful if the HTTP status code 200 is returned. Sample code:

Note We recommend that you check both the callback information and the active stream status provided by your CDN vendor to determine whether the mixed-stream relay task is normal.

{
	"EventType": 1,
	"MsgId": "42bba8b5-94ab-468c-9dae-9b501dd****",
	"AppId": "rtcdev",
	"SubId": "Sub-9799B2C45009799B2*****",
	"TaskId": "mpucallbacktest",
	"CallbackTs": 1712656430476,
	"Payload": {
		"DstUrl": "rtmp://domain/app/stream?auth",
		"EventTs": 1712656430384,
		"EventCode": 1,
		"ErrorCode": 0,
		"ErrorMessage": ""
	}
}

Callback information

The following table describes the fields that are included in the callback header.

Field	Description
Content-Type	The data type. Set the value to application/json.
Ali-Rtc-Timestamp	The timestamp.
Ali-Rtc-Signature	The signature value.

The following table describes the fields that are included in the callback message.

Field	Type	Description	Example
EventType	Integer	The type of the callback event. 1 is returned for mixed-stream relay event callbacks.	1
MsgId	String	The unique ID of the callback.	*****973C-4529-A334*****
AppId	String	The ID of the application.	yourAppId
SubId	String	The ID of the subscription.	Sub-9799B2C4500
TaskId	String	The ID of the stream relay task.	yourTaskId
CallbackTs	Integer	The time when the callback request was initiated. The value must be a timestamp in milliseconds.	1712656430476
Payload	JSON Object	The information about the callback event.	-

• The following table describes the fields in Payload.

Field	Type	Description	Example
DstUrl	String	The destination URL.	rtmp://domain/app/stream?auth
EventTs	Integer	The time when the callback event occurred. The value must be a timestamp in milliseconds.	1712656430384
EventCode	Integer	The callback event code.	1
ErrorCode	Integer	The error code.	10001
ErrorMessage	String	The error message.	rtmp server init failed

Callback event codes

Field	Value	Description	Callback interval
MPU_STATE_PREPARING	0	The stream relay task is created.	Only one callback is fired.
MPU_STATE_ESTABLISHING	1	The stream relay task is being connected.	Every 5 seconds
MPU_STATE_RUNNING	2	The stream relay task is in progress.	Only one callback is fired.
MPU_STATE_RECOVERING	3	The stream relay task is interrupted and being recovered.	Every 5 seconds
MPU_STATE_TERMINATED	4	The stream relay task ends. You can differentiate whether the task is completed, failed to start, or unexpectedly exited based on ErrorCode and ErrorMessage.	Only one callback is fired.

The following flowchart describes the lifecycle of a callback event: Note:

1. Callback information may be sent to your business server out of order. You can sort events by using EventTs in Payload. This allows you to ignore callbacks of expired events and helps you obtain the latest callback information.

2. If you create a mixed-stream relay task by calling the StartLiveMPUTask (new) operation, the task automatically stops when all users in the room leave for a specific period of time. The MPU_STATE_TERMINATED callback is fired when the task stops.

3. Callback configurations affect only incremental tasks. The following rules apply:

a. No callback is fired for tasks that are created before the callback configurations are set.

b. Callbacks are fired for tasks that are created after the callback configurations are set.

c. Callbacks are fired for tasks that are created before the callback configurations are deleted.

d. No callback is fired for tasks that are created before after the callback configurations are deleted.

Callback error codes

When a stream relay task ends, you can check the cause based on ErrorCode and ErrorMessage.

Error code	Error message	Description
0		The task is completed.
10001	rtmp server init failed	The connection failed to be established.
10002	rtmp server internal error	An internal error occurred and the task failed.
10003	task idle timeout	The task was idle for too long and timed out.

Callback authentication

By default, callback authentication is enabled. The following authentication logic applies:

• When ApsaraVideo Live initiates a callback request, it includes the Ali-Rtc-Timestamp and Ali-Rtc-Signature headers in the HTTP or HTTPS request so that the callback message receiving server can authenticate the signature. The value of the Ali-Rtc-Signature header is calculated by using the following formula: Ali-Rtc-Signature = MD5SUM(MD5CONTENT). In the formula, MD5CONTENT is a string in the following format: Callback domain name|Ali-Rtc-Timestamp value|Authentication key. The callback domain name is the domain name in the callback URL. The authentication key is the AppKey of the application.

• After receiving a callback message, the callback message receiving server concatenates the callback domain name, value of the Ali-Rtc-Timestamp header, and authentication key in the preceding format. The server calculates the MD5 value of the string to obtain an encrypted string. Then, the server compares the encrypted string with the value of the Ali-Rtc-Signature header in the HTTP or HTTPS request initiated by Real-Time Communication (RTC). If the two values are different, the request is invalid.

Callback retry

After Alibaba Cloud initiates a callback request, the callback is considered successful only if the HTTP status code 200 is returned by your business server. If a callback fails, ApsaraVideo Live resends the callback request 7 times at intervals of 1 second, 2 seconds, 5 seconds, 10 seconds, 60 seconds, 120 seconds, and 300 seconds. A callback record is generated each time a callback request is resent.