Agora provides ensured quality of experience (QoE) for worldwide Internet-based voice and video communications through a virtual global network optimized for real-time web and mobile-to-mobile applications.

‍- As of v3.0.0, Agora deprecates the RtcEngineParameters class. IRtcEngine class covers all APIs of the RtcEngineParameters class, use the IRtcEngine class instead.

During API calls, the SDK may return error codes and warning codes. See Error Codes and Warning Codes.

The IRtcEngine class is the entry point of the Agora SDK providing API methods for applications to quickly start a voice and video call or the interactive live audio and video streaming.
The IRtcEngineEventHandler class reports runtime events to the applications.
The IChannel class provides methods that enable real-time communications in a specified channel. By creating multiple IChannel objects, the user can join multiple channels.
The IChannelEventHandler class provides callbacks that report events and statistics of a specified channel.
The IAudioDeviceManager class allows for audio device interface testing.
The IVideoDeviceManager class allows for video device interface testing.

Core methods

Method	Description
createAgoraRtcEngine	Creates an RtcEngine object and returns the pointer.
initialize	Initializes the Agora SDK service.
release	Releases all IRtcEngine resources.
setChannelProfile	Sets the channel profile.
setClientRole [1/2]	Sets the role of the user (interactive live streaming only).
setClientRole [2/2]	Sets the role and level of the user (interactive live streaming only).
joinChannel [1/2]	Allows a user to join a channel.
joinChannel [2/2]	Allows a user to join a channel and set the publishing and subscribing states.
switchChannel [1/2]	Switches to a different channel in the interactive live streaming.
switchChannel [2/2]	Switches to a different channel and sets the subscribing state in the interactive live streaming.
leaveChannel	Allows a user to leave a channel.
renewToken	Renews the Token.
getConnectionState	Gets the current connection state of the SDK.

Core events

Event	Description
onConnectionStateChanged	Occurs when the connection state between the SDK and the server changes.
onJoinChannelSuccess	Occurs when a user joins a channel.
onRejoinChannelSuccess	Occurs when a user rejoins the channel.
onLeaveChannel	Occurs when a user leaves the channel.
onClientRoleChanged	Occurs when the user role switches successfully in the interactive live streaming.
onClientRoleChangeFailed	Occurs when the user role switch fails in the interactive live streaming.
onUserJoined	Occurs when a remote user (`COMMUNICATION`)/ host (`LIVE_BROADCASTING`) joins the channel.
onUserOffline	Occurs when a remote user (`COMMUNICATION`)/ host (`LIVE_BROADCASTING`) leaves the channel.
onNetworkTypeChanged	Occurs when the local network type changes.
onConnectionLost	Occurs when the SDK cannot reconnect to Agora's edge server 10 seconds after its connection to the server is interrupted.
onTokenPrivilegeWillExpire	Occurs when the token expires in 30 seconds.
onRequestToken	Occurs when the token expires.

Audio management

Method	Description
enableAudio	Enables the audio module.
disableAudio	Disables the audio module.
setAudioProfile	Sets the audio parameters and application scenarios.
adjustRecordingSignalVolume	Adjusts the volume of the signal captured by the microphone.
adjustLoopbackRecordingSignalVolume	Adjusts the volume of the signal captured by the sound card (for Windows and macOS only).
adjustUserPlaybackSignalVolume	Adjusts the playback signal volume of a specified remote user.
adjustPlaybackSignalVolume	Adjusts the playback signal volume of all remote users.
enableLocalAudio	Enables/Disables the local audio sampling.
muteLocalAudioStream	Stops/Resumes publishing the local audio stream.
muteRemoteAudioStream	Stops/Resumes subscribing to the audio stream of a specified user.
muteAllRemoteAudioStreams	Stops/Resumes subscribing to the audio streams of all remote users.

Video management

Method	Description
enableVideo	Enables the video module.
disableVideo	Disables the video module.
setVideoEncoderConfiguration	Sets the video encoder configuration.
setupLocalVideo	Initializes the local video view.
setupRemoteVideo	Initializes the video view of a remote user.
setLocalRenderMode	Updates the display mode of the local video view.
setRemoteRenderMode	Updates the display mode of the video view of a remote user.
startPreview	Starts the local video preview before joining the channel.
stopPreview	Stops the local video preview and disables video.
enableLocalVideo	Enables/Disables the local video capture.
muteLocalVideoStream	Stops/Resumes publishing the local video stream.
muteRemoteVideoStream	Stops/Resumes subscribing to the video stream of a specified user.
muteAllRemoteVideoStreams	Stops/Resumes subscribing to the video streams of all remote users.

