Agora RTC Objective-C API Reference  Refactor
Agora C++ API Reference for All Platforms

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.

This page provides Reference for Agora low-level APIs:

Agora service

IAgoraService is the entry point of Agora Low Level APIs. Use this interface to create access points to Agora Modules, including RTC Connection, Media Tracks, Audio Device Manager and etc. In addition, in order to customize different user scenarios, the interface allows application to configure service and media sessions on the global level, for example, AgoraServiceConfiguration or AudioSessionConfiguration.

Method Description
createAgoraService Creates an Agora Service object and returns the pointer.
initialize Initializes the Agora Service object.
setAudioSessionPreset Configures the preset audio session.
setAudioSessionConfiguration Sets the audio session configuration.
getAudioSessionConfiguration Gets the audio session configuration.
setLogFile Sets the log file path and size.
setLogFilter Sets the log output level.
createRtcConnection Creates an RTC connection object and returns the pointer.
createLocalAudioTrack Creates a local audio track object and returns the pointer.
createCustomAudioTrack1 Creates a local audio track object with the receiver for encoded audio data and returns the pointer.
createCustomAudioTrack2 Creates a local audio track object with the PCM data receiver and returns the pointer.
createCustomAudioTrack3 Creates a local audio track object with the receiver for encoded audio data and returns the pointer.
createAudioDeviceManager Creates an audio device manager object and returns the pointer.
createMediaNodeFactory Creates a media node factory and returns the pointer.
createMediaPlayerVideoTrack Creates a local video track object with an IMediaPlayerSource object and returns the pointer.
createMediaPlayerAudioTrack Creates a local video track object with an IMediaPlayerSource object and returns the pointer.
createCameraVideoTrack Creates a local video track object with the camera capturer and returns the pointer.
createScreenVideoTrack Creates a local video track object with the screen capturer and returns the pointer.
createCustomVideoTrack1 Creates a local video track object with the custom video source and returns the pointer.
createCustomVideoTrack2 Creates a local video track object with the receiver for encoded video data and returns the pointer.
createCustomVideoTrack3 Creates a local video track object with the custom video source and returns the pointer.
createRtmpStreamingService Creates a live stream service object.
createRtmService Creates an RTM service object.

RTC connection

IRtcConnection allows an app to establish a connection to an Agora channel. In order to establish a connection, the app must provide an app ID, a token, and the ID of the channel that you want to join.

Method Description
connect Connects to an Agora channel.
disconnect Disconnects from the channel.
startLastmileProbeTest Starts the last mile network probe test.
stopLastmileTest Stops the last mile network probe test.
renewToken Renews the token.
getConnectionInfo Gets the current connection information.
getLocalUser Gets the ILocalUser object.
getRemoteUsers Gets the information of remote users.
getUserInfo Gets the information of a specified user in the channel.
getUserInfoByUid Gets the information of a specified user in the channel by uid, which is in integer format.
getUserInfoByUserAccount Gets the information of a specified user in the channel by user account, which is in string format.
registerObserver Registers an IRtcConnectionObserver object.
unregisterObserver Releases the registered IRtcConnectionObserver object.
getConnId Gets the ID of the current connection.
getTransportStats Gets the transportation statistics of this connection.
getAgoraParameter Gets an IAgoraParameter object.
createDataStream Creates a data stream.
sendStreamMessage Sends data stream messages to all users in a channel.

Connecting to an Agora channel is done asynchronously, and apps can listen for the connection states of both the local and remote user using an RTC connection observer.

Event Description
onConnected Occurs when the connection state changes to STATE_CONNECTED.
onDisconnected Occurs when the connection state changes to STATE_DISCONNECTED.
onReconnecting Occurs when the connection state changes to STATE_RECONNECTING.
onConnectionLost Occurs when the SDK loses connection with the Agora channel.
onLastmileQuality Reports the quality of the last mile network.
onTokenPrivilegeWillExpire Occurs when the token privilege expires in 30 seconds.
onTokenPrivilegeDidExpire Occurs when the token privilege has expired.
onConnectionFailure Occurs when the connection state changes to STATE_FAILED.
onUserJoined Occurs when a remote user has successfully joined the channel.
onUserLeft Occurs when a remote user has left the channel.
onTransportStats Reports the transport statistics of the current connection,
onChangeRoleSuccess Occurs when the role of the local user changes.
onChangeRoleFailure Occurs when the role of the local user changes.
onUserNetworkQuality Reports the network quality of each user.
onApiCallExecuted Occurs when an API method is executed.
onError Reports the error code and error message.
onWarning Reports the warning code and warning message.
onChannelMediaRelayStateChanged Occurs when the state of the channel media relay changes.

Local user

Once connected, each RTC connection has its own local user. Apps can get the local user object using IRtcConnection::getLocalUser.

Each local user has two user roles: broadcaster (publisher or subscriber) and audience (subscriber only). The publisher publishes audio and video tracks, while the audience receives them.

Method Description
setUserRole Sets the role of the user.
getUserRole Gets the role of the user.
setAudioEncoderConfiguration Configures the audio encoder.
getLocalAudioStatistics Gets the detailed statistics of the local audio.
publishAudio Publishes a local audio track to the RTC connection.
unpublishAudio Stops publishing the local audio track to the RTC connection.
publishVideo Publishes a local video track to the RTC connection.
unpublishVideo Stops publishing the local video track to the RTC connection.
subscribeAudio Subscribes to the audio of a specified remote user in the RTC connection.
subscribeAllAudio Subscribes to the audio of all remote users in the RTC connection.
unsubscribeAudio Stops subscribing to the audio of a specified remote user in the RTC connection.
unsubscribeAllAudio Stops subscribing to the audio of all remote users in the RTC connection.
pullMixedAudioPcmData Pulls mixed PCM audio data from the RTC connection.
setPlaybackAudioFrameParameters Sets the audio frame parameters for the onPlaybackAudioFrame callback.
setRecordingAudioFrameParameters Sets the audio frame parameters for the onRecordAudioFrame callback.
setMixedAudioFrameParameters Sets the audio frame parameters for the onMixedAudioFrame callback.
setPlaybackAudioFrameBeforeMixingParameters Sets the audio frame parameters for the onPlaybackAudioFrameBeforeMixing callback.
registerAudioFrameObserver Registers an audio frame observer object.
unregisterAudioFrameObserver Releases the audio frame observer object.
subscribeVideo Subscribes to the video of a specified remote user in the RTC connection.
subscribeAllVideo Subscribes to the video of all remote users in the RTC connection.
unsubscribeVideo Stops subscribing to the video of a specified remote user in the RTC connection.
unsubscribeAllVideo Stops subscribing to the video of all remote users in the RTC connection.
setAudioVolumeIndicationParameters Sets the time interval and the volume smoothing factor of the onAudioVolumeIndication callback.
registerLocalUserObserver Registers a local user observer object.
unregisterLocalUserObserver Releases the local user observer object.
Event Description
onAudioTrackPublishSuccess Occurs when the local audio track has published.
onAudioTrackPublicationFailure Occurs when the local audio track fails to be published.
onLocalAudioTrackStateChanged Occurs when the state of the local audio track changes.
onUserAudioTrackSubscribed Occurs when the first remote audio frame is received.
onUserAudioTrackStateChanged Occurs when the state of a remote audio track changes.
onVideoTrackPublishSuccess Occurs when the local video track is published.
onVideoTrackPublicationFailure Occurs when the local video track fails to be published.
onLocalVideoTrackStateChanged Occurs when the state of the local video track changes.
onLocalVideoTrackStatistics Reports the statistics of the local video track.
onUserVideoTrackSubscribed Occurs when the first remote video frame is received.
onUserVideoTrackStateChanged Occurs when the state of a remote video track changes.
onRemoteVideoTrackStatistics Reports the statistics of the remote video track.
onAudioVolumeIndication Reports which users are speaking, the speakers' volume, and whether the local user is speaking.
onUserInfoUpdated Occurs when the user information is updated.

Local audio track

A local audio track can be created by IAgoraService::createLocalAudioTrack. It originates from the default audio recording device, that is, the built-in microphone. You can also use the APIs we provide in the IAudioDeviceManager class if multiple recording devices are available in the system.

After the local audio track is created, you can publish one or multiple local audio tracks using ILocalUser::publishAudio.

Method Description
setEnabled Enables or disables the local audio track.
getState Gets the state of the local audio.
getStats Gets the statistics of the local audio track.
adjustPlayoutVolume Adjusts the audio volume for local playback.
adjustPublishVolume Adjusts the audio volume for publishing.
enableLocalPlayback Enables or disables local playback.
enableEarMonitor Enables or disables ear monitor.
addAudioFilter Adds an audio filter.
removeAudioFilter Removes the audio filter.

Remote audio track

Method Description
getStatistics Gets the statistics of the remote audio.
getState Gets the state of the remote audio.
addAudioFilter Adds an audio filter.
removeAudioFilter Removes the audio filter.

Local video track

A local video track can be created by either of the following methods:

. It originates from one video source, for example, the camera capturer, the screen capturer, or a custom video source.

To customize the video track, choose the video node that you want to use, for example, the video source, the video filter, or video renderer in IVideoNodeFactory.

Apps can publish one or multiple local video tracks through ILocalUser::publishVideo. Each video track has its own video stream. In other words, you can send the camera capturing stream and screen sharing stream simultaneously.

Method Description
setEnabled Enables or disables the local video track.
setVideoEncoderConfiguration Sets the video encoder configuration.
enableSimulcastStream Enables or disables the simulcast stream mode.
updateSimulcastStreamConfig Update the simulcast stream config
getState Gets the state of the local video.
getStatistics Gets the statistics of the local video track.
addVideoFilter Adds a video filter to the video track.
removeVideoFilter Removes the video filter added by addVideoFilter.
addRenderer Adds a video renderer to the video track.
removeRenderer Removes the video renderer added by addVideoRenderer from the video track.

Remote video track

Method Description
getStatistics Gets the statistics of the remote video track.
getState Gets the state of the remote video.
getTrackInfo Gets the information of the remote video track.
registerVideoEncodedImageReceiver Registers an IVideoEncodedImageReceiver object.
unregisterVideoEncodedImageReceiver Releases the IVideoEncodedImageReceiver object.
addVideoFilter Adds a video filter to the video track.
remoteVideoFilter Removes the video filter added by addVideoFilter.
addRenderer Adds a video renderer to the video track.
removeRenderer Removes the video renderer added by addVideoRenderer from the video track.

Media node factory

Use this factory to create audio and video nodes for the audio and video tracks.

Method Description
createAudioPcmDataSender Creates a PCM audio data sender.
createAudioEncodedFrameSender Creates an encoded audio data sender.
createAudioFilter Creates an audio filter.
createCameraCapturer Creates a camera capturer.
createScreenCapturer Creates a screen capturer.
createMediaPlayerSource Creates a media player source object and returns the pointer.
createVideoFrameSender Creates a video frame sender.
createVideoEncodedImageSender Creates an encoded video image sender.
createVideoRenderer Creates a built-in video renderer.

Audio data sender

Method Description
sendAudioPcmData Sends the PCM audio data to the local audio track.
sendEncodedAudioFrame Sends the encoded audio data to the local audio track.

Audio filter

Method Description
setEnabled Enables or disables the audio filter.
isEnabled Checks whether the audio filter is enabled.
adaptAudioFrame Adapts the audio frame.

Audio device manager

Method Description
setMicrophoneVolume Sets the volume of the microphone.
getMicrophoneVolume Gets the volume of the microphone.
setSpeakerVolume Sets the volume of the speaker.
getSpeakerVolume Gets the volume of the speaker.
setMicrophoneMute Captures or stop capturing the local audio with the microphone.
getMicrophoneMute Gets the mute state of the microphone.
setSpeakerMute Plays or stops playing the remote audio with the speaker.
getSpeakerMute Gets the mute state of the speaker.
setDefaultAudioRouting Sets the default audio routing. Applies to Android and iOS only.
changeAudioRouting Changes the current audio routing. Applies to Android and iOS only.
getCurrentRouting Gets the current audio routing. Applies to Android and iOS only.
getNumberOfPlayoutDevices Gets the index numbers of all playout devices. Applies to Windows and macOS only.
getNumberOfRecordingDevices Gets the index numbers of all recording devices. Applies to Windows and macOS only.
getPlayoutDeviceInfo Gets the information of the current audio playout device. Applies to Windows and macOS only.
getRecordingDeviceInfo Gets the information of the current recording device. Applies to Windows and macOS only.
setPlayoutDevice Sets the audio playback device. Applies to Windows and macOS only.
setRecordingDevice Sets the recording device. Applies to Windows and macOS only.
setApplicationVolume Sets the volume of the app. Applies to Windows only.
getApplicationVolume Gets the volume of the app. Applies to Windows only.
setApplicationMuteState Sets the mute state of the app.
getApplicationMuteState Gets the mute state of the app.
registerObserver Registers an IAudioDeviceManagerObserver object.
unregisterObserver Releases the IAudioDeviceManagerObserver object.
Event Description
onDeviceStateChanged Occurs when the device state changes.
onRoutingChanged Occurs when the audio route changes.

Video data sender

Method Description
sendVideoFrame Sends the video frame to the video track.
sendEncodedVideoImage Sends the encoded video image to the video track.

Video filter

Method Description
setEnabled Enables or disables the video filter.
isEnabled Checks whether the video filter is enabled.
setProperty Sets a private property in the IVideoFilter class.
getProperty Gets a private property in the IVideoFilter class.
setBeautyEffectOptions Sets the beauty effect options.
adaptVideoFrame Adapts the video frame.

Video renderer

Method Description
setRenderMode Sets the render mode.
setMirror Sets whether to mirror the video.
setView Sets the video display window.
unsetView Stops rendering the video view on the window.
onFrame Occurs when the IVideoSinkBase object receives the video frame.

Video camera capturer

Method Description
setCameraSource Sets the camera source. Applies to Android and iOS only.
getCameraSource Gets the camera source. Applies to Android and iOS only.
createDeviceInfo Creates a DeviceInfo object. Applies to Windows, macOS, and Linux only.
initWithDeviceId Initialize the device with the device ID. Applies to Windows, macOS, and Linux only.
initWithDeviceName Initializes the device with the device name. Applies to Windows, macOS, and Linux only.
setCaptureFormat Sets the format of the video captured by the camera.
getCaptureFormat Gets the format of the video captured by the camera.

Video screen capturer

Method Description
initWithDisplayId Initializes the screen capturer by specifying a display ID. Applies to macOS only.
initWithScreenRect Initializes the screen capturer by specifying a screen Rect. Applies to Windows only.
initWithWindowId Initializes the screen capturer by specifying a window ID. Applies to Windows and macOS only.
setContentHint Sets the content hint for screen sharing. Applies to Windows and macOS only.
updateScreenCaptureRegion Updates the screen capture region. Applies to Windows and macOS only.

Media player

Method Description
open Opens a media file with a specified URL.
play Plays the media file.
stop Stops playing the current media file.
pause Pauses playing the media file.
getDuration Gets the duration of the media file.
registerPlayerSourceObserver Registers a media player source observer.
unregisterPlayerSourceObserver Releases the media player source observer.
Event Description
onPlayerSourceStateChanged Occurs when the state of the media player has changed.
onPositionChanged Occurs when the playback position of the media player has changed.

RTMP streaming service

Method Description
addPublishStreamUrl Publishes the local stream to the CDN.
removePublishStreamUrl Removes an RTMP stream from the CDN.
setLiveTranscoding Sets the video layout and audio settings for CDN live.
registerObserver Registers a RTMP streaming observer.
unregisterObserver Releases the RTMP streaming observer.
Event Description
onRtmpStreamingStateChanged Occurs when the state of the RTMP streaming has changed.
onStreamPublished Reports the result of calling addPublishStreamUrl.
onStreamUnpublished Reports the result of calling removePublishStreamUrl.
onTranscodingUpdated Occurs when the publisher's transcoding settings are updated.

RTM service

Method Description
initialize Initializes and gets an IRtmService instance.
unregisterObserver Releases the IRtmServiceEventHandler object.
release Releases the IRtmService instance.
login Logs in the RTM service.
logout Logs out of the RTM service.
sendMessageToPeer Sends a peer message to s specified remote user.
createChannel Creates an RTM channel.
Event Description
onLoginSuccess Occurs when the user successfully logs in the RTM service.
onLoginFailure Occurs when the user fails to log in the RTM service.
onLogout Occurs when the user successfully logs out of the RTM service.
onConnectionStateChanged Occurs when the connection state of the local user has changed.
onSendMessageState Reports the state of sending a message.
onMessageReceivedFromPeer Occurs when the local user receives a message from a remote user.

RTM channel

Method Description
setEventHandler Sets an event handler for IChannel
join Joins the current channel.
leave Leaves the current channel.
sendMessage Sends a channel message.
updateAttributes Updates the channel attributes.
deleteAttributes Removes the channel attributes.
getId Gets the current request ID.
release Releases the IChannel instance.
getMemberId Gets the ID of the channel member.
getChannelId Gets the ID of the channel.
release Release the IChannelMember class.
createChannelAttributes Creates an IChannelAttributes instance.
addAttribute Adds an attribute to a specified channel.
removeAttribute Removes an attribute from the channel.
getAttributesSize Gets the size of the attributes.
getAttributes Gets the channel attributes.
getAttributeValue Gets the value of a channel attribute using the attribute key.
release Releases the IChannelAttributes instance.
Event Description
onJoinSuccess Occurs when the local user successfully joins the channel.
onJoinFailure Occurs when the local user fails to join the channel.
onLeave Occurs when the local user leaves the channel.
onMessageReceived Occurs when the local user receives the channel message.
onSendMessageState Reports the state od the message sent by the local user.
onMemberJoined Occurs when another member joins the channel.
onMemberLeft Occurs when the other member leaves the channel.
onMembersGotten Reports all members in the channel
onAttributesUpdated Occurs when the channel attributes are updated.
onUpdateAttributesResponse Occurs when the local user calls updateAttributes.
onAttributedDeleted Occurs when the channel attributed are deleted.
onDeleteAttributesResponse Occurs when the local user calls deleteAttributes.

RTM message

Method Description
createMessage Creates an IMessage instance.
getMessageId Gets the ID of the message.
getMessageType Gets the message type.
setText Sets the content of the text message, or the text description of the raw message.
getText Gets the content of the text message, or the text description of the raw message.
release Releases the IMessage instance.