This page provides an overview of the Agora real-time communications products, including:
The information on this page is specifically intended for use by:
- Agora’s prospective partners.
- Software developers interested in Agora’s products and services.
This section describes the major features of the Agora products.
One-to-one call is a term used in social apps such as WhatsApp, Hike, and Snapchat, and involves two users communicating with each other.
With Agora’s products, you can easily implement the one-to-one call feature on any app. If user A and user B want to set up a one-to-one call, they only need to enter the same channel. A channel is created when you call an API to join a channel, and is destroyed when both users leave the channel. The following figure shows a typical one-to-one call scenario:
This is a video call, but you can disable video and proceed with a voice call only.
A group call is when more than two users chat with one another, like when you chat with a selected group of friends together on WhatsApp. The following figure shows a group call scenario, where three users are involved:
This is a video call, but you can disable video and proceed with a voice call only.
Live broadcast is the broadcast of a live performance with an app, where the viewers are called the audience and the one who gives the performance is the host.
Agora’s products allow you to easily implement the live broadcast feature on any app:
- To give a live broadcast, create a channel and enter it as the host.
- To view a live broadcast, enter the channel created by the host as the audience.
The following terms are associated with a live broadcast:
|Host In||An audience can apply to become a host to interact directly with existing hosts.|
|Real-time Interactive Broadcast||Global users can join the same channel to “Host In” from their mobile or PC clients.|
|Pushing Streams ||The process of pushing a media stream onto the Internet.|
|CDN Live||The process of publishing streams onto the CDN (Content Delivery Network) where users can view live broadcasts through a web browser.|
|||Pushing streams is triggered when the host first joins a channel. When there is no host in a channel for more than 30 seconds, pushing stream terminates. Pushing streams will not be triggered when an audience switches to a host.|
The following figure shows a live broadcast scenario:
This is a live video broadcast, but you can disable video and proceed with a live voice broadcast only.
Signaling implements the following processes:
- Text Messaging
- Calling and hanging up
- Retrieving the user list and sending public messages
You can also send text messages to each other. This process is implemented by signaling; while the actual voice or video call falls into the category of communications.
The following figure shows a typical text messaging scenario:
Calling and Hanging Up¶
If you are making a call using an App, signaling implements the processes such as sending out a call invitation, receiving a call invitation, taking a call, and hanging up.
The following figure shows a calling scenario.
The following figure shows a channel messaging scenario:
In this scenario, signaling implements:
- The user list, which shows how many users there are online
- Group text messaging, that is visible to all users in the channel
Terms such as calling, meeting control, and text messaging refer to signaling. For more information about the differences between the signaling channel and the live broadcast channel, see Channels.
Communications and live broadcasts are in real time and only available to users in a channel. With the recording feature, you can record and share content of the communications or live broadcasts at a later time.
With just one SDK and a set of APIs, you can take advantage of Agora’s globally deployed real-time virtual network.
Communications or Live Broadcast SDK¶
Communications and live broadcast on the same platform share one SDK and a set of APIs. The only difference is whether you set the channel mode to Communication or Live Broadcast when calling the API, setChannelProfile().
The Gaming Voice SDK derives from the Media SDK, and enables the implementation of the voice feature in your gaming app with two modes:
- Free-talk mode (communication)
- Command mode (live broadcast)
Agora also provides a web-based SDK to implement voice and video features on the web.
You can incorporate the following add-ons in the communications or live broadcast SDKs:
This section describes the major features of the Agora services.
Agora provides the following security mechanisms:
- Login authentication
- Call encryption
For more information about the security mechanisms associated with Agora’s products and services, see the Information Security Policy.
User login normally requires authentication. Agora provides static and dynamic App IDs to meet different needs.
By calling one API, you can apply the AES-128 or AES-256 algorithm to Agora channels between clients or between clients and servers.
Agora’s high-quality services:
- 99.99% service availability.
- 99.9% throughput rate.
- End-to-end latency down to 76 ms.
- A globally-deployed, real-time virtual network that enables transnational and cross-domain transmissions, coupled with Agora’s proprietary transmission algorithm, packet-loss countermeasures, and self-adaptive bandwidth control.
- High-definition graphics, superior speed, and low image-freeze rates (smooth graphics rendering). For more information about Agora’s technical advantages in transmission, see Transmitting.
Ease of Use¶
- One SDK
- One set of APIs
- Support on all-platforms, including Android, iOS, macOS, Windows, and the web.
- Support for multiple programming languages, including Java, Objective-C, Swift, and C++.
- Compatible with more than 5,000 types of devices. (Incompatibility may lead to problems such as chirping, echoes, CPU overload, and high-power consumption.)
This section describes the core concepts to get started with Agora’s products and services.
After signing up at Dashboard you can create multiple projects. Each of your projects will be assigned a unique identity called an App ID. Anyone with your App ID can use it on any SDK provided by Agora. Furthermore, anyone who knows your App ID and channel name may intercept your communication. Therefore, Agora recommends that you use a Channel Key for added security on your projects before official launch.
For information about the App ID and Dynamic Key, refer to Security Keys.
A channel is created when you call an API to join a channel, and is destroyed automatically when all users have left the channel.
You will see the following channels when using Agora’s products and services:
To transmit signaling, such as to set up Internet sessions between different clients, control meetings, and send reliable callback events. The channel name is set by the parameter, channelID, in the signaling API.
The signaling channel is a separate channel even though it has the same name as the communications or live broadcast channel.
To transmit media data in communications or live broadcasts between different clients. The channel name is set by the parameter, channelName, in the communications or live broadcast API.
The communications and live broadcast channels under the media channel are virtually the same. The only difference is whether you set the channel mode to communications or live broadcast when calling the API, setChannelProfile().
Account and User ID¶
You need to set the account and uid parameters when using Agora’s media and signaling channels. The account parameter is the user account of the app in either the communications or live broadcast service, while the uid parameter varies with the channels:
The uid parameter is a unique identity in a single media channel of a client app. If two users in the same channel have identical uids, both users will drop out of the channel. If a user sets uid to 0, the Agora server will randomly assign a 32-bit unsigned integer (UInt32) uid to it. You can use the following ways to manage the uid:
- If a user’s account meets the requirement of UInt32, the account can be used directly as the uid.
- If a user’s account is a phone number or email address that does not meet the requirements of UInt32, the user can maintain a mapping table between the account and UInt32.
The uid parameter is set to 0 by default. When user A successfully calls the signaling API, channelJoin, all the other users in the corresponding channel will receive an onChannelUserJoined callback, which suggests that user A has joined the channel and returns the internal uid automatically assigned by the system. Agora recommends the other users to record user A’s uid to quickly locate and fix issues when they occur.
Voice and Video Processing¶
Agora’s voice and video processing include:
Capturing is the process of collecting information from unprocessed raw voice and video data. For example, on a cellphone, recording audio is a form of voice capturing and taking pictures or video is a form of image or video capturing.
Encoding is the process where the sampled or pre-processed data is transformed into a different format.
Agora’s voice and video transmission relies on its self-built SD-RTN (Software Defined Real-time Network), a virtual and UDP (User Datagram Protocol)-based network architecture designed specifically for real-time communications. By deploying software networking units at different data centers across the Internet, Agora manages to add a virtual layer. To ensure stable transmission and low latency, the SD-RTN automatically assigns an optimal path according to the following node conditions in real time:
- Transmission status
- Load conditions
- Distance to the users
- Response time
The following lists the features of the SD-RTN:
Ultra-low latency: User data transmits in real time both within the network elements and on the transmission lines to ensure low latency.
Guaranteed packet arrival rate: Adopts UDP, a protocol specifically designed for real-time transmissions.
- Guaranteed transmission arrival rate
- No uncontrollable latency as in TCP (Transmission Control Protocol)
- Latency down to within 1 ms
Guaranteed data security: Chooses the optimal route based on self-defined routing. Transmits data directly from end-to-end without caching data in the network units, and therefore ensures greater data security.
Perfect fit for real-time communications: Applies to real-time interactive scenarios requiring ultra-low latency, such as Internet calls, video conferences, and live broadcasts involving interaction between the host and the audience.
The following table compares the basic parameters of other networks and Agora’s SD-RTN:
|Parameters||Other Networks||Agora SD-RTN|
|Latency||Normally between 5 to 20 s (RTMP).||Normally between 200 to 600 ms, no more than 2 s.|
|Interaction||One-way interaction between the host and an audience.||Supports host-in between up to 17 video hosts and an audience.|
|Host In||No support for both voice and video host-in.||Supports both voice and video host-in.|
|Packet Loss||No packet loss countermeasures. Image freezes completely when packet loss hits 30%.||Superior packet loss countermeasures. Smooth and fluid images when packet loss hits 30%.|
The following table compares the network transmission parameters of other networks and Agora’s SD-RTN:
|Parameters||Content Delivery Network||Agora SD-RTN|
|Transport Layer Protocol||TCP protocol. Can be optimized in terms of reliability, but may introduce additional latency.||UDP protocol without additional latency.|
|Transport Layer Algorithm||Open source.||Proprietary.|
|Transnational Transmission||Involves different web operators and not optimized for real-time transmission.||Proprietary virtual network with nearly 100 networking nodes deployed worldwide. Monitors and adjusts the network in real time.|
|Packet Loss Countermeasures||Unreliable transmission quality. Poor user experience on weak networks.||Monitors the real-time network quality and optimizes the traffic accordingly.|
Rendering is the process that transforms decoded voice or video data into playable audio or graphics. When it comes to graphics rendering, the process may crop or scale the images.
API Methods and Callbacks¶
The Agora SDK includes a set of API methods (engine interfaces) and callbacks (event callbacks).
- API Methods: The client calls the API methods to implement the features provided by the Agora SDK.
- Callback: Feedback is sent from the SDK to the client on a local or remote event that occurred. A remote event callback is initiated by a remote user in a channel, and transmitted through the UDP channel which is not 100% reliable.
It is recommended that you use reliable signaling for events and statuses. All API methods and callbacks listed in the following table are reliable.
|API Methods||Local Event Callback||Remote Event Callback||Description|
|joinChannel||onJoinChannelSuccess||onUserJoined||A user joined the channel.|
|leaveChannel||onLeaveChannel||onUserOffline||A user left the channel.|
|muteLocalAudioStream||onUserMuteAudio||A user muted the local audio.|
|muteLocalVideoStream||onUserMuteVideo||A user paused sending the local video stream.|
|disableVideo/enableVideo||onUserEnableVideo||A user disabled or enabled the video.|
Agora uses UDP rather than TCP as its underlying transport protocol.
TCP is a reliable protocol. When packet loss occurs, the system will keep resending the packets until transmission is completed or a timeout is reached. Applications using TCP have almost no way of optimizing the resend process to reduce latency.
UDP is an unreliable protocol. When packet loss occurs, the operating system will not resend the packets.
In real-time communications, latency is more important than reliability. Using UDP as the underlying transport protocol, Agora can decide on when to resend the packets or not.
On an Internet connection with packet loss, TCP has a latency that ranges from hundreds of milliseconds (in the case of almost no packet loss) to dozens of minutes (when the packet loss rate hits 30%), and a connection that easily breaks (when the packet loss rate hits 50%). On similar links, UDP has a latency that ranges from dozens of milliseconds (in the case of little packet loss) to several seconds (when transmitting through poor routers). Therefore, UDP still works when packet loss exceeds 30%, while TCP does not. TCP is not optimized for real-time communications, but UDP transmission is optimized by Agora.