Voice SDK v3.7.1 API Reference for Unity
Public Member Functions | Static Public Member Functions | List of all members
agora_gaming_rtc.IRtcEngine Class Reference

Inherits IRtcEngineNative.

Public Member Functions

int  SetChannelProfile (CHANNEL_PROFILE profile)
 
int  SetClientRole (CLIENT_ROLE_TYPE role)
 
int  SetLogFilter (LOG_FILTER filter)
 
int  SetLogFile (string filePath)
 
int  JoinChannel (string channelName, string info="", uint uid=0)
 
int  JoinChannelByKey (string channelKey, string channelName, string info="", uint uid=0)
 
int  RenewToken (string token)
 
int  LeaveChannel ()
 
int  SetParameters (string parameters)
 
string  GetCallId ()
 
int  Rate (string callId, int rating, string desc="")
 
int  Complain (string callId, string desc="")
 
int  EnableAudio ()
 
int  DisableAudio ()
 
int  MuteLocalAudioStream (bool mute)
 
int  MuteAllRemoteAudioStreams (bool mute)
 
int  MuteRemoteAudioStream (uint uid, bool mute)
 
int  SetEnableSpeakerphone (bool speakerphone)
 
int  SetDefaultAudioRouteToSpeakerphone (bool speakerphone)
 
bool  IsSpeakerphoneEnabled ()
 
int  SwitchCamera ()
 
int  SetVideoProfile (VIDEO_PROFILE_TYPE profile, bool swapWidthAndHeight=false)
 
int  MuteLocalVideoStream (bool mute)
 
int  MuteAllRemoteVideoStreams (bool mute)
 
int  MuteRemoteVideoStream (uint uid, bool mute)
 
int  EnableDualStreamMode (bool enabled)
 
int  SetEncryptionMode (string encryptionMode)
 
int  SetEncryptionSecret (string secret)
 
int  CreateDataStream (bool reliable, bool ordered)
 
int  CreateDataStream (DataStreamConfig config)
 
int  SendStreamMessage (int streamId, byte[] data)
 
int  SetSpeakerphoneVolume (int volume)
 
int  SetVideoQualityParameters (bool preferFrameRateOverImageQuality)
 
int  StartEchoTest ()
 
int  StartEchoTest (int intervalInSeconds)
 
int  StartEchoTest (EchoTestConfiguration config)
 
int  StopEchoTest ()
 
int  StartLastmileProbeTest (LastmileProbeConfig lastmileProbeConfig)
 
int  StopLastmileProbeTest ()
 
int  AddVideoWatermark (RtcImage rtcImage)
 
int  AddVideoWatermark (string watermarkUrl, WatermarkOptions watermarkOptions)
 
int  ClearVideoWatermarks ()
 
int  SetRemoteVideoStreamType (uint uid, REMOTE_VIDEO_STREAM_TYPE streamType)
 
int  SetMixedAudioFrameParameters (int sampleRate, int samplesPerCall)
 
int  SetAudioMixingPosition (int pos)
 
int  EnableAudioVolumeIndication (int interval, int smooth, bool report_vad=false)
 
int  AdjustRecordingSignalVolume (int volume)
 
int  AdjustPlaybackSignalVolume (int volume)
 
int  StartAudioMixing (string filePath, bool loopback, bool replace, int cycle)
 
int  StartAudioMixing (string filePath, bool loopback, bool replace, int cycle, int startPos)
 
int  StopAudioMixing ()
 
int  PauseAudioMixing ()
 
int  ResumeAudioMixing ()
 
int  AdjustAudioMixingVolume (int volume)
 
int  GetAudioMixingDuration ()
 
int  GetAudioMixingDuration (string filePath)
 
int  GetAudioMixingCurrentPosition ()
 
int  StartAudioRecording (string filePath, AUDIO_RECORDING_QUALITY_TYPE quality)
 
int  StartAudioRecording (string filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality)
 
int  StopAudioRecording ()
 
IAudioEffectManager  GetAudioEffectManager ()
 
IAudioRecordingDeviceManager  GetAudioRecordingDeviceManager ()
 
IAudioPlaybackDeviceManager  GetAudioPlaybackDeviceManager ()
 
IVideoDeviceManager  GetVideoDeviceManager ()
 
IAudioRawDataManager  GetAudioRawDataManager ()
 
IVideoRawDataManager  GetVideoRawDataManager ()
 
IScreenCaptureManager  GetScreenCaptureManager ()
 
IMediaRecorder  GetMediaRecorder ()
 
int  EnableVideo ()
 
int  DisableVideo ()
 
int  EnableLocalVideo (bool enabled)
 
int  EnableLocalAudio (bool enabled)
 
int  StartPreview ()
 
int  StopPreview ()
 
int  EnableVideoObserver ()
 
int  DisableVideoObserver ()
 
int  SetDefaultMuteAllRemoteAudioStreams (bool mute)
 
int  SetDefaultMuteAllRemoteVideoStreams (bool mute)
 
int  EnableLastmileTest ()
 
int  DisableLastmileTest ()
 
CONNECTION_STATE_TYPE  GetConnectionState ()
 
int  SetAudioProfile (AUDIO_PROFILE_TYPE audioProfile, AUDIO_SCENARIO_TYPE scenario)
 
int  SetVideoEncoderConfiguration (VideoEncoderConfiguration configuration)
 
int  AdjustAudioMixingPlayoutVolume (int volume)
 
int  AdjustAudioMixingPublishVolume (int volume)
 
int  SetVolumeOfEffect (int soundId, int volume)
 
int  SetRecordingAudioFrameParameters (int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall)
 
int  SetPlaybackAudioFrameParameters (int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall)
 
int  SetLocalPublishFallbackOption (STREAM_FALLBACK_OPTIONS option)
 
int  SetRemoteSubscribeFallbackOption (STREAM_FALLBACK_OPTIONS option)
 
int  SetRemoteDefaultVideoStreamType (REMOTE_VIDEO_STREAM_TYPE remoteVideoStreamType)
 
int  AddPublishStreamUrl (string url, bool transcodingEnabled)
 
int  RemovePublishStreamUrl (string url)
 
int  EnableWebSdkInteroperability (bool enabled)
 
int  SetLiveTranscoding (LiveTranscoding transcoding)
 
int  PushVideoFrame (ExternalVideoFrame externalVideoFrame)
 
int  SetExternalVideoSource (bool enable, bool useTexture=false)
 
int  SetExternalAudioSource (bool enabled, int sampleRate, int channels)
 
int  PushAudioFrame (AudioFrame audioFrame)
 
int  PushAudioFrame (int sourcePos, AudioFrame audioFrame)
 
int  GetAudioMixingPlayoutVolume ()
 
int  GetAudioMixingPublishVolume ()
 
int  EnableSoundPositionIndication (bool enabled)
 
int  SetLocalVoiceChanger (VOICE_CHANGER_PRESET voiceChanger)
 
int  SetLocalVoiceReverbPreset (AUDIO_REVERB_PRESET audioReverbPreset)
 
int  SetLocalVoicePitch (double pitch)
 
int  SetLocalVoiceEqualization (AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain)
 
int  SetLocalVoiceReverb (AUDIO_REVERB_TYPE reverbKey, int value)
 
int  SetCameraCapturerConfiguration (CameraCapturerConfiguration cameraCaptureConfiguration)
 
int  SetRemoteUserPriority (uint uid, PRIORITY_TYPE userPriority)
 
int  SetLogFileSize (uint fileSizeInKBytes)
 
int  SetExternalAudioSink (bool enabled, int sampleRate, int channels)
 
int  RegisterLocalUserAccount (string appId, string userAccount)
 
int  JoinChannelWithUserAccount (string token, string channelId, string userAccount)
 
int  JoinChannelWithUserAccount (string token, string channelId, string userAccount, ChannelMediaOptions options)
 
UserInfo  GetUserInfoByUserAccount (string account)
 
UserInfo  GetUserInfoByUid (uint uid)
 
int  SetBeautyEffectOptions (bool enabled, BeautyOptions beautyOptions)
 
int  StartScreenCaptureByDisplayId (uint displayId, Rectangle rectangle, ScreenCaptureParameters screenCaptureParameters)
 
int  StartScreenCaptureByScreenRect (Rectangle screenRectangle, Rectangle regionRectangle, ScreenCaptureParameters screenCaptureParameters)
 
int  SetScreenCaptureContentHint (VideoContentHint videoContentHint)
 
int  UpdateScreenCaptureParameters (ScreenCaptureParameters screenCaptureParameters)
 
int  UpdateScreenCaptureRegion (Rectangle rectangle)
 
int  StopScreenCapture ()
 
int  EnableLoopbackRecording (bool enabled, string deviceName)
 
int  SetAudioSessionOperationRestriction (AUDIO_SESSION_OPERATION_RESTRICTION restriction)
 
int  StartChannelMediaRelay (ChannelMediaRelayConfiguration mediaRelayConfiguration)
 
int  UpdateChannelMediaRelay (ChannelMediaRelayConfiguration mediaRelayConfiguration)
 
int  StopChannelMediaRelay ()
 
int  SwitchChannel (string token, string channelId)
 
int  SetMultiChannelWant (bool multiChannelWant)
 
int  SetMirrorApplied (bool wheatherApply)
 
int  SetInEarMonitoringVolume (int volume)
 
int  StartScreenCaptureByWindowId (int windowId, Rectangle regionRect, ScreenCaptureParameters screenCaptureParameters)
 
int  EnableInEarMonitoring (bool enabled)
 
int  AdjustUserPlaybackSignalVolume (uint uid, int volume)
 
AgoraChannel  CreateChannel (string channelId)
 
int  EnableFaceDetection (bool enable)
 
int  SetAudioMixingPitch (int pitch)
 
int  EnableEncryption (bool enabled, EncryptionConfig encryptionConfig)
 
int  EnableRemoteSuperResolution (uint userId, bool enable)
 
int  SetClientRole (CLIENT_ROLE_TYPE role, ClientRoleOptions clientRoleOptions)
 
int  SetVoiceBeautifierPreset (VOICE_BEAUTIFIER_PRESET preset)
 
int  SetAudioEffectPreset (AUDIO_EFFECT_PRESET preset)
 
int  SetAudioEffectParameters (AUDIO_EFFECT_PRESET preset, int param1, int param2)
 
int  SendCustomReportMessage (string id, string category, string events, string label, int value)
 
int  SetVoiceBeautifierParameters (VOICE_BEAUTIFIER_PRESET preset, int param1, int param2)
 
int  EnableDeepLearningDenoise (bool enable)
 
int  JoinChannel (string token, string channelId, string info, uint uid, ChannelMediaOptions options)
 
int  SwitchChannel (string token, string channelId, ChannelMediaOptions options)
 
int  SetVoiceConversionPreset (VOICE_CONVERSION_PRESET preset)
 
int  SetCloudProxy (CLOUD_PROXY_TYPE proxyType)
 
int  AdjustLoopbackRecordingSignalVolume (int volume)
 
int  StartAudioRecording (AudioRecordingConfiguration config)
 
int  EnableVirtualBackground (bool enabled, VirtualBackgroundSource source)
 
int  SetCameraTorchOn (bool on)
 
bool  IsCameraTorchSupported ()
 
int  SetExternalAudioSourceVolume (int sourcePos, int volume)
 
int  SetAudioMixingPlaybackSpeed (int speed)
 
int  SelectAudioTrack (int index)
 
int  GetAudioTrackCount ()
 
int  SetAudioMixingDualMonoMode (AUDIO_MIXING_DUAL_MONO_MODE mode)
 
int  PauseAllChannelMediaRelay ()
 
int  ResumeAllChannelMediaRelay ()
 
int  GetAudioFileInfo (string filePath)
 
int  TakeSnapshot (string channel, uint uid, string filePath)
 
int  SetLowlightEnhanceOptions (bool enabled, LowLightEnhanceOptions options)
 
int  SetVideoDenoiserOptions (bool enabled, VideoDenoiserOptions options)
 
int  SetColorEnhanceOptions (bool enabled, ColorEnhanceOptions options)
 
int  SetAVSyncSource (string channelId, uint uid)
 
int  StartRtmpStreamWithoutTranscoding (string url)
 
int  StartRtmpStreamWithTranscoding (string url, LiveTranscoding transcoding)
 
int  UpdateRtmpTranscoding (LiveTranscoding transcoding)
 
int  StopRtmpStream (string url)
 
int  EnableLocalVoicePitchCallback (int interval)
 
int  SetScreenCaptureScenario (int screenScenario)
 
int  SetCameraZoomFactor (float factor)
 
float  GetCameraMaxZoomFactor ()
 
bool  IsCameraZoomSupported ()
 
bool  IsCameraFocusSupported ()
 
bool  IsCameraExposurePositionSupported ()
 
bool  IsCameraAutoFocusFaceModeSupported ()
 
int  SetCameraFocusPositionInPreview (float positionX, float positionY)
 
int  SetCameraExposurePosition (float positionXinView, float positionYinView)
 
int  SetCameraAutoFocusFaceModeEnabled (bool enabled)
 

Static Public Member Functions

static string  GetSdkVersion ()
 
static string  GetErrorDescription (int code)
 
static IRtcEngine  GetEngine (string appId)
 
static IRtcEngine  GetEngine (RtcEngineConfig engineConfig)
 
static IRtcEngine  getEngine (string appId)
 
static void  Destroy ()
 
static IRtcEngine  QueryEngine ()
 

Detailed Description

The definition of IRtcEngine.

Member Function Documentation

◆ AddPublishStreamUrl()

int agora_gaming_rtc.IRtcEngine.AddPublishStreamUrl ( string  url,
bool  transcodingEnabled 
)

Publishes the local stream to a specified CDN streaming URL. (CDN live only.)

Deprecated:
This method is deprecated as of v3.6.1.1. See Release Notes for an alternative solution.

The SDK returns the result of this method call in the OnStreamPublishedHandler callback.

The AddPublishStreamUrl method call triggers the OnRtmpStreamingStateChangedHandler callback on the local client to report the state of adding a local stream to the CDN.

Note
  • Ensure that the user joins the channel before calling this method.
  • Ensure that you enable the RTMP Converter service before using this function.
  • This method adds only one stream CDN streaming URL each time it is called.
  • Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.
Parameters
url The CDN streaming URL in the RTMP or RTMPS format. The maximum length of this parameter is 1024 bytes. The CDN streaming URL must not contain special characters, such as Chinese language characters.
transcodingEnabled Sets whether transcoding is enabled/disabled:
  • true: Enable transcoding. To transcode the audio or video streams when publishing them to CDN live, often used for combining the audio and video streams of multiple hosts in CDN live. If you set this parameter as true, ensure that you call the SetLiveTranscoding method before this method.
  • false: Disable transcoding.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_INVALID_ARGUMENT(-2): The CDN streaming URL is null or has a string length of 0.
    • ERR_NOT_INITIALIZED(-7): You have not initialized the RTC engine when publishing the stream.

◆ AddVideoWatermark() [1/2]

int agora_gaming_rtc.IRtcEngine.AddVideoWatermark ( RtcImage  rtcImage )

Adds a watermark image to the local video or CDN live stream.

Deprecated:
This method is deprecated from v2.9.1. Use AddVideoWatermark instead.

This method adds a PNG watermark image to the local video stream for the capturing device, channel audience, and CDN live audience to view and capture.

To add the PNG file to the CDN live publishing stream, see the SetLiveTranscoding method.

Note
  • The URL descriptions are different for the local video and CDN live streams:
    • In a local video stream, url in RtcImage refers to the absolute path of the added watermark image file in the local video stream.
    • In a CDN live stream, url in RtcImage refers to the URL address of the added watermark image in the CDN live broadcast.
  • The source file of the watermark image must be in the PNG file format. If the width and height of the PNG file differ from your settings in this method, the PNG file will be cropped to conform to your settings.
  • The Agora RTC SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one.
Parameters
rtcImage The watermark image to be added to the local video stream. See RtcImage.
Returns
  • 0: Success.
  • < 0: Failure.

◆ AddVideoWatermark() [2/2]

int agora_gaming_rtc.IRtcEngine.AddVideoWatermark ( string  watermarkUrl,
WatermarkOptions  watermarkOptions 
)

Adds a watermark image to the local video.

This method adds a PNG watermark image to the local video in the interactive live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the capturing device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one.

The watermark position depends on the settings in the SetVideoEncoderConfiguration method:

Note
  • Ensure that you have called the EnableVideo method to enable the video module before calling this method.
  • If you only want to add a watermark image to the local video for the audience in the CDN live broadcast channel to see and capture, you can call this method or the SetLiveTranscoding method.
  • This method supports adding a watermark image in the PNG file format only. Supported pixel formats of the PNG image are RGBA, RGB, Palette, Gray, and Alpha_gray.
  • If the dimensions of the PNG image differ from your settings in this method, the image will be cropped or zoomed to conform to your settings.
  • If you have enabled the local video preview by calling the StartPreview method, you can use the visibleInPreview member in the WatermarkOptions class to set whether or not the watermark is visible in preview.
  • If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer.
Parameters
watermarkUrl The local file path of the watermark image to be added. This method supports adding a watermark image from the local absolute or relative file path.
watermarkOptions The watermark's options to be added. See WatermarkOptions for more infomation.
Returns
  • 0: Success.
  • < 0: Failure.

◆ AdjustAudioMixingPlayoutVolume()

int agora_gaming_rtc.IRtcEngine.AdjustAudioMixingPlayoutVolume ( int  volume )

Adjusts the audio mixing volume for local playback.

Note
Ensure that this method is called after StartAudioMixing.
Parameters
volume Audio mixing volume for local playback. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ AdjustAudioMixingPublishVolume()

int agora_gaming_rtc.IRtcEngine.AdjustAudioMixingPublishVolume ( int  volume )

Adjusts the audio mixing volume for publishing (for remote users).

Note
Ensure that this method is called after StartAudioMixing.
Parameters
volume Audio mixing volume for publishing. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ AdjustAudioMixingVolume()

int agora_gaming_rtc.IRtcEngine.AdjustAudioMixingVolume ( int  volume )

Adjusts the volume during audio mixing.

Call this method when you are in a channel.

Note
  • Calling this method does not affect the volume of audio effect file playback invoked by the PlayEffect method.
  • Ensure that this method is called after StartAudioMixing.
Parameters
volume Audio mixing volume. The value ranges between 0 and 100.
  • 0: Mute.
  • 100: Original volume.
Returns
  • 0: Success.
  • < 0: Failure.

◆ AdjustLoopbackRecordingSignalVolume()

int agora_gaming_rtc.IRtcEngine.AdjustLoopbackRecordingSignalVolume ( int  volume )

Adjusts the volume of the signal captured by the sound card.

After calling EnableLoopbackRecording to enable loopback audio capturing, you can call this method to adjust the volume of the signal captured by the sound card.

Note
This method applies to Windows and macOS only.
Parameters
volume The volume of the signal captured by the sound card. The value ranges between 0 and 100, where 0 represents no volume and 100 the original volume.
Returns
  • 0: Success.
  • < 0: Failure.

◆ AdjustPlaybackSignalVolume()

