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 v2.3.3, Agora C++ API Reference for All Platforms can be downloaded from Dash, see FAQ for details.

  • 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.
  • The IRtcEngineEventHandler class reports runtime events to the applications.

Channel Management

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 in a live broadcast.
setClientRole Sets the role of the user in a live broadcast.
joinChannel Allows a user to join a channel.
switchChannel Switches to a different channel in a live broadcast.
leaveChannel Allows a user to leave a channel.
renewToken Renews the Token.
enableWebSdkInteroperability Enables interoperability with the Agora Web SDK (Live Broadcast only).
getConnectionState Gets the current connection state of the SDK.

Channel 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 in a live broadcast.
onUserJoined Occurs when a remote user (Communication)/ host (Live Broadcast) joins the channel.
onUserOffline Occurs when a remote user (Communication)/ host (Live Broadcast) 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.

User Info Management

Method Description
registerLocalUserAccount Registers a user account.
joinChannelWithUserAccount Joins the channel with a user account.
getUserInfoByUserAccount Gets the user information by passing in the user account.
getUserInfoByUid Gets the user information by passing in the user ID.
Event Description
onLocalUserRegistered Occurs when the local user successfully registers a user account.
onUserInfoUpdated Occurs when the SDK gets the user ID and user account of the remote user.

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 recording volume.
adjustPlaybackSignalVolume Adjusts the playback volume of the voice.
enableLocalAudio Enables/Disables the local audio sampling.
muteLocalAudioStream Stops/Resumes sending the local audio stream.
muteRemoteAudioStream Stops/Resumes receiving the audio stream from a specified remote user.
muteAllRemoteAudioStreams Stops/Resumes receiving all remote users' audio streams.
setDefaultMuteAllRemoteAudioStreams Stops/Resumes receiving all remote users' audio streams by default.

Video Management

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 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 and disables video.
enableLocalVideo Enables/Disables the local video capture.
muteLocalVideoStream Stops/Resumes sending the local video stream.
muteRemoteVideoStream Stops/Resumes receiving the video stream from a specified remote user.
muteAllRemoteVideoStreams Stops/Resumes receiving all video stream from a specified remote user.
setDefaultMuteAllRemoteVideoStreams Stops/Resumes receiving all remote users' video streams by default.

Local Media Events

Event Description
onLocalAudioStateChanged Occurs when the local audio state changes.
onLocalVideoStateChanged Occurs when the local video state changes.
onFirstLocalAudioFrame Occurs when the first local audio frame is sent.
onFirstLocalVideoFrame Occurs when the first local video frame is sent.

Remote Media Events

Event Description
onRemoteAudioStateChanged Occurs when the remote audio state changes.
onRemoteVideoStateChanged Occurs when the remote video state changes.
onUserMuteAudio Occurs when a remote user's audio stream playback pauses/resumes.
onUserMuteVideo Occurs when a remote user's video stream playback pauses/resumes.
onFirstRemoteAudioFrame Occurs when the first remote audio frame is received.
onFirstRemoteAudioDecoded Occurs when the SDK decodes the first remote audio frame for playback.
onFirstRemoteVideoFrame Occurs when the first remote video frame is rendered.

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 In-call Stats.

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 streams.
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 (for Android and iOS only).

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
startScreenCaptureByDisplayId Shares the whole or part of a screen by specifying the display ID (for macOS only).
startScreenCaptureByScreenRect Shares the whole or part of a screen by specifying the screen rect.
startScreenCaptureByWindowId Shares the whole or part of a window by specifying the window ID.
setScreenCaptureContentHint Sets the content hint for screen sharing.
updateScreenCaptureParameters Updates the screen sharing parameters.
updateScreenCaptureRegion Updates the screen sharing region.
stopScreenCapture Stops screen sharing.

Audio 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.。
getAudioMixingPlayoutVolume Gets the audio mixing volume for local playback.
getAudioMixingPublishVolume Gets the audio mixing volume for publishing.
getAudioMixingDuration Gets the duration (ms) of the music file.
getAudioMixingCurrentPosition Gsts the playback position (ms) of the music file.
setAudioMixingPosition Sets the playback position of the 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.

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.
Event Description
onAudioEffectFinished Occurs when the local audio effect playback finishes.

Voice Changer and Reverberation

