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.

The API Reference version corresponds to the SDK version.

• The IRtcEngine class is the entry point of the Agora SDK providing API methods for applications to quickly start a voice/video communication or interactive broadcast.
• Methods in the RtcEngineParameters class will be moved under the IRtcEngine class in the future. For now, call the RtcEngineParameters(IRtcEngine& engine) or RtcEngineParameters(IRtcEngine* engine) method to create an RtcEngineParameters object before calling any method that belongs to the RtcEngineParameters class.
• The IRtcEngineEventHandler class reports runtime callbacks/events to the applications.

Methods

Core Methods

Core methods are used for creating an RTC engine and setting up a basic communication channel. This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Description
createAgoraRtcEngine	Creates the RTC engine object and returns the pointer.
initialize	Initializes the Agora SDK service.
release	Releases all IRtcEngine resources.
setChannelProfile	Sets the channel profile.
setClientRole	Sets the role of the user (Live Broadcast only).
joinChannel	Allows a user to join a channel.
leaveChannel	Allows a user to leave a channel.
renewToken	Renews the Token
enableWebSdkInteroperability	Enables interoperability with the Agora Web SDK. (Live Broadcast only.)

Core Audio

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Description
enableAudio	Enables the audio module.
disableAudio	Disables the audio module.
setAudioProfile	Sets the audio parameters and application scenarios.
adjustRecordingSignalVolume	Adjusts the recording volume.
adjustPlaybackSignalVolume	Adjusts the playback volume.
enableAudioVolumeIndication	Enables the onAudioVolumeIndication callback at a set time interval to report on which users are speaking and the speakers' volume.
enableLocalAudio	Enables/Disables the local audio sampling.
muteLocalAudioStream	Sends/Stops sending the local audio stream.
muteRemoteAudioStream	Receives/Stops receiving a specified remote user’s audio stream.
muteAllRemoteAudioStreams	Receives/Stops receiving all remote users' audio streams.
setDefaultMuteAllRemoteAudioStreams	Sets whether to receive audio streams by default.

Core Video

This group of methods is applicable to Video Communication and Interactive Broadcast.

Method	Description
enableVideo	Enables the video module.
disableVideo	Disables the video module.
setVideoEncoderConfiguration	Sets the video encoder configuration.
setupLocalVideo	Sets the local video view.
setupRemoteVideo	Sets the remote user's video view.
setLocalRenderMode	Sets the local video display mode.
setRemoteRenderMode	Sets the video display mode of a specified remote user.
startPreview	Starts the local video preview before joining the channel.
stopPreview	Stops the local video preview.
enableLocalVideo	Enables/Disables the local video capture.
muteLocalVideoStream	Sends/Stops sending the local video stream.
muteRemoteVideoStream	Receives/Stops receiving a specified remote video stream.
muteAllRemoteVideoStreams	Receives/Stops receiving all the video streams.
setDefaultMuteAllRemoteVideoStreams	Sets whether to receive the video streams by default.

In-ear Monitor

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Description
setInEarMonitoringVolume	Sets the volume of the in-ear monitor.

Audio Sound Effect

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Description
setLocalVoicePitch	Changes the voice pitch of the local speaker.
setLocalVoiceEqualization	Sets the local voice equalization effect.
setLocalVoiceReverb	Sets the local voice reverberation.

Music File Playback and Mixing

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

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.
getAudioMixingDuration	Gets the duration (ms) of the music file.
getAudioMixingCurrentPosition	Retrieves the playback position (ms) of the music file.
setAudioMixingPosition	Sets the playback position of the music file.

Audio Effect File Playback

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

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.

Audio Recorder

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

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

Loopback Recording

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Description
enableLoopbackRecording	Enables loopback recording.

Network-related Test

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Description
startEchoTest	Starts an audio call test.
stopEchoTest	Stops the audio call test.
enableLastmileTest	Enables the network connection quality test.
disableLastmileTest	Disables the network connection quality test.

Custom Video Module

• N/A

External Audio Data (Push-mode Only)

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Description
setExternalAudioSource	Configures the external audio source.
pushAudioFrame	Pushes the external audio frame.

