Optional Readonly channelThe current channel name.
The value is undefined if the local user has not joined a channel.
Readonly connectionConnection state between the SDK and the Agora server.
Readonly localReadonly remoteA list of the remote users in the channel, each of which includes the user ID and the corresponding track information.
The list is empty if the local user has not joined a channel.
Optional Readonly uidThe ID of the local user.
The value is undefined if the local user has not joined a channel.
Allows a user to join a channel.
Users in the same channel can talk to each other.
When joining a channel, the [AgoraRTCClient.on("connection-state-change")]event_connection_state_change callback is triggered on the local client.
After joining a channel, if the user is in the communication profile, or is a host in the Live Broadcast profile, the [AgoraRTCClient.on("user-joined")]event_user_joined callback is triggered on the remote client.
A Promise object with the user ID.
uid.uid.uid parameter empty or set it as null, the Agora server assigns a number uid and returns it.The App ID of your Agora project.
A string that provides a unique channel name for the call. The length must be within 64 bytes. Supported character scopes:
The token generated at your server:
Optional uid: null | UIDThe user ID, an integer or a string, ASCII characters only. Ensure this ID is unique. If you set the uid to null, the Agora server assigns a number uid and returns it in the Promise object.
Note:
- All users in the same channel should have the same type (number or string) of
uid.- If you use a number as the user ID, it should be a 32-bit unsigned integer with a value ranging from 0 to (232-1).
- If you use a string as the user ID, the maximum length is 255 characters.
- You can use string UIDs to interoperate with the Native SDK 2.8 or later. Ensure that the Native SDK uses the User Account to join the channel. See Use String User Accounts.
Leaves a channel.
When leaving the channel, the [AgoraRTCClient.on("connection-state-change")]IAgoraRTCClient.event_connection_state_change callback is triggered on the local client.
When a user (in the communication profile) or a host (in the live-broadcast profile) leaves the channel, the [AgoraRTCClient.on("user-left")]IAgoraRTCClient.event_user_left callback is triggered on each remote client in the channel.
Publishes local audio and/or video tracks to a channel.
After publishing the local tracks, the [AgoraRTCClient.on("user-published")]event_user_published callback is triggered on the remote client.
Note:
- In a live broadcast channel, call setClientRole to set the user role as host before calling this method.
- You can call this method multiple times to add tracks for publishing.
- An
AgoraRTCClientobject can publish multiple audio tracks. The SDK automatically mixes the audio tracks into one audio track. Exception: Safari does not support publishing multiple audio tracks on versions earlier than Safari 12.- An
AgoraRTCClientobject can publish only one video track. If you want to switch the published video track, for example, from a camera video track to a scree-sharing video track, you must unpublish the published video track.
Local tracks created by [AgoraRTC.createMicrophoneAudioTrack]IAgoraRTC.createMicrophoneAudioTrack / [AgoraRTC.createCameraVideoTrack]IAgoraRTC.createCameraVideoTrack or other methods.
Subscribes to the audio and/or video tracks of a remote user.
await client.subscribe(user，"audio");
user.audioTrack.play();
When the subscription succeeds, the SDK adds the subscribed tracks to [user.audioTrack]audioTrack and [user.videoTrack]videoTrack. You can go on to call [audioTrack.play]play or [videoTrack.play]play to play the tracks.
The
Promiseobject throws theTRACK_IS_NOT_PUBLISHEDerror if the specified tracks do not exist.
The remote user.
The media type of the tracks to subscribe to.
"video": Subscribe to the video track only.“audio”: Subscribe to the audio track only.Unpublishes the local audio and/or video tracks.
After the local client unpublishes, the [AgoraRTCClient.on("user-unpublished")]event_user_unpublished callback is triggered on each remote client in the channel.
Optional tracks: ILocalTrack | ILocalTrack[]The tracks to unpublish. If left empty, all the published tracks are unpublished.
Unsubscribes from the audio and/or tracks of a remote user.
The Promise object throws the TRACK_IS_NOT_SUBSCRIBED error if the specified tracks do not exist.
The remote user.
Optional mediaType: "audio" | "video"The media type of the tracks to unsubscribe from:
"video": Unsubscribe from the video track only.“audio”: Unsubscribe from the audio track only.Starts relaying media streams across channels.
After this method call, the SDK triggers the following callbacks:
state 3. Refer to code for the error code and call this method again.code 4, reporting that the SDK starts relaying the media stream to the destination channel.Note:
- Contact sales-us@agora.io to enable this function.
- We do not support string user IDs in this API.
- Call this method only after joining a channel.
- In a live-broadcast channel, only a host can call this method.
- To call this method again after it succeeds, you must call stopChannelMediaRelay to quit the current relay.
client.startChannelMediaRelay(config).then(() => {
console.log("startChannelMediaRelay success");
}).catch(e => {
console.log("startChannelMediaRelay failed", e);
})
A Promise object, which is resolved if the media relay starts successfully.
Configurations of the media stream relay.
Updates the destination channels for media stream relay.
After the channel media relay starts, if you want to relay the media stream to more channels, or leave the current relay channel, you can call this method.
Note:
- Call this method after startChannelMediaRelay.
- You can add a maximum of four destination channels to a relay.
A Promise object, which is resolved if the update succeeds. If the update fails, the media relay state is reset, and you need to call startChannelMediaRelay again to restart the relay.
Configurations of the media stream relay.
Enables dual-stream mode.
Enables dual-stream mode for the local stream. Dual streams are a hybrid of a high-quality video stream and a low-quality video stream:
Note:
- Dual-stream mode is not supported mobile devices.
client.enableDualStream().then(() => {
console.log("Enable Dual stream success!");
}).catch(err => {
console.log(err);
})
Sets the video profile of the low-quality video stream.
If you have enabled the dual-stream mode by calling enableDualStream, use this method to set the low-quality video stream profile.
If you do not set the low-quality video stream profile, the SDK assigns the default values based on your stream video profile.
Note:
- Frame rate settings do not take effect on Firefox. The browser sets the frame rate as 30 fps.
- Due to limitations of some devices and browsers, the resolution you set may get adjusted by the browser. In this case, billings are calculated based on the actual resolution.
- Call this method before calling publish.
The video profile of the low-quality video stream.
Sets the video type of a remote stream.
If a remote user enables dual-stream mode, use this method to set which stream to subscribe to. The local client subscribes to the high-quality video stream by default.
This method works only if the remote client has enabled dual-stream mode (enableDualStream).
The ID of the remote user.
The remote video stream type. The following lists the video-stream types:
Sets the stream fallback option.
Use this method to set the fallback option for the subscribed video stream. Under poor network conditions, the SDK can subscribe to the low-quality video stream or only to the audio stream.
If the auto-fallback option is enabled, the SDK triggers the [AgoraRTCClient.on("stream-type-changed")]event_stream_type_changed callback when the remote stream changes from a high-quality video stream to a low-quality video stream or vice versa, and triggers the [AgoraRTCClient.on("stream-fallback")]event_stream_fallback callback when the remote stream changes from a video stream to an audio stream or vice versa.
This method works only if the remote user has enabled the dual-stream mode by enableDualStream.
The ID of the remote user.
The fallback option. See RemoteStreamFallbackType for details.
Note: Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it.
Injects an online media stream to a live-broadcast channel.
After you call this method, the server pulls the online stream and injects it into a live-broadcast channel. This is applicable to scenarios where all audience members in the channel can watch a live show and interact with each other. See Inject Online Media Stream for details.
If the online media stream is injected successfully, this stream is added to the channel, and all users in the channel receive the [AgoraRTCClient.on("user-published")]event_user_published and [AgoraRTCClient.on("user-joined")]event_user_joined callbacks with the uid 666.
The SDK reports the status of the media stream by triggering the [AgoraRTCClient.on("stream-inject-status")]event_stream_inject_status event.
The URL address to be injected to the ongoing live broadcast. ASCII characters only, and the string length must be less than 1024 bytes. Valid protocols are RTMP, HLS, and HTTP-FLV.
Configurations for the injected stream.
Note: Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it.
Removes an injected stream.
This method removes an injected stream (added by addInjectStreamUrl) from the live broadcast.
If the injected stream is removed successfully, all users in the channel receive the [AgoraRTCClient.on("user-left")]event_user_left and [AgoraRTCClient.on("user-unpublished")]event_user_unpublished callbacks.
Sets the video layout and audio for CDN live streaming.
Ensure that you enable the RTMP Converter service before using this function.
Configurations for live transcoding. See LiveStreamingTranscodingConfig for details.
Publishes the local stream to the CDN.
See Push Streams to the CDN for details.
Note:
- This method adds only one stream HTTP/HTTPS URL address each time it is called.
- Pushing streams to the CDN is not supported on mobile devices.
The CDN streaming URL in the RTMP format. ASCII characters only.
Optional transcodingEnabled: booleanWhether to enable live transcoding. Transcoding sets the audio and video profiles and the picture-in-picture layout for the stream to be pushed to the CDN. It is often used to combine the audio and video streams of multiple hosts in a CDN live stream.
If set as
true, setLiveTranscoding must be called before this method.
true: Enable transcoding.false: (Default) Disable transcoding.Enables the volume indicator.
This method enables the SDK to regularly report the remote users who are speaking and their volumes.
After the volume indicator is enabled, the SDK triggers the [AgoraRTCClient.on("volume-indicator")]event_volume_indicator callback to report the volumes every two seconds, regardless of whether there are active speakers in the channel.
client.enableAudioVolumeIndicator();
client.on("volume-indicator", volumes => {
volumes.forEach((volume, index) => {
console.log(`${index} UID ${volume.uid} Level ${volume.level}`);
});
})
Since
4.1.0
Gets the statistics of a local audio track.
Since
4.1.0
Gets the statistics of a local video track.
Note: You cannot get the
encodeDelayproperty on iOS.
Gets the statistics of the call.
The statistics of the call.
Since
4.1.0
Gets the statistics of remote audio tracks.
Since
4.2.0
Gets the network quality of all the remote users to whom the local user subscribes.
Since
4.1.0
Gets the statistics of remote video tracks.
Occurs when the state of the connection between the SDK and the server changes.
IAgoraRTCClient
Events
The current connection state.
The previous connection state.
Optional reason: ConnectionDisconnectedReasonThe reason of disconnection if curState is "DISCONNECTED".
Occurs when a remote user or host joins the channel.
The SDK triggers this callback when one of the following situations occurs:
IAgoraRTCClient
Events
Information of the remote user.
Occurs when a remote user becomes offline.
The SDK triggers this callback when one of the following situations occurs:
In live-broadcast channels, the SDK triggers this callback only when a host goes offline.
IAgoraRTCClient
Events
Information of the user who is offline.
Reason why the user has gone offline.
"Quit": The user calls leave and leaves the channel."ServerTimeOut": The user has dropped offline."BecomeAudience": The client role is switched from host to audience.Occurs when a remote user publishes an audio or video track.
You can subscribe to and play the audio or video track in this callback. See subscribe and [RemoteTrack.play]play.
The SDK also triggers this callback to report the existing tracks in the channel when a user joins the channel.
client.on("user-published", async (user, mediaType) => {
await client.subscribe(user, mediaType);
if (mediaType === "video") {
console.log("subscribe video success");
user.videoTrack.play("xxx");
}
if (mediaType === "audio") {
console.log("subscribe audio success");
user.audioTrack.play();
}
})
IAgoraRTCClient
Events
Information of the remote user.
Type of the track.
"audio": The remote user publishes an audio track."video": The remote user publishes a video track.Occurs when a remote user unpublishes an audio or video track.
IAgoraRTCClient
Events
Information of the remote user.
Type of the track.
"audio": The remote user unpublishes an audio track."video": The remote user unpublishes a video track.Reports the state change of users using the Agora RTC Native SDK when your scenario involves the Native SDK.
This event is only for synchronizing states with the clients that integrate the Native SDK.
In most cases, you only need to listen for [user-published]IAgoraRTCClient.event_user_published and [user-unpublished]IAgoraRTCClient.event_user_unpublished events for operations including subscribeing, unsubscribing, and displaying whether the remote user turns on the camera and microphone. You do not need to pay special attention to user states since the SDK automatically handles user states.
This event indicating the media stream of a remote user is active does not necessarily mean that the local user can subscribe to this remote user. The local user can subscribe to a remote user only when receiving the [user-published]IAgoraRTCClient.event_user_published event.
IAgoraRTCClient
Events
The ID of the remote user.
The current user state.
Occurs when the SDK starts to reestablish the media connection for publishing and subscribing.
IAgoraRTCClient
Events
The ID of the user who reestablishes the connection. If it is the local uid, the connection is for publishing; if it is a remote uid, the connection is for subscribing.
Occurs when the SDK ends reestablishing the media connection for publishing and subscribing.
IAgoraRTCClient
Events
The ID of the user who reestablishes the connection. If it is the local uid, the connection is for publishing; if it is a remote uid, the connection is for subscribing.
Occurs when the type of a remote video stream changes.
The SDK triggers this callback when a high-quality video stream changes to a low-quality video stream, or vice versa.
IAgoraRTCClient
Events
The ID of the remote user.
The new stream type:
Occurs when a remote video stream falls back to an audio stream due to unreliable network conditions or switches back to video after the network conditions improve.
IAgoraRTCClient
Events
The ID of the remote user.
Whether the remote media stream falls back or recovers:
"fallback": The remote media stream falls back to audio-only due to unreliable network conditions."recover": The remote media stream switches back to the video stream after the network conditions improve.Occurs when the state of the media stream relay changes.
The SDK reports the state and error code of the current media relay with this callback.
If the media relay is in an abnormal state, you can find the error code in ChannelMediaRelayError (for example if the token has expired, or repeated reconnection attempts fail.)
IAgoraRTCClient
Events
The state of the media relay.
The error code.
Reports events during a media stream relay.
IAgoraRTCClient
Events
The event code for a media stream relay.
Reports all the speaking remote users and their volumes.
It is disabled by default. You can enable this callback by calling enableAudioVolumeIndicator. If enabled, it reports the users' volumes every two seconds regardless of whether there are users speaking.
The volume is an integer ranging from 0 to 100. Usually a user with volume above five is a speaking user.
client.on("volume-indicator", function(result){
result.forEach(function(volume, index){
console.log(`${index} UID ${volume.uid} Level ${volume.level}`);
});
});
IAgoraRTCClient
Events
Occurs when decryption fails.
The SDK triggers this callback when the decryption fails during the process of subscribing to a stream. The failure is usually caused by incorrect encryption settings. See setEncryptionConfig for details.
IAgoraRTCClient
Events
Occurs 30 seconds before a token expires.
You must request a new token from your server and call renewToken to pass a new token as soon as possible.
client.on("token-privilege-did-expire", async () => {
await client.join(<APPID>, <CHANNEL NAME>, <NEW TOKEN>);
});
IAgoraRTCClient
Events
Occurs when the token expires.
You must request a new token from your server and call join to use the new token to join the channel.
client.on("token-privilege-did-expire", async function(){
//After requesting a new token
await client.renewToken(token);
});
IAgoraRTCClient
Events
Reports the network quality of the local user.
After the local user joins the channel, the SDK triggers this callback to report the uplink and downlink network conditions of the local user once every two second.
Agora recommends listening for this event and displaying the network quality.
IAgoraRTCClient
Events
The network quality of the local user.
Occurs when an error occurs in CDN live streaming.
After the method call of startLiveStreaming succeeds, the SDK triggers this callback when errors occur during CDN live streaming.
You can visit err.code to get the error code. The errors that you may encounter include:
LIVE_STREAMING_INVALID_ARGUMENT: Invalid argument.LIVE_STREAMING_INTERNAL_SERVER_ERROR: An error occurs in Agora's streaming server.LIVE_STREAMING_PUBLISH_STREAM_NOT_AUTHORIZED: The URL is occupied.LIVE_STREAMING_TRANSCODING_NOT_SUPPORTED: Sets the transcoding parameters when the transcoding is not enabled.LIVE_STREAMING_CDN_ERROR: An error occurs in the CDN.LIVE_STREAMING_INVALID_RAW_STREAM: Timeout for the CDN live streaming. Please check your media stream.IAgoraRTCClient
Events
The URL of the CDN live streaming that has errors.
The error details.
Occurs when a warning occurs in CDN live streaming.
After the method call of startLiveStreaming succeeds, the SDK triggers this callback when warnings occur during CDN live streaming.
You can visit err.code to get the warning code. The warnings that you may encounter include:
LIVE_STREAMING_WARN_STREAM_NUM_REACH_LIMIT: Pushes stremas to more than 10 URLs.LIVE_STREAMING_WARN_FAILED_LOAD_IMAGE: Fails to load the background image or watermark image.LIVE_STREAMING_WARN_FREQUENT_REQUEST: Pushes stremas to the CDN too frequently.IAgoraRTCClient
Events
The URL of the CDN live streaming that has warnings.
Note: Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it.
Occurs when the status of the media stream injected by addInjectStreamUrl updates.
IAgoraRTCClient
Events
The current status.
The ID of the user who injects the media stream.
The URL address of the media stream.
Reports exceptions in the channel.
Exceptions are not errors, but usually reflect quality issues.
This callback also reports recovery from an exception.
Each exception corresponds to a recovery event.
Exception
| Code | Message | Exception |
|---|---|---|
| 1001 | FRAMERATE_INPUT_TOO_LOW | Captured video frame rate is too low |
| 1002 | FRAMERATE_SENT_TOO_LOW | Sent video frame rate is too low |
| 1003 | SEND_VIDEO_BITRATE_TOO_LOW | Sent video bitrate is too low |
| 1005 | RECV_VIDEO_DECODE_FAILED | Decoding received video fails |
| 2001 | AUDIO_INPUT_LEVEL_TOO_LOW | Sent audio volume is too low |
| 2002 | AUDIO_OUTPUT_LEVEL_TOO_LOW | Received audio volume is too low |
| 2003 | SEND_AUDIO_BITRATE_TOO_LOW | Sent audio bitrate is too low |
| 2005 | RECV_AUDIO_DECODE_FAILED | Decoding received audio fails |
Recoveries
| Code | Message | Recovery |
|---|---|---|
| 3001 | FRAMERATE_INPUT_TOO_LOW_RECOVER | Captured video frame rate recovers |
| 3002 | FRAMERATE_SENT_TOO_LOW_RECOVER | Sent video frame rate recovers |
| 3003 | SEND_VIDEO_BITRATE_TOO_LOW_RECOVER | Sent video bitrate recovers |
| 3005 | RECV_VIDEO_DECODE_FAILED_RECOVER | Decoding received video recovers |
| 4001 | AUDIO_INPUT_LEVEL_TOO_LOW_RECOVER | Sent audio volume recovers |
| 4002 | AUDIO_OUTPUT_LEVEL_TOO_LOW_RECOVER | Received audio volume recovers |
| 4003 | SEND_AUDIO_BITRATE_TOO_LOW_RECOVER | Sent audio bitrate recovers |
| 4005 | RECV_AUDIO_DECODE_FAILED_RECOVER | Decoding received audio recovers |
IAgoraRTCClient
Events
Since
4.4.0
After the method call of publish succeeds, the SDK triggers this callback to indicate whether the media stream is forwarded by the Agora cloud proxy service.
IAgoraRTCClient
Events
Whether the media stream is forwarded by the Agora cloud proxy service.
true: Forwarded by the Agora cloud proxy service.false: Not forwarded by the Agora cloud proxy service.Renews the token.
The token expires after a set time once token is enabled. When the SDK triggers the [AgoraRTCClient.on("token-privilege-will-expire")]event_token_privilege_will_expire callback, call this method to pass a new token. Otherwise the SDK disconnects from the server.
The new token.
Reports customized messages to Agora's data center.
Temporarily, Agora supports reporting a maximum of 20 message pieces within 5 seconds.
Sets the user role and level in a live streaming (when [mode]ClientConfig.mode is "live").
"host" or "audience". A host can publish and subscribe to streams, while an audience member can only subscribe to streams. The default role in a live streaming is "audience". Before publishing tracks, you must call this method to set the user role as "host".Note:
- When [mode]ClientConfig.mode is
"rtc", this method does not take effect and all users are"host"by default.- If the local client switches the user role after joining a channel, the SDK triggers the [AgoraRTCClient.on("user-joined")]event_user_joined or [AgoraRTCClient.on("user-left")]event_user_left callback on the remote client.
- To switch the user role to
"audience"after calling publish, call unpublish first. Otherwise the method call fails and throws an exception.
The role of the user.
Optional options: ClientRoleOptionsThe detailed options of a user, including user level.
Sets the encryption configurations.
Use this method to enable the built-in encryption before joining a channel.
If the encryption configurations are incorrect, the SDK triggers the [AgoraRTCClient.on("crypt-error")]event_crypt_error callback when publishing tracks or subscribing to tracks.
Notes:
- All users in a channel must use the same encryption mode, secret, and salt.
- You must call this method before joining a channel, otherwise the method call does not take effect and encryption is not enabled.
- As of v4.7.0, after a user leaves the channel, the SDK automatically disables the built-in encryption. To re-enable the built-in encryption, call this method before the user joins the channel again.
- Do not use this method for CDN live streaming.
The encryption mode.
The encryption secret. ASCII characters only. When a user uses a weak secret, the SDK outputs a warning message to the Web Console and prompts the users to set a strong secret. A strong secret must contain at least eight characters and be a combination of uppercase and lowercase letters, numbers, and special characters. Due to browser encryption algorithm limitations, the secret length cannot exceed 62 characters. Agora recommends you use OpenSSL to generate the secret on your server. For details, see Media Stream Encryption.
Optional salt: Uint8ArrayThe salt. Only valid when you set the encryption mode as "aes-128-gcm2" or "aes-256-gcm2". Agora recommends you use OpenSSL to generate the salt on your server. For details, see Media Stream Encryption.
Enables cloud proxy.
You must call this method before joining the channel or after leaving the channel.
For the extra settings required for using the cloud proxy service, see Use Cloud Proxy.
Optional mode: numberCloud proxy mode.
Generated using TypeDoc
An interface providing the local client with basic functions for a voice or video call, such as joining a channel, publishing tracks, or subscribing to tracks.
An
AgoraRTCClientobject is created by the createClient method.