Agora Objective-C 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.

Methods

The AgoraRtcEngineKit class is the entry point of the Agora SDK providing API methods for apps to easily start voice and video communication.

Core Service

This group of methods is applicable to Voice Communication, Video Communication, and Interactive broadcast.

Method	Function
sharedEngineWithAppId	Initializes the RtcEngine.
destroy	Destroys the RtcEngine instance.
setChannelProfile	Sets the channel profile.
setClientRole	Sets the role of the user (Live Broadcast only).
joinChannelByToken	Allows a user to join a channel.
leaveChannel	Allows a user to leave a channel.
renewToken	Renews the Token.
enableWebSdkInteroperability	Enables interoperability with the Agora Web SDK (Live Broadcast only).

Core Audio

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Function
enableAudio	Enables the audio module.
disableAudio	Disables the audio module.
setAudioProfile	Sets the audio parameters and application scenarios.
adjustRecordingSignalVolume	Adjusts the recording volume.
adjustPlaybackSignalVolume	Adjusts the playback volume.
enableAudioVolumeIndication	Enables the SDK to regularly report to the application on which users are speaking and the speakers volume.
enableLocalAudio	Enables/Disables the local audio capture.
muteLocalAudioStream	Sends/Stops sending the local audio.
muteRemoteAudioStream	Receives/Stops receiving a specified audio stream.
muteAllRemoteAudioStreams	Receives/Stops receiving all the audio streams.
setDefaultMuteAllRemoteAudioStreams	Sets whether to receive the audio streams by default.

Core Video

This group of methods is applicable to Video Communication and Interactive Broadcast.

Method	Function
enableVideo	Enables the video module.
disableVideo	Disables the video module.
setVideoEncoderConfiguration	Sets the video encoder configuration.
setupLocalVideo	Sets the local video view.
setupRemoteVideo	Sets the remote user’s video view.
setLocalRenderMode	Sets the local video display mode.
setRemoteRenderMode	Sets the remote video display mode.
startPreview	Starts the local video preview.
stopPreview	Stops the local video preview.
enableLocalVideo	Enables/Disables the local video capture.
muteLocalVideoStream	Sends/Stops sending the local video.
muteRemoteVideoStream	Receives/Stops receiving a specified video stream.
muteAllRemoteVideoStreams	Receives/Stops receiving all the video streams.
setDefaultMuteAllRemoteVideoStreams	Sets whether to receive the video streams by default.

Audio Routing Controller

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

This group of methods is for iOS only.

Method	Function
setDefaultAudioRouteToSpeakerphone	Sets the default audio route.
setEnableSpeakerphone	Enables/Disables the audio routing to the speakerphone.
isSpeakerphoneEnabled	Checks whether the speakerphone is enabled..

In-ear Monitor

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

This group of methods is for iOS only.

Method	Function
enableInEarMonitoring	Enables in-ear monitoring.
setInEarMonitoringVolume	Sets the volume of the in-ear monitor.

Audio Sound Effect

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Function
setLocalVoicePitch	Changes the voice pitch of the local speaker.
setLocalVoiceEqualizationOfBandFrequency	Sets the local voice equalization effect.
setLocalVoiceReverbOfType	Sets the local voice reverberation.

Music File Playback and Mixing

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Function
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.
getAudioMixingDuration	Gets the duration (ms) of the music file.
getAudioMixingCurrentPosition	Gets the playback position (ms) of the music file.
setAudioMixingPosition	Sets the playback position of the music file.

Audio Effect File Playback

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Function
getEffectsVolume	Gets the volume of the audio effects.
setEffectsVolume	Sets the volume of the audio effects.
setVolumeOfEffect	Sets the volume of a specified 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 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.

Audio Recorder

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

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

Loopback Recording

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Function
enableLoopbackRecording	Enables loopback recording. (macOS only)

Miscellaneous Audio Control

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Function
setAudioSessionOperationRestriction	Sets the audio session’s operational restriction. (iOS only)

Network-related Test

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Function
startEchoTest	Starts an audio call test.
stopEchoTest	Stops the audio call test.
enableLastmileTest	Enables the network connection quality test.
disableLastmileTest	Disables the network connection quality test.

Custom Video Module

This group of methods is applicable to Video Communication and Interactive Broadcast.

Method	Function
setVideoSource	Sets the video source.
setLocalVideoRenderer	Sets the local video renderer.
setRemoteVideoRenderer	Sets the remote video renderer.
videoSource	Gets the video source.
localVideoRenderer	Gets the local video renderer.
remoteVideoRendererOfUserId	Gets the remote video renderer.

External Audio Data (push-mode only)

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Function
enableExternalAudioSourceWithSampleRate	Enables the external audio source.
disableExternalAudioSource	Disables the external audio source.
pushExternalAudioFrameRawData	Pushes the external raw data audio frame.
pushExternalAudioFrameSampleBuffer	Pushes the external CMSampleBuffer audio frame.

External Video Data (push-mode only)

This group of methods is applicable to Video Communication and Interactive Broadcast.

Method	Function
setExternalVideoSource	Configures the external video source.
pushExternalVideoFrame	Pushes the external video frame.

Raw Audio Data

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

See Modify Raw Data for details.

Method	Function
setRecordingAudioFrameParametersWithSampleRate	Sets the audio recording format.
setPlaybackAudioFrameParametersWithSampleRate	Sets the audio playback format.
setMixedAudioFrameParametersWithSampleRate	Sets the mixed audio format.

Raw Video Data

N/A

Watermark

This group of methods is applicable to Interactive Broadcast only.

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

Stream Fallback

This group of methods is applicable to Interactive Broadcast only.

Method	Function
setLocalPublishFallbackOption	Sets the fallback option for the published stream under unreliable network conditions.
setRemoteSubscribeFallbackOption	Sets the fallback option for the remote stream under unreliable network conditions.

Dual-stream Mode

This group of methods is applicable to Video Communication and Interactive Broadcast.

Method	Function
enableDualStreamMode	Enables/Disables the dual-stream mode.
setRemoteVideoStream	Sets the video stream type of the remote stream.
setRemoteDefaultVideoStreamType	Sets the default video stream type of the remote stream.

Encryption

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Function
setEncryptionSecret	Enables built-in encryption with an encryption secret.
setEncryptionMode	Sets the built-in encryption mode.

Inject an Online Media Stream

This group of methods is applicable to Interactive Broadcast only.

Method	Function
addInjectStreamUrl	Adds an online media stream to a live broadcast.
removeInjectStreamUrl	Removes the online media stream from a live broadcast.

CDN Live Streaming

This group of methods is applicable to Interactive Broadcast only.

Method	Function
addPublishStreamUrl	Adds a CDN stream address.
removePublishStreamUrl	Removes a CDN stream address.
setLiveTranscoding	Sets the video layout and audio settings for CDN live.

Data Stream

This group of methods is applicable to Voice Communication, Video Communication, and Interactive Broadcast.

Method	Function
createDataStream	Creates a data stream.
sendStreamMessage	Sends data stream messages.

Miscellaneous Video Control

This group of methods is applicable to Video Communication and Interactive Broadcast.

Method	Function
setVideoQualityParameters	Sets the preferences for the video quality. (Live broadcast only).
setLocalVideoMirrorMode	Sets the local video mirror mode.

Camera Control

This group of methods is applicable to Video Communication and Interactive Broadcast.

This group of methods is for iOS only.

Method	Function
switchCamera	Switches between the front and rear cameras.
isCameraZoomSupported	Checks whether the camera zoom function is supported.
isCameraTorchSupported	Checks whether the camera flash function is supported.
isCameraFocusPositionInPreviewSupported	Checks whether the camera manual focus function is supported.
isCameraAutoFocusFaceModeSupported	Checks whether the camera auto-face focus function is supported.
setCameraZoomFactor	Sets the camera zoom ratio.
setCameraFocusPositionInPreview	Sets the manual focus position.
setCameraTorchOn	Enables the camera flash function.
setCameraAutoFocusFaceModeEnabled	Enables the camera auto-face focus function.

Screen Sharing

This group of methods is applicable to Video Communication and Interactive Broadcast.

This group of methods is for macOS only.

Method	Function
startScreenCapture	Starts screen sharing.
stopScreenCapture	Stops screen sharing.
updateScreenCaptureRegion	Updates the screen-sharing region.

Device Manager

This group of methods is for macOS only.

Method	Function
monitorDeviceChange	Monitors the change of a device state.
enumerateDevices	Retrieves all the devices in the system.
getDeviceInfo	Retrieves the device information.
setDevice	Sets the playback, recording, or audio-sampling device.
getDeviceVolume	Retrieves the specified device’s volume.
setDeviceVolume	Sets the specified device’s volume.
startRecordingDeviceTest	Starts the microphone test.
stopRecordingDeviceTest	Stops the microphone test.
startPlaybackDeviceTest	Starts the audio playback device test.
stopPlaybackDeviceTest	Stops the audio playback device test.
startCaptureDeviceTest	Starts the video capture device test.
stopCaptureDeviceTest	Stops the video capture device test.

Miscellaneous Methods

This group of methods is applicable to Video Communication and Interactive Broadcast.

Method	Function
getCallId	Gets the current 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.
enableMainQueueDispatch	Enables/Disables dispatching the delegate to the main queue.
getSdkVersion	Gets the Agora SDK version.
setLogFile	Specifies an SDK output log file.
setLogFilter	Sets the output log level of the SDK.
getNativeHandle	Gets the native handle of the SDK engine.
delegate	Sets and retrieves the SDK delegate.

Customized Methods (Technical Preview)

Method	Function
setParameters	Provides technical preview functionalities or special customizations by configuring the SDK with JSON options.
getParameter	Gets the Agora SDK’s parameters for customization purposes.

Delegates

The Agora SDK uses delegate callbacks in the AgoraRtcEngineDelegate protocol to report runtime events to the app.

Core Delegate Methods

Delegate	Description
didOccurWarning	Occurs when a warning occurs.
didOccurError	Occurs when an error occurs.
didApiCallExecute	Occurs when an API method is executed.
didJoinChannel	Occurs when a user joins the channel.
didRejoinChannel	Occurs when a user rejoins the channel.
didLeaveChannel	Occurs when a user leaves the channel.
didClientRoleChanged	Occurs when the user role switches in a live broadcast.
didJoinedOfUid	Occurs when a remote user joins the channel.
didOfflineOfUid	Occurs when a remote user leaves the channel.
rtcEngineConnectionDidInterrupted	Occurs when the connection between the SDK and the server is interrupted.
rtcEngineConnectionDidLost	Occurs when the connection between the SDK and the server is lost.
rtcEngineConnectionDidBanned	Occurs when your connection is banned by the Agora Server.
tokenPrivilegeWillExpire	Occurs when the Token expires in 30 seconds.
rtcEngineRequestToken	Occurs when the Token expires.

Media Delegate Methods

Delegate	Description
didMicrophoneEnabled	Occurs when the state of the microphone changes.
reportAudioVolumeIndicationOfSpeakers	Reports which users are speaking and the speakers' volume at the moment.
activeSpeaker	Reports which user is the loudest speaker over a period of time.
firstLocalAudioFrame	Occurs when the first local audio frame is sent.
firstRemoteAudioFrameOfUid	Occurs when the first remote audio frame is received.
rtcEngineVideoDidStop	Occurs when the video stops playing.
firstLocalVideoFrameWithSize	Occurs when the first local video frame is sent.
firstRemoteVideoDecodedOfUid	Occurs when the first video frame from a specific remote user is decoded.
firstRemoteVideoFrameOfUid	Occurs when the first remote video frame is rendered.
didAudioMuted	Occurs when a remote user’s audio stream is muted/unmuted.
didVideoMuted	Occurs when a remote user’s video stream playback pauses/resumes.
didVideoEnabled	Occurs when a specified remote user enables/disables the video module.
didLocalVideoEnabled	Occurs when a specified remote user enables/disables the local video.
videoSizeChangedOfUid	Occurs when the video size or rotation of a specified remote user changes.
remoteVideoStateChangedOfUid	Occurs when the remote video stream state changes.

Fallback Delegate Methods

Delegate	Description
didLocalPublishFallbackToAudioOnly	Occurs when the published stream falls back to an audio-only stream, or when it switches back to the video stream.
didRemoteSubscribeFallbackToAudioOnly	Occurs when the remote stream falls back to an audio-only stream, or when it switches back to the video stream.

Device Delegate Methods

Delegate	Description
stateChanged	Occurs when the device state changes. (macOS only)
didAudioRouteChanged	Occurs when the local audio route changes.
rtcEngineCameraDidReady	Occurs when the camera is turned on and ready to capture video.
cameraFocusDidChangedToRect	Occurs when a camera focus area changes. (iOS only)

Statistics Delegate Methods

Delegate	Description
audioQualityOfUid	Reports the audio quality of the current call once every two seconds.
reportRtcStats	Reports the statistics of the Rtc Engine once every two seconds.
lastmileQuality	Reports the last mile network quality of the local user once every two seconds.
networkQuality	Reports the network quality of each user once every two seconds.
localVideoStats	Reports the statistics of the uploading local video streams once every two seconds.
remoteVideoStats	Reports the statistics of the receiving remote video streams once every two seconds.
audioTransportStatsOfUid	Reports the statistics of the remote audio transmission once every two seconds.
videoTransportStatsOfUid	Reports the statistics of the remote video transmission once every two seconds.

Audio Player Delegate Methods

Delegate	Description
rtcEngineLocalAudioMixingDidFinish	Occurs when the audio mixing file playback finishes.
rtcEngineRemoteAudioMixingDidStart	Occurs when a remote user starts audio mixing.
rtcEngineRemoteAudioMixingDidFinish	Occurs when a remote user finishes audio mixing.
rtcEngineDidAudioEffectFinish	Occurs when the local audio effect playback finishes.

CDN Live Streaming Delegate Methods

Delegate	Description
streamPublishedWithUrl	Occurs when a CDN live stream is published.
streamUnpublishedWithUrl	Occurs when a CDN live stream stops.
rtcEngineTranscodingUpdated	Occurs when the publisher’s transcoding settings are updated.

Inject Stream URL Delegate Methods

Delegate	Description
streamInjectedStatusOfUrl	Reports the status of the injected video stream.

Stream Message Delegate Methods

Delegate	Description
receiveStreamMessageFromUid	Occurs when the local user receives the data stream from a remote user within five seconds.
didOccurStreamMessageErrorFromUid	Occurs when the local user fails to receive the data stream from the remote user within five seconds.

Raw Audio Data Delegate Methods

N/A

Raw Video Data Delegate Methods

N/A

Miscellaneous Delegate Methods

Delegate	Description
rtcEngineMediaEngineDidLoaded	Occurs when the media engine is loaded.
rtcEngineMediaEngineDidStartCall	Occurs when the media engine starts.

Deprecated Callbacks

From v1.1, the block callbacks in the SDK are replaced with delegate callbacks.

The old block callbacks are therefore deprecated, but can still be used in the current version. However, Agora recommends replacing block callbacks with delegate callbacks.

The SDK calls the block callback if a callback is defined in both the block and delegate callbacks.

Callback	Description
audioVolumeIndicationBlock	Reports on which users are speaking and the speakers' volume.
firstLocalVideoFrameBlock	Occurs when the first local video frame on the video window is received and rendered.
firstRemoteVideoDecodedBlock	Occurs when the first video frame from a specific remote user is decoded.
firstRemoteVideoFrameBlock	Occurs when the first remote video frame is received and rendered.
userJoinedBlock	Occurs when a user joins the channel.
userOfflineBlock	Occurs when a user leaves the channel or goes offline.
userMuteAudioBlock	Occurs when a remote user’s audio stream mutes/unmutes.
userMuteVideoBlock	Occurs when a remote user’s video stream pauses/resumes playing.
localVideoStatBlock	Reports the statistics of the uploading local video streams once every two seconds.
remoteVideoStatBlock	Reports the statistics of receiving remote video streams once every two seconds.
cameraReadyBlock	Occurs when the camera is turned on and ready to capture the video.
connectionLostBlock	Occurs when the SDK loses network connection with the server.
rejoinChannelSuccessBlock	Occurs when a user rejoins the channel.
rtcStatsBlock	Reports the Rtc Engine runtime statistics once every two seconds.
leaveChannelBlock	Occurs when a user leaves the channel.
audioQualityBlock	Occurs when the audio quality of the current call is reported.
networkQualityBlock	Occurs when the network quality is reported.
lastmileQualityBlock	Occurs when the last mile network quality of the local user is reported.
mediaEngineEventBlock	Media engine Event.