The Interactive Gaming Audio Only API is composed of Objective-C Interface and C++ Interface:

Objective-C Interface

Basic Methods (AgoraRtcEngineKit)

AgoraRtcEngineKit is the basic interface class of Agora Native SDK. Creating an AgoraRtcEngineKit object and then calling the methods of this object enables the use of Agora Native SDK’s communication functionality.

Initialize (sharedEngineWithAppId)

+ (instancetype _Nonnull)sharedEngineWithAppId:(NSString * _Nonnull)appId
                                      delegate:(id<AgoraRtcEngineDelegate> _Nullable)delegate;

This method initializes the AgoraRtcEngineKit class as a singleton instance. Call this method to initialize service before using AgoraRtcEngineKit.

The SDK uses Delegate to inform the application on the engine runtime events. All methods defined in Delegate are optional implementation methods.

Name Description
appId The App ID issued to the application developers by Agora. Apply for a new one from Agora if the key is missing in your kit.
delegate

Set the Channel Profile (setChannelProfile)

- (int)setChannelProfile:(AgoraChannelProfile)profile;

This method configures the channel profile. The Agora RtcEngine needs to know what scenario the application is in to apply different methods for optimization.

The Agora Native SDK supports the following profiles:

Profile Description
Communication Default setting. This is used in one-on-one calls, where all users in the channel can talk.
Live Broadcast Live Broadcast. Host and audience roles that can be set by calling setClientRole. The host sends and receives voice, while the audience receives voice only with the sending function disabled.
Gaming Gaming Mode. Any user in the channel can talk freely. This mode uses the codec with low-power consumption and low bitrate by default.
  • Only one profile can be used at the same time in the same channel. If you want to switch to another profile, use destroy to destroy the current Engine and create a new one using sharedEngineWithAppId before calling this method to set the new channel profile.
  • Make sure that different App IDs are used for different channel profiles.
  • This method must be called and configured before a user joining a channel, because the channel profile cannot be configured when the channel is in use.
Name Description
profile

The channel profile. Choose one of the following:

  • AgoraChannelProfileCommunication = 0: Communication (default)
  • AgoraChannelProfileLiveBroadcasting = 1: Live Broadcast
  • AgoraChannelProfileGame = 2: Gaming
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.

Set the User Role (setClientRole)

- (int)setClientRole:(AgoraClientRole)role;

In a live broadcasr channel, this method allows you:

  • Set the user role as a host or an audience (default) before joining a channel;
  • Switch the user role after joining a channel.
Name Description
role The user role in a live broadcast:
  • AgoraClientRoleBroadcaster = 1; Host
  • AgoraClientRoleAudience = 2; Audience (default)
Return Value
  • 0: The Method is called successfully
  • <0: Failed to call the method

Enable the Audio Mode (enableAudio)

- (int)enableAudio;

This method enables the audio mode. The application can call this method either before joining a channel. This function is enabled by default.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

This method sets to enable the internal engine, and still works after leaveChannel is called.

Disables/Re-enables the Local Audio Function (enableLocalAudio)

- (int)enableLocalAudio:(BOOL)enabled;

When an App joins a channel, the audio function is enabled by default. This method disables or re-enables the local audio function, that is, to stop or restart local audio capturing and handling.
This method does not affect receiving or playing the remote audio streams, and is applicable to scenarios where the user wants to receive the remote audio streams without sending any audio stream to other users in the channel.
The didMicrophoneEnabled callback function will be triggered once the local audio function is disabled or re-enabled.

  • Call this method after joinChannelByToken.
  • This method is different from muteLocalAudioStream:
    • enableLocalAudio: Disables/Re-enables the local audio capturing and handling.
    • muteLocalAudioStream: Stops/Continues sending the local audio streams.
Name Description
enabled
  • true: Re-enable the local audio function, that is, to start local audio capturing and handling.
  • false: Disable the local audio function, that is, to stop local audio capturing and handling.
Return Value
  • 0: Success
  • <0: Failure

Disable the Audio Mode (disableAudio)

- (int)disableAudio;

This method disables the audio mode.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

This method sets to disable the internal engine, and still works after leaveChannel is called.

Set the Audio Profile (setAudioProfile)

- (int)setAudioProfile:(AgoraAudioProfile)profile
        scenario:(AgoraAudioScenario)scenario;

This method sets the audio parameters and application scenarios.

This API is only valid when you call it before joining a channel.

Name Description
profile

Sets the sampling rate, bitrate, encode mode, and the number of channels:

  • AgoraAudioProfileSpeechStandard = 1: Specifies the sampling rate as 32 kHz, audio encoding, single channel, and bitrate up to 18 kbit/s
  • AgoraAudioProfileMusicStandard = 2: Specifies the sampling rate as 48 kHz, music encoding, single channel, and bitrate up to 48 kbit/s
  • AgoraAudioProfileMusicStandardStereo = 3: Specifies the sampling rate as 48 kHz, music encoding, dual-channel, and bitrate up to 56 kbit/s
  • AgoraAudioProfileMusicHighQuality = 4: Specifies the sampling rate as 48 kHz, music encoding, single channel, and bitrate up to 128 kbit/s
  • AgoraAudioProfileMusicHighQualityStereo = 5: Specifies the sampling rate as 48 kHz, music encoding, dual-channel, and bitrate up to 192 kbit/s
scenario

Sets the audio application scenarios:

  • AgoraAudioScenarioDefault = 0: default
  • AgoraAudioScenarioChatRoomEntertainment = 1: Applicable to the entertainment scenario that supports voice during gameplay
  • AgoraAudioScenarioEducation = 2: Applicable to the education scenario that prioritizes fluency and stability
  • AgoraAudioScenarioGameStreaming = 3: Applicable to the live gaming scenario that needs to enable the gameing audio effects in the speaker mode in a live broadcast scenario. Choose this scenario if you wish to achieve high-fidelity music play
  • AgoraAudioScenarioShowRoom = 4: Applicable to the showroom scenario that optimizes the audio quality with professional external equipment
  • AgoraAudioScenarioChatRoomGaming = 5: Applicable to the gaming scenario
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.
  • Use this method before joinChannelByToken, else it does not work.
  • In the communication mode, setting profile works, but not scenario.
  • In the communication and live-broadcast mode, the bitrate may be different from your settings due to network self-adaptation.
  • In scenarios with music teaching, Agora recommends setting profile as MusicHighQuality(4) and scenario as GameStreaming(3).
  • ChatRoomEntertainment(1) and ChatRoomGaming(5) are recommended for audio-only scenarios.

Set High-quality Audio Preferences (setHighQualityAudioParametersWithFullband)

- (int)setHighQualityAudioParametersWithFullband:(BOOL)fullband
                            stereo:(BOOL)stereo
                       fullBitrate:(BOOL)fullBitrate;

This method sets high-quality audio preferences. Call this method and set all the three modes before joining a channel. Do NOT call this method again after joining channel.

Name Description
fullband

Full-band codec (48 kHz sampling rate), not compatible with versions before v1.7.4.

  • True: Enable full-band codec.
  • False: Disable full-band codec.
stereo

Stereo codec, not compatible with versions before v1.7.4.

  • True: Enable stereo codec.
  • False: Disable stereo codec.
fullBitrate

High bitrate. Recommended in voice-only mode.

  • True: Enable high bitrate mode.
  • False: Disable high bitrate mode.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Agora does not recommend using this method. If you want to set the audio profile, see setAudioProfile .

Join a Channel (joinChannelByToken)

- (int)joinChannelByToken:(NSString * _Nullable)token
                channelId:(NSString * _Nonnull)channelId
                     info:(NSString * _Nullable)info
                      uid:(NSUInteger)uid
              joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock;

This method allows a user to join a channel. Users in the same channel can talk to each other; and multiple users in the same channel can start a group chat. Users using different App IDs cannot call each other. Once in a call, the user must call the leaveChannel method to exit the current call before entering another channel. This method is called asynchronously; therefore, it can be called in the main user interface thread.

The SDK uses the OS X’s AVAudioSession shared object for audio recording and playing, so using this object may affect the SDK’s audio functions.

Once this method is called successfully, the SDK will trigger the callback. If both joinChannelSuccessBlock and didJoinChannel are implemented, the priority of joinChannelSuccessBlock is higher than didJoinChannel, thus didJoinChannel will be ignored. If you want to use didJoinChannel, set joinChannelSuccessBlock as nil.

A channel does not accept duplicate UIDs, such as two users with the same UID. If your app supports logging in a user from different devices at the same time, ensure that you use different UIDs. For example, if you already used the same UID, make the UIDs different by adding the respective device ID to the UID. This is not applicable if your app does not support a user logging in from different devices at the same time. In this case, when you log in a new device, you will be logged out from the other device.

Name Description
token

A Token generated by the application.

This parameter is optional if the user uses a static App ID. In this case, pass NIL as the parameter value.

If the user uses a Token, Agora issues an additional App Certificate to the application developers. The developers can then generate a user key using the algorithm and App Certificate provided by Agora for user authentication on the server.

In most circumstances, the static App ID will suffice. For added security, use a Token.

channelName

A string providing the unique channel name for the AgoraRTC session. The length must be within 64 bytes.

The following is the supported scope: a-z, A-Z, 0-9, space, !

#$%&, ()+,

-, :;<=., >?

@[], ^_, {|}, ~

info (Optional) Any additional information the developer wants to add. [1] It can be set as a NIL Sting or channel related information. Other users in the channel will not receive this information.
uid (Optional) User ID: A 32-bit unsigned integer ranging from 1 to (2^32-1). It must be unique. If not assigned (or set to 0), the SDK assigns one and returns it in the joinSuccessBlock callback. The app must record and maintain the returned value, as the SDK does not maintain it.
joinSuccessBlock Callback on user successfully joined the channel.

[1] For example, when a host wants to customize the resolution and bitrate for a live broadcast channel with CDN Live enabled, they can include them in this parameter in JSON format. For example, {“owner”:true, …, “width”:300, “height”:400, “bitrate”:100}. Only when neither width, height, and bitrate is 0 can the bitrate and resolution settings take effect.

When joining a channel, the SDK calls setCategory AVAudioSessionCategoryPlayAndRecord to set AVAudioSession to PlayAndRecord mode. The application should not set it to any other mode. When setting to this mode, the sound being played (for example a ringtone) will be interrupted.

Leave a Channel (leaveChannel)

- (int)leaveChannel:(void(^ _Nullable)(AgoraChannelStats * _Nonnull stat))leaveChannelBlock;

This method allows a user to leave a channel, such as hanging up or exiting a call. After joining a channel, the user must call the leaveChannel method to end the call before joining another one.

The leaveChannel method releases all resources related to the call. The leaveChannel method is called asynchronously, and the user has not actually left the channel when the call returns. When the user leaves the channel, the SDK triggers the didLeaveChannelWithstats callback.

If you call destroy() immediately after leaveChannel, the leaveChannel process will be interrupted, and the SDK will not trigger the didLeaveChannelWithstats callback.

Name Description
leaveChannelBlock Callback on user successfully left the channel.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Local Voice Pitch (setLocalVoicePitch)

- (int) setLocalVoicePitch:(double) pitch;

This method changes the voice pitch of the local speaker.

Name Description
pitch Voice frequency, in the range of [0.5, 2.0]. The default value is 1.0.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Sets the Voice Position of the Remote user (setRemoteVoicePosition)

- (int)setRemoteVoicePosition:(int)uid pan:(double)pan gain:(double)gain;

This method sets the voice position of the remote user.

This API is valid only for earphones, and is invalid when the speakerphone is enabled.

Name Description
uid

User ID of the remote user

pan

Sets whether to change the spatial position of the audio effect. The range is [-1, 1]:

  • 0: The audio effect shows right ahead.
  • -1: The audio effect shows on the left.
  • 1: The audio effect shows on the right.
gain

Sets whether to change the volume of a single audio effect. The range is [0.0, 100.0]. The default value is 100.0. The smaller the number is, the lower the volume of the audio effect.

Return Value
  • 0: Success
  • < 0: Failure

Sets to Voice-only Mode (setVoiceOnlyMode)

- (int)setVoiceOnlyMode:(bool)enable;

This method sets to voice-only mode (transmit the audio stream only), and the other streams will be ignored; for example the sound of the keyboard strokes.

Name Description
enable
  • true: Enable voice-only mode.
  • false: Disable voice-only mode.
Return Value
  • 0: Success
  • < 0: Failure

Set the Local Voice Equalization (setLocalVoiceEqualizationOfBandFrequency)

- (int)setLocalVoiceEqualizationOfBandFrequency:(AgoraAudioEqualizationBandFrequency)bandFrequency withGain:(NSInterger)gain;

This method sets the local voice equalization.

Name Description
bandFrequency The band frequency ranging from 0 to 9; representing the respective 10-band center frequencies of the voice effects, including 31, 62, 125, 500, 1k, 2k, 4k, 8k, and 16k Hz.
gain Gain of each band in dB; ranging from -15 to 15.
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.

Set the Local Voice Reverberation (setLocalVoiceReverbOfType)

- (int)setLocalVoiceReverbOfType:(AgoraAudioReverbType)reverbType withValue:(NSInterger)value;

This method sets the local voice reverberation.

Name Description
reverbType The reverberation types. This method contains five reverberation types. For details, see the description of each value:
value
  • AgoraAudioReverbDryLevel = 0, (dB, [-20,10]), level of the dry signal
  • AgoraAudioReverbWetLevel = 1, (dB, [-20,10]), level of the early reflection signal (wet signal)
  • AgoraAudioReverbRoomSize = 2, ([0, 100]), room size of the reflection
  • AgoraAudioReverbWetDelay = 3, (ms, [0, 200]), length of the initial latency of the wet signal in ms
  • AgoraAudioReverbStrength = 4, ([0, 100]), length of the late reverberation
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.

Enable Web SDK Interoperability (enableWebSdkInteroperability)

- (int)enableWebSdkInteroperability:(BOOL)enabled;

This method enables interoperability with the Agora Web SDK.

Name Description
enabled

Whether to enable the interoperability with the Agora Web SDK is enabled:

  • True: Enable the interoperability
  • False: Disable the interoperability
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Default Audio Route (setDefaultAudioRouteToSpeakerPhone)

- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeaker;

This method sets whether the received audio is routed to the earpiece or speakerphone.

  • Call this method only if you want to change the default settings.
  • This method only works in audio mode.
  • Call this method before joinChannel.

If the user does not call this method, the audio is routed to the earpiece by default.

Name Description
defaultToSpeaker YES: Audio is routed to the speakerphone
NO: Audio is routed to the earpiece
Return Value 0: Method call succeeded.
<0: Method call failed.

Enable the Speakerphone (setEnableSpeakerphone)

- (int)setEnableSpeakerphone:(BOOL)enableSpeaker;

This method enables the audio routing to the speaker. Ensure that the joinChannelByKey method has been executed successfully before calling this method.

The SDK calls setCategory AVAudioSessionCategoryPlayAndRecord with options to configure the headset/speaker, so any sound will be interrupted when calling this method.

After this method is called, the SDK returns the didAudioRouteChanged callback, indicating that the audio routing has changed.

Name Description
enableSpeaker Yes: Switches to the speaker.
No: Switches to the headset.
Return Value 0: Method call succeeded.
<0: Method call failed.

Check Whether the Speakerphone is Enabled (isSpeakerphoneEnabled)

- (BOOL)isSpeakerphoneEnabled;

This method checks whether the speakerphone is enabled.

Name Description
Return Value
  • Yes: Yes, enabled.
  • No: No, not enabled.

Enable In-ear Monitoring (enableInEarMonitoring)

- (int)enableInEarMonitoring:(BOOL)enabled;

This method enables or disables the in-ear monitoring function.

Name Description
enabled
  • YES: Enable in-ear monitoring
  • NO: Disable in-ear monitoring (default)
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Audio Session Operation Restriction (setAudioSessionOperationRestriction)

- (void)setAudioSessionOperationRestriction:(AgoraAudioSessionOperationRestriction)restriction;

The SDK and the app can both configure the audio session by default. The app may occassionally use other applications or third-party components to manipulate the audio session and restrict the SDK from doing so. This API allows the app to restrict the SDK’s manipulation of the audio session.

  • You can call this method before or after joining the channel.
  • This method restricts the SDK’s manipulation of the audio session. Any operation to the audio session relies solely on the app, other applications, or third-party components.
Name Description
restriction

The operational restriction of the SDK on the audio session. It comes as a bit mask.

  • AgoraAudioSessionOperationRestrictionNone = 0: No restrictions. The SDK has full control over the audio session operation.
  • AgoraAudioSessionOperationRestrictionSetCategory = 1: The SDK cannot change the category of the audio session.
  • AgoraAudioSessionOperationRestrictionConfigurationSession = 1 << 1: The SDK cannot change the category, mode or categoryOptions of the audio session.
  • AgoraAudioSessionOperationRestrictionDeactivateSession = 1 << 2: The SDK cannot deactivate the session when it leaves the channel.
  • AgoraAudioSessionOperationRestrictionAll = 1 << 7: Restricts the SDK from manipulating the audio session.

Enable the Audio Volume Indication (enableAudioVolumeIndication)

- (int)enableAudioVolumeIndication:(NSInteger)interval
                            smooth:(NSInteger)smooth;

This method allows the SDK to regularly report to the application on which user is speaking and the volume of the speaker. Once the method is enabled, the SDK returns the volume indications at the set time internal in the reportAudioVolumeIndicationOfSpeakers and audioVolumeIndicationBlock callback, regardless of whether anyone is speaking in the channel.

Name Description
interval

Time interval between two consecutive volume indications:

  • <= 0: Disables the volume indication
  • > 0: The time interval between two consecutive volume indications in milliseconds. Agora recommends setting it to more than 200 ms. Do not set it lower than 10 ms, or the reportAudioVolumeIndicationOfSpeakers callback will not be triggered.
smooth The Smoothing factor that determines the sensitivity of this method. The range is [0-10] and Agora recommends setting it 3. The bigger the number, the more sensitive it is.
Return values
  • 0: Method call succeeded
  • < 0: Method call failed

Set the Volume of In-ear Monitor (setInEarMonitoringVolume)

- (int)setInEarMonitoringVolume:(NSInteger)volume;

This method sets the volume of the in-ear monitor.

Name Description
volume Volume of the in-ear monitor, ranging from 0 to 100. The default value is 100.
Return values
  • 0: Method call succeeded.
  • < 0: Method call failed.

Get the Audio Effect Volume (getEffectsVolume)

- (double)getEffectsVolume;

This method gets the volume of the audio effects from 0.0 to 100.0.

Set the Audio Effect Volume (setEffectsVolume)

- (int)setEffectsVolume:(double)volume;

This method sets the volume of the audio effects.

Name Description
volume Value ranging from 0.0 to 100.0. 100.0 is the default value.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Adjust the Audio Effect Volume in Real Time (setVolumeOfEffect)

- (int)setVolumeOfEffect:(int)soundId
              withVolume:(double)volume;

This method adjusts the volume of the specified audio effect in real time.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
volume Value ranging from 0.0 to 100.0. 100.0 is the default value.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Play the Audio Effect (playEffect)

- (int)playEffect:(int)soundId
         filePath:(NSString * _Nullable)filePath
        loopCount:(int)loopCount
            pitch:(double)pitch
              pan:(double)pan
             gain:(double)gain
          publish:(BOOL)publish;

This method plays the specified audio effect.

Name Description
soundId ID of the specified audio effect. Each audio effect has a unique ID [4]
filePath The absolute path of the audio effect file
loopCount

Set the number of times looping the audio effect

  • 0: Play the audio effect once
  • 1: Play the audio effect twice
  • -1: Play the audio effect in a loop indefinitely, until stopEffect or stopAllEffects is called
pitch Set whether to change the pitch of the audio effect. The range is [0.5, 2]. The default value is 1, which means no change to the pitch. The smaller the value, the lower the pitch.
pan

Spatial position of the local audio effect. The range is [-1.0, 1.0]

  • 0.0: The audio effect shows ahead
  • 1.0: The audio effect shows on the right
  • -1.0: The audio effect shows on the left
gain Volume of the audio effect. The range is [0.0, 100,0] The default value is 100.0. The smaller the value, the lower the volume of the audio effect
publish

Set whether to publish the specified audio effect to the remote stream:

  • true: The audio effect, played locally, is published to the Agora Cloud and the remote users can hear it
  • false: The audio effect, played locally, is not published to the Agora Cloud and the remote users cannot hear it
Return Value
  • 0: Method call succeeded
  • < 0: Method call failed

[4] If you preloaded the audio effect into the memory through preloadEffect, ensure that the soundID value is set to the same value as in preloadEffect.

In version v2.1.x, the following method, which is not recommended by Agora, is used.

- (int) playEffect: (int) soundId
          filePath: (NSString*) filePath
              loop: (BOOL) loop
             pitch: (double) pitch
               pan: (double) pan
              gain: (double) gain;

Stop Playing an Audio Effect (stopEffect)

- (int)stopEffect:(int)soundId;

This method stops playing a specified audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Stop Playing all Audio Effects (stopAllEffects)

- (int)stopAllEffects;

This method stops playing all the audio effects.

Preload an Audio Effect (preloadEffect)

- (int)preloadEffect:(int)soundId
            filePath:(NSString * _Nullable) filePath;

This method preloads a specific audio effect file (compressed audio file) to the memory.

To ensure smooth communication, pay attention to the size of the audio effect file. Agora recommends using this method to preload the audio effect before calling joinChannelByToken.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
filePath Absolute path of the audio effect file.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Release an Audio Effect (unloadEffect)

- (int)unloadEffect:(int)soundId;

This method releases a specific preloaded audio effect from the memory.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Pause an Audio Effect (pauseEffect)

- (int)pauseEffect:(int)soundId;

This method pauses a specific audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Pause all Audio Effects (pauseAllEffects)

- (int)pauseAllEffects;

This method pauses all the audio effects.

Name Description
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Resume an Audio Effect (resumeEffect)

- (int)resumeEffect:(int)soundId;

This method resumes playing a specific audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Resume all Audio Effects (resumeAllEffects)

- (int) esumeAllEffects;

This method resumes all the audio effects.

Mute the Local Audio Stream (muteLocalAudioStream)

- (int)muteLocalAudioStream:(BOOL)mute;

This method mutes/unmutes the local audio.

Name Description
mute
  • True: Mutes the local audio.
  • False: Unmutes the local audio.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute all Remote Audio Streams (muteAllRemoteAudioStreams)

- (int)muteAllRemoteAudioStreams:(BOOL)mute;

This method mutes/unmutes all remote users’ audio streams.

Name Description
muted
  • True: Stops playing all received audio streams.
  • False: Resumes playing all received audio streams.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute a Specified Remote Audio Stream (muteRemoteAudioStream)

- (int)muteRemoteAudioStream:(NSUInteger)uid muted:(BOOL)mute;

Mute/unmute a specified remote user’s audio stream.

When set to True, this method stops playing audio streams without affecting the audio stream receiving process.

Name Description
uid User ID whose audio streams the user intends to mute.
mute
  • True: Stops playing a specified user’s audio streams.
  • False: Allows playing a specified user’s audio streams.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Start Audio Mixing (startAudioMixing)

- (int)startAudioMixing:(NSString *  _Nonnull)filePath
               loopback:(BOOL)loopback
                replace:(BOOL)replace
                  cycle:(NSInteger)cycle;

This method mixes the specified local audio file with the audio stream from the microphone; or, it replaces the microphone’s audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of loop playbacks. This API also supports online music playback.

  • To use the startAudioMixing API, ensure the iOS device version is 8.0 or later.
  • Call this API when you are in a channel, otherwise it may cause issues.
Name Description
filePath Name and path of the local audio file to be mixed.
Supported audio formats: mp3, aac, m4a, 3gp, and wav.
loopback True: Only the local user can hear the remix or the replaced audio stream.
False: Both users can hear the remix or the replaced audio stream.
replace True: The content of the local audio file replaces the audio stream from the microphone.
False: Local audio file mixed with the audio stream from the microphone.
cycle Number of loop playbacks:
Positive integer: Number of loop playbacks
-1:Infinite loop
Return Value 0: Method call succeeded.
<0: Method call failed.

Stop Audio Mixing (stopAudioMixing)

- (int)stopAudioMixing;

This method stops audio mixing. Call this API when you are in a channel.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Pause Audio Mixing (pauseAudioMixing)

- (int)pauseAudioMixing;

This method pauses audio mixing. Call this API when you are in a channel.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Resume Audio Mixing (resumeAudioMixing)

- (int)resumeAudioMixing;

This method resumes audio mixing. Call this API when you are in a channel.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Adjust the Audio Mixing Volume (adjustAudioMixingVolume)

- (int)adjustAudioMixingVolume:(NSInteger)volume;

This method adjusts the volume during audio mixing. Call this API when you are in a channel.

Name Description
volume Volume ranging from 0 to 100. By default, 100 is the original volume.
Return Value 0: Method call succeeded.
<0: Method call failed.

Get the Audio Mixing Duration (getAudioMixingDuration)

- (int)getAudioMixingDuration;

This method gets the duration (ms) of audio mixing. Call this API when you are in a channel.

Get Current Audio Position (getAudioMixingCurrentPosition)

- (int)getAudioMixingCurrentPosition;

This method gets the playback position (ms) of the audio. Call this API when you are in a channel.

Drag the Audio Progress Bar (setAudioMixingPosition)

- (int)setAudioMixingPosition:(NSInteger)pos;

This method drags the playback progress bar of the audio mixing file to where you want to play instead of playing it from the beginning.

Name Description
pos Integer. The position of the audio mixing file (ms).

Start an Audio Recording (startAudioRecording)

- (int)startAudioRecording:(NSString * _Nonnull)filePath
                   quality:(AgoraAudioRecordingQuality)quality;

This method starts an audio recording. The SDK allows recording during a call, which supports either one of the following two formats:

  • .wav: Large file size with high sound fidelity OR

  • .aac: Small file size with low sound fidelity

Ensure that the saving directory in the application exists and is writable. This method is usually called after the joinChannelByToken method. The recording automatically stops when the leaveChannel method is called.

Name Description
filePath Full file path of the recording file. The string of the file name is in UTF-8 code.
quality

Audio recording quality:

  • AgoraRtc_AudioRecordingQuality_Low = 0: Low quality, file size around 1.2 MB after 10 minutes of recording
  • AgoraRtc_AudioRecordingQuality_Low = 1: Medium quality, file size around 2 MB after 10 minutes of recording
  • AgoraRtc_AudioRecordingQuality_Low = 2: High quality, file size around 3.75 MB after 10 minutes of recording
Return Value
  • 0: Method call succeeded
  • <0: Method call failed.

Stop an Audio Recording (stopAudioRecording)

- (int)stopAudioRecording;

This method stops recording on the client.

Call this method before calling leaveChannel, otherwise the recording automatically stops when the leaveChannel method is called.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Adjust the Recording Volume (adjustRecordingSignalVolume)

- (int)adjustRecordingSignalVolume:(NSInteger)volume;

This method adjusts the recording volume.

Name Description
volume

Recording volume, ranges from 0 to 400:

  • 0: Mute
  • 100: Original volume
  • 400: (Maximum) Four times the original volume with signal clipping protection
Return Value 0: Method call succeeded.
<0: Method call failed.

Adjust the Playback Volume (adjustPlaybackSignalVolume)

- (int)adjustPlaybackSignalVolume:(NSInteger)volume;

This method adjusts the playback volume.

Name Description
volume

Playback volume, ranges from 0 to 400:

  • 0: Mute
  • 100: Original volume
  • 400: (Maximum) Four times the original volume with signal clipping protection
Return Value 0: Method call succeeded.
<0: Method call failed.

Enable Built-in Encryption and Set the Encryption Secret (setEncryptionSecret)

- (int)setEncryptionSecret:(NSString * _Nullable)secret;

Use setEncryptionSecret to specify an encryption password to enable built-in encryption before joining a channel. All users in a channel must set the same encryption password. The encryption password is automatically cleared once a user has left the channel. If the encryption password is not specified or set to empty, the encryption function will be disabled.

Do not use this function together with CDN.

Name Description
secret Encryption Password
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Built-in Encryption Mode (setEncryptionMode)

- (int)setEncryptionMode:(NSString * _Nullable)encryptionMode;

The Agora Native SDK supports built-in encryption, which is in AES-128-XTS mode by default. If you want to use other modes, call this API to set the encryption mode.

All users in the same channel must use the same encryption mode and password. Refer to information related to the AES encryption algorithm on the differences between encryption modes.

Call setEncryptionSecret to enable the built-in encryption function before calling this API.

Do not use this function together with CDN.

Name Description
encryptionMode

Encryption mode. The following modes are currently supported:

  • “aes-128-xts”:128-bit AES encryption, XTS mode
  • “aes-128-ecb”:128-bit AES encryption, ECB mode
  • “aes-256-xts”: 256-bit AES encryption, XTS mode
  • “”: When it is set to NUL string, the encryption is in “aes-128-xts” by default.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Create a Data Stream (createDataStream)

- (int)createDataStream:(NSInteger * _Nonnull)streamId
               reliable:(BOOL)reliable
                ordered:(BOOL)ordered;

This method creates a data stream. Each user can only have up to five data channels at the same time.

Set reliable and ordered both as True or both as False. Do not set one as True and the other as False.

Name Description
reliable
  • True: The recipients will receive data from the sender within 5 seconds. If the recipient does not receive the sent data within 5 seconds, the data channel will report an error to the application.
  • False: The recipients may not receive any data, and the SDK will not report any error upon data missing.
ordered
  • True: The recipients will receive data in the order of the sender.
  • False: The recipients will not receive data in the order of the sender.
Return Value
  • <0: Returns an error code when it fails to create the data stream. [5]
  • >0: Returns the Stream ID when the data stream is created.

