Network and Others

Call this method after the user leaves the channel.

Parameters

callId

The Call ID of the current call. You can obtain it by calling getCallId.

description

(Optional) Description of the call. The string length should be less than 800 bytes.

Return Values

After the user leaves the channel, the SDK automatically disables the built-in encryption feature. Call this method again before the user rejoins the channel.

Scenario

Applicable to scenarios with high security requirements.

Timing

Call this method before joining a channel.

Parameters

enabled

Whether to enable the built-in encryption feature:

• true: Enable built-in encryption.
• false: (default) Disable built-in encryption.

config

Built-in encryption configuration. See EncryptionConfig.

Return Values

After the user leaves the channel, the SDK automatically disables built-in encryption. You need to call this method again before the user rejoins the channel.

Scenario

Applicable to multi-channel scenarios or scenarios with high security requirements.

Timing

Call this method before joining a channel.

Parameters

enabled

Whether to enable built-in encryption:

• true: Enable built-in encryption.
• false: (Default) Disable built-in encryption.

config

Built-in encryption configuration. See EncryptionConfig.

connection

Connection information. See RtcConnection.

Return Values

Deprecated

This method is deprecated. The SDK automatically enables interoperability with the Web SDK, so you do not need to call this method.

If there are Web SDK users in the channel, you must call this method; otherwise, Native users' video will appear black on the web. This method is only applicable in Live Broadcast Low Latency mode. In the voice call scenario, interoperability is enabled by default.

Parameters

enabled

Whether to enable interoperability:

• true: Enable interoperability.
• false: (default) Disable interoperability.

Return Values

After the user joins a channel, the client generates a callId to identify the current call. You can call getCallId to get the callId, and pass it when calling methods such as rate and complain.

Timing

You must call this method after joining a channel.

Return Values

You can call this method to get the callId, and pass it when calling methods such as rate and complain.

Scenario

This method is applicable in multi-channel scenarios.

Timing

Call this method after joining a channel.

Parameters

connection

Connection information. See RtcConnection.

Return Values

Returns the call ID if the method call succeeds. Returns an empty string if the method call fails.

Timing

You can call this method before or after joining a channel.

Return Values

Scenario

This method applies to multi-channel scenarios.

Timing

This method can be called before or after joining a channel.

Parameters

connection

Connection information. See RtcConnection.

Return Values

In custom video and audio capture scenarios, to ensure audio-video synchronization, Agora recommends calling this method to get the current monotonic time of the SDK and passing this value to the timestamp parameter of the captured VideoFrame and AudioFrame. Monotonic time refers to a time sequence that increases monotonically over time, in milliseconds.

Timing

You can call this method before or after joining a channel.

Return Values

Parameters

error

The error code reported by the SDK.

Return Values

If the method call succeeds, returns the description of the error code. If the method call fails, returns an empty string.

This method can be used to register audio and video frame observers.

Return Values

If the method call succeeds, returns the native handle of the SDK.

You can call this method at any time to get the current network type in use.

Return Values

In real-time chorus scenarios, especially when multiple receivers experience inconsistent downlink connections due to network issues, you can call this method to obtain the current NTP time as a reference to align lyrics and music across receivers, achieving chorus synchronization.

Return Values

If the method call succeeds, returns the current NTP time as a Unix timestamp in milliseconds.

Return Values

If the method call succeeds, returns the SDK version string. If the method call fails, returns an empty string.

Since

Available since v4.3.0.

Before using advanced features, it is recommended to call this method to check whether the current device meets the required capabilities, to avoid performance degradation or feature unavailability on low-end devices. You can use the return value of this method to decide whether to display or enable the corresponding feature button, or to notify the user when the device lacks sufficient capabilities.

Parameters

type

Type of advanced feature:

• FEATURE_VIDEO_VIRTUAL_BACKGROUND (1): Virtual background.
• FEATURE_VIDEO_BEAUTY_EFFECT (2): Beauty effect.

Return Values

