Agora Objective-C API Reference for iOS/macOS

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 user is speaking and the speaker’s 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 user is speaking and the speaker’s volume.
activeSpeaker Reports which user who is speaking in the channel.
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 user is speaking and the speaker’s 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.
Is this page helpful?