[5] The error code is related to the positive integer displayed in Error Codes and Warning Codes for example, if it returns -2, then it indicates 2: ERR_INVALID_ARGUMENT in Error Codes and Warning Codes.

Send a Data Stream (sendStreamMessage)

- (int)sendStreamMessage:(NSInteger)streamId
                    data:(NSData * _Nonnull)data;

This method sends data stream messages to all users in a channel. Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 kB. The API controls the data channel transfer rate. Each client can send up to 6 kB of data per second. Each user can have up to five data channels simultaneously.

Name Description
streamId Stream ID.
message Data to be sent
Return Value When it fails to send the message, the following error code will be returned: ERR_SIZE_TOO_LARGE/ERR_TOO_OFTEN/ERR_BITRATE_LIMIT

Start an Audio Call Test (startEchoTest)

- (int)startEchoTest:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))successBlock;

This method launches an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly. In the test, the user first speaks, and the recording is played back in 10 seconds. If the user can hear the recording in 10 seconds, it indicates that the audio devices and network connection work properly.

  • After calling the startEchoTest method, call stopEchoTest to end the test; otherwise, the application cannot run the next echo test, nor can it call the joinChannel method to start a new call.
  • This method is applicable only when the user role is broadcaster. If you switch the channel mode from communication to live broadcast, ensure that setClientRole is called to change the user role from audience(default in the live broadcast mode) to broadcaster before using this method.
Name Description
successBlock Callback on successfully starting the echo test. See joinSuccessBlock in joinChannelByToken for a description of the callback parameters.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
  • ERR_REFUSED (-5): Failed to launch the echo test, for example, initialization failed.

Stop an Audio Call Test (stopEchoTest)

- (int)stopEchoTest;

This method stops an audio call test.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
  • ERR_REFUSED(-5): Failed to stop the echo test. It could be that the echo test is not running.

Enable the Network Test (enableLastmileTest)

- (int)enableLastmileTest;

This method tests the quality of the user’s network connection and is disabled by default.

This method is mainly used in two scenarios:

  • Before users join a channel, this method can be called to check the uplink network quality.

  • Before the audience in a channel switch to a host role, this method can be called to check the uplink network quality.

In both scenarios, calling this method consumes extra network traffic, which affects the communication quality.

Call disableLastmileTest to disable it immediately once the users have received the onLastmileQuality callback before they join the channel or switch the user role.

For current hosts, do not call this method.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Disable the Network Test (disableLastmileTest)

- (int)disableLastmileTest;

This method disables the network connection quality test.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Retrieve the Current Call ID (getCallId)

- (NSString * _Nullable)getCallId;

When a user joins a channel on a client, a CallId is generated to identify the call from the client. Some methods such as rate and complain need to be called after the call ends in order to submit feedback to the SDK. These methods require assigned values of the CallId parameters. To use these feedback methods, call the getCallId method to retrieve the CallId during the call, and then pass the value as an argument in the feedback methods after the call ends.

Name Description
Return Value Current call ID.

Rate the Call (rate)

- (int)rate:(NSString * _Nonnull)callId
     rating:(NSInteger)rating
description:(NSString * _Nullable)description;

This method lets the user rate the call. It is usually called after the call ends.

Name Description
callId Call ID retrieved from the getCallId method.
rating Rating for the call between 1 (lowest score) to 10 (highest score).
description A given description for the call with a length less than 800 bytes.
This parameter is optional.
Return Value 0: Method call succeeded.
<0: Method call failed.
ERR_INVALID_ARGUMENT (-2): The passed argument is invalid, for example, callId invalid.
ERR_NOT_READY (-3): The SDK status is incorrect, for example, initialization failed.

Complain about the Call Quality (complain)

- (int)complain:(NSString * _Nonnull)callId
    description:(NSString * _Nullable)description;

This method allows the user to complain about the call quality. It is usually called after the call ends.

Name Description
callId Call ID retrieved from the getCallId method.
description A given description of the call with a length less than 800 bytes.
This parameter is optional.
Return Value 0: Method call succeeded.
<0: Method call failed.
ERR_INVALID_ARGUMENT (-2): The passed argument is invalid, for example, callId invalid.
ERR_NOT_READY (-3): The SDK status is incorrect, for example, initialization failed.

Renew Token (renewToken)

- (int)renewToken:(NSString * _Nonnull)token;

This method updates the Token.

The key expires after a certain period of time once the Token schema is enabled when:

  • The rtcEngine:didOccurError: callback reports the ERR_TOKEN_EXPIRED(109) error, or

  • The rtcEngineRequestToken: callback reports the ERR_TOKEN_EXPIRED(109) error, or

The application should retrieve a new key and then call this method to renew it. Failure to do so will result in the SDK disconnecting from the server.

Name Description
token Token to be renewed.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Specify a Log File (setLogFile)

- (int)setLogFile:(NSString * _Nonnull)filePath;

This method specifies an SDK output log file. The log file records all the log data of the SDK’s operation. Ensure that the directory to save the log file exists and is writable.

Name Description
filePath File path of the log file. The string of the log file is in UTF-8 code.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

The default log file location is at: Library/caches/agorasdk.log.

Set the Log Filter (setLogFilter)

- (int)setLogFilter:(NSUInteger)filter;

This method sets the output log level of the SDK. You can use either one or a combination of the filters.

The log level follows the sequence of Off, Critical, Error, Warning, Info, and Debug. Choose a level, and you can see logs that precede that level.

For example, if you set the log level as Warning, then you can see logs in levels Critical, Error and Wwarning.

Name Description
filter

Set the levels of the filters:

  • AgoraLogFilterOff = 0: Output no log.
  • AgoraLogFilterDebug = 0x080f: Output all the API logs.
  • AgoraLogFilterInfo = 0x000f: Output logs of the CRITICAL, ERROR, WARNING and INFO level.
  • AgoraLogFilterWarning = 0x000e: Output logs of the CRITICAL, ERROR and WARNING level.
  • AgoraLogFilterError = 0x000c: Output logs of the CRITICAL and ERROR level.
  • AgoraLogFilterCritical = 0x0008: Output logs of the CRITICAL level.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Destroy the Engine Instance (destroy)

+ (void)destroy;

This method releases all the resources used by the Agora SDK. This is useful for applications that occasionally make voice or video calls, to free up resources for other operations when not making calls.

Once the application has called destroy() to destroy the created RtcEngine instance, no other methods in the SDK can be used and no callbacks occur. To start communications again, initialize sharedEngineWithappId to establish a new AgoraRtcEngineKit instance.

  • Use this method in the sub thread.
  • This method is called synchronously. The result returns after the IRtcEngine object resources are released. The app should not call this interface in the callback generated by the SDK, otherwise the SDK must wait for the callback to return before it can reclaim the related object resources, causing a deadlock.

Get the SDK Version (getSdkVersion)

+ (NSString * _Nonnull)getSdkVersion;

This method returns the string of the SDK version number.

Delegate Methods (AgoraRtcEngineDelegate)

The SDK uses Delegate methods AgoraRtcEngineDelegate to report runtime events to the application. From v1.1, some Block callbacks in the SDK are replaced with Delegate methods. The old Block callbacks are therefore being deprecated, but can still be used in the current version. However, we recommend replacing them with Delegate methods. The SDK calls the Block method if a callback is defined in both Block and Delegate.

Warning Occurred Callback (didOccurWarning)

- (void)rtcEngine:(AgoraRtcEngineKit *)engine didOccurWarning:(AgoraRtcErrorCode)warningCode;

This callback method indicates that some warning occurred during SDK runtime. In most cases, the application can ignore the warnings reported by the SDK because the SDK can usually fix the issue and resume running.

For instance, the SDK may report an AgoraRtc_Error_OpenChannelTimeout(106) warning upon disconnection with the server and attempts to reconnect.

Name Description
warningCode The warning code.

Error Occurred Callback (didOccurError)

- (void)rtcEngine:(AgoraRtcEngineKit *)engine didOccurError:(AgoraRtcErrorCode)errorCode;

This callback indicates that a network or media error occurred during SDK runtime. In most cases, reporting an error means that the SDK cannot fix the issue and resume running, and therefore requires actions from the application or simply informs the user on the issue. For instance, the SDK reports an AgoraRtc_Error_StartCall(1002) error when failing to initialize a call. In this case, the application informs the user that the call initialization failed and calls the leaveChannel method to exit the channel.

Name Description
Engine The AgoraRtcEngineKit Object.
errorCode Error code.

API Call Executed Callback (didApiCallExecute)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didApiCallExecute:(NSInteger)error api:(NSString * _Nonnull)api result:(NSString * _Nonnull)result;

This callback is triggered when the API has been executed.

Name Description
error The error code that the SDK returns when the method call fails. If the SDK returns o, then the method has been called successfully.
api The API that the SDK executes
result The result of calling the API

Join Channel Callback (didJoinChannel)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didJoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger) elapsed;

Same as joinSuccessBlock in the joinChannelByToken API. This callback indicates that the user has successfully joined the specified channel.

Name Description
channel Channel name.
uid

User ID.

If the uid is specified in the joinChannelByToken method, returns the specified ID; if not, returns an ID that is automatically allocated by the Agora server.

elapsed Time elapsed (ms) from calling joinChannelByToken until this event occurs.

Rejoin Channel (didRejoinChannel)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didRejoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger) elapsed;

If the client loses connection with the server because of network problems, the SDK automatically attempts to reconnect, and then triggers this callback method upon reconnection, indicating that the user has rejoined the channel with the assigned channel ID and user ID.

Name Description
channel Channel name.
uid User ID.
elapsed Time elapsed (ms) from calling joinChannelByToken until this event occurs.

User Left Channel Callback (didLeaveChannelWithStats)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didLeaveChannelWithStats:(AgoraChannelStats * _Nonnull)stats;

When the user executes leaveChannel() successfully, SDK will trigger this callback. Same as leaveChannelBlock.

Definition of AgoraChannelStats

__attribute__((visibility("default"))) @interface AgoraChannelStats: NSObject
@property (assign, nonatomic) NSInteger duration;
@property (assign, nonatomic) NSInteger txBytes;
@property (assign, nonatomic) NSInteger rxBytes;
@property (assign, nonatomic) NSInteger txAudioKBitrate;
@property (assign, nonatomic) NSInteger rxAudioKBitrate;
@property (assign, nonatomic) NSInteger txVideoKBitrate;
@property (assign, nonatomic) NSInteger rxVideoKBitrate;
@property (assign, nonatomic) NSInteger lastmileDelay;
@property (assign, nonatomic) NSInteger userCount;
@property (assign, nonatomic) double cpuAppUsage;
@property (assign, nonatomic) double cpuTotalUsage;
@end
Name Description
stats

Statistics of the call:

  • duration: Call duration in seconds, represented by an aggregate value.
  • txBytes: Total number of bytes transmitted, represented by an aggregate value.
  • rxBytes: Total number of bytes received, represented by an aggregate value.
  • txAudioKBitrate: Audio transmission bitrate in kbit/s, represented by an instantaneous value.
  • rxAudioKBitRate: Audio receive bitrate in kbit/s, represented by an instantaneous value.
  • txVideoKBitRate: Video transmission bitrate in kbit/s, represented by an instantaneous value.
  • rxVideoKBitRate: Video receive bitrate in kbit/s, represented by an instantaneous value.
  • lastmileDelay: The time delay in milliseconds from the Client to the VO Server
  • users: The instant number of users in the channel when the user leaves the channel.
  • puTotalUsage: System CPU usage (%).
  • cpuAppUsage: Application CPU usage (%).

Audio Route Changed Callback (didAudioRouteChanged)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didAudioRouteChanged:(AgoraAudioOutputRouting)routing;

This callback is triggered when the audio routing is changed. The definition of AgoraAudioOutputRouting is listed as follows:

typedef NS_ENUM(NSInteger, AgoraAudioOutputRouting)
{
    AgoraAudioOutputRoutingDefault = -1,
    AgoraAudioOutputRoutingHeadset = 0,
    AgoraAudioOutputRoutingEarpiece = 1,
    AgoraAudioOutputRoutingHeadsetNoMic = 2,
    AgoraAudioOutputRoutingSpeakerphone = 3,
    AgoraAudioOutputRoutingLoudspeaker = 4,
    AgoraAudioOutputRoutingHeadsetBluetooth = 5
};

The State of the Microphone Has Changed Callback (didMicrophoneEnabled)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didMicrophoneEnabled:(BOOL)enabled;
Name Description
enabled
  • true: The microphone is enabled.
  • false: The microphone is disabled.

Audio Quality Callback (audioQualityOfUid)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine audioQualityOfUid:(NSUInteger)uid quality:(AgoraNetworkQuality)quality delay:(NSUInteger)delay lost:(NSUInteger)lost;

Same as audioQualityBlock. During a call, this callback is triggered once every two seconds to report on the audio quality of the current call.

Name Description
uid User ID of the speaker
quality

Rating of the audio quality:

  • AgoraNetworkQualityUnknown(0): The network quality is unknown.
  • AgoraNetworkQualityExcellent(1): The network quality is excellent.
  • AgoraNetworkQualityGood(2): The network quality is quite good, but the bitrate may be slightly lower than excellent.
  • AgoraNetworkQualityPoor(3): Users can feel the communication slightly impaired.
  • AgoraNetworkQualityBad(4): Users can communicate only not very smoothly.
  • AgoraNetworkQualityVBad(5): The network is so bad that users can hardly communicate.
  • AgoraNetworkQualityDown(6): Users cannot communicate at all.
delay Time delay in milliseconds.
lost The packet loss rate(%).

Audio Volume Indication Callback (reportAudioVolumeIndicationOfSpeakers)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine reportAudioVolumeIndicationOfSpeakers:(NSArray<AgoraRtcAudioVolumeInfo *> * _Nonnull)speakers totalVolume:(NSInteger)totalVolume;

Same as audioVolumeIndicationBlock. By default this notification is disabled. If you need it, use the enableAudioVolumeIndication method to configure it.

Name Description
speakers

The speakers (array). Each speaker ():

  • uid: User ID of the speaker. By default, 0 means the local user.
  • volume: The volume of the speaker that ranges from 0 (lowest volume) to 255 (highest volume).
totalVolume Total volume after audio mixing that ranges from 0 (lowest volume) to 255 (highest volume).

In the returned speakers array:

  • If the uid is 0, that is, the local user is the speaker, the returned volume is the same as totalVolumn.

  • If the uid is not 0 and the volume is 0, it indicates that the user specified by the uid did not speak.

  • If a uid is contained in the previous speakers array but not in the present one, it indicates that the user specified by the uid did not speak.

Other User Joined Callback (didJoinedOfUid)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didJoinedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed;

Same as userJoinedBlock. This callback method notifies the application the broadcaster has joined the channel. If the broadcaster is already in the channel when the application joins the channel, the SDK also reports to the application on the broadcaster that is already in the channel.

