Agora Objective-C API Overview Document

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.

  • The AgoraRtcEngineKit class is the entry point of the Agora SDK providing API methods for apps to easily start voice and video communication.
  • The Agora SDK uses delegate callbacks in the AgoraRtcEngineDelegate protocol to report runtime events to the app.
  • The AgoraRtcChannel class provides methods that enable real-time communications in a specified channel. By creating multiple RtcChannel instances, users can join multiple channels.
  • The AgoraRtcChannelDelegate class provides callbacks that report events and statistics of a specified channel.

During API calls, the SDK may returns error codes and warning codes. See Error Codes and Warning Codes.

icon As of v2.3.3, Agora Objective-C API Reference for iOS/macOS can be downloaded from Dash, see FAQ for details.

Core methods

Method Function
sharedEngineWithAppId Creates the AgoraRtcEngineKit instance.
sharedEngineWithConfig Creates the AgoraRtcEngineKit instance and specifies the region for connection.
destroy Destroys the AgoraRtcEngineKit instance.
setChannelProfile Sets the channel profile.
setClientRole1 Sets the role of the user (interactive live streaming only).
setClientRole2 Sets the role and level of the user (interactive live streaming only).
joinChannelByToken1 Allows a user to join a channel.
joinChannelByToken2 Allows a user to join a channel and set the publishing or subscribing state.
switchChannelByToken1 Switches to a different channel in the interactive live streaming.
switchChannelByToken2 Switches to a different channel and set the subscribing state in the interactive live streaming.
leaveChannel Allows a user to leave a channel.
renewToken Renews the Token.

Core events

Event Description
didJoinChannel Occurs when a user joins a channel.
didRejoinChannel Occurs when a user rejoins a channel.
didLeaveChannelWithStats Occurs when a user leaves a channel.
didClientRoleChanged Occurs when the user role switches successfully in the interactive live streaming.
didClientRoleChangeFailed Occurs when the user role switch fails in the interactive live streaming.
didJoinedOfUid Occurs when a remote user joins a channel.
didOfflineOfUid Occurs when a remote user leaves a channel.
connectionChangedToState Occurs when the connection state of the app changes.
networkTypeChangedToType Occurs when the network type changes.
rtcEngineConnectionDidLost Occurs when the connection between the SDK is interrupted, and the SDK cannot reconnect to the edge server in 10 seconds.
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.

Audio management

Method Function
enableAudio Enables the audio module.
disableAudio Disables the audio module.
setAudioProfile Sets the audio parameters and application scenarios.
adjustRecordingSignalVolume Adjusts the volume of the signal captured by the microphone.
adjustLoopbackRecordingSignalVolume Adjusts the volume of the signal captured by the sound card. (macOS only)
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/Resumes publishing the local audio stream.
muteRemoteAudioStream Stops/Resumes subscribing to the audio stream of a specified user.
muteAllRemoteAudioStreams Stops/Resumes subscribing to the audio streams of all remote users.

Video management

Method Function
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 Updates the display mode of the local video view.
setRemoteRenderMode Updates the display mode of the video view of a remote user.
startPreview Starts the local video preview.
stopPreview Stops the local video preview.
enableLocalVideo Enables/Disables the local video capture.
muteLocalVideoStream Stops/Resumes publishing the local video stream.
muteRemoteVideoStream Stops/Resumes subscribing to the video stream of a specified user.
muteAllRemoteVideoStreams Stops/Resumes subscribing to the video streams of all remote users.

Local media events