Local media events

Event	Description
onLocalAudioStateChanged	Occurs when the local audio state changes.
onLocalVideoStateChanged	Occurs when the local video state changes.
onFirstLocalAudioFramePublished	Occurs when the first audio frame is published.
onFirstLocalVideoFramePublished	Occurs when the first video frame is published.
onFirstLocalVideoFrame	Occurs when the first local video frame is rendered.
onAudioPublishStateChanged	Occurs when the audio publishing state changes.
onVideoPublishStateChanged	Occurs when the video publishing state changes.

Remote media events

Event	Description
onRemoteAudioStateChanged	Occurs when the remote audio state changes.
onRemoteVideoStateChanged	Occurs when the remote video state changes.
onFirstRemoteVideoFrame	Occurs when the first remote video frame is rendered.
onFirstRemoteVideoDecoded	Occurs when the first remote video frame is received and decoded.
onAudioSubscribeStateChanged	Occurs when the audio subscribing state changes.
onVideoSubscribeStateChanged	Occurs when the audio subscribing state changes.
onUserMuteAudio	Occurs when a remote user's audio stream playback pauses/resumes.
onUserMuteVideo	Occurs when a remote user stops or resumes publishing the video stream.
onUserEnableVideo	Occurs when a specific remote user enables/disables the video module.
onUserEnableLocalVideo	Occurs when a specified remote user enables/disables the local video capturing function.

Statistics events

‍After joining a channel, SDK triggers this group of callbacks once every two seconds. We provide an advanced guide for these callbacks. For details, see Report In-call Statistics.

Event	Description
onRtcStats	Reports the statistics of the current call session.
onNetworkQuality	Reports the network quality of each user.
onLocalAudioStats	Reports the statistics of the local audio stream.
onLocalVideoStats	Reports the statistics of the local video stream.
onRemoteAudioStats	Reports the statistics of the audio stream from each remote user/host.
onRemoteVideoStats	Reports the statistics of the video stream from each remote user/host.

Video pre-process and post-process

Method	Description
setBeautyEffectOptions	Sets the image enhancement options.
enableVirtualBackground	Enables/Disables the virtual background feature.
enableRemoteSuperResolution	Enables/Disables the super resolution feature for a remote user's video. (beta feature)
setVideoDenoiserOptions	Sets video noise reduction.
setLowlightEnhanceOptions	Sets low-light enhancement.
setColorEnhanceOptions	Sets color enhancement.

Event	Description
onVirtualBackgroundSourceEnabled	Reports whether the virtual background feature is successfully enabled.
onUserSuperResolutionEnabled	Reports whether the super resolution feature is successfully enabled. (beta feature)

Multiple channels management

‍We provide an advanced guide on the applicable scenarios, implementation and considerations for this group of methods. For details, see Join multiple channels.

API	Description
createChannel	Initializes and gets an `IChannel` object. To join multiple channels, create multiple `IChannel` objects.
IChannel	Provides methods that enable real-time communications in a specified channel.
IChannelEventHandler	Provides callbacks that report events and statistics in a specified channel.

Screen capture

‍We provide an advanced guide on the applicable scenarios, implementation and considerations for this group of methods. For details, see Share the Screen.

Method	Description
getScreenCaptureSources	Gets a list of shareable screens and windows (for macOS and Windows only).
startScreenCaptureByDisplayId	Shares the whole or part of a screen by specifying the display ID (for macOS and Windows only).
startScreenCaptureByWindowId	Shares the whole or part of a window by specifying the window ID (for macOS and Windows only).
setScreenCaptureContentHint	Sets the content hint for screen sharing (for macOS and Windows only).
setScreenCaptureScenario	Sets the screen sharing scenario (for macOS and Windows only).
updateScreenCaptureParameters	Updates the screen sharing parameters (for macOS and Windows only).
updateScreenCaptureRegion	Updates the screen sharing region (for macOS and Windows only).
stopScreenCapture	Stops screen sharing (for macOS and Windows only).

