Interactive Gaming API

Interactive Gaming API

This document is provided for the Java language with the following classes:

RtcEngineForGaming Inteface Class

Create RtcEngine Object (create)

public static RtcEngine create(Context context,
                               String appId,
                               IRtcEngineEventHandlerForGamingForGaming handler);

This method creates an RtcEngine object.

Currently the Agora Native SDK only supports one RtcEngine instance at a time, therefore the application should create one RtcEngine object only. Unless otherwise specified, all called methods provided by RtcEngine class are executed asynchronously. We recommend calling the interface methods in the same thread. Unless otherwise specified, the following applies to all the APIs whose return values are int type: a return value of 0 indicates that the call is successful, and a return value less than 0 indicates that the call fails.

Name Description
context The context of Android Activity.
appId App ID, see Get an App ID for details
handler IRtcEngineEventHandlerForGaming is an abstract class that provides default implementations. The SDK uses this class to report to the application on SDK runtime events.
Return Value An RtcEngine object.

Set Channel Profile (setChannelProfile)

public int setChannelProfile (int profile);

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

Note

  • You can only use one profile at the same time in the same channel.
  • This method must be called and configured before user joining a channel, because the channel profile cannot be configured when the channel is in use.
Name Description
profile

The channel profile. Choose from the following:

  • CHANNEL_PROFILE_GAME_FREE_MODE = 2: Free Mode
  • CHANNEL_PROFILE_GAME_COMMAND_MODE = 3; Command Mode
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set User Role (setClientRole)

public int setClientRole (int role, String permissionkey);

This method allows you to set the user role before joining a channel or switch the user role after joining a channel.

Note

This method is only applicable when you set the channel profile as command mode when calling setChannelProfile.

Name Description
role

The user role in a command-mode channel:

  • CLIENT_ROLE_BROADCASTER = 1; Host
  • CLIENT_ROLE_AUDIENCE = 2; Audience(default)

Once set, only the host in the channel can speak, while the audiences only obey orders.

permissionKey Set it as NULL
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Join Channel(joinChannel)

public synchronized int joinChannel(String channelName, String info, int uid);

This method lets the user join a channel. If a channel is not created, this method creates a channel automatically.

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.

Note

The UID must not be the same as that of the other users in the same channel, otherwise it forces the services to be stopped for the other users with the same UID in the channel.

Name Description
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) Additional info about the channel. Other users in the channel won’t receive this information.
uid

(Optional) The user ID: a 32-bit unsigned integer ranges from 1 to (2^32-1). It must be unique. If not assigned (or set to 0), the SDK will allocate one and returns it in onJoinChannelSuccess callback. The App needs to record and maintain the returned value as the SDK does not maintain it.

The UID is represented as a 32-bit unsigned integer in the SDK. Since unsigned integer is not supported by Java, UID is handled as 32-bit signed integer and larger numbers are interpreted as negative numbers in Java. If necessary the UID can be converted to a 64-bit integer via “uid&0xffffffffL”.

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

Join Channel With Key (joinChannel)

public synchronized int joinChannel(String channelKey, String channelName, String info, int uid);

This method provides the same function as the above method Join Channel(joinChannel) , and the only difference is that it requires a Channel Key. In most cases, the method Join Channel(joinChannel) should suffice, for users who have a high security requirement, use this method with a Channel Key.

Name Description
channelKey For how to get a channel key, refer to Security Keys.
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) Additional info about the channel. Other users in the channel won’t receive this information.
uid (Optional) The user ID: a 32-bit unsigned integer ranges from 1 to (2^32-1). It must be unique. If not assigned (or set to 0), the SDK will allocate one and returns it in onJoinChannelSuccess callback. The App needs to record and maintain the returned value as the SDK does not maintain it.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Renew Channel Key(renewChannelKey)

public override int renewChannelKey (string channelKey);

The Channel Key expires after a certain period of time once the Channel Key schema is enabled. When the onRequestChannelKey callback is triggered, call this method to retrieve a new key and then call this method to renew it. Failure to do so will result in SDK disconnecting with the server.

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

Leave Channel(leaveChannel)

public int leaveChannel();

This method lets the user leave a channel, that is, 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. Calling the leaveChannel method even when not in a call is harmless. The leaveChannel method releases all recourses related to the call. The leaveChannel() method is called asynchronously, and the user actually does not exit the channel when the call returns. Once the user exits the channel, the SDK triggers onLeaveChannel callback.

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