Event Description
localAudioStateChange Occurs when the local audio state changes.
localVideoStateChange Occurs when the state of the local video changes.
firstLocalAudioFramePublished Occurs when the first audio frame is published.
firstLocalVideoFramePublished Occurs when the first video frame is published.
firstLocalVideoFrameWithSize Occurs when the first local video frame is rendered.
didAudioPublishStateChange Occurs when the local audio publish state changes.
didVideoPublishStateChange Occurs when the local video publish 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 first remote video frame is rendered.
firstRemoteVideoDecodedOfUid Occurs when the first remote video frame is received and decoded.
didAudioSubscribeStateChange Occurs when the remote audio subscribe state changes.
didVideoSubscribeStateChange Occurs when the remote video subscribe state changes.
didAudioMuted Occurs when a remote user’s audio stream is muted.
didVideoMuted Occurs when a remote user stops or resumes publishing the video stream.
didVideoEnabled Occurs when a specific remote user enables/disables the video module.
didLocalVideoEnabled 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. We provide an advanced guide for these callbacks. For details, see In-call Stats.

Event Description
remoteAudioStats Reports the statistics of the audio stream from each remote user/host.
reportRtcStats Reports the statistics of the Rtc Engine.
networkQuality Reports the network quality of each user.
localAudioStats Reports the statistics of the local audio stream.
localVideoStats Reports the statistics of the uploading local video streams.
remoteVideoStats Reports the statistics of the video stream from each remote user/host.

Video pre-process and post-process

Method Function
setBeautyEffectOptions Enables/Disables image enhancement and sets the options.
enableVirtualBackground Enables/Disables the virtual background.
enableRemoteSuperResolution Enables/Disables the super resolution feature for a remote user’s video. (beta feature)
setVideoDenoiserOptions Sets video noise reduction.
setLowlightEnhanceOptions Sets low-light enhancement.
setColorEnhanceOptions Sets color enhancement.
Event Description
virtualBackgroundSourceEnabled Reports whether the virtual background is successfully enabled.
superResolutionEnabledOfUid Reports whether the super resolution feature is successfully enabled. (beta feature)

Multi-channel management

We provide an advanced guide on the applicable scenarios, implementation and considerations for this group of methods. For details, see Join multiple channels.

API Function
createRtcChannel Initializes and gets an AgoraRtcChannel instance. To join multiple channels, create multiple AgoraRtcChannel objects.
AgoraRtcChannel Provides methods that enable real-time communications in a specified channel.
AgoraRtcChannelDelegate Provides callbacks that report events and statistics in a specified channel.

Screen sharing

We provide an advanced guide on the applicable scenarios, implementation, and considerations for this group of methods, see Share the Screen.

Method Function
getScreenCaptureSourcesWithThumbSize Gets a list of shareable screens and windows. (macOS only)
startScreenCaptureByDisplayId Shares the whole or part of a screen by specifying the display ID. (macOS only)
startScreenCaptureByWindowId Shares the whole or part of a window by specifying the window ID. (macOS only)
startScreenCapture Starts screen sharing. (iOS only)
setScreenCaptureContentHint Sets the content hint for screen sharing. (macOS only)
updateScreenCaptureParameters Updates the screen sharing parameters. (macOS only)
updateScreenCapture Updates the screen sharing configuration. (iOS only)
updateScreenCaptureRegion Updates the screen-sharing region. (macOS only)
stopScreenCapture Stops screen sharing.

Music file playback and mixing

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 of audio mixing.
adjustAudioMixingPlayoutVolume Adjusts the volume of audio mixing for local playback.
adjustAudioMixingPublishVolume Adjusts the volume of audio mixing for remote playback.
setAudioMixingPitch Sets the pitch of the local music file.
getAudioMixingPlayoutVolume Gets the audio mixing volume for local playback.
getAudioMixingPublishVolume Gets the audio mixing volume for publishing.
getAudioMixingCurrentPosition Gets the playback position (ms) of the music file.
setAudioMixingPosition Sets the playback position of the music file.
getAudioTrackCount Gets the number of audio tracks of the current music file. (iOS only)
selectAudioTrack Specifies the playback track of the current music file. (iOS only)
setAudioMixingPlaybackSpeed Sets the playback speed of the current music file.
setAudioMixingDualMonoMode Sets the channel mode of the current music file.
Event Description
localAudioMixingStateDidChanged Occurs when the state of the local user’s audio mixing file changes.
rtcEngineRemoteAudioMixingDidStart Occurs when a remote user starts audio mixing.
rtcEngineRemoteAudioMixingDidFinish Occurs when a remote user finishes audio mixing.

Audio effect file playback

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.
getEffectCurrentPosition Gets the playback position of the audio effect file.
setEffectPosition Sets the playback position of an audio effect file.
Event Description
rtcEngineDidAudioEffectFinish Occurs when the local audio effect playback finishes.

Audio file information

Method Function
getAudioFileInfo Gets the information of a specified audio file.
getEffectDuration Gets the information of a specified audio file.
Event Description
didRequestAudioFileInfo Reports the information of an audio file.

Virtual metronome

This group of methods is for iOS only.

Method Function
startRhythmPlayer Enables the virtual metronome.
configRhythmPlayer Configures the virtual metronome.
stopRhythmPlayer Disables the virtual metronome.

Voice effect

Method Function
setLocalVoicePitch Changes the voice pitch of the local speaker.
enableLocalVoicePitchCallback Enables reporting the voice pitch of the local user.
setLocalVoiceEqualizationOfBandFrequency Sets the local voice equalization effect.
setLocalVoiceReverbOfType Sets the local voice reverberation.
setVoiceBeautifierPreset Sets an SDK preset voice beautifier effect.
setVoiceBeautifierParameters Sets parameters for SDK preset voice beautifier effects.
setAudioEffectPreset Sets an SDK preset audio effect.
setAudioEffectParameters Sets parameters for SDK preset audio effects.
setVoiceConversionPreset Sets an SDK preset voice conversion effect.
Event Description
reportLocalVoicePitchFrequency Reports the voice pitch of the local user.

Sound localization

Method Function
enableSoundPositionIndication Enables/Disables stereo panning for remote users.
setRemoteVoicePosition Sets the sound position and gain of a remote user.

Media push

This group of methods is applicable to the interactive live streaming only.

Method Function
startRtmpStreamWithoutTranscoding Starts pushing media streams to a CDN without transcoding.
startRtmpStreamWithTranscoding Starts pushing media streams to a CDN and sets the transcoding configuration.
updateRtmpTranscoding Updates the transcoding configuration.
stopRtmpStream Stops pushing media streams to a CDN.
Delegate Description
rtmpStreamingChangedToState Occurs when the RTMP or RTMPS streaming status changes.
rtmpStreamingEventWithUrl Reports events during the RTMP or RTMPS streaming.
rtcEngineTranscodingUpdated Occurs when the publisher’s transcoding settings are updated.

Media stream relay across channels

Method Function
startChannelMediaRelay Starts to relay media streams across channels.
updateChannelMediaRelay Updates the channels for media stream relay.
stopChannelMediaRelay Stops the media stream relay.
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.

Audio volume indication

Method Function
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.

Face detection

This group of methods is for iOS only.

Method Function
enableFaceDetection Enables/Disables face detection for the local user.
Event Description
facePositionDidChangeWidth Reports the face detection result of the local user.

Audio routing controller

Method Function
setDefaultAudioRouteToSpeakerphone Sets the default audio route (for iOS only).
setEnableSpeakerphone Enables/Disables the audio route to the speakerphone (for iOS only).
isSpeakerphoneEnabled Checks whether the speakerphone is enabled (for iOS only).
Event Description
didAudioRouteChanged Occurs when the local audio route changes.

In-ear monitor

This group of methods is for iOS only.

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

Dual video stream mode

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.

Stream fallback

We provide an advanced guide on the applicable scenarios, implementation, and considerations for this group of methods, see Video Stream Fallback.

Method Function
setRemoteUserPriority Sets the priority of a remote user’s stream.
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.
Event Description
didLocalPublishFallbackToAudioOnly Occurs when the published video stream falls back to an audio-only stream, or when it switches back to the video stream.
didRemoteSubscribeFallbackToAudioOnly Occurs when the remote video stream falls back to an audio-only stream, or when it switches back to the video stream.

Pre-call network test

We provide an advanced guide on the applicable scenarios, implementation, and considerations for this group of methods, see Pre-call Test.

Method Function
startEchoTestWithInterval Starts an audio call loop test.
startEchoTestWithConfig Starts an audio and video call loop test.
stopEchoTest Stops the call loop 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
lastmileQuality Reports the last mile network quality of the local user before the user joins a channel.
lastmileProbeTestResult Reports the last-mile network probe result.

Custom video module

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)

Method Function
enableExternalAudioSourceWithSampleRate Enables the external audio source.
disableExternalAudioSource Disables the external audio source.
pushExternalAudioFrameRawData Pushes the external raw audio frame to a specified position.
pushExternalAudioFrameSampleBuffer Pushes the external CMSampleBuffer audio frame to a specified position.
setExternalAudioSourceVolume Sets the volume of the external audio frame in the specified position.

External audio sink

Method Function
enableExternalAudioSink Enables the external audio sink.
disableExternalAudioSink Disables the external audio sink.
pullPlaybackAudioFrameRawData Pulls the remote audio data in the RawData format.
pullPlaybackAudioFrameSampleBufferByLengthInByte Pulls the remote audio data in the SampleBuffer format.

External video data (push-mode only)

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

Raw audio data

Method Function
setAudioDataFrame Registers the raw audio frame protocol.
setRecordingAudioFrameParametersWithSampleRate Sets the audio sampling format.
setPlaybackAudioFrameParametersWithSampleRate Sets the audio playback format.
setMixedAudioFrameParametersWithSampleRate Sets the format of the mixed sampled and playback audio frame.
Event Description
getObservedAudioFramePosition Sets the audio observation positions.
getMixedAudioParams Sets the audio mixing format for the onMixedAudioFrame callback.
getRecordAudioParams Sets the audio recording format for the onRecordAudioFrame callback.
getPlaybackAudioParams Sets the audio playback format for the onPlaybackAudioFrame callback.
onRecordAudioFrame Occurs when the recorded audio frame of the local user is received.
onPlaybackAudioFrame Occurs when the playback audio frame of all remote users is received.
onMixedAudioFrame Occurs when the mixed audio frame of the local user and all remote users is received.
onPlaybackAudioFrameBeforeMixing Occurs when the audio frame of a remote user is received before mixing.

Raw video data

This group of methods is for iOS only. To implement raw video data on macOS, use C++ APIs.

Method Function
setVideoDataFrame Registers a raw video frame protocol.
Event Description
getVideoFormatPreference Sets the format of the raw video data output by the SDK.
getRotationApplied Sets whether to rotate the raw video data output by the SDK.
getMirrorApplied Sets whether to mirror the raw video data output by the SDK.
getObservedFramePosition Sets the video observation positions.
onCaptureVideoFrame Gets the video data captured by the local camera.
onPreEncodeVideoFrame Gets the local pre-encoded video data.
onRenderVideoFrame Gets the incoming remote video data.

Local encoded video data

This group of methods is for iOS only.

Method Function
setVideoEncodedFrame Registers a local encoded video frame protocol.
Event Description
onVideoEncodedFrame Gets the local encoded video frame.

Media metadata

Do not implement metadataMaxSize, readyToSendMetadataAtTimestamp, and receiveMetadata in AgoraRtcEngineDelegate.

Method Function
setMediaMetadataDataSource Sets the data source of the media metadata.
setMediaMetadataDelegate Sets the delegate for the media metadata.
Event Description
metadataMaxSize Occurs when the SDK requests the maximum size of the metadata.
readyToSendMetadataAtTimestamp Occurs when the sender is ready to send the metadata.
receiveMetadata Occurs when the receiver receives the metadata.

Watermark

This group of methods is applicable to the interactive live streaming only.

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

Video snapshot

Method Function
takeSnapshot Takes a snapshot of a video stream.
Event Description
snapshotTaken Reports the result of taking a video snapshot.