int agora_gaming_rtc.IRtcEngine.AdjustPlaybackSignalVolume ( int  volume )

Adjusts the playback signal volume of all remote users.

Note
  • This method adjusts the playback signal volume which is mixed volume of all remote users.
  • Since v2.3.2, to mute the local audio playback, call both AdjustPlaybackSignalVolume and AdjustAudioMixingVolume, and set volume as 0.
  • You can call this method either before or after joining a channel.
Parameters
volume the playback signal volume of all remote users. To avoid echoes and improve call quality, Agora recommends setting the value of volume between 0 and 100. If you need to set the value higher than 100, contact suppo.nosp@m.rt@a.nosp@m.gora..nosp@m.io first.
  • 0: Mute.
  • 100: Original volume.
Returns
  • 0: Success.
  • < 0: Failure.

◆ AdjustRecordingSignalVolume()

int agora_gaming_rtc.IRtcEngine.AdjustRecordingSignalVolume ( int  volume )

Adjusts adjust the capturing signal volume.

Note
You can call this method either before or after joining a channel.
Parameters
volume Recording volume. To avoid echoes and improve call quality, Agora recommends setting the value of volume between 0 and 100. If you need to set the value higher than 100, contact suppo.nosp@m.rt@a.nosp@m.gora..nosp@m.io first.
  • 0: Mute.
  • 100: Original volume.
Returns
  • 0: Success.
  • < 0: Failure.

◆ AdjustUserPlaybackSignalVolume()

int agora_gaming_rtc.IRtcEngine.AdjustUserPlaybackSignalVolume ( uint  uid,
int  volume 
)

Adjusts the playback signal volume of a specified remote user.

Since
v3.0.1

You can call this method as many times as necessary to adjust the playback signal volume of different remote users, or to repeatedly adjust the playback signal volume of the same remote user.

Note
  • Call this method after joining a channel.
  • The playback signal volume here refers to the mixed volume of a specified remote user.
  • This method can only adjust the playback signal volume of one specified remote user at a time. To adjust the playback signal volume of different remote users, call the method as many times, once for each remote user.
Parameters
uid The ID of the remote user.
volume the playback signal volume of the specified remote user. The value ranges from 0 to 100:
  • 0: Mute.
  • 100: Original volume.
Returns
  • 0: Success.
  • < 0: Failure.

◆ ClearVideoWatermarks()

int agora_gaming_rtc.IRtcEngine.ClearVideoWatermarks ( )

Removes the watermark image from the video stream added by the AddVideoWatermark method.

Returns
  • 0: Success.
  • < 0: Failure.

◆ Complain()

int agora_gaming_rtc.IRtcEngine.Complain ( string  callId,
string  desc = "" 
)

Allows a user to complain about the call quality after a call ends.

Note
Ensure that you call this method after joining a channel.
Parameters
callId The ID of the call, retrieved from the GetCallId method.
desc (Optional) The description of the rating, with a string length of less than 800 bytes.
Returns
  • 0: Success.
  • < 0: Failure.

◆ CreateChannel()

AgoraChannel agora_gaming_rtc.IRtcEngine.CreateChannel ( string  channelId )

Creates and gets an AgoraChannel object.

Since
v3.0.1

To join more than one channel, call this method multiple times to create as many AgoraChannel objects as needed, and call the JoinChannel method of each created AgoraChannel object.

After joining multiple channels, you can simultaneously subscribe to streams of all the channels, but publish a stream in only one channel at one time.

Parameters
channelId The unique channel name for an Agora RTC session. It must be in the string format and not exceed 64 bytes in length. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Note
  • This parameter does not have a default value. You must set it.
  • Do not set it as the empty string "". Otherwise, the SDK returns ERR_REFUSED(5).
Returns
  • The AgoraChannel object, if the method call succeeds.
  • null, if the method call fails.
  • ERR_REFUSED(5), if you set channelId as the empty string "".

◆ CreateDataStream() [1/2]

int agora_gaming_rtc.IRtcEngine.CreateDataStream ( bool  reliable,
bool  ordered 
)

Creates a data stream.

Deprecated:
This method is deprecated from v3.3.1. Use the CreateDataStream2 method instead.

Each user can create up to five data streams during the lifecycle of the IRtcEngine.

Note
  • Do not set reliable as true while setting ordered as false.
  • Ensure that you call this method after joining a channel.
Parameters
reliable Sets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds:
  • true: The recipients receive the data stream from the sender within five seconds. If the recipient does not receive the data stream within five seconds, an error is reported to the application.
  • false: There is no guarantee that the recipients receive the data stream within five seconds and no error message is reported for any delay or missing data stream.
ordered Sets whether or not the recipients receive the data stream in the sent order:
  • true: The recipients receive the data stream in the sent order.
  • false: The recipients do not receive the data stream in the sent order.
Returns
  • ≥ 0: The ID of the data stream, if this method call succeeds.
  • < 0: Failure.

◆ CreateDataStream() [2/2]

int agora_gaming_rtc.IRtcEngine.CreateDataStream ( DataStreamConfig  config )

Creates a data stream.

Since
v3.3.1

Each user can create up to five data streams in a single channel.

This method does not support data reliability. If the receiver receives a data packet five seconds or more after it was sent, the SDK directly discards the data.

Parameters
config The configurations for the data stream: DataStreamConfig.
Returns
  • ≥ 0: The ID of the data stream, if this method call succeeds.
  • < 0: Fails to create the data stream.

◆ Destroy()

static void agora_gaming_rtc.IRtcEngine.Destroy ( )
static

Destroys the IRtcEngine instance and releases all resources used by the Agora RTC SDK.

Use this method for apps in which users occasionally make voice or video calls. When users do not make calls, you can free up resources for other operations. Once you call Destroy to destroy the created IRtcEngine instance, you cannot use any method or callback in the SDK any more. If you want to use the real-time communication functions again, you must call GetEngine to Initialize a new IRtcEngine instance.

Note
  • Because Destroy is a synchronous method and the app cannot move on to another task until the execution completes, Agora suggests calling this method in a sub-thread to avoid congestion in the main thread. Besides, you cannot call Destroy in any method or callback of the SDK. Otherwise, the SDK cannot release the resources occupied by the IRtcEngine instance until the callbacks return results, which may result in a deadlock.
  • If you want to create a new IRtcEngine instance after destroying the current one, ensure that you wait till the destroy method completes executing.

◆ DisableAudio()

int agora_gaming_rtc.IRtcEngine.DisableAudio ( )

Disables the audio module.

Note
  • This method affects the internal engine and can be called after the LeaveChannel method. You can call this method either before or after joining a channel.
  • This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the audio engine modules separately:
Returns
  • 0: Success.
  • < 0: Failure.

◆ DisableLastmileTest()

int agora_gaming_rtc.IRtcEngine.DisableLastmileTest ( )

Disables the network connection quality test.

Returns
  • 0: Success.
  • < 0: Failure.

◆ DisableVideo()

int agora_gaming_rtc.IRtcEngine.DisableVideo ( )

Disables the video module.

This method can be called before joining a channel or during a call. If this method is called before joining a channel, the call starts in audio mode. If this method is called during a video call, the video mode switches to the audio mode. To enable the video module, call the EnableVideo method.

A successful DisableVideo method call triggers the OnUserEnableVideoHandler(false) callback on the remote client.

Note
  • To stop getting video raw data, call both DisableVideo and DisableVideoObserver methods.
  • This method affects the internal engine and can be called after the LeaveChannel method.
  • This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the video engine modules separately:
Returns
  • 0: Success.
  • < 0: Failure.

◆ DisableVideoObserver()

int agora_gaming_rtc.IRtcEngine.DisableVideoObserver ( )

Disables the video observer.

This method disables sending video directly to the app.

Note
  • To stop getting video raw data, call both DisableVideo and DisableVideoObserver methods.
  • Call this method after leaving the channel.
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableAudio()

int agora_gaming_rtc.IRtcEngine.EnableAudio ( )

Enables the audio module.

The audio mode is enabled by default.

Note
  • This method affects the audio module and can be called after the LeaveChannel method. You can call this method either before or after joining a channel.
  • This method enables the audio module and takes some time to take effect. Agora recommend using the following API methods to control the audio modules separately:
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableAudioVolumeIndication()

int agora_gaming_rtc.IRtcEngine.EnableAudioVolumeIndication ( int  interval,
int  smooth,
bool  report_vad = false 
)

Enables the reporting of users' volume indication.

This method enables the SDK to regularly report the volume information of the local user who sends a stream and remote users (up to three) whose instantaneous volumes are the highest to the app. Once you call this method and users send streams in the channel, the SDK triggers the OnVolumeIndicationHandler callback at the time interval set in this method.

Note
You can call this method either before or after joining a channel.
Parameters
interval Sets the time interval between two consecutive volume indications:
  • ≤ 0: Disables the volume indication.
  • > 0: Time interval (ms) between two consecutive volume indications. We recommend setting interval > 200 ms. Do not set interval < 10 ms, or the OnVolumeIndicationHandler callback will not be triggered.
smooth Smoothing factor sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The greater the value, the more sensitive the indicator. The recommended value is 3.
report_vad
  • true: Enable the voice activity detection of the local user. Once it is enabled, the vad parameter of the OnVolumeIndicationHandler callback reports the voice activity status of the local user.
  • false: (Default) Disable the voice activity detection of the local user. Once it is disabled, the vad parameter of the OnVolumeIndicationHandler callback does not report the voice activity status of the local user, except for the scenario where the engine automatically detects the voice activity of the local user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableDeepLearningDenoise()

int agora_gaming_rtc.IRtcEngine.EnableDeepLearningDenoise ( bool  enable )

Enables or disables deep-learning noise reduction.

Since
v3.3.1

The SDK enables traditional noise reduction mode by default to reduce most of the stationary background noise. If you need to reduce most of the non-stationary background noise, Agora recommends enabling deep-learning noise reduction as follows:

  1. Integrate the dynamical library under the libs folder to your project:
    • Android: libagora_ai_denoise_extension.so
    • iOS: AgoraAIDenoiseExtension.framework
    • macOS: AgoraAIDenoiseExtension.framework
    • Windows: libagora_ai_denoise_extension.dll
  2. Call EnableDeepLearningDenoise(true).

Deep-learning noise reduction requires high-performance devices. For example, the following devices and later models are known to support deep-learning noise reduction:

  • iPhone 6S
  • MacBook Pro 2015
  • iPad Pro (2nd generation)
  • iPad mini (5th generation)
  • iPad Air (3rd generation)

After successfully enabling deep-learning noise reduction, if the SDK detects that the device performance is not sufficient, it automatically disables deep-learning noise reduction and enables traditional noise reduction.

If you call EnableDeepLearningDenoise(false) or the SDK automatically disables deep-learning noise reduction in the channel, when you need to re-enable deep-learning noise reduction, you need to call LeaveChannel first, and then call EnableDeepLearningDenoise(true).

Note
  • This method dynamically loads the library, so Agora recommends calling this method before joining a channel.
  • This method works best with the human voice. Agora does not recommend using this method for audio containing music.
Parameters
enable Sets whether to enable deep-learning noise reduction.
  • true: (Default) Enables deep-learning noise reduction.
  • false: Disables deep-learning noise reduction.
Returns
  • 0: Success.
  • < 0: Failure.
    • -157 (ERR_MODULE_NOT_FOUND): The dynamical library for enabling deep-learning noise reduction is not integrated.

◆ EnableDualStreamMode()

int agora_gaming_rtc.IRtcEngine.EnableDualStreamMode ( bool  enabled )

Sets the stream mode to the single-stream (default) or dual-stream mode. (Interactive live streaming only.)

If the dual-stream mode is enabled, the receiver can choose to receive the high stream (high-resolution and high-bitrate video stream), or the low stream (low-resolution and low-bitrate video stream).

Parameters
enabled Sets the stream mode:
  • true: Dual-stream mode.
  • false: (Default) Single-stream mode.
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableEncryption()

int agora_gaming_rtc.IRtcEngine.EnableEncryption ( bool  enabled,
EncryptionConfig  encryptionConfig 
)

Enables/Disables the built-in encryption.

Since
v3.2.1

In scenarios requiring high security, Agora recommends calling this method to enable the built-in encryption before joining a channel.

All users in the same channel must use the same encryption mode and encryption key. After a user leaves the channel, the SDK automatically disables the built-in encryption. To enable the built-in encryption, call this method before the user joins the channel again.

Note
If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function.
Parameters
enabled Whether to enable the built-in encryption:
  • true: Enable the built-in encryption.
  • false: Disable the built-in encryption.
encryptionConfig Configurations of built-in encryption schemas. See EncryptionConfig.
Returns
  • 0: Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): An invalid parameter is used. Set the parameter with a valid value.
    • -4(ERR_NOT_SUPPORTED): The encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Initialize the IRtcEngine instance before calling this method.

◆ EnableFaceDetection()

int agora_gaming_rtc.IRtcEngine.EnableFaceDetection ( bool  enable )

Enables/Disables face detection for the local user.

Since
v3.0.1

Once face detection is enabled, the SDK triggers the OnFacePositionChangedHandler callback to report the face information of the local user, which includes the following aspects:

  • The width and height of the local video.
  • The position of the human face in the local video.
  • The distance between the human face and the device screen.
Note
  • Applies to Android and iOS only.
  • You can call this method either before or after joining a channel.
Parameters
enable Determines whether to enable the face detection function for the local user:
  • true: Enable face detection.
  • false: (Default) Disable face detection.
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableInEarMonitoring()

int agora_gaming_rtc.IRtcEngine.EnableInEarMonitoring ( bool  enabled )

Enables in-ear monitoring.

Note
  • This method is only for Android and iOS.
  • Users must use wired earphones to hear their own voices.
  • You can call this method either before or after joining a channel.
Parameters
enabled Sets whether to enable/disable in-ear monitoring:
  • true: Enable.
  • false: (Default) Disable.
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableLastmileTest()

int agora_gaming_rtc.IRtcEngine.EnableLastmileTest ( )

Enables the network connection quality test.

This method tests the quality of the users' network connections and is disabled by default.

Before a user joins a channel or before an audience switches to a host, call this method to check the uplink network quality.

This method consumes additional network traffic, and hence may affect communication quality.

Call the DisableLastmileTest method to disable this test after receiving the OnLastmileQualityHandler callback, and before joining a channel.

Note
  • Do not call any other methods before receiving the OnLastmileQualityHandler callback. Otherwise, the callback may be interrupted by other methods, and hence may not be triggered.
  • A host should not call this method after joining a channel (when in a call).
  • If you call this method to test the last-mile quality, the SDK consumes the bandwidth of a video stream, whose bitrate corresponds to the bitrate you set in the SetVideoEncoderConfiguration method. After you join the channel, whether you have called the DisableLastmileTest method or not, the SDK automatically stops consuming the bandwidth.
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableLocalAudio()

int agora_gaming_rtc.IRtcEngine.EnableLocalAudio ( bool  enabled )

Disables/Re-enables the local audio function.

The audio function is enabled by default. This method disables or re-enables the local audio function, that is, to stop or restart local audio capturing.

This method does not affect receiving or playing the remote audio streams, and EnableLocalAudio(false) is applicable to scenarios where the user wants to receive remote audio streams without sending any audio stream to other users in the channel.

Once the local audio function is disabled or re-enabled, the SDK triggers the OnLocalAudioStateChangedHandler callback, which reports LOCAL_AUDIO_STREAM_STATE_STOPPED(0) or LOCAL_AUDIO_STREAM_STATE_RECORDING(1).

Note
  • This method is different from the MuteLocalAudioStream method:
    • EnableLocalAudio: Disables/Re-enables the local audio capturing and processing. If you disable or re-enable local audio capturing using the EnableLocalAudio method, the local user may hear a pause in the remote audio playback.
    • MuteLocalAudioStream: Sends/Stops sending the local audio streams.
  • You can call this method either before or after joining a channel.
Parameters
enabled Sets whether to disable/re-enable the local audio function:
  • true: (Default) Re-enable the local audio function, that is, to start the local audio capturing device (for example, the microphone).
  • false: Disable the local audio function, that is, to stop local audio capturing.
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableLocalVideo()

int agora_gaming_rtc.IRtcEngine.EnableLocalVideo ( bool  enabled )

Enables/Disables the local video capture.

This method disables or re-enables the local video capturer, and does not affect receiving the remote video stream.

After you call the EnableVideo method, the local video capturer is enabled by default. You can call EnableLocalVideo(false) to disable the local video capturer. If you want to re-enable it, call EnableLocalVideo(true).

After the local video capturer is successfully disabled or re-enabled, the SDK triggers the OnUserEnableLocalVideoHandler callback on the remote client.

Note
  • You can call this method either before or after joining a channel.
  • This method affects the internal engine and can be called after the LeaveChannel method.
Parameters
enabled Sets whether to disable/re-enable the local video, including the capturer, renderer, and sender:
  • true: (Default) Re-enable the local video.
  • false: Disable the local video. Once the local video is disabled, the remote users can no longer receive the video stream of this user, while this user can still receive the video streams of the other remote users.
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableLocalVoicePitchCallback()

int agora_gaming_rtc.IRtcEngine.EnableLocalVoicePitchCallback ( int  interval )

Enables reporting the voice pitch of the local user.

Since
3.7.0

This method enables the SDK to regularly report the pitch value of the local user who sends a stream. After the local audio capture is enabled, and you call this method, the SDK triggers the OnLocalVoicePitchInHzHandler callback at the time interval set in this method.

Note
You can call this method either before or after joining a channel.
Parameters
interval Sets the time interval at which the SDK triggers the OnLocalVoicePitchInHzHandler callback:
  • ≤ 0: Disables the OnLocalVoicePitchInHzHandler callback.
  • > 0: Time interval (ms) at which the SDK triggers the onLocalVoicePitchInHzHandler callback. The value must be greater than or equal to 10. If the value is less than 10, the SDK automatically changes it to 10.
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableLoopbackRecording()

int agora_gaming_rtc.IRtcEngine.EnableLoopbackRecording ( bool  enabled,
string  deviceName 
)

Enables loopback capturing.

If you enable loopback capturing, the output of the sound card is mixed into the audio stream sent to the other end.

Note
  • This method is for macOS and Windows only.
  • The default sound card on the macOS system does not support loopback audio capture. To enable this capture, you need to enable a virtual sound card and pass the name of the virtual sound card in the deviceName parameter. Agora recommends that you use AgoraALD (Agora Audio Loopback Device) and pass in "AgoraALD".
Parameters
enabled Sets whether to enable/disable loopback capturing.
  • true: Enable loopback capturing.
  • false: (Default) Disable loopback capturing.
deviceName The device name of the sound card. The default value is null (the default sound card), which means the SDK uses the current sound card to capture. If you are using a virtual sound card, such as AgoraALD (Agora Audio Loopback Device), set this parameter as the name of the sound card ("AgoraALD").
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableRemoteSuperResolution()

int agora_gaming_rtc.IRtcEngine.EnableRemoteSuperResolution ( uint  userId,
bool  enable 
)

Enables/Disables the super-resolution algorithm for a remote user's video stream.

Since
v3.5.1