Disable Audio Mode(enableAudio)

public int enableAudio();

This method enables audio mode.

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

Disable Audio Mode(disableAudio)

public int disableAudio();

This method disables audio mode.

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

Specify Log File (setLogFile)

public int setLogFile (String filePath);

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

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

Set Log Filter (setLogFilter)

public int setLogFilter (int filter);

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

Name Description
filter

It sets the levels of the filters.

  • LOG_FILTER_OFF = 0;
  • LOG_FILTER_DEBUG = 0x80f;
  • LOG_FILTER_INFO = 0x0f;
  • LOG_FILTER_WARNING = 0x0e;
  • LOG_FILTER_ERROR = 0x0c;
  • LOG_FILTER_CRITICAL = 0x08;
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set Default Audio Route(setDefaultAudioRouteToSpeakerphone)

public int setDefaultAudioRouteToSpeakerphone(boolean defaultToSpeaker);

This method modifies the default audio route (speakerphone) if necessary.

Name Description
defaultToSpeaker
  • True: the default audio route is changed to the speakerphone
  • False: the default audio route is changed to the earpiece

No matter whether the audio is routed to speakerphone or earpiece, once a headset is plugged in or bluetooth is connected,

the audio route will be changed. The audio is switched back to the default audio route once plugging the headset out or the bluetooth is no longer connected.

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

Check Whether Speakerphone is Enabled(isSpeakerphoneEnabled)

public boolean isSpeakerphoneEnabled();

This method checks whether the speakerphone is enabled.

Name Description
isSpeakerphoneEnabled
  • True: the speakerphone is enabled.
  • False: the speakerphone is disabled.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set Speakerphone Volume(setSpeakerphoneVolume)

public int setSpeakerphoneVolume(int volume);
Name Description
volume It sets the speakerphone volume between 0 (lowest volume) to 255 (highest volume).
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Enable Audio Volume Indication(enableAudioVolumeIndication)

public int enableAudioVolumeIndication (int interval, int smooth);

This method enables the SDK to regularly report to the application on which user is speaking and the volume of the speaker.

Name Description
interval

Specifies the time interval between two consecutive volume indications.

  • <=0 : Disables volume indication.
  • >0: The volume indication interval in milliseconds. It is recommended to set it to a minimum of 200ms.
smooth The smoothing factor. The recommended default value is 3.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute Local Audio Stream(muteLocalAudioStream)

public int muteLocalAudioStream (boolean muted);

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

Note

When set to True, this method does not disable the microphone and thus does not affect any ongoing recording.

Name Description
muted
  • True: Stops sending local audio streams to the network.
  • False: Allows sending local audio streams to the network.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute All Remote Audio Streams (muteAllRemoteAudioStreams)

public int muteAllRemoteAudioStreams (boolean mute);

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

Name Description
muted
  • 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 Certain Remote Audio Stream (muteRemoteAudioStream)

public int muteRemoteAudioStream (int uid, boolean mute);

This method mutes/unmutes a specified remote user’s audio stream.

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 Recording (startAudioRecording)

public int startAudioRecording( String filePath, int quality );

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

  • .wav : relatively large file size with high sound fidelity OR
  • .aac : relatively 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 joinChannel() method. The recording automatically stops when the leaveChannel() method is called.

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

The recording audio quality:

  • AUDIO_RECORDING_QUALITY_LOW = 0: low quality, and the file size is around 1.2 M after 10 minutes recording
  • AUDIO_RECORDING_QUALITY_MEDIUM = 1: medium quality, and the file size is around 2 M after 10 minutes recording
  • AUDIO_RECORDING_QUALITY_HIGH = 2: high quality, and the file size is around 3.75 M after 10 minutes recording
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Stop Audio Recording (stopAudioRecording)

public int stopAudioRecording();

This method stops recording on the client machine. 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.

Start Audio Mixing (startAudioMixing)

public int startAudioMixing (String filePath,
                             boolean loopback,
                             boolean replace,
                             int cycle
                             int playTime);

This method mixes the specified local audio file with the audio stream that the microphone collects; or, it replaces the microphone audio stream with the specified local audio file. You can decide whether the other user can hear the local audio playback and specify the number of loop playbacks.

Note

  • If you want to use this API, then ensure that Android device is >=4.2, and API Level>=16.
  • Call this API when you are in the channel, otherwise it will probably cause issues.
Name Description
filePath