Encryption

Method Function
enableEncryption Enables/Disables the built-in encryption.

Audio recorder

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

Media recorder

Method Function
sharedMediaRecorderWithRtcEngine Creates an AgoraMediaRecorder instance.
destroy Destroys the AgoraMediaRecorder instance.
enableMainQueueDispatch Enables/Disables dispatching delegate methods to the main queue.
startRecording Starts recording the local audio and video.
stopRecording Stops recording the local audio and video.
Event Description
stateDidChanged Occurs when the recording state changes.
informationDidUpdated Occurs when the recording information is updated.

Camera control

This group of methods is for iOS only.

Method Function
switchCamera Switches between front and rear cameras.
isCameraZoomSupported Checks whether the camera zoom function is supported.
isCameraTorchSupported Checks whether the device supports enabling the flash.
isCameraFocusPositionInPreviewSupported Checks whether the camera manual focus function is supported.
isCameraExposurePositionSupported Checks whether the camera manual exposure 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.
setCameraExposurePosition Sets the manual exposure position.
setCameraTorchOn Sets whether to enable the flash.
setCameraAutoFocusFaceModeEnabled Sets whether to enable face autofocus.
Event Description
cameraFocusDidChangedToRect Occurs when a camera focus area changes. (iOS only)
cameraExposureDidChangedToRect Occurs when a camera exposure area changes. (iOS only)

Device manager

Method Function
monitorDeviceChange Monitors the change of a device state (macOS only).
enumerateDevices Gets all devices in the system (macOS only).
getDeviceInfo Gets the information of devices, such as audio sampling and playback device (macOS only).
setDevice Sets the devices, such as audio sampling and playback device (macOS only).
getDeviceVolume Gets the specified device’s volume (macOS only).
setDeviceVolume Sets the specified device’s volume (macOS only).
startRecordingDeviceTest Starts the audio sampling device test (macOS only).
stopRecordingDeviceTest Stops the audio sampling device test (macOS only).
startPlaybackDeviceTest Starts the audio playback device test (macOS only).
stopPlaybackDeviceTest Stops the audio playback device test (macOS only).
startCaptureDeviceTest Starts the video capture device test (macOS only).
stopCaptureDeviceTest Stops the video capture device test (macOS only).
startAudioDeviceLoopbackTest Starts the audio device loopback test (macOS only).
stopAudioDeviceLoopbackTest Stops the audio device loopback test (macOS only).
getDefaultAudioDevice Gets the default audio device of the system (macOS only).
followSystemPlaybackDevice Sets the audio playback device used by the SDK to follow the system default audio playback device (macOS only).
followSystemRecordingDevice Sets the audio recording device used by the SDK to follow the system default audio recording device (macOS only).
Delegate Description
stateChanged Occurs when the device state changes (macOS only).
reportAudioDeviceTestVolume Reports the result of an audio device test (macOS only).

Data stream

Method Function
createDataStream Creates a data stream.
sendStreamMessage Sends data stream messages.
Event 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.

Miscellaneous audio control

Method Function
enableLoopbackRecording Enables loopback sampling. (macOS only)
setAudioSessionOperationRestriction Sets the operational permission of the SDK on the audio session. (iOS only)

Miscellaneous video control

Method Function
setCameraCapturerConfiguration Sets the camera capture preference.

Miscellaneous methods

Method Function
setCloudProxy Sets the Agora cloud proxy service.
enableDeepLearningDenoise Enables/Disables deep-learning noise reduction.
sendCustomReportMessage Reports customized messages.
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.
getErrorDescription Gets the description of a warning or error code.
getNativeHandle Gets the native handle of the SDK engine.
delegate Sets and gets the SDK delegate.

Miscellaneous events

Event Description
didOccurWarning Occurs when a warning occurs.
didOccurError Occurs when an error occurs.
didApiCallExecute Occurs when an API method is executed.
didProxyConnected Reports the proxy connection state.