The algorithm effectively improves the resolution of the specified remote user's video stream. When the original resolution of the remote video stream is a × b pixels, you can receive and render the stream at a higher resolution (2a × 2b pixels) by enabling the algorithm.

After calling this method, the SDK triggers the OnUserSuperResolutionEnabledHandler callback to report whether you have successfully enabled the super-resolution algorithm.

Warning
The super-resolution algorithm requires extra system resources. To balance the visual experience and system usage, the SDK poses the following restrictions:
  • The algorithm can only be used for a single user at a time.
  • On the Android platform, the original resolution of the remote video must not exceed 640 × 360 pixels.
  • On the iOS platform, the original resolution of the remote video must not exceed 640 × 480 pixels. If you exceed these limitations, the SDK triggers the OnSDKWarningHandler callback with the corresponding warning codes:
  • WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION(1610): The origin resolution of the remote video is beyond the range where the super-resolution algorithm can be applied.
  • WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION(1611): Another user is already using the super-resolution algorithm.
  • WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED(1612): The device does not support the super-resolution algorithm.
Note
  • This method applies to Android and iOS only.
  • Requirements for the user's device:
    • Android: The following devices are known to support the method:
      • VIVO: V1821A, NEX S, 1914A, 1916A, and 1824BA
      • OPPO: PCCM00
      • OnePlus: A6000
      • Xiaomi: Mi 8, Mi 9, MIX3, and Redmi K20 Pro
      • SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, and SM-G9750
      • HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, and EVR-AN00
    • iOS: This method is supported on devices running iOS 12.0 or later. The following device models are known to support the method:
      • iPhone XR
      • iPhone XS
      • iPhone XS Max
      • iPhone 11
      • iPhone 11 Pro
      • iPhone 11 Pro Max
      • iPad Pro 11-inch (3rd Generation)
      • iPad Pro 12.9-inch (3rd Generation)
      • iPad Air 3 (3rd Generation)
Parameters
userId The ID of the remote user.
enable Whether to enable the super-resolution algorithm:
  • true: Enable the super-resolution algorithm.
  • false: Disable the super-resolution algorithm.
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableSoundPositionIndication()

int agora_gaming_rtc.IRtcEngine.EnableSoundPositionIndication ( bool  enabled )

Enables/Disables stereo panning for remote users.

Ensure that you call this method before JoinChannelByKey to enable stereo panning for remote users so that the local user can track the position of a remote user by calling SetRemoteVoicePosition.

Parameters
enabled Sets whether or not to enable stereo panning for remote users:
  • true: enables stereo panning.
  • false: disables stereo panning.
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableVideo()

int agora_gaming_rtc.IRtcEngine.EnableVideo ( )

Enables the video module.

Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode. If this method is called during an audio call, the audio mode switches to the video mode. To disable the video module, call the DisableVideo method.

A successful EnableVideo method call triggers the OnUserEnableVideoHandler(true) callback on the remote client.

Note
  • To get video raw data, call both EnableVideo and EnableVideoObserver methods.
  • This method affects the internal engine and can be called after the LeaveChannel method.
  • This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the video engine modules separately:
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableVideoObserver()

int agora_gaming_rtc.IRtcEngine.EnableVideoObserver ( )

Enables the video observer.

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

Note
  • To get video raw data, call both EnableVideo and EnableVideoObserver methods.
  • Call this method before joining a channel.
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableVirtualBackground()

int agora_gaming_rtc.IRtcEngine.EnableVirtualBackground ( bool  enabled,
VirtualBackgroundSource  source 
)

Enables/Disables the virtual background.

After enabling the virtual background feature, you can replace the original background image of the local user with a custom background image. After the replacement, all users in the channel can see the custom background image. You can find out from the OnVirtualBackgroundSourceEnabledHandler callback whether the virtual background is successfully enabled or the cause of any errors.

Note
  • Call this method after EnableVideo.
  • This functions requires a high-performance device. Agora recommends that you use this function on the following devices:
    • Android: Devices with the following chips:
      • Snapdragon 700 series 750G and later
      • Snapdragon 800 series 835 and later
      • Dimensity 700 series 720 and later
      • Kirin 800 series 810 and later
      • Kirin 900 series 980 and later
    • iOS: Devices with an A9 chip and better, as follows:
      • iPhone 6S and later
      • iPad Air (3rd generation) and later
      • iPad (5th generation) and later
      • iPad Pro (1st generation) and later
      • iPad mini (5th generation) and later
    • macOS and Windows: Devices with an i5 CPU and better
  • Agora recommends that you use this function in scenarios that meet the following conditions:
    • A high-definition camera device is used, and the environment is uniformly lit.
    • The captured video image is uncluttered, the user's portrait is half-length and largely unobstructed, and the background is a single color that differs from the color of the user's clothing.
  • The virtual background feature does not support video in the Texture format or video obtained from custom video capture by the Push method.
Parameters
enabled Sets whether to enable the virtual background:
  • true: Enable.
  • false: Disable.
source The custom background image. See VirtualBackgroundSource. Note: To adapt the resolution of the custom background image to the resolution of the SDK capturing video, the SDK scales and crops the custom background image while ensuring that the content of the custom background image is not distorted.
Returns
  • 0: Success.
  • < 0: Failure.

◆ EnableWebSdkInteroperability()

int agora_gaming_rtc.IRtcEngine.EnableWebSdkInteroperability ( bool  enabled )

Enables interoperability with the Agora Web SDK.

Deprecated:
This method is deprecated. As of v3.0.1, the Unity SDK automatically enables interoperability with the Web SDK, so you no longer need to call this method.
Note
  • This method applies only to the Live-broadcast profile. In the Communication profile, interoperability with the Agora Web SDK is enabled by default.
  • If the channel has Web SDK users, ensure that you call this method, or the video of the Unity user will be a black screen for the Web user.
Parameters
enabled Sets whether to enable/disable interoperability with the Agora Web SDK:
  • true: Enable.
  • false: (Default) Disable.
Returns
  • 0: Success.
  • < 0: Failure.

◆ GetAudioEffectManager()

IAudioEffectManager agora_gaming_rtc.IRtcEngine.GetAudioEffectManager ( )

Retrieves the AudioEffectManagerImpl object.

Returns
The AudioEffectManagerImpl object.

◆ GetAudioFileInfo()

int agora_gaming_rtc.IRtcEngine.GetAudioFileInfo ( string  filePath )

Gets the information of a specified audio file.

Since
v3.6.1.1

After calling this method successfully, the SDK triggers the OnRequestAudioFileInfoHandler callback to report the information of an audio file, such as audio duration. You can call this method multiple times to get the information of multiple audio files.

Note
Parameters
filePath The file path:
  • Windows: The absolute path or URL address (including the filename extensions) of the audio file. For example: C:\music\audio.mp4.
  • Android: The file path, including the filename extensions. To access an online file, Agora supports using a URL address; to access a local file, Agora supports using a URI address, an absolute path, or a path that starts with /assets/. You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: content://com.android.providers.media.documents/document/audio%3A14441.
  • iOS or macOS: The absolute path or URL address (including the filename extensions) of the audio file. For example: /var/mobile/Containers/Data/audio.mp4.
Returns
  • 0: Success.
  • < 0: Failure.

◆ GetAudioMixingCurrentPosition()

int agora_gaming_rtc.IRtcEngine.GetAudioMixingCurrentPosition ( )

Retrieves the playback position (ms) of the music file.

Call this method when you are in a channel.

Returns
  • ≥ 0: The current playback position of the audio mixing, if this method call succeeds.
  • < 0: Failure.

◆ GetAudioMixingDuration() [1/2]

int agora_gaming_rtc.IRtcEngine.GetAudioMixingDuration ( )

Retrieves the duration (ms) of the music file.

Call this method when you are in a channel.

Returns
  • ≥ 0: The audio mixing duration, if this method call succeeds.
  • < 0: Failure.

◆ GetAudioMixingDuration() [2/2]

int agora_gaming_rtc.IRtcEngine.GetAudioMixingDuration ( string  filePath )

Gets the total duration of the music file.

Deprecated:
Deprecated from v3.6.1.1. Use GetAudioFileInfo instead.
Note
Call this method after joining a channel.
Parameters
filePath The absolute path (including the filename extensions) of the local music file. For example: C:\music\audio.mp4. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. For more information, see Supported Media Formats in Media Foundation. When you access a local file on Android, Agora recommends passing a URI address or the path starts with /assets/ in this parameter.
Returns
  • ≥ 0: A successful method call. Returns the total duration (ms) of the specified music file.
  • < 0: Failure.

◆ GetAudioMixingPlayoutVolume()

int agora_gaming_rtc.IRtcEngine.GetAudioMixingPlayoutVolume ( )

Retrieves the audio mixing volume for local playback.

This method helps troubleshoot audio volume related issues.

Note
Call this method when you are in a channel.
Returns
  • ≥ 0: The audio mixing volume, if this method call succeeds. The value range is [0,100].
  • < 0: Failure.

◆ GetAudioMixingPublishVolume()

int agora_gaming_rtc.IRtcEngine.GetAudioMixingPublishVolume ( )

Retrieves the audio mixing volume for publishing.

This method helps troubleshoot audio volume related issues.

Note
Call this method when you are in a channel.
Returns
  • ≥ 0: The audio mixing volume for publishing, if this method call succeeds. The value range is [0,100].
  • < 0: Failure.

◆ GetAudioPlaybackDeviceManager()

IAudioPlaybackDeviceManager agora_gaming_rtc.IRtcEngine.GetAudioPlaybackDeviceManager ( )

Retrieves the AudioPlaybackDeviceManager object.

Returns
The AudioPlaybackDeviceManager object.

◆ GetAudioRawDataManager()

IAudioRawDataManager agora_gaming_rtc.IRtcEngine.GetAudioRawDataManager ( )

Retrieves the AudioRawDataManager object.

Returns
The AudioRawDataManager object.

◆ GetAudioRecordingDeviceManager()

IAudioRecordingDeviceManager agora_gaming_rtc.IRtcEngine.GetAudioRecordingDeviceManager ( )

Retrieves the AudioRecordingDeviceManager object.

Returns
The AudioRecordingDeviceManager object.

◆ GetAudioTrackCount()

int agora_gaming_rtc.IRtcEngine.GetAudioTrackCount ( )

Gets the audio track index of the current music file.

Since
v3.6.1.1
Note

@ param The specified playback track. This parameter must be less than or equal to the return value of GetAudioTrackCount.

Returns
  • ≥ 0: The audio track index of the current music file, if this method call succeeds.
  • < 0: Failure.

◆ GetCallId()

string agora_gaming_rtc.IRtcEngine.GetCallId ( )

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. Feedback methods, such as Rate and Complain, must be called after the call ends to submit feedback to the SDK.

The Rate and Complain methods require the callId parameter retrieved from the GetCallId method during a call. callId is passed as an argument into the Rate and Complain methods after the call ends.

Note
Ensure that you call this method after joining a channel.
Returns
  • ≥ 0: The current call ID, if this method call succeeds.
  • < 0: Failure.

◆ GetCameraMaxZoomFactor()

float agora_gaming_rtc.IRtcEngine.GetCameraMaxZoomFactor ( )

Gets the maximum zoom ratio supported by the camera.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

Returns
The maximum camera zoom factor.

◆ GetConnectionState()

CONNECTION_STATE_TYPE agora_gaming_rtc.IRtcEngine.GetConnectionState ( )

Retrieves the connection state of the SDK.

Note
You can call this method either before or after joining a channel.
Returns
CONNECTION_STATE_TYPE

◆ GetEngine() [1/2]

static IRtcEngine agora_gaming_rtc.IRtcEngine.GetEngine ( RtcEngineConfig  engineConfig )
static

Initializes an IRtcEngine instance.

Unless otherwise specified, all the methods provided by the IRtcEngine class are executed asynchronously. Agora recommends calling these methods in the same thread.

Note
  • You must initialize the IRtcEngine instance before calling any other method.
  • You can initialize an IRtcEngine instance either by calling this method or by calling GetEngine1. The difference between GetEngine1 and this method is that this method enables you to specify the connection area.
  • The Agora RTC Unity SDK supports initializing only one IRtcEngine instance for an app for now.
Parameters
engineConfig Configurations for the IRtcEngine instance. For details, see RtcEngineConfig.
Returns
  • The IRtcEngine instance, if this method call succeeds.
  • The error code, if this method call fails.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): No IRtcEngineEventHandler object is specified.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Check whether context is properly set.
    • -22(ERR_RESOURCE_LIMITED): The resource is limited. The app uses too much of the system resource and fails to allocate any resources.
    • -101(ERR_INVALID_APP_ID): The App ID is invalid.

◆ GetEngine() [2/2]

static IRtcEngine agora_gaming_rtc.IRtcEngine.GetEngine ( string  appId )
static

Initializes an IRtcEngine instance.

Unless otherwise specified, all the methods provided by the IRtcEngine class are executed asynchronously. Agora recommends calling these methods in the same thread.

Note
  • You must initialize the IRtcEngine instance before calling any other method.
  • You can initialize an IRtcEngine instance either by calling this method or by calling GetEngine2. The difference between GetEngine2 and this method is that GetEngine2 enables you to specify the connection area.
  • The Agora RTC Unity SDK supports initializing only one IRtcEngine instance for an app for now.
Parameters
appId The App ID issued to you by Agora. See How to get the App ID. Only users in apps with the same App ID can join the same channel and communicate with each other. Use an App ID to initialize only one IRtcEngine instance. To change your App ID, call Destroy to destroy the current IRtcEngine instance and then call this method to initialize an IRtcEngine instance with the new App ID.
Returns
  • The IRtcEngine instance, if this method call succeeds.
  • The error code, if this method call fails.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): No IRtcEngineEventHandler object is specified.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Check whether context is properly set.
    • -22(ERR_RESOURCE_LIMITED): The resource is limited. The app uses too much of the system resource and fails to allocate any resources.
    • -101(ERR_INVALID_APP_ID): The App ID is invalid.

◆ getEngine()

static IRtcEngine agora_gaming_rtc.IRtcEngine.getEngine ( string  appId )
static

Initializes the IRtcEngine.

Deprecated:
Use GetEngine instead.
Parameters
appId The App ID of your project.
Returns
The IRtcEngine instance.

◆ GetErrorDescription()

static string agora_gaming_rtc.IRtcEngine.GetErrorDescription ( int  code )
static

Retrieves the description of a warning or error code.

Parameters
code The warning or error code that the OnSDKWarningHandler or OnSDKErrorHandler callback returns.
Returns
Warning Code or Error Code.

◆ GetMediaRecorder()

IMediaRecorder agora_gaming_rtc.IRtcEngine.GetMediaRecorder ( )

Gets the MediaRecorder object.

Since
v3.6.1.1
Returns
The IMediaRecorder object.

◆ GetScreenCaptureManager()

IScreenCaptureManager agora_gaming_rtc.IRtcEngine.GetScreenCaptureManager ( )

Gets the ScreenCaptureManager object.

Since
v3.6.1.1
Returns
The ScreenCaptureManager object.

◆ GetSdkVersion()

static string agora_gaming_rtc.IRtcEngine.GetSdkVersion ( )
static

Gets the SDK version.

Returns
The version of the current SDK in the string format. For example, 2.9.1.

◆ GetUserInfoByUid()

UserInfo agora_gaming_rtc.IRtcEngine.GetUserInfoByUid ( uint  uid )

Gets the user information by passing in the user ID.

After a remote user joins the channel, the SDK gets the user ID and user account of the remote user, caches them in a mapping table object (userInfo), and triggers the OnUserInfoUpdatedHandler callback on the local client.

After receiving the OnUserInfoUpdatedHandler callback, you can call this method to get the user account of the remote user from the userInfo object by passing in the user ID.

Parameters
uid The user ID of the remote user. Ensure that you set this parameter.
Returns
  • 0: Success.
  • < 0: Failure.

◆ GetUserInfoByUserAccount()

UserInfo agora_gaming_rtc.IRtcEngine.GetUserInfoByUserAccount ( string  account )

Gets the user information by passing in the user account.

After a remote user joins the channel, the SDK gets the user ID and user account of the remote user, caches them in a mapping table object (userInfo), and triggers the OnUserInfoUpdatedHandler callback on the local client.

After receiving the OnUserInfoUpdatedHandler callback, you can call this method to get the user ID of the remote user from the userInfo object by passing in the user account.

Parameters
account The user account of the user. Ensure that you set this parameter.
Returns
  • 0: Success.
  • < 0: Failure.

◆ GetVideoDeviceManager()

IVideoDeviceManager agora_gaming_rtc.IRtcEngine.GetVideoDeviceManager ( )

Retrieves the VideoDeviceManager object.

Returns
The VideoDeviceManager object.

◆ GetVideoRawDataManager()

IVideoRawDataManager agora_gaming_rtc.IRtcEngine.GetVideoRawDataManager ( )

Retrieves the VideoRawDataManager object.

Returns
The VideoRawDataManager object.

◆ IsCameraAutoFocusFaceModeSupported()

bool agora_gaming_rtc.IRtcEngine.IsCameraAutoFocusFaceModeSupported ( )

Checks whether the camera auto-face focus function is supported.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

Returns
  • true: The device supports the camera auto-face focus function.
  • false: The device does not support the camera auto-face focus function.

◆ IsCameraExposurePositionSupported()

bool agora_gaming_rtc.IRtcEngine.IsCameraExposurePositionSupported ( )

Checks whether the camera exposure function is supported.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

Returns
  • true: The device supports the camera exposure function.
  • false: The device does not support the camera exposure function.

◆ IsCameraFocusSupported()

bool agora_gaming_rtc.IRtcEngine.IsCameraFocusSupported ( )

Checks whether the camera manual focus function is supported.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

Returns
  • true: The device supports the camera manual focus function.
  • false: The device does not support the camera manual focus function.

◆ IsCameraTorchSupported()

bool agora_gaming_rtc.IRtcEngine.IsCameraTorchSupported ( )

Checks whether the device supports enabling the flash.

Since
v3.6.1.1

The SDK uses the front camera by default, so if you call IsCameraTorchSupported directly, you can find out from the return value whether the device supports enabling the flash when using the front camera. If you want to check whether the device supports enabling the flash when using the rear camera, call SwitchCamera to switch the camera used by the SDK to the rear camera, and then call IsCameraTorchSupported.

Note
  • Call this method after the camera is started.
  • This method is for Android and iOS only.
  • On iPads with system version 15, even if IsCameraTorchSupported returns true, you might fail to enable the flash by calling SetCameraTorchOn due to system issues.
Returns
  • true: The device supports enabling the flash.
  • false: The device does not support enabling the flash.

◆ IsCameraZoomSupported()

bool agora_gaming_rtc.IRtcEngine.IsCameraZoomSupported ( )

Checks whether the camera zoom function is supported.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

Returns
  • true: The device supports the camera zoom function.
  • false: The device does not support the camera zoom function.

◆ IsSpeakerphoneEnabled()

bool agora_gaming_rtc.IRtcEngine.IsSpeakerphoneEnabled ( )

Checks whether the speakerphone is enabled.

Note
  • This method is for Android and iOS only.
  • You can call this method either before or after joining a channel.
