API Overview
Agora provides ensured quality of experience (QoE) for worldwide Internet-based voice and video communications through SD-RTN™.
Channel management
Method | Description |
---|---|
sharedEngineWithAppId | Creates and initializes AgoraRtcEngineKit. |
sharedEngineWithConfig | Creates and initializes AgoraRtcEngineKit. |
destroy | Releases the AgoraRtcEngineKit instance. |
setChannelProfile | Sets the channel profile. |
joinChannelByToken [1/4] | Joins a channel. |
joinChannelByToken [2/4] | Joins a channel with media options. |
updateChannelWithMediaOptions | Updates the channel media options after joining the channel. |
leaveChannel [1/2] | Leaves a channel. |
leaveChannel [2/2] | Sets channel options and leaves the channel. |
renewToken | Gets a new token when the current token expires after a period of time. |
setClientRole [1/2] | Sets the client role. |
setClientRole [2/2] | Sets the user role and level in an interactive live streaming channel. |
getConnectionState | Gets the current connection state of the SDK. |
Channel events
Event | Description |
---|---|
didJoinChannel | Occurs when a user joins a channel. |
didRejoinChannel | Occurs when a user rejoins the channel. |
didClientRoleChanged | Occurs when the user role switches during the interactive live streaming. |
didClientRoleChangeFailed | Occurs when the user role switch fails in the interactive live streaming. |
didLeaveChannelWithStats | Occurs when a user leaves a channel. |
didJoinedOfUid | Occurs when a remote user (COMMUNICATION)/ host (LIVE_BROADCASTING) joins the channel. |
didOfflineOfUid | Occurs when a remote user (in the communication profile)/ host (in the live streaming profile) leaves the channel. |
networkTypeChangedToType | Occurs when the local network type changes. |
uplinkNetworkInfoUpdate | Occurs when the uplink network information changes. |
rtcEngineConnectionDidLost | Occurs when the SDK cannot reconnect to Agora's edge server 10 seconds after its connection to the server is interrupted. |
connectionChangedToState | Occurs when the network connection state changes. |
rtcEngineRequestToken | Occurs when the token expires. |
tokenPrivilegeWillExpire | Occurs when the token expires in 30 seconds. |
didOccurError | Reports an error during SDK runtime. |
Audio management
Method | Description |
---|---|
enableAudio | Enables the audio module. |
disableAudio | Disables the audio module. |
setAudioProfile [2/2] | Sets the audio parameters and application scenarios. |
setAudioScenario | Sets audio scenarios. |
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. |
adjustLoopbackSignalVolume | Adjusts the volume of the signal captured by the sound card. |
adjustCustomAudioPublishVolume | Adjusts the volume of the custom external audio source when it is published in the channel. |
muteRecordingSignal | Whether to mute the recording signal. |
enableLocalAudio | Enables/Disables the local audio capture. |
Video management
Method | Description |
---|---|
enableVideo | Enables the video module. |
disableVideo | Disables the video module. |
setRenderMode | Sets the render mode of the media player. |
setView | Sets the view. |
setVideoEncoderConfiguration | Sets the video encoder configuration. |
startPreview | Enables the local video preview. |
stopPreview | Stops the local video preview. |
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. |
enableLocalVideo | Enables/Disables the local video capture. |
muteLocalVideoStream | Stops or resumes publishing the local video stream. |
muteRemoteVideoStream | Cancels or resumes subscribing to the specified remote user's video stream. |
muteAllRemoteVideoStreams | Stops or resumes subscribing to the video streams of all remote users. |
enableInstantMediaRendering | Enables audio and video frame instant rendering. |
startMediaRenderingTracing | Enables tracing the video frame rendering process. |
Event | Description |
---|---|
videoRenderingTracingResultOfUid | Video frame rendering event callback. |
Capture screenshots
Method | Description |
---|---|
takeSnapshot | Takes a snapshot of a video stream. |
Event | Description |
---|---|
snapshotTaken | Reports the result of taking a video snapshot. |
Subscribing to and publishing audio and video streams
Method | Description |
---|---|
setSubscribeAudioBlocklist | Set the blocklist of subscriptions for audio streams. |
setSubscribeAudioAllowlist | Sets the allowlist of subscriptions for audio streams. |
setSubscribeVideoBlocklist | Set the blocklist of subscriptions for video streams. |
setSubscribeVideoAllowlist | Set the allowlist of subscriptions for video streams. |
muteLocalAudioStream | Stops or resumes publishing the local audio stream. |
muteRemoteAudioStream | Cancels or resumes subscribing to the specified remote user's audio stream. |
muteAllRemoteAudioStreams | Stops or resumes subscribing to the audio streams of all remote users. |
enableLocalVideo | Enables/Disables the local video capture. |
muteLocalVideoStream | Stops or resumes publishing the local video stream. |
muteRemoteVideoStream | Cancels or resumes subscribing to the specified remote user's video stream. |
muteAllRemoteVideoStreams | Stops or resumes subscribing to the video streams of all remote users. |
setRemoteVideo | Options for subscribing to remote video streams. |
Media player
For more methods about the media player, see AgoraRtcMediaPlayerProtocol.
Method | Description |
---|---|
createMediaPlayerWithDelegate | Creates one AgoraRtcMediaPlayerProtocol instance. |
createMediaPlayerCacheManager | Creates one AgoraRtcMediaPlayerCacheManagerProtocol instance. |
AgoraRtcMediaPlayerProtocol | This class provides media player functions and supports multiple instances. |
AgoraRtcMediaPlayerCacheManagerProtocol | This class provides methods to manage cached media files. |
AgoraRtcMediaPlayerDelegate | Provides callbacks for media players. |
Local media events
Event | Description |
---|---|
localAudioStateChanged | Occurs when the local audio stream state changes. |
localVideoStateChangedOfState | Occurs when the local video stream state changes. |
firstLocalAudioFramePublished | Occurs when the first audio frame is published. |
firstLocalVideoFramePublishedWithElapsed | Occurs when the first video frame is published. |
didAudioPublishStateChange | Occurs when the audio publishing state changes. |
didVideoPublishStateChange | Occurs when the video publishing state changes. |
Remote media events
Event | Description |
---|---|
remoteAudioStateChangedOfUid | Occurs when the remote audio state changes. |
remoteVideoStateChangedOfUid | Occurs when the remote video stream state changes. |
firstRemoteVideoFrameOfUid | Occurs when the renderer receives the first frame of the remote video. |
firstRemoteVideoDecodedOfUid | Occurs when the first remote video frame is received and decoded. |
didAudioSubscribeStateChange | Occurs when the audio subscribing state changes. |
didVideoSubscribeStateChange | Occurs when the video subscribing state changes. |
didAudioMuted | Occurs when a remote user (in the communication profile) or a host (in the live streaming profile) stops/resumes sending the audio stream. |
didVideoMuted | Occurs when a remote user stops or resumes publishing the video stream. |
didVideoEnabled | Occurs when a remote user enables or disables the video module. |
didLocalVideoEnabled | Occurs when a specific remote user enables/disables the local video capturing function. |
Statistics events
Event | Description |
---|---|
reportRtcStats | Reports the statistics of the current call. |
networkQuality | Reports the last mile network quality of each user in the channel. |
localAudioStats | Reports the statistics of the local audio stream. |
localVideoStats | Reports the statistics of the local video stream. |
remoteAudioStats | Reports the statistics of the audio stream sent by each remote users. |
remoteVideoStats | Reports the statistics of the video stream sent by each remote users. |
Video pre-process and post-process
Method | Description |
---|---|
setBeautyEffectOptions | Sets the image enhancement options. |
enableVirtualBackground | Enables/Disables the virtual background. |
setColorEnhanceOptions | Sets color enhancement. |
setLowlightEnhanceOptions | Sets low-light enhancement. |
setVideoDenoiserOptions | Sets video noise reduction. |
In-ear monitoring
Method | Description |
---|---|
enableInEarMonitoring [2/2] | Enables in-ear monitoring. |
setInEarMonitoringVolume | Sets the volume of the in-ear monitor. |
setEarMonitoringAudioFrameParametersWithSampleRate | Sets the format of the in-ear monitoring raw audio data. |
Event | Description |
---|---|
onEarMonitoringAudioFrame | Gets the in-ear monitoring audio frame. |
getEarMonitoringAudioParams | Sets the audio format for the onEarMonitoringAudioFrame callback. |
Music file playback and mixing
Method | Description |
---|---|
startAudioMixing [1/2] | Starts playing the music file. |
startAudioMixing [2/2] | Starts playing the music file. |
stopAudioMixing | Stops playing and mixing the music file. |
pauseAudioMixing | Pauses playing 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. |
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. |
setAudioMixingPitch | Sets the pitch of the local music file. |
setAudioMixingPosition | Sets the audio mixing position. |
setAudioMixingDualMonoMode | Sets the channel mode of the current audio file. |
Event | Description |
---|---|
audioMixingStateChanged | Occurs when the playback state of the music file changes. |
Audio effect file playback
Method | Description |
---|---|
getEffectsVolume | Retrieves the volume of the audio effects. |
setEffectsVolume | Sets the volume of the audio effects. |
getVolumeOfEffect | Gets the volume of a specified audio effect. |
setVolumeOfEffect | Sets the volume of a specified audio effect. |
preloadEffect | Preloads a specified audio effect file into the memory. |
playEffect [3/3] | Plays the specified local or online audio effect file. |
pauseEffect | Pauses playing a specified audio effect file. |
pauseAllEffects | Pauses playing all audio effect files. |
resumeEffect | Resumes playing a specified audio effect. |
resumeAllEffects | Resumes playing all audio effects. |
stopEffect | Stops playing a specified audio effect. |
stopAllEffects | Stops playing all audio effects. |
unloadEffect | Releases a specified preloaded audio effect from the memory. |
getEffectDuration | Retrieves the duration of the audio effect file. |
getEffectCurrentPosition | Retrieves the playback position of the audio effect file. |
setEffectPosition | Sets the playback position of an audio effect file. |
Voice changer and reverberation
Method | Description |
---|---|
setLocalVoiceEqualizationOfBandFrequency | Sets the local voice equalization effect. |
setLocalVoicePitch | Changes the voice pitch of the local speaker. |
setLocalVoiceReverbOfType | 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. |
Pre-call network test
Method | Description |
---|---|
startEchoTestWithConfig | Starts an audio and video call loop test. |
stopEchoTest | Stops the audio call test. |
startLastmileProbeTest | Starts the last mile network probe test. |
stopLastmileProbeTest | Stops the last mile network probe test. |
Event | Description |
---|---|
lastmileQuality | Reports the last-mile network quality of the local user. |
lastmileProbeTestResult | Reports the last mile network probe result. |
Screen Sharing
Method | Description |
---|---|
getScreenCaptureSourcesWithThumbSize | Gets a list of shareable screens and windows. |
startScreenCaptureByWindowId | Shares the whole or part of a window by specifying the window ID. |
startScreenCaptureByDisplayId | Shares the screen by specifying the display ID. |
updateScreenCaptureParameters | Updates the screen sharing parameters. |
stopScreenCapture | Stops screen sharing. |
updateScreenCaptureRegion | Updates the screen sharing region. |
setScreenCaptureScenario | Sets the screen sharing scenario. |
Video dual stream
Method | Description |
---|---|
enableDualStreamMode [1/2] | Enables or disables dual-stream mode on the sender side. |
enableDualStreamMode [2/2] | Enables or disables the dual-stream mode on the sender and sets the low-quality video stream. |
setRemoteVideoStream | Sets the stream type of the remote video. |
setRemoteDefaultVideoStreamType | Sets the default stream type of subscrption for remote video streams. |
setDualStreamMode [2/2] | Sets dual-stream mode configuration on the sender, and sets the low-quality video stream. |
Watermark
Method | Description |
---|---|
addVideoWatermark [2/2] | Adds a watermark image to the local video. |
clearVideoWatermarks | Removes the watermark image from the video stream. |
Encryption
Method | Description |
---|---|
enableEncryption | Enables/Disables the built-in encryption. |
Event | Description |
---|---|
didOccurEncryptionError | Reports the built-in encryption errors. |
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. |
Spatial audio effect
Note:
This feature is in experimental status. To enable it, contact , contact if needed.
Local Cartesian coordinate system calculation solution | Description |
---|---|
sharedLocalSpatialAudioWithConfig | Initializes AgoraLocalSpatialAudioKit. |
destroy | Destroys AgoraLocalSpatialAudioKit. |
updateSelfPosition | Updates the spatial position of the local user. |
updateRemotePosition | Updates the spatial position of the specified remote user. |
removeRemotePosition | Removes the spatial position of the specified remote user. |
clearRemotePositions | Removes the spatial positions of all remote users. |
Media push
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 |
---|---|
rtmpStreamingEventWithUrl | Reports events during the media push. |
rtmpStreamingChangedToState | Occurs when the media push state changes. |
rtcEngineTranscodingUpdated | 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. |
stopChannelMediaRelay | Stops the media stream relay. Once the relay stops, the host quits all the destination channels. |
pauseAllChannelMediaRelay | Pauses the media stream relay to all destination channels. |
resumeAllChannelMediaRelay | Resumes the media stream relay to all destination channels. |
Event | Description |
---|---|
channelMediaRelayStateDidChange | Occurs when the state of the media stream relay changes. |
didReceiveChannelMediaRelayEvent | Reports events during the media stream relay. |
Custom audio source
Method | Description |
---|---|
setExternalAudioSource [2/2] | Sets the external captured audio parameters and chooses whether to publish the audio to the remote user. |
pushExternalAudioFrameSampleBuffer | Pushes external CMSampleBuffer audio frames. |
pushExternalAudioFrameNSData | Pushes the external audio frames to the SDK. |
Raw audio data
Method | Description |
---|---|
setAudioFrameDelegate | Registers an audio frame observer object. |
setRecordingAudioFrameParametersWithSampleRate | Sets the format of the captured raw audio data. |
setPlaybackAudioFrameParametersWithSampleRate | Sets the audio data format for playback. |
setMixedAudioFrameParametersWithSampleRate | Sets the audio data format reported by onMixedAudioFrame. |
setPlaybackAudioFrameBeforeMixingParametersWithSampleRate | Sets the audio data format reported by onPlaybackAudioFrameBeforeMixing. |
Event | Description |
---|---|
onRecordAudioFrame | Gets the captured audio frame. |
onPlaybackAudioFrame | Gets the raw audio frame for playback. |
onPlaybackAudioFrameBeforeMixing | Retrieves the audio frame of a specified user before mixing. |
onMixedAudioFrame | Retrieves the mixed captured and playback audio frame. |
getObservedAudioFramePosition | Sets the frame position for the video observer. |
getRecordAudioParams | Sets the audio format for the onRecordAudioFrame callback. |
getPlaybackAudioParams | Sets the audio format for the onPlaybackAudioFrame callback. |
getMixedAudioParams | Sets the audio format for the onMixedAudioFrame callback. |
Encoded audio data
Method | Description |
---|---|
registerAudioEncodedFrameObserver | Registers an encoded audio observer. |
Event | Description |
---|---|
onRecordEncodedAudioFrame | Gets the encoded audio data of the local user. |
onPlaybackEncodedAudioFrame | Gets the encoded audio data of all remote users. |
onMixedEncodedAudioFrame | Gets the mixed and encoded audio data of the local and all remote users. |
Audio spectrum
Method | Description |
---|---|
registerAudioSpectrumDelegate | Registers an audio spectrum observer. |
enableAudioSpectrumMonitor | Turns on audio spectrum monitoring. |
disableAudioSpectrumMonitor | Disables audio spectrum monitoring. |
unregisterAudioSpectrumDelegate | Unregisters the audio spectrum observer. |
Event | Description |
---|---|
onLocalAudioSpectrum | Gets the statistics of a local audio spectrum. |
onRemoteAudioSpectrum | Gets the remote audio spectrum. |
Custom video source
Method | Description |
---|---|
createCustomVideoTrack | Creates a customized video track. |
destroyCustomVideoTrack | Destroys the specified video track. |
External video source
Method | Description |
---|---|
setExternalVideoSource | Configures the external video source. |
pushExternalVideoFrame | Pushes the external raw video frame to the SDK. |
Raw video data
Method | Description |
---|---|
setVideoFrameDelegate | Registers a raw video frame observer object. |
Event | Description |
---|---|
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. |
onPreEncodeScreenVideoFrame | Gets the video data captured from the screen before encoding. |
onScreenCaptureVideoFrame | Occurs each time the SDK receives a video frame captured by the screen. |
onRenderVideoFrame | Occurs each time the SDK receives a video frame sent by the remote user. |
getObservedFramePosition | Sets the frame position for the video observer. |
getVideoFrameProcessMode | Occurs each time the SDK receives a video frame and prompts you to set the process mode of the video frame. |
getMirrorApplied | Occurs each time the SDK receives a video frame and prompts you whether or not to mirror the captured video. |
getRotationApplied | Occurs each time the SDK receives a video frame, and prompts you whether to rotate the captured video. |
getVideoFormatPreference | Sets the format of the raw video data output by the SDK. |
Encoded video data
Method | Description |
---|---|
registerVideoEncodedFrameObserver | Registers a receiver object for the encoded video image. |
Event | Description |
---|---|
onEncodedVideoFrameReceived | Reports that the receiver has received the to-be-decoded video frame sent by the remote end. |
Extension
Method | Description |
---|---|
enableExtensionWithVendor | Enables/Disables an extension. |
setExtensionPropertyWithVendor | Sets the properties of the extension. |
setExtensionProviderPropertyWithVendor | Sets the properties of the extension provider. |
getExtensionProperty [1/2] | Gets detailed information on the extensions. |
getExtensionProperty [2/2] | Gets detailed information on the extensions. |
Event | Description |
---|---|
onEvent | The event callback of the extension. |
onExtensionStarted | Occurs when the extension is enabled. |
onExtensionStopped | Occurs when the extension is disabled. |
onExtensionError | Occurs when the extension runs incorrectly. |
Media metadata
Method | Description |
---|---|
setMediaMetadataDelegate | Registers the metadata observer. |
setMediaMetadataDataSource | Sets the data source of the metadata. |
Event | Description |
---|---|
metadataMaxSize | Occurs when the SDK requests the maximum size of the metadata. |
readyToSendMetadataAtTimestamp | Occurs when the SDK is ready to send metadata. |
receiveMetadata | Occurs when the local user receives the metadata. |
Audio recording
Method | Description |
---|---|
startAudioRecording [2/2] | Starts the audio recording on the client. |
stopAudioRecording | Stops the audio recording on the client. |
Local audio and video recording
Method | Description |
---|---|
sharedMediaRecorderWithRtcEngine | Creates an AgoraMediaRecorder instance. |
setMediaRecorderDelegate | Registers one AgoraMediaRecorderDelegate object. |
startRecording | Starts recording the local audio and video. |
stopRecording | Stops recording the local audio and video. |
enableMainQueueDispatch | Enables or disables dispatching delegate methods to the main queue. |
destroy | Release the AgoraMediaRecorder object. |
Event | Description |
---|---|
stateDidChanged | Occurs when the recording state changes. |
informationDidUpdated | Occurs when the recording information is updated. |
Multiple channels
For more methods about multi-channel, see AgoraRtcEngineKit(Ex).
Method | Description |
---|---|
joinChannelExByToken | Joins a channel with the connection ID. |
leaveChannelEx [2/2] | Sets channel options and leaves the channel. |
Volume indication
Method | Description |
---|---|
enableAudioVolumeIndication | Enables the reporting of users' volume indication. |
Event | Description |
---|---|
reportAudioVolumeIndicationOfSpeakers | Reports the volume information of users. |
activeSpeaker | Occurs when the most active remote speaker is detected. |
Data stream
Method | Description |
---|---|
createDataStream [2/2] | Creates a data stream. |
sendStreamMessage | Sends data stream messages. |
Event | Description |
---|---|
receiveStreamMessageFromUid | Occurs when the local user receives the data stream from the remote user. |
didOccurStreamMessageErrorFromUid | Occurs when the local user does not receive the data stream from the remote user. |
Device management
Method | Description |
---|---|
enumerateDevices | Enumerates all the audio and video devices in the system. |
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. |
getDeviceInfo | Retrieves the name of the current device. |
getDefaultAudioDevice | Gets the default audio device of the system. |
getDeviceVolume | Retrieves the volume of the current device. |
monitorDeviceChange | Monitors the change of the device state. |
setDevice | Specifies a device with the device ID. |
setDeviceVolume | Sets the volume of the specified device. |
startAudioDeviceLoopbackTest | Starts an audio device loopback test. |
startPlaybackDeviceTest | Starts the audio playback device test. |
stopAudioDeviceLoopbackTest | Stops the audio device loopback test. |
stopPlaybackDeviceTest | Stops the audio playback device test. |
Event | Description |
---|---|
stateChanged | Occurs when the device state changes. |
Miscellaneous audio control
Method | Description |
---|---|
enableLoopbackRecording | Enables loopback audio capturing. |
Miscellaneous methods
Method | Description |
---|---|
setCloudProxy | Sets the Agora cloud proxy service. |
setParameters | Provides technical preview functionalities or special customizations by configuring the SDK with JSON options. |
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. |
getSdkVersion | Gets the SDK version. |
getErrorDescription | Gets the warning or error description. |
enableVideoImageSource | Sets whether to replace the current video feeds with images when publishing video streams. |
getNetworkType | Gets the type of the local network connection. |
setHeadphoneEQPreset | Sets the preset headphone equalization effect. |
setHeadphoneEQParameters | Sets the low- and high-frequency parameters of the headphone equalizer. |