In the live broadcast scenario:

  • The broadcaster can receive the callback when another broadcaster joins the channel.
  • All the audience in the channel can receive the callback when the new broadcaster joins the channel.
  • When a web application joins the channel, this callback is triggered as long as the web application publishes streams.
Name Description
uid

User ID of the host.

If the uid is specified in the joinChannelByToken method, returns the specified ID; if not, returns an ID that is automatically allocated by the Agora server.

elapsed Time elapsed (ms) from calling joinChannelByToken until this callback is triggered.

Other User Offline Callback (didOfflineOfUid)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didOfflineOfUid:(NSUInteger)uid reason:(AgoraUserOfflineReason)reason;

Same as userOfflineBlock. This callback indicates that the broadcaster has left the call or gone offline.

The SDK reads the timeout data to determine if a user has left the channel (or has gone offline). If no data package is received from the user in 15 seconds, the SDK assumes the user is offline. A poor network connection may lead to false detections; therefore, use signaling for reliable offline detection.

Name Description
uid User ID.
reason

This callback is triggered when:

  • AgoraRtc_UserOffline_Quit(0): A user has quit the call.
  • AgoraRtc_UserOffline_Dropped(1): The SDK timed out and the user dropped offline because it has not received any data package within a certain period of time. If a user quits the call and the message is not passed to the SDK (due to an unreliable channel), the SDK assumes the event has timed out.

Other User Muted Audio Callback (didAudioMuted)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didAudioMuted:(BOOL)muted byUid:(NSUInteger)uid;

Same as userMuteAudioBlock. This callback indicates that some other user has muted/unmuted his/her audio streams.

Currently, this callback returns invalid when the number of broadcasters in a channel exceeds 20, which will be improved in the future.

Name Description
uid User ID.
muted Yes: User has muted his/her audio.
No: User has unmuted his/her audio.

RtcEngine Statistics Callback (reportRtcStats)

- (void)rtcEngine:(AgoraRtcEngineKit *)engine
reportRtcStats:(AgoraRtcStats*)stats;

Same as rtcStatsBlock. The SDK updates the application on the statistics of the RtcEngine runtime status once every two seconds.

Name Description
stat See descriptions in User Left Channel Callback (didLeaveChannelWithStats) .

Channel Network Quality Callback (networkQuality)

- (void)rtcEngine:(AgoraRtcEngineKit *)engine networkQuality:(NSUInteger)uid txQuality:(AgoraRtcQuality)txQuality rxQuality:(AgoraRtcQuality)rxQuality;

This callback is triggered every 2 seconds to update the application on the current network quality of each user in a communication or live broadcast channel.

Name Description
uid
User ID. The network quality of the user with this UID will be reported.

If uid is 0, it reports the local network quality.

txQuality

The transmission quality of the user:

  • AgoraNetworkQualityUnknown(0): The network quality is unknown.
  • AgoraNetworkQualityExcellent(1): The network quality is excellent.
  • AgoraNetworkQualityGood(2): The network quality is quite good, but the bitrate may be slightly lower than excellent.
  • AgoraNetworkQualityPoor(3): Users can feel the communication slightly impaired.
  • AgoraNetworkQualityBad(4): Users can communicate only not very smoothly.
  • AgoraNetworkQualityVBad(5): The network is so bad that users can hardly communicate.
  • AgoraNetworkQualityDown(6): Users cannot communicate at all.
rxQuality

The receiving quality of the user:

  • AgoraNetworkQualityUnknown(0): The network quality is unknown.
  • AgoraNetworkQualityExcellent(1): The network quality is excellent.
  • AgoraNetworkQualityGood(2): The network quality is quite good, but the bitrate may be slightly lower than excellent.
  • AgoraNetworkQualityPoor(3): Users can feel the communication slightly impaired.
  • AgoraNetworkQualityBad(4): Users can communicate only not very smoothly.
  • AgoraNetworkQualityVBad(5): The network is so bad that users can hardly communicate.
  • AgoraNetworkQualityDown(6): Users cannot communicate at all.

Device Changed Callback (stateChanged)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine device:(NSString * _Nonnull) deviceId type:(AgoraMediaDeviceType) deviceType stateChanged:(NSInteger) state;
Name Description
deviceId Device ID
deviceType -1: Audio unknown
0: Audio recording
1: Audio playback
2: Render
3: Capture
state 0: Device is added
1: Device is removed

Connection Interrupted Callback (rtcEngineConnectionDidInterrupted)

- (void)rtcEngineConnectionDidInterrupted:(AgoraRtcEngineKit * _Nonnull)engine;

This method indicates that the SDK has lost connection with the server.

This method is triggered upon connection lost, while the onConnectionLost method is triggered when the SDK attempts to reconnect after losing connection. Once the connection is lost, and if the application does not call leaveChannel, the SDK automatically tries to reconnect repeatedly.

Connection Lost Callback (rtcEngineConnectionDidLost)

- (void)rtcEngineConnectionDidLost:(AgoraRtcEngineKit * _Nonnull)engine;

This callback indicates that the SDK has lost connection with the network, and it has remained unconnected for a period of time (10 seconds by default) despite that it attempts to reconnect. It is also triggered when the SDK fails to join the channel 10 seconds after it calls joinChannel. The SDK will keep trying to reconnect after this callback is triggered. Upon reconnection, an onRejoinChannelSuccess callback will then be triggered.

Connection Banned Callback (rtcEngineConnectionDidBanned)

- (void)rtcEngineConnectionDidBanned:(AgoraRtcEngineKit * _Nonnull)engine;

This callback is triggered when your connection is banned by the Agora Server.

First Remote Audio Frame Received Callback (firstRemoteAudioFrameOfUid)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine firstRemoteAudioFrameOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed;

This callback method is triggered when the first remote audio frame is received.

Name Description
uid The UID of the remote user whose audio frame is received.
elapsed Time elapsed (ms) from calling joinChannel until this callback is triggered.

Data Stream Received Callback (receiveStreamMessageFromUid)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine receiveStreamMessageFromUid:(NSUInteger)uid streamId:(NSInteger)streamId data:(NSData * _Nonnull)data;

This callback indicates that the local user has received the data stream from the other user within five seconds.

Name Description
uid User ID
streamId Stream ID
data Data received by the recipients.

Data Stream Sent Failure Callback (didOccurStreamMessageErrorFromUid)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didOccurStreamMessageErrorFromUid:(NSUInteger)uid streamId:(NSInteger)streamId error:(NSInteger)error missed:(NSInteger)missed cached:(NSInteger)cached;

This callback indicates that the local user has not received the data stream from the other user within five seconds.

Name Description
uid User ID
streamId Stream ID
error
  • ERR_OK = 0, No error
  • ERR_NOT_IN_CHANNEL=113, the user is not in a channel
  • ERR_BITRATE_LIMIT=115, limited bitrate

For more error code descriptions, see Error Codes and Warning Codes.

missed The number of lost messages
cached The number of incoming cached messages when the data stream is interrupted

Active Speaker Detected Callback (ActiveSpeaker)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine activeSpeaker:(NSUInteger)speakerUid;

If you have used the enableAudioVolumeIndication API, this callback is triggered then the volume detecting unit has detected active speaker in the channel. Also returns with the uid of the active speaker.

Name Description
speakerUid The UID of the active speaker. By default, 0 means the local user. If needed, you can also add relative functions on your App, for example, the active speaker, once detected, will have his/her head portrait zoomed in.
  • You need to call enableAudioVolumeIndication to receive this callback.
  • The active speaker means the uid of the speaker who speaks at the highest volume during a certain period of time.

Refer to the following code for the logic:

 - (void)rtcEngine:(AgoraRtcEngineKit *)engine activeSpeaker:(NSUInteger)speakerUid {
[self switchToMainViewOfSpeaker:speakerUid];
}

User Role Changed Callback (didClientRoleChanged)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didClientRoleChanged:(AgoraClientRole)oldRole newRole:(AgoraClientRole)newRole;

This callback is triggered when the user role is switched, for example, from a host to an audience or vice versa.

Name Description
oldRole Role that you switched from.
newRole Role that you switched to.

API Call Executed Callback (didApiCallExecute)

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didApiCallExecute:(NSInteger)error api:(NSString * _Nonnull)api result:(NSString * _Nonnull)result;

This callback indicates that the API call has been executed.

Method API String Parameter Status Code
settRemoteVideoStream rtc.video.set_remote_video_stream See Error Codes and Warning Codes

Token Expired Callback (rtcEngineRequestToken)

- (void)rtcEngineRequestToken:(AgoraRtcEngineKit * _Nonnull)engine;

If a Token is specified when calling joinChannelByToken, and due to Token will be expired after a certain amount of time, and if SDK lost the connection with the Agora server out of network issues, it might need a new Token to reconnect to the server.

This callback notifies the application of generating a new Token, and calling renewtoken to specify the newly generated Token.

This function was previously provided in the callback report of didOccurError(): ERR_TOKEN_EXPIRED(109), ERR_INVALID_TOKEN(110). Starting from v1.7.3, the old method is still working, but it is recommended for you to put the related logic in this callback.

This function was previously provided when the callback reported didOccurError(): ERR_CHANNEL_KEY_EXPIRED(109)、ERR_INVALID_CHANNEL_KEY(110). Starting from v1.7.3, the old method still works, but it is recommended to use this callback.

Local Audio Mixing Playback Finished Callback (rtcEngineLocalAudioMixingDidFinish)

- (void)rtcEngineLocalAudioMixingDidFinish:(AgoraRtcEngineKit * _Nonnull)engine;

This callback is triggered when the audio mixing file playback is finished after calling startAudioMixing. If you failed to execute the startAudioMixing method, it returns the error code in the didOccurError callback.

Local Audio Effect Playback Finished Callback (rtcEngineDidAudioEffectFinish)

- (void)rtcEngineDidAudioEffectFinish:(AgoraRtcEngineKit * _Nonnull)engine soundId:(NSInteger)soundId;
Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.

Remote Audio Mixing Started Callback (rtcEngineRemoteAudioMixingDidStart)

- (void)rtcEngineRemoteAudioMixingDidStart:(AgoraRtcEngineKit * _Nonnull)engine;

This callback is triggered when a remote host calls startAudioMixing.

Remote Audio Mixing Stopped Callback (rtcEngineRemoteAudioMixingDidFinish)

- (void)rtcEngineRemoteAudioMixingDidFinish:(AgoraRtcEngineKit * _Nonnull)engine;

This callback is triggered when a remote host stops calling startAudioMixing.

Block Callbacks

The SDK supports Block callbacks to report runtime events to the application. From version 1.1, some Block callbacks in the SDK are replaced with Delegate methods. The old Block callbacks are therefore being deprecated, but can still be used in current versions. However, we recommend replacing them with Delegate methods. The SDK calls the Block method if a callback is defined in both Block and Delegate. If you want to use the Delegate methods, set the Block attribute of the method as nil. The following section describes each of the callback methods in the SDK.

Other User Joined Callback (userJoinedBlock)

- (void)userJoinedBlock:(void(^)
(NSUInteger uid, NSInteger elapsed))userJoinedBlock;

This callback method notifies the application the broadcaster has joined the channel. If the broadcaster is already in the channel when the application joins the channel, the SDK also reports to the application on the broadcaster that is already in the channel.

In the live broadcast scenario:

  • The broadcaster can receive the callback when another broadcaster joins the channel.
  • All the audience in the channel can receive the callback when the new broadcaster joins the channel.
  • When a web application joins the channel, this callback is triggered as long as the web application publishes streams.
Name Description
uid User ID.
If the uid is specified in the joinChannelByToken method, returns the specified ID; if not, returns an ID that is automatically allocated by the Agora server.
elapsed Time elapsed (ms) from calling joinChannelByToken until this callback is triggered.

Other User offline Callback (userOfflineBlock)

- (void)userOfflineBlock:(void(^)
(NSUInteger uid))userOfflineBlock;

This callback indicates that a user has left the call or gone offline.

The SDK reads the timeout data to determine if a user has left the channel (or has gone offline). If no data package is received from the user in 15 seconds, the SDK assumes the user is offline. Sometimes a weak network connection may lead to false detections, therefore we recommend using signaling for reliable offline detection.

Name Description
uid User ID.

Rejoin Channel Callback (rejoinChannelSuccessBlock)

 - (void)rejoinChannelSuccessBlock:(void(^)(NSString* channel,
NSUInteger uid, NSInteger elapsed))rejoinChannelSuccessBlock;

When the local machine loses connection with the server because of network problems, the SDK automatically attempts to reconnect, and then triggers this callback method upon reconnection. The callback indicates that the user has rejoined the channel with an assigned channel ID and user ID.

Name Description
channel Channel name.
uid User ID.
elapsed Time delay (ms) in rejoining the channel.

User Left Channel Callback (leaveChannelBlock)

- (void)leaveChannelBlock:(void(^)
(AgoraRtcStats* stat))leaveChannelBlock;

This callback indicates that a user has left the channel, and it also provides call session statistics including the duration of the call and tx/rx bytes.

Name Description
stat See the table below.
AgoraRtcStats Description
duration Call duration (s), represented by an aggregate value.
txBytes Total number of bytes transmitted, represented by an aggregate value.
rxBytes Total number of bytes received, represented by an aggregate value.

RtcEngine Statistics Callback (rtcStatsBlock)

- (void)rtcStatsBlock:(void(^)
(AgoraRtcStats* stat))rtcStatsBlock;

This callback is triggered once every two seconds to update the application on RtcEngine runtime statistics.

Name Description
stat See the table below.
AgoraRtcStats Description
duration Call duration (s), represented by an aggregate value.
txBytes Total number of bytes transmitted, represented by an aggregate value.
rxBytes Total number of bytes received, represented by an aggregate value.

Audio Volume Indication Callback (audioVolumeIndicationBlock)

- (void)audioVolumeIndicationBlock:(void(^)(NSArray *speakers,
NSInteger totalVolume))audioVolumeIndicationBlock;

This callback indicates who is talking and the speaker’s volume. By default it is disabled. If needed, use the enableAudioVolumeIndication method to configure it.

Name Description
speakers The speakers (array). Each speaker ():
uid: User ID of the speaker.
volume:Volume of the speaker, between 0 (lowest volume) to 255 (highest volume).
totalVolume The total volume after audio mixing between 0 (lowest volume) to 255 (highest volume).

Other User Muted Audio Callback (userMuteAudioBlock)

- (void)userMuteAudioBlock:(void(^)
(NSUInteger uid, bool muted))userMuteAudioBlock;

This callback indicates that a user has muted/unmuted his/her audio stream.

Name Description
uid User ID.
muted Yes: Muted audio.
No: Unmuted audio.

Audio Quality Callback (audioQualityBlock)

- (void)audioQualityBlock:(void(^)(NSUInteger uid,
AgoraNetworkQuality quality,  NSUInteger delay,
NSUInteger lost))audioQualityBlock;

During a conversation, this callback is triggered once every two seconds to report on the audio quality of the current call.

Name Description
uid User ID of the speaker
quality