Event	Description
onScreenCaptureInfoUpdated	Occurs when the screen sharing information is updated (for Windows only).

Music file playback and mixing

Method	Description
startAudioMixing	Starts playing and mixing the music file.
stopAudioMixing	Stops playing and mixing the music file.
pauseAudioMixing	Pauses playing and mixing the music file.
resumeAudioMixing	Resumes playing and mixing the music file.
adjustAudioMixingVolume	Adjusts the volume during audio mixing.
adjustAudioMixingPlayoutVolume	Adjusts the volume of audio mixing for local playback.
adjustAudioMixingPublishVolume	Adjusts the volume of audio mixing for remote playback.
setAudioMixingPitch	Sets the audio mixing pitch.
getAudioMixingPlayoutVolume	Gets the audio mixing volume for local playback.
getAudioMixingPublishVolume	Gets the audio mixing volume for publishing.
getAudioMixingCurrentPosition	Gets the playback position (ms) of the music file.
setAudioMixingPosition	Sets the playback position of the music file.
getAudioTrackCount	Gets the number of audio tracks of the current music file (for Android, iOS, and Windows only).
selectAudioTrack	Specifies the playback track of the current music file (for Android, iOS, and Windows only).
setAudioMixingPlaybackSpeed	Sets the playback speed of the current music file.
setAudioMixingDualMonoMode	Sets the channel mode of the current music file.

Event	Description
onAudioMixingStateChanged	Occurs when the state of the local user's audio mixing file changes.
onRemoteAudioMixingBegin	Occurs when a remote user starts audio mixing.
onRemoteAudioMixingEnd	Occurs when a remote user finishes audio mixing.
onAudioMixingStateChanged	Occurs when the state of the local user's audio mixing file changes.
onRemoteAudioMixingBegin	Occurs when a remote user starts audio mixing.
onAudioMixingFinished	Occurs when the local audio effect playback finishes.

Audio effect playback

Method	Description
getEffectsVolume	Gets the volume of the audio effects.
setEffectsVolume	Sets the volume of the audio effects.
setVolumeOfEffect	Sets the volume of the audio effect.
playEffect	Plays a specified audio effect.
stopEffect	Stops playing a specified audio effect.
stopAllEffects	Stops playing all audio effects.
preloadEffect	Preloads a specified audio effect file into the memory.
unloadEffect	Releases a specified audio effect from the memory.
pauseEffect	Pauses a specified audio effect.
pauseAllEffects	Pauses all audio effects.
resumeEffect	Resumes playing a specified audio effect.
resumeAllEffects	Resumes playing all audio effects.
getEffectCurrentPosition	Gets the playback position of the audio effect file.
setEffectPosition	Sets the playback position of an audio effect file.

Event	Description
onAudioEffectFinished	Occurs when the local audio effect playback finishes.

Audio file information

Method	Description
getAudioFileInfo	Gets the information of a specified audio file.
getEffectDuration	Gets the information of a specified audio file.

Event	Description
onRequestAudioFileInfo	Reports the information of an audio file.

Voice effect

Method	Description
setLocalVoicePitch	Changes the voice pitch of the local speaker.
enableLocalVoicePitchCallback	Enables reporting the voice pitch of the local user.
setLocalVoiceEqualization	Sets the local voice equalization effect.
setLocalVoiceReverb	Sets the local voice reverberation.
setVoiceBeautifierPreset	Sets an SDK preset voice beautifier effect.
setVoiceBeautifierParameters	Sets parameters for SDK preset voice beautifier effects.
setAudioEffectPreset	Sets an SDK preset audio effect.
setAudioEffectParameters	Sets parameters for SDK preset audio effects.
setVoiceConversionPreset	Sets an SDK preset voice conversion effect.

Event	Description
onLocalVoicePitchInHz	Reports the voice pitch of the local user.

Sound localization

Method	Description
enableSoundPositionIndication	Enables/Disables stereo panning for remote users.
setRemoteVoicePosition	Sets the sound position and gain of a remote user.

Media push

‍This group of methods apply to interactive live streaming only.

Method	Description
startRtmpStreamWithoutTranscoding	Starts pushing media streams to a CDN without transcoding.
startRtmpStreamWithTranscoding	Starts pushing media streams to a CDN and sets the transcoding configuration.
updateRtmpTranscoding	Updates the transcoding configuration.
stopRtmpStream	Stops pushing media streams to a CDN.