External Video Data (Push-mode Only)

• N/A

Raw Audio Data

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Description
registerAudioFrameObserver	Registers an audio frame observer object.
setRecordingAudioFrameParameters	Sets the audio recording 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.

Raw Video Data

This group of methods is applicable to Video Communication and Interactive Broadcast.

Method	Description
registerVideoFrameObserver	Registers a video frame observer object.

Watermark

This group of methods is applicable only to Interactive Broadcast.

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

Stream Fallback

This group of methods is applicable only to Interactive Broadcast.

Method	Description
setLocalPublishFallbackOption	Sets the fallback option for the published video stream under unreliable conditions.
setRemoteSubscribeFallbackOption	Sets the fallback option for the remote stream under unreliable conditions.

Dual-stream Mode

This group of methods is applicable to Video Communication and Interactive Broadcast.

Method	Description
enableDualStreamMode	Sets the stream mode to single- (default) or dual-stream mode. (Live broadcast only.)
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.

Encryption

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Description
setEncryptionSecret	Enables built-in encryption with an encryption password before joining a channel.
setEncryptionMode	Sets the built-in encryption mode.
registerPacketObserver	Registers a packet observer.

Inject an Online Media Stream

This group of methods is applicable only to Interactive Broadcast.

Method	Description
addInjectStreamUrl	Adds an online media stream to a live broadcast.
removeInjectStreamUrl	Removes the online media stream from a live broadcast.

CDN Live Streaming

This group of methods is applicable only to Interactive Broadcast.

Method	Description
addPublishStreamUrl	Adds a CDN stream address.
removePublishStreamUrl	Removes a CDN stream address.
setLiveTranscoding	Sets the video layout and audio for CDN live.

Data Stream

This group of methods is applicable to Video Communication and Interactive Broadcast.

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

Miscellaneous Video Control

This group of methods is applicable to Video Communication and Interactive Broadcast.

Method	Description
setVideoQualityParameters	Sets the preferences for the video quality. (Live broadcast only).
setLocalVideoMirrorMode	Sets the local video mirror mode.

Camera Control

• N/A

Screen Sharing

This group of methods is applicable to Video Communication and Interactive Broadcast.

Method	Description
startScreenCapture	Starts screen sharing.
stopScreenCapture	Stops screen sharing.
updateScreenCaptureRegion	Updates the screen capture region.

Device Manager

Method	Description
enumerateVideoDevices	Enumerates the video devices.
startDeviceTest	Starts the video-capture device test.
stopDeviceTest	Stops the video-capture device test.
getCount	Retrieves the total number of the indexed video devices in the system.
getDevice	Retrieves the video-capture device that is in use
setDevice	Sets the device with the device ID.
enumeratePlaybackDevices	Enumerates the audio playback devices.
enumerateRecordingDevices	Enumerates the audio recording devices.
setPlaybackDevice	Sets the audio playback device using the device ID.
setRecordingDevice	Sets the audio recording device using the device ID.
startPlaybackDeviceTest	Starts the audio playback device test.
stopPlaybackDeviceTest	Stops the audio playback device test.
setPlaybackDeviceVolume	Sets the volume of the audio playback device.
getPlaybackDeviceVolume	Retrieves the volume of the audio playback device.
setRecordingDeviceVolume	Sets the volume of the microphone.
getRecordingDeviceVolume	Retrieves the volume of the microphone.
setPlaybackDeviceMute	Mutes the audio playback device.
getPlaybackDeviceMute	Retrieves the mute state of the audio playback device.
setRecordingDeviceMute	Mutes/Unmutes the microphone.
getRecordingDeviceMute	Retrieves the microphone’s mute status.
startRecordingDeviceTest	Starts the microphone test.
stopRecordingDeviceTest	Stops the microphone test.

Miscellaneous Methods

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Description
getCallId	Retrieves 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	Retrieves the SDK version number.
getErrorDescription	Retrieves the warning or error description.
setLogFile	Specifies an SDK output log file.
setLogFilter	Sets the output log level of the SDK.

Customized Methods

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Description
setParameters	Provides the technical preview functionalities or special customizations by configuring the SDK with JSON options.

Callbacks

Core Events

Callback	Description
onWarning	Occurs when a warning occurs during SDK runtime.
onError	Occurs when an error occurs during SDK runtime.
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 in a live broadcast.
onUserJoined	Occurs when a remote user joins the channel.
onUserOffline	Occurs when a remote user leaves the channel.
onConnectionInterrupted	Occurs when the connection between the SDK and the server is interrupted.
onConnectionLost	Occurs when the connection between the SDK and the server is lost.
onConnectionBanned	Occurs when your connection is banned by the Agora Server.
onApiCallExecuted	Occurs when a method is executed.
onTokenPrivilegeWillExpire	Occurs when the token expires in 30 seconds.
onRequestToken	Occurs when the token expires.

Media Events

Callback	Description
onAudioVolumeIndication	Reports which users are speaking and the speakers' volume.
onActiveSpeaker	Reports which user is the loudest speaker.
onFirstLocalAudioFrame	Occurs when the first local audio frame is sent.
onFirstRemoteAudioFrame	Occurs when the first remote audio frame is received.
onVideoStopped	Occurs when the video stops playing.
onFirstLocalVideoFrame	Occurs when the first local video frame is sent.
onFirstRemoteVideoDecoded	Occurs when the first video frame from a specific remote user is decoded.
onFirstRemoteVideoFrame	Occurs when the first remote video frame is rendered.
onUserMuteAudio	Occurs when a remote user's audio stream is muted/unmuted.
onUserMuteVideo	Occurs when a remote user's video stream palyback pauses/resumes.
onUserEnableVideo	Occurs when a remote user enables/disables the video module.
onUserEnableLocalVideo	Occurs when a remote user enables/disables his local video capture.
onVideoSizeChanged	Occurs when the video size or rotation of a specified remote user is changed.
onRemoteVideoStateChanged	Occurs when the remote video stream state is changed..

Fallback Events

Callback	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.

Device Events

Callback	Description
onAudioDeviceStateChanged	Occurs when the audio device state is changed.
onAudioDeviceVolumeChanged	Occurs when the volume of the playback, microphone, or application is changed.
onCameraReady	Occurs when camera is turned on and ready to capture video.
onCameraFocusAreaChanged	Occurs when the camera focus area changes.

Statistics Events

Callback	Description
onAudioQuality	Reports the audio quality of the current call is reported once every two seconds.
onRtcStats	Reports the statistics of the current call session once every two seconds.
onLastmileQuality	Reports the last mile network quality of the local user once every two seconds.
onNetworkQuality	Reports the network quality of each user once every two seconds.
onLocalVideoStats	Reports the statistics of the local video streams once every two seconds.
onRemoteVideoStats	Reports the statistics of the remote video streams once every two seconds.
onRemoteAudioTransportStats	Reports the statistics of the remote audio transmission once every two seconds.
onRemoteVideoTransportStats	Reports the statistics of the remote video transmission once every two seconds.

Audio Player Events

Callback	Description
onAudioMixingFinished	Occurs when the audio mixing file playback finishes.
onRemoteAudioMixingBegin	Occurs when a remote user starts audio mixing.
onRemoteAudioMixingEnd	Occurs when a remote user finishes audio mixing.
onAudioEffectFinished	Occurs when the local audio effect playback finishes.

CDN Live Streaming Events

Callback	Description
onStreamPublished	Occurs when a CDN live stream is published.
onStreamUnpublished	Occurs when a CDN live stream is unpublished. (CDN live only.)
onTranscodingUpdated	Occurs when the publisher's transcoding settings are updated.

Inject Stream URL Events

Callback	Description
onStreamInjectedStatus	Reports the status of the injected online media stream.

Stream Message Events

Callback	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.

Raw Audio Data Events

Callback	Description
onRecordAudioFrame	Occurs when the recorded 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 recorded and playback audio frame is received.

Raw Video Data Events

Callback	Description
onCaptureVideoFrame	Occurs when the camera captured image is received.

Miscellaneous Events

Callback	Description
onMediaEngineLoadSuccess	Occurs when the media engine is loaded.
onMediaEngineStartCallSuccess	Occurs when the media engine call starts.