Returns
  • 0: Success.
  • < 0: Failure.

◆ JoinChannel() [1/2]

int agora_gaming_rtc.IRtcEngine.JoinChannel ( string  channelName,
string  info = "",
uint  uid = 0 
)

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 with different App IDs cannot call each other.

You must call the LeaveChannel method to exit the current call before entering another channel.

A successful JoinChannel method call triggers the following callbacks:

  • The local client: OnJoinChannelSuccessHandler
  • The remote client: OnUserJoinedHandler, if the user joining the channel is in the Communication profile, or is a BROADCASTER in the Live Broadcast profile. When the connection between the client and Agora's server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the OnReJoinChannelSuccessHandler callback on the local client.
Note
A channel does not accept duplicate uids, such as two users with the same uid. If you set uid as 0, the system automatically assigns a uid. If you want to join a channel from different devices, ensure that each device has a different uid.
Warning
Ensure that the App ID used for creating the token is the same App ID used by the GetEngine method for initializing the IRtcEngine. Otherwise, the CDN live streaming may fail.
Parameters
channelName The unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters:
  • The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9
  • The space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
info (Optional) Additional information about the channel. This parameter can be set to null or contain channel related information. Other users in the channel will not receive this message.
uid (Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the OnJoinChannelSuccessHandler callback. Your application must record and maintain the returned uid since the SDK does not do so.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_INVALID_ARGUMENT(-2)
    • ERR_NOT_READY(-3)
    • ERR_REFUSED(-5)

◆ JoinChannel() [2/2]

int agora_gaming_rtc.IRtcEngine.JoinChannel ( string  token,
string  channelId,
string  info,
uint  uid,
ChannelMediaOptions  options 
)

Joins a channel with the user ID, and configures whether to publish or automatically subscribe to the audio or video streams.

Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other.

You must call the LeaveChannel method to exit the current call before entering another channel.

A successful JoinChannel method call triggers the following callbacks:

When the connection between the client and the Agora server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the OnReJoinChannelSuccessHandler callback on the local client.

Note
  • Compared with Compared with the JoinChannel method in the IRtcEngine class, this method has the options parameter, which configures whether the user publishes or automatically subscribes to the audio and video streams in the channel when joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams of all the other users in the channel. Subscribing incurs all associated usage costs. To unsubscribe, set the options parameter or call the Mute methods accordingly.
  • Ensure that the App ID used for generating the token is the same App ID used in creating an IRtcEngine object.
Parameters
token The token generated at your server. See Authenticate Your Users with Tokens.
channelId The unique channel name for an Agora RTC session. It must be in the string format and not exceed 64 bytes in length. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
info (Optional) Reserved for future use.
uid The user ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the OnJoinChannelSuccessHandler callback. Your application must record and maintain the returned uid, because the SDK does not do so.
  • Note: The ID of each user in the channel should be unique. If you want to join the same channel from different devices, ensure that the user IDs in all devices are different.
options The channel media options: ChannelMediaOptions.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -2(ERR_INALID_ARGUMENT): The parameter is invalid.
    • -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK.
    • -5(ERR_REFUSED): The request is rejected. This may be caused by the following:
      • You have created an AgoraChannel object with the same channel name.
      • You have joined and published a stream in a channel created by the AgoraChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method.
    • -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one channel at a time. Therefore, the SDK returns this error code when a user who has already joined a channel.

◆ JoinChannelByKey()

int agora_gaming_rtc.IRtcEngine.JoinChannelByKey ( string  channelKey,
string  channelName,
string  info = "",
uint  uid = 0 
)

Allows a user to join a channel with token.

Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other.

You must call the LeaveChannel method to exit the current call before entering another channel.

A successful JoinChannelByKey method call triggers the following callbacks:

When the connection between the client and Agora's server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the OnReJoinChannelSuccessHandler callback on the local client.

Once the user joins the channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the mute methods accordingly.

Note
A channel does not accept duplicate uids, such as two users with the same uid. If you set uid as 0, the system automatically assigns a uid. If you want to join a channel from different devices, ensure that each device has a different uid.
Warning
Ensure that the App ID used for creating the token is the same App ID used by the GetEngine method for initializing the IRtcEngine. Otherwise, the CDN live streaming may fail.
Parameters
channelKey The token generated by the application server. In most circumstances, a static App ID suffices. For added security, use a Channel Key.
  • If the user uses a static App ID, token is optional and can be set as null.
  • If the user uses a Channel Key, Agora issues an additional App Certificate for you to generate a user key based on the algorithm and App Certificate for user authentication on the server.
channelName The unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters:
  • The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9
  • The space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
info (Optional) Additional information about the channel. This parameter can be set to null or contain channel related information. Other users in the channel will not receive this message.
uid (Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the OnJoinChannelSuccessHandler callback. Your application must record and maintain the returned uid since the SDK does not do so.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -2(ERR_INALID_ARGUMENT): The parameter is invalid.
  • -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK.
  • -5(ERR_REFUSED): The request is rejected. This may be caused by the following:
    • You have created an AgoraChannel object with the same channel name.
    • You have joined and published a stream in a channel created by the AgoraChannel object.

◆ JoinChannelWithUserAccount() [1/2]

int agora_gaming_rtc.IRtcEngine.JoinChannelWithUserAccount ( string  token,
string  channelId,
string  userAccount 
)

Joins the channel with a user account.

After the user successfully joins the channel, the SDK triggers the following callbacks:

Once the user joins the channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the mute methods accordingly.

Note
To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
Parameters
token The token generated at your server:
  • For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary toke.
  • For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
channelId The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Returns
  • 0: Success.
  • < 0: Failure.

◆ JoinChannelWithUserAccount() [2/2]

int agora_gaming_rtc.IRtcEngine.JoinChannelWithUserAccount ( string  token,
string  channelId,
string  userAccount,
ChannelMediaOptions  options 
)

Joins the channel with a user account, and configures whether to publish or automatically subscribe to the audio or video streams.

Since
v3.3.1

After the user successfully joins the channel, the SDK triggers the following callbacks:

  • The local client: OnLocalUserRegisteredHandler and OnJoinChannelSuccessHandler.
  • The remote client: OnUserJoinedHandler and OnUserInfoUpdatedHandler, if the user joining the channel is in the COMMUNICATION profile, or is a host in the LIVE_BROADCASTING profile.

    Note
  • Compared with JoinChannelWithUserAccount, this method has the options parameter, which configures whether the user publishes or automatically subscribes to the audio and video streams in the channel when joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams of all the other users in the channel. Subscribing incurs all associated usage costs. To unsubscribe, set the options parameter or call the Mute methods accordingly.
  • To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
  • Before using a String user name, ensure that you read How can I use string user names for details about the limitations and implementation steps.
Parameters
token The token generated at your server. For details, see Generate a token.
channelId The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that the user account is unique and do not set it as null. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
options The channel media options: ChannelMediaOptions.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_INVALID_ARGUMENT (-2)
    • ERR_NOT_READY (-3)
    • ERR_REFUSED (-5)

◆ LeaveChannel()

int agora_gaming_rtc.IRtcEngine.LeaveChannel ( )

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

This method returns 0 if the user leaves the channel and destroys all resources related to the call.

This method call is asynchronous, and the user has not left the channel when the method call returns. Once the user leaves the channel, the SDK triggers the OnLeaveChannelHandler callback.

A successful LeaveChannel method call triggers the following callbacks:

  • The local client: OnLeaveChannelHandler
  • The remote client: OnUserOfflineHandler, if the user leaving the channel is in the Communication channel, or is a BROADCASTER in the Live Broadcast profile.
Note
  • If you call the Destroy method immediately after the LeaveChannel method, the LeaveChannel process interrupts, and the OnLeaveChannelHandler callback is not triggered.
  • If you call the LeaveChannel method during a CDN live streaming, the SDK triggers the RemovePublishStreamUrl method.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ MuteAllRemoteAudioStreams()

int agora_gaming_rtc.IRtcEngine.MuteAllRemoteAudioStreams ( bool  mute )

Stops or resumes subscribing to the audio streams of all remote users.

As of v3.3.1, after successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users.

Note
  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing Status.
Parameters
mute Sets whether to stop subscribing to the audio streams of all remote users.
  • true: Stop subscribing to the audio streams of all remote users.
  • false: (Default) Resume subscribing to the audio streams of all remote users.
Returns
  • 0: Success.
  • < 0: Failure.

◆ MuteAllRemoteVideoStreams()

int agora_gaming_rtc.IRtcEngine.MuteAllRemoteVideoStreams ( bool  mute )

Stops or resumes subscribing to the video streams of all remote users.

As of v3.3.1, after successfully calling this method, the local user stops or resumes subscribing to the video streams of all remote users, including all subsequent users.

Note
  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.
Parameters
mute Sets whether to stop subscribing to the video streams of all remote users.
  • true: Stop subscribing to the video streams of all remote users.
  • false: (Default) Resume subscribing to the video streams of all remote users.
Returns
  • 0: Success.
  • < 0: Failure.

◆ MuteLocalAudioStream()

int agora_gaming_rtc.IRtcEngine.MuteLocalAudioStream ( bool  mute )

Stops or resumes publishing the local audio stream.

Note
  • When mute is set as true, this method does not affect any ongoing audio recording, because it does not disable the microphone.
  • You can call this method either before or after joining a channel. If you call SetChannelProfile after this method, the SDK resets whether or not to stop publishing the local audio according to the channel profile and user role. Therefore, we recommend calling this method after the SetChannelProfile method.
Parameters
mute Sets whether to stop publishing the local audio stream.
  • true: Stops publishing the local audio stream.
  • false: (Default) Resumes publishing the local audio stream.
Returns
  • 0: Success.
  • < 0: Failure.

◆ MuteLocalVideoStream()

int agora_gaming_rtc.IRtcEngine.MuteLocalVideoStream ( bool  mute )

Stops or resumes publishing the local video stream.

A successful MuteLocalVideoStream method call triggers the OnUserMuteVideoHandler callback on the remote client.

Note
  • This method executes faster than the EnableLocalVideo method, which controls the sending of the local video stream.
  • When mute is set as true, this method does not affect any ongoing video recording, because it does not disable the camera.
  • You can call this method either before or after joining a channel. If you call SetChannelProfile after this method, the SDK resets whether or not to stop publishing the local video according to the channel profile and user role. Therefore, Agora recommends calling this method after the SetChannelProfile method.
Parameters
mute Sets whether to stop publishing the local video stream.
  • true: Stops publishing the local video stream.
  • false: (Default) Resumes publishing the local video stream.
Returns
  • 0: Success.
  • < 0: Failure.

◆ MuteRemoteAudioStream()

int agora_gaming_rtc.IRtcEngine.MuteRemoteAudioStream ( uint  uid,
bool  mute 
)

Stops or resumes subscribing to the audio stream of a specified user.

Note
  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.
Parameters
uid The user ID of the specified remote user.
mute Sets whether to stop subscribing to the audio stream of a specified user.
  • true: Stop subscribing to the audio stream of a specified user.
  • false: (Default) Resume subscribing to the audio stream of a specified user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ MuteRemoteVideoStream()

int agora_gaming_rtc.IRtcEngine.MuteRemoteVideoStream ( uint  uid,
bool  mute 
)

Stops or resumes subscribing to the video stream of a specified user.

Note
  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.
Parameters
uid The user ID of the specified remote user.
mute Sets whether to stop subscribing to the video stream of a specified user.
  • true: Stop subscribing to the video stream of a specified user.
  • false: (Default) Resume subscribing to the video stream of a specified user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ PauseAllChannelMediaRelay()

int agora_gaming_rtc.IRtcEngine.PauseAllChannelMediaRelay ( )

Pauses the media stream relay to all destination channels.

Since
v3.6.1.1

After the cross-channel media stream relay starts, you can call this method to pause relaying media streams to all destination channels; after the pause, if you want to resume the relay, call ResumeAllChannelMediaRelay.

After a successful method call, the SDK triggers the OnChannelMediaRelayEventHandler callback to report whether the media stream relay is successfully paused.

Note
Call this method after the StartChannelMediaRelay method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ PauseAudioMixing()

int agora_gaming_rtc.IRtcEngine.PauseAudioMixing ( )

Pauses playing and mixing the music file.

Call this method when you are in a channel.

Returns
  • 0: Success.
  • < 0: Failure.

◆ PushAudioFrame() [1/2]

int agora_gaming_rtc.IRtcEngine.PushAudioFrame ( AudioFrame  audioFrame )

Pushes the raw data as the external audio frame into the channel.

Deprecated:
This method is deprecated from v3.6.1.1, use the PushAudioFrame method instead.

For more information, see Custom Audio Source and Renderer in the Advanced Features of the Docs section.

Parameters
audioFrame The audio frame: AudioFrame.
Returns
  • 0: Success.
  • < 0: Failure.

◆ PushAudioFrame() [2/2]

int agora_gaming_rtc.IRtcEngine.PushAudioFrame ( int  sourcePos,
AudioFrame  audioFrame 
)

Pushes the external audio frame to a specified position.

Since
v3.6.1.1

According to your needs, you can push the external audio frame to one of three positions: after audio capture, before audio encoding, or before local playback. You can call this method multiple times to push one audio frame to multiple positions or multiple audio frames to different positions. For example, in the KTV scenario, you can push the singing voice to after audio capture, so that the singing voice can be processed by the SDK audio module and you can obtain a high-quality audio experience; you can also push the accompaniment to before audio encoding, so that the accompaniment is not affected by the audio module of the SDK.

Note
Call this method after joining a channel.
Parameters
sourcePos The push position of the external audio frame.
audioFrame The external audio frame. The value range of the audio frame length (ms) is [10,60].
Returns
  • 0: Success.
  • < 0: Failure.
    • -2(ERR_INALID_ARGUMENT): The parameter is invalid.
    • -12 (ERR_TOO_OFTEN): The call frequency is too high, causing the internal buffer to overflow. Call this method again after 30-50 ms.

◆ PushVideoFrame()

int agora_gaming_rtc.IRtcEngine.PushVideoFrame ( ExternalVideoFrame  externalVideoFrame )

Pushes the video frame using the ExternalVideoFrame and passes the video frame to the Agora RTC SDK.

Note
This method does not support video frames in the Texture format.
Parameters
externalVideoFrame Video frame to be pushed. See ExternalVideoFrame.
Returns
  • 0: Success.
  • < 0: Failure.

◆ QueryEngine()

static IRtcEngine agora_gaming_rtc.IRtcEngine.QueryEngine ( )
static

Query the IRtcEngine instance.

Note
Call this method after calling GetEngine.
Returns
The IRtcEngine instance.

◆ Rate()

int agora_gaming_rtc.IRtcEngine.Rate ( string  callId,
int  rating,
string  desc = "" 
)

Allows a user to rate a call after the call ends.

Note
Ensure that you call this method after joining a channel.
Parameters
callId The ID of the call, retrieved from the GetCallId method.
rating Rating of the call. The value is between 1 (lowest score) and 5 (highest score). If you set a value out of this range, the ERR_INVALID_ARGUMENT(2) error returns.
desc (Optional) The description of the rating, with a string length of less than 800 bytes.
Returns
  • 0: Success.
  • < 0: Failure.

◆ RegisterLocalUserAccount()

int agora_gaming_rtc.IRtcEngine.RegisterLocalUserAccount ( string  appId,
string  userAccount 
)

Registers a user account.

Once registered, the user account can be used to identify the local user when the user joins the channel. After the user successfully registers a user account, the SDK triggers the OnLocalUserRegisteredHandler callback on the local client, reporting the user ID and user account of the local user.

To join a channel with a user account, you can choose either of the following:

  • Call the RegisterLocalUserAccount method to create a user account, and then the JoinChannelWithUserAccount method to join the channel.
  • Call the JoinChannelWithUserAccount method to join the channel.

The difference between the two is that for the former, the time elapsed between calling the JoinChannelWithUserAccount method and joining the channel is shorter than the latter.

Note
  • Ensure that you set the userAccount parameter. Otherwise, this method does not take effect.
  • Ensure that the value of the userAccount parameter is unique in the channel.
  • To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
Parameters
appId The App ID of your project.
userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Returns
  • 0: Success.
  • < 0: Failure.

◆ RemovePublishStreamUrl()

int agora_gaming_rtc.IRtcEngine.RemovePublishStreamUrl ( string  url )

Removes an RTMP or RTMPS stream from the CDN. (CDN live only.)

Deprecated:
This method is deprecated as of v3.6.1.1. See Release Notes for an alternative solution.

This method removes the CDN streaming URL (added by the AddPublishStreamUrl method) from a CDN live stream. The SDK returns the result of this method call in the OnStreamUnpublishedHandler callback.

The RemovePublishStreamUrl method call triggers the OnRtmpStreamingStateChangedHandler callback on the local client to report the state of removing an RTMP or RTMPS stream from the CDN.

Note
  • This method removes only one CDN streaming URL each time it is called.
  • The CDN streaming URL must not contain special characters, such as Chinese language characters.
  • This method applies to Live Broadcast only.
Parameters
url The CDN streaming URL to be removed. The maximum length of this parameter is 1024 bytes.
Returns
  • 0: Success.
  • < 0: Failure.

◆ RenewToken()

int agora_gaming_rtc.IRtcEngine.RenewToken ( string  token )

Gets a new token when the current token expires after a period of time.

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

The application should call this method to get the new token. Failure to do so will result in the SDK disconnecting from the server.

Parameters
token The new token.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ ResumeAllChannelMediaRelay()

int agora_gaming_rtc.IRtcEngine.ResumeAllChannelMediaRelay ( )

Resumes the media stream relay to all destination channels.

Since
v3.6.1.1

After calling the PauseAllChannelMediaRelay method, you can call this method to resume relaying media streams to all destination channels.

After a successful method call, the SDK triggers the OnChannelMediaRelayEventHandler callback to report whether the media stream relay is successfully resumed.

Note
Call this method after the PauseAllChannelMediaRelay method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ ResumeAudioMixing()

int agora_gaming_rtc.IRtcEngine.ResumeAudioMixing ( )

Resumes playing and mixing the music file.

Call this method when you are in a channel.

Returns
  • 0: Success.
  • < 0: Failure.

◆ SelectAudioTrack()

int agora_gaming_rtc.IRtcEngine.SelectAudioTrack ( int  index )

Specifies the playback track of the current music file.

Since
v3.6.1.1

After getting the audio track index of the current music file, call this method to specify any audio track to play. For example, if different tracks of a multitrack file store songs in different languages, you can call this method to set the language of the music file to play.

Note
  • This method is for Android, iOS, and Windows only.
  • Call this method after calling StartAudioMixing and receiving the OnAudioMixingStateChangedHandler(AUDIO_MIXING_STATE_PLAYING) callback.
  • For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
Parameters
index The specified playback track. This parameter must be less than or equal to the return value of GetAudioTrackCount.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SendCustomReportMessage()

int agora_gaming_rtc.IRtcEngine.SendCustomReportMessage ( string  id,
string  category,
string  events,
string  label,
int  value 
)

Agora supports reporting and analyzing customized messages.

Since
v3.2.0

This function is in the beta stage with a free trial. The ability provided in its beta test version is reporting a maximum of 10 message pieces within 6 seconds, with each message piece not exceeding 256 bytes and each string not exceeding 100 bytes. To try out this function, contact support@agora.io and discuss the format of customized messages with us.

◆ SendStreamMessage()

int agora_gaming_rtc.IRtcEngine.SendStreamMessage ( int  streamId,
byte[]  data 
)

Sends data stream messages to all users in a channel.

The SDK has the following restrictions on this method:

  • Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 kB.
  • Each client can send up to 6 kB of data per second.
  • Each user can have up to five data streams simultaneously.

A successful SendStreamMessage method call triggers the OnStreamMessageHandler callback on the remote client, from which the remote user gets the stream message.

A failed SendStreamMessage method call triggers the OnStreamMessageHandler callback on the remote client.

Note
  • This method applies only to the Communication profile or to the hosts in the Live-broadcast profile. If an audience in the Live-broadcast profile calls this method, the audience may be switched to a host.
  • Ensure that you have created the data stream using CreateDataStream before calling this method.
Parameters
streamId ID of the sent data stream, returned in the CreateDataStream method.
data The sent data.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetAudioEffectParameters()

int agora_gaming_rtc.IRtcEngine.SetAudioEffectParameters ( AUDIO_EFFECT_PRESET  preset,
int  param1,
int  param2 
)

Sets parameters for SDK preset audio effects.

Since
v3.2.0

Call this method to set the following parameters for the local user who send an audio stream:

  • 3D voice effect: Sets the cycle period of the 3D voice effect.
  • Pitch correction effect: Sets the basic mode and tonic pitch of the pitch correction effect. Different songs have different modes and tonic pitches. Agora recommends bounding this method with interface elements to enable users to adjust the pitch correction interactively.

After setting parameters, all users in the channel can hear the relevant effect.

You can call this method directly or after SetAudioEffectPreset. If you call this method after SetAudioEffectPreset, ensure that you set the preset parameter of SetAudioEffectPreset to ROOM_ACOUSTICS_3D_VOICE or PITCH_CORRECTION and then call this method to set the same enumerator; otherwise, this method overrides SetAudioEffectPreset.

Note
Parameters
preset The options for SDK preset audio effects:
  • ROOM_ACOUSTICS_3D_VOICE: 3D voice effect.
    • Call SetAudioProfile and set the profile parameter to AUDIO_PROFILE_MUSIC_STANDARD_STEREO(3) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before setting this enumerator; otherwise, the enumerator setting does not take effect.
    • If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect.
  • PITCH_CORRECTION: Pitch correction effect. To achieve better audio effect quality, Agora recommends calling SetAudioProfile and setting the profile parameter to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before setting this enumerator.
param1
  • If you set preset to ROOM_ACOUSTICS_3D_VOICE, the param1 sets the cycle period of the 3D voice effect. The value range is [1,60] and the unit is a second. The default value is 10 seconds, indicating that the voice moves around you every 10 seconds.
  • If you set preset to PITCH_CORRECTION, param1 sets the basic mode of the pitch correction effect:
    • 1: (Default) Natural major scale.
    • 2: Natural minor scale.
    • 3: Japanese pentatonic scale.
param2
  • If you set preset to ROOM_ACOUSTICS_3D_VOICE, you need to set param2 to 0.
  • If you set preset to PITCH_CORRECTION, param2 sets the tonic pitch of the pitch correction effect:
    • 1: A
    • 2: A#
    • 3: B
    • 4: (Default) C
    • 5: C#
    • 6: D
    • 7: D#
    • 8: E
    • 9: F
    • 10: F#
    • 11: G
    • 12: G#
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetAudioEffectPreset()

int agora_gaming_rtc.IRtcEngine.SetAudioEffectPreset ( AUDIO_EFFECT_PRESET  preset )

Sets an SDK preset audio effect.

Since
v3.2.0

Call this method to set an SDK preset audio effect for the local user who sends an audio stream. This audio effect does not change the gender characteristics of the original voice. After setting an audio effect, all users in the channel can hear the effect.

You can set different audio effects for different scenarios. See Set the Voice Effect.

To achieve better audio effect quality, Agora recommends calling SetAudioProfile and setting the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING(3) before calling this method.

Note
Parameters
preset The options for SDK preset audio effects. See AUDIO_EFFECT_PRESET.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetAudioMixingDualMonoMode()

int agora_gaming_rtc.IRtcEngine.SetAudioMixingDualMonoMode ( AUDIO_MIXING_DUAL_MONO_MODE  mode )

Sets the channel mode of the current music file.

Since
v3.6.1.1

In a stereo music file, the left and right channels can store different audio data. According to your needs, you can set the channel mode to original mode, left channel mode, right channel mode, or mixed channel mode. For example, in the KTV scenario, the left channel of the music file stores the musical accompaniment, and the right channel stores the singing voice. If you only need to listen to the accompaniment, call this method to set the channel mode of the music file to left channel mode; if you need to listen to the accompaniment and the singing voice at the same time, call this method to set the channel mode to mixed channel mode.

Note
  • Call this method after calling StartAudioMixing and receiving the OnAudioMixingStateChangedHandler(AUDIO_MIXING_STATE_PLAYING) callback.
  • This method only applies to stereo audio files.
Parameters
mode The channel mode, see AUDIO_MIXING_DUAL_MONO_MODE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetAudioMixingPitch()

int agora_gaming_rtc.IRtcEngine.SetAudioMixingPitch ( int  pitch )

Sets the pitch of the local music file.

Since
v3.0.1

When a local music file is mixed with a local human voice, call this method to set the pitch of the local music file only.

Note
Call this method after calling StartAudioMixing.
Parameters
pitch Sets the pitch of the local music file by chromatic scale. The default value is 0, which means keeping the original pitch. The value ranges from -12 to 12, and the pitch value between consecutive values is a chromatic value. The greater the absolute value of this parameter, the higher or lower the pitch of the local music file.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetAudioMixingPlaybackSpeed()

int agora_gaming_rtc.IRtcEngine.SetAudioMixingPlaybackSpeed ( int  speed )

Sets the playback speed of the current music file.

Since
v3.6.1.1
Note
Call this method after calling StartAudioMixing and receiving the OnAudioMixingStateChangedHandler(AUDIO_MIXING_STATE_PLAYING) callback.
Parameters
speed The playback speed. Agora recommends that you limit this value to between 50 and 400, defined as follows:
  • 50: Half the original speed.
  • 100: The original speed.
  • 400: 4 times the original speed.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetAudioMixingPosition()

int agora_gaming_rtc.IRtcEngine.SetAudioMixingPosition ( int  pos )

Sets the playback position of the music file to a different starting position (the default plays from the beginning).

Note
Ensure that this method is called after StartAudioMixing.
Parameters
pos The playback starting position (ms) of the music file.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetAudioProfile()

int agora_gaming_rtc.IRtcEngine.SetAudioProfile ( AUDIO_PROFILE_TYPE  audioProfile,
AUDIO_SCENARIO_TYPE  scenario 
)

Sets the audio parameters and application scenarios.

Note
Parameters
audioProfile Sets the sample rate, bitrate, encoding mode, and the number of channels. See AUDIO_PROFILE_TYPE.
scenario Sets the audio application scenario. See AUDIO_SCENARIO_TYPE. Under different audio scenarios, the device uses different volume tracks, i.e. either the in-call volume or the media volume. For details, see What is the difference between the in-call volume and the media volume?.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetAudioSessionOperationRestriction()

int agora_gaming_rtc.IRtcEngine.SetAudioSessionOperationRestriction ( AUDIO_SESSION_OPERATION_RESTRICTION  restriction )

Sets the audio session’s operational restriction.

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

You can call this method at any time to return the control of the audio sessions to the SDK.

Note
  • This method is for iOS only.
  • This method restricts the SDK’s manipulation of the audio session. Any operation to the audio session relies solely on the app, other apps, or third-party components.
  • You can call this method either before or after joining a channel.
Parameters
restriction The operational restriction (bit mask) of the SDK on the audio session. See AUDIO_SESSION_OPERATION_RESTRICTION.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetAVSyncSource()

int agora_gaming_rtc.IRtcEngine.SetAVSyncSource ( string  channelId,
uint  uid 
)

Bind local user and a remote user as an audio&video sync group. The remote user is defined by cid and uid. There’s a usage limit that local user must be a video stream sender. On the receiver side, media streams from same sync group will be time-synced

Parameters
channelId The channel id
uid The user ID of the remote user to be bound with (local user)
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetBeautyEffectOptions()

int agora_gaming_rtc.IRtcEngine.SetBeautyEffectOptions ( bool  enabled,
BeautyOptions  beautyOptions 
)

Enables/Disables image enhancement and sets the options.

Since
v3.0.1
Note
Call this method after calling EnableVideo.
Parameters
enabled Sets whether or not to enable image enhancement:
  • true: Enables image enhancement.
  • false: Disables image enhancement.
beautyOptions Sets the image enhancement option. See BeautyOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetCameraAutoFocusFaceModeEnabled()

int agora_gaming_rtc.IRtcEngine.SetCameraAutoFocusFaceModeEnabled ( bool  enabled )

Sets whether to enable face auto-focus.

The SDK disables face autofocus by default. To set face autofocus, call this method.

Note
Call this method after the camera is started.
Parameters
enabled Whether to enable face auto-focus:
  • true: Enable face auto-focus.
  • false: Disable face auto-focus.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetCameraCapturerConfiguration()

int agora_gaming_rtc.IRtcEngine.SetCameraCapturerConfiguration ( CameraCapturerConfiguration  cameraCaptureConfiguration )

Sets the camera capture configuration.

For a video call or interactive live streaming, generally the SDK controls the camera output parameters. When the default camera capturer settings do not meet special requirements or cause performance problems, we recommend using this method to set the camera capturer configuration:

Note
Call this method before enabling the local camera. That said, you can call this method before calling JoinChannelByKey, EnableVideo, or EnableLocalVideo, depending on which method you use to turn on your local camera.
Parameters
cameraCaptureConfiguration Sets the camera capturer configuration. See CameraCapturerConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetCameraExposurePosition()

int agora_gaming_rtc.IRtcEngine.SetCameraExposurePosition ( float  positionXinView,
float  positionYinView 
)

Sets the camera exposure position.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

Parameters
positionXinView The horizontal coordinate of the touch point in the view.
positionYinView The vertical coordinate of the touch point in the view.
Returns
  • 0: Success. < 0: Failure.

◆ SetCameraFocusPositionInPreview()

int agora_gaming_rtc.IRtcEngine.SetCameraFocusPositionInPreview ( float  positionX,
float  positionY 
)

Sets the camera manual focus position.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

A successful setCameraFocusPositionInPreview method call triggers the OnCameraFocusAreaChangedHandler callback on the local client.

Parameters
positionX The horizontal coordinate of the touch point in the view.
positionY The vertical coordinate of the touch point in the view.
Returns
  • 0: Success. < 0: Failure.

◆ SetCameraTorchOn()

int agora_gaming_rtc.IRtcEngine.SetCameraTorchOn ( bool  on )

Sets whether to enable the flash.

Since
v3.6.1.1
Note
  • Call this method after the camera is started.
  • This method is for Android and iOS only.
  • On iPads with system version 15, even if IsCameraTorchSupported returns true, you might fail to successfully enable the flash by calling SetCameraTorchOn due to system issues.
Parameters
on Determines whether to enable the flash:
  • true: Enable the flash.
  • false: Disable the flash.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetCameraZoomFactor()

int agora_gaming_rtc.IRtcEngine.SetCameraZoomFactor ( float  factor )

Sets the camera zoom ratio.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

Parameters
factor Sets the camera zoom factor. The value ranges between 1.0 and the maximum zoom supported by the device.
Returns
  • The set camera zoom factor, if this method call is successful. < 0: Failure.

◆ SetChannelProfile()

int agora_gaming_rtc.IRtcEngine.SetChannelProfile ( CHANNEL_PROFILE  profile )

Sets the channel profile of the Agora IRtcEngine.

The Agora IRtcEngine differentiates channel profiles and applies optimization algorithms accordingly. For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for a video broadcast.

Warning
  • To ensure the quality of real-time communication, we recommend that all users in a channel use the same channel profile.
  • Call this method before calling joins a channel. You cannot set the channel profile once you have joined the channel.
  • The default audio route and video encoding bitrate are different in different channel profiles. For details, see SetDefaultAudioRouteToSpeakerphone and SetVideoEncoderConfiguration.
Parameters
profile The channel profile of the Agora IRtcEngine. See CHANNEL_PROFILE.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ SetClientRole() [1/2]

int agora_gaming_rtc.IRtcEngine.SetClientRole ( CLIENT_ROLE_TYPE  role )

Sets the role of the user, such as a host or an audience (default), before joining a channel in the interactive live streaming.

This method can be used to switch the user role in the interactive live streaming after the user joins a channel.

You can call this method either before or after joining a channel. If you call this method to switch the user role after joining a channel, the SDK automatically does the following:

  • Calls MuteLocalAudioStream and MuteLocalVideoStream to change the publishing state.
  • Triggers OnClientRoleChangedHandler or OnClientRoleChangeFailedHandler on the local client.
  • Triggers OnUserJoinedHandler or OnUserOfflineHandler(BECOME_AUDIENCE) on the remote client.
Note
This method applies only to the Live-broadcast profile.
Parameters
role Sets the role of the user. See CLIENT_ROLE_TYPE.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ SetClientRole() [2/2]

int agora_gaming_rtc.IRtcEngine.SetClientRole ( CLIENT_ROLE_TYPE  role,
ClientRoleOptions  clientRoleOptions 
)

Sets the role of a user in interactive live streaming.

Since
v3.2.0

You can call this method either before or after joining the channel to set the user role as audience or host. If you call this method to switch the user role after joining the channel, the SDK triggers the following callbacks:

Note
  • This method applies to the LIVE_BROADCASTING profile only (when the profile parameter in SetChannelProfile is set as CHANNEL_PROFILE_LIVE_BROADCASTING).
  • The difference between this method and SetClientRole1 is that this method can set the user level in addition to the user role.
    • The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, receive remote streams, and push streams to a CDN address.
    • The user level determines the level of services that a user can enjoy within the permissions of the user's role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. Levels affect prices.
Parameters
role The role of a user in interactive live streaming. See CLIENT_ROLE_TYPE.
clientRoleOptions The detailed options of a user, including user level. See ClientRoleOptions.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ SetCloudProxy()

int agora_gaming_rtc.IRtcEngine.SetCloudProxy ( CLOUD_PROXY_TYPE  proxyType )

Sets the Agora cloud proxy service.

Since
v3.3.1

When the user's firewall restricts the IP address and port, refer to Use Cloud Proxy to add the specific IP addresses and ports to the firewall whitelist; then, call this method to enable the cloud proxy and set the proxyType parameter as UDP_PROXY(1), which is the cloud proxy for the UDP protocol.

After a successfully cloud proxy connection, the SDK triggers the OnConnectionStateChangedHandler(CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) callback.

To disable the cloud proxy that has been set, call SetCloudProxy(NONE_PROXY). To change the cloud proxy type that has been set, call SetCloudProxy(NONE_PROXY) first, and then call SetCloudProxy, and pass the value that you expect in proxyType.

Note
  • Agora recommends that you call this method before joining the channel or after leaving the channel.
  • When you use the cloud proxy for the UDP protocol, the services for pushing streams to CDN and co-hosting across channels are not available.
Parameters
proxyType The cloud proxy type, see CLOUD_PROXY_TYPE. This parameter is required, and the SDK reports an error if you do not pass in a value.
Returns
  • 0: Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ SetColorEnhanceOptions()

int agora_gaming_rtc.IRtcEngine.SetColorEnhanceOptions ( bool  enabled,
ColorEnhanceOptions  options 
)

Sets color enhancement.

Since
3.6.2 The video images captured by the camera can have color distortion. The color enhancement feature intelligently adjusts video characteristics such as saturation and contrast to enhance the video color richness and color reproduction, making the video more vivid.

You can call this method to enable the color enhancement feature and set the options of the color enhancement effect.

Note
  • Call this method after EnableVideo.
  • The color enhancement feature has certain performance requirements on devices. If your device overheats after you enable color enhancement, Agora recommends modifying the color enhancement options to a less performance-consuming level or disabling color enhancement entirely.
Parameters
enabled Whether to enable color enhancement:
  • true: Yes.
  • false: No.
options The color enhancement options. See ColorEnhanceOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetDefaultAudioRouteToSpeakerphone()

int agora_gaming_rtc.IRtcEngine.SetDefaultAudioRouteToSpeakerphone ( bool  speakerphone )

Sets the default audio playback route.

This method sets whether the received audio is routed to the earpiece or speakerphone by default before joining a channel. If a user does not call this method, the audio is routed to the earpiece by default. If you need to change the default audio route after joining a channel, call the SetEnableSpeakerphone method.

The default setting for each profile:

  • Communication:
    • In a voice call, the default audio route is the earpiece.
    • In a video call, the default audio route is the speakerphone. If a user who is in the Communication profile calls the DisableVideo method or if the user calls the MuteLocalVideoStream and MuteAllRemoteVideoStreams methods, the default audio route switches back to the earpiece automatically.
  • Live Broadcast: Speakerphone.
Note
  • This method is for Android and iOS only.
  • This method is applicable only to the Communication profile.
  • For iOS, this method only works in a voice call.
  • Call this method before calling the JoinChannelByKey method.
Parameters
speakerphone Sets the default audio route:
  • true: Route the audio to the speakerphone. If the playback device connects to the earpiece or Bluetooth, the audio cannot be routed to the speakerphone.
  • false: (Default) Route the audio to the earpiece. If a headset is plugged in, the audio is routed to the headset.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetDefaultMuteAllRemoteAudioStreams()

int agora_gaming_rtc.IRtcEngine.SetDefaultMuteAllRemoteAudioStreams ( bool  mute )

Stops or resumes subscribing to the audio streams of all remote users by default.

Deprecated:
This method is deprecated from v3.3.1.

Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all subsequent users.

Note
If you need to resume subscribing to the audio streams of remote users in the channel after calling SetDefaultMuteAllRemoteAudioStreams(true), do the following.
Parameters
mute Sets whether to stop subscribing to the audio streams of all remote users by default.
  • true: Stop subscribing to the audio streams of all remote users by default.
  • false: (Default) Resume subscribing to the audio streams of all remote users by default.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetDefaultMuteAllRemoteVideoStreams()

int agora_gaming_rtc.IRtcEngine.SetDefaultMuteAllRemoteVideoStreams ( bool  mute )

Stops or resumes subscribing to the video streams of all remote users by default.

Deprecated:
This method is deprecated from v3.3.1.

Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the video streams of all subsequent users.

Note
If you need to resume subscribing to the video streams of remote users in the channel after calling SetDefaultMuteAllRemoteVideoStreams(true), do the following.
Parameters
mute Sets whether to stop subscribing to the video streams of all remote users by default.
  • true: Stop subscribing to the video streams of all remote users by default.
  • false: (Default) Resume subscribing to the video streams of all remote users by default.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetEnableSpeakerphone()

int agora_gaming_rtc.IRtcEngine.SetEnableSpeakerphone ( bool  speakerphone )

Enables/Disables the audio playback route to the speakerphone.

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

See the default audio route explanation in the SetDefaultAudioRouteToSpeakerphone method and check whether it is necessary to call this method.

On Android, settings of SetAudioProfile and SetChannelProfile affect the call result of SetEnableSpeakerphone. The following are scenarios where SetEnableSpeakerphone does not take effect:

  • If you set scenario as AUDIO_SCENARIO_GAME_STREAMING, no user can change the audio playback route.
  • If you set scenario as AUDIO_SCENARIO_DEFAULT or AUDIO_SCENARIO_SHOWROOM, the audience cannot change the audio playback route. If there is only one host is in the channel, the host cannot change the audio playback route either.
  • If you set scenario as AUDIO_SCENARIO_EDUCATION, the audience cannot change the audio playback route.
Note
  • This method is for Android and iOS only.
  • Ensure that you have successfully called the JoinChannelByKey method before calling this method.
  • After calling this method, the SDK returns the OnAudioRouteChangedHandler callback to indicate the changes.
  • This method does not take effect if a headset is used.
Parameters
speakerphone Sets whether to route the audio to the speakerphone or earpiece:
  • true: Route the audio to the speakerphone. If the playback device connects to the earpiece or Bluetooth, the audio cannot be routed to the speakerphone.
  • false: Route the audio to the earpiece. If a headset is plugged in, the audio is routed to the headset.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetEncryptionMode()

int agora_gaming_rtc.IRtcEngine.SetEncryptionMode ( string  encryptionMode )

Sets the built-in encryption mode.

Deprecated:
Deprecated as of v3.2.0. Use the EnableEncryption instead.

The Agora RTC SDK supports built-in encryption, which is set to the aes-128-xts mode by default. Call this method to use other encryption modes.

All users in the same channel must use the same encryption mode and password.

Refer to the information related to the AES encryption algorithm on the differences between the encryption modes.

Note
Call the SetEncryptionSecret method to enable the built-in encryption function before calling this method.
Parameters
encryptionMode The set encryption mode:
  • "aes-128-xts": (Default) 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 encryptionMode is set as null, the encryption mode is set as "aes-128-xts" by default.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetEncryptionSecret()

int agora_gaming_rtc.IRtcEngine.SetEncryptionSecret ( string  secret )

Enables built-in encryption with an encryption password before users join a channel.

Deprecated:
Deprecated as of v3.2.0. Use the EnableEncryption instead.

All users in a channel must use the same encryption password. The encryption password is automatically cleared once a user leaves the channel.

If an encryption password is not specified, the encryption functionality will be disabled.

Note
  • Do not use this method for CDN live streaming.
  • For optimal transmission, ensure that the encrypted data size does not exceed the original data size + 16 bytes. 16 bytes is the maximum padding size for AES encryption.
Parameters
secret The encryption password.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetExternalAudioSink()

int agora_gaming_rtc.IRtcEngine.SetExternalAudioSink ( bool  enabled,
int  sampleRate,
int  channels 
)

Sets the external audio sink. This method applies to scenarios where you want to use external audio data for playback. After enabling the external audio sink, you can call the PullAudioFrame method to pull the remote audio data, process it, and play it with the audio effects that you want.

Note
  • Once you enable the external audio sink, the app will not retrieve any audio data from the OnPlaybackAudioFrameHandler callback.
  • Ensure that you call this method before joining a channel.
Parameters
enabled
  • true: Enables the external audio sink.
  • false: (Default) Disables the external audio sink.
sampleRate Sets the sample rate (Hz) of the external audio sink, which can be set as 16000, 32000, 44100 or 48000.
channels Sets the number of audio channels of the external audio sink:
  • 1: Mono.
  • 2: Stereo.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetExternalAudioSource()

int agora_gaming_rtc.IRtcEngine.SetExternalAudioSource ( bool  enabled,
int  sampleRate,
int  channels 
)

Sets the external audio source. Please call this method before JoinChannelByKey.

Parameters
enabled Sets whether to enable/disable the external audio source:
  • true: Enables the external audio source.
  • false: (Default) Disables the external audio source.
sampleRate Sets the sample rate (Hz) of the external audio source, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channels Sets the number of audio channels of the external audio source:
  • 1: Mono.
  • 2: Stereo.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetExternalAudioSourceVolume()

int agora_gaming_rtc.IRtcEngine.SetExternalAudioSourceVolume ( int  sourcePos,
int  volume 
)

Sets the volume of the external audio frame in the specified position.

Since
v3.6.1.1

You can call this method multiple times to set the volume of external audio frames in different positions. The volume setting takes effect for all external audio frames that are pushed to the specified position.

Note
Call this method after joining a channel.
Parameters
sourcePos The push position of the external audio frame.
volume The volume of the external audio frame. The value range is [0,100]. The default value is 100, which represents the original value.
Returns
  • 0: Success.
  • < 0: Failure.
    • -2(ERR_INALID_ARGUMENT): The parameter is invalid.

◆ SetExternalVideoSource()

int agora_gaming_rtc.IRtcEngine.SetExternalVideoSource ( bool  enable,
bool  useTexture = false 
)

Configures the external video source.

Note
Ensure that you call this method before joining a channel.
Parameters
enable Sets whether to use the external video source:
  • true: Use the external video source.
  • false: (Default) Do not use the external video source.
useTexture Sets whether to use texture as an input (Agora does not support texture now, please use false):
  • true: Use texture as an input.
  • false: (Default) Do not use texture as an input.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetInEarMonitoringVolume()

int agora_gaming_rtc.IRtcEngine.SetInEarMonitoringVolume ( int  volume )

Sets the volume of the in-ear monitor.

Note
  • This method is for Android and iOS only.
  • Users must use wired earphones to hear their own voices.
  • You can call this method either before or after joining a channel.
Parameters
volume Sets the volume of the in-ear monitor. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetLiveTranscoding()

int agora_gaming_rtc.IRtcEngine.SetLiveTranscoding ( LiveTranscoding  transcoding )

Sets the video layout and audio settings for CDN live. (CDN live only.)

Deprecated:
This method is deprecated as of v3.6.1.1. See Release Notes for an alternative solution.

The SDK triggers the OnTranscodingUpdatedHandler callback when you call the SetLiveTranscoding method to update the transcoding setting.

Note
  • This method applies to Live Broadcast only.
  • Ensure that you enable the RTMP Converter service before using this function.
  • If you call the SetLiveTranscoding method to update the transcoding setting for the first time, the SDK does not trigger the OnTranscodingUpdatedHandler callback.
  • Ensure that you call this method after joining a channel.
  • Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.
Parameters
transcoding Sets the CDN live audio/video transcoding settings. See LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetLocalPublishFallbackOption()

int agora_gaming_rtc.IRtcEngine.SetLocalPublishFallbackOption ( STREAM_FALLBACK_OPTIONS  option )

Sets the fallback option for the locally published video stream based on the network conditions.

If option is set as STREAM_FALLBACK_OPTION_AUDIO_ONLY(2), the SDK will:

  • Disable the upstream video but enable audio only when the network conditions deteriorate and cannot support both video and audio.
  • Re-enable the video when the network conditions improve.

When the locally published video stream falls back to audio only or when the audio-only stream switches back to the video, the SDK triggers the OnLocalPublishFallbackToAudioOnlyHandler callback.

Note
  • Agora does not recommend using this method for CDN live streaming, because the remote CDN live user will have a noticeable lag when the locally published video stream falls back to audio only.
  • Ensure that you call this method before joining a channel.
Parameters
option Sets the fallback option for the locally published video stream. See STREAM_FALLBACK_OPTIONS.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetLocalVoiceChanger()

int agora_gaming_rtc.IRtcEngine.SetLocalVoiceChanger ( VOICE_CHANGER_PRESET  voiceChanger )

Sets the local voice changer option.

Deprecated:
Deprecated from v3.2.0. Use the following methods instead:
  • SetAudioEffectPreset: Audio effects.
  • SetVoiceBeautifierPreset: Voice beautifier effects.
  • SetVoiceConversionPreset: Voice conversion effects. This method can be used to set the local voice effect for users in a communication channel or hosts in the interactive live streaming channel. Voice changer options include the following voice effects:
  • VOICE_CHANGER_XXX: Changes the local voice to an old man, a little boy, or the Hulk. Applies to the voice talk scenario.
  • VOICE_BEAUTY_XXX: Beautifies the local voice by making it sound more vigorous, resounding, or adding spacial resonance. Applies to the voice talk and singing scenario.
  • GENERAL_BEAUTY_VOICE_XXX: Adds gender-based beautification effect to the local voice. Applies to the voice talk scenario.
    • For a male voice: Adds magnetism to the voice.
    • For a female voice: Adds freshness or vitality to the voice.
Note
  • To achieve better voice effect quality, Agora recommends setting the profile parameter in SetAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5).
  • This method works best with the human voice, and Agora does not recommend using it for audio containing music and a human voice.
  • Do not use this method with SetLocalVoiceReverbPreset, because the method called later overrides the one called earlier.
  • You can call this method either before or after joining a channel.
Parameters
voiceChanger Sets the local voice changer option. The default value is VOICE_CHANGER_OFF, which means the original voice. See details in VOICE_CHANGER_PRESET. Gender-based beatification effect works best only when assigned a proper gender:
  • For male: GENERAL_BEAUTY_VOICE_MALE_MAGNETIC
  • For female: GENERAL_BEAUTY_VOICE_FEMALE_FRESH or GENERAL_BEAUTY_VOICE_FEMALE_VITALITY Failure to do so can lead to voice distortion.
Returns
  • 0: Success.
  • < 0: Failure. Check if the enumeration is properly set.

◆ SetLocalVoiceEqualization()

int agora_gaming_rtc.IRtcEngine.SetLocalVoiceEqualization ( AUDIO_EQUALIZATION_BAND_FREQUENCY  bandFrequency,
int  bandGain 
)

Sets the local voice equalization effect.

Note
You can call this method either before or after joining a channel.
Parameters
bandFrequency Sets the band frequency. The value ranges between 0 and 9, representing the respective 10-band center frequencies of the voice effects, including 31, 62, 125, 500, 1k, 2k, 4k, 8k, and 16k Hz. See AUDIO_EQUALIZATION_BAND_FREQUENCY.
bandGain Sets the gain of each band in dB. The value ranges between -15 and 15.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetLocalVoicePitch()

int agora_gaming_rtc.IRtcEngine.SetLocalVoicePitch ( double  pitch )

Changes the voice pitch of the local speaker.

Parameters
pitch Sets the voice pitch. The value ranges between 0.5 and 2.0. The lower the value, the lower the voice pitch. The default value is 1.0 (no change to the local voice pitch).
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetLocalVoiceReverb()

int agora_gaming_rtc.IRtcEngine.SetLocalVoiceReverb ( AUDIO_REVERB_TYPE  reverbKey,
int  value 
)

Sets the local voice reverberation.

v2.4.0 adds the SetLocalVoiceReverbPreset method, a more user-friendly method for setting the local voice reverberation. You can use this method to set the local reverberation effect, such as pop music, R&B, rock music, and hip-hop.

Note
You can call this method either before or after joining a channel.
Parameters
reverbKey Sets the reverberation key. See AUDIO_REVERB_TYPE.
value Sets the value of the reverberation key.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetLocalVoiceReverbPreset()

int agora_gaming_rtc.IRtcEngine.SetLocalVoiceReverbPreset ( AUDIO_REVERB_PRESET  audioReverbPreset )

Sets the local voice reverberation option, including the virtual stereo.

Deprecated:
Deprecated from v3.2.0. Use SetAudioEffectPreset or SetVoiceBeautifierPreset instead.

This method sets the local voice reverberation for users in a communication channel or hosts in a Live-broadcast channel. After successfully calling this method, all users in the channel can hear the voice with reverberation.

Note
  • When calling this method with enumerations that begin with AUDIO_REVERB_FX, ensure that you set profile in SetAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5); otherwise, this methods cannot set the corresponding voice reverberation option.
  • When calling this method with AUDIO_VIRTUAL_STEREO, Agora recommends setting the profile parameter in SetAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5).
  • This method works best with the human voice, and Agora does not recommend using it for audio containing music and a human voice.
  • Do not use this method with SetLocalVoiceChanger, because the method called later overrides the one called earlier. For detailed considerations, see the advanced guide Voice Enhancement and Effects.
  • You can call this method either before or after joining a channel.