Specify the name and path of the local audio file to be mixed:

  • If the path begins with /assets/ , find the audio file in the /assets/ directory.
  • Otherwise, find the audio file in the absolute path.

The following lists the supported audio formats: mp3, aac, m4a, 3gp, wav, flac

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 collected by the microphone.
  • False: Mix the content of the local audio file with the audio stream collected by the microphone.
cycle

Specify the number of loop playbacks:

  • Positive integer: the number of loop playbacks
  • -1: infinite loop
playTime

It specifies the start time(ms) of the audio file to play

0 means starting from the very beginning.

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

Stop Audio Mixing (stopAudioMixing)

public int stopAudioMixing();

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

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

Pause Audio Mixing (pauseAudioMixing)

public int pauseAudioMixing();

This method pauses mixing the specified local audio with the microphone input. Call this API when you are in the channel.

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

Resume Audio Mixing (resumeAudioMixing)

public int resumeAudioMixing();

This method resumes mixing the specified local audio with the microphone input. Call this API when you are in the channel.

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

Adjust Audio Mixing Volume (adjustAudioMixingVolume)

public int adjustAudioMixingVolume(int volume);

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

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

Get the Audio Mixing Duration(getAudioMixingDuration)

public int getAudioMixingDuration();

This method gets the duration(in milliseconds) of the music. Call this API when you are in the channel.

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

Get Music Current Position(getAudioMixingCurrentPosition)

public int getAudioMixingCurrentPosition();

This method gets the duration(in milliseconds) of the music that has been played. Call this API when you are in the channel.

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

Adjust Recording Signaling Volume (adjustRecordingSignalVolume)

public int adjustRecordingSignalVolume(int volume);

This method adjusts the recording signal volume.

Name Description
volume

The recording signal volume ranges from 0~400:

  • 0: Mute
  • 100: Original volume
  • 400: 4 times of the original volume in maximum with heap overflow protection
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Adjust Playback Signal Volume(adjustPlaybackSignalVolume)

public int adjustPlaybackSignalVolume(int volume);

This method adjusts the playback Signal Volume.

Name Description
volume

The recording signal volume ranges from 0~400:

  • 0: Mute
  • 100: Original volume
  • 400: 4 times of the original volume in maximum with heap overflow protection
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Get Audio Effect Manager(getAudioEffectManager)

public IAudioEffectManager getAudioEffectManager();

This method gets the IAudioEffectManager object associated with the current rtc engine.

Get SDK Version(getSdkVersion)

public static String getSdkVersion();

This method returns the string of the SDK version number.

Get Media Engine Version(getMediaEngineVersion)

public static String getMediaEngineVersion();

This method returns the media engine version number.

Get Error Description(getErrorDescription)

public static String getErrorDescription(int error);

This method gets the detailed error description.

Name Description
error The warning code or error code returned in onWarning or onError.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

IAudioEffectManager Interface Class

Get Audio Effect Volume(getEffectsVolume)

double getEffectsVolume();

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

Set Audio Effect Volume (setEffectsVolume)

public int setEffectsVolume(double volume);

This method sets the volume of the audio effects.

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.

Play Audio Effect(playEffect)

public int playEffect(int soundId, String filePath, boolean loop, double pitch, double pan, double gain);

This method plays the audio effect.

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

It sets whether to play the audio effect in loops:

  • True: yes, it will be played in loops
  • False: no (default)
pitch

It sets whether to change the volume of the audio effect.

The range is [0.5, 2] with 1.0 as the default value, which means no need to change the volume.

The smaller the value is set, the lower the volume will be.

pan

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

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

It 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, and the volume the audio effect will be.

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

Footnotes

[1]If you have loaded the audio effect to the memory via preloadEffect, be sure that the soundId to be set here is the same as the one set in preloadEffect .

Stop Playing Audio Effect(stopEffect)

public int stopEffect(int soundId);

This method stops playing a specific audio effect.

Name Description
soundId The 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)

public int stopAllEffects();

This method stops playing all the audio effects.

Pre-Load Audio Effect(preloadEffect)

public int preloadEffect(int soundId, String filePath);

This method pre-loads a specific audio effect file, which is a compressed audio file, to the memory.

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

Release Audio Effect(unloadEffect)

public int unloadEffect(int soundId);

This method releases the specific pre-loaded audio effect from the memory.

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

Pause Audio Effect(pauseEffect)

public int pauseEffect(int soundId);

This method pauses the specific audio effect.

