Voice SDK v3.7.1 API Reference for All Platforms (C++)
Voice SDK v3.7.1 API Reference for All Platforms (C++) Documentation

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, Voice SDK v3.7.1 API Reference for All Platforms (C++) can be downloaded from Dash, see FAQ for details.
  • 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.
getEffectDuration Gets the duration of the audio effect file.
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.
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 deep-learning noise reduction.
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.