ApsaraVideo Live:CreateRtcMPUEventSub

Creates an event subscription for stream mixing and relaying. When you create a subscription, you can configure parameters such as the callback URL, the application to subscribe to, and channel information.

QPS limit

The single-user QPS limit for this operation is 50 calls per second. If the limit is exceeded, API calls are throttled, which may affect your business. Call this operation appropriately.

Callback content example

The callback content is sent to your business server as an HTTP/HTTPS POST request. The character encoding is UTF-8, and the request body is a JSON structure. When your business server responds with an HTTP status code of 200, the callback is considered successful. The following is an example of the callback content:

{
	"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 callback header contains the following fields:

Field	Description
Content-Type	The data type. Fixed value: application/json
Ali-Rtc-Timestamp	The timestamp.
Ali-Rtc-Signature	The signature value.

The callback body contains the following fields:

Field	Type	Description	Example
EventType	Integer	The callback event type. For stream mixing and relaying callbacks, the value is fixed to 1.	1
MsgId	String	The callback ID that uniquely identifies this callback.	*****973C-4529-A334*****
AppId	String	The ID of the subscribed application.	yourAppId
SubId	String	The subscription ID.	Sub-******9799B2C4500******
TaskId	String	The relay task ID.	yourTaskId
CallbackTs	Integer	The timestamp in milliseconds when the callback request is initiated.	1712656430476
Payload	JSON Object	The callback event information.	-

• Callback event information (Payload)

Field	Type	Description	Example
DstUrl	String	The destination URL for relaying.	rtmp://domain/app/stream?auth
EventTs	Integer	The timestamp in milliseconds when the callback event occurs.	1712656430384
EventCode	Integer	The callback event code.	1
ErrorCode	Integer	The error code of the callback event.	10001
ErrorMessage	String	The error message of the callback event.	rtmp server init failed

Callback event codes

Field	Value	Description	Callback frequency
MPU_STATE_PREPARING	0	The relay task is created and triggered.	Called back only once.
MPU_STATE_ESTABLISHING	1	The relay task is establishing a connection.	Called back every 5 seconds.
MPU_STATE_RUNNING	2	The relay task is running.	Called back only once.
MPU_STATE_RECOVERING	3	The relay task is interrupted and recovering.	Called back every 5 seconds.
MPU_STATE_TERMINATED	4	The relay task has ended, including normal stop, startup failure, or abnormal exit. The specific reason is indicated by ErrorCode and ErrorMessage.	Called back only once.

The following figure shows an example of state transitions for callback events: Note:

1. Callback messages may arrive at your business server out of order. You can sort events based on EventTs in the Payload. If you only need the latest state of a callback event, ignore subsequently arriving expired events.

2. For stream mixing and relaying tasks created by calling CreateMixStreamRelayTask (new), the task automatically stops after all users leave the room for a period of time, and an MPU_STATE_TERMINATED callback is sent.

3. Callback configurations only affect new tasks and do not affect existing tasks:

a. Tasks started before the callback configuration is enabled do not send callbacks.

b. Tasks started after the callback configuration is enabled send callbacks.

c. Tasks started before the callback configuration is deleted continue to send callbacks until the task ends.

d. Tasks started after the callback configuration is deleted do not send callbacks.

Callback error codes

When a relay task ends, the ErrorCode and ErrorMessage indicate the reason for termination.

Error code	Error message	Description
0		The task stopped normally.
10001	rtmp server init failed	Connection establishment failed. The task ended abnormally.
10002	rtmp server internal error	An internal server error occurred. The task ended abnormally.
10003	task idle timeout	The task ended because it was idle for too long.

Callback authentication

Callback event authentication is enabled by default. The authentication logic is as follows:

• When ApsaraVideo Live initiates a callback request, the HTTP(S) request header contains the Ali-Rtc-Timestamp and Ali-Rtc-Signature fields for signature verification by the callback message receiving server. The Ali-Rtc-Signature value is calculated as follows: Ali-Rtc-Signature=MD5SUM(MD5CONTENT), where MD5CONTENT=Callback URL|Ali-Rtc-Timestamp value|Authentication Key. The callback URL is the complete callback URL that you configured. The authentication key is the AppKey generated when you created the AppId.

• When the callback message receiving server receives a callback message, it concatenates the callback URL, the Ali-Rtc-Timestamp value, and the authentication key, calculates the MD5 value to obtain an encrypted string, and then compares the calculated encrypted string with the Ali-Rtc-Signature field value in the HTTP(S) request header sent by ApsaraVideo Real-time Communication. If the values do not match, the request is invalid.

Callback retry on failure

When Alibaba Cloud initiates a callback request, the callback is considered successful only when your business server responds with an HTTP status code of 200. If the callback fails, Alibaba Cloud retries 7 times at intervals of 1 second, 2 seconds, 5 seconds, 10 seconds, 1 minute, 2 minutes, and 5 minutes. Each retry generates a corresponding callback record.