Interface RtcEngineEvents

This callback reports the speaker with the highest accumulative volume during a certain period. If the user enables the audio volume indication by calling enableAudioVolumeIndication, this callback returns the uid of the active speaker whose voice is detected by the audio volume detection module of the SDK.

Note

• To receive this callback, you need to call enableAudioVolumeIndication.
• This callback returns the user ID of the user with the highest voice volume during a period of time, instead of at the moment.

You can start a local audio effect playback by calling playEffect. This callback is triggered when the local audio effect file playback finishes.

You can start an audio mixing file playback by calling startAudioMixing. This callback is triggered when the audio mixing file playback finishes.

If the startAudioMixing method call fails, an AudioMixingOpenError warning returns in the Warning callback.

since

3.4.2

When the playback state of the local user's music file changes, the SDK triggers this callback and reports the current playback state and the reason for the change.

since

v3.1.2.

This callback indicates the publishing state change of the local audio stream.

deprecated

Use RemoteAudioStats instead.

The SDK triggers this callback once every two seconds to report the audio quality of each remote user/host sending an audio stream. If a channel has multiple remote users/hosts sending audio streams, the SDK trggers this callback as many times.

This callback returns that the audio route switched to an earpiece, speakerphone, headset, or Bluetooth device.

The definition of the routing is listed in AudioOutputRouting.

since

v3.1.2.

This callback indicates the subscribing state change of a remote audio stream.

This callback reports the IDs and volumes of the loudest speakers (at most 3) at the moment in the channel, and whether the local user is speaking.

By default, this callback is disabled. You can enable it by calling enableAudioVolumeIndication. Once enabled, this callback is triggered at the set interval, regardless of whether a user speaks or not.

The SDK triggers two independent AudioVolumeIndication callbacks at one time, which separately report the volume information of the local user and all the remote speakers. For more information, see the detailed parameter descriptions.

Note

• To enable the voice activity detection of the local user, ensure that you set report_vad(true) in the enableAudioVolumeIndication method.
• Calling muteLocalAudioStream affects the SDK's behavior.
• If the local user calls muteLocalAudioStream, the SDK stops triggering the local user's callback.
• 20 seconds after a remote speaker calls muteLocalAudioStream, the remote speakers' callback does not include information of this remote user; 20 seconds after all remote users call the the muteLocalAudioStream method, the SDK stops triggering the remote speakers' callback.

The SDK triggers this callback when the local user changes the camera exposure position by calling setCameraExposurePosition.

The SDK triggers this callback when the local user changes the camera focus position by calling setCameraFocusPositionInPreview.

deprecated

Use Capturing in the LocalVideoStateChanged callback instead. If the camera fails to turn on, fix the error reported in the Error callback.

The SDK reports the state of the current media relay and possible error messages in this callback.

since

v3.7.0

In the LiveBroadcasting channel profile, when the local user calls setClientRole to switch their user role after joining the channel but the switch fails, the SDK triggers this callback to report the reason for the failure and the current user role.

In the LiveBroadcasting channel profile, when the local user successfully calls setClientRole to switch their user role after joining the channel, for example, from a host to an audience member or vice versa, the SDK triggers this callback to report the user role before and after the switch.

deprecated

Use ConnectionStateChanged instead.

deprecated

Use ConnectionStateChanged instead.

The SDK triggers this callback when it loses connection to the server for more than four seconds after the connection is established. After triggering this callback, the SDK tries to reconnect to the server. You can use this callback to implement pop-up reminders. This callback is different from ConnectionLost:

• The SDK triggers the ConnectionInterrupted callback when the SDK loses connection with the server for more than four seconds after it joins the channel.
• The SDK triggers the ConnectionLost callback when it loses connection with the server for more than 10 seconds, regardless of whether it joins the channel or not.

If the SDK fails to rejoin the channel 20 minutes after being disconnected from Agora's edge server, the SDK stops rejoining the channel.

The SDK triggers this callback when it cannot connect to the server 10 seconds after calling joinChannel, regardless of whether it is in the channel or not.

If the SDK fails to rejoin the channel 20 minutes after being disconnected from Agora's edge server, the SDK stops rejoining the channel.

The Agora SDK returns this callback to report on the current network connection state when it changes, and the reason to such change.

In most cases, the SDK cannot fix the issue and resume running. The SDK requires the app to take action or informs the user about the issue.

For example, the SDK reports a StartCall error when failing to initialize a call. The app informs the user that the call initialization failed and invokes the leaveChannel method to leave the channel. For detailed error codes, see ErrorCode.

Once you enable face detection by calling enableFaceDetection, you can get the following information on the local user in real-time:

• The width and height of the local video.
• The position of the human face in the local video.
• The distance between the human face and the device screen. This value is based on the fitting calculation of the local video size and the position of the human face.

Note

• If the SDK does not detect a face, it reduces the frequency of this callback to reduce power consumption on the local device.
• The SDK stops triggering this callback when a human face is in close proximity to the screen.
• On Android, the distance value reported in this callback may be slightly different from the actual distance. Therefore, Agora does not recommend using it for accurate calculation.

deprecated

Deprecated as of v3.1.2. Use FirstLocalAudioFramePublished instead.

since

v3.1.2.

The SDK triggers this callback under one of the following circumstances:

• The local client enables the audio module and calls joinChannel successfully.
• The local client calls muteLocalAudioStream(true) and muteLocalAudioStream(false) in sequence.
• The local client calls disableAudio and enableAudio in sequence.

This callback is triggered after the first local video frame is rendered on the local video window.

since

v3.1.2.

The SDK triggers this callback under one of the following circumstances:

• The local client enables the video module and calls joinChannel successfully.
• The local client calls muteLocalVideoStream(true) and muteLocalVideoStream(false) in sequence.
• The local client calls disableVideo and enableVideo in sequence.

deprecated

Use Decoding in RemoteAudioStateChanged instead.

This callback is triggered in either of the following scenarios:

• The remote user joins the channel and sends the audio stream.
• The remote user stops sending the audio stream and re-sends it after 15 seconds. Possible reasons include:
• The remote user leaves channel.
• The remote user drops offline.
• The remote user calls muteLocalAudioStream.
• The remote user calls disableAudio.

deprecated

Use Starting in RemoteAudioStateChanged instead.

deprecated

This callback is deprecated. Use Starting or Decoding in the RemoteVideoStateChanged callback instead.

This callback is triggered in either of the following scenarios:

• The remote user joins the channel and sends the video stream.
• The remote user stops sending the video stream and re-sends it after 15 seconds. Possible reasons include:
• The remote user leaves channel.
• The remote user drops offline.
• The remote user calls muteLocalVideoStream.
• The remote user calls disableVideo.

This callback is triggered after the first frame of the remote video is rendered on the video window. The application can retrieve the data of the time elapsed from the user joining the channel until the first video frame is displayed.

The channel name assignment is based on channelName specified in the joinChannel method.

If the uid is not specified when joinChannel is called, the server automatically assigns a uid.

The SDK triggers this callback within 30 seconds after the app calls startLastmileProbeTest.

When the app calls the leaveChannel method, the SDK uses this callback to notify the app when the user leaves the channel.

With this callback, the application retrieves the channel information, such as the call duration and statistics.

This callback indicates the state change of the local audio stream, including the state of the audio recording and encoding, and allows you to troubleshoot issues when exceptions occur.

Note

When the state is Failed, see the error parameter for details.

If you call setLocalPublishFallbackOption and set option as AudioOnly, this callback is triggered when the locally published stream falls back to audio-only mode due to poor uplink conditions, or when the audio stream switches back to the video after the uplink network condition improves. Once the published stream falls back to audio only, the remote app receives the RemoteVideoStateChanged callback.

This callback is triggered when the local user successfully registers a user account by calling registerLocalUserAccount, or joins a channel by calling joinChannelWithUserAccount. This callback reports the user ID and user account of the local user.

The SDK returns the current video state in this callback.

The SDK triggers the LocalVideoStateChanged(Failed, CaptureFailure) callback in the following situations:

• On Android:
  • (Android 9 or later) The application exits to the background, and the system recycles the camera.
  • (Android 6 or later) The camera is occupied by a third-party application. When the third-party application releases the camera, the SDK triggers the LocalVideoStateChanged(Capturing, OK) callback.
  • The camera starts normally, but the captured video is not output for four seconds.
• On iOS:
  • The application exits to the background, and the system recycles the camera.
  • The camera starts normally, but the captured video is not output for four seconds.

When the camera outputs the captured video frames, if all the video frames are the same for 15 consecutive frames, the SDK triggers the LocalVideoStateChanged(Capturing, CaptureFailure) callback. Note that the video frame duplication detection is only available for video frames with a resolution greater than 200 × 200, a frame rate greater than or equal to 10 fps, and a bitrate less than 20 Kbps.

The SDK triggers this callback once every two seconds for each user/host. If there are multiple users/hosts in the channel, the SDK triggers this callback as many times.

deprecated

This callback is deprecated. Use Stopped or Recording in the LocalAudioStateChanged callback instead.

The SDK triggers this callback when the local user resumes or stops capturing the local audio stream by calling enableLocalAudio.

Last mile refers to the connection between the local device and Agora's edge server. This callback reports once every two seconds the last mile network conditions of each user in the channel. If a channel includes multiple users, then this callback will be triggered as many times.

Note txQuality is Unknown when the user is not sending a stream; rxQuality is Unknown when the user is not receiving a stream.

The SDK returns the current network type in this callback. When the network connection is interrupted, this callback indicates whether the interruption is caused by a network type change or poor network conditions.

since

v3.6.2

You can use this callback to listen for the state of the SDK connecting to a proxy. For example, when a user calls setCloudProxy and joins a channel successfully, the SDK triggers this callback to report the user ID, the proxy type connected, and the time elapsed from the user calling joinChannel until this callback is triggered.

When a user loses connection with the server because of network problems, the SDK automatically tries to reconnect and triggers this callback upon reconnection.

This callback indicates the state change of the remote audio stream.

Note

This callback does not work properly when the number of users (in the [Communication] profile) or hosts (in the [LiveBroadcasting] profile) in the channel exceeds 17.

The SDK triggers this callback once every two seconds for each remote user/host. If a channel includes multiple remote users, the SDK triggers this callback as many times.

Schemes such as FEC (Forward Error Correction) or retransmission counter the frame loss rate. Hence, users may find the overall audio quality acceptable even when the packet loss rate is high.

deprecated

This callback is deprecated. Use RemoteAudioStats instead.

This callback reports the transport-layer statistics, such as the packet loss rate and time delay, once every two seconds after the local user receives an audio packet from a remote user.

If you call setRemoteSubscribeFallbackOption and set option as AudioOnly, this callback is triggered when the remotely subscribed media stream falls back to audio-only mode due to poor downlink conditions, or when the remotely subscribed media stream switches back to the video after the downlink network condition improves.

deprecated

This callback is deprecated. Use RemoteVideoStats instead.

This callback reports the transport-layer statistics, such as the packet loss rate and time delay, once every two seconds after the local user receives the video packet from a remote user.

since

v3.5.2

After successfully calling getAudioFileInfo, the SDK triggers this callback to report the information of the audio file, such as the file path and duration.

After a token is specified when joining the channel, the token expires after a certain period of time, and a new token is required to reconnect to the server. This callback notifies the app to generate a new token and call joinChannel to rejoin the channel with the new token.

since

v3.1.2.

When the CDN live streaming state changes, the SDK triggers this callback to report the current state and the reason why the state has changed.