Parameters
audioReverbPreset The local voice reverberation option. The default value is AUDIO_REVERB_OFF, which means the original voice. See AUDIO_REVERB_PRESET. To achieve better voice effects, Agora recommends the enumeration whose name begins with AUDIO_REVERB_FX.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetLogFile()

int agora_gaming_rtc.IRtcEngine.SetLogFile ( string  filePath )

Sets the log files that the SDK outputs.

Deprecated:
This method is deprecated from v3.3.1. Use logConfig in the GetEngine method instead.

By default, the SDK outputs five log files, agorasdk.log, agorasdk_1.log, agorasdk_2.log, agorasdk_3.log, agorasdk_4.log, each with a default size of 1024 KB. These log files are encoded in UTF-8. The SDK writes the latest logs in agorasdk.log. When agorasdk.log is full, the SDK deletes the log file with the earliest modification time among the other four, renames agorasdk.log to the name of the deleted log file, and create a new agorasdk.log to record latest logs.

Note
Ensure that you call this method immediately after calling GetEngine, otherwise the output logs may not be complete.
See also
SetLogFileSize
SetLogFilter
Parameters
filePath The absolute path of log files. The default file path is C: \Users\<user_name>\AppData\Local\Agora\<process_name>\agorasdk.log. Ensure that the directory for the log files exists and is writable. You can use this parameter to rename the log files.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetLogFileSize()

int agora_gaming_rtc.IRtcEngine.SetLogFileSize ( uint  fileSizeInKBytes )

Sets the size of a log file that the SDK outputs.

Deprecated:
This method is deprecated from v3.3.1. Use logConfig in the GetEngine method instead.
Note
If you want to set the log file size, ensure that you call this method before SetLogFile, or the logs are cleared.

By default, the SDK outputs five log files, agorasdk.log, agorasdk_1.log, agorasdk_2.log, agorasdk_3.log, agorasdk_4.log, each with a default size of 1024 KB. These log files are encoded in UTF-8. The SDK writes the latest logs in agorasdk.log. When agorasdk.log is full, the SDK deletes the log file with the earliest modification time among the other four, renames agorasdk.log to the name of the deleted log file, and create a new agorasdk.log to record latest logs.

See also
SetLogFile
SetLogFilter
Parameters
fileSizeInKBytes The size (KB) of a log file. The default value is 1024 KB. If you set fileSizeInKByte to 1024 KB, the SDK outputs at most 5 MB log files; if you set it to less than 1024 KB, the maximum size of a log file is still 1024 KB.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetLogFilter()

int agora_gaming_rtc.IRtcEngine.SetLogFilter ( LOG_FILTER  filter )

Sets the output log level of the SDK.

Deprecated:
This method is deprecated from v3.3.1. Use logConfig in the GetEngine method instead.

You can use one or a combination of the log filter levels. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG. Choose a level to see the logs preceding that level.

For example, when you set the log level to WARNING, you can see the logs within levels CRITICAL, ERROR, and WARNING.

See also
SetLogFile
SetLogFileSize
Parameters
filter Sets the log filter level. See LOG_FILTER.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetLowlightEnhanceOptions()

int agora_gaming_rtc.IRtcEngine.SetLowlightEnhanceOptions ( bool  enabled,
LowLightEnhanceOptions  options 
)

Sets low-light enhancement.

Since
3.6.2

The low-light enhancement feature can adaptively adjust the brightness value of the video captured in situations with low or uneven lighting, such as backlit, cloudy, or dark scenes. It restores or highlights the image details and improves the overall visual effect of the video.

You can call this method to enable the low-light enhancement feature and set the options of the low-light enhancement effect.

Note
  • Call this method after EnableVideo.
  • The low-light enhancement feature has certain performance requirements on devices. If your device overheats after you enable low-light enhancement, Agora recommends modifying the low-light enhancement options to a less performance-consuming level or disabling low-light enhancement entirely.
Parameters
enabled Whether to enable low-light enhancement:
  • true: Yes.
  • false: No.
options The low-light enhancement options. See LowLightEnhanceOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetMirrorApplied()

int agora_gaming_rtc.IRtcEngine.SetMirrorApplied ( bool  wheatherApply )

Sets whether to enable the mirror mode of both local video and remote video.

Note
Call this method before EnableVideoObserver.
Parameters
wheatherApply Sets whether to enable the mirror mode of both local video and remote video.
  • true: Enable the mirror mode.
  • false: (Default) Disable the mirror mode.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetMixedAudioFrameParameters()

int agora_gaming_rtc.IRtcEngine.SetMixedAudioFrameParameters ( int  sampleRate,
int  samplesPerCall 
)

Sets the mixed audio format for the OnMixedAudioFrameHandler callback.

Note
  • The SDK calculates the sample interval according to the value of the channels of AudioFrame, sampleRate, and samplesPerCall parameters you set in this method. Sample interval (sec) = samplePerCall/(sampleRate × channels). Ensure that the value of sample interval is no less than 0.01. The SDK triggers the OnMixedAudioFrameHandler callback according to the sample interval.
  • Ensure that you call this method before joining a channel.
Parameters
sampleRate Sets the sample rate (samplesPerSec) returned in the OnMixedAudioFrameHandler callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
samplesPerCall Sets the number of samples the OnMixedAudioFrameHandler callback returns. Set it as 1024 for RTMP or RTMPS streaming.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetMultiChannelWant()

int agora_gaming_rtc.IRtcEngine.SetMultiChannelWant ( bool  multiChannelWant )

Sets whether to enable the multi-channel mode.

Since
v3.0.1

In multi-channel video scenarios, you must call this method to enable the multi-channel mode. Otherwise, a user cannot receive video frames from multiple channels.

Note
  • Call this method before joining a channel.
  • In voice-only scenarios, you do not need to call this method.
Parameters
multiChannelWant Whether to enable the multi-channel mode:
  • true: Enable the multi-channel mode
  • false: (Default) Disable the multi-channel mode.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetParameters()

int agora_gaming_rtc.IRtcEngine.SetParameters ( string  parameters )

Provides the technical preview functionalities or special customizations by configuring the SDK with JSON options.

Parameters
parameters The set parameters in a JSON string.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetPlaybackAudioFrameParameters()

int agora_gaming_rtc.IRtcEngine.SetPlaybackAudioFrameParameters ( int  sampleRate,
int  channel,
RAW_AUDIO_FRAME_OP_MODE_TYPE  mode,
int  samplesPerCall 
)

Sets the audio playback format for the OnPlaybackAudioFrameHandler callback.

Note
  • The SDK calculates the sample interval according to the value of the sampleRate, channel, and samplesPerCall parameters you set in this method. Sample interval (sec) = samplePerCall/(sampleRate × channel). Ensure that the value of sample interval is no less than 0.01. The SDK triggers the OnPlaybackAudioFrameHandler callback according to the sample interval.
  • Ensure that you call this method before joining a channel.
Parameters
sampleRate Sets the sample rate returned in the OnPlaybackAudioFrameHandler callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channel Sets the number of channels returned in the OnPlaybackAudioFrameHandler callback:
  • 1: Mono
  • 2: Stereo
mode Sets the use mode (see RAW_AUDIO_FRAME_OP_MODE_TYPE) of the OnPlaybackAudioFrameHandler callback.
samplesPerCall Sets the number of samples the OnPlaybackAudioFrameHandler callback returns. Set it as 1024 for RTMP or RTMPS streaming.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetRecordingAudioFrameParameters()

int agora_gaming_rtc.IRtcEngine.SetRecordingAudioFrameParameters ( int  sampleRate,
int  channel,
RAW_AUDIO_FRAME_OP_MODE_TYPE  mode,
int  samplesPerCall 
)

Sets the audio capturing format for the OnRecordAudioFrameHandler callback.

Note
  • The SDK calculates the sample interval according to the value of the sampleRate, channel, and samplesPerCall parameters you set in this method. Sample interval (sec) = samplePerCall/(sampleRate × channel). Ensure that the value of sample interval is no less than 0.01. The SDK triggers the OnRecordAudioFrameHandler callback according to the sample interval.
  • Ensure that you call this method before joining a channel.
Parameters
sampleRate Sets the sample rate returned in the OnRecordAudioFrameHandler callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channel Sets the number of audio channels returned in the OnRecordAudioFrameHandler callback:
  • 1: Mono
  • 2: Stereo
mode Sets the use mode (see RAW_AUDIO_FRAME_OP_MODE_TYPE) of the OnRecordAudioFrameHandler callback.
samplesPerCall Sets the number of samples the OnRecordAudioFrameHandler callback returns. Set it as 1024 for RTMP or RTMPS streaming.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetRemoteDefaultVideoStreamType()

int agora_gaming_rtc.IRtcEngine.SetRemoteDefaultVideoStreamType ( REMOTE_VIDEO_STREAM_TYPE  remoteVideoStreamType )

Sets the default video-stream type for the video received by the local user when the remote user sends dual streams.

  • If the dual-stream mode is enabled by calling the EnableDualStreamMode method, the user receives the high-stream video by default. The SetRemoteDefaultVideoStreamType method allows the application to adjust the corresponding video-stream type according to the size of the video window, reducing the bandwidth and resources.
  • If the dual-stream mode is not enabled, the user receives the high-stream video by default.

The result after calling this method is returned in the OnApiExecutedHandler callback. The Agora RTC SDK receives the high-stream video by default to reduce the bandwidth. If needed, users can switch to the low-stream video through this method.

Note
You can call this method either before or after joining a channel. If you call both SetRemoteDefaultVideoStreamType and SetRemoteVideoStreamType, the SDK applies the settings in the SetRemoteVideoStreamType.
Parameters
remoteVideoStreamType Sets the default video-stream type. See REMOTE_VIDEO_STREAM_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetRemoteSubscribeFallbackOption()

int agora_gaming_rtc.IRtcEngine.SetRemoteSubscribeFallbackOption ( STREAM_FALLBACK_OPTIONS  option )

Sets the fallback option for the remotely subscribed video stream based on the network conditions.

The default setting for option is STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW(1), where the remotely subscribed video stream falls back to the low-stream video (low resolution and low bitrate) under poor downlink network conditions.

If option is set as STREAM_FALLBACK_OPTION_AUDIO_ONLY(2), the SDK automatically switches the video from a high-stream to a low-stream, or disables the video when the downlink network conditions cannot support both audio and video to guarantee the quality of the audio. The SDK monitors the network quality and restores the video stream when the network conditions improve.

When the remotely subscribed video stream falls back to audio only or when the audio-only stream switches back to the video stream, the SDK triggers the OnRemoteSubscribeFallbackToAudioOnlyHandler callback.

Note
Ensure that you call this method before joining a channel.
Parameters
option Sets the fallback option for the remotely subscribed video stream. See STREAM_FALLBACK_OPTIONS.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetRemoteUserPriority()

int agora_gaming_rtc.IRtcEngine.SetRemoteUserPriority ( uint  uid,
PRIORITY_TYPE  userPriority 
)

Prioritizes a remote user's stream.

Use this method with the SetRemoteSubscribeFallbackOption method. If the fallback function is enabled for a subscribed stream, the SDK ensures the high-priority user gets the best possible stream quality.

Note
  • The Agora RTC SDK supports setting userPriority as high for one user only.
  • Ensure that you call this method before joining a channel.
Parameters
uid The ID of the remote user.
userPriority Sets the priority of the remote user. See PRIORITY_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetRemoteVideoStreamType()

int agora_gaming_rtc.IRtcEngine.SetRemoteVideoStreamType ( uint  uid,
REMOTE_VIDEO_STREAM_TYPE  streamType 
)

Sets the stream type of the remote video.

Under limited network conditions, if the publisher has not disabled the dual-stream mode using EnableDualStreamMode(false), the receiver can choose to receive either the high-quality video stream (the high resolution, and high bitrate video stream) or the low-video stream (the low resolution, and low bitrate video stream).

By default, users receive the high-quality video stream. Call this method if you want to switch to the low-video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources.

The aspect ratio of the low-video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-video stream.

The method result returns in the OnApiExecutedHandler callback.

Note
You can call this method either before or after joining a channel. If you call both SetRemoteVideoStreamType and SetRemoteDefaultVideoStreamType, the SDK applies the settings in the SetRemoteVideoStreamType.
Parameters
uid ID of the remote user sending the video stream.
streamType Sets the video-stream type. See REMOTE_VIDEO_STREAM_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetScreenCaptureContentHint()

int agora_gaming_rtc.IRtcEngine.SetScreenCaptureContentHint ( VideoContentHint  videoContentHint )

Sets the content hint for screen sharing.

A content hint suggests the type of the content being shared, so that the SDK applies different optimization algorithm to different types of content.

Note
  • This method is for Windows and macOS only.
  • You can call this method either before or after you start screen sharing.
Parameters
videoContentHint Sets the content hint for screen sharing. See VideoContentHint.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetScreenCaptureScenario()

int agora_gaming_rtc.IRtcEngine.SetScreenCaptureScenario ( int  screenScenario )

Sets the screen sharing scenario.

Since
3.7.0

When you start screen sharing or window sharing, you can call this method to set the screen sharing scenario. The SDK adjusts the video quality and experience of the sharing according to the scenario.

Note
This method applies to macOS and Windows only.
Parameters
screenScenario The screen sharing scenario. See SCREEN_SCENARIO_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetSpeakerphoneVolume()

int agora_gaming_rtc.IRtcEngine.SetSpeakerphoneVolume ( int  volume )

Set the volume of the speaker. (macOS only.)

Deprecated:
This method is deprecated as of v2.3.0. Use AdjustRecordingSignalVolume and AdjustPlaybackSignalVolume instead.
Parameters
volume Sets the speakerphone volume. The value ranges between 0 (lowest volume) and 255 (highest volume).
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetVideoDenoiserOptions()

int agora_gaming_rtc.IRtcEngine.SetVideoDenoiserOptions ( bool  enabled,
VideoDenoiserOptions  options 
)

Sets video noise reduction.

Since
3.6.2

Underlit environments and low-end video capture devices can cause video images to contain significant noise, which affects video quality. In real-time interactive scenarios, video noise also consumes bitstream resources and reduces encoding efficiency during encoding.

You can call this method to enable the video noise reduction feature and set the options of the video noise reduction effect.

Note
  • Call this method before EnableVideo.
  • The video noise reduction feature has certain performance requirements on devices. If your device overheats after you enable video noise reduction, Agora recommends modifying the video noise reduction options to a less performance-consuming level or disabling video noise reduction entirely.
Parameters
enabled Whether to enable video noise reduction:
  • true: Enable.
  • false: (Default) Disable.
options The video reduction options. See VideoDenoiserOptions.
Returns
  • 0: Success. &lt 0: Failure.

◆ SetVideoEncoderConfiguration()

int agora_gaming_rtc.IRtcEngine.SetVideoEncoderConfiguration ( VideoEncoderConfiguration  configuration )

Sets the video encoder configuration.

Each video encoder configuration corresponds to a set of video parameters, including the resolution, frame rate, bitrate, and video orientation.

The parameters specified in this method are the maximum values under ideal network conditions. If the video engine cannot render the video using the specified parameters due to poor network conditions, the parameters further down the list are considered until a successful configuration is found.

Note
  • You can call this method either before or after joining a channel.
  • If you do not need to set the video encoder configuration after joining the channel, you can call this method before the EnableVideo method to reduce the render time of the first video frame.
Parameters
configuration Sets the local video encoder configuration. See VideoEncoderConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetVideoProfile()

int agora_gaming_rtc.IRtcEngine.SetVideoProfile ( VIDEO_PROFILE_TYPE  profile,
bool  swapWidthAndHeight = false 
)

Sets the video profile.

Deprecated:
This method is deprecated as of v2.3. Use the SetVideoEncoderConfiguration method instead.

Each video profile includes a set of parameters, such as the resolution, frame rate, and bitrate. If the camera device does not support the specified resolution, the SDK automatically chooses a suitable camera resolution, keeping the encoder resolution specified by the setVideoProfile method.

Note
  • If you do not need to set the video profile after joining the channel, call this method before the EnableVideo method to reduce the render time of the first video frame.
  • Always set the video profile before calling the JoinChannelByKey or StartPreview method.
  • Since the landscape or portrait mode of the output video can be decided directly by the video profile, We recommend setting swapWidthAndHeight to false (default).
Parameters
profile Sets the video profile. See VIDEO_PROFILE_TYPE.
swapWidthAndHeight Sets whether to swap the width and height of the video stream:
  • true: Swap the width and height.
  • false: (Default) Do not swap the width and height. The width and height of the output video are consistent with the set video profile.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetVideoQualityParameters()

int agora_gaming_rtc.IRtcEngine.SetVideoQualityParameters ( bool  preferFrameRateOverImageQuality )

Sets the preferences for the high-quality video. (Interactive live streaming only).

Deprecated:
This method is deprecated as of v2.4.0.
Parameters
preferFrameRateOverImageQuality Sets the video quality preference:
  • true: Frame rate over image quality.
  • false: (Default) Image quality over frame rate.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetVoiceBeautifierParameters()

int agora_gaming_rtc.IRtcEngine.SetVoiceBeautifierParameters ( VOICE_BEAUTIFIER_PRESET  preset,
int  param1,
int  param2 
)

Sets parameters for SDK preset voice beautifier effects.

Since
v3.3.1

Call this method to set a gender characteristic and a reverberation effect for the singing beautifier effect. This method sets parameters for the local user who sends an audio stream. See Set the Voice Effect.

After you call this method successfully, all users in the channel can hear the relevant effect.

To achieve better audio effect quality, before you call this method, Agora recommends calling SetAudioProfile, and setting the scenario parameter as AUDIO_SCENARIO_GAME_STREAMING(3) and the profile parameter as AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5).

Note
Parameters
preset The options for SDK preset voice beautifier effects:
  • SINGING_BEAUTIFIER: Singing beautifier effect.
param1 The gender characteristics options for the singing voice:
  • 1: A male-sounding voice.
  • 2: A female-sounding voice.
param2 The reverberation effects options:
  • 1: The reverberation effect sounds like singing in a small room.
  • 2: The reverberation effect sounds like singing in a large room.
  • 3: The reverberation effect sounds like singing in a hall.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetVoiceBeautifierPreset()

int agora_gaming_rtc.IRtcEngine.SetVoiceBeautifierPreset ( VOICE_BEAUTIFIER_PRESET  preset )

Sets an SDK preset voice beautifier effect.

Since
v3.2.0

Call this method to set an SDK preset voice beautifier effect for the local user who sends an audio stream. After setting a voice beautifier effect, all users in the channel can hear the effect.

You can set different voice beautifier effects for different scenarios. See Set the Voice Effect.

To achieve better audio effect quality, Agora recommends calling SetAudioProfile and setting the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING(3) and the profile parameter to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before calling this method.

Note
Parameters
preset The options for SDK preset voice beautifier effects: VOICE_BEAUTIFIER_PRESET.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetVoiceConversionPreset()

int agora_gaming_rtc.IRtcEngine.SetVoiceConversionPreset ( VOICE_CONVERSION_PRESET  preset )

Sets an SDK preset voice conversion effect.

Since
v3.3.1

Call this method to set an SDK preset voice conversion effect for the local user who sends an audio stream. After setting a voice conversion effect, all users in the channel can hear the effect.

You can set different voice conversion effects for different scenarios. See Set the Voice Effect.

To achieve better voice effect quality, Agora recommends calling SetAudioProfile and setting the profile parameter to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) and the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING(3) before calling this method.

Note
Parameters
preset The options for SDK preset voice conversion effects: VOICE_CONVERSION_PRESET.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SetVolumeOfEffect()

int agora_gaming_rtc.IRtcEngine.SetVolumeOfEffect ( int  soundId,
int  volume 
)

Sets the volume of a specified audio effect.

Note
Ensure that this method is called after PlayEffect.
Parameters
soundId ID of the audio effect. Each audio effect has a unique ID.
volume Sets the volume of the specified audio effect. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ StartAudioMixing() [1/2]

int agora_gaming_rtc.IRtcEngine.StartAudioMixing ( string  filePath,
bool  loopback,
bool  replace,
int  cycle 
)

Starts playing and mixing the music file.

This method mixes the specified local audio file with the audio stream from the microphone, or 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 playback loops. This method also supports online music playback.

When the audio mixing file playback finishes after calling this method, the SDK triggers the OnAudioMixingFinishedHandler callback.

A successful StartAudioMixing method call triggers the OnAudioMixingStateChangedHandler(PLAYING) callback on the local client.

When the audio mixing file playback finishes, the SDK triggers the OnAudioMixingStateChangedHandler(STOPPED) callback on the local client.

Note
  • Call this method when you are in a channel.
  • If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns WARN_AUDIO_MIXING_OPEN_ERROR(701).
  • On Android, if you set filePath as an HTTP URL, ensure that you add android:usesCleartextTraffic="true" in the <application> tag in the project AndroidManifest.xml file.
Parameters
filePath The absolute path (including the suffixes of the filename) of the local or online audio file to mix. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav. For more information, see Supported Media Formats in Media Foundation.
loopback Sets which user can hear the audio mixing:
  • true: Only the local user can hear the audio mixing.
  • false: Both users can hear the audio mixing.
replace Sets the audio mixing content:
  • true: Only the specified audio file is published; the audio stream received by the microphone is not published.
  • false: The local audio file is mixed with the audio stream from the microphone.
cycle Sets the number of playback loops:
  • Positive integer: Number of playback loops.
  • -1: Infinite playback loops.
Returns
  • 0: Success.
  • < 0: Failure.

◆ StartAudioMixing() [2/2]

int agora_gaming_rtc.IRtcEngine.StartAudioMixing ( string  filePath,
bool  loopback,
bool  replace,
int  cycle,
int  startPos 
)

Starts playing and mixing the music file.

This method supports mixing or replacing local or online music file and audio collected by a microphone. After successfully playing the music file, the SDK triggers OnAudioMixingStateChangedHandler(AUDIO_MIXING_STATE_PLAYING, AUDIO_MIXING_REASON_STARTED_BY_USER). After completing playing the music file, the SDK triggers OnAudioMixingStateChangedHandler(AUDIO_MIXING_STATE_STOPPED, AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED).

Note
  • To use this method, ensure that the Android device is v4.2 or later and the API version is v16 or later.
  • If you need to play an online music file, Agora does not recommend using the redirected URL address. Some Android devices may fail to open a redirected URL address.
  • On Android, if you set filePath as an HTTP URL, ensure that you add android:usesCleartextTraffic="true" in the <application> tag in the project AndroidManifest.xml file.
  • If the local music file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns WARN_AUDIO_MIXING_OPEN_ERROR(701).
Parameters
filePath The file path, including the filename extensions. To access an online file, Agora supports using a URL address; to access a local file, Agora supports using a URI address, an absolute path, or a path that starts with /assets/.
loopback Whether to only play the music file on the local client:
  • true: Only play the music file on the local client so that only the local user can hear the music.
  • false: Publish the music file to remote clients so that both the local user and remote users can hear the music.
replace Whether to replace the audio collected by the microphone with a music file:
  • true: Replace. Users can only hear music.
  • false: Do not replace. Users can hear both music and audio collected by the microphone.
cycle The number of times the music file plays.
  • ≥ 0: The number of playback times. For example, 0 means that the SDK does not play the music file, while 1 means that the SDK plays the music file once.
  • -1: Play the music in an indefinite loop.
startPos The playback position (ms) of the music file.
Returns
  • 0: Success.
  • < 0: Failure.

◆ StartAudioRecording() [1/3]

int agora_gaming_rtc.IRtcEngine.StartAudioRecording ( AudioRecordingConfiguration  config )

Starts an audio recording on the client.

Since
3.4.0

The SDK allows recording audio during a call. After successfully calling this method, you can record the audio of users in the channel and get an audio recording file. Supported file formats are as follows:

  • WAV: High-fidelity files with typically larger file sizes. For example, if the sample rate is 32,000 Hz, the file size for a 10-minute recording is approximately 73 MB.
  • AAC: Low-fidelity files with typically smaller file sizes. For example, if the sample rate is 32,000 Hz and the recording quality is AUDIO_RECORDING_QUALITY_MEDIUM, the file size for a 10-minute recording is approximately 2 MB.

Once the user leaves the channel, the recording automatically stops.

Note
Call this method after joining a channel.
Parameters
config The recording configuration. See AudioRecordingConfiguration
Returns
  • 0: Success.
  • < 0: Failure.
    • -160(ERR_ALREADY_IN_RECORDING): The client is already recording audio. To start a new recording, call stopRecording to stop the current recording and then call this method again.

◆ StartAudioRecording() [2/3]

int agora_gaming_rtc.IRtcEngine.StartAudioRecording ( string  filePath,
AUDIO_RECORDING_QUALITY_TYPE  quality 
)

Starts an audio recording.

Deprecated:
Use StartAudioRecording2 instead.

The SDK allows recording during a call. Supported formats:

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

This method has a fixed sample rate of 32 kHz.

  • Ensure that the directory to save the recording file exists and is writable.
  • This method is usually called after the JoinChannelByKey method.
  • The recording automatically stops when the LeaveChannel method is called.
Parameters
filePath Pointer to the absolute file path of the recording file. The string of the file name is in UTF-8.
quality Sets the audio recording quality. See AUDIO_RECORDING_QUALITY_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ StartAudioRecording() [3/3]

int agora_gaming_rtc.IRtcEngine.StartAudioRecording ( string  filePath,
int  sampleRate,
AUDIO_RECORDING_QUALITY_TYPE  quality 
)

Starts an audio recording on the client.

The SDK allows recording during a call. After successfully calling this method, you can record the audio of all the users in the channel and get an audio recording file. Supported formats of the recording file are as follows:

  • .wav: Large file size with high fidelity.
  • .aac: Small file size with low fidelity.
Note
Parameters
filePath Pointer to the absolute file path of the recording file. The string of the file name is in UTF-8.
sampleRate Sample rate (Hz) of the recording file. Supported values are as follows:
  • 16000
  • (Default) 32000
  • 44100
  • 48000
quality Sets the audio recording quality. See AUDIO_RECORDING_QUALITY_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ StartChannelMediaRelay()

int agora_gaming_rtc.IRtcEngine.StartChannelMediaRelay ( ChannelMediaRelayConfiguration  mediaRelayConfiguration )

Starts to relay media streams across channels.

After a successful method call, the SDK triggers the OnChannelMediaRelayStateChangedHandler and OnChannelMediaRelayEventHandler callbacks, and these callbacks return the state and events of the media stream relay.

Note
  • Call this method after the JoinChannelByKey method.
  • This method takes effect only when you are a host in a Live-broadcast channel.
  • After a successful method call, if you want to call this method again, ensure that you call the StopChannelMediaRelay method to quit the current relay.
Parameters
mediaRelayConfiguration The configuration of the media stream relay: ChannelMediaRelayConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ StartEchoTest() [1/3]

int agora_gaming_rtc.IRtcEngine.StartEchoTest ( )

Starts an audio call test.

Deprecated:
This method is deprecated as of v2.4.0.

This method starts an audio call test to check whether the audio devices (for example, headset and speaker) and the network connection are working properly.

To conduct the test:

  • The user speaks and the capturing is played back within 10 seconds.
  • If the user can hear the capturing within 10 seconds, the audio devices and network connection are working properly.
Note
  • After calling this method, always call the StopEchoTest method to end the test. Otherwise, the application cannot run the next echo test.
  • In the Live-broadcast profile, only the hosts can call this method. If the user switches from the Communication to Live-broadcast profile, the user must call the SetClientRole method to change the user role from the audience (default) to the host before calling this method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ StartEchoTest() [2/3]

int agora_gaming_rtc.IRtcEngine.StartEchoTest ( EchoTestConfiguration  config )

Starts an audio and video call loop test.

Since
v3.6.1.1

Before joining a channel, to test whether the user's local sending and receiving streams are normal, you can call this method to perform an audio and video call loop test, which tests whether the audio and video devices and the user's upstream and downstream networks are working properly.

After starting the test, the user needs to make a sound or face the camera. The audio or video is output after about two seconds. If the audio playback is normal, the audio device and the user's upstream and downstream networks are working properly; if the video playback is normal, the video device and the user's upstream and downstream networks are working properly.

Note
  • Call this method before joining a channel.
  • After calling this method, call StopEchoTest to end the test; otherwise, the user cannot perform the next audio and video call loop test and cannot join the channel.
  • In the LIVE_BROADCASTING profile, only a host can call this method.
Parameters
config The configuration of the audio and video call loop test, see EchoTestConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ StartEchoTest() [3/3]

int agora_gaming_rtc.IRtcEngine.StartEchoTest ( int  intervalInSeconds )

Starts an audio call test.

This method starts an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly.

In the audio call test, you record your voice. If the capturing plays back within the set time interval, the audio devices and the network connection are working properly.

Note
  • Call this method before joining a channel.
  • After calling this method, call the StopEchoTest method to end the test. Otherwise, the app cannot run the next echo test, or call the JoinChannelByKey method.
  • In the Live-broadcast profile, only a host can call this method.
Parameters
intervalInSeconds The time interval (sec) between when you speak and when the capturing plays back.
Returns
  • 0: Success.
  • < 0: Failure.

◆ StartLastmileProbeTest()

int agora_gaming_rtc.IRtcEngine.StartLastmileProbeTest ( LastmileProbeConfig  lastmileProbeConfig )

Starts the last-mile network probe test before joining a channel to get the uplink and downlink last-mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT).

Once this method is enabled, the SDK returns the following callbacks:

  • OnLastmileQualityHandler: the SDK triggers this callback within two seconds depending on the network conditions. This callback rates the network conditions and is more closely linked to the user experience.
  • OnLastmileProbeResultHandler: the SDK triggers this callback within 30 seconds depending on the network conditions. This callback returns the real-time statistics of the network conditions and is more objective.

Call this method to check the uplink network quality before users join a channel or before an audience switches to a host.

Note
  • This method consumes extra network traffic and may affect communication quality. We do not recommend calling this method together with EnableLastmileTest.
  • Do not call other methods before receiving the OnLastmileQualityHandler and OnLastmileProbeResultHandler callbacks. Otherwise, the callbacks may be interrupted.
  • In the Live-broadcast profile, a host should not call this method after joining a channel.
Parameters
lastmileProbeConfig Sets the configurations of the last-mile network probe test. See LastmileProbeConfig.
Returns
  • 0: Success.
  • < 0: Failure.

◆ StartPreview()

int agora_gaming_rtc.IRtcEngine.StartPreview ( )

Starts the local video preview before joining the channel.

Before calling this method, you must call the EnableVideo method to enable video.

Note
Once the StartPreview method is called to start the local video preview, if you leave the channel by calling the LeaveChannel method, the local video preview remains until you call the StopPreview method to disable it.
Returns
  • 0: Success.
  • < 0: Failure.

◆ StartRtmpStreamWithoutTranscoding()

int agora_gaming_rtc.IRtcEngine.StartRtmpStreamWithoutTranscoding ( string  url )

Starts pushing media streams to a CDN without transcoding.

Since
v3.6.1.1

You can call this method to push a live audio-and-video stream to the specified CDN address. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times.

After you call this method, the SDK triggers the OnRtmpStreamingStateChangedHandler callback on the local client to report the state of the streaming.

Note
  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in Media Push.
  • Call this method after joining a channel.
  • Only hosts in the LIVE_BROADCASTING profile can call this method.
  • If you want to retry pushing streams after a failed push, make sure to call StopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push.
  • If you want to push media streams in the RTMPS protocol to CDN, call StartRtmpStreamWithTranscoding instead of StartRtmpStreamWithoutTranscoding.
Parameters
url The address of the CDN live streaming. The format is RTMP. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_INVALID_ARGUMENT (2): The RTMP URL address is NULL or the string length is 0.
    • ERR_NOT_INITIALIZED (7): The SDK is not initialized before calling this method.

◆ StartRtmpStreamWithTranscoding()

int agora_gaming_rtc.IRtcEngine.StartRtmpStreamWithTranscoding ( string  url,
LiveTranscoding  transcoding 
)

Starts pushing media streams to a CDN and sets the transcoding configuration.

Since
v3.6.1.1

You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times.

After you call this method, the SDK triggers the OnRtmpStreamingStateChangedHandler callback on the local client to report the state of the streaming.

Note
  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in Push Streams to CDN.
  • Call this method after joining a channel.
  • Only hosts in the LIVE_BROADCASTING profile can call this method.
  • If you want to retry pushing streams after a failed push, make sure to call StopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push.
  • If you want to push media streams in the RTMPS protocol to CDN, call StartRtmpStreamWithTranscoding instead of StartRtmpStreamWithoutTranscoding.
Parameters
url The address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.
transcoding The transcoding configuration for CDN live streaming. See LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ StartScreenCaptureByDisplayId()

int agora_gaming_rtc.IRtcEngine.StartScreenCaptureByDisplayId ( uint  displayId,
Rectangle  rectangle,
ScreenCaptureParameters  screenCaptureParameters 
)

Shares the whole or part of a screen by specifying the display ID.

Note
  • This method is for macOS and Windows only.
  • Ensure that you call this method after joining a channel.
Warning
On Windows platforms, if the user device is connected to another display, to avoid screen sharing issues, use StartScreenCaptureByDisplayId to start sharing instead of using StartScreenCaptureByScreenRect.
Parameters
displayId The display ID of the screen to be shared. This parameter specifies which screen you want to share.
rectangle (Optional) Sets the relative location of the region to the screen. null means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen.
screenCaptureParameters Sets the screen sharing encoding parameters. The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of videoDimension to calculate the charges. For details, see descriptions in ScreenCaptureParameters.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_INVALID_STATE: the screen sharing state is invalid, probably because another screen or window is being shared. Call StopScreenCapture to stop the current screen sharing.
    • ERR_INVALID_ARGUMENT(-2): the argument is invalid.

◆ StartScreenCaptureByScreenRect()

int agora_gaming_rtc.IRtcEngine.StartScreenCaptureByScreenRect ( Rectangle  screenRectangle,
Rectangle  regionRectangle,
ScreenCaptureParameters  screenCaptureParameters 
)

Shares the whole or part of a screen by specifying the screen rect.

Note
  • This method is for Windows only.
  • Ensure that you call this method after joining a channel.
Parameters
screenRectangle Sets the relative location of the screen to the virtual screen.
regionRectangle (Optional) Sets the relative location of the region to the screen. null means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen.
screenCaptureParameters Sets the screen sharing encoding parameters. The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of videoDimension to calculate the charges. For details, see descriptions in ScreenCaptureParameters.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_INVALID_STATE: the screen sharing state is invalid, probably because another screen or window is being shared. Call StopScreenCapture to stop the current screen sharing.
    • ERR_INVALID_ARGUMENT(-2): the argument is invalid.

◆ StartScreenCaptureByWindowId()

int agora_gaming_rtc.IRtcEngine.StartScreenCaptureByWindowId ( int  windowId,
Rectangle  regionRect,
ScreenCaptureParameters  screenCaptureParameters 
)

Shares the whole or part of a window by specifying the window ID.

Note
  • Ensure that you call this method after joining a channel.
  • Applies to the macOS and Windows platforms only.

Since v3.0.0, this method supports window sharing of UWP (Universal Windows Platform) applications.

Agora tests the mainstream UWP applications by using the lastest SDK, see details as follows:

OS version Software Software name Whether support
win10 Chrome 76.0.3809.100 No
Office Word 18.1903.1152.0 Yes
Office Excel No
Office PPT Yes
WPS Word 11.1.0.9145 Yes
WPS Excel
WPS PPT
Media Player (come with the system) All Yes
win8 Chrome All Yes
Office Word All Yes
Office Excel
Office PPT
WPS Word 11.1.0.9098 Yes
WPS Excel
WPS PPT
Media Player(come with the system) All Yes
win7 Chrome 73.0.3683.103 No
Office Word All Yes
Office Excel
Office PPT
WPS Word 11.1.0.9098 No
WPS Excel
WPS PPT 11.1.0.9098 Yes
Media Player(come with the system) All No
Parameters
windowId The ID of the window to be shared. For information on how to get the windowId, see the advanced guide Share Screen.
regionRect (Optional) The relative location of the region to the window. NULL/NIL means sharing the whole window. See Rectangle. If the specified region overruns the window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole window.
screenCaptureParameters The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of videoDimension to calculate the charges. For details, see descriptions in ScreenCaptureParameters.
Returns
  • 0: Success.
  • < 0: Failure:
    • ERR_INVALID_ARGUMENT: The argument is invalid.

◆ StopAudioMixing()

int agora_gaming_rtc.IRtcEngine.StopAudioMixing ( )

Stops playing and mixing the music file.

Call this method when you are in a channel.

Returns
  • 0: Success.
  • < 0: Failure.

◆ StopAudioRecording()

int agora_gaming_rtc.IRtcEngine.StopAudioRecording ( )

Stops an audio recording on the client.

You can call this method before calling the LeaveChannel method else, the recording automatically stops when the LeaveChannel method is called.

Returns
  • 0: Success.
  • < 0: Failure.

◆ StopChannelMediaRelay()

int agora_gaming_rtc.IRtcEngine.StopChannelMediaRelay ( )

Stops the media stream relay.

Once the relay stops, the host quits all the destination channels.

After a successful method call, the SDK triggers the OnChannelMediaRelayStateChangedHandler callback. If the callback returns RELAY_STATE_IDLE(0) and RELAY_OK(0), the host successfully stops the relay.

Note
If the method call fails, the SDK triggers the OnChannelMediaRelayStateChangedHandler callback with the RELAY_ERROR_SERVER_NO_RESPONSE(2) or RELAY_ERROR_SERVER_CONNECTION_LOST(8) state code. You can leave the channel by calling the LeaveChannel method, and the media stream relay automatically stops.
Returns
  • 0: Success.
  • < 0: Failure.

◆ StopEchoTest()

int agora_gaming_rtc.IRtcEngine.StopEchoTest ( )

Stops the audio call test.

Returns
  • 0: Success.
  • < 0: Failure.

◆ StopLastmileProbeTest()

int agora_gaming_rtc.IRtcEngine.StopLastmileProbeTest ( )

Stops the last-mile network probe test.

Returns
  • 0: Success.
  • < 0: Failure.

◆ StopPreview()

int agora_gaming_rtc.IRtcEngine.StopPreview ( )

Stops the local video preview and disables video.

Returns
  • 0: Success.
  • < 0: Failure.

◆ StopRtmpStream()

int agora_gaming_rtc.IRtcEngine.StopRtmpStream ( string  url )

Stops pushing media streams to a CDN.

Since
v3.6.1.1

You can call this method to stop the live stream on the specified CDN address. This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing streams to multiple addresses, call this method multiple times.

After you call this method, the SDK triggers the OnRtmpStreamingStateChangedHandler callback on the local client to report the state of the streaming.

Parameters
url The address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.
Returns
  • 0: Success.
  • < 0: Failure.

◆ StopScreenCapture()

int agora_gaming_rtc.IRtcEngine.StopScreenCapture ( )

Stop screen sharing.

Note
This method is for Windows and macOS only.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SwitchCamera()

int agora_gaming_rtc.IRtcEngine.SwitchCamera ( )

Switches between front and rear cameras.

Note
  • This method is for Android and iOS only.
  • Ensure that you call this method after the camera starts, for example, by calling StartPreview or JoinChannelByKey.
Returns
  • 0: Success.
  • < 0: Failure.

◆ SwitchChannel() [1/2]

int agora_gaming_rtc.IRtcEngine.SwitchChannel ( string  token,
string  channelId 
)

Switches to a different channel.

This method allows the audience of a Live-broadcast channel to switch to a different channel.

After the user successfully switches to another channel, the OnLeaveChannelHandler and OnJoinChannelSuccessHandler callbacks are triggered to indicate that the user has left the original channel and joined a new one.

Once the user switches to another channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the mute methods accordingly.

Note
This method applies to the audience role in a Live-broadcast channel only.
Parameters
token The token generated at your server:
  • For low-security requirements: You can use the temporary token generated in Console. For details, see Get a temporary token.
  • For high-security requirements: Use the token generated at your server. For details, see Get a token.
channelId Unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INALID_ARGUMENT): The parameter is invalid.
    • -5(ERR_REFUSED): The request is rejected, probably because the user is not an audience.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.
    • -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid.
    • -113(ERR_NOT_IN_CHANNEL): The user is not in the channel.

◆ SwitchChannel() [2/2]

int agora_gaming_rtc.IRtcEngine.SwitchChannel ( string  token,
string  channelId,
ChannelMediaOptions  options 
)

Switches to a different channel, and configures whether to automatically subscribe to audio or video streams in the target channel.

Since
v3.3.1

This method allows the audience of a LIVE_BROADCASTING channel to switch to a different channel.

After the user successfully switches to another channel, the OnLeaveChannelHandler and OnJoinChannelSuccessHandler callbacks are triggered to indicate that the user has left the original channel and joined a new one.

Note
  • This method applies to the audience role in a LIVE_BROADCASTING channel only.
  • The difference between this method and SwitchChannel1 is that the former adds the options parameter to configure whether the user automatically subscribes to all remote audio and video streams in the target channel. By default, the user subscribes to the audio and video streams of all the other users in the target channel, thus incurring all associated usage costs. To unsubscribe, set the options parameter or call the mute methods accordingly.
Parameters
token The token generated at your server. For details, see Generate a token.
channelId Unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
options The channel media options: ChannelMediaOptions.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INALID_ARGUMENT): The parameter is invalid.
    • -5(ERR_REFUSED): The request is rejected, probably because the user is not an audience.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.
    • -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid.
    • -113(ERR_NOT_IN_CHANNEL): The user is not in the channel.

◆ TakeSnapshot()

int agora_gaming_rtc.IRtcEngine.TakeSnapshot ( string  channel,
uint  uid,
string  filePath 
)

Takes a snapshot of a video stream.

Since
v3.6.1.1

This method takes a snapshot of a video stream from the specified user, generates a JPG image, and saves it to the specified path.

The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the OnSnapshotTakenHandler callback to report whether the snapshot is successfully taken as well as the details of the snapshot taken.

Note
  • Call this method after joining a channel.
  • If the video of the specified user is pre-processed, for example, added with watermarks or image enhancement effects, the generated snapshot also includes the pre-processing effects.
Parameters
channel The channel name.
uid The user ID of the user. Set uid as 0 if you want to take a snapshot of the local user's video.
filePath The local path (including the filename extensions) of the snapshot. For example, C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.jpg on Windows, /App Sandbox/Library/Caches/example.jpg on iOS, ~/Library/Logs/example.jpg on macOS, and /storage/emulated/0/Android/data/<package name>/files/example.jpg on Android. Ensure that the path you specify exists and is writable.
Returns
  • 0: Success.
  • < 0: Failure.

◆ UpdateChannelMediaRelay()

int agora_gaming_rtc.IRtcEngine.UpdateChannelMediaRelay ( ChannelMediaRelayConfiguration  mediaRelayConfiguration )

Updates the channels for media stream relay. After a successful StartChannelMediaRelay method call, if you want to relay the media stream to more channels, or leave the current relay channel, you can call the UpdateChannelMediaRelay method.

After a successful method call, the SDK triggers the OnChannelMediaRelayEventHandler callback with the RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL(7) state code.

Note
Call this method after the StartChannelMediaRelay method to update the destination channel.
Parameters
mediaRelayConfiguration The media stream relay configuration: ChannelMediaRelayConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ UpdateRtmpTranscoding()

int agora_gaming_rtc.IRtcEngine.UpdateRtmpTranscoding ( LiveTranscoding  transcoding )

Updates the transcoding configuration.

Since
v3.6.1.1

After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. The SDK triggers the OnTranscodingUpdatedHandler callback after the transcoding configuration is updated.

Parameters
transcoding The transcoding configuration for CDN live streaming. See LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ UpdateScreenCaptureParameters()

int agora_gaming_rtc.IRtcEngine.UpdateScreenCaptureParameters ( ScreenCaptureParameters  screenCaptureParameters )

Updates the screen sharing parameters.

Note
This method is for Windows and macOS only.
Parameters
screenCaptureParameters Sets the screen sharing encoding parameters. The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of videoDimension to calculate the charges. For details, see descriptions in ScreenCaptureParameters.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_NOT_READY(-3): no screen or windows is being shared.

◆ UpdateScreenCaptureRegion()

int agora_gaming_rtc.IRtcEngine.UpdateScreenCaptureRegion ( Rectangle  rectangle )

Updates the screen sharing region.

Note
This method is for Windows and macOS only.
Parameters
rectangle Sets the relative location of the region to the screen or window. null means sharing the whole screen or window. See Rectangle. If the specified region overruns the screen or window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen or window.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_NOT_READY(-3): no screen or windows is being shared.

The documentation for this class was generated from the following file: