Best practices integrating Media Push

To ensure reliability of Media Push, follow the advice on this page when integrating Media Push RESTful APIs.

You need the following to start using Media Push RESTful API:

• The scene of the channel is live, profile set to BROADCASTING
• Media Push is enabled
• To monitor Media Push events, enable Notifications (optional).

Check that your Peak Concurrent Worker (PCW), Queries Per Second (QPS), and the number of streams do not exceed the following limits set by Agora.

Agora sets the following QPS limits for the Media Push RESTful API:

API	QPS limit
Create	Creating a converter is limited to 50 queries per second.
Delete	Deleting a converter is limited to 50 queries per second.
Update	Updating a specified converter is limited to 50 queries per second.
Get	Getting the request rate of a specified converter is limited to 50 queries per second.

When the QPS limit is exceeded, the status code 429 (Too Many Requests) is returned. To extend the QPS limit, contact support@agora.io.

The PCW limit depends on your video stream resolution and region.

Resolutions:

• SD: Standard definition video, resolution ≤ 640 × 360
• HD: High definition video, resolution ≤ 1280 × 720 and > 640 × 360
• FHD: Full HD video, resolution ≤ 1920 × 1080 and > 1280 × 720

Item	Mainland China	Europe	America	Asia (excluding mainland China)
RESTful API	SD 300 HD 50 FHD 20	SD 20 HD 5 FHD - Contact support@agora.io to enable	SD 20 HD 5 FHD - Contact support@agora.io to enable	SD 20 HD 5 FHD - Contact support@agora.io to enable

To learn the details of the PCW limits for SDK API, or if you need to extend the RESTful API PCW limit, contact support@agora.io.

The upper limit of video attributes supported by Agora is as follows:

• Resolution 1920 × 1080
• Frame rate 30 FPS

The maximum number of supported streams is as follows:

Service type	Mainland China	Europe	America	Asia (excluding mainland China)
Media Push	SD 300 HD 50 FHD 20	SD 20 HD 5 FHD - Contact support@agora.io to enable	SD 20 HD 5 FHD - Contact support@agora.io to enable	SD 20 HD 5 FHD - Contact support@agora.io to enable

Note

If you need to upload multiple streams of different resolutions at the same time, make sure you meet the following requirements:

• The number of streams per resolution cannot exceed the corresponding limit for that resolution.
• The total number of streams cannot exceed the limit set for the higher resolution. For example, if you upload both SD and HD streams in America, the total number of streams cannot exceed 20. If you upload HD and FHD, the total number cannot exceed 5.

To ensure the high availability of REST services and prevent downtime caused by regional network faults, Agora provides failover and domain name switch.

Network failures and risks may be caused by cloud and network software, infrastructure, and other factors that Agora cannot control. To provide the best possible user experience, Media Push provides high availability automatic task migration for failure recovery. After a failure is confirmed, the Media Push task is migrated within 120 seconds. During this period, the task may be interrupted.

Consider whether you can accept the impact of high availability migration based on your own business characteristics, and decide whether to adopt higher quality assurance measures. For example, create multiple Media Push tasks for critical scenes. Alternatively, you can make periodic API calls and monitor notifications to get the latest task status, then create a new task with a different UID once you confirm the task status is unhealthy.

If you need a more reliable solution than fault recovery, you can use a multiple Media Push task strategy. You can choose the following two ways to implement it:

1. Start the main push task and multiple backup tasks at the same time. Set a different CDN address for each Media Push task. When the main Media Push task fails, the CDN audience can switch to the backup CDN address in time.

