Interactive Broadcast API

There is a new release of the Developer Center! If you'd like to check it out, please click  here

Interactive Broadcast API

Java Interface Class Description
Basic Methods (RtcEngine) The RtcEngine class provides the main methods that can be invoked by your application.
Audio Effect Methods (IAudioEffectManager) The IAudioEffectManager class provides the methods to manage the audio effects.
Push-Stream Methods (PublisherConfiguration) The PublisherConfiguration class provides the method to configure pushing streams for CDN (content delivery network) Live scenarios.
Callback Methods (IRtcEngineEventHandler) The IRtcEngineEventHandler class enables callback event notifications to your application.

Basic Methods (RtcEngine)

Developer suite: io.agora.rtc

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

Create an RtcEngine Object (create)

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

This method creates an RtcEngine object.

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 the RtcEngine class are executed asynchronously. Agora recommends calling the interface methods in the same thread. Unless otherwise specified, the following rule applies to all APIs whose return values are integer types: A return value of 0 indicates that the call was successful, and a return value less than 0 indicates that the call failed.

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

Implementing a Live Voice Broadcast

The following figure shows how to implement the basic live voice broadcast function. Developers can add more functions according to the modules described in this document. Ensure that an RtcEngine object has been created for the application according to Create an RtcEngine Object (create).

../_images/android_audio_api_live.png

Set the 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 methods for optimization.

The Agora Native SDK supports the following profiles:

Profile Description
Communication Default setting. This is used in one-on-one calls, where all users in the channel can talk freely.
Live Broadcast Live Broadcast. Host and audience roles that can be set by calling setClientRole. The host sends and receives voice, while the audience receives voice only with the sending function disabled.
Gaming Gaming Mode. Any user in the channel can talk freely. This mode uses the codec with low-power consumption and low bitrate by default.

Note

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

The channel profile. Choose one of the following:

  • CHANNEL_PROFILE_COMMUNICATION: Communication (default)
  • CHANNEL_PROFILE _LIVE_BROADCASTING: Live Broadcast
  • CHANNEL_PROFILE _GAME: Game Voice
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the User Role (setClientRole)

int setClientRole(int role)

This method allows you to set the user role as a host or an audience (default) before joining a channel. This method also allows you to switch the user role after joining a channel.

Name Description
role

The user role in a live broadcast:

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

Enable the Audio Mode (enableAudio)

public int enableAudio();

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

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

Disable the Audio Mode (disableAudio)

public int disableAudio();

This method disables the audio mode.

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

Set High-quality Audio Preferences (setHighQualityAudioParameters)

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

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

Name Description
fullband

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

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

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

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

High bitrate. Recommended in voice-only mode.

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

Note

Agora does not recommend using this method. If you want to set the audio profile, see Set the Audio Profile (setAudioProfile) .

Join a Channel (joinChannel)

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

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

Note

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

Name Description
token

A Token generated by the application.

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

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

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

channelName

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

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

#$%&, ()+,

-, :;<=., >?

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

optionalInfo (Optional) Additional information about the channel [1]. Other users in the channel will not receive this information.
optionalUid

(Optional) User ID: A 32-bit unsigned integer ranging from 1 to (2^32-1). It must be unique. If not assigned (or set to 0), the SDK will assign one and return it in the 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 integers are not supported by Java, the UID is handled as a 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 through “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. The SDK could be in another call or failed to create a channel.

Footnotes

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

Leave a Channel (leaveChannel)

public int leaveChannel();

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

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

Note

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

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

Set the Video Source (setVideoSource)

public abstract int setVideoSource(IVideoSource source);

This method sets the video source. If you wish to use external video source, call this method to add the external video source into the SDK. See The IVideoSource Interface .

Set the Local Video Renderer (setLocalVideoRenderer)

public abstract int setLocalVideoRenderer(IVideoRenderer render);

This method sets the local video renderer. If you wish to use the external video renderer, call this method to add the external renderer into the SDK. See The IVideoSink Interface .

Set the Remote Video Renderer (setRemoteVideoRenderer)

public abstract int setRemoteVideoRenderer(int uid, IVideoRenderer render);