Rating of the audio quality:

  • AgoraNetworkQualityUnknown(0): The network quality is unknown.
  • AgoraNetworkQualityExcellent(1): The network quality is excellent.
  • AgoraNetworkQualityGood(2): The network quality is quite good, but the bitrate may be slightly lower than excellent.
  • AgoraNetworkQualityPoor(3): Users can feel the communication slightly impaired.
  • AgoraNetworkQualityBad(4): Users can communicate only not very smoothly.
  • AgoraNetworkQualityVBad(5): The network is so bad that users can hardly communicate.
  • AgoraNetworkQualityDown(6): Users cannot communicate at all.
delay Time delay in milliseconds.
lost The packet loss rate(%).

Network Quality Callback (lastmileQualityBlock)

- (void)lastmileQualityBlock:(void(^)
(AgoraNetworkQuality quality))lastmileQualityBlock;

This callback is triggered once every two seconds during a call to report on the network quality.

Name Description
quality Rating of the network quality:
AgoraRtc_Quality_Unknown = 0
AgoraRtc_Quality_Excellent = 1
AgoraRtc_Quality_Good = 2
AgoraRtc_Quality_Poor = 3
AgoraRtc_Quality_Bad = 4
AgoraRtc_Quality_VBad = 5
AgoraRtc_Quality_Down = 6

Connection Lost Callback (connectionLostBlock)

- (void)connectionLostBlock:(void(^)())connectionLostBlock;

This callback indicates that the SDK has lost network connection with the server.

Data Stream Received Callback (receiveStreamMessageFromUid)

- (void)rtcEngine:(AgoraRtcEngineKit *)engine receiveStreamMessageFromUid:(NSUInteger)uid streamId:(NSInteger)streamId data:(NSData*)data;

This callback indicates that the local user has received the data stream from the other user within five seconds.

Name Description
uid User ID
streamId Stream ID
data Data received by the recipients.

Data Stream Sent Failure Callback (didOccurStreamMessageErrorFromUid)

- (void)rtcEngine:(AgoraRtcEngineKit *)engine didOccurStreamMessageErrorFromUid:(NSUInteger)uid streamId:(NSInteger)streamId error:(NSInteger)error missed:(NSInteger)missed cached:(NSInteger)cached;

This callback indicates that the local user has not received the data stream from the other user within five seconds.

Name Description
uid User ID
streamId Stream ID
code
  • ERR_OK = 0, No error
  • ERR_NOT_IN_CHANNEL=113, the user is not in a channel
  • ERR_SIZE_TOO_LARGE=114, data size is too big
  • ERR_BITRATE_LIMIT=115, limited bitrate
  • ERR_TOO_MANY_DATA_STREAMS =116, too many data streams
  • ERR_STREAM_MESSAGE_TIMEOUT=117, data stream timed out

For more error code descriptions, see Error Codes and Warning Codes.

missed The number of lost messages
cached The number of incoming cached messages when the data stream is interrupted

User Role Changed Callback (didClientRoleChanged)

- (void)rtcEngine:(AgoraRtcEngineKit *)engine didClientRoleChanged:(AgoraClientRole)oldRole newRole:(AgoraClientRole)newRole;

This callback is triggered when the user role is switched, for example, from a host to an audience or vice versa.

Name Description
oldRole Role that you switched from.
newRole Role that you switched to.

Audio Route Changed Callback (didAudioRouteChanged)

- (void)rtcEngine:(AgoraRtcEngineKit *)engine didAudioRouteChanged:(AgoraAudioOutputRouting)routing;

This callback is triggered when the audio routing is changed. The definition of AgoraAudioOutputRouting is listed as follows:

typedef NS_ENUM(NSInteger, AgoraAudioOutputRouting)
{
    AgoraAudioOutputRoutingDefault = -1,
    AgoraAudioOutputRoutingHeadset = 0,
    AgoraAudioOutputRoutingEarpiece = 1,
    AgoraAudioOutputRoutingHeadsetNoMic = 2,
    AgoraAudioOutputRoutingSpeakerphone = 3,
    AgoraAudioOutputRoutingLoudspeaker = 4,
    AgoraAudioOutputRoutingHeadsetBluetooth = 5
};

C++ Interface

Basic Methods (IRtcEngine)

agora::IRtcEngine is the basic interface class of Agora Native SDK. Creating an agora::IRtcEngine object and then calling the methods of this object enables the use of Agora Native SDK’s communication functionality. In the previous versions this class is named as IAgoraAudio, and it is renamed to agora::IRtcEngine from version 1.0.

Create an agora::IRtcEngine Object (create)

agora::rtc::IRtcEngine* AGORA_CALL createAgoraRtcEngine();

This method creates an IRtcEngine object. Unless otherwise specified, all called methods provided by the RtcEngine class are executed asynchronously. Agora recommends calling the interface methods in the same thread. Unless otherwise specified, the following rule applies to all APIs whose return values are integer types: A return value of 0 indicates that the call was successful, and a return value less than 0 indicates that the call failed.

Name Description
Return Value An agora::IRtcEngine object.

Initialize (initialize)

virtual int initialize(const RtcEngineContext& context) = 0;

This method initializes the Agora SDK service. Enter the Agoran App ID issued to developers to start initialization. After creating an agora::IRtcEngine object, call this method to initialize service before using any other methods. After initialization, the service is set to audio mode by default. To enable video mode, call enableVideo API afterwards.

The definition of RTCEngineContext is:

struct RtcEngineContext
{
    IRtcEngineEventHandler* eventHandler;
    /** App ID issued to the developers by Agora. Apply for a new one from Agora if it is missing from your kit.
    */
    const char* appId;
    RtcEngineContext()
    :eventHandler(NULL)
    ,appId(NULL)
    {}
};
Name Description
appID App ID issued to application developers by Agora. Apply for a new one from Agora if the key is missing from your kit. See Getting an App ID for more information to how to get an App ID.
eventHandler IRtcEngineEventHandler is an abstract class that provides default implementations. The SDK uses this class to report to the application on SDK runtime events.
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.
  • ERR_INVALID_VENDOR_KEY(-101): The entered App ID is invalid.

Set a Channel Profile (setChannelProfile)

virtual int setChannelProfile(CHANNEL_PROFILE_TYPE profile) = 0;

This method configures the channel profile. The Agora RtcEngine needs to know what scenario the application is in to apply different methods for optimization.

The Agora Native SDK supports the following profiles:

Profile Description
Communication Default setting. This is used in one-on-one calls, where all users in the channel can talk freely.
Live Broadcast Live Broadcast. Host and audience roles that can be set by calling setClientRole. The host sends and receives voice, while the audience receives voice only with the sending function disabled.
Gaming Gaming Mode. Any user in the channel can talk freely. This mode uses the codec with low-power consumption and low bitrate by default.
  • Only one profile can be used at the same time in the same channel. If you want to switch to another profile, use release to destroy the current Engine and create a new one using create and initialize before calling this method to set the new channel profile.
  • Make sure that different App IDs are used for different channel profiles.
  • This method must be called and configured before a user joining a channel, because the channel profile cannot be configured when the channel is in use.
Name Description
profile

The channel profile. Choose one of the following:

  • CHANNEL_PROFILE_COMMUNICATION = 0: Communication (default)
  • CHANNEL_PROFILE_LIVE_BROADCASTING = 1: Live Broadcast
  • CHANNEL_PROFILE_GAME = 2: Gaming
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.

Set the User Role (setClientRole)

virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0;

In a live broadcast channel, this method allows you to:

  • Set the user role as a host or an audience (default) before joining a channel;
  • Switch the user role after joining a channel.
Name Description
role

The user role in a live broadcast:

  • CLIENT_ROLE_BROADCASTER = 1; Host
  • CLIENT_ROLE_AUDIENCE = 2; Audience(default)
Return Value
  • 0: The Method is called successfully
  • <0: Failed to call the method

Enable the Audio Mode (enableAudio)

virtual int enableAudio() = 0;

This method enables the audio mode. This function is enabled by default.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

This method sets to enable the internal engine, and still works after leaveChannel is called.

Disables/Re-enables the Local Audio Function (enableLocalAudio)

virtual int enableLocalAudio(bool enabled) = 0;

When an App joins a channel, the audio function is enabled by default. This method disables or re-enables the local audio function, that is, to stop or restart local audio capturing and handling.
This method does not affect receiving or playing the remote audio streams, and is applicable to scenarios where the user wants to receive the remote audio streams without sending any audio stream to other users in the channel.
The onMicrophoneEnabled callback function will be triggered once the local audio function is disabled or re-enabled.

  • Call this method after joinChannel.
  • This method is different from muteLocalAudioStream:
    • enableLocalAudio: Disables/Re-enables the local audio capturing and handling.
    • muteLocalAudioStream: Stops/Continues sending the local audio streams.
Name Description
enabled
  • true: Re-enable the local audio function, that is, to start local audio capturing and handling.
  • false: Disable the local audio function, that is, to stop local audio capturing and handling.
Return Value
  • 0: Success
  • <0: Failure

Disable the Audio Mode (disableAudio)

virtual int disableAudio() = 0;

This method disables the audio mode.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

This method sets to disable the internal engine, and still works after leaveChannel is called.

Set the Audio Profile (setAudioProfile)

virtual int setAudioProfile(AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario) = 0;

This method sets the audio parameters and application scenarios.

Name Description
profile

Sets the sampling rate, bitrate, encode mode, and the number of channels:

  • AUDIO_PROFILE_SPEECH_STANDARD = 1: Specifies the sampling rate as 32 kHz, audio encoding, single channel, and bitrate up tp 18 kbit/s
  • AUDIO_PROFILE_MUSIC_STANDARD = 2: Specifies the sampling rate as 48 kHz, music encoding, single channel, and bitrate up to 48 kbit/s
  • AUDIO_PROFILE_MUSIC_STANDARD_STEREO = 3: Specifies the sampling rate as 48 kHz, music encoding, dual-channel, and bitrate up to 56 kbit/s
  • AUDIO_PROFILE_MUSIC_HIGH_QUALITY = 4: Specifies the sampling rate as 48 kHz, music encoding, single channel, and bitrate up to 128 kbit/s
  • AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO = 5: Specifies the sampling rate as 48 kHz, music encoding, dual-channel, and bitrate up to 192 kbit/s
scenario

Sets the audio application scenarios:

  • AUDIO_SCENARIO_DEFAULT = 0: default
  • AUDIO_SCENARIO_CHARROOM_ENTERTAINMENT = 1: Applicable to the entertainment scenario that supports voice during gameplay
  • AUDIO_SCENARIO_EDUCATION = 2: Applicable to the education scenario that prioritizes fluency and stability
  • AUDIO_SCENARIO_GAME_STREAMING = 3: Applicable to the live gaming scenario that needs to enable the gaming audio effects in the speaker mode in a live broadcast scenario
  • AUDIO_SCENARIO_SHOWROOM = 4: Applicable to the showroom scenario that optimizes the audio quality with professional external equipment
  • AUDIO_SCENARIO_CHATROOM_GAMING = 5: Applicable to the gaming scenario
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.
  • Use this method before joinChannel, else it does not work.
  • In the communication mode, setting profile works, but not scenario.
  • In the communication and live-broadcast mode, the bitrate may be different from your settings due to network self-adaptation.
  • In scenarios with music teaching, Agora recommends setting profile as MUSIC_HIGH_QUALITY(4) and scenario as GAME_STREAMING(3).
  • CHATROOM_ENTERTAINMENT(1) and CHATROOM_GAMING(5) are recommended for audio-only scenarios.

Set High-quality Audio Preferences (setHighQualityAudioParameters)

int setHighQualityAudioParameters(boolean fullband, boolean stereo, boolean fullBitrate)

This method sets high-quality audio preferences. Call this method and set all the three modes before joining a channel. Do NOT call this method again after joining a channel.

Name Description
fullband

Full-band codec (48 kHz sampling rate), not compatible with versions before v1.7.4.

  • True: Enable full-band codec.
  • False: Disable full-band codec.
stereo

Stereo codec, not compatible with versions before v1.7.4.

  • True: Enable stereo codec.
  • False: Disable stereo codec.
fullBitrate

High bitrate. Recommended in voice-only mode.

  • True: Enable high bitrate mode.
  • False: Disable high bitrate mode.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Agora does not recommend using this method. If you want to set the audio profile, see setAudioProfile.

Join a Channel (joinChannel)

virtual int joinChannel(const char* token, const char* channelId, const char* info, uid_t uid) = 0;

This method allows a user to join a channel. Users in the same channel can talk to each other; and multiple users in the same channel can start a group chat. Users using different App IDs cannot call each other. Once in a call, the user must call the leaveChannel method to exit the current call before entering another channel.

A channel does not accept duplicate UIDs, such as two users with the same UID. If your app supports logging in a user from different devices at the same time, ensure that you use different UIDs. For example, if you already used the same UID, make the UIDs different by adding the respective device ID to the UID. This is not applicable if your app does not support a user logging in from different devices at the same time. In this case, when you log in a new device, you will be logged out from the other device.

Name Description
token

A Token generated by the application.

This parameter is optional if the user uses a static key, or App ID. In this case, pass NULL as the parameter value.

If the user uses a Channel key, Agora issues an additional App Certificate to the developers. The developers can then generate a user key using the algorithm and App Certificate provided by Agora for user authentication on the server.

In most circumstances, the static App ID will suffice. For added security, use the Channel Key.

channel

A string providing the unique channel name for the AgoraRTC session. The length must be within 64 bytes.

The following is the supported scope: a-z, A-Z, 0-9, space, ! #$%&, ()+, -, :;<=., >? @[], ^_, {|}, ~

info (Optional) Additional information about the channel that developers need to add. [1] It can be set as a NULL String or channel related information. Other users in the channel will not receive this message.
uid (Optional) User ID: A 32-bit unsigned integer ranging from 1 to (2^32-1). It must be unique. If not assigned (or set to 0), the SDK assigns one and returns it in the onJoinChannelSuccess callback. Your app must record and maintain the returned value, as the SDK does not maintain it.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
  • ERR_INVALID_ARGUMENT (-2): The passed argument is invalid.
  • ERR_NOT_READY (-3): Initialization failed.

[1] For example, when a host wants to customize the resolution and bitrate for a live broadcast channel with CDN Live enabled, they can include them in this parameter in JSON format. For example, {“owner”:true, …, “width”:300, “height”:400, “bitrate”:100}. Only when neither width, height, and bitrate is 0 can the bitrate and resolution settings take effect.

Leave a Channel (leaveChannel)

virtual int leaveChannel() = 0;

This method allows a user to leave a channel, such as hanging up or exiting a call.

After joining a channel, the user must call the leaveChannel method to end the call before joining another one. The leaveChannel method releases all resources related to the call. The leaveChannel method is called asynchronously, and the user has not actually left the channel when the call returns. Once the user leaves the channel, the SDK triggers the onLeaveChannel callback.

If you call release() immediately after you call leaveChannel, it will interrupt the leavechannel process, and the SDK will not trigger the onLeaveChannel callback.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
  • ERR_REFUSED (-5): Failed to leave the channel, reasons being that the user is not currently in a call or is in the process of leaving the channel.