Name Description
soundId The 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)

public int pauseAllEffects();

This method pauses all the audio effects.

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

Resume Audio Effect (resumeEffect)

public int resumeEffect(int soundId);

This method resumes playing a specific audio effect.

Name Description
soundId The 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)

public int resumeAllEffects();

This method resumes all the audio effects.

Set Voice only Mode (setVoiceOnlyMode)

public int setVoiceOnlyMode(boolean enable);

This method sets the voice only mode, which means it only transmit the audio stream, and the rest streams will be eliminated, for example, the sound of the keyboard strokes and etc.

Name Description
enable

True: it enables the voice only mode.

False: it disables the voice only mode.

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

Set the Voice Position of the Remote User(setRemoteVoicePosition)

public int setRemoteVoicePosition(int uid, double pan, double gain);

It sets the voice position of the remote user.

Name Description
uid The User ID of the remote user.
pan

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

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

It 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, and the volume the audio effect will be.

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

Set the Local Voice Pitch(setLocalVoicePitch)

public int setLocalVoicePitch(double pitch);

This method changes the voice pitch of the local speaker.

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

IRtcEngineEventHandlerForGaming Abstract Class

Join Channel Callback (onJoinChannelSuccess)

public void onJoinChannelSuccess(String channel, int uid, int elapsed);

This callback indicates that the user has successfully joined the specified channel with Channel Name and User ID assigned. The channel ID is assigned based on the channel name specified in join() API. If the User ID is not specified when join() is called, the server allocates one automatically.

Name Description
channel Channel Name.
uid

User ID.

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

elapsed Time elapsed in milliseconds from calling joinChannel until this event occurs.

Rejoin Channel Callback (onRejoinChannelSuccess)

public void onRejoinChannelSuccess(String channel, int uid, int elapsed);

In times when the client machine 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 Channel Name.
uid

User ID.

If the UID is specified in the joinChannel method, returns the specified ID;

If not, returns an ID that is automatically allocated by the Agora server.

elapsed Time elapsed in milliseconds from calling joinChannel until this event occurs.

Warning Occurred Callback (onWarning)

public void onWarning(int warn);

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

Note

For detailed warning codes, refer to error_amg.

Name Description
warn Warning code.
msg Warning message.

Error Occurred Callback (onError)

public void onError(int err);

This callback indicates that a network or media error occurred during the runtime of the SDK.

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 failed to initialize a call. In this case, the application informs the user that the call initialization failed and in the same time it also calls the leaveChannel method to exit the channel.

Name Description
err Error codes.

Audio Quality Callback (onAudioQuality)

public void onAudioQuality(int uid, int quality, short delay, short lost);

During a call, this callback is triggered once every 2 seconds to report on the audio quality of the current call. By default it is enabled.

Name Description
uid User ID of the speaker (that is, the user who is speaking).
quality

Rating of the audio quality of the user:

  • QUALITY_EXCELLENT( = 1)
  • QUALITY_GOOD( = 2)
  • QUALITY_POOR( = 3)
  • QUALITY_BAD( = 4)
  • QUALITY_VBAD( = 5)
  • QUALITY_DOWN( = 6)
delay Time delay (in milliseconds).
lost Packet loss rate (in percentage).

Leave Channel Callback (onLeaveChannel)

public void onLeaveChannel(IRtcEngineEventHandler.RtcStats stats);

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.

Name Description
stats

The statistics about the call.

  • totalDuration: The call duration in seconds, represented by an aggregate value.
  • txBytes: The total number of bytes transmitted, represented by an aggregate value.
  • rxBytes: The total number of bytes received, represented by an aggregate value.
  • txKBitRate: The transmission bitrate in kbps, represented by an instantaneous value.
  • rxKBitRate: The receive bitrate in kbps, represented by an instantaneous value.
  • lastmileQuality: The current network connection quality of the client machine, represented by an instantaneous value.
  • cpuTotalQuality: The current system CPU usage in percentage (%).
  • cpuAppQuality: The current application CPU usage in percentage (%).
struct SessionStat {
    int totalDuration;
    int txBytes;
    int rxBytes;
    int txKBitRate;
    int rxKBitRate;
    int lastmileQuality;
    int cpuTotalUsage;
    int cpuAppUsage;
    };

Rtc Engine Statistics Callback (onRtcStats)

public void onRtcStats(IRtcEngineEventHandler.RtcStats stats);