This method sets the remote local renderer. If you wish to use the external video renderer, call this method to add the external renderer into the SDK. See The IVideoSink Interface .

Set the Local Voice Pitch (setLocalVoicePitch)

int setLocalVoicePitch(double pitch)

This method changes the voice pitch of the local speaker.

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

Set the Local Voice Equalization (setLocalVoiceEqualization)

public abstract int setLocalVoiceEqualization(int bandFrequency, int bandGain);

This method sets the local voice equalization effect.

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

Set the Local Voice Reverberation (setLocalVoiceReverb)

public abstract int setLocalVoiceReverb(int reverbKey, int value);

This method sets local voice reverberation.

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

Set the Volume of the In-ear Monitor (setInEarMonitoringVolume)

int setInEarMonitoringVolume(int volume)

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

Name Description  
volume Volume of the in-ear monitor ranging from 0 to 100. The default value is 100.

Set the Audio Profile (setAudioProfile)

public int setAudioProfile(int profile, int scenario);

This method sets the audio parameters and application scenarios.

Note

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

Name Description
profile

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

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

It sets the audio application scenarios:

  • AUDIO_SCENARIO_DEFAULT = 0: default
  • AUDIO_SCENARIO_CHATROOM_GAMING = 1: Applicable to the gaming scenario
  • AUDIO_SCENARIO_CHARROOM_ENTERTAINMENT = 2: Applicable to the entertainment scenario that supports voice during gameplay
  • AUDIO_SCENARIO_EDUCATION = 3: Applicable to the education scenario that prioritizes fluency and stability
  • AUDIO_SCENARIO_GAME_STREAMING = 4: Applicable to the live gaming scenario that needs to enable the gaming audio effects in the speaker mode in a live broadcast scenario
  • AUDIO_SCENARIO_SHOWROOM = 5: Applicable to the showroom scenario that optimizes the audio quality with professional external equipment
Return Value
  • 0: Method call succeeded
  • < 0: Method call failed

Implementing a Live Video Broadcast

The following figure shows how to implement the basic live video broadcast function. Developers can add more functions according to the modules described in this document. Ensure that an RtcEngine object has been created for the application according to Create an RtcEngine Object (create).

For which APIs are the same as the ones used in a live voice broadcast, see Implementing a Live Voice Broadcast.

../_images/android_video_api_live.png

Create a Video Renderer View (createRendererView)

public static SurfaceView createRendererView (Context context)

This method creates a video renderer view. 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.

Set the 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 configure the video display settings. 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 Video display settings. Class VideoCanvas:
  • view: Video display window (view).
  • renderMode: 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, it resizes the video proportionally to fit the window.
  • uid: Local user ID as set in the joinchannel method.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the 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 other clients also receive this 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 has left the channel, the SDK unbinds the remote user.

Name Description
remote

Video display settings.

Class VideoCanvas:

  • view: Video display window (view).
  • renderMode: 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, it resizes the video proportionally to fit the window.

Enable the Video Mode (enableVideo)

public int enableVideo()

This method enables the video mode.

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

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

Disable the Video Mode (disableVideo)

public int disableVideo()

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

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

Set the 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 the resolution, frame rate, and bitrate. When the camera device does not support the specified resolution, the SDK will automatically choose a suitable camera resolution, while the encoder resolution will still be the one specified by setVideoProfile.

This 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 640 x 480, and the rotation attribute of the stream is 90 degrees, then the resolution of the final display will be 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

Video profile. See the following tables for details.

The 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 Resolution Enumeration Resolution Frame Rate (fps) Bitrate (kbit/s)
120P 0 160 x 120 15 120
120P_3 2 120 x 120 15 100
180P 10 320 x 180 15 280
180P_3 12 180 x 180 15 200
180P_4 13 240 x 180 15 240
240P 20 320 x 240 15 360
240P_3 22 240 x 240 15 280
240P_4 23 424 x 240 15 440
360P 30 640 x 360 15 800
360P_3 32 360 x 360 15 520
360P_4 33 640 x 360 30 1200
360P_6 35 360 x 360 30 780
360P_7 36 480 x 360 15 1000
360P_8 37 480 x 360 30 1500
480P 40 640 x 480 15 1000
480P_3 42 480 x 480 15 800
480P_4 43 640 x 480 30 1500
480P_6 45 480 x 480 30 1800
480P_8 47 848 x 480 15 1200
480P_9 48 848 x 480 30 1800
720P 50 1280 x 720 [2] 15 2400
720P_3 52 1280 x 720 [2] 30 3600
720P_5 54 960 x 720 [2] 15 1920
720P_6 55 960 x 720 [2] 30 2880