You can call this method to query the device score. If the returned score is low (e.g., below 60), you should lower the video resolution to avoid affecting the video experience. Different business scenarios have different minimum score requirements. For specific score recommendations, please contact technical support.

Return Values

Parameters

callId

The ID of the current call. You can obtain it by calling getCallId.

rating

Rating value, ranging from 1 (lowest) to 5 (highest).

description

(Optional) Description of the call. The string length should be less than 800 bytes.

Return Values

This feature is currently in testing and is available for free trial. In the test version, you can report up to 10 messages within 6 seconds. Each message must not exceed 256 bytes, and each string must not exceed 100 bytes. To try this feature, contact technical support and discuss the format of the custom message with us.

Parameters

id

The ID of the custom message.

category

The category of the custom message.

event

The event name of the custom message.

label

The label of the custom message.

value

The value of the custom message.

Return Values

This feature is currently in testing and available for free trial. In the test version, you can report up to 10 messages within 6 seconds. Each message must not exceed 256 bytes, and each string must not exceed 100 bytes. To try this feature, contact technical support and discuss the format of the custom messages with us.

Scenario

This method applies to multi-channel scenarios.

Parameters

id

The ID of the custom message.

category

The category of the custom message.

event

The event name of the custom message.

label

The label of the custom message.

value

The value of the custom message.

connection

Connection information. Applies to multi-channel scenarios. See RtcConnection.

Return Values

You can call this method on the video publishing device and pass in the channel name and user ID of the audio publishing device. The SDK uses the timestamp of the sent audio stream as a reference to automatically adjust the video stream, ensuring that even if the two publishing devices have different uplink network conditions (e.g., one uses Wi-Fi and the other uses 4G), the audio and video remain synchronized on the receiving end.

Parameters

channelId

Channel name of the audio publishing device.

uid

User ID of the audio publishing device.

Return Values

When the user's network access is restricted by a firewall, you need to first configure the firewall to allow access to specific IP addresses and ports provided by Agora, then call this method to enable the cloud proxy and set the proxy type via the proxyType parameter. After successfully connecting to the cloud proxy, the SDK triggers the onConnectionStateChanged callback with the state CONNECTION_STATE_CONNECTING and reason CONNECTION_CHANGED_SETTING_PROXY_SERVER. To disable the configured cloud proxy, call setCloudProxy and set proxyType to TRANSPORT_TYPE_NONE_PROXY. To switch the cloud proxy type, first call setCloudProxy to disable the current proxy (proxyType set to TRANSPORT_TYPE_NONE_PROXY), then call setCloudProxy again to set the new proxyType.

Parameters

proxyType

Type of cloud proxy:

• TRANSPORT_TYPE_NONE_PROXY (0): Auto mode. This is the default mode enabled by the SDK. In this mode, the SDK tries to connect to SD-RTN™ directly and automatically switches to TCP/TLS 443 if it fails.
• TRANSPORT_TYPE_UDP_PROXY (1): UDP protocol cloud proxy, i.e., forced UDP cloud proxy mode. In this mode, the SDK always transmits data via UDP.
• TRANSPORT_TYPE_TCP_PROXY (2): TCP (encrypted) protocol cloud proxy, i.e., forced TCP cloud proxy mode. In this mode, the SDK always transmits data via TCP/TLS 443.

Return Values

After successfully deploying the Agora hybrid cloud solution and integrating the 4.x RTC SDK into the intranet client, you can call this method to specify the local access point and assign the access module to the SDK.

Timing

You must call this method before joining a channel.

Parameters

config

Local access point configuration. See LocalAccessPointConfiguration.

Return Values

Deprecated

This method is deprecated. Set the log file path using the config parameter when calling create [2/2].

You must call this method immediately after calling create [2/2], or the log output may be incomplete.

Timing

You must call this method immediately after calling create, or the log output may be incomplete.

Parameters

filePath

The full path of the log file, encoded in UTF-8.

Return Values

Deprecated

This method is deprecated. Set the log file size using the logConfig parameter in create [2/2].

Parameters

fileSizeInKBytes

The size of the agorasdk.log file in KB. Range: [128, 20480], default is 2,048 KB.

• If the value is less than 128 KB, the SDK automatically adjusts it to 128 KB.
• If the value is greater than 20,480 KB, the SDK automatically adjusts it to 20,480 KB.

Return Values

Deprecated

This method is deprecated. Use logConfig in create [2/2] instead.

You can use a combination of one or more log filter levels. The log level order is LOG_FILTER_OFF, LOG_FILTER_CRITICAL, LOG_FILTER_ERROR, LOG_FILTER_WARN, LOG_FILTER_INFO, and LOG_FILTER_DEBUG. Selecting a level will show logs of that level and higher. For example, if you set the log level to LOG_FILTER_WARN, you will see logs of LOG_FILTER_CRITICAL, LOG_FILTER_ERROR, and LOG_FILTER_WARN.

Parameters

filter

The SDK log output level.

• LOG_FILTER_OFF (0): No log output.
• LOG_FILTER_DEBUG (0x080f): Outputs all logs. Set this level if you want the most complete log file.
• LOG_FILTER_INFO (0x0f): Outputs logs of LOG_FILTER_CRITICAL, LOG_FILTER_ERROR, LOG_FILTER_WARN, and LOG_FILTER_INFO levels. This is the recommended level.
• LOG_FILTER_WARN (0x0e): Outputs logs of LOG_FILTER_CRITICAL, LOG_FILTER_ERROR, and LOG_FILTER_WARN levels.
• LOG_FILTER_ERROR (0x0c): Outputs logs of LOG_FILTER_CRITICAL and LOG_FILTER_ERROR levels.
• LOG_FILTER_CRITICAL (0x08): Outputs only LOG_FILTER_CRITICAL logs.

Return Values

Deprecated

This method is deprecated. Set the log output level using the config parameter when calling create [2/2].

Select a log level to view logs of that level and higher.

Parameters

level

The log level. See LogLevel.

Return Values

Parameters

parameters

The JSON string used to set parameters.

Return Values

If you set option to STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW or STREAM_FALLBACK_OPTION_AUDIO_ONLY, when the downlink network cannot support both audio and video, the SDK automatically switches the video stream from high quality to low quality, or disables the video to guarantee audio quality. The SDK continuously monitors the network quality and restores the audio and video stream subscription when the network improves.

Parameters

option

The fallback option for the subscribed stream. See StreamFallbackOptions.

Return Values

Deprecated

This method is deprecated.

Unstable networks affect the audio and video quality in video calls or interactive live streaming. When the downlink network cannot support both audio and video, if option is set to STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW or STREAM_FALLBACK_OPTION_AUDIO_ONLY, the SDK automatically switches the video stream from high quality to low quality, or disables the video to ensure audio quality. The SDK continuously monitors network quality and resumes audio and video stream subscription when the network improves.

Parameters

option

The fallback option for the subscribed stream:

• STREAM_FALLBACK_OPTION_DISABLED (0): No fallback for audio and video streams. Audio and video quality is not guaranteed.
• STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1): (Default) When the downlink network is poor, the subscribed remote video stream falls back to a low-quality (low resolution, low bitrate) video stream.
• STREAM_FALLBACK_OPTION_AUDIO_ONLY (2): When the network condition is poor, the SDK first attempts to receive the low-quality video stream. If the network is too poor to display video, it falls back to receiving only the audio stream.

Return Values

You can call this method to perform an audio and video call loop test to check if the devices and the user's network connection are working properly. After starting the test, the user should speak or face the camera, and the audio or video will be played back after about two seconds.

Timing

You can call this method before or after joining a channel.

Parameters

config

Configuration for the audio and video call loop test. See EchoTestConfiguration.

Return Values

This method starts the last-mile network probe test before joining a channel to obtain uplink and downlink network statistics, including bandwidth, packet loss, jitter, and round-trip time (RTT).

Parameters

config

Configuration for the last-mile network probe test. See LastmileProbeConfig.

Return Values

After calling startEchoTest, you must call this method to end the test, otherwise you cannot perform another loop test or join a channel.

Return Values

Return Values

Deprecated

This method is deprecated. Use onConnectionStateChanged instead.

Trigger Timing

This callback is triggered when the connection is banned by the Agora server.

Deprecated

This method is deprecated. Use onConnectionStateChanged instead.

Trigger Timing

This callback is triggered when the SDK loses connection with the server for more than four seconds.

Regardless of whether the user is in a channel, this callback is triggered after calling joinChannel and the SDK fails to reconnect to the server within 10 seconds after the connection is lost. If the SDK fails to rejoin the channel within 20 minutes after disconnecting from the Agora edge server, it stops trying to reconnect.

Trigger Timing

This callback is triggered after calling joinChannel and the SDK loses connection with the server and fails to reconnect within 10 seconds.

Since

Available since v2.3.2.

The SDK triggers this callback when the network connection state changes and reports the current connection state and the reason for the change.

Trigger Timing

This callback is triggered when the network connection state changes.

Parameters

state

Current connection state:

• CONNECTION_STATE_DISCONNECTED (1): The SDK is disconnected from the Agora edge server.
• CONNECTION_STATE_CONNECTING (2): The SDK is connecting to the Agora edge server.
• CONNECTION_STATE_CONNECTED (3): The SDK is connected to the Agora edge server.
• CONNECTION_STATE_RECONNECTING (4): The SDK is reconnecting to the Agora edge server.
• CONNECTION_STATE_FAILED (5): The SDK failed to connect to the Agora edge server.

reason

Reason for the connection state change:

• CONNECTION_CHANGED_CONNECTING (0): The SDK is connecting to the Agora edge server.
• CONNECTION_CHANGED_JOIN_SUCCESS (1): The SDK successfully joined the channel.
• CONNECTION_CHANGED_INTERRUPTED (2): The connection between the SDK and the Agora edge server was interrupted.
• CONNECTION_CHANGED_BANNED_BY_SERVER (3): The connection was banned by the Agora server, for example, when a user is kicked from the channel.
• CONNECTION_CHANGED_JOIN_FAILED (4): The SDK failed to join the channel. If it fails to join the channel for more than 20 minutes, the SDK stops reconnecting and returns this error code. You need to prompt the user to try switching networks and rejoining the channel.
• CONNECTION_CHANGED_LEAVE_CHANNEL (5): The SDK has left the channel.
• CONNECTION_CHANGED_INVALID_APP_ID (6): Invalid App ID. You need to use a valid App ID to rejoin the channel and ensure the App ID matches the one generated in the Agora Console.
• CONNECTION_CHANGED_INVALID_CHANNEL_NAME (7): Invalid channel name. Please use a valid channel name to rejoin the channel. A valid channel name is a string no longer than 64 bytes and supports the following characters:
  • All lowercase letters: a to z.
  • All uppercase letters: A to Z.
  • All numeric digits: 0 to 9.
  • Special characters: !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,.
• CONNECTION_CHANGED_INVALID_TOKEN (8): Invalid Token. Possible reasons include:
  • App Certificate is enabled in the Agora Console, but no Token is provided when joining the channel.
  • The uid specified in joinChannel differs from the uid used to generate the Token.
  • The Token used does not match the generated Token.

Ensure that:

• If App Certificate is enabled, a Token must be provided when joining the channel.
• The user ID specified when generating the Token matches the one used to join the channel.
• The Token used matches the generated Token.

• CONNECTION_CHANGED_TOKEN_EXPIRED (9): The current Token has expired. You need to generate a new Token on your server and rejoin the channel with it.
• CONNECTION_CHANGED_REJECTED_BY_SERVER (10): The user was banned by the server.
• CONNECTION_CHANGED_SETTING_PROXY_SERVER (11): After setting a proxy server, the SDK tries to reconnect.
• CONNECTION_CHANGED_RENEW_TOKEN (12): The connection state changed due to a Token update.
• CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED (13): The client IP address changed. If this error code is received multiple times, prompt the user to switch networks and rejoin the channel.
• CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT (14): The keep-alive connection between the SDK and the Agora edge server timed out. The SDK will try to reconnect automatically.
• CONNECTION_CHANGED_REJOIN_SUCCESS (15): The SDK successfully rejoined the channel.
• CONNECTION_CHANGED_LOST (16): The connection between the SDK and the server was lost.
• CONNECTION_CHANGED_ECHO_TEST (17): The connection state changed due to an echo test.
• CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED_BY_USER (18): The local IP address was changed by the user.
• CONNECTION_CHANGED_SAME_UID_LOGIN (19): The same uid joined the same channel from different devices. Note: Joining the same RTC channel with the same uid is undefined behavior, and Agora does not guarantee this error code will always be triggered in such cases.
• CONNECTION_CHANGED_TOO_MANY_BROADCASTERS (20): The number of hosts in the channel has reached the limit.

If an error occurs during encryption or decryption after calling enableEncryption to enable encryption, the SDK triggers this callback on the sender or receiver side.

Trigger Timing

This callback is triggered when an error occurs during encryption or decryption.

Parameters

errorType

Error type:

• ENCRYPTION_ERROR_INTERNAL_FAILURE (0): Internal reason.
• ENCRYPTION_ERROR_DECRYPTION_FAILURE (1): Media stream decryption error. Ensure the receiver and sender use the same encryption mode and key.
• ENCRYPTION_ERROR_ENCRYPTION_FAILURE (2): Media stream encryption error.
• ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE (3): Data stream decryption error. Ensure the receiver and sender use the same encryption mode and key.
• ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE (4): Data stream encryption error.

This callback is triggered after calling startLastmileProbeTest.

Trigger Timing

This callback is triggered within 30 seconds after calling startLastmileProbeTest.

Parameters

result

Uplink and downlink Last-mile network probe test results. See LastmileProbeResult.

This callback is triggered before the user joins the channel to report the Last-mile network quality between the local user and the Agora edge server. After calling startLastmileProbeTest, the SDK triggers this callback.

Trigger Timing

This callback is triggered after calling the startLastmileProbeTest method.

Parameters

quality

Last-mile network quality:

• QUALITY_UNKNOWN (0): Unknown network quality.
• QUALITY_EXCELLENT (1): Excellent network quality.
• QUALITY_GOOD (2): Good network quality, but bitrate may be slightly lower than excellent.
• QUALITY_POOR (3): Slight degradation in communication quality.
• QUALITY_BAD (4): Unable to communicate smoothly.
• QUALITY_VBAD (5): Very poor network quality, almost unable to communicate.
• QUALITY_DOWN (6): Network disconnected, unable to communicate.
• QUALITY_DETECTING (8): Performing Last-mile probe.

Since

Available since v4.6.0.

Trigger Timing

This callback is triggered after you set enableMultipath to true to enable multipath transmission.

Parameters

stats

Multipath transmission statistics. See MultipathStats.

This callback reflects network quality by sending and receiving broadcast packets within the channel. Too many broadcast packets may cause a broadcast storm. To prevent excessive data transmission in the channel, this callback reports at most 4 remote users' network quality by default.

Trigger Timing

This callback is triggered every two seconds.

Parameters

uid

User ID identifying the user whose network quality is reported.

• 0: Indicates the local user.

txQuality

User's uplink network quality rating, evaluated based on transmission bitrate, packet loss rate, average round-trip time (RTT), and jitter:

• QUALITY_UNKNOWN (0): Unknown quality.
• QUALITY_EXCELLENT (1): Excellent quality.
• QUALITY_GOOD (2): Appears excellent but slightly lower bitrate.
• QUALITY_POOR (3): Slight stutter in communication.
• QUALITY_BAD (4): Unable to communicate smoothly.
• QUALITY_VBAD (5): Very poor quality, almost unable to communicate.
• QUALITY_DOWN (6): Network disconnected, unable to communicate.
• QUALITY_DETECTING (8): Performing Last-mile probe test.

rxQuality

User's downlink network quality rating, evaluated based on packet loss rate, average round-trip time (RTT), and jitter:

• QUALITY_UNKNOWN (0): Unknown quality.
• QUALITY_EXCELLENT (1): Excellent quality.
• QUALITY_GOOD (2): Appears excellent but slightly lower bitrate.
• QUALITY_POOR (3): Slight stutter in communication.
• QUALITY_BAD (4): Unable to communicate smoothly.
• QUALITY_VBAD (5): Very poor quality, almost unable to communicate.
• QUALITY_DOWN (6): Network disconnected, unable to communicate.
• QUALITY_DETECTING (8): Performing Last-mile probe test.

You can use this callback to get the connection state and the reason for the change. When the network connection is interrupted, this callback indicates whether the interruption is due to a change in network type or poor network conditions.

Trigger Timing

This callback is triggered when the local network type changes.

Parameters

type

Network type:

• NETWORK_TYPE_UNKNOWN (-1): Unknown network type.
• NETWORK_TYPE_DISCONNECTED (0): SDK is disconnected from the network.
• NETWORK_TYPE_LAN (1): LAN network type.
• NETWORK_TYPE_WIFI (2): Wi-Fi network type (including hotspots).
• NETWORK_TYPE_MOBILE_2G (3): Mobile 2G network type.
• NETWORK_TYPE_MOBILE_3G (4): Mobile 3G network type.
• NETWORK_TYPE_MOBILE_4G (5): Mobile 4G network type.
• NETWORK_TYPE_MOBILE_5G (6): Mobile 5G network type.

This callback is triggered when the SDK fails to obtain device permissions and is used to report the type of permission that could not be obtained.

Trigger Timing

This callback is triggered when the SDK fails to obtain device permissions.

Parameters

permission

Type of device permission:

• RECORD_AUDIO (0): Permission for audio capture devices.
• CAMERA (1): Permission for the camera.
• SCREEN_CAPTURE (2): Permission for screen sharing.

Parameters

permission

Permission type, including:

• RECORD_AUDIO: Microphone permission.
• CAMERA: Camera permission.
• SCREEN_CAPTURE: Screen capture permission.

After the user calls setCloudProxy and successfully joins the channel, the SDK triggers this callback to report the user ID, the type of connected proxy, and the elapsed time (in milliseconds) from calling joinChannel to triggering this callback.

Trigger Timing

This callback is triggered after the user calls setCloudProxy and successfully joins the channel.

Parameters

channel

Channel name.

uid

User ID.

proxyType

Type of connected proxy:

• PROXY_TYPE_NONE_PROXY (0): Reserved parameter.
• PROXY_TYPE_UDP_CLOUD_PROXY (1): UDP cloud proxy, i.e., forced UDP cloud proxy mode. In this mode, the SDK always transmits data via UDP.
• PROXY_TYPE_TCP_CLOUD_PROXY (2): TCP (encrypted) cloud proxy, i.e., forced TCP cloud proxy mode. In this mode, the SDK always transmits data via TCP/TLS 443.
• PROXY_TYPE_LOCAL_PROXY (3): Reserved parameter.
• PROXY_TYPE_TCP_AUTO_FALLBACK (4): Auto mode. In this mode, the SDK tries to connect to SD-RTN™ directly, and falls back to TCP/TLS 443 if it fails.

localProxyIp

Reserved parameter.

elapsed

Elapsed time (in milliseconds) from calling joinChannel to triggering this callback.

Trigger Timing

This callback is triggered when the remote media stream switches between audio and video due to network changes.

Parameters

uid

The user ID of the remote user.

isFallbackOrRecover

Whether the switch between audio and video is triggered by network changes:

• true: The subscribed media stream switches to audio-only due to poor network conditions.
• false: The subscribed media stream switches back to video after the network improves.

Trigger Timing

This callback is triggered when uplink network information changes.

Parameters

info

Uplink network information. See UplinkNetworkInfo.