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.
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. |
| leaveChannel | Allows a user to leave a channel. |
| renewToken | Renews the Token. |
| enableWebSdkInteroperability | Enables interoperability with the Agora Web SDK (Live Broadcast only). |
Channel events
| Event | Description |
|---|---|
| didJoinChannel | Occurs when a user joins a channel. |
| didRejoinChannel | Occurs when a user rejoins a channel. |
| didLeaveChannel | 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. |
User information management
| Method | Function |
|---|---|
| registerLocalUserAccount | Registers a user account. |
| joinChannelByUserAccount | Joins the channel with a user account. |
| getUserInfoByUserAccount | Gets the user information by passing in the user account. |
| getUserInfoByUid | Gets the user information by passing in the user ID. |
| Event | Description |
|---|---|
| didRegisteredLocalUser | Occurs when the local user successfully registers a user account. |
| didUpdatedUserInfo | Occurs when the SDK gets the user ID and user account of the remote user. |
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. |
| adjustPlaybackSignalVolume | Adjusts the playback 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 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 | 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 remote video streams. |
| setDefaultMuteAllRemoteVideoStreams | Sets whether to receive all remote video streams by default. |
Local media events
| Event | Description |
|---|---|
| localVideoStateChange | Occurs when the state of the local video changes. |
| didMicrophoneEnabled | Occurs when the state of the microphone changes. |
| firstLocalAudioFrame | Occurs when the first local audio frame is sent. |
| firstLocalVideoFrameWithSize | Occurs when the first local video frame is sent. |
Remote media events
| Event | Description |
|---|---|
| firstRemoteAudioFrameOfUid | Occurs when the first remote audio frame is received. |
| firstRemoteAudioFrameDecodedOfUid | Occurs when the first remote audio frame is decoded. |
| 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. |
| remoteVideoStateChangedOfUid | Occurs when the remote video stream state changes. |
Statistics events
| 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. |
| localVideoStats | Reports the statistics of the uploading local video streams. |
| remoteVideoStats | Reports the statistics of the video stream from each remote user/host. |
| audioTransportStatsOfUid | Reports the transport-layer statistics of each remote audio stream. |
| videoTransportStatsOfUid | Reports the transport-layer statistics of each remote video stream. |
Video pre-process and post-process
| Method | Function |
|---|---|
| setBeautyEffectOptions | Enables/Disables image enhancement and sets the options. (iOS only) |
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. |
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
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, see Improve Experience Under Poor Network Conditions.
| 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 Conduct a Last-mile Test.
| 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
N/A
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, see Inject an 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 |
|---|---|
| setLocalVideoMirrorMode | Sets the local video mirror mode. |
| 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. |
| 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. |
