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
- RTC connection
- Local user
- Local audio track
- Remote audio track
- Local video track
- Remote video track
- Media node factory
- Audio data sender
- Audio filter
- Audio device manager
- Video data sender
- Video filter
- Video renderer
- Video camera capturer
- Video screen capturer
- Media player
- RTMP streaming service
- RTM service
- RTM channel
- RTM message

## 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.
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:

- IAgoraService::createCameraVideoTrack
- IAgoraService::createScreenVideoTrack
- IAgoraService::createCustomVideoTrack1
- IAgoraService::createCustomVideoTrack2
- IAgoraService::createCustomVideoTrack3

. 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.
setSimulcastStreamMode | Set the simulcast stream mode.
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.
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.