This document is provided for the C# programming language with the following classes:

IRtcEngineForGaming Abstract Class

Create an Engine Instance

Get an Engine Instance (GetEngine)

public static IRtcEngineForGaming GetEngine (string appId);

This method gets an engine instance. If none exists, it creates an instance. Once the API is executed successfully, it returns the IRtcEngineForGaming instance (not null).

Name Description
appId App ID, see Get an App ID

Query an Engine Instance (QueryEngine)

puiblic static IRtcEngineForGaming QueryEngine();

This method queries an engine instance. Unlike GetEngine, QueryEngine will not create a new instance if none exists.

Implement the Voice Function

Set the Channel Profile (SetChannelProfile)

public abstract int SetChannelProfile(CHANNEL_PROFILE 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.

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

The channel profile. Choose from the following:

  • CHANNEL_PROFILE _GAME_FREEMODE = 2: Free Mode
  • CHANNEL_PROFILE _GAME_COMMANDMODE = 3: Command Mode
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Client Role (SetClientRole)

public abstract int SetClientRole(CLIENT_ROLE role);

This method sets the user role before joining a channel, and allows you to switch the user role after joining a channel.

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

Name Description
role

User role in a command-mode channel:

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

Once set, only the host in the channel can talk, not the audience.

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

Join a Channel (JoinChannel)

public abstract int JoinChannel (string token, string channelName, string optionalInfo, uint 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.

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

Name Description
token

A Token generated by the application.

This parameter is optional if the user uses a static App ID. In this case, pass 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. 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): Invalid argument
    • ERR_NOT_READY (-3): Initiazation failed

Enable the Audio Mode (EnableAudio)

public abstract int EnableAudio();

This method enables the audio mode, which is enabled by default.

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

Disable the Audio Mode (DisableAudio)

public abstract int DisableAudio();

This method disables the audio mode.

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

Leave a Channel (LeaveChannel)

public abstract int LeaveChannel();
Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Audio Route

Set the Default Audio Route to Speakerphone (setDefaultAudioRouteToSpeakerphone)

public int SetDefaultAudioRouteToSpeakerphone(bool speakerphone)

This method sets the default audio route to speakerphone or earpiece.

Once a headset is plugged in or bluetooth is connected, the audio route will be changed accordingly. Once removing the headset or disconnecting bluetooth, the audio route will be the default value.

Name Description
defaultToSpeaker
  • True: sets the default audio route to speakerphone
  • False: sets the default audio route to earpiece
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

This method only works in audio mode.

The original default value for audio route is as follows:

Channel Mode Original Default Audio Route
Free Talk Earpiece
Command Speakerphone

Set the Audio Route to Speakerphone (setEnableSpeakerphone)

public int SetEnableSpeakerphone (bool speakerphone)

This method sets the audio route to speakerphone. The action, that a headset is plugged in or bluetooth is connected, does not affect the audio route.

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

Name Description
enabled
  • True:
    • If this API is called after a user joins a channel, the audio route of the user will be the speakerphone.
    • If this API is called before a user joins a channel, when the user joins a channel, the audio route of the user will be the speakerphone.
  • False: use the default audio route value. See setDefaultAudioRouteToSpeakerphone for details.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Check Whether Audio Route is Set to Speakerphone (isSpeakerphoneEnabled)

public bool IsSpeakerphoneEnabled()

This method checks whether the audio route is set to speakerphone.

The method is only valid on Unity for iOS and Unity for Android.

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

The method is only valid on Unity for Windows.

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 abstract int EnableAudioVolumeIndication (int interval, int smooth);

This method enables or disables the audio volume indication.

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

Time interval between two consecutive volume indications.

  • <=0 : Disables the volume indication.
  • >0: Volume indication interval (ms). Recommend setting it to a minimum of 200 ms.
smooth Smoothing factor. Recommended default value is 3.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute the Audio and Video Stream

Mute the Local Audio Stream (MuteLocalAudioStream)

public abstract int MuteLocalAudioStream (bool mute);

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

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

Mute all Remote Audio Streams (MuteAllRemoteAudioStreams)

public abstract int MuteAllRemoteAudioStreams (bool mute);

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

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

Mute a Remote Audio Stream (MuteRemoteAudioStream)

public abstract int MuteRemoteAudioStream (uint uid, bool mute);

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

Name Description
uid User ID of the user whose audio stream is to be muted.
muted
  • True: Mutes the user’s audio stream.
  • False: Unmutes the user’s audio stream.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Get the SDK Version (GetSdkVersion)

public static string GetSdkVersion ()

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

Get the Error Description (GetErrorDescription)

public static string GetErrorDescription (int code)

This method returns the error code when an error is detected during SDK runtime.

Audio Mixing

Start Audio Mixing (StartAudioMixing)

public abstract int StartAudioMixing (string filePath, bool loopback, bool replace, int cycle, int playTime = 0);

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

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

Name Description
filePath

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

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

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

Number of loop playbacks:

  • Positive integer: Number of loop playbacks.
  • -1: Infinite loop.
playTime

Start time (ms) of the audio file to play.

0 means from the beginning.

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

Stop Audio Mixing (StopAudioMixing)

public abstract int StopAudioMixing();

This method stops 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.

Pause Audio Mixing (PauseAudioMixing)

public abstract 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 abstract 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 the Audio Mixing Volume (AdjustAudioMixingVolume)

public abstract int AdjustAudioMixingVolume (int volume);

This method adjusts the volume during audio mixing. Call this API when you are in the 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 abstract int GetAudioMixingDuration();

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

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

Get the Current Audio Position (GetAudioMixingCurrentPosition)

public abstract int GetAudioMixingCurrentPosition();

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

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

Recording

Start an Audio Recording (StartAudioRecording)

public abstract int StartAudioRecording(string filePath);

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
  • .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 joining a channel. The recording automatically stops when the LeaveChannel method is called.

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

Stop an Audio Recording (StopAudioRecording)

public abstract int StopAudioRecording();

This method stops recording on the client.

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

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

Adjust the Recording Volume (AdjustRecordingSignalVolume)

public abstract int AdjustRecordingSignalVolume (int volume);

This method adjusts the recording volume.

Name Description
volume

Recording volume, ranges from 0~400:

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

Adjust the Playback Volume (AdjustPlaybackSignalVolume)

public abstract 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 heap overflow protection
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

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

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.

Retrieve the Current Call ID (GetCallId)

public string GetCallId()
Name Description
Return Value Current call ID.

Rate the Call (Rate)

public int Rate(string callId, int rating, string desc)

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

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

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

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.

Pause the Audio (Pause)

public void Pause ()

This method pauses the audio. Ffor example, when using background mode, you can call this API to pause the audio.

Resume the Audio (Resume)

public void Resume ()

This method resumes the paused audio.

Get the Message Count (getMessageCount)

public int GetMessageCount ()

This method gets the number of messages in the message queue.

Destroy an Engine Instance (Destroy)

public static void Destroy()

This method releases all the resources used by the Agora SDK. This is useful for applications that occassionaly 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.

Implement the Video Function

Before you implement the video function, read Implement the Voice Function. The basic video function is based on the APIs listed in Implement the Voice Function.

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 called before entering the 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 the 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, bool swapWidthAndHeight)

This method sets the video encoding profile. Each profile includes a set of parameters such as resolution, frame rate, and bitrate. When the camera does not support the specified resolution, the SDK 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 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.

  • 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 Video Profile Definition for details.
swapWidthAndHeight

Whether to swap the width and height of the stream:

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

Video Profile Definition

Video Profile Enum Value Resolution (Width x Height) Frame Rate (fps) Bitrate (kbit/s)
120P 0 160 x 120 15 65
120P_3 2 120 x 120 15 50
180P 10 320 x 180 15 140
180P_3 12 180 x 180 15 100
180P_4 13 240 x 180 15 120
240P 20 320 x 240 15 200
240P_3 22 240 x 240 15 140
240P_4 24 424 x 240 15 220
360P 30 640 x 360 15 400
360P_3 32 360 x 360 15 260
360P_4 33 640 x 360 30 600
360P_6 35 360 x 360 30 400
360P_7 36 480 x 360 15 320
360P_8 37 480 x 360 30 490
360P_9 38 640 x 360 15 800
360P_10 39 640 x 360 24 800
360P_11 100 640 x 360 24 1000
480P 40 640 x 480 15 500
480P_3 42 480 x 480 15 400
480P_4 43 640 x 480 30 750
480P_6 45 480 x 480 30 600
480P_8 47 848 x 480 15 610
480P_9 48 848 x 480 30 930
720P 50 1280 x 720 15 1130
720P_3 52 1280 x 720 30 1710
720P_5 54 960 x 720 15 910
720P_6 55 960 x 720 30 1380
1080P 60 1920 x 1080* [1] 15 2080
1080P_3 62 1920 x 1080* [1] 30 3150
1080P_5 64 1920 x 1080* [1] 60 4780

[1] Whether the video can achieve 1080p resolution depends on the performance and capabilities of the device. Devices with lower performance may experience low frame rates when using 1080p. Agora will optimize the video for lower-end devices in future releases. Contact support@agora.io for details.

Enable Dual-stream Mode (EnableDualStreamMode)

public int EnableDualStreamMode(bool enabled)

This method sets the stream mode: Single- (default) or dual-stream, which is only applicable when you set the channel profile as command mode when calling setChannelProfile.

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)

public int SetRemoteVideoStreamType(uint uid, int 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. This method allows the application to adjust the corresponding video stream type according to the size of the video windows to save bandwidth and resources.

The Agora SDK receives the high-video stream by default. 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 resolutions of the high-video stream are 1:1, 4:3, and 16:9. The low-video stream has the same aspect ratio:

Resolution Frame Rate Keyframe Interval Bitrate (kbit/s)
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 the users to set the video preferences.

Name Description
preferFrameRateOverImageQuality

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.

Disable the Local Video (EnableLocalVideo)

public int EnableLocalVideo (bool 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.

Start the Video Preview (StartPreview)

public int StartPreview ()

This method starts the local video preview.

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

Stop the Video Preview (StopPreview)

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

Switch Between Front and Back Cameras (SwitchCamera)

public int SwitchCamera()

This method switches between front and back cameras.

The method is only valid on Unity for iOS and Unity for Android.

Enable the Video Observer (EnableVideoObserver)

public int EnableVideoObserver ()

This method sends the video pictures directly to the app instead of to the traditional view renderer.

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

Disable the Video Observer (DisableVideoObserver)

public int DisableVideoObserver ()

This method disables sending video directly to the app.

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

Mute the Local Video Stream (MuteLocalVideoStream)

public int MuteLocalVideoStream(bool mute)

This method enables/disables sending local video streams to the network. When set to True, this method does not disable the camera and thus does not affect getting 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(bool mute)

This method enables/disables playing all remote users’ video streams. 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(uint uid, bool mute)

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

Name Description
uid User ID of the specified user.
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.

Trigger an SDK Event (Poll)

public abstract void Poll ();

This method triggers an SDK event according to vertical synchronization, such as Update (Unity3D).

Encryption

Enable Built-in Encryption (setEncryptionSecret)

public int SetEncryptionSecret(string secret)

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

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

Set the Built-in Encryption Mode (SetEncryptionMode)

public int SetEncryptionMode(string encryptionMode)

The Agora SDK supports built-in encryption in AES-128-XTS mode by default. 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.

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 set to a NUL string, the encryption is in “aes-128-xts” by default.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Others

Set the Log Filter (SetLogFilter)

public abstract int SetLogFilter (LOG_FILTER filter);

This method sets the SDK output log filter.

Name Description
filter

Sets the levels of the filters.

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

Set a Log File (SetLogFile)

public abstract int SetLogFile (string filePath);

This method sets the path to save the log file.

Name Description
filePath Path to save the log file.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Renew Token (RenewToken)

public override int RenewToken (string token);

This method updates the Token.

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

  • The onError callback reports the ERR_TOKEN_EXPIRED (109) error, or
  • The onRequestToken callback reports the ERR_TOKEN_EXPIRED (109) error, or
  • The user receives the onTokenPrivilegeWillExpire callback.

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

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

Callbacks

Join Channel Callback (JoinChannelSuccessHandler)

public delegate void JoinChannelSuccessHandler (string channelName, uint uid, int elapsed);

This callback is triggered when the user has joined the channel successfully.

The channel ID is assigned based on the channel name specified in the JoinChannel API. If the User ID is not specified when JoinChannel is called, the server assigns 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 assigned by the Agora server.

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

Rejoin Channel Callback (ReJoinChannelSuccessHandler)

public delegate void ReJoinChannelSuccessHandler (string channelName, uint uid, int elapsed);

This callback is triggered when the user has re-joined the channel successfully.

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

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.

Connection Interrupted Callback (ConnectionInterruptedHandler)

public delegate void ConnectionInterruptedHandler ();

This callback indicates that the connection is lost between the SDK and the server. Once the connection is lost, the SDK tries to reconnect it repeatedly until the application calls LeaveChannel.

Connection Lost Callback (ConnectionLostHandler)

public delegate void ConnectionLostHandler ();

When the connection between the SDK and server is lost, the ConnectionInterruptedHandler callback is triggered and the SDK reconnects automatically. If the reconnection fails within a certain period (10 seconds by default), the callback ConnectionLostHandler is triggered. The SDK continues to reconnect until the application calls leaveChannel.

Other User Joined Channel Callback (UserJoinedHandler)

public delegate void UserJoinedHandler (uint uid, int elapsed);

This callback is triggered when the other user has joined the channel.

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 interval (ms) from calling JoinChannel() until this callback is triggered.

Other User Offline Callback (UserOfflineHandler)

public delegate void UserOfflineHandler (uint uid, USER_OFFLINE_REASON 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). If no data package is received from the user in 15 seconds, the SDK assumes the user is offline. Sometimes a weak network connection may lead to false detections; therefore, it is recommend to use signaling for reliable offline detection.

Name Description
uid User ID.
reason

This callback is triggered when:

  • USER_OFFLINE_QUIT: User has quit the call.
  • USER_OFFLINE_DROPPED: The SDK timed out and has dropped offline because it has not received a data package within a certain period.

If a user quits the call and the message is not passed to the SDK (due to an unreliable channel), the SDK assumes the event has timed out.

Leave Channel Callback (LeaveChannelHandler)

public delegate void LeaveChannelHandler (RtcStats stats);

This callback is triggered when the user left the channel.

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

Name Description
stat

The statistics about the call.

  • duration: Call duration (s).
  • txBytes: Total number of bytes transmitted.
  • rxBytes: Total number of bytes received.
  • txKBitRate: Transmission bitrate (kbit/s).
  • rxKBitRate: Receive bitrate (kbit/s).
struct RtcStats {
    unsigned int duration;
    unsigned int txBytes;
    unsigned int rxBytes;
    unsigned short txKBitRate;
    unsigned short rxKBitRate;
  };

Audio Volume Indication Callback (VolumeIndicationHandler)

public delegate void VolumeIndicationHandler (AudioVolumeInfo[] speakers, int speakerNumber, int totalVolume);

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

Name Description
speakers

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

  • uid: User ID of the speaker.
  • volume: Volume of the speaker, between 0 (lowest volume) to 255 (highest volume).
speakerNumber Number of the speakers
totalVolume Total volume after audio mixing between 0 (lowest volume) to 255 (highest volume).

Other User Muted Audio Callback (UserMutedHandler)

public delegate void UserMutedHandler (uint uid, bool 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.

Warning Occurred Callback (SDKWarningHandler)

public delegate void SDKWarningHandler (int warn, string msg);

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

For detailed warning codes, refer to Error Codes and Warning Codes.

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

Error Occurred Callback (SDKErrorHandler)

public delegate void SDKErrorHandler (int error, string msg);

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

For detailed error codes, see Error Codes and Warning Codes.

Name Description
err The error code.
msg The error message.

RtcEngine Statistics Callback (RtcStatsHandler)

public delegate void RtcStatsHandler (RtcStats stats);

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

Audio Mixing Playback Finished (AudioMixingFinishedHandler)

public delegate void AudioMixingFinishedHandler ();

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

Audio Route Changed Callback (AudioRouteChangedHandler)

public delegate void AudioRouteChangedHandler (AUDIO_ROUTE route);

The SDK notifies the application that the audio route is changed, and is switched to an earpiece, speakerphone, headset, or bluetooth device.

Token Expired Callback (RequestTokenHandler)

public delegate void RequestTokenHandler ();

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

This callback notifies the application the need to generate a new Token, and calls renewTokento renew the Token.

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

First Remote Video Frame Received and Decoded Callback (OnFirstRemoteVideoDecodedHandler)

public delegate void OnFirstRemoteVideoDecodedHandler (uint 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 (ms) from calling joinChannel until this callback is triggered.

Video Size Changed Callback (OnVideoSizeChangedHandler)

public delegate void OnVideoSizeChangedHandler (uint uid, int width, int height, int elapsed);

This method is triggered when the video size of the specific user is changed.

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

Client Role Changed Callback (onClientRoleChangedHandler)

public delegate void onClientRoleChangedHandler(int oldRole, int newRole)

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

Name Description
oldRole The role that you switched from
newRole The role that you are now in

User Video Muted Callback (OnUserMuteVideoHandler)

public delegate void OnUserMuteVideoHandler (uint uid, bool muted);

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

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: The remote user mute the video
  • False: The remote user unmute the video

IAudioEffectManager Interface Class

Set Voice-only Mode (setVoiceOnlyMode)

int setVoiceOnlyMode(bool enable);

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

Name Description
enable

True: Enables voice-only mode.

False: Disables voice-only mode.

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

Set the Voice Position of the Remote User (SetRemoteVoicePosition)

int SetRemoteVoicePosition(uint uid, double pan, double gain);

Sets the voice position of the remote user.

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

Name Description
uid User ID of the remote user.
pan

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

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

gain

Return Value

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

Default value is 100.0. The smaller the number, the lower the volume.

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

Set the Local Voice Pitch (SetLocalVoicePitch)

int SetLocalVoicePitch (double pitch);

This method changes the voice pitch of the local speaker.

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

Get the Audio Effect Volume (GetEffectsVolume)

double GetEffectsVolume();

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

Set the Audio Effect Volume (SetEffectsVolume)

int SetEffectsVolume(double volume)

This method sets the volume of the audio effects.

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

Play the Audio Effect (PlayEffect)

int PlayEffect (int soundId, String filePath,
              bool loop = false,
              double pitch = 1.0D,
              double pan = 0.0D,
              double gain = 100.0D
);

This method plays the audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID. [2]
filePath Absolute path of the audio effect file.
loop

Sets whether to play the audio effect in loops:

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

Sets whether to change the frequency of the audio effect.

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

The smaller the value, the lower the frequency.

pan

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

  • 0: Audio effect shows right ahead; stereo effect.
  • -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 value, and lower the volume.

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

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

Stop Playing the Audio Effect (StopEffect)

int StopEffect(int soundId);

This method stops playing a specific audio effect.

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

Stop Playing all Audio Effects (stopAllEffects)

int stopAllEffects();

This method stops playing all the audio effects.

Preload an Audio Effect (preloadEffect)

int PreloadEffect(int soundId, String filePath);

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

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
filePath Path and file name of the effect audio file to be preloaded.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Release an Audio Effect (unloadEffect)

int unloadEffect(int soundId);

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

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

Pause an Audio Effect (pauseEffect)

virtual int pauseEffect(int soundId)

This method pauses a specific audio effect.

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

Pause all Audio Effects (pauseAllEffects)

int pauseAllEffects();

This method pauses all audio effects.

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

Resume an Audio Effect (resumeEffect)

int resumeEffect(int soundId);

This method resumes playing a specific audio effect.

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

Resume all Audio Effects (resumeAllEffects)

int resumeAllEffects();

This method resumes all audio effects.

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

Error Codes

See Error Codes and Warning Codes.