Agora C++ API Reference for All Platforms

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
- Video data sender

## 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, etc.

Method | Description
--- | ---
createAgoraService | Creates an IAgoraService object and returns the pointer.
initialize | Initializes the IAgoraService object.
release | Releases the IAgoraService object.
setLogFile | Sets the log file path and size.
setLogFilter | Sets the log output level.
createRtcConnection | Creates an RTC connection object and returns the pointer.
createCustomAudioTrack1 | Creates a local audio track object with the PCM data receiver and returns the pointer.
createCustomAudioTrack2 | Creates a local audio track object with the receiver for encoded audio data and returns the pointer.
createMediaNodeFactory | Creates a media node factory and returns the pointer.
createCustomVideoTrack1 | Creates a local video track object with the custom video source ans returns the pointer.
createCustomVideoTrack2 | Creates a local video track object with the receiver for encoded video data and returns the pointer.

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

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.
onLastmileProbeResult | Reports the last-mile network probe result.
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.

## 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.
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.
onLocalAudioTrackStatistics | Reports the statistics of the local audio track.
onRemoteAudioTrackStatistics | Reports the statistics of the remote audio track.
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.

## Local audio track

A local audio track can be created by createCustomAudioTrack.

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.
isEnabled | Gets whether the local audio track is enabled.
getState | Gets the state of the local audio.
GetStats | Gets the statistics of the local audio track.
adjustPublishVolume | Adjusts the audio volume for publishing.
getPublishVolume | Gets the current volume for publishing.

## Remote audio track

Method | Description
--- | ---
getStatistics | Gets the statistics of the remote audio track.
getState | Gets the state of the remote audio.

## Local video track

A local video track can be created by createCustomVideoTrack.

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.
getState | Gets the state of the local video.

## Remote video track

Method | Description
--- | ---
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.
addRenderer | Adds a video renderer to 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.
createVideoFrameSender | Creates a video frame sender.
createVideoEncodedImageSender | Creates an encoded video image sender.

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

## Video data sender

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