Communication API - Android

Java Interface Class Description
Basic Methods(RtcEngine) The RtcEngine class provides the main methods that can be invoked by your application.
Callback Methods(IRtcEngineEventHandler) The IRtcEngineEventHandler class enables callback event notifications to your application.

Basic Methods(RtcEngine)

Developer suite: io.agora.rtc

RtcEngine class is the main interface class of Agora Native SDK. Call the methods of this class to use all the functionalities of the SDK. We recommend calling the RtcEngine API methods in the same thread instead of in multiple threads. In the previous versions this class is named as AgoraAudio, and it is renamed to RtcEngine from version 1.0.

The developers must follow the corresponding section to implement the basic audio or video functions first, based on which they can add other functions.

Create RtcEngine Object (create)

public static RtcEngine create(Context context,
                                    String appId,
                                    IRtcEngineEventHandler  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 only one RtcEngine object. 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 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.
handler 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 An RtcEngine object.

Implement Audio Communication

The following shows how to implement a basic audio communication function. The developers can add more functions to the basic audio communication according to the following modules included in this document. Be sure that a RtcEngine object has been created for the application according to Create RtcEngine Object (create).

../../_images/android_audio_api.png

Set Channel Profile (setChannelProfile)

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.

The Agora Native SDK currently supports two profiles:

Profile Description
Communication The default setting. It is most commonly used in one-on-one conversations or meetings, where all users in the channel can talk freely.
Live Broadcast Live Broadcast has host and audience roles which can be set by calling setClientRole.,The host sends and receives audio/video, while the audience only receives audio/video only with sending function disabled.
Game Game Voice Mode. Any user in the channel can speak freely. This mode uses the codec with low power consumption and low bitrate by default.

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_COMMUNICATION: Communication (default)
  • CHANNEL_PROFILE _LIVE_BROADCASTING: Live Broadcast
  • CHANNEL_PROFILE _GAME: Game Voice
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Enable Audio Mode(enableAudio)

public int enableAudio();

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

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.

Join Channel (joinChannel)

public int joinChannel(   String  channelKey,
                          String  channelName,
                          String  optionalInfo,
                          int     optionalUid );

This method lets the user 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.

Note

One channel does not accept duplicated UIDs, for example, two users with the same UID. If your App supports the function of one user logging in from different devices simultaneously, be sure that you will use different UIDs. For example, if you used the same UID previously, add the respective Device ID in the UID to make the UIDs different. This action does not apply to the scenario if your App does not support one user logging in from different devices, for example, you log onto a new device and it will be forced to quit on the previously logged-in device.

Name Description
channelKey

The token is a Channel Key generated by the application.

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

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

In most developer circumstances, the static App ID should suffice. For users who have a high security requirement, use the Channel Key.

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,!

#$%&,()+,

-,:;<=.,>?

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

optionalInfo (Optional) Additional info about the channel. Other users in the channel won’t receive this information.
optionalUid

(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.
  • ERR_INVALID_ARGUMENT (-2): The passed argument is invalid.
  • ERR_NOT_READY (-3): Initialization failed.
  • ERR_REFUSED (-5): The SDK cannot start a call. It could be that the SDK is in another call or failed to create a channel.

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.

Note

If you call destroy() immediately after you have called leaveChannel, it will interrupt the leavechannel process, which means the SDK won’t trigger the onLeaveChannel callback.

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

Implement Video Communication

The following shows how to implement a basic video communication function. The developers can add more functions to the basic audio communication according to the following modules included in this document. Be sure that a RtcEngine object has been created for the application according to Create RtcEngine Object (create).

For the highlighted APIs same as the audio communication, refer to the description in the Implement Audio Communication.

../../_images/android_video_api.png

Create Render View(createRendererView)

public static SurfaceView CreateRendererView (Context context)

This method creates the view for video renderer. It returns the SurfaceView type.

The operation and layout of the view are managed by the application, and the Agora SDK renders the view provided by the application.

The view to display videos must be created using this method instead of directly calling SurfaceView.

Name Description
context The context of Android Activity.

Enable Video Mode (enableVideo)

public int enableVideo()

This method enables video mode.

The application can call this method either before entering a channel or during a call. If it is called before entering the channel, the service starts in video mode; if it is called during a call, it switches from audio to video mode. To disable video mode, call the disablevideo method.

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

Disable Video Mode (disableVideo)

public int disableVideo()

This method disables video mode. The application can call this method either before entering a channel or during a call. If it is called before entering the channel, the service starts in audio mode; if it is called during a call, it switches from video to audio mode. To enable video mode, call the enablevideo method.

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

Set Video Profile (setVideoProfile)

public int setVideoProfile( int profile, boolean swapWidthAndHeight );

This method sets the video encoding profile. Each profile includes a set of parameters such as resolution, frame rate, bitrate, and so on. When the device camera does not support the specified resolution, the SDK automatically chooses a suitable camera resolution, but the encoder resolution still uses the one specified by setVideoProfile.

The method only sets the attributes of the streams encoded by the encoder which may be inconsistent with the final display. For example, when the resolution of the encoded stream is 640x480, and the rotation attribute of the stream is 90 degrees, then the resolution of the final display is in portrait mode.

Note

  • Always set the video profile after calling the enableVideo method.
  • Always set the video profile before calling the joinChannel/startPreview method.
Name Description
profile

The video profile. See the table below for its definition. Profile value is defined in:

io.agora.rtc.IRtcEngineEventHandler.VideoProfile

swapWidthAndHeight

Whether to swap the width and height of the stream:

  • true: swap
  • false: not swap (default)
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Video Profile Definition

Video Profile Enum value Resolution (width * height) Frame Rate (fps) Bitrate(kbps)
120P 0 160x120 15 65
120P_3 2 120x120 15 50
180P 10 320x180 15 140
180P_3 12 180x180 15 100
180P_4 13 240x180 15 120
240P 20 320x240 15 200
240P_3 22 240x240 15 140
240P_4 24 424x240 15 220
360P 30 640x360 15 400
360P_3 32 360x360 15 260
360P_4 33 640x360 30 600
360P_6 35 360x360 30 400
360P_7 36 480x360 15 320
360P_8 37 480x360 30 490
360P_9 38 640x360 15 800
360P_10 39 640x360 24 800
360P_11 100 640x360 24 1000
480P 40 640x480 15 500
480P_3 42 480x480 15 400
480P_4 43 640x480 30 750
480P_6 45 480x480 30 600
480P_8 47 848x480 15 610
480P_9 48 848x480 30 930
720P 50 1280x720 * [1] 15 1130
720P_3 52 1280x720 * [1] 30 1710
720P_5 54 960x720 * [1] 15 910
720P_6 55 960x720 * [1] 30 1380

Footnotes

[1](1, 2, 3, 4) Achieving 720P resolution depends on the performance and capabilities of the device and may not currently be possible on lower performance devices. If a device has inadequate performance then low frame rates may be experienced when using 720P. Agora.io is continuing to optimize video for lower-end devices in future releases – contact support@agora.io to discuss particular device needs.

Set Local Video View(setupLocalVideo)

public int setupLocalVideo( VideoCanvas local );

This method configures the video display settings on the local machine.

The application calls this method to bind with the video window (view) of local video streams and configures the video display settings. When developing the application, the usual practice is to call this method after initialization to configure the local video display settings before entering a channel. After leaving the channel, the bind is still valid which means the window still displays. To unbind the window, set the view value to NULL when calling setupLocalVideo.

Name Description
local The video display settings. Class VideoCanvas:
  • view: The video display window (view).
  • renderMode: The video display mode.
    • RENDER_MODE_HIDDEN(1): If the video size is different than that of the display window, this mode crops the borders of the video (if the video is bigger) or stretches the video (if the video is smaller) to fit it in the window.
    • RENDER_MODE_FIT(2): If the video size is different than that of the display window, resizes the video proportionally to fit the window.
    • RENDER_MODE_ADAPTIVE(3): This mode adopts one of the two above, depending on the orientations. If both callers use the same screen orientation, that is, both use vertical screens or both use horizontal screens, RENDER_MODE_HIDDEN applies. If they use different screen orientations, that is, one vertical and one horizontal, RENDER_MODE_FIT applies.
  • uid: The local user ID as set in the joinchannel method.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set Remote Video View (setupRemoteVideo)

public int setupRemoteVideo( VideoCanvas remote );

This method binds the remote user to the video display window, that is, sets the view for the user of the specified uid. Usually the application should specify the uid of the remote video in the method call before the user enters a channel.

If the remote uid is unknown to the application, set it later when the application receives the onUserJoined event. If the Video Recording function is enabled, the Video Recording Service joins the channel as a dumb client, which means others clients also receive its onUserJoined event. Your application should not bind it with the view, because it does not send any video stream. If your application cannot recognize the dumb client, bind it with the view when the onFirstRemoteVideoDecoded event is triggered. To unbind the user with the view, set the view to null. Once the user left the channel, the SDK unbinds the remote user.

Name Description
remote

The video display settings.

Class VideoCanvas:

  • view: The video display window (view).
  • renderMode: The video display mode.
    • RENDER_MODE_HIDDEN(1): If the video size is different than that of the display window, this mode crops the borders of the video (if the video is bigger) or stretches the video (if the video is smaller) to fit it in the window.
    • RENDER_MODE_FIT(2): If the video size is different than that of the display window, resizes the video proportionally to fit the window.
    • RENDER_MODE_ADAPTIVE(3): This mode adopts one of the two above, depending on the orientations. If both callers use the same screen orientation, that is, both use vertical screens or both use horizontal screens, RENDER_MODE_HIDDEN applies. If they use different screen orientations, that is, one vertical and one horizontal, RENDER_MODE_FIT applies.

Set High-Quality Video Preferences(setVideoQualityParameters)

public int setVideoQualityParameters(bool preferFrameRateOverImageQuality);

This method allows the users to set the video preferences.

Name Description
preferFrameRateOverImageQuality

The video preference to be set:

  • True: Frame Rate over Image Quality
  • False: Image Quality over Frame Rate (default)
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Start Video Preview (startPreview)

int startPreview()

This method starts the local video preview. Before starting the preview, always call setupLocalVideo to set up the preview window and configure its attributes and also call the enableVideo method to enable video. If before calling joinChannel to join the channel, you have called startPreview to start the local video preview, then the local preview is still in the started state after you called leaveChannel to exit the channel. You can call stopPreview to close the local preview.

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

Stop Video Preview (stopPreview)

int stopPreview()

This method stops the local video preview and closes the video.

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

Set Local Video Display Mode (setLocalRenderMode)

public int setLocalRenderMode( int mode );

This method configures the local video display mode.

The application can call this method multiple times during a call to change the display mode.

Name Description
mode

Configures the video display mode.

  • RENDER_MODE_HIDDEN(1): If the video size is different than that of the display window, this mode crops the borders of the video (if the video is bigger) or stretches the video (if the video is smaller) to fit it in the window.
  • RENDER_MODE_FIT(2): If the video size is different than that of the display window, resizes the video proportionally to fit the window.
  • RENDER_MODE_ADAPTIVE(3): This mode adopts one of the two above, depending on the orientations. If both callers use the same screen orientation, that is, both use vertical screens or both use horizontal screens, RENDER_MODE_HIDDEN applies. If they use different screen orientations, that is, one vertical and one horizontal, RENDER_MODE_FIT applies.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set Remote Video Display Mode (setRemoteRenderMode)

public int setRemoteRenderMode(int uid, int mode );

This method configures the remote video display mode. The application can call this method multiple times during a call to change the display mode.

Name Description
uid User ID.
mode

Configures the video display mode.

  • RENDER_MODE_HIDDEN(1): If the video size is different than that of the display window, this mode crops the borders of the video (if the video is bigger) or stretches the video (if the video is smaller) to fit it in the window.
  • RENDER_MODE_FIT(2): If the video size is different than that of the display window, resizes the video proportionally to fit the window.
  • RENDER_MODE_ADAPTIVE(3): This mode adopts one of the two above, depending on the orientations. If both callers use the same screen orientation, that is, both use vertical screens or both use horizontal screens, RENDER_MODE_HIDDEN applies. If they use different screen orientations, that is, one vertical and one horizontal, RENDER_MODE_FIT applies.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Switch Between Front and Back Cameras (switchCamera)

public int switchCamera();

This method switches between front and back cameras.

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

Set Audio Route

Set Default Audio Route(setDefaultAudioRouteToSpeakerPhone)

public int setDefaultAudioRouteToSpeakerPhone( boolean defaultToSpeaker );

This method modifies the default audio route if necessary.

The default audio routes are listed as follows:

Channel Mode Default Audio Route
Communication

Audio Communication: Earpiece

Video Communication: Speakerphone

If the user in a communication channel has called disableVideo or if the user has called muteLocalVideoStream and muteAllRemoteVideoStreams , the audio route is switched back to the earpiece automatically.

Live Broadcast Speakerphone
Game Voice Speakerphone

Modify the above default audio route if necessary according to the following:

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.

Enable Speakerphone (setEnableSpeakerphone)

public int setEnableSpeakerphone( boolean enabled );

This method enables the audio routing to the speakerphone.

After calling this method, the SDK will return the onAudioRouteChanged callback to indicate the changes.

Note

Be sure that you have read the default audio route explanation according to Set Default Audio Route(setDefaultAudioRouteToSpeakerPhone) and check whether it is necessary to call this method.

Name Description
enabled
  • True: when you set it as true:
    • If this API is called after joining channel, no matter whether the audio was routed to the headset, bluetooth, or earpiece, it will be routed to the speaker.
    • If this API is called before joining channel, when joining channel, the audio will be routed to the speaker no matter whether the user has headset or bluetooth.
  • False: when you set it as false, the audio will follow the default audio route mentioned in Set Default Audio Route(setDefaultAudioRouteToSpeakerphone).
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set Audio Volume

Set Speakerphone Volume (setSpeakerphoneVolume)

public int setSpeakerphoneVolume( int volume );

This method sets the speakerphone volume.

Name Description
volume 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. We recommend setting it to a minimum of 200ms.
smooth The smoothing factor. recommended default value is 3.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute Audio and Video Stream

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
On
  • 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 muted );

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

Note

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

Name Description
On
  • 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 muted );

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