Event	Description
onRtmpStreamingStateChanged	Occurs when the state of the RTMP or RTMPS streaming changes.
onRtmpStreamingEvent	Reports events during the RTMP or RTMPS streaming.
onTranscodingUpdated	Occurs when the publisher's transcoding settings are updated.

Media stream relay across channels

‍This group of methods apply to interactive live streaming only.

Method	Description
startChannelMediaRelay	Starts to relay media streams across channels.
updateChannelMediaRelay	Updates the channels for media stream relay.
pauseAllChannelMediaRelay	Pauses the media stream relay to all destination channels.
resumeAllChannelMediaRelay	Resumes the media stream relay to all destination channels.
stopChannelMediaRelay	Stops the media stream relay.

Event	Description
onChannelMediaRelayStateChanged	Occurs when the state of the media stream relay changes.
onChannelMediaRelayEvent	Reports events during the media stream relay.

Audio volume indication

Method	Description
enableAudioVolumeIndication	Enables the reporting of users' volume indication.

Event	Description
onAudioVolumeIndication	Reports the volume information of users.
onActiveSpeaker	Occurs when the most active remote speaker is detected.

Face detection

‍This group of methods applies to Android and iOS only.

Method	Description
enableFaceDetection	Enables/Disables face detection for the local user.

Event	Description
onFacePositionChanged	Reports the face detection result of the local user.

Audio routing control

Method	Description
setDefaultAudioRouteToSpeakerphone	Sets the default audio route. (for Android and iOS only).
setEnableSpeakerphone	Enables/Disables the audio route to the speakerphone (for Android and iOS only).
isSpeakerphoneEnabled	Checks whether the speakerphone is enabled (for Android and iOS only).

Event	Description
onAudioRouteChanged	Occurs when the local audio route changes. (for Android, iOS and macOS only)

In-ear monitoring

Method	Description
enableInEarMonitoring	Enables in-ear monitoring (for Android and iOS only).
setInEarMonitoringVolume	Sets the volume of the in-ear monitor (for Android and iOS only).

Dual video stream mode

Method	Description
enableDualStreamMode	Sets the stream mode to single- (default) or dual-stream mode.
setRemoteVideoStreamType	Sets the remote user’s video stream type received by the local user when the remote user sends dual streams.
setRemoteDefaultVideoStreamType	Sets the default video-stream type for the video received by the local user when the remote user sends dual streams.

Stream fallback

‍We provide an advanced guide on the applicable scenarios, implementation and considerations for this group of methods. For details, see Video Stream Fallback.

Method	Description
setLocalPublishFallbackOption	Sets the fallback option for the published video stream under unreliable network conditions.
setRemoteSubscribeFallbackOption	Sets the fallback option for the remote stream under unreliable network conditions.
setRemoteUserPriority	Prioritizes a remote user's stream.

Event	Description
onLocalPublishFallbackToAudioOnly	Occurs: When the published media stream falls back to an audio-only stream due to poor network conditions.When the published media stream switches back to the video after the network conditions improve.
onRemoteSubscribeFallbackToAudioOnly	Occurs: When the remote media stream falls back to audio-only due to poor network conditions. When the remote media stream switches back to the video after the network conditions improve.

Pre-call network test

‍We provide an advanced guide on the applicable scenarios, implementation and considerations for this group of methods. For details, see Pre-call Test.

Method	Description
startEchoTest [2/3]	Starts an audio call loop test.
startEchoTest [3/3]	Starts an audio and video call loop test.
stopEchoTest	Stops the call loop test.
enableLastmileTest	Enables the network connection quality test.
disableLastmileTest	Disables the network connection quality test.
startLastmileProbeTest	Starts the last-mile network probe test.
stopLastmileProbeTest	Stops the last-mile network probe test.

Event	Description
onLastmileQuality	Reports the last mile network quality of the local user before the user joins the channel.
onLastmileProbeResult	Reports the last-mile network probe result.

Custom video renderer

Method	Description
setVideoSource	Sets a custom video source.
setLocalVideoRenderer	Customizes the local video renderer.
setRemoteVideoRenderer	Customizes the remote video renderer.

External video data (push-mode only)

Method	Description
setExternalVideoSource	Configures the external video source.
pushVideoFrame	Pushes the external video frame.

External audio data (push-mode only)

Method	Description
setExternalAudioSource	Configures the external audio source.
setExternalAudioSourceVolume	Sets the volume of the external audio frame in the specified position.
pushAudioFrame	Pushes the external audio frame to a specified position.

External audio sink (pull-mode only)

Method	Description
setExternalAudioSink	Sets the external audio sink.
pullAudioFrame	Pulls the external audio frame.

Raw audio data

Method	Description
registerAudioFrameObserver	Registers an audio frame observer object.
setRecordingAudioFrameParameters	Sets the audio capturing format for the onRecordAudioFrame callback.
setPlaybackAudioFrameParameters	Sets the audio playback format for the onPlaybackAudioFrame callback.
setMixedAudioFrameParameters	Sets the mixed audio format for the onMixedAudioFrame callback.

Event	Description
onRecordAudioFrame	Occurs when the captured audio frame is received.
onPlaybackAudioFrame	Occurs when the audio playback frame is received.
onPlaybackAudioFrameBeforeMixing	Occurs when the audio playback frame of a specified user is received.
onMixedAudioFrame	Occurs when the mixed captured and playback audio frame is received.

Raw video data

Method	Description
registerVideoFrameObserver	Registers a video frame observer object.

Event	Description
getObservedFramePosition	Sets the frame position for the video observer.
onCaptureVideoFrame	Occurs when the camera captured image is received.
onPreEncodeVideoFrame	Occurs each time the SDK receives a video frame before encoding.
onRenderVideoFrame	Processes the received image of the specified user (post-processing).
getVideoFormatPreference	Occurs each time the SDK receives a video frame and prompts you to set the video format.
getRotationApplied	Occurs each time the SDK receives a video frame and prompts you whether to rotate the captured video.
getMirrorApplied	Occurs each time the SDK receives a video frame and prompts you whether to mirror the captured video.

Local encoded video data

Method	Description
registerVideoEncodedFrameObserver	Registers a local encoded video frame observer.

Event	Description
onVideoEncodedFrame	Gets the local encoded video frame.

Media metadata

‍Do not implement getMaxMetadataSize, onReadyToSendMetadata, and onMetadataReceived in IRtcEngineEventHandler.

Method	Description
registerMediaMetadataObserver	Registers the metadata observer.

Event	Description
getMaxMetadataSize	Occurs when the SDK requests the maximum size of the metadata.
onReadyToSendMetadata	Occurs when the SDK is ready to receive and send metadata.
onMetadataReceived	Occurs when the local user receives the metadata.

Watermark

‍This group of methods apply to interactive live streaming only.

Method	Description
addVideoWatermark	Adds a watermark image to the local video stream.
clearVideoWatermarks	Removes the added watermark image from the video stream.

Video snapshot

Method	Description
takeSnapshot	Takes a snapshot of a video stream.

Event	Description
onSnapshotTaken	Reports the result of taking a video snapshot.

Encryption

Method	Description
enableEncryption	Enables/Disables the built-in encryption.
registerPacketObserver	Registers a packet observer.

Audio recorder

Method	Description
startAudioRecording	Starts an audio recording on the client.
stopAudioRecording	Stops an audio recording on the client.

Media recorder

Method	Description
getMediaRecorder	Gets the IMediaRecorder object.
startRecording	Starts recording the local audio and video.
stopRecording	Stops recording the local audio and video.
releaseRecorder	Releases the IMediaRecorder object.

Event	Description
onRecorderStateChanged	Occurs when the recording state changes.
onRecorderInfoUpdated	Occurs when the recording information is updated.

Camera control

Method	Description
switchCamera	Switches between front and rear cameras (for Android and iOS only).
isCameraTorchSupported	Checks whether the device supports enabling the flash (for Android and iOS only).
setCameraTorchOn	Sets whether to enable the flash (for Android and iOS only).

Event	Description
onCameraFocusAreaChanged	Occurs when the camera focus area changes.
onCameraExposureAreaChanged	Occurs when the camera exposure area changes.

Device manager

