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.

  • 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.

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

Channel management

Method Function
sharedEngineWithAppId Initializes 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.
switchChannelByToken Switches to a different channel.
leaveChannel Allows a user to leave a channel.
renewToken Renews the Token.

Channel 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 in a live broadcast.
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 recording volume.
adjustUserPlaybackSignalVolume Adjusts the playback volume of a specified remote user.
adjustPlaybackSignalVolume Adjusts the playback volume of all remote users.
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 remote audio streams.
setDefaultMuteAllRemoteAudioStreams Sets whether to receive all remote audio streams by default.

Video management

Method Function
enableVideo Enables the video module.
disableVideo Disables the video module.
setVideoEncoderConfiguration Sets the video encoder configuration.
setupLocalVideo Initializes the video view of a local user.
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 Sends/Stops sending the local video.
muteRemoteVideoStream Receives/Stops receiving a specified video stream.
muteAllRemoteVideoStreams Receives/Stops receiving all remote video streams.
setDefaultMuteAllRemoteVideoStreams Sets whether to receive all remote video streams by default.

Local media events

Event Description
localAudioStateChange Occurs when the local audio state changes.
localVideoStateChange Occurs when the state of the local video changes.
firstLocalAudioFrame Occurs when the first local audio frame is sent.
firstLocalVideoFrameWithSize Occurs when the first local video frame is rendered.

Remote media events

Event Description
remoteAudioStateChangedOfUid Occurs when the remote audio state changes.
remoteVideoStateChangedOfUid Occurs when the remote video stream state changes.
firstRemoteVideoDecodedOfUid Occurs when the first video frame from a specific remote user is decoded.
didVideoMuted Occurs when a remote user’s video stream is muted/unmuted.

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. (iOS only)

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.
  • This group of methods is for macOS only.
Method Function
startScreenCaptureByDisplayId Shares the whole or part of a screen by specifying the display ID.
startScreenCaptureByWindowId Shares the whole or part of a window by specifying the window ID.
setScreenCaptureContentHint Sets the content hint for screen sharing.
updateScreenCaptureParameters Updates the screen sharing parameters.
updateScreenCaptureRegion Updates the screen-sharing region.
stopScreenCapture Stops screen sharing.

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.
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.
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.
Event Description
rtcEngineDidAudioEffectFinish Occurs when the local audio effect playback finishes.

Voice changer and reverberation

Method Function
setLocalVoicePitch Changes the voice pitch of the local speaker.
setLocalVoiceEqualizationOfBandFrequency Sets the local voice equalization effect.
setLocalVoiceReverbOfType Sets the local voice reverberation.
setLocalVoiceChanger Sets the local voice changer option.
setLocalVoiceReverbPreset Sets the preset local voice reverberation effect.

Sound position indication

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

CDN publisher

This group of methods is applicable to Interactive Broadcast only.

Method Function
addPublishStreamUrl Adds a CDN live stream address.
removePublishStreamUrl Removes a CDN live stream address.
setLiveTranscoding Sets the video layout and audio settings for CDN live.
Delegate Description
rtmpStreamingChangedToState Occurs when the RTMP streaming status changes.
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.
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 SDK to regularly report to the application on which users are speaking and the speakers' volume.
Event Description
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.

Audio routing controller

This group of methods is for iOS only.

Method Function
setDefaultAudioRouteToSpeakerphone Sets the default audio route.
setEnableSpeakerphone Enables/Disables the audio route to the speakerphone.
isSpeakerphoneEnabled Checks whether the speakerphone is enabled.
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. For details, 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. For details, see Lastmile Tests.

Method Function
startEchoTestWithInterval 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.
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 data.
pushExternalAudioFrameSampleBuffer Pushes the external CMSampleBuffer audio frame.

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

You can use the C++ APIs to implement this function, see C++ Raw Audio Data.

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

Raw video data

You can use the C++ APIs to implement this function, see C++ Raw Video Data.

Media metadata

This group of methods is applicable to Interactive Broadcast only. Do not implement metadataMaxSize, readyToSendMetadataAtTimestamp, and receiveMetadata in AgoraRtcEngineDelegate.

Method Function
setMediaMetadataDataSource Sets the data source of the media metadata.
setMediaMetadataDataDelegate 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 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.

Encryption

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

Audio recorder

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

Inject an online media stream

  • This group of methods is applicable to Interactive Broadcast only.
  • We provide an advanced guide on the applicable scenarios, implementation, and considerations for this group of methods. For details, see Inject Online Media Stream
Method Function
addInjectStreamUrl Adds an online media stream to a live broadcast.
removeInjectStreamUrl Removes the online media stream from a live broadcast.
Event Description
streamInjectedStatusOfUrl Reports the status of injecting the online media stream.

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 camera flash function is supported.
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 Enables the camera flash function.
setCameraAutoFocusFaceModeEnabled Enables the camera auto-face focus function.
Event Description
cameraFocusDidChangedToRect Occurs when a camera focus area changes. (iOS only)
cameraExposureDidChangedToRect Occurs when a camera exposure area changes. (iOS only)

Device manager

This group of methods is for macOS only.

Method Function
monitorDeviceChange Monitors the change of a device state.
enumerateDevices Retrieves all 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.
startAudioDeviceLoopbackTest Starts the audio device loopback test.
stopAudioDeviceLoopbackTest Stops the audio device loopback test.
Delegate Description
stateChanged Occurs when the device state changes. (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 recording. (macOS only)
setAudioSessionOperationRestriction Sets the audio session’s operational restriction. (iOS only)

Miscellaneous video control

Method Function
setCameraCapturerConfiguration Sets the camera capturer configuration.

Miscellaneous methods

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.
getErrorDescription Retrieves the description of a warning or error code.
setLogFile Specifies an SDK output log file.
setLogFileSize Sets the log file size.
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.

Miscellaneous events

Event Description
didOccurWarning Occurs when a warning occurs.
didOccurError Occurs when an error occurs.
didApiCallExecute Occurs when an API method is executed.

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.