Method Description
setLocalVoiceChanger Sets the local voice changer option.
setLocalVoiceReverbPreset Sets the preset local voice reverberation effect.
setLocalVoicePitch Changes the voice pitch of the local speaker.
setLocalVoiceEqualization Sets the local voice equalization effect.
setLocalVoiceReverb Sets the local voice reverberation.

Sound Position Indication

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

CDN Publisher

This group of methods apply to Live Broadcast only.

Method Description
setLiveTranscoding Sets the video layout and audio for CDN live.
addPublishStreamUrl Adds a CDN stream address.
removePublishStreamUrl Removes a CDN stream address.
Event Description
onRtmpStreamingStateChanged Occurs when the state of the RTMP streaming changes.
onTranscodingUpdated Occurs when the publisher's transcoding settings are updated.

Media Stream Relay Across Channels

Method Description
startChannelMediaRelay Starts to relay media streams across channels.
updateChannelMediaRelay Updates the channels for media stream relay.
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 onAudioVolumeIndication callback at a set time interval to report on which users are speaking and the speakers' volume.
Event Description
onAudioVolumeIndication Reports which users are speaking and the speakers' volume.
onActiveSpeaker Reports which user is the loudest speaker.

Audio Routing Control

Method Description
setDefaultAudioRouteToSpeakerphone Sets the default audio playback route (for Android and iOS only).
setEnableSpeakerphone Enables/Disables the audio playback 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 and iOS only).

In-ear Monitoring

Method Description
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 (for 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.

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 Conduct a Last-mile Test.

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

  • N/A

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.
pushAudioFrame Pushes the external audio frame.

External Audio Sink (Pull-mode only)

This group of methods are for Windows 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 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.
Event 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

Method Description
registerVideoFrameObserver Registers a video frame observer object.
Event Description
onCaptureVideoFrame Occurs when the camera captured image is received.
onRenderVideoFrame Processes the received image of the specified user (post-processing).

Media Metadata

This group of methods apply to Live Broadcast only. 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 Live Broadcast only.

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

Encryption

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.

Audio Recorder

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

Inject an Online Media Stream

  • This group of methods apply to Live Broadcast only.
  • We provide an advanced guide on the applicable scenarios, implementation and considerations for this group of methods. For details, see Inject an Online Media Stream.
Method Description
addInjectStreamUrl Adds an online media stream to a live broadcast.
removeInjectStreamUrl Removes the online media stream from a live broadcast.
Event Description
onStreamInjectedStatus Reports the status of the injected online media stream.

Camera Control

Method Description
switchCamera Switches between front and rear cameras (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

This group of methods are for Windows only.

Method Description
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.
startRecordingDeviceTest Starts the recording device test.
stopRecordingDeviceTest Stops the recording device test.
startAudioDeviceLoopbackTest Starts the audio device loopback test.
stopAudioDeviceLoopbackTest Stops the audio device loopback test.
setPlaybackDeviceVolume Sets the volume of the audio playback device.
getPlaybackDeviceVolume Gets the volume of the audio playback device.
setRecordingDeviceVolume Sets the volume of the recording device.
getRecordingDeviceVolume Gets the volume of the recording device.
setPlaybackDeviceMute Mutes/Unmutes the audio playback device.
getPlaybackDeviceMute Gets the mute state of the audio playback device.
setRecordingDeviceMute Mutes/Unmutes the recording device.
getRecordingDeviceMute Gets the mute state of the recording device.
enumerateVideoDevices Enumerates the video devices.
startDeviceTest Starts the video-capture device test.
stopDeviceTest Stops the video-capture device test.
getCount Gets the total number of indexed video devices in the system.
getDevice Gets the video-capture device that is in use.
setDevice Sets the device with the device ID.
Event Description
onAudioDeviceStateChanged Occurs when the audio device state changes.
onAudioDeviceVolumeChanged Occurs when the volume of the playback, microphone, or application changes.
onVideoDeviceStateChanged Occurs when the video device state changes.

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 Video Control

Method Description
enableLoopbackRecording Enables loopback recording (for macOS and Windows only).
setAudioSessionOperationRestriction Sets the audio session’s operational restriction (for iOS only).

Miscellaneous Audio Control

Method Description
setLocalVideoMirrorMode Sets the local video mirror mode.
setCameraCapturerConfiguration Sets the camera capturer configuration.

Miscellaneous Methods

Method Description
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.

Customized Methods

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