Footnote

[2](1, 2, 3, 4) Whether 720p can be supported depends on the device. If the device cannot support 720p, the frame rate will be lower than the one listed in the table. Agora optimizes the video in lower-end devices. For special requirements, please contact support@agora.io.

Enable Dual-stream Mode (enableDualStreamMode)

int enableDualStreamMode(boolean enabled);

This method sets the stream mode (only applicable to live broadcast) to single- (default) or dual-stream mode.

Name Description
enabled

The mode is in single stream or dual stream:

  • True: Dual stream
  • False: Single stream
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Video Stream Type (setRemoteVideoStreamType)

int setRemoteVideoStreamType(uid_t uid, REMOTE_VIDEO_STREAM_TYPE streamType)

This method specifies the video stream type of the remote user to be received by the local user when the remote user sends dual streams.

  • If dual stream mode is enabled by calling enableDualStreamMode, you will receive the high video stream by default. This method allows the application to adjust the corresponding video stream type according to the size of the video windows to save bandwidth and calculation resources.
  • If dual stream mode is not enabled, you will receive the high video stream by default.

The result after calling this method will be returned in onApiCallExecuted. The Agora SDK receives the high video stream by default to save the bandwidth. If needed, users can switch to the low video stream using this method.

Name Description
uid User ID
streamType

Set the video stream size.

The following lists the video stream types:

  • REMOTE_VIDEO_STREAM_HIGH(0): High video stream
  • REMOTE_VIDEO_STREAM_LOW(1): Low video stream
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

The resolution of the high video stream is 1.1, 4.3, and 16.9. The low video stream has the same aspect ratio:

Resolution Frame Rate Keyframe Interval Bitrate (kbps)
160 x 160 5 5 45
160 x 120 5 5 32
160 x 90 5 5 28

Set High-quality Video Preferences (setVideoQualityParameters)

public int setVideoQualityParameters(bool preferFrameRateOverImageQuality);

This method allows users to set 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.

Set the Picture-in-picture Layout (setVideoCompositingLayout)

public abstract int setVideoCompositingLayout(const VideoCompositingLayout layout);

This method sets the picture-in-picture layouts for live broadcast. This method is only applicable when you want to push streams at the Agora server. When you push stream at the server:

  1. Define a canvas, its width and height (video resolution), the background color, and the number of videos you want to display in total.
  2. Define the position and size of each video on the canvas, and whether it is cropped or zoomed to fit.

The push stream application will format the information of the customized layouts as JSON and package it to the Supplemental Enhancement Information (SEI) of each key frame when generating the H.264 video stream and pushing it to the CDN vendors through the RTMP protocol.

Parameter details are explained in the following table, and you can also refer to Advanced: Adjusting the Picture-in-picture Layout.

Note

  • Call this method after joining a channel.
  • The application should only allow one user to call this method in the same channel, if more than one user calls this method, the other users must call clearVideoCompositingLayout to remove the settings.
Name Description
canvasWidth Width of the entire canvas (display window or screen).
canvasHeight Height of the entire canvas (display window or screen).
backgroundColor Enter any of the 6-digit symbols defined in RGB.
regions

Array of AgoraRtcVideoCompositingRegion. Each host in the channel can have a region to display the video on the screen with the following parameters to be set:

  • uid: User ID of the user with the video to be displayed in the region.
    • x[0.0,1.0]: Horizontal position of the region on the screen.
    • y[0.0,1.0]: Vertical position of the region on the screen.
    • width[0.0, 1.0]: Actual width of the region.
    • height[0.0, 1.0]: Actual height of the region.
  • zOrder[0, 100]: 0 means the region is at the bottom, and 100 means the region is at the top.
  • alpha[0.0, 1.0]: 0 means the region is transparent, and 1 means the region is opaque.
  • renderMode:
    • RENDER_MODE_HIDDEN(1): Cropped
    • RENDER_MODE_FIT(2): Zoomed to fit
appData Application defined data.

Here is an example used to describe the position and size of the region:

../_images/sei_overview.png

Remove the Picture-in-Picture Layout Settings (clearVideoCompositingLayout)

public int clearVideoCompositingLayout;

This method removes the settings made after calling setVideoCompositingLayout.

Start a 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 the attributes, and also call the enableVideo method to enable video. If startPreview is called to start the local video preview before calling joinChannel to join a channel, the local preview will still be in the started state after leaveChannel is called to leave the channel. stopPreview can be called to close the local preview.

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

Stop a 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 the 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, it resizes the video proportionally to fit the window.
  • RENDER_MODE_ADAPTIVE(3): This mode adopts one of the two above-mentioned modes, depending on the orientation. If both callers use the same screen orientation (both use vertical or horizontal screens), RENDER_MODE_HIDDEN applies. If different screen orientations are used (one vertical and one horizontal), RENDER_MODE_FIT applies.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the 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, it resizes the video proportionally to fit the window.
  • RENDER_MODE_ADAPTIVE(3): This mode adopts one of the two above-mentioned modes, depending on the orientation. If both callers use the same screen orientation (both use vertical or horizontal screens), RENDER_MODE_HIDDEN applies. If different screen orientations are used (one vertical and one horizontal), RENDER_MODE_FIT applies.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Local Video Mirror Mode (setLocalVideoMirrorMode)

public abstract int setLocalVideoMirrorMode(int mode)

This method sets the local video mirror mode. Use this method before startPreview , or it does not take effect until you reenable startPreview .

Name Description
mode

Sets the local video mirror mode

  • 0: The default mirror mode, that is, the mode set by the SDK
  • 1: Enable the mirror mode
  • 2: Disable the mirror mode
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.

Start Playing a Video Stream (startPlayingStream)

int startPlayingStream(const char* uri)

This method plays a video stream from the network.

Note

This method is obsolete, and will be removed later.

Name Description
uri The link of the video stream
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Stop Playing a Video Stream (stopPlayingStream)

int stopPlayingStream()

This method stops playing a video stream from the network.

Note

This method is obsolete, and will be removed later.

Name Description
uri The link of the video stream
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Enable Web SDK Interoperability (enableWebSdkInteroperability)

public int enableWebSdkInteroperability(bool enabled);

This method enables interoperability with the Agora Web SDK.

Note

Since the Agora Web SDK is in beta, the performance may be not very stable. Contact support if any issue occurs.

Name Description
enabled

Whether interoperability with the Agora Web SDK is enabled:

  • True: Enabled.
  • False: Disabled.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Manage the Camera

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.

Check whether Camera Zoom is Supported (isCameraZoomSupported)

public abstract boolean isCameraZoomSupported();

It returns:

  • True: The device supports the camera zoom function
  • False: The device does not support the camera zoom function

Check whether Camera Flash is Supported (isCameraTorchSupported)

public abstract boolean isCameraTorchSupported();

It returns:

  • True: The device supports the camera flash function
  • False: The device does not support the camera flash function

Check whether Manual Focus is Supported (isCameraFocusSupported)

public abstract boolean isCameraFocusSupported();

It returns:

  • True: The device supports the manual focus function
  • False: The device does not support the manual focus function

Check whether Auto Focus is Supported (isCameraAutoFocusFaceModeSupported)

public abstract boolean isCameraAutoFocusFaceModeSupported();

It returns:

  • True: The device supports the auto focus function;
  • False: The device does not support the auto focus function;

Set the Camera Zoom Ratio (setCameraZoomFactor)

public abstract int setCameraZoomFactor(float factor);
Name Description
factor Camera zoom factor ranging from 1.0 to the max zoom

Get the Supported Max Zoom Ratio (getCameraMaxZoomFactor)

public abstract float getCameraMaxZoomFactor();

This method gets the max zoom ratio supported by the camera.