Note

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.
muted
  • 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.

Disable Local Video(enableLocalVideo)

int enableLocalVideo(boolean enabled)

This method disables the local video, which is only applicable to the scenario when the user only wants to watch the remote video without sending any video stream to the other user. This method does not require a local camera.

Name Description
enabled
  • true: Enable the local video(default)
  • false: Disable the local video
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute Local Video Stream (muteLocalVideoStream)

public int muteLocalVideoStream( boolean muted );

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

Note

When set to True, this method does not disable the camera and thus does not affect the retrieval of local video streams.

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

Mute All Remote Video Streams (muteAllRemoteVideoStreams)

public int muteAllRemoteVideoStreams( boolean muted );

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

Note

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

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

Mute Certain Remote Video Stream (muteRemoteVideoStream)

public int muteRemoteVideoStream( int uid, boolean muted );

This method pauses/resumes playing a specified user’s video, that is, enables/disables playing a specified user’s video stream.

Note

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

Name Description
uid Specified user’s user ID.
mute
  • True: Stops playing a specified user’s video stream.
  • False: Allows playing a specified user’s video stream.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Audio Mixing

Start Audio Mixing (startAudioMixing)

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

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

Drag Audio Progress Bar(setAudioMixingPosition)

public abstract int setAudioMixingPosition(int pos);