2. If the CDN vendor you use supports the feature of pushing several streams to the same CDN address with different priorities, create a Media Push task No. 1 to the CDN with priority 1 (<rtmp://xxx/xxx/xxx>? priority=1). If task 1 fails, create task 2 with priority is 2. In this case, task 1 is ignored by the CDN. The priority fields of different CDNs are different. Check with the CDN vendor whether the priority function is supported and what the name of the priority field is.

For use cases with higher quality requirements, requesting multiple Media Push tasks with different tagging enables isolated resources for these tasks and raises the success rate. Media Push supports room-level isolation for tasks. For example, if there is a task with "name":"my-task" in the original request, you can add a suffix to the name parameter to realize isolation at the computer room level. Use "name":"my-task-agora-isolate-1" and "name":"my-task-agora-isolate-2" to start additional tasks. Note that:

• If resources are insufficient, then tasks started later fails.
• Media Push supports up to three-way isolation, That is, my-taskagora-isolate1, my-task-agoraisolate-2, and my-taskagora-isolate-3 can be separated.

To ensure high availability of REST services, Agora enables you to switch domain names when you experience service outage due to regional network failures. Take the following steps to set up and switch your domain name:

1. Set the primary domain name based on the location of your service server:

   • If the DNS address of the service server is located in a country or region other than mainland China, set the primary domain name to api.agora.io.
   • If the DNS address of the service server is in mainland China, set the primary domain name to api.sd-rtn.com.

2. If your attempt to initiate a RESTful API request using the primary domain fails, set up your retry strategy as follows:

   1. Primary domain retry: Retry using the same primary domain name.

   2. Alternate domain retry:

      • If the current primary domain name is api.sd-rtn.com, use api.agora.io as the alternate domain name.
      • If the current primary domain name is api.agora.io, use api.sd-rtn.com as the alternate domain name.

   3. Adjacent domain retry: If alternate domain retry fails, retry using the domain name adjacent to the current region.

      For example, suppose your business server is located in Europe. You set the primary domain name to api.agora.io, and the business server resolves the primary domain name to Germany. Germany is located in central Europe (api-eu-central-1.agora.io). The domain name table shows that the adjacent area is West Europe. Use the api-eu-west-1.agora.io or api-eu-west-1.sd-rtn.com domain name to retry.

Take the following precautions when setting up your retry strategy:

• To avoid exceeding the QPS limit with retry requests, best practice is to use a back-off strategy. For example, wait 1 second before you retry for the first time, wait 3 seconds before retrying the second time, and wait 6 seconds before retry a third time.

• If the request fails because of a network problem rather than a DNS domain name resolution problem, skip alternate domain retry and proceed to adjacent domain retry.

• Before switching to the region domain name, ensure that the REST services you wish to use, for example, cloud recording or channel management, are deployed in that region.

The following table shows the primary and region domain names for various regions.

Primary domain name	Region domain name	Region
api.sd-rtn.com	api-us-west-1.sd-rtn.com	Western United States
	api-us-east-1.sd-rtn.com	Eastern United States
	api-ap-southeast-1.sd-rtn.com	Southeast Asia Pacific
	api-ap-northeast-1.sd-rtn.com	Northeast Asia Pacific
	api-eu-west-1.sd-rtn.com	Western Europe
	api-eu-central-1.sd-rtn.com	Central Europe
	api-cn-east-1.sd-rtn.com	East China
	api-cn-north-1.sd-rtn.com	North China
api.agora.io	api-us-west-1.agora.io	Western United States
	api-us-east-1.agora.io	Eastern United States
	api-ap-southeast-1.agora.io	Southeast Asia Pacific
	api-ap-northeast-1.agora.io	Northeast Asia Pacific
	api-eu-west-1.agora.io	Western Europe
	api-eu-central-1.agora.io	Central Europe
	api-cn-east-1.agora.io	East China
	api-cn-north-1.agora.io	North China

When creating a converter with a create call, pay attention to the following:

• Create the converter by region parameter:

  • The region you set must be in the same area as your CDN origin station. For example, if your CDN origin is located in the US, set region to na.
  • Pass the region value in lowercase.

• Agora recommends that you assign a string value to the X-Request-ID field in the request header. The Agora server returns an X-Custom-request-ID field in the response header for troubleshooting purposes.

• Set UID or account as the user name for the converter. Do not set these two fields at the same time. Ensure that each converter has a unique user name within the channel.

• To avoid repeated media streaming due to repeated creation of multiple converters, it is recommended to use the name field to manage converters under a specific project. At the same time, converters with the same names cannot exist in a project. If you attempt to create a converter with the same name, you receive the 409 (Conflict) status code.

• Agora recommends that you assign the name using a combination of the channel name and a converter property. For example, show68_horizontal and show68_vertical would represent a horizontal and a vertical layout respectively.

• audioOption and videoOptions are set as follows for audio only or video only scenarios:

  • In a video only scenario, you do not need to set audioOptions and its related fields.
  • In an audio-only scenario, you do not need to set videoOptions and its related fields by default. For special cases, see Output SEI in audio-only scenarios.
  • In audio plus video scenarios, videoOptions and audioOptions are required and cannot be left blank. If you do not need to configure audioOptions set it to null.

• Set an appropriate value for idleTimeout. The default value of 300 seconds is recommended. It means that the converter is automatically destroyed, 300 seconds after all subscribers leave the channel.

In an audio-only scenario, by default, you do not need to set videoOptions and its related fields. However, if you need to carry additional user information, such as volume, you can set SEI information with the seiOptions field in videoOptions.

If you want to output SEI information in Metadata or DataStream type carried by the user in an audio-only scenario and avoid video transcoding fees, follow these steps:

1. Pass the SEI information to be output in videoOptions.seiOptions.
2. Ensure that the width and height in videoOptions.canvas are set to 16 to avoid video transcoding fees.
3. Pass the UID of the user who carries the SEI information in rtcStreamUid field in videoOptions.layout.

When updating a specified converter with an Update call, pay attention to the following:

When you use the query parameter sequence to update the same converter multiple times, ensure that the sequence value increases. Media Push updates the converter according to the latest update request, that is, the maximum sequence number.

The Update API does not support the following configuration parameters:

• name
• idleTimeOut
• transcodeOptions.rtcChannel
• transcodeOptions.audioOptions.codecProfile
• transcodeOptions.audioOptions.sampleRate
• transcodeOptions.audioOptions.bitrate
• transcodeOptions.audioOptions.audioChannels
• transcodeOptions.videoOptions.codec
• transcodeOptions.videoOptions.codecProfile

If you receive 404, 429, or 5xx error codes, use a backoff strategy. For example, wait 5-6 seconds, 10-11 seconds, or 15-16 seconds and try again. If you get three consecutive 404 or 5xx error codes, or if the state field in the response to checking the status of a Media Push task says failed, it means that the Media Push task has failed. To fix this problem, follow these steps:

1. Check whether the CDN address is correct.
2. If the CDN address is correct, destroy the current converter and create a new one.

• If the status code is 200, the request is successful.
• If the status code is not 200, the request has failed. See the error message in the response body for clarification.

Status code	Possible error message	Possible reason of failure	Measures to take
400 Bad Request	Invalid parameter: rtmpUrl. Replace and retry. Invalid parameter: idleTimeout. Replace and retry.	Wrong parameters. Check by referring to the reason field in the HTTP response body.
401 Unauthorized	Invalid authentication credentials.	RESTful API authentication failed.	See RESTful Authentication
403 Forbidden	No valid permission to use this function. Contact us.	Service is not enabled.	Enable the service.
404 Not Found	Resource is not found and destroyed.	The task was not started or is in the process of failover or deletion.	Retry following the retreat strategy.
409 Conflict	Resource with the same name already exists. Use the existing resource or delete it and create a new resource.	Resource with the same name already exists.	Delete the existing converter and create a new one.
429 Too Many Requests	Request rate limit exceeded. Resources quota exceeded. No available resources.	Too many request	Retry following the retreat strategy.
500 Unknown	Internal error. Contact us for troubleshooting.	Internal error	Retry following the retreat strategy.
501 Not Implemented	The requested method has not been implemented.	Internal error	Retry following the retreat strategy.
503 Service Unavailable	The server is temporarily overloaded. Retry following the retreat strategy and contact us for troubleshooting. The server is temporarily down. Retry following the retreat strategy.	Internal error.	Retry following the retreat strategy.
504 Gateway Timeout	Gateway timeout. Check whether the resource is created. If not, create a new resource.	Internal error.	Retry following the retreat strategy.

If the error persists, print the X-Request-ID and X-Resource-ID fields in the response header in the log and contact technical support.

Refer to the following table to quickly check whether each check item meets the integration requirements to ensure the reliability of Media Push.

Required or optional	Item	Check
Required	Channel mode	Ensure that the scene of the channel is live.
Required	Availability	Enable Media Push.
Required	QPS limit	Ensure that the rate of API calls in a project is below the maximum limit.
Required	Maximum number of concurrent Tasks	Ensure that the number of concurrent tasks in a project is below 300.
Optional	Converter name	Use the name field to manage the converter under the specified project. Assigning the name as a combination of the channel name and a converter property.
Required	Region	Set the region in the same area as your media streaming. Pass region value in lowercase.
Required	Idle timeout	Set an appropriate idleTimeout value. 300 seconds is recommended.
Optional	Troubleshooting	Rectify the errors as follows: Use the retreat strategy. Check the error code. If the preceding troubleshooting methods do not resolve the problem, print the values of the X-Request-ID and X-Resource-ID fields in the response header and contact Agora technical support.
Optional	Message notifications	Enable message notification service for Media Push and listen to Media Push events.