Set the Manual Focus Position (setCameraFocusPositionInPreview)

public abstract int setCameraFocusPositionInPreview(float positionX, float positionY);
Name Description
positionX Horizontal coordinate of the touch point in the view
positionY Vertical coordinate of the touch point in the view

Enable the Camera Flash (setCameraTorchOn)

public abstract int setCameraTorchOn(boolean isOn);
Name Description
isOn Whether to enable the camera flash function: True/False

Enable the Camera Auto Focus (setCameraAutoFocusFaceModeEnabled)

public abstract int setCameraAutoFocusFaceModeEnabled(boolean enabled);
Name Description
enabled Whether to enable the camera auto focus function: True/False

Set the Audio Route

Set the Default Audio Route (setDefaultAudioRouteToSpeakerphone)

public int setDefaultAudioRouteToSpeakerphone( boolean defaultToSpeaker );

This method modifies the default audio route if necessary.

The default audio routes are listed in the following table:

Channel Mode Default Audio Route
Communication

Voice 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 default audio route if necessary according to the following table:

Name Description
defaultToSpeaker
  • True: Speakerphone.
  • False: Earpiece.

Whether the audio is routed to the speakerphone or earpiece, once a headset is plugged in or Bluetooth is connected,

the audio route will be changed. The audio route will be switched to default once removing the headset or disconnecting Bluetooth.

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

Enable the 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

Read the default audio route explanation according to Set the Default Audio Route (setDefaultAudioRouteToSpeakerphone) and check whether it is necessary to call this method.

Name Description
enabled
  • True:
    • If this API is called after joining a channel, whether the audio was routed to the headset, Bluetooth device, or earpiece, it will be routed to the speaker.
    • If this API is called before joining a channel, when joining a channel, the audio will be routed to the speaker whether the user uses a headset or Bluetooth device.
  • False: The audio will follow the default audio route mentioned in Set the Default Audio Route (setDefaultAudioRouteToSpeakerphone).
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Audio Volume

Set the 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 the 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 talking and the volume of the speaker.

Name Description
interval

The time interval between two consecutive volume indications:

  • <= 0: Disables the volume indication
  • > 0: The time interval between two consecutive volume indications in millisecond. Agora recommends that you set it to a minimum of 200 ms. Once the method is enabled, the SDK returns the volume indications at the set time internal in the Audio Volume Indication Callback (onAudioVolumeIndication) callback, no matter if there is any one speaking in the channel
smooth The smoothing factor. The default value is 3
Return values
  • 0: Method call succeeded
  • < 0: Method call failed

Mute the Audio and Video Stream

Mute the 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 users’ 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 a Specified 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 the 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 the 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 a Specified Remote Video Stream (muteRemoteVideoStream)

public int muteRemoteVideoStream( int uid, boolean muted );

This method pauses/resumes 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 from the microphone; or, it replaces the microphone’s audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of loop playbacks. This API also supports online music playback.

Note

  • To use this API, ensure that the Android device version is 4.2 or later, and the API version is 16 or later.
  • Call this API when you are in the channel, otherwise it may cause issues.
  • If you call this API on an emulator, only the MP3 file format is supported.
Name Description
filePath

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.

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 from the microphone.
  • False: Local audio file mixed with the audio stream from the microphone.
cycle

Number of loop playbacks:

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

Stop Audio Mixing (stopAudioMixing)

public int stopAudioMixing();

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

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

Pause Audio Mixing (pauseAudioMixing)

public int pauseAudioMixing();

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

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

Resume Audio Mixing (resumeAudioMixing)

public int resumeAudioMixing();

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

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

Adjust the Audio Mixing Volume (adjustAudioMixingVolume)

public int adjustAudioMixingVolume(int volume);

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

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

Get the Audio Mixing Duration (getAudioMixingDuration)

public int getAudioMixingDuration();

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

Get the Current Audio Position (getAudioMixingCurrentPosition)

public int getAudioMixingCurrentPosition();

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

Drag the Audio Progress Bar (setAudioMixingPosition)

public abstract int setAudioMixingPosition(int pos);

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

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

Recording

Start an Audio Recording (startAudioRecording)