This method drags the progress bar of the audio mixing file to the place wherever you want to play instead of playing it from the very beginning to the end.

Name Description
pos Integer. The position of the audio mixing file in milliseconds.

Recording

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.

Note

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.

Set Recording Audio Format (setRecordingAudioFrameParameters)

Refer to Set Recording Audio Format (setRecordingAudioFrameParameters).

Set Playback Audio Format (setPlaybackAudioFrameParameters)

Refer to Set Playback Audio Format (setPlaybackAudioFrameParameters).

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 signal clipping 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 playback signal volume ranges from 0~400:

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

Encryption

Register Packet Observer (registerAgoraPacketObserver)

JNIEXPORT jint registerAgoraPacketObserver(void* engine,agora::rtc::IPacketObserver* observer);

This method registers a packet observer. When sending or receiving audio or video packets, the Agora SDK calls back the interface defined by IPacketObserver, and the application can use this interface to process data, performing, for example, data encryption and decryption. When the application initializes the RtcEngine instance, use dlopen/dlsym to find registerAgoraPacketObserver, the derived function of libagora-rtc-sdk-jni.so.

Note

The maximum size of the processed network packet is 1200 bytes. A packet larger than the maximum size may not be sent successfully.

Name Description
engine It can be retrieved by calling the API RtcEngine.getNativeHandle().
observer Callback interface of the send/receive packet.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Enable Built-in Encryption(setEncryptionSecret)