This callback indicates the state of the RTMP or RTMPS streaming. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the errCode parameter.

since

v3.5.2

After a successful takeSnapshot method call, the SDK triggers this callback to report whether the snapshot is successfully taken as well as the details for the snapshot taken.

The SDK triggers this callback when the local user receives the stream message that the remote user sends by calling the sendStreamMessage method.

The SDK triggers this callback when the local user fails to receive the stream message that the remote user sends by calling the sendStreamMessage method.

deprecated

Use RtmpStreamingStateChanged instead.

This callback indicates whether you have successfully added an RTMP or RTMPS stream to the CDN.

deprecated

Use RtmpStreamingStateChanged instead.

This callback indicates whether you have successfully removed an RTMP or RTMPS stream from the CDN.

The user becomes offline if the token used when joining the channel expires. This callback is triggered 30 seconds before the token expires to remind the app to get a new token. Upon receiving this callback, you need to generate a new token on the server and call renewToken to pass the new token to the SDK.

When the LiveTranscoding class in the setLiveTranscoding method updates, the SDK triggers this callback to report the update information.

Note

• If you call setLiveTranscoding to set the LiveTranscoding class for the first time, the SDK does not trigger this callback.

The SDK triggers this callback when the remote user resumes or stops capturing the video stream by calling enableLocalVideo.

This callback is only applicable to the scenario when the remote user only wants to watch the remote video without sending any video stream to the other user.

Once the video module is disabled, the remote user can only use a voice call. The remote user cannot send or receive any video from other users.

The SDK triggers this callback when the remote user enables or disables the video module by calling the enableVideo or disableVideo method.

Note

This callback is invalid when the number of users or hosts in the channel exceeds 17.

After a remote user joins the channel, the SDK gets the UID and user account of the remote user, caches them in a mapping table object (UserInfo), and triggers this callback on the local client.

The SDK triggers this callback under one of the following circumstances:

• A remote user/host joins the channel by calling joinChannel.
• A remote user switches the user role to the host by calling setClientRole after joining the channel.
• A remote user/host rejoins the channel after a network interruption.

Note In the LiveBroadcasting profile:

• The host receives the UserJoined callback when another host joins the channel.
• The audience in the channel receives the UserJoined callback when a new host joins the channel.
• When a web application joins the channel, the UserJoined callback is triggered as long as the web application publishes streams.

The SDK triggers this callback when the remote user stops or resumes sending the audio stream by calling the muteLocalAudioStream method.

Note

This callback is invalid when the number of users or hosts in the channel exceeds 17.

The SDK triggers this callback when the remote user stops or resumes sending the video stream by calling the muteLocalVideoStream method.

Note

This callback is invalid when the number of users or hosts in the channel exceeds 17.

There are two reasons for users to become offline:

• Leave the channel: When the user/host leaves the channel, the user/host sends a goodbye message. When this message is received, the SDK determines that the user/host leaves the channel.
• Drop offline: When no data packet of the user or host is received for a certain period of time (20 seconds for the Communication profile, and more for the LiveBroadcasting profile), the SDK assumes that the user/host drops offline. A poor network connection may lead to false detections, so we recommend using the Agora RTM SDK for reliable offline detection.

since

v3.5.2

After calling enableRemoteSuperResolution, the SDK triggers this callback to report whether super resolution is successfully enabled. If it is not successfully enabled, use reason for troubleshooting.

since

v3.1.2.

This callback indicates the publishing state change of the local video stream.

deprecated

Use Stopped in the LocalVideoStateChanged callback instead. The application can use this callback to change the configuration of the view (for example, displaying other pictures in the view) after the video stops playing.

since

v3.1.2.

This callback indicates the subscribing state change of a remote video stream.

In most cases, the app can ignore the warning reported by the SDK because the SDK can usually fix the issue and resume running.

For instance, the SDK may report a LookupChannelTimeout warning upon disconnection with the server and tries to reconnect. For detailed warning codes, see WarningCode.