The SDK updates the application on the statistics of the Rtc Engine runtime status once every 2 seconds.

Name Description
stats Refer to the description of onLeaveChannel.

Audio Volume Indication Callback (onAudioVolumeIndication)

public void onAudioVolumeIndication(IRtcEngineEventHandler.AudioVolumeInfo[] speakers, int totalVolume);

This callback indicates who is speaking and the speaker’s volume. By default the indication is disabled. If needed, call enableAudioVolumeIndication() method to trigger this indication.

Name Description
speakers

The speaker (array). Each speaker () includes:

  • uid: User ID of the speaker (that is, the user who is speaking).
  • volume: The volume of the speaker between 0 (lowest volume) to 255 (highest volume).
totalVolume Total volume after audio mixing between 0 (lowest volume) to 255 (highest volume).

In-Call Network Quality Callback(onNetworkQuality)

public void onNetworkQuality(int uid, int txQuality, int rxQuality);

This callback is triggered regularly to update the application on the current network quality in a communication or live broadcast channel.

Name Description
uid

User ID. It indicates the specific callback reports the network quality of the user with this UID.

If uid is 0, it reports the local network quality. The current release only reports the quality for the local user.

txQuality

The uplink network quality of the user:

  • QUALITY_EXCELLENT(1)
  • QUALITY_GOOD(2)
  • QUALITY_POOR(3)
  • QUALITY_BAD(4)
  • QUALITY_VBAD(5)
  • QUALITY_DOWN(6)
rxQuality

The downlink network quality of the user:

  • QUALITY_EXCELLENT(1)
  • QUALITY_GOOD(2)
  • QUALITY_POOR(3)
  • QUALITY_BAD(4)
  • QUALITY_VBAD(5)
  • QUALITY_DOWN(6)

Other User Joined Channel Callback (onUserJoined)

public void onUserJoined (int uid, int elapsed);

This callback method notifies the application that another user has joined the channel. If there are other users in the channel when that user joins, the SDK also reports to the application on the existing users who are already in the channel.

Name Description
uid The user ID.
elapsed The time interval in milliseconds from calling joinChannel until this callback is triggered.

Other User Offline Callback (onUserOffline)

public void onUserOffline (int uid, int reason);

This callback notifies the application that a user 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) or not. If no data package is received from the user in 15 seconds, the SDK takes it as the user being offline. Sometimes a weak network connection may lead to false detection, therefore we recommend using signaling for reliable offline detection.

Name Description
uid User ID.
reason

Reasons for user going offline:

  • USER_OFFLINE_QUIT: User has quit the call.
  • USER_OFFLINE_DROPPED: The SDK is timeout and dropped offline because it hasn’t received data package for too long.

Sometimes when the other user quits the call but the message is not passed to the SDK due to unreliable channel, the SDK may mistake it as the other user is timeout and dropped offline.

Other User Muted Audio Callback (onUserMuteAudio)

public void onUserMuteAudio (int uid, boolean muted);

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

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

Connection Lost Callback (onConnectionLost)

public 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. The SDK will keep trying to reconnect after this callback is triggered. Upon reconnection, an onRejoinChannelSuccess callback will then be triggered.

Connection Interrupted Callback (onConnectionInterrupted)

public 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 (stated below) 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.

Audio Mixing Playback Finished Callback (onAudioMixingFinished)

public void onAudioMixingFinished();

This callback is triggered when the playback of the audio mixing file is finished.

Audio Route Changed Callback(onAudioRouteChanged)

public void onAudioRouteChanged(int routing);

The SDK notifies the application that the audio route is changed. It notifies the current audio route is switched to earpiece, speakerphone, headset or bluetooth.

Channel Key Expired Callback(onRequestChannelKey)

public void onRequestChannelKey();

If a Channel Key is specified when calling joinChannel(), and due to Channel Key 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 Channel Key to reconnect to the server.

This callback notifies the application of generating a new Channel Key, and calling renewChannelKey() to specify the newly generated Channel Key.

Client Role Changed Callback (onClientRoleChanged)

public void onClientRoleChanged(CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole)

When you set the channel profile as Live Broadcast when calling setChannelProfile,this callback is triggered when there is any role change in the channel.

Name Description
oldRole The role that you switched from
newRole The role that you are now in
enum CLIENT_ROLE_TYPE
{
    CLIENT_ROLE_BROADCASTER = 1,
    CLIENT_ROLE_AUDIENCE = 2,
};