Set the Local Voice Pitch (setLocalVoicePitch)

int setLocalVoicePitch(double pitch);

This method changes the voice pitch of the local speaker.

Name Description
pitch Voice frequency, in the range of [0.5, 2.0]. The default value is 1.0.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Sets the Voice Position of the Remote user (setRemoteVoicePosition)

virtual int setRemoteVoicePosition(int uid, double pan, double gain) = 0;

This method sets the voice position of the remote user.

This API is valid only for earphones, and is invalid when the speakerphone is enabled.

Name Description
uid

User ID of the remote user

pan

Sets whether to change the spatial position of the audio effect. The range is [-1, 1]:

  • 0: The audio effect shows right ahead.
  • -1: The audio effect shows on the left.
  • 1: The audio effect shows on the right.
gain

Sets whether to change the volume of a single audio effect. The range is [0.0, 100.0]. The default value is 100.0. The smaller the number is, the lower the volume of the audio effect.

Return Value
  • 0: Success
  • < 0: Failure

Sets to Voice-only Mode (setVoiceOnlyMode)

virtual int setVoiceOnlyMode(bool enable) = 0;

This method sets to voice-only mode (transmit the audio stream only), and the other streams will be ignored; for example the sound of the keyboard strokes.

Name Description
enable
  • true: Enable voice-only mode.
  • false: Disable voice-only mode.
Return Value
  • 0: Success
  • < 0: Failure

Set the Local Voice Equalization (setLocalVoiceEqualization)

int setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain);

This method sets the local voice equalization effect.

Name Description
bandFrequency The band frequency ranging from 0 to 9, representing the respective 10-band center frequencies of the voice effects, including 31, 62, 125, 500, 1k, 2k, 4k, 8k, and 16k Hz.
bandGain Gain of each band in dB; ranging from -15 to 15.
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.

Set the Local Voice Reverberation (setLocalVoiceReverb)

int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value)

This method sets local voice reverberation.

Name Description
reverbKey The reverberation key. This method contains five reverberation keys. For details, see the description of each value:
value
  • AUDIO_REVERB_DRY_LEVEL = 0, (dB, [-20,10]), level of the dry signal
  • AUDIO_REVERB_WET_LEVEL = 1, (dB, [-20,10]), level of the early reflection signal (wet signal)
  • AUDIO_REVERB_ROOM_SIZE = 2, ([0, 100]), room size of the reflection
  • AUDIO_REVERB_WET_DELAY = 3, (ms, [0, 200]), length of the initial latency of the wet signal in ms
  • AUDIO_REVERB_STRENGTH = 4, ([0, 100]), length of the late reverberation
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.

Get the Audio Effect Volume (getEffectsVolume)

int getEffectsVolume();

This method gets the volume of the audio effects from 0.0 to 100.0.

Set the Audio Effect Volume (setEffectsVolume)

int setEffectsVolume(int volume);

This method sets the volume of the audio effects from 0.0 to 1.0.

Name Description
volume The value ranges from 0.0 to 100.0. 100.0 is the default value.
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.

Adjust the Audio Effect Volume in Real Time (setVolumeOfEffect)

int setVolumeOfEffect(int soundId, int volume);

This method adjusts the volume of the specified sound effect in real time.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
volume The value ranges from 0.0 to 100.0. 100.0 is the default value.
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.

Play the Audio Effect (playEffect)

int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish)

This method plays the specified audio effect.

Name Description
soundId ID of the specified audio effect. Each audio effect has a unique ID [2]
filePath The absolute path of the audio effect file
loopCount

Set the number of times looping the audio effect

  • 0: Play the audio effect once
  • 1: Play the audio effect twice
  • -1: Play the audio effect in a loop indefinitely, until stopEffect or stopAllEffects is called
pitch Set whether to change the pitch of the audio effect. The range is [0.5, 2]. The default value is 1, which means no change to the pitch. The smaller the value, the lower the pitch.
pan

Spatial position of the local audio effect. The range is [-1.0, 1.0]

  • 0.0: The audio effect shows ahead
  • 1.0: The audio effect shows on the right
  • -1.0: The audio effect shows on the left
gain Volume of the audio effect. The range is [0.0, 100,0] The default value is 100.0. The smaller the value, the lower the volume of the audio effect
publish

Set whether to publish the specified audio effect to the remote stream:

  • true: The audio effect, played locally, is published to the Agora Cloud and the remote users can hear it
  • false: The audio effect, played locally, is not published to the Agora Cloud and the remote users cannot hear it
Return Value
  • 0: Method call succeeded
  • < 0: Method call failed

[2] If you preloaded the audio effect into the memory through preloadEffect, ensure that the soundID value is set to the same value as in preloadEffect

Stop Playing an Audio Effect (stopEffect)

int stopEffect(int soundId);

This method stops playing a specific audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Stop Playing all Audio Effects (stopAllEffects)

int stopAllEffects();

This method stops playing all the audio effects.

Preload an Audio Effect (preloadEffect)

int preloadEffect(int soundId, String filePath);

This method preloads a specific audio effect file (compressed audio file) to the memory.

To ensure smooth communication, pay attention to the size of the audio effect file. Agora recommends using this method to preload the audio effect before calling joinChannel.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
filePath Absolute path of the audio effect file.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Release an Audio Effect (unloadEffect)

int unloadEffect(int soundId);

This method releases a specific preloaded audio effect from the memory.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Pause an Audio Effect (pauseEffect)

int pauseEffect(int soundId);

This method pauses a specific audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Pause all Audio Effects (pauseAllEffects)

int pauseAllEffects();

This method pauses all the audio effects.

Name Description
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Resume an Audio Effect (resumeEffect)

int resumeEffect(int soundId);

This method resumes playing a specific audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Resume Playing all Audio Effects (resumeAllEffects)

int resumeAllEffects();

This method resumes playing all the audio effects.

Enable Web SDK Interoperability (enableWebSdkInteroperability)

int enableWebSdkInteroperability(bool enabled);

This method enables interoperability with the Agora Web SDK.

Name Description
enabled

Whether to enable the interoperability with the Agora Web SDK is enabled:

  • True: Enable the interoperability
  • False: Disable the interoperability
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Enable Built-in Encryption and Set the Encryption Secret (setEncryptionSecret)

virtual int setEncryptionSecret(const char* secret) = 0;

Use setEncryptionSecret to specify an encryption password to enable built-in encryption before joining a channel. All users in a channel must set the same encryption password. The encryption password is automatically cleared once a user has left the channel. If the encryption password is not specified or set to empty, the encryption function will be disabled.

Do not use this function together with CDN.

Name Description
secret Encryption Password
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Built-in Encryption Mode (setEncryptionMode)

virtual int setEncryptionMode(const char* encryptionMode) = 0;

AThe Agora Native SDK supports built-in encryption, which is in AES-128-XTS mode by default. If you want to use other modes, call this API to set the encryption mode.

All users in the same channel must use the same encryption mode and password. Refer to information related to the AES encryption algorithm on the differences between encryption modes.

Call setEncryptionSecret to enable the built-in encryption function before calling this API.

Do not use this function together with CDN

Name Description
encryptionMode

Encryption mode. The following modes are currently supported:

  • “aes-128-xts”:128-bit AES encryption, XTS mode
  • “aes-128-ecb”:128-bit AES encryption, ECB mode
  • “aes-256-xts”: 256-bit AES encryption, XTS mode
  • “”: When it is set to NUL string, the encryption is in “aes-128-xts” by default.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Create a Data Stream (createDataStream)

virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0;

This method creates a data stream. Each user can only have up to five data channels at the same time.

Set reliable and ordered both as True or both as False. Do not set one as True and the other as False.

Name Description
reliable
  • True: The recipients will receive data from the sender within 5 seconds. If the recipient does not receive the sent data within 5 seconds, the data channel will report an error to the application.
  • False: The recipients may not receive any data, and the SDK will not report any error upon data missing.
ordered
  • True: The recipients will receive data in the order of the sender.
  • False: The recipients will not receive data in the order of the sender.
Return Value
  • <0: Returns an error code when it fails to create the data stream. [4]
  • >0: Returns the Stream ID when the data stream is created.

[4] The error code is related to the positive integer displayed in Error Codes and Warning Codes, for example, if it returns -2, then it indicates 2: ERR_INVALID_ARGUMENT in Error Codes and Warning Codes.

Send a Data Stream (sendStreamMessage)

virtual int sendStreamMessage(int streamId, const char* data, size_t length) = 0;

This method sends data stream messages to all users in a channel. Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 kB. The API controls the data channel transfer rate. Each client can send up to 6 kB of data per second. Each user can have up to five data channels simultaneously.

Name Description
streamId Stream ID returned by createDataStream
data Data to be sent
Return Value

When it fails to send the message, the following error code will be returned:

ERR_SIZE_TOO_LARGE/ERR_TOO_OFTEN/ERR_BITRATE_LIMIT

Start an Audio Call Test (startEchoTest)

virtual int startEchoTest() = 0;

This method launches an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly. In the test, the user first speaks, and the recording is played back in 10 seconds. If the user can hear the recording in 10 seconds, it indicates that the audio devices and network connection work properly.

  • After calling the startEchoTest method, call stopEchoTest to end the test; otherwise, the application cannot run the next echo test, nor can it call the joinChannel method to start a new call.
  • This method is applicable only when the user role is broadcaster. If you switch the channel mode from communication to live broadcast, ensure that setClientRole is called to change the user role from audience(default in the live broadcast mode) to broadcaster before using this method.
Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
  • ERR_REFUSED (-5): Failed to launch the echo test, for example, initialization failed.

Stop an Audio Call Test (stopEchoTest)

virtual int stopEchoTest() = 0;

This method stops an audio call test.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
  • ERR_REFUSED(-5): Failed to stop the echo test. It could be that the echo test is not running.

Enable the Network Test (enableLastmileTest)

virtual int enableLastmileTest() = 0;

This method tests the quality of the user’s network connection and is disabled by default.

This method is mainly used in two scenarios:

  • Before users join a channel, this method can be called to check the uplink network quality.

  • Before the audience in a channel switch to a host role, this method can be called to check the uplink network quality.

In both scenarios, calling this method consumes extra network traffic, which affects the communication quality.

Call disableLastmileTest to disable it immediately once the users have received the onLastmileQuality callback before they join the channel or switch the user role.

For current hosts, do not call this method.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Disable the Network Test (disableLastmileTest)

virtual int disableLastmileTest() = 0;

This method disables the network connection quality test.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Retrieve the Current Call ID (getCallId)

virtual int getCallId(agora::util::AString& callId) = 0;

When a user joins a channel on a client, a CallId is generated to identify the call from the client. Some methods such as rate and complain need to be called after the call ends in order to submit feedback to the SDK. These methods require assigned values of the CallId parameters. To use these feedback methods, call the getCallId method to retrieve the CallId during the call, and then pass the value as an argument in the feedback methods after the call ends.

Name Description
callId The current call ID.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Rate the Call (rate)

virtual int rate(const char* callId, int rating, const char* description) = 0;

This method lets the user rate the call. It is usually called after the call ends.

Name Description
callId Call ID retrieved from the getCallId method.
rating The rating for the call between 1 (lowest score) to 10 (highest score).
description

A given description for the call with a length less than 800 bytes.

This parameter is optional.

Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
  • ERR_INVALID_ARGUMENT (-2): The passed argument is invalid, for example, callId invalid.
  • ERR_NOT_READY (-3): The SDK status is incorrect, for example, initialization failed.

Complain about the Call Quality (complain)

virtual int complain(const char* callId, const char* description) = 0;

This method allows the user to complain about the call quality. It is usually called after the call ends.

Name Description
callId Call ID retrieved from the getCallId method.
description

A given description of the call with a length less than 800 bytes.

This parameter is optional.

Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
  • ERR_INVALID_ARGUMENT (-2): The passed argument is invalid, for example, callId invalid.
  • ERR_NOT_READY (-3): The SDK status is incorrect, for example, initialization failed.

Renew Token (renewtoken)

virtual int renewToken(const char* token) = 0;

This method updates the Channel Key.

The key expires after a certain period of time once the Token schema is enabled. When:

  • The onError callback reports the error ERR_TOKEN_EXPIRED(109), or

  • The onRequestToken callback reports the error ERR_TOKEN_EXPIRED(109)

The application should retrieve a new key and then call this method to renew it. Failure to do so will result in the SDK disconnecting with the server.

Name Description
token Specifies the Channel Key to be renewed.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Specify a Log File (setLogFile)

int setLogFile(const char* filePath);

This method specifies an SDK output log file. The log file records all the log data of the SDK’s operation. Ensure that the directory to save the log file exists and is writable.

Name Description
filePath File path of the log file. The string of the log file is in UTF-8 code.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

The default log file location is at: C:Users<user_name>AppDataLocalAgora<process_name>.

Set the Log Filter (setLogFilter)

int setLogFilter(unsigned int filter);

This method sets the output log level of the SDK. You can use either one or a combination of the filters.

The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG. Choose a level, and you can see logs that precede that level.

For example, if you set the log level as WARNING, then you can see logs in levels CRITICAL, ERROR and WARNING.

Name Description
filter

Set the levels of the filters:

  • LOG_FILTER_OFF = 0: Output no log.
  • LOG_FILTER_DEBUG = 0x80f: Output all the API logs.
  • LOG_FILTER_INFO = 0x0f: Output logs of the CRITICAL, ERROR, WARNING and INFO level.
  • LOG_FILTER_WARNING = 0x0e: Output logs of the CRITICAL, ERROR and WARNING level.
  • LOG_FILTER_ERROR = 0x0c: Output logs of the CRITICAL and ERROR level.
  • LOG_FILTER_CRITICAL = 0x08: Output logs of the CRITICAL level.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Release the IRtcEngine Object (release)

virtual void release() = 0;

This method releases the IRtcEngine object.

Name Description
sync

Indicates whether this method is called synchronously or asynchronously.

  • True: Synchronous call. The result returns after the IRtcEngine Object resources are released. The app should not call this interface in the callback generated by the SDK, otherwise the SDK must wait for the callback to return in order to recover the associated object resources, resulting in a deadlock. The SDK automatically detects the deadlock and turns it into an asynchronous call, but the test itself takes extra time.
  • False: Asynchronous call. The result returns immediately even when the IRtcEngine object resources are not released, and the SDK will release all resources on its own. Pay attention: Do not immediately uninstall the SDK’s dynamic library after the call, otherwise it may crash because the SDK clean-up thread has not quit.
Return Value
  • <0: error code.
  • 0: method call succeed.

Get the SDK Version (getVersion)

virtual const char* getVersion(int* build) = 0;

This method returns the string of the SDK version number in char format.

Parameter Methods (RtcEngineParameters)

This is an auxiliary class that sets parameters for the SDK. The following section describes each of the methods in this class.

Mute the Local Audio Stream (muteLocalAudioStream)

int muteLocalAudioStream(bool mute);

This method mutes/unmutes local audio. It enables/disables sending local audio streams to the network.

This method does not disable the microphone, and thus does not affect the recording process, if any.

Name Description
mute
  • True: Mutes local audio.
  • False: Unmutes local audio.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute All Remote Audio Streams (muteAllRemoteAudioStreams)

int muteAllRemoteAudioStreams(bool mute);

This method enables/disables playing all remote callers’ audio streams.

When set to True, this method stops playing audio streams without affecting the audio stream receiving process.

Name Description
mute
  • True: Stops playing all the received audio streams.
  • False: Allows playing all the received audio streams.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute A Specified Remote Audio Stream (muteRemoteAudioStream)

int muteRemoteAudioStream(uid_t uid, bool mute);

This method mutes/unmutes the audio streams of a specified user. It enables or disables playing a certain user’s audio streams.

When set to True, this method stops playing audio streams without affecting the audio stream receiving process.

Name Description
uid User ID whose audio streams the user intends to mute.
mute
  • True: Stops playing a specified user’s audio streams.
  • False: Allows playing a specified user’s audio streams.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Enable the Audio Volume Indication (enableAudioVolumeIndication)

int enableAudioVolumeIndication(int interval, int smooth);

This method enables the SDK to regularly report to the application on which user is talking and the volume of the speaker. Once the method is enabled, the SDK returns the volume indications at the set time internal in the [Audio Volume Indication Callback onAudioVolumeIndication callback, regardless of whether anyone is speaking in the channel.

Name Description
interval

Time interval between two consecutive volume indications:

  • <= 0: Disables the volume indication
  • > 0: The time interval between two consecutive volume indications in milliseconds. Agora recommends setting it to more than 200 ms. Do not set it lower than 10 ms, or the onAudioVolumeIndication callback will not be triggered.
smooth Smoothing factor. The default value is 3
Return values
  • 0: Method call succeeded
  • < 0: Method call failed

Start Audio Mixing (startAudioMixing)

int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle);

This method mixes the specified local audio file with the audio stream from the microphone; or, it replaces the microphone’s audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of loop playbacks. This API also supports online music playback.

Call this API when you are in a channel, otherwise it may cause issues.

Name Description
filePath

Name and path of the local audio file to be mixed.

Supported audio formats: mp3, aac, m4a, 3gp, and wav.

loopback
  • True: Only the local user can hear the remix or the replaced audio stream.
  • False: Both users can hear the remix or the replaced audio stream.
replace
  • True: the content of the local audio file replaces the audio stream from the microphone.
  • False: Local audio file mixed with the audio stream from the microphone.
cycle

Number of loop playbacks:

  • Positive integer: Number of loop playbacks.
  • -1: Infinite loop.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Stop Audio Mixing (stopAudioMixing)

int stopAudioMixing();

This method stops the audio mixing. Call this API when you are in a channel.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Pause Audio Mixing (pauseAudioMixing)

int pauseAudioMixing();

This method pauses audio mixing. Call this API when you are in a channel.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Resume Audio Mixing (resumeAudioMixing)

int resumeAudioMixing();

This method resumes audio mixing. Call this API when you are in a channel.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Adjust the Audio Mixing Volume (adjustAudioMixingVolume)

int adjustAudioMixingVolume(int volume);

This method adjusts the volume during audio mixing. Call this API when you are in a channel.

Name Description
volume Volume ranging from 0 to 100. By default, 100 is the original volume.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Get the Audio Mixing Duration (getAudioMixingDuration)

int getAudioMixingDuration();

This method gets the duration (ms) of audio mixing. Call this API when you are in a channel.

Get the Current Audio Position (getAudioMixingCurrentPosition)

int getAudioMixingCurrentPosition();

This method gets the playback position (ms) of the audio. Call this API when you are in a channel.

Drag the Audio Progress Bar (setAudioMixingPosition)

int setAudioMixingPosition(int pos /*in ms*/);

This method drags the playback progress bar of the audio mixing file to where you want to play instead of playing it from the beginning.

Name Description
pos Integer. The position of the audio mixing file (ms).

Start an Audio Recording (startAudioRecording)

int startAudioRecording(const char* filePath, AUDIO_RECORDING_QUALITY_TYPE quality);

This method starts an audio recording. The SDK allows recording during a call, which supports either one of the following two formats:

  • .wav: Large file size with high sound fidelity OR

  • .aac: Small file size with low sound fidelity

Ensure that the directory to save the recording file exists and is writable. This method is usually called after the joinChannel method. The recording automatically stops when the leaveChannel method is called.

Name Description
filePath Full file path of the recording file. The string of the file name is in UTF-8 code.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Stop an Audio Recording (stopAudioRecording)

int stopAudioRecording();

This method stops recording on the client.

Call this method before calling leaveChannel; otherwise the recording automatically stops when the leaveChannel method is called.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Adjust the Recording Volume (adjustRecordingSignalVolume)

int adjustRecordingSignalVolume(int volume);

This method adjusts the recording volume.

Name Description
volume

Recording volume, ranges from 0 to 400:

  • 0: Mute
  • 100: Original volume
  • 400: (Maximum) Four times the original volume with signal clipping protection
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Adjust the Playback Volume (adjustPlaybackSignalVolume)

int adjustPlaybackSignalVolume(int volume);

This method adjusts the playback volume.

Name Description
volume

Playback volume, ranges from 0 to 400:

  • 0: Mute
  • 100: Original volume
  • 400: (Maximum) Four times the original volume with signal clipping protection
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Audio Device Management Methods (IAudioDeviceManager)

The agora::IAudioDeviceManager interface class tests the interfaces of the audio devices. Instantiate an AAudioDeviceManager class to get an IAudioDeviceManager interface.

Enumerate Playback Devices (enumeratePlaybackDevices)

virtual IAudioDeviceCollection* enumeratePlaybackDevices() = 0;

This method returns an IAudioDeviceCollection object that includes all the playback devices in the system. With the IAudioDeviceCollection object, the application can enumerate the playback devices. The application must call the IAudioDeviceCollection::release() method to release the returned object after using it.

Name Description
Return Value

It returns an IAudioDeviceCollection object that includes all the playback devices in the system when the method call succeeds.

It returns NULL when the method call fails.

Enumerate Recording Devices (enumerateRecordingDevices)

virtual IAudioDeviceCollection* enumerateRecordingDevices() = 0;

This method returns an IAudioDeviceCollection object that includes all the recording devices in the system. With the IAudioDeviceCollection object, the application can enumerate the recording devices. The application needs to call the IAudioDeviceCollection::release() method to release the returned object after using it.

Name Description
Return Value

When successful, it returns an IAudioDeviceCollection object that includes all the recording devices in the system when the call succeeds.

It returns NULL when the call fails.

Specify a Playback Device with the Device ID (setPlaybackDevice)

virtual int setPlaybackDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

This method uses the device ID to specify a playback device.

Name Description
deviceId Device ID of the playback device. It can be retrieved by the enumeratePlaybackDevices() method. Plugging or unplugging the device does not change the device ID.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Specify a Recording Device with the Device ID (setRecordingDevice)

virtual int setRecordingDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

This method uses the device ID to specify a recording device.

Name Description
deviceId Device ID of the recording device. It can be retrieved by the enumerateRecordingDevices() method. Plugging or unplugging the device does not change the device ID.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Playback Device Volume (setPlaybackDeviceVolume)

virtual int setPlaybackDeviceVolume(int volume) = 0;
Name Description
volume Volume of the playing device, ranging from 0 to 255
Return value
  • 0: Method call succeeded
  • < 0: Method call failed

Get the Playback Device Volume (getPlaybackDeviceVolume)

virtual int getPlaybackDeviceVolume(int *volume) = 0;
Name Description
volume Volume of the playing device, ranging from 0 to 255
Return value
  • 0: Method call succeeded
  • < 0: Method call failed

Set the Recording Device Volume (setRecordingDeviceVolume)

virtual int setRecordingDeviceVolume(int volume) = 0;
Name Description
volume Volume of the microphone, ranging from 0 to 255
Return value
  • 0: Method call succeeded
  • < 0: Method call failed

Get the Recording Device Volume (getRecordingDeviceVolume)

virtual int getRecordingDeviceVolume(int *volume) = 0;
Name Description
volume Volume of the microphone, ranging from 0 to 255
Return value
  • 0: Method call succeeded
  • < 0: Method call failed

Mute the Playback Device (setPlaybackDeviceMute)

virtual int setPlaybackDeviceMute(bool mute) = 0;
Name Description
mute
Mute the playback device:
  • True: Mute
  • False: Unmute
Return value
  • 0: Method call succeeded
  • < 0: Method call failed

Check Whether the Playback Device is Muted (getPlaybackDeviceMute)

virtual int getPlaybackDeviceMute(bool *mute) = 0;
Name Description
mute
Checks whether the playback device is muted:
  • True: Muted
  • False: Unmuted

Mute the Recording Device (setRecordingDeviceMute)

virtual int setRecordingDeviceMute(bool mute) = 0;
Name Description
mute
Mute the recording device:
  • True: Mute
  • False: Unmute
Return value
  • 0: Method call succeeded
  • < 0: Method call failed

Check Whether the Recording Device is Mute (getRecordingDeviceMute)

virtual int getRecordingDeviceMute(bool *mute) = 0;
Name Description
mute
Check whether the recording device is muted:
  • True: Muted
  • False: Unmuted

Enable Loopback Recording (enableLoopbackRecording)

int enableLoopbackRecording(bool enabled);

This method enables loopback recording. Once enabled, the SDK collects all local sounds.

Name Description
enabled Enable loopback recording
Return value
  • 0: Method call succeeded
  • < 0: Method call failed

Start the Playback Device Test (startPlaybackDeviceTest)

virtual int startPlaybackDeviceTest(const char* testAudioFilePath) = 0;

This method checks whether the playback device works properly. The SDK plays an audio file specified by the user. If the user can hear the sound, then the playback device works properly.

Name Description
testAudioFilePath

File path of the audio file for the test, which is in UTF-8 absolute path:

  • File formats: wav, mp3, m4a, and aac
  • File sampling rates: 8000, 16000, 32000, 44100, and 48000
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Stop the Playback Device Test (stopPlaybackDeviceTest)

virtual int stopPlaybackDeviceTest() = 0;

This method stops a playback device test. To stop the test, call this method after calling the startPlaybackDeviceTest() method.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Start the Microphone Test (startRecordingDeviceTest)

virtual int startRecordingDeviceTest(int indicationInterval) = 0;

This method checks whether the microphone works properly. Once the test starts, the SDK uses the onAudioVolumeIndication callback to notify the application about the volume information.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Stop the Microphone Test (stopRecordingDeviceTest)

virtual int stopRecordingDeviceTest() = 0;

This method stops the microphone test. To stop the test, call this method after calling the startRecordingDeviceTest() method.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Audio Device Collection Methods (IAudioDeviceCollection)

The agora::IAudioDeviceCollection interface class retrieves device-related information.

Retrieve the Total Number of Playback or Recording Devices (getCount)

virtual int getCount() = 0;

First call enumeratePlaybackDevices(), then call this method to return the number of audio playback devices. First call enumerateRecordingDevices(), then call this method to return the number of audio recording devices.

Name Description
Return Value The number of audio devices.

Retrieve the Indexed Device Information (getDevice)

virtual int getDevice(int index, char deviceName[MAX_DEVICE_ID_LENGTH], char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

This method retrieves information about an audio device.

Name Description
index An input parameter to specify the device information to be retrieved.
deviceName An output parameter that indicates the device name.
deviceId An output parameter that indicates the device ID.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Specify a Device with the Device ID (setDevice)

virtual int setDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

This method (recommended) uses the device ID to specify a video-capture device.

Name Description
deviceId Device ID.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Application Volume (setApplicationVolume)

virtual int setApplicationVolume(int volume) = 0;

This method sets the volume of the Application.

Name Description
volume The volume value, which ranges from 0-255
Return value
  • 0: Method call succeeded
  • 1: Method call failed

Get the Application Volume (getApplicationVolume)

virtual int getApplicationVolume(int& volume) = 0;

This method gets the volume of the Application.

Name Description
volume The volume value, which ranges from 0-255
Return value
  • 0: Method call succeeded
  • 1: Method call failed

Set the Application Mute (setApplicationMute)

virtual int setApplicationMute(bool mute) = 0;

This method sets the Application mute.

Name Description
mute

Whether to mute the Application

  • True: Mute the Application
  • False: Unmute the Application
Return value
  • 0: Method call succeeded
  • 1: Method call failed

Get the Mute State of the Application (isApplicationMute)

virtual int isApplicationMute(bool& mute) = 0;

This method gets the mute state of the Application.

Name Description
mute

The mute state of the current Application

  • True: The application is mute
  • False: The application is not mute
Return value
  • 0: Method call succeeded
  • < 0: Method call failed

Callback Methods (IRtcEngineEventHandler)

The SDK uses the agora::IRtcEngineEventHandler interface class to send callback event notifications to the application, and the application inherits the methods of this interface class to retrieve these event notifications. All methods in this interface class have their (empty) default implementations, and the application can inherit only some of the required events instead of all of them. In the callback methods, the application should avoid time-consuming tasks or calling blocking APIs, for example, SendMessage, otherwise the SDK may not work properly.

Join a Channel Callback (onJoinChannelSuccess)

virtual void onJoinChannelSuccess (const char* channel, uid_t uid, int elapsed);

This callback indicates that the user has successfully joined the specified channel.

Name Description
channel The channel name.
uid

User ID.

If the uid is specified in the joinChannel method, it returns the specified ID; if not, it returns an ID that is automatically assigned by the Agora server.

elapsed Time elapsed (ms) from calling joinChannel until this event occurs.

Rejoin Channel Callback (onRejoinChannelSuccess)

virtual void onRejoinChannelSuccess(const char* channel, uid_t uid, int elapsed);

When the client loses connection with the server because of network problems, the SDK automatically attempts to reconnect, and then triggers this callback method upon reconnection.

Name Description
channel The channel name.
uid User ID.
elapsed Time elapsed (ms) from calling joinChannel until this event occurs.

Warning Occurred Callback (onWarning)

virtual void onWarning(int warn, const char* msg);

This callback method indicates that some warning occurred during SDK runtime. In most cases the application can ignore the warnings reported by the SDK, because the SDK can usually fix the issue and resume running. For instance, the SDK may report an ERR_OPEN_CHANNEL_TIMEOUT warning upon disconnection with the server and attempts to reconnect.

Name Description
warn The warning code.
msg The warning message.

Error Occurred Callback (onError)

virtual void onError(int err, const char* msg);

This callback indicates that a network or media error occurred during SDK runtime. In most cases, reporting an error means that the SDK cannot fix the issue and resume running, and therefore requires actions from the application or simply informs the user on the issue. For instance, the SDK reports an ERR_START_CALL error when failing to initialize a call. In this case, the application informs the user that the call initialization failed and calls the leaveChannel method to exit the channel.

Name Description
err

Error code:

  • ERR_INVALID_VENDOR_KEY(101): Invalid App ID.
  • ERR_INVALID_CHANNEL_NAME(102): Invalid channel name.
  • ERR_LOOKUP_CHANNEL_REJECTED(105): Failed to look up the channel, because the server rejected the request.
  • ERR_OPEN_CHANNEL_REJECTED(107): Failed to join the channel, because the media server rejected the request.
  • ERR_LOAD_MEDIA_ENGINE(1001): Failed to load the media engine.
  • ERR_START_CALL(1002): Failed to turn on the local audio or video devices and thus failed to start a call.
  • ERR_START_CAMERA(1003): Failed to turn on the local camera.
msg The error message.

API Call Executed Callback (onApiCallExecuted)

virtual void onApiCallExecuted(int err, const char* api, const char* result);

This callback is triggered when the API has been executed.

Name Description
error The error code that the SDK returns when the method call fails. If the SDK returns o, then the method has been called successfully.
api The API that the SDK executes
result The result of calling the API

The State of the Microphone Has Changed Callback (onMicrophoneEnabled)

virtual void onMicrophoneEnabled(bool enabled)
Name Description
enabled
  • true: The microphone is enabled.
  • false: The microphone is disabled.

Audio Quality Callback (onAudioQuality)

virtual void onAudioQuality(uid_t uid, int quality, unsigned short delay, unsigned short lost);

During a call, this callback is triggered once every two seconds to report on the audio quality of the call.

Name Description
uid User ID of the speaker
quality

Rating of the audio quality:

  • QUALITY_UNKNOWN(0): The network quality is unknown.
  • QUALITY_EXCELLENT(1): The network quality is excellent.
  • QUALITY_GOOD(2): The network quality is quite good, but the bitrate may be slightly lower than excellent.
  • QUALITY_POOR(3): Users can feel the communication slightly impaired.
  • QUALITY_BAD(4): Users can communicate only not very smoothly.
  • QUALITY_VBAD(5): The network is so bad that users can hardly communicate.
  • QUALITY_DOWN(6): Users cannot communicate at all.
delay Time delay in milliseconds.
lost The packet loss rate(%).

Audio Volume Indication Callback (onAudioVolumeIndication)

virtual void onAudioVolumeIndication (const AudioVolumeInfo* speakers, unsigned int speakerNumber, int totalVolume);

This callback indicates who is talking and the speaker’s volume. By default the indication is disabled. If needed, use the enableAudioVolumeIndication() method to configure it.

Name Description
speakers

The speakers (array). Each speaker ():

  • uid: User ID of the speaker. The uid of the local user is 0.
  • volume: The volume of the speaker between 0 (lowest volume) to 255 (highest volume).
speakerNumber Total number of speakers.
totalVolume Total volume after audio mixing between 0 (lowest volume) to 255 (highest volume).

In the returned speakers array:

  • If the uid is 0, that is, the local user is the speaker, the returned volume is the same as totalVolumn.

  • If the uid is not 0 and the volume is 0, it indicates that the user specified by the uid did not speak.

  • If a uid is contained in the previous speakers array but not in the present one, it indicates that the user specified by the uid did not speak.

Leave Channel Callback (onLeaveChannel)

virtual void onLeaveChannel(const RtcStats& stat);

When the application calls the leaveChannel() method, the SDK uses this callback to notify the application that the user has successfully left the channel. With this callback function, the application retrieves information such as the call duration and the statistics of data received/transmitted by the SDK.

Definition of RtcStats

struct RtcStats
{
    unsigned int duration;
    unsigned int txBytes;
    unsigned int rxBytes;
    unsigned short txKBitRate;
    unsigned short rxKBitRate;

    unsigned short rxAudioKBitRate;
    unsigned short txAudioKBitRate;

    unsigned short rxVideoKBitRate;
    unsigned short txVideoKBitRate;
    unsigned int userCount;
    double cpuAppUsage;
    double cpuTotalUsage;
};
Name Description
stats

Statistics about the call:

  • duration: Call duration in seconds, represented by an aggregate value.
  • txBytes: Total number of bytes transmitted, represented by an aggregate value.
  • rxBytes: Total number of bytes received, represented by an aggregate value.
  • txKBitRate: Transmission bitrate in kbps, represented by an instantaneous value.
  • rxKBitRate: Receive bitrate in kbps, represented by an instantaneous value.
  • txAudioKBitrate: Audio transmission bitrate in kbps, represented by an instantaneous value.
  • rxAudioKBitRate: Audio receive bitrate in kbps, represented by an instantaneous value.
  • txVideoKBitRate: Video transmission bitrate in kbps, represented by an instantaneous value.
  • rxVideoKBitRate: Video receive bitrate in kbps, represented by an instantaneous value.
  • users: The instant number of users in the channel when the user leaves the channel.
  • puTotalUsage: System CPU usage (%).
  • cpuAppUsage: Application CPU usage (%).

Other User Joined Channel Callback (onUserJoined)

virtual void onUserJoined(uid_t uid, int elapsed);

This callback method notifies the application the broadcaster has joined the channel. If the broadcaster is already in the channel when the application joins the channel, the SDK also reports to the application on the broadcaster that is already in the channel.

In the live broadcast scenario:

  • The broadcaster can receive the callback when another broadcaster joins the channel.
  • All the audience in the channel can receive the callback when the new broadcaster joins the channel.
  • When a web application joins the channel, this callback is triggered as long as the web application publishes streams.
Name Description
uid User ID.
elapsed Time delay (ms) from calling joinChannel until this callback is triggered.

Other User Offline Callback (onUserOffline)

virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason);

This callback notifies the application that the broadcaster has left the channel or gone offline.

The SDK reads the timeout data to determine if a user has left the channel (or has gone offline). If no data package is received from the user in 15 seconds, the SDK assumes the user is offline. A poor network connection may lead to false detections; therefore, use signaling for reliable offline detection.

Name Description
uid User ID.
reason

This callback is triggered when:

  • USER_OFFLINE_QUIT(0): User has quit the call.
  • USER_OFFLINE_DROPPED(1): The SDK timed out and the user dropped offline because it has not received a data package within a certain period of time. If a user quits the call and the message is not passed to the SDK (due to an unreliable channel), the SDK assumes the event has timed out.

Call Session Statistics Callback (onRtcStats)

virtual void onRtcStats(const RtcStats& stats);

The SDK updates the application on the statistics of the call session once every two seconds.

Name Description
stat See descriptions in Leave Channel Callback (onLeaveChannel) .

First Remote Audio Frame Received Callback (onFirstRemoteAudioFrame)

virtual void onFirstRemoteAudioFrame(uid_t uid, int elapsed)

This callback method is triggered when the first remote audio frame is received.

Name Description
uid The UID of the remote user whose audio frame is received.
elapsed Time elapsed (ms) from calling joinChannel until this callback is triggered.

Audio Device State Changed Callback (onAudioDeviceStateChanged)

virtual void onAudioDeviceStateChanged(const char* deviceId, int deviceType, int deviceState);

This callback notifies the application that the system’s audio device state has been changed, for example, a headset is unplugged from the device.

Name Description
deviceId The device ID.
deviceType

The device type defined as follows:

  • UNKNOWN_DEVICE(-1): The device type is unknown.
  • AUDIO_PLAYOUT_DEVICE(0): The device is a playout device.
  • AUDIO_RECORDING_DEVICE(1): The device is a recording device.
deviceState

The device state defined as follows:

  • DEVICE_STATE_ACTIVE(1): The device is active.
  • DEVICE_STATE_DISABLED(2): The device is disabled.
  • DEVICE_STATE_NOT_PRESENT(4): The device is not present.
  • DEVICE_STATE_UNPLUGGED(8): The device is unplugged.

Network Quality Callback (onLastmileQuality)

virtual void onLastmileQuality(int quality);

This callback reports on the network quality. It is triggered once every two seconds after enableLastmileTest() is called. When not in a call and the network test is enabled (by calling enableLastmileTest), this callback function is triggered irregularly to update the application on the network connection quality of the local user.

Name Description
quality

Quality of the last mile network:

  • QUALITY_UNKNOWN(0): The network quality is unknown.
  • QUALITY_EXCELLENT(1): The network quality is excellent.
  • QUALITY_GOOD(2): The network quality is quite good, but the bitrate may be slightly lower than excellent.
  • QUALITY_POOR(3): Users can feel the communication slightly impaired.
  • QUALITY_BAD(4): Users can communicate only not very smoothly.
  • QUALITY_VBAD(5): The network is so bad that users can hardly communicate.
  • QUALITY_DOWN(6): Users cannot communicate at all.

Channel Network Quality Callback (onNetworkQuality)

virtual void onNetworkQuality(uid_t uid, int txQuality, int rxQuality);

This callback is triggered every 2 seconds to update the application on the network quality of each user in a communication or live broadcast channel.

Name Description
uid User ID. The network quality of the user with this UID will be reported. If uid is 0, it reports the local network quality.
txQuality

The transmission quality of the user:

  • QUALITY_UNKNOWN(0): The network quality is unknown.
  • QUALITY_EXCELLENT(1): The network quality is excellent.
  • QUALITY_GOOD(2): The network quality is quite good, but the bitrate may be slightly lower than excellent.
  • QUALITY_POOR(3): Users can feel the communication slightly impaired.
  • QUALITY_BAD(4): Users can communicate only not very smoothly.
  • QUALITY_VBAD(5): The network is so bad that users can hardly communicate.
  • QUALITY_DOWN(6): Users cannot communicate at all.
rxQuality

The receiving quality of the user:

  • QUALITY_UNKNOWN(0): The network quality is unknown.
  • QUALITY_EXCELLENT(1): The network quality is excellent.
  • QUALITY_GOOD(2): The network quality is quite good, but the bitrate may be slightly lower than excellent.
  • QUALITY_POOR(3): Users can feel the communication slightly impaired.
  • QUALITY_BAD(4): Users can communicate only not very smoothly.
  • QUALITY_VBAD(5): The network is so bad that users can hardly communicate.
  • QUALITY_DOWN(6): Users cannot communicate at all.

Other User Muted Audio Callback (onUserMuteAudio)

virtual void onUserMuteAudio(uid_t uid, bool muted);

This callback indicates that some other user has muted/unmuted his/her audio streams.

Currently, this callback returns invalid when the number of broadcasters in a channel exceeds 20, which will be improved later.

Name Description
uid User ID.
muted
  • True: User has muted his/her audio.
  • False: User has unmuted his/her audio.

Connection Interrupted Callback (onConnectionInterrupted)

virtual void onConnectionInterrupted();

This method indicates that the SDK has lost connection with the server.

This method is triggered upon connection lost, while the onConnectionLost method is triggered when the SDK attempts to reconnect after losing connection. Once the connection is lost, and if the application does not call leaveChannel, the SDK automatically tries to reconnect repeatedly.

Connection Lost Callback (onConnectionLost)

virtual void onConnectionLost();

This callback indicates that the SDK has lost connection with the network, and it has remained unconnected for a period of time (10 seconds by default) despite that it attempts to reconnect. It is also triggered when the SDK fails to join the channel 10 seconds after it calls joinChannel. The SDK will keep trying to reconnect after this callback is triggered. Upon reconnection, an onRejoinChannelSuccess callback will then be triggered.

Connection Banned Callback (onConnectionBanned)

virtual void onConnectionBanned();

This callback is triggered when your connection is banned by the Agora Server.

Video-stream Type Switched (onApiCallExecuted)

virtual void onApiCallExecuted(const char* api, int error);

This callback indicates whether the video-stream type is switched or not.

API API String Parameter Status Code
setRemotVideoStream rtc.video.set_remote_video_stream See the Error Code.

Data Stream Received Callback (onStreamMessage)

virtual void onStreamMessage(uid_t uid, int streamID, const char* data, size_t length);

This callback indicates the local user has received the data stream from the other user within five seconds.

Name Description
uid User ID
data Data received by the recipients.
length Length of the data

Data Stream Sent Failure Callback (onStreamMessageError)

virtual void onStreamMessageError(uid_t uid, int streamId, int code, int missed, int cached);

This callback indicates that the local user has not received the data stream from the other user within five seconds.

Name Description
uid User ID
streamId Stream ID
code
  • ERR_OK = 0, No error
  • ERR_NOT_IN_CHANNEL=113, the user is not in a channel
  • ERR_BITRATE_LIMIT=115, limited bitrate

For more error code descriptions, see Error Codes and Warning Codes

missed The number of lost messages
cached The number of incoming cached messages when the data stream is interrupted

Token Expired Callback (onRequestToken)

virtual void onRequestToken();

When a Channel Key is specified by calling joinChannel(), if the SDK lost connection with the Agora server due to network issues, the Channel Key may expire after a certain period of time and a new Channel Key may be required to reconnect to the server.

This callback notifies the application of generating a new Token, and calling renew token to specify the newly generated Channel Key.

This function was previously provided in the callback report of onError(): ERR_TOEKN_EXPIRED(109), ERR_INVALID_TOKEN(110). Starting from v1.7.3, the old method is still working, but it is recommended for you to put the related logic in this callback.

Audio Mixing File Playback Finished Callback (onAudioMixingFinished)

virtual void onAudioMixingFinished();

This callback is triggered when the audio mixing file playback is finished after calling startAudioMixing. If you failed to execute the startAudioMixing method, it returns the error code in the onError callback.

Local Audio Effect Playback Finished Callback (onAudioEffectFinished)

virtual void onAudioEffectFinished(int soundId)

This callback is triggered when the local audio effect playback is finished.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.

Active Speaker Detected Callback (onActiveSpeaker)

virtual void onActiveSpeaker(uid_t uid);

If you have used the enableAudioVolumeIndication API, this callback is triggered then the volume detecting unit has detected active speaker in the channel. Also returns with the uid of the active speaker.

Name Description
uid The UID of the active speaker. By default, 0 means the local user. If needed, you can also add relative functions on your App, for example, the active speaker, once detected, will have his/her head portrait zoomed in.
  • You need to call enableAudioVolumeIndication to receive this callback.
  • The active speaker means the uid of the speaker who speaks at the highest volume during a certain period of time.

User Role Changed Callback (onClientRoleChanged)

virtual void onClientRoleChanged(CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole);

This callback is triggered when the user role is switched, for example, from a host to an audience or vice versa.

Name Description
oldRole Role that you switched from.
newRole Role that you switched to.

Audio Device Volume Changed Callback (onAudioDeviceVolumeChanged)

virtual void onAudioDeviceVolumeChanged(MEDIA_DEVICE_TYPE deviceType, int volume, bool muted);

This callback is triggered when the volume of the playback, microphone, or application is changed.

Name Description
deviceType Device type:
deviceType
  • AUDIO_PLAYOUT_DEVICE: Playback device
deviceType
  • AUDIO_RECORDING_DEVICE: Recording device, microphone
deviceType
  • AUDIO_APPLICATION_PLAYOUT_DEVICE: Application
volume Volume, ranging from 0 to 255
muted Whether the device is muted: True/False

Error Codes

See Error Codes and Warning Codes.