public abstract int setEncryptionSecret(String secret);

Ensure that your application calls setEncryptionSecret to specify a secret, which enables the built-in encryption before joining a channel. Otherwise the communication is unencrypted. All users in a channel must set the same secret. The secret is automatically cleared once a user has left the channel. If the secret is not specified or set to empty, the encryption function is disabled.

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

Set Built-in Encryption Mode(setEncryptionMode)

int setEncryptionMode  (String  encryptionMode)

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

All users in the same channel must use the same encryption mode and secret. You can refer to AES encryption algorithm related information on the differences of the several encryption modes.

Note

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

Name Description
encryptionMode

Encryption mode. The following modes are supported currently:

  • “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.

Establish Data Channel

Create Data Stream(createDataStream)

public abstract int createDataStream(boolean reliable, boolean ordered);

This method creates the data stream. Each person can only have up to 5 data channels at the same time. It allows the maximum latency of 5s in a channel. If the recipient does not receive the sent data within 5s, the data channel will report an error to the application. Currently Agora Native SDK supports 99% reliable and 100% ordered data transmission.

Name Description
reliable True: The recipients will receive data from the sender within 5s.
ordered True: The recipients will receive data from the sender in order within 5s.
Return Value
  • <0: It returns error code when it fails to create the data stream [2]
  • >0: It returns the Stream ID when the data stream is created.

Footnotes

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

Send Data Stream(sendStreamMessage)

public abstract int sendStreamMessage(int streamId, byte[] message);

This method sends the created data stream to the recipients. Each channel supports up to 30 packets per second and each packet cannot exceed 1KB. The API controls the rate in data channel: each application supports up to 6KB data per second. Each user can have up to 5 data channels simultaneously.

Name Description
streamId Stream ID returned by createDataStream.
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 and etc.

Test and Detection

Start Audio Call Test (startEchoTest)

public int startEchoTest();

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

Note

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.

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 Audio Call Test (stopEchoTest)

public int stopEchoTest();

This method stops the 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 Network Test (enableLastmileTest)

public int enableLastmileTest();

This method enables the network quality test to test the user’s network connection quality. It is disabled by default.

This method is mainly used in this scenario:

Before the users join a channel, they call this method to forecast whether the uplink network quality currently is good enough.

Calling this method consumes extra network traffic, which may affect the communication quality. Call disableLastmileTest to disable it immediately once they have received the onLastmileQuality callback before they join the channel.

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

Disable Network Test (disableLastmileTest)

public int disableLastmileTest();

This method disables the network connection quality test.

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

Monitor Network Connection Event (monitorConnectionEvent)

public void monitorConnectionEvent( boolean monitor );

This method monitors the network connection event. The application calls this method before entering the channel. By default, monitoring network connection event is enabled.

Name Description
monitor
  • True: Monitoring network connection event enabled (this is the default setting).
  • False: Monitoring network connection event disabled.

Feedback

Retrieve Current Call ID (getCallId)

public String getCallId();

This method retrieves the current call ID.

Every time when a user joins a channel on a client machine, a CallId is generated to identify the call from this client. Some methods such as rate and complain submit feedback to the SDK and are invoked after the call ends. These methods r equire 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)

public int rate(String      callId,
                    int     rating,
                    String  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 Call Quality (complain)

public int complain(String callId,
                    String 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 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.

Others

Renew Channel Key (renewChannelKey)

public int renewChannelKey( const char* channelKey )

This method updates the Channel Key.

The key expires after a certain period of time once the Channel Key schema is enabled. When the onError callback reports the error ERR_CHANNEL_KEY_EXPIRED(109), the application should 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.

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( unsigned int filter )

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

Name Description
filter Filters
  • 1: INFO
  • 2: WARNING
  • 4: ERROR
  • 8: FATAL
  • 0x800: DEBUG
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Destroy Engine Instance (destroy)

public void destroy();

This method releases all the resources being used by the Agora SDK, and may be useful for applications that perform voice or video communications from time to time according to user needs, but at other times want to maintain resources for other application functions.

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 a new Initialize ((sharedEngineWithappId) must be performed to establish a new AgoraRtcEngineKit instance.

Note

This method is called synchronously. The result returns after the IRtcEngine Object resources are released. APP should not call this interface in the callback generated by the SDK, otherwise the SDK must wait for the callback to return to recover the associated object resources, resulting in deadlock.

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

Get SDK Version(getVersion)

public void getVersion();

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

Audio Effect Methods(IAudioEffectManager)

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

Adjust Audio Effect Volume in Real Time(setVolumeOfEffect)

public int setVolumeOfEffect(int soundId, double volume);

This method adjusts the volume of the specified sound effect in realtime.

Name Description
soundId The 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 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. [3]
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 pitch of the audio effect. The range is [0.5, 2] with 1.0 as the default value, which means no need to change the pitch.

The smaller the value is set, the lower the pitch 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

[3]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.

Callback Methods(IRtcEngineEventHandler)

Developer Suite: io.agora.rtc

The SDK uses the 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 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 ID 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.
elapsed Time elapsed (in milliseconds) from calling joinChannel until this event occurs.

Warning Occurred Callback (onWarning)

public void onWarning(int warn, const char* msg )

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.

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:

  • 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 open the local audio or video devices and thus failed to start a call.
  • ERR_START_CAMERA(1003): Failed to open the local camera.

Leave Channel Callback (onLeaveChannel)

public void onLeaveChannel( 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.Audio Quality Callback (onAudioQuality)

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;
    };

Audio Route Changed Callback(onAudioRouteChanged)

public void onAudioRouteChanged(int routing);

The SDK notifies the application that the audio route is changed after calling setEnableSpeakerphone successfully.

It notifies the current audio route is switched to earpiece, speakerphone, headset or bluetooth.

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:

  • QUALITY_UNKNOWN( = 0)
  • 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).

Audio Volume Indication Callback (onAudioVolumeIndication)

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

This callback indicates who is speaking and the speaker’s volume.

By default the indication is disabled. If needed, use the enableAudioVolumeIndication() method to configure it.

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

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

Rtc Engine Statistics Callback (onRtcStats)

public void onRtcStats( 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 RtcStats as above.

Network Quality Callback (onLastmileQuality)

public void onLastmileQuality(int quality);

This callback reports the network quality of the local user. It is triggered once every 2 seconds during a call.

Name Description
quality
  • QUALITY_UNKNOWN( = 0)
  • QUALITY_EXCELLENT(1)
  • QUALITY_GOOD(2)
  • QUALITY_POOR(3)
  • QUALITY_BAD(4)
  • QUALITY_VBAD(5)
  • QUALITY_DOWN(6)

In-Call Network Quality Callback(onNetworkQuality)

public void onNetworkQuality(uid_t 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_UNKNOWN( = 0)
  • 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_UNKNOWN( = 0)
  • QUALITY_EXCELLENT(1)
  • QUALITY_GOOD(2)
  • QUALITY_POOR(3)
  • QUALITY_BAD(4)
  • QUALITY_VBAD(5)
  • QUALITY_DOWN(6)

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.

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.

First Local Video Frame Displayed Callback (onFirstLocalVideoFrame)

public void onFirstLocalVideoFrame( int width,
                                    int height,
                                    int elapsed )

This callback is triggered when the first local video frame is displayed on the screen.

Name Description
width Width (in pixels) of the video stream.
height Height (in pixels) of the video stream.
elapsed Time elapsed (in milliseconds) from calling joinChannel until this callback is triggered.

First Remote Video Frame Displayed Callback (onFirstRemoteVideoFrame)

public void onFirstRemoteVideoFrame( int uid,
                                    int width,
                                    int height,
                                    int elapsed )

This method is triggered when the first frame of the remote video appears in the user’s video window. The application can retrieve the data of time elapsed from user joining the channel until the first video frame is displayed.

Name Description
uid User ID of the user whose video streams are received.
width Width (in pixels) of the video stream.
height Height (in pixels) of the video stream.
elapsed Time elapsed (in milliseconds) from calling joinChannel until this callback is triggered.

First Remote Video Frame Received and Decoded Callback (onFirstRemoteVideoDecoded)

public void onFirstRemoteVideoDecoded(int uid,
                                      int width,
                                      int height,
                                      int elapsed )

This callback is triggered upon receiving and successfully decoding the first frame of the remote video. The application can configure the user view settings in this callback.

Name Description
uid User ID of the user whose video streams are received.
width Width (in pixels) of the video stream.
height Height (in pixels) of the video stream.
elapsed Time elapsed (in milliseconds) from calling joinChannel until this callback is triggered.

Other User Paused/Resumed Video Callback (onUserMuteVideo)

public void onUserMuteVideo(int uid, boolean muted)

This callback indicates that some other user has paused/resumed his/her video stream.

Name Description
uid User ID
muted
  • True: User has paused his/her video.
  • False: User has resumed his/her video.

Other User Enabled/Disabled Video Callback (onUserEnableVideo)

public void onUserEnableVideo(int uid, boolean enabled)

This callback indicates that some other user has enabled/disabled the video function. Disabling the video function means that the user can only use voice call, can neither show/send their own videos nor receive or display videos from other people.

Name Description
uid User ID
muted
  • True: User has enabled his/her video.
  • False: User has disabled his/her video.

Local Video Statistics Callback (onLocalVideoStats)

public void onLocalVideoStats( RemoteVideoStats stats) {
}

The SDK updates the application on the statistics about uploading local video streams once every 2 seconds.

Name Description
stats

The statistics of the local video, including:

  • sentBitrate: Data sending bitrate (in kbps) since last count.
  • sentFrameRate: Data sending frame rate (in fps) since last count.

Remote Video Statistics Callback (onRemoteVideoStats)

public void onRemoteVideoStats( RemoteVideoStats stats) {
}

The SDK updates the application on the statistics about receiving remote video streams once every 2 seconds.

Name Description
stats

The statistics of the remote video, including:

  • uid: User ID of the user whose video streams are received.
  • delay: Time delay (in milliseconds).
  • receivedBitrate: Data receiving bitrate (in kbps).
  • receivedFrameRate: Data receiving framerate (in fps).
  • rxStreamType: High Video Stream or Low Video Stream.

Camera Ready Callback (onCameraReady)

public void onCameraReady()

This callback indicates that the camera is opened and ready to capture video. If failed to open the camera, handle the error in the onError() method.

Video Stopped Callback (onVideoStopped)

public void onVideoStopped()

This callback indicates that the video is stopped. The application can use this callback to change the configuration of the view (for example, displaying other pictures on the view) after the video stops.

Data Stream Received Callback(onStreamMessage)

public void onStreamMessage(int uid, int streamId, byte[] data);

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

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

Data Stream Sent Failure Callback(onStreamMessageError)

public 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 5 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 description, see Error and Warning Messages

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

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.

This function was previously provided in the callback report of onError(): ERR_CHANNEL_KEY_EXPIRED(109)、ERR_INVALID_CHANNEL_KEY(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)

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