public int startAudioRecording( String filePath, int quality );

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

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

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

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

Audio recording quality:

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

Stop an Audio Recording (stopAudioRecording)

public int stopAudioRecording();

This method stops recording on the client.

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.

Adjust the Recording Volume (adjustRecordingSignalVolume)

public int adjustRecordingSignalVolume(int volume);

This method adjusts the recording volume.

Name Description
volume

Recording volume, ranges from 0 to 400:

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

Adjust the Playback Volume (adjustPlaybackSignalVolume)

public int adjustPlaybackSignalVolume(int volume);

This method adjusts the playback volume.

Name Description
volume

Playback volume, ranges from 0 to 400:

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

Encryption

Register a 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. Any 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);

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

Note

Do not use this method together with CDN.

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

Set the Built-in Encryption Mode (setEncryptionMode)

int setEncryptionMode  (String  encryptionMode)

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

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

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

Note

Do not use this function together with CDN.

Name Description
encryptionMode

Encryption mode. The following modes are supported:

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

Establish a Data Channel

Create a Data Stream (createDataStream)

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

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

Note

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

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

Footnotes

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

Send a Data Stream (sendStreamMessage)

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

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

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

Test and Detection

Start an 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 are working properly. In the test, the user first speaks, and the recording is played back in 10 seconds. If the user can hear the recording in 10 seconds, it indicates that the audio devices and network connection work properly.

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

public int stopEchoTest();

This method stops an audio call test.

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

Enable the Network Test (enableLastmileTest)

public int enableLastmileTest();

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

This method is mainly used in two scenarios:

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

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

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

Note

For current hosts, do not call this method.

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

Disable the Network Test (disableLastmileTest)

public int disableLastmileTest();

This method disables the network connection quality test.

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

Monitor the Network Connection Event (monitorConnectionEvent)

public void monitorConnectionEvent( boolean monitor );

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

Name Description
monitor
  • True: Enabled (default setting).
  • False: Disabled.

Feedback

Retrieve the Current Call ID (getCallId)

public String getCallId();

This method retrieves the current call ID.

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

Name Description
Return Value Current call ID.

Rate the Call (rate)

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 the 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 of the call with a length less than 800 bytes.

This parameter is optional.

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

Other Functions

Renew Token (renewtoken)

public int renewtoken( const char* token )

This method updates the Token.

The key expires after a certain period of time once the Token schema is enabled. When the onError callback reports the error ERR_TOKEN_EXPIRED(109), the application should retrieve a new key and then call this method to renew it. Failure to do so will result in the SDK disconnecting with the server.

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

Specify a Log File (setLogFile)

public int setLogFile( String filePath );

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

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

Set the 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 the Engine Instance (destroy)

public void destroy();

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

Once the application has called destroy() to destroy the created RtcEngine instance, no other methods in the SDK can be used and no callbacks occur.

To start communications again, 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. The app should not call this interface in the callback generated by the SDK, otherwise the SDK must wait for the callback to return before it can reclaim the related object resources, causing a deadlock.

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

Get the SDK Version (getVersion)

public void getVersion();

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

Audio Effect Methods (IAudioEffectManager)

Get the Audio Effect Volume (getEffectsVolume)

double getEffectsVolume();

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

Set the Audio Effect Volume (setEffectsVolume)

public int setEffectsVolume(double volume);

This method sets the volume of the audio effects.

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

Adjust the Audio Effect Volume in Real Time (setVolumeOfEffect)

public int setVolumeOfEffect(int soundId, double volume);

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

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

Play an 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 ID of the audio effect. Each audio effect has a unique ID. [4]
filePath Absolute path of the audio effect file.
loop

Sets whether to play the audio effect in a loop

  • True: Yes
  • False: No (default)
pitch

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.

pan

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

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

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

The default value is 100.0. The smaller the number, the lower the volume of the audio effect.

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

Footnotes

[4]If the audio effect is loaded into the memory through preloadEffect, ensure that the soundId set is the same as in preloadEffect.

Stop Playing an Audio Effect (stopEffect)

public int stopEffect(int soundId);

This method stops playing a specific audio effect.

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

Stop Playing all Audio Effects (stopAllEffects)

public int stopAllEffects();

This method stops playing all the audio effects.

Preload an Audio Effect (preloadEffect)

public int preloadEffect(int soundId, String filePath);

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

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

Release an Audio Effect (unloadEffect)

public int unloadEffect(int soundId);

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

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

Pause an Audio Effect (pauseEffect)

public int pauseEffect(int soundId);

This method pauses 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

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 an Audio Effect (resumeEffect)

public int resumeEffect(int soundId);

This method resumes playing a specific audio effect.

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

Resume all Audio Effects (resumeAllEffects)

public int resumeAllEffects();

This method resumes all the audio effects.

Push-stream Methods (PublisherConfiguration)

Before calling the methods listed in this section:

  • Ensure that the bypass-live push-stream function is enabled by contacting Agora.
  • Ensure that only the user, who has called setClientRole and set the user role as the host, can use the methods in this section.
  • The host must call the related methods before joining a channel

Configure Push-stream (configPublisher)

Note

This method is deprecated. Though you can still use it to publish to CDN,Agora recommends using the following methods instead:

  • addPublishStreamUrl()
  • removePublishStreamUrl()
  • setLiveTranscoding()

Agora will continue improving the CDN publishing feature on top of the abovementioned APIs.

public abstract int configPublisher(PublisherConfiguration config);

This method configures the push-stream settings for the engine before joining a channel for CDN Live. Agora provides a Builder class to configure the push-stream for CDN Live, for example,

PublisherConfiguration config = New PublisherConfiguration.Builder()
  .owner(true)
  .size(360, 640)
  .framerate(15)
  .bitrate(500)
  .defaultLayout(1)
  .lifecycle(STREAM_LIFE_CYCLE_BIND2CHANNEL)
  .rawStreamUrl(rtmpUrl)
  .publisherUrl(rtmpUrl)
  .injectStream(Url, width, height)
  .build();

mRtcEngine.configPublisher(config);

Note

  • Check the The Builder Class on how to call each method included for the push-stream settings configuration.
  • Set the resolution, frame rate, and bitrate the same as those of the uplink host to avoid video quality degradation.
  • Currently, this method is in beta for test and use. Contact sales@agora.io to use this method.

The Builder Class

Set the RTMP Stream Owner (owner)

public Builder owner(boolean isRoomOwner)

In the Builder Class, this method sets whether the current host is the RTMP stream owner.

Name Description
isRoomOwner
  • True: Yes (default), push-stream configuration.
  • False: No push-stream configuration.

Set the Stream Resolution (size)

public Builder size(int width, int height)

In the Builder Class, this method sets the resolution of the output data stream set for CDN Live.

Name Description
width Width of the output data stream set for CDN Live. 360 is the default value.
height Height of the output data stream set for CDN Live. 640 is the default value.

Set the Stream Frame Rate (frameRate)

public Builder frameRate(int framerate)

In the Builder class, this method sets the frame rate of the output data stream set for CDN Live.

Name Description
framerate Frame rate of the output data stream set for CDN Live. 15 fps is the default value.

Set the Stream Bitrate (bitRate)

public Builder biteRate(int bitrate)

In the Builder class, this method sets the bitrate of the output data stream set for CDN Live.

Name Description
bitrate Bitrate of the output data stream set for the CDN Live. 500 kbps is the default value.

Set the Default Layout (defaultLayout)

public Builder defaultLayout(int layoutStyle)

In the Builder class, this method sets the Default Layout if you do not use Flexible Adjustment.

Name Description
layoutStyle
  • 0: Tile horizontally
  • 1: Layered windows
  • 2: Tile vertically

Set the Publishing URL (publishUrl)

public Builder publishUrl(String url)

In the Builder class, this method configures the push-stream address for the picture-in-picture layouts.

Name Description
url Configures the push-stream address for the picture-in-picture layouts. The default value is NULL.

Set the Raw Stream URL (rawStreamUrl)

public Builder rawStreamUrl(String url)

In the Builder class, this method sets the push-stream address of the original stream which does not require picture-blending.

Name Description
url Push-stream address of the original stream. The default value is NULL.

Set the Inject Stream (injectStream)

public Builder injectStream(String url, int width, int height)

In the Builder class, this method injects a stream to the current channel.

Name Description
url Address of the stream to be injected to the channel.
width Width of the stream. N/A, set as 0 for now.
height Height of the stream. N/A, set as 0 for now.

Add Extra Information (extraInfo)

public Builder extraInfo(String optionalInfo)
Name Description
optionalInfo Reserved Field. The default value is NULL.

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 (such as 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 the 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 assigns one automatically.

Name Description
channel The channel name.
uid

User ID.

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

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

Rejoin Channel Callback (onRejoinChannelSuccess)

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

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

Name Description
channel Channel name.
uid User ID.
elapsed Time elapsed (ms) 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 SDK runtime of the SDK. In most cases, the application can ignore the warnings reported by the SDK because the SDK can usually fix the issue and resume running. For instance, the SDK may report an ERR_OPEN_CHANNEL_TIMEOUT warning upon disconnection with the server and attempts to reconnect.

Name Description
warn 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 SDK runtime.

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

Name Description
err

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

Leave a 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, 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. The definition of routing is listed as follows:

public static final int AUDIO_ROUTE_DEFAULT = -1;
public static final int AUDIO_ROUTE_HEADSET = 0;
public static final int AUDIO_ROUTE_EARPIECE = 1;
public static final int AUDIO_ROUTE_HEADSETNOMIC = 2;
public static final int AUDIO_ROUTE_SPEAKERPHONE = 3;
public static final int AUDIO_ROUTE_LOUDSPEAKER = 4;
public static final int AUDIO_ROUTE_HEADSETBLUETOOTH = 5;

Audio Quality Callback (onAudioQuality)

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

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

Name Description
uid User ID of the speaker.
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 (ms).
lost Packet loss rate (%).

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 the 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 User ID.
elapsed Time delay (ms) from calling joinChannel until this callback is triggered.

Other User is 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 detections, therefore we recommend using signaling for reliable offline detection.

Name Description
uid User ID.
reason Reasons for user going offline:
  • USER_OFFLINE_QUIT(0): User has quit the call.
  • USER_OFFLINE_DROPPED(1): 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 the Audio Callback (onUserMuteAudio)

public void onUserMuteAudio( int uid, boolean muted );

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

Note

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

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

RtcEngine Statistics Callback (onRtcStats)

public void onRtcStats( RtcStats stats )

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

Name Description
stats Refer to the description of RtcStats 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 after you have called enableLastmileTest().

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

Channel 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 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 transmission 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 receiving 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.

Connection Banned Callback (onConnectionBanned)

public void onConnectionBanned()

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

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 (pixels) of the video stream.
height Height (pixels) of the video stream.
elapsed Time elapsed (ms) 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 (pixels) of the video stream.
height Height (pixels) of the video stream.
elapsed Time elapsed (ms) 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 (pixels) of the video stream.
height Height (pixels) of the video stream.
elapsed Time elapsed (ms) 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.

Note

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

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.

Note

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

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 (ms).
  • receivedBitrate: Data receiving bitrate (kbps).
  • receivedFrameRate: Data receiving frame rate (fps).
  • rxStreamType: High Video Stream or Low Video Stream.

Camera Ready Callback (onCameraReady)

public void onCameraReady()

This callback indicates that the camera is turned on and ready to capture video. If the camera fails to turn on, handle the error in the onError() method.

Video Stopped Callback (onVideoStopped)

public void onVideoStopped()

This callback indicates that the video has 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.

Video Stream Type Switched (onApiCallExecuted)

public void onApiCallExecuted(String api, int error)

This callback indicates whether the video stream type is switched.

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

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

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

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

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

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

Token Expired Callback (onRequestToken)

public void onRequestToken();

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

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

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

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.

User Role Changed Callback (onClientRoleChanged)

public void onClientRoleChanged(int oldRole, int newRole)

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

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

Camera Focus Area Changed (onCameraFocusAreaChanged)

public void onCameraFocusAreaChanged (Rect rect){}

This callback is triggered when the camera focus area has changed.
Name Description
rect The rectangle area in the camera zoom that specifies the focus area
Is this page helpful?