Method	Description
enumeratePlaybackDevices	Enumerates the audio playback devices (for macOS and Windows only).
enumerateRecordingDevices	Enumerates the audio capturing devices (for macOS and Windows only).
setPlaybackDevice	Sets the audio playback device using the device ID (for macOS and Windows only).
setRecordingDevice	Sets the audio capturing device using the device ID (for macOS and Windows only).
startPlaybackDeviceTest	Starts the audio playback device test (for Windows and macOS only).
stopPlaybackDeviceTest	Stops the audio playback device test (for macOS and Windows only).
startRecordingDeviceTest	Starts the audio capturing device test (for Windows and macOS only).
stopRecordingDeviceTest	Stops the capturing device test (for macOS and Windows only).
startAudioDeviceLoopbackTest	Starts the audio device loopback test (for Windows and macOS only).
stopAudioDeviceLoopbackTest	Stops the audio device loopback test (for macOS and Windows only).
setPlaybackDeviceVolume	Sets the volume of the audio playback device (for macOS and Windows only).
getPlaybackDeviceVolume	Gets the volume of the audio playback device (for macOS and Windows only).
setRecordingDeviceVolume	Sets the volume of the capturing device (for macOS and Windows only).
getRecordingDeviceVolume	Gets the volume of the capturing device (for macOS and Windows only).
setPlaybackDeviceMute	Mutes/Unmutes the audio playback device (for macOS and Windows only).
isApplicationMute	Gets the mute state of the application (for macOS and Windows only).
getDefaultDevice	Gets the default audio device of the system (for macOS and Windows only).
getPlaybackDeviceMute	Gets the mute state of the audio playback device (for macOS and Windows only).
setRecordingDeviceMute	Mutes/Unmutes the capturing device (for macOS and Windows only).
getRecordingDeviceMute	Gets the mute state of the capturing device (for macOS and Windows only).
followSystemPlaybackDevice	Sets the audio playback device used by the SDK to follow the system default audio playback device (for macOS and Windows only).
followSystemRecordingDevice	Sets the audio recording device used by the SDK to follow the system default audio recording device (for macOS and Windows only).
enumerateVideoDevices	Enumerates the video devices (for macOS and Windows only).
startDeviceTest	Starts the video-capture device test (for macOS and Windows only).
stopDeviceTest	Stops the video-capture device test (for macOS and Windows only).
getCount	Gets the total number of indexed video devices in the system (for macOS and Windows only).
getDevice	Gets the video-capture device that is in use (for macOS and Windows only).
setDevice	Sets the device with the device ID (for macOS and Windows only).

Event	Description
onAudioDeviceStateChanged	Occurs when the audio device state changes (for macOS and Windows only).
onAudioDeviceVolumeChanged	Occurs when the volume of the playback, microphone, or application changes.
onAudioDeviceTestVolumeIndication	Reports the result of an audio device test.
onVideoDeviceStateChanged	Occurs when the video device state changes (for macOS and Windows only).

Stream message

Method	Description
createDataStream	Creates a data stream.
sendStreamMessage	Sends data stream messages.

Event	Description
onStreamMessage	Occurs when the local user receives a remote data stream within five seconds.
onStreamMessageError	Occurs when the local user fails to receive the remote data stream.

Miscellaneous audio control

Method	Description
enableLoopbackRecording	Enables loopback audio capturing (for macOS and Windows only).
setAudioSessionOperationRestriction	Sets the operational permission of the SDK on the audio session (for iOS only).

Miscellaneous video control

Method	Description
setCameraCapturerConfiguration	Sets the camera capturer configuration.

Miscellaneous methods

Method	Description
setCloudProxy	Sets the Agora cloud proxy service.
enableDeepLearningDenoise	Enables/Disables noise suppression.
sendCustomReportMessage	Reports customized messages.
getCallId	Gets the current call ID.
rate	Allows the user to rate the call and is called after the call ends.
complain	Allows a user to complain about the call quality after a call ends.
getVersion	Gets the SDK version number.
setLogFile	Specifies an SDK output log file.
setLogFilter	Sets the output log level of the SDK.
setLogFileSize	Sets the log file size (KB).
getErrorDescription	Gets the warning or error description.
queryInterface	Gets the pointer to the device manager object.

Miscellaneous events

Event	Description
onWarning	Reports a warning during SDK runtime.
onError	Reports an error during SDK runtime.
onApiCallExecuted	Occurs when a method is executed.
onProxyConnected	Reports the proxy connection state.