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:
- During API calls, the SDK may returns error codes and warning codes. See Error Codes and Warning Codes.
- 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. |
| 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. |
| 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. |