API Overview

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.

Note:
  • IAgoraRtcEngine provides the main methods that can be invoked by your application.
  • IAgoraRtcEngineEventHandler reports runtime events to the application.
  • IAgoraRtcChannel provides methods that enable real-time communications in a specified channel. By creating multiple IAgoraRtcChannel objects, users can join multiple channels at the same time.
  • IAgoraRtcChannelEventHandler provides callbacks that report events and statistics of a specified channel.

Core methods

Method Description
CreateAgoraRtcEngine Creates the IAgoraRtcEngine object.
Initialize Creates and initializes IAgoraRtcEngine .
Dispose Releases the IAgoraRtcEngine, IAgoraRtcAudioPlaybackDeviceManager, IAgoraRtcAudioRecordingDeviceManager and IAgoraRtcVideoDeviceManager instance.
SetChannelProfile Sets the channel profile.
SetClientRole [1/2] Sets the client role.
SetClientRole [2/2] Sets the user role and level in an interactive live streaming channel.
JoinChannel [1/2] Joins a channel.
JoinChannel [2/2] Joins a channel with the user ID, and configures whether to automatically subscribe to the audio or video streams.
SwitchChannel [1/2] Switches to a different channel.
SwitchChannel [2/2] Switches to a different channel, and configures whether to automatically subscribe to audio or video streams in the target channel.
LeaveChannel Leaves a channel.
RenewToken Gets a new token when the current token expires after a period of time.
GetConnectionState Gets the current connection state of the SDK.

Core events

Event Description
OnConnectionStateChanged Occurs when the network connection state changes.
OnJoinChannelSuccess Occurs when a user joins a channel.
OnRejoinChannelSuccess Occurs when a user rejoins the channel.
OnLeaveChannel Occurs when a user leaves a channel.
OnClientRoleChanged Occurs when the user role switches 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 profile and audio scenario.
AdjustLoopbackRecordingSignalVolume Adjusts the volume of the signal captured by the sound card.
AdjustRecordingSignalVolume Adjusts the capturing signal volume.
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 capture.
MuteLocalAudioStream Stops or resumes publishing the local audio stream.
MuteRemoteAudioStream Stops or resumes subscribing to the audio stream of a specified user.
MuteAllRemoteAudioStreams Stops or 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 [2/2] Updates the display mode of the local video view.
SetRemoteRenderMode [2/2] Updates the display mode of the video view of a remote user.
StartPreview Enables the local video preview.
StopPreview Stops the local video preview.
EnableLocalVideo Enables/Disables the local video capture.
MuteLocalVideoStream Stops or resumes publishing the local video stream.
MuteRemoteVideoStream Stops or resumes subscribing to the video stream of a specified user.
MuteAllRemoteVideoStreams Stops or resumes subscribing to the video streams of all remote users.

Local media events

Event Description
OnLocalAudioStateChanged Occurs when the local audio stream state changes.
OnLocalVideoStateChanged Occurs when the local video stream 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.
OnAudioSubscribeStateChanged Occurs when the audio subscribing state changes.
OnVideoSubscribeStateChanged Occurs when the video subscribing state changes.
OnUserMuteAudio Occurs when a remote user (in the communication profile)/ host (in the live streaming profile) joins the channel.
OnUserMuteVideo Occurs when a remote user's video stream playback pauses/resumes.
OnUserEnableVideo Occurs when a remote user enables/disables the video module.
OnUserEnableLocalVideo Occurs when a specific 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.

Event Description
OnRtcStats Reports the statistics of the current call.
OnNetworkQuality Reports the last mile network quality of each user in the channel.
OnLocalAudioStats Reports the statistics of the local audio stream.
OnLocalVideoStats Reports the statistics of the local video stream.
OnRemoteAudioStats Reports the transport-layer statistics of each remote audio stream.
OnRemoteVideoStats Reports the transport-layer statistics of each remote video stream.

Video pre-processing and post-processing

Method Description
SetBeautyEffectOptions Sets the image enhancement options.
EnableVirtualBackground Enables/Disables the virtual background. (beta feature)
SetVideoDenoiserOptions Sets video noise reduction.
SetLowlightEnhanceOptions Sets low-light enhancement.
SetColorEnhanceOptions Sets color enhancement.
Event Description
OnVirtualBackgroundSourceEnabled Reports whether virtual background is successfully enabled. (beta feature)

Multiple channels management

API Description
CreateChannel Creates and gets an IAgoraRtcChannel object.
IAgoraRtcChannel Provides methods that enable real-time communications in an
IAgoraRtcChannelEventHandler The SDK uses IAgoraRtcChannelEventHandler to send IAgoraRtcChannel event notifications to your app.

Screen share API

Method Description
StartScreenCaptureByDisplayId Shares the screen by specifying the display ID.
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.
Event Description
OnScreenCaptureInfoUpdated Occurs when the screen sharing information is updated.

Music file playback and mixing

Method Description
StartAudioMixing [2/2] Starts playing 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 publishing.
SetAudioMixingPitch Sets the pitch of the local music file.
GetAudioMixingPlayoutVolume Retrieves the audio mixing volume for local playback.
GetAudioMixingPublishVolume Retrieves the audio mixing volume for publishing.
GetAudioMixingDuration Retrieves the duration (ms) of the music file.
GetAudioMixingCurrentPosition Retrieves the playback position (ms) of the music file.
SetAudioMixingPosition Sets the audio mixing position.
GetAudioTrackCount Gets the audio track index of the current music file.
SelectAudioTrack Specified the playback track of the current music file.
SetAudioMixingPlaybackSpeed Sets the channel mode of the current music file.
SetAudioMixingDualMonoMode Sets the channel mode of the current music file.
Event Description
OnAudioMixingStateChanged Occurs when the playback state of the music file changes.
OnRemoteAudioMixingBegin Occurs when a remote user starts audio mixing.
OnRemoteAudioMixingEnd Occurs when a remote user finishes audio mixing.

Audio effect file playback

Method Description
GetEffectsVolume Retrieves the volume of the audio effects.
SetEffectsVolume Sets the volume of the audio effects.
SetVolumeOfEffect Sets the volume of a specified audio effect.
PlayEffect [2/2] Plays the specified local or online audio effect file.
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 preloaded 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 Retrieves the duration of the audio effect file.
SetEffectPosition Sets the playback position of an audio effect file.
GetEffectCurrentPosition Retrieves the playback position of the audio effect file.
Event Description
OnAudioEffectFinished Occurs when the playback of the local audio effect file finishes.

Audio file info

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.
SetLocalVoiceEqualization Sets the local voice equalization effect.
SetLocalVoiceReverb Sets the local voice reverberation.
SetVoiceBeautifierPreset Sets a preset voice beautifier effect.
SetVoiceBeautifierParameters Sets parameters for the preset voice beautifier effects.
SetAudioEffectPreset Sets an SDK preset audio effect.
SetAudioEffectParameters Sets parameters for SDK preset audio effects.
SetVoiceConversionPreset Sets a preset voice beautifier effect.

Sound localization

Method Description
EnableSoundPositionIndication Enables/Disables stereo panning for remote users.
SetRemoteVoicePosition Sets the 2D position (the position on the horizontal plane) of the remote user's voice.

CDN publisher

This method applies only to interactive live streaming.

Method Description
StartRtmpStreamWithoutTranscoding Starts pushing media streams to a CDN without transcoding.
StartRtmpStreamWithTranscoding Starts Media Push and sets the transcoding configuration.
UpdateRtmpTranscoding Updates the transcoding configuration.
StopRtmpStream Stops pushing media streams to a CDN.
Event Description
OnRtmpStreamingStateChanged Occurs when the media push state changes.
OnRtmpStreamingEvent Reports events during the media push.
OnTranscodingUpdated Occurs when the publisher's transcoding is updated.

Channel media stream relay

Method Description
StartChannelMediaRelay Starts relaying media streams across channels. This method can be used to implement scenarios such as co-host 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. Once the relay stops, the host quits all the destination channels.
Event Description
OnChannelMediaRelayStateChanged Occurs when the state of the media stream relay changes.
OnChannelMediaRelayEvent Reports events during the media stream relay.

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 speaker is detected.

Dual video stream mode

Method Description
EnableDualStreamMode Enables/Disables dual-stream mode.
SetRemoteVideoStreamType Sets the stream type of the remote video.
SetRemoteDefaultVideoStreamType Sets the default stream type of remote video streams.

Video stream fallback

Method Description
SetLocalPublishFallbackOption Sets the fallback option for the published video stream based on the network conditions.
SetRemoteSubscribeFallbackOption Sets the fallback option for the remotely subscribed video stream based on the 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.
OnRemoteSubscribeFallbackToAudioOnly Occurs when the remote media stream falls back to the audio-only stream due to poor network conditions or switches back to the video stream after the network conditions improve.

Pre-call network test

Method Description
StartEchoTest [2/3] Starts an audio call test.
StartEchoTest [3/3] Starts an audio and video call loop 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 once every two seconds.
OnLastmileProbeResult Reports the last mile network probe result.

External video data (push-mode only)

Method Description
SetExternalVideoSource Configures the external video source.
PushVideoFrame Pushes the external raw video frame to the SDK.

External audio data (push-mode only)

Method Description
SetExternalAudioSource Sets the external audio source.
SetExternalAudioSourceVolume Sets the volume of the external audio frame in the specified position.
PushAudioFrame Pushes the external audio frame.

External audio sink (pull-mode only)

Method Description
SetExternalAudioSink Sets the external audio sink.
PullAudioFrame Pulls the remote audio data.

Raw audio data

Method Description
RegisterAudioFrameObserver Registers an audio frame observer object.
UnRegisterAudioFrameObserver Unregisters an audio observer.
SetRecordingAudioFrameParameters Sets the format of the captured raw audio data.
SetPlaybackAudioFrameParameters Sets the audio data format for playback.
SetMixedAudioFrameParameters Sets the format of mixed audio.
Event Description
OnRecordAudioFrame Gets the captured audio frame.
OnPlaybackAudioFrame Gtes the audio frame for playback.
OnPlaybackAudioFrameBeforeMixing Retrieves the audio frame of a specified user before mixing.
OnMixedAudioFrame Retrieves the mixed captured and playback audio frame.
IsMultipleChannelFrameWanted Determines whether to receive audio data from multiple channels.
OnPlaybackAudioFrameBeforeMixingEx Gets the before-mixing playback audio frame from multiple channels.

Raw video data

Method Description
RegisterVideoFrameObserver Registers a video frame observer object.
UnRegisterVideoFrameObserver Unregisters the video frame observer.
Event Description
GetObservedFramePosition Sets the frame position for the video observer.
OnCaptureVideoFrame Occurs each time the SDK receives a video frame captured by the local camera.
OnPreEncodeVideoFrame Occurs each time the SDK receives a video frame before encoding.
OnRenderVideoFrame Occurs each time the SDK receives a video frame sent by the remote user.
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 or not to mirror the captured video.
IsMultipleChannelFrameWanted Sets whether to get video data from multiple channels in the multi-channel scenario.
OnRenderVideoFrameEx Gets the video frame from multiple channels.

Media metadata

This method applies only to interactive live streaming.

Method Description
RegisterMediaMetadataObserver Registers the metadata observer.
UnRegisterMediaMetadataObserver Unregisters the specified metadata observer.
SetMaxMetadataSize Sets the maximum size of the media metadata.
SendMetadata Sends media metadata.
Event Description
OnReadyToSendMetadata Occurs when the SDK is ready to send metadata.
OnMetadataReceived Occurs when the local user receives the metadata.

Watermark

This method applies only to interactive live streaming.

Method Description
AddVideoWatermark [2/2] Adds a watermark image to the local video.
ClearVideoWatermarks Removes the 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.

Audio recorder

Method Description
StartAudioRecording [3/3] Starts audio recording on the client.
StopAudioRecording Stops the audio recording on the client.

Audio and video recording

Method Description
StartRecording Starts recording the local audio and video.
StopRecording Stops recording the local audio and video
Event Description
OnRecorderStateChanged Occurs when the local audio and video recording state changes.
OnRecorderInfoUpdated Occurs when the recording information is updated.

Device management

Method Description
EnumeratePlaybackDevices Enumerates the audio playback devices.
EnumerateRecordingDevices Enumerates the audio capture devices.
SetPlaybackDevice Sets the audio playback device.
SetRecordingDevice Sets the audio capture device.
StartPlaybackDeviceTest Starts the audio playback device test.
StopPlaybackDeviceTest Stops the audio playback device test.
StartRecordingDeviceTest Starts the audio capture device test.
StopRecordingDeviceTest Stops the audio capture device test.
StartAudioDeviceLoopbackTest Starts an audio device loopback test.
StopAudioDeviceLoopbackTest Stops the audio device loopback 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 audio capture device.
GetRecordingDeviceVolume Retrieves the volume of the audio recording device.
SetPlaybackDeviceMute Mutes the audio playback device.
GetPlaybackDeviceMute Retrieves whether the audio playback device is muted.
SetRecordingDeviceMute Sets the mute status of the audio capture device.
GetRecordingDeviceMute Gets the microphone's mute status.
FollowSystemPlaybackDevice Sets the audio playback device used by the SDK to follow the system default audio playback device.
FollowSystemRecordingDevice Sets the audio recording device used by the SDK to follow the system default audio recording device.
EnumerateVideoDevices Enumerates the video devices.
StartDeviceTest Starts the video capture device test.
StopDeviceTest Stops the video capture device test.
GetDevice Retrieves the current video capture device.
SetDevice Specifies the video capture device with the device ID.
Event Description
OnAudioDeviceStateChanged Occurs when the audio device state changes.
OnAudioDeviceVolumeChanged Occurs when the volume on the playback or audio capture device, or the volume in the application changes.
OnAudioDeviceTestVolumeIndication Reports the result of an audio device test.
OnVideoDeviceStateChanged Occurs when the video device state changes.

Stream message

Method Description
CreateDataStream [2/2] Creates a data stream.
SendStreamMessage Sends data stream messages.
Event Description
OnStreamMessage Occurs when the local user receives the data stream from the remote user.
OnStreamMessageError Occurs when the local user does not receive the data stream from the remote user.

Miscellaneous audio control

Method Description
EnableLoopbackRecording Enables loopback audio capturing.

Miscellaneous video control

Method Description
SetCameraCapturerConfiguration Sets the camera capture configuration.

Miscellaneous methods

Method Description
SetCloudProxy Sets the Agora cloud proxy service.
EnableDeepLearningDenoise Enables/Disables deep-learning noise reduction.
SendCustomReportMessage Reports customized messages.
GetCallId Retrieves the call ID.
Rate Allows a user to rate a call after the call ends.
Complain Allows a user to complain about the call quality after a call ends.
GetVersion Gets the SDK version.
GetErrorDescription Gets the warning or error description.

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 by the SDK.
OnProxyConnected Reports the proxy connection state.