Type definition

Enumerator

CN

Mainland China.

NA

North America.

EU

Europe.

AS

Asia, excluding Mainland China.

JP

Japan.

IN

India.

GLOB

(Default) Global.

Enumerator

LowLatency

1: Low latency.

UltraLowLatency

2: (Default) Ultra low latency.

Enumerator

Ok

0: Successfully get the information of an audio file.

Failure

1: Fail to get the information of an audio file.

Enumerator

LCAAC

0: (Default) LC-AAC.

HEAAC

1: HE-AAC.

HEAACV2

2: HE-AAC v2.

For better voice effects, Agora recommends setting the profile parameter of setAudioProfile to MusicHighQuality or MusicHighQualityStereo before using the following presets:

• RoomAcousticsKTV
• RoomAcousticsVocalConcert
• RoomAcousticsStudio
• RoomAcousticsPhonograph
• RoomAcousticsSpacial
• RoomAcousticsEthereal
• VoiceChangerEffectUncle
• VoiceChangerEffectOldMan
• VoiceChangerEffectBoy
• VoiceChangerEffectSister
• VoiceChangerEffectGirl
• VoiceChangerEffectPigKing
• VoiceChangerEffectHulk
• PitchCorrection

Enumerator

AudioEffectOff

Turn off voice effects, that is, use the original voice.

RoomAcousticsKTV

The voice effect typical of a KTV venue.

RoomAcousticsVocalConcert

The voice effect typical of a concert hall.

RoomAcousticsStudio

The voice effect typical of a recording studio.

RoomAcousticsPhonograph

The voice effect typical of a vintage phonograph.

RoomAcousticsVirtualStereo

The virtual stereo effect, which renders monophonic audio as stereo audio.

Attention: Before using this preset, set the profile parameter of setAudioProfile to MusicHighQuality or MusicHighQualityStereo; otherwise, the preset setting is invalid.

RoomAcousticsSpacial

A more spatial voice effect.

RoomAcousticsEthereal

A more ethereal voice effect.

RoomAcoustics3DVoice

A 3D voice effect that makes the voice appear to be moving around the user. The default movement cycle is 10 seconds. After setting this effect, you can call setAudioEffectParameters to modify the movement period.

Attention:

• Before using this preset, set the profile parameter of setAudioProfile to MusicStandardStereo or MusicHighQualityStereo; otherwise, the preset setting is invalid.
• If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect.

VoiceChangerEffectUncle

A middle-aged man's voice.

Attention: Agora recommends using this preset to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect.

VoiceChangerEffectOldMan

A senior man's voice.

Attention: Agora recommends using this preset to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect.

VoiceChangerEffectBoy

A boy's voice.

Attention: Agora recommends using this preset to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect.

VoiceChangerEffectSister

A young woman's voice.

Attention: Agora recommends using this preset to process a female-sounding voice; otherwise, you may not hear the anticipated voice effect.

VoiceChangerEffectGirl

A girl's voice.

Attention: Agora recommends using this preset to process a female-sounding voice; otherwise, you may not hear the anticipated voice effect.

VoiceChangerEffectPigKing

The voice of Pig King, a character in Journey to the West who has a voice like a growling bear.

VoiceChangerEffectHulk

The Hulk's voice.

StyleTransformationRnB

The voice effect typical of R&B music.

Attention: Before using this preset, set the profile parameter of setAudioProfile to MusicHighQuality or MusicHighQualityStereo; otherwise, the preset setting is invalid.

StyleTransformationPopular

The voice effect typical of popular music.

Attention: Before using this preset, set the profile parameter of setAudioProfile to MusicHighQuality or MusicHighQualityStereo; otherwise, the preset setting is invalid.

PitchCorrection

A pitch correction effect that corrects the user's pitch based on the pitch of the natural C major scale. After setting this voice effect, you can call setAudioEffectParameters to adjust the basic mode of tuning and the pitch of the main tone.

Enumerator

Band31

0: 31 Hz

Band62

1: 62 Hz

Band125

2: 125 Hz

Band250

3: 250 Hz

Band500

4: 500 Hz

Band1K

5: 1 kHz

Band2K

6: 2 kHz

Band4K

7: 4 kHz

Band8K

8: 8 kHz

Band16K

9: 16 kHz

Enumerator

Auto

0: Original mode.

L

1: Left channel mode. This mode replaces the audio of the right channel with the audio of the left channel, which means the user can only hear the audio of the left channel.

R

2: Right channel mode. This mode replaces the audio of the left channel with the audio of the right channel, which means the user can only hear the audio of the right channel.

MIX

3: Mixed channel mode. This mode mixes the audio of the left channel and the right channel, which means the user can hear the audio of the left channel and the right channel at the same time.

Deprecated:

Deprecated as of v3.4.0.

Enumerator

CanNotOpen

The SDK cannot open the music file.

TooFrequentCall

The SDK opens the music file too frequently.

InterruptedEOF

The playback of the music file is interrupted.

OK

The music file is playing.

Enumerator

CanNotOpen

701: The SDK cannot open the music file. For example, the local music file does not exist, the SDK does not support the file format, or the SDK cannot access the music file URL.

TooFrequentCall

702: The SDK opens the music file too frequently. If you need to call startAudioMixing multiple times, ensure that the call interval is more than 500 ms.

InterruptedEOF

703: The music file playback is interrupted.

StartedByUser

720: The method call of startAudioMixing to play music files succeeds.

OneLoopCompleted

721: The music file completes a loop playback.

StartNewLoop

722: The music file starts a new loop playback.

AllLoopsCompleted

723: The music file completes all loop playbacks.

StoppedByUser

724: The method call of stopAudioMixing to stop playing the music file succeeds.

PausedByUser

725: The method call of pauseAudioMixing to pause playing the music file succeeds.

ResumedByUser

726: The method call of resumeAudioMixing to resume playing the music file succeeds.

Enumerator

Playing

710: The music file is playing.

The possible reasons include:

• StartedByUser(710)
• OneLoopCompleted(720)
• StartNewLoop(722)
• ResumedByUser(726)

Paused

711: The music file pauses playing.

This state is due toPausedByUser (725).

Stopped

713: The music file stops playing.

The possible reasons include:

• AllLoopsCompleted(723)
• StoppedByUser(724)

Failed

714: An error occurs during the playback of the audio mixing file.

The possible reasons include:

• CanNotOpen(701)
• TooFrequentCall(702)
• InterruptedEOF(703)

Enumerator

Default

0: The default audio profile.

• For the interactive streaming profile: A sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 64 Kbps.
• For the communication profile:

SpeechStandard

1: A sample rate of 32 kHz, audio encoding, mono, and a bitrate of up to 18 Kbps.

MusicStandard

2: A sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 64 Kbps.

MusicStandardStereo

3: A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 80 Kbps.

MusicHighQuality

4: A sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 96 Kbps.

MusicHighQualityStereo

5: A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 128 Kbps.

Enumerator boundary.

Enumerator

PositionMixedRecordingAndPlayback

0: (Default) Records the mixed audio of the local and all remote users.

PositionRecording

1: Only records the audio of the local user.

PositionMixedPlayback

2: Only records the audio of all remote users.

Enumerator

Low

0: Low quality. The sample rate is 32 kHz, and the file size is around 1.2 MB after 10 minutes of recording.

Medium

1: Medium quality. The sample rate is 32 kHz, and the file size is around 2 MB after 10 minutes of recording.

High

2: High quality. The sample rate is 32 kHz, and the file size is around 3.75 MB after 10 minutes of recording.

UltraHigh

3: Ultra high quality. The sample rate is 32 kHz, and the file size is around 7.5 MB after 10 minutes of recording.

Enumerator

Off

Turn off voice reverb, that is, to use the original voice.

FX_KTV

The reverb style typical of a KTV venue (enhanced).

FX_VOCAL_CONCERT

The reverb style typical of a concert hall (enhanced).

FX_UNCLE

A middle-aged man's voice.

FX_SISTER

The reverb style typical of a young woman's voice.

FX_STUDIO

The reverb style typical of a recording studio (enhanced).

FX_POPULAR

The reverb style typical of popular music (enhanced).

FX_RNB

The reverb style typical of R&B music (enhanced).

FX_PHONOGRAPH

The voice effect typical of a vintage phonograph.

Popular

The voice effect typical of popular music.

RnB

The voice effect typical of R&B music.

Rock

The reverb style typical of rock music.

HipHop

The reverb style typical of hip-hop music.

VocalConcert

The voice effect typical of a concert hall.

KTV

The voice effect typical of a KTV venue.

Studio

The voice effect typical of a recording studio.

VIRTUAL_STEREO

The reverberation of the virtual stereo. The virtual stereo is an effect that renders the monophonic audio as the stereo audio, so that all users in the channel can hear the stereo voice effect.

AUDIO_ELECTRONIC_VOICE

A pitch correction effect that corrects the user's pitch based on the pitch of the natural C major scale.

AUDIO_THREEDIM_VOICE

A 3D voice effect that makes the voice appear to be moving around the user.

Enumerator

DryLevel

0: The level of the dry signal (dB). The value is between -20 and 10.

WetLevel

1: The level of the early reflection signal (wet signal) (dB). The value is between -20 and 10.

RoomSize

2: The room size of the reflection. The value is between 0 and 100.

WetDelay

3: The length of the initial delay of the wet signal (ms). The value is between 0 and 200.

Strength

4: The reverberation strength. The value is between 0 and 100.

Enumerator

Default

-1: The default audio route.

Headset

0: The headset.

Earpiece

1: The earpiece.

HeadsetNoMic

2: The headset with no microphone.

Speakerphone

3: The built-in speaker on a mobile device.

Loudspeaker

4: The external speaker.

HeadsetBluetooth

5: The bluetooth headset.

USB

6: The USB peripheral (macOS only).

HDMI

7: The HDMI peripheral (macOS only).

DisplayPort

8: The DisplayPort peripheral (macOS only).

AirPlay

9: Apple AirPlay (macOS only).

Enumerator

Type32000

32000: 32 kHz

Type44100

44100: 44.1 kHz

Type48000

48000: (Default) 48 kHz

Enumerator

Default

0: The default audio scenario.

ChatRoomEntertainment

1: Entertainment scenario where users need to frequently switch the user role.

Education

2: Education scenario where users want smoothness and stability.

GameStreaming

3: High-quality audio chatroom scenario where hosts mainly play music.

ShowRoom

4: Showroom scenario where a single host wants high-quality audio.

ChatRoomGaming

5: Gaming scenario for group chat that only contains the human voice.

IOT

6: IoT (Internet of Things) scenario where users use IoT devices with low power consumption.

MEETING

8: Meeting scenario that mainly contains the human voice.

Enumerator

None

No restriction, the SDK has full control of the audio session operations.

SetCategory

The SDK does not change the audio session category.

ConfigureSession

The SDK does not change any setting of the audio session (category, mode, categoryOptions).

DeactivateSession

The SDK keeps the audio session active when leaving a channel.

All

The SDK does not configure the audio session anymore.

Enumerator

BACKGROUND_COLOR

1: (Default) The background image is a solid color.

BACKGROUND_IMG

The background image is a file in PNG or JPG format.

BACKGROUND_BLUR

The background image is the blurred background.

Enumerator

Low

1: The degree of blurring applied to the custom background image is low. The user can almost see the background clearly.

Medium

The degree of blurring applied to the custom background image is medium. It is difficult for the user to recognize details in the background.

High

(Default) The degree of blurring applied to the custom background image is high. The user can barely see any distinguishing features in the background.

Enumerator

Rear

The rear camera.

Front

The front camera.

Enumerator

Invalid

-1: The SDK does not detect the brightness level of the video image. Wait a few seconds to get the brightness level from captureBrightnessLevel in the next callback.

Normal

0: The brightness level of the video image is normal.

Bright

1: The brightness level of the video image is too bright.

Dark

2: The brightness level of the video image is too dark.

Enumerator

Auto

0: (Default) Automatically adjust the camera capture preference. The SDK adjusts the camera output parameters according to the system performance and network conditions to balance CPU consumption and video preview quality.

Performance

1: Prioritizes the system performance. The SDK chooses the dimension and frame rate of the local camera capture closest to those set by setVideoEncoderConfiguration. In this case, the local preview quality depends on the encoder.

Preview

2: Prioritizes the local preview quality. The SDK chooses higher camera output parameters to improve the local video preview quality. This option requires extra CPU and RAM usage for video pre-processing.

Manual

3: Allows you to customize the width and height of the video image captured by the local camera.

Enumerator

None

0: No error.

ServerErrorResponse

1: An error occurs in the server response.

ServerNoResponse

2: No server response.

You can call leaveChannel to leave the channel.

This error can also occur if your project has not enabled co-host token authentication. You can mailto:support@agora.io to enable the co-host token authentication service before starting a channel media relay.

NoResourceAvailable

3: The SDK fails to access the service, probably due to limited resources of the server.

FailedJoinSourceChannel

4: Fails to send the relay request.

FailedJoinDestinationChannel

5: Fails to accept the relay request.

FailedPacketReceivedFromSource

6: The server fails to receive the media stream.

FailedPacketSentToDestination

7: The server fails to send the media stream.

ServerConnectionLost

8: The SDK disconnects from the server due to poor network connections. You can call the leaveChannel method to leave the channel.

InternalError

9: An internal error occurs in the server.

SourceTokenExpired

10: The token of the source channel has expired.

DestinationTokenExpired

11: The token of the destination channel has expired.

Enumerator

Disconnect

0: The user disconnects from the server due to a poor network connection.

Connected

1: The user is connected to the server.

JoinedSourceChannel

2: The user joins the source channel.

JoinedDestinationChannel

3: The user joins the destination channel.

SentToDestinationChannel

4: The SDK starts relaying the media stream to the destination channel.

ReceivedVideoPacketFromSource

5: The server receives the audio stream from the source channel.

ReceivedAudioPacketFromSource

6: The server receives the audio stream from the source channel.

UpdateDestinationChannel

7: The destination channel is updated.

UpdateDestinationChannelRefused

8: The destination channel update fails due to internal reasons.

UpdateDestinationChannelNotChange

9: The destination channel does not change, which means that the destination channel fails to be updated.

UpdateDestinationChannelIsNil

10: The destination channel name is null.

VideoProfileUpdate

11: The video profile is sent to the server.

PauseSendPacketToDestChannelSuccess

12: The SDK successfully pauses relaying the media stream to destination channels.

PauseSendPacketToDestChannelFailed

13: The SDK fails to pause relaying the media stream to destination channels.

ResumeSendPacketToDestChannelSuccess

14: The SDK successfully resumes relaying the media stream to destination channels.

ResumeSendPacketToDestChannelFailed

15: The SDK fails to resume relaying the media stream to destination channels.

Enumerator

Idle

0: The initial state. After you successfully stop the channel media relay by calling stopChannelMediaRelay, the channelMediaRelayStateChanged callback returns this state.

Connecting

1: The SDK tries to relay the media stream to the destination channel.

Running

2: The SDK successfully relays the media stream to the destination channel.

Failure

3: An error occurs. See code in channelMediaRelayStateChanged for the error code.

Enumerator

Communication

0: (Default) The communication profile. This profile applies to scenarios such as an audio call or video call, where all users can publish and subscribe to streams.

LiveBroadcasting

1: Live streaming. In this profile, you can set the role of users as the host or audience by calling setClientRole. A host both publishes and subscribes to streams, while an audience subscribes to streams only. This profile applies to scenarios such as a chat room or interactive video streaming.

Game

2: Gaming. Agora does not recommend using this setting.

Enumerator

Broadcaster

1: Host. A host can both send and receive streams.

Audience

2: (Default) Audience. An audience member can only receive streams.

Enumerator

None

0: The automatic mode. In this mode, the SDK attempts a direct connection to SD-RTN™ and automatically switches to TCP/TLS 443 if the attempt fails. As of v3.6.2, the SDK has this mode enabled by default.

UDP

1: The cloud proxy for the UDP protocol, that is, the Force UDP cloud proxy mode. In this mode, the SDK always transmits data over UDP.

TCP

2: The cloud proxy for the TCP (encryption) protocol, that is, the Force TCP cloud proxy mode. In this mode, the SDK always transmits data over TCP/TLS 443.

Enumerator

Connecting

0: The SDK is connecting to the Agora edge server.

JoinSuccess

1: The SDK has joined the channel successfully.

Interrupted

2: The connection between the SDK and the Agora edge server is interrupted.

BannedByServer

3: The connection between the SDK and the Agora edge server is banned by the Agora edge server. This error occurs when the user is kicked out of the channel by the server.

JoinFailed

4: The SDK fails to join the channel. When the SDK fails to join the channel for more than 20 minutes, this error occurs and the SDK stops reconnecting to the channel.

LeaveChannel

5: The SDK has left the channel.

InvalidAppId

6: The connection failed because the App ID is not valid. Please rejoin the channel with a valid App ID.

InvalidChannelName

7: The connection failed since channel name is not valid. Please rejoin the channel with a valid channel name.

InvalidToken

8: The connection failed because the token is not valid. Typical reasons include:

• The App Certificate for the project is enabled in Agora Console, but you do not use a token when joining the channel. If you enable the App Certificate, you must use a token to join the channel.
• The uid specified when calling joinChannel to join the channel is inconsistent with the uid passed in when generating the token.

TokenExpired

9: The connection failed since token is expired.

RejectedByServer

10: The connection is rejected by server. Typical reasons include:

• The user is already in the channel and still calls a method, for example, joinChannel, to join the channel. Stop calling this method to clear this error.
• The user tries to join the channel when conducting a pre-call test. The user needs to call the channel after the call test ends.

SettingProxyServer

11: The connection state changed to reconnecting because the SDK has set a proxy server.

RenewToken

12: The connection state changed because the token is renewed.

ClientIpAddressChanged

13: The IP address of the client has changed, possibly because the network type, IP address, or port has been changed.

KeepAliveTimeout

14: Timeout for the keep-alive of the connection between the SDK and the Agora edge server. The connection state changes to Reconnecting.

Enumerator

Disconnected

1: The SDK is disconnected from the Agora edge server. The state indicates the SDK is in one of the following phases:

• The initial state before calling the joinChannel method.
• The app calls the leaveChannel method.

Connecting

2: The SDK is connecting to the Agora edge server. This state indicates that the SDK is establishing a connection with the specified channel after the app calls joinChannel.

• If the SDK successfully joins the channel, it triggers the connectionStateChanged callback and the connection state switches to Connected.
• After the connection is established, the SDK also initializes the media and triggers joinChannelSuccess when everything is ready.

Connected

3: The SDK is connected to the Agora edge server. This state also indicates that the user has joined a channel and can now publish or subscribe to a media stream in the channel. If the connection to the Agora edge server is lost because, for example, the network is down or switched, the SDK automatically tries to reconnect and triggers connectionStateChanged that indicates the connection state switches to Reconnecting.

Reconnecting

4: The SDK keeps reconnecting to the Agora edge server. The SDK keeps rejoining the channel after being disconnected from a joined channel because of network issues.

• If the SDK cannot rejoin the channel within 10 seconds, it triggers connectionLost, stays in the Reconnecting state, and keeps rejoining the channel.
• If the SDK fails to rejoin the channel 20 minutes after being disconnected from the Agora edge server, the SDK triggers the connectionStateChanged callback, switches to the Failed state, and stops rejoining the channel.

Failed

5: The SDK fails to connect to the Agora edge server or join the channel. This state indicates that the SDK stops trying to rejoin the channel. You must call leaveChannel to leave the channel.

• You can call joinChannel to rejoin the channel.
• If the SDK is banned from joining the channel by the Agora edge server through the RESTful API, the SDK triggers the connectionStateChanged callback.

Enumerator

MaintainQuality

0: (Default) Prefers to reduce the video frame rate while maintaining video quality during video encoding under limited bandwidth. This degradation preference is suitable for scenarios where video quality is prioritized.

Attention: In the COMMUNICATION channel profile, the resolution of the video sent may change, so remote users need to handle this issue. See videoSizeChanged.

MaintainFramerate

1: Prefers to reduce the video quality while maintaining the video frame rate during video encoding under limited bandwidth. This degradation preference is suitable for scenarios where smoothness is prioritized and video quality is allowed to be reduced.

MaintainBalanced

2: Reduces the video frame rate and video quality simultaneously during video encoding under limited bandwidth. MaintainBalanced has a lower reduction than MaintainQuality and MaintainFramerate, and this preference is suitable for scenarios where both smoothness and video quality are a priority.

Attention: The resolution of the video sent may change, so remote users need to handle this issue. See videoSizeChanged.

Attributes

view

The view used to render the local user's video. This parameter is only applicable to scenarios testing video devices, that is, when the enableVideo member is set to true.

enableAudio

Whether to enable the audio device for the call loop test:

• true: (Default) Enables the audio device. To test the audio device, set this parameter as true.
• false: Disables the audio device.

enableVideo

Whether to enable the video device for the call loop test:

• true: (Default) Enables the video device. To test the video device, set this parameter as true.
• false: Disables the video device.

token

The token used to secure the audio and video call loop test. If you do not enable App Certificate in Agora Console, you do not need to pass a value in this parameter; if you have enabled App Certificate in Agora Console, you must pass a token in this parameter. The uid used when you generate the token must be 0xFFFFFFFF, and the channel name used must be the channel name that identifies each audio and video call loop test. For server-side token generation, see https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows.

channelId

The channel name that identifies each audio and video call loop. To ensure proper loop test functionality, the channel name passed in to identify each loop test cannot be the same when users of the same project (App ID) perform audio and video call loop tests on different devices.

Agora recommends using AES128GCM2 or AES256GCM2 encrypted mode. These two modes support the use of salt for higher security.

Enumerator

AES128XTS

1: (Default) 128-bit AES encryption, XTS mode.

AES128ECB

2: 128-bit AES encryption, ECB mode.

AES256XTS

3: 256-bit AES encryption, XTS mode.

SM4128ECB

4: 128-bit SM4 encryption, ECB mode.

AES128GCM

5: 128-bit AES encryption, GCM mode.

AES256GCM

6: 256-bit AES encryption, GCM mode.

AES128GCM2

7: 128-bit AES encryption, GCM mode. This encryption mode requires the setting of salt (encryptionKdfSalt).

AES256GCM2

8: 256-bit AES encryption, GCM mode. This encryption mode requires the setting of salt (encryptionKdfSalt).

Enumerator

ErrScreenCapturePermissionDenied

16: The user refuses to grant screen capture permission to the application.

ErrScreenCaptureSystemNotSupported

2: Due to system limitations, screen capture is not available on systems earlier than Android 5 (that is, Android API level 21). The SDK reports this error code when you call startScreenCaptureMobile on systems earlier than Android 5.

ErrScreenCaptureSystemAudioNotSupported

3: Due to system limitations, system audio cannot be captured on systems earlier than Android 10 (that is, API level 29). The SDK reports this error when you call startScreenCaptureMobile and set captureAudio as true on systems later than Android 5 (API level 21) and earlier than Android 10 (API level 29).

Enumerator

Fail

-1: Fails to block the window during screen sharing. The user's graphics card does not support window blocking.

None

0: Reserved.

Enumerator

None

0: No reason, indicating a good QoE of the local user.

RemoteNetworkQualityPoor

1: The remote user's network quality is poor.

LocalNetworkQualityPoor

2: The local user's network quality is poor.

WirelessSignalPoor

4: The local user's Wi-Fi or mobile network signal is weak.

WifiBluetoothCoexist

8: The local user enables both Wi-Fi and bluetooth, and their signals interfere with each other. As a result, audio transmission quality is undermined.

Enumerator

Good

0: The QoE of the local user is good.

Bad

1: The QoE of the local user is poor.

Enumerator

Fps1

1: 1 fps

Fps7

7: 7 fps

Fps10

10: 10 fps

Fps15

15: 15 fps

Fps24

24: 24 fps

Fps30

30: 30 fps

Fps60

60: 60 fps

Attention: (For Windows and macOS only)

Enumerator

Complete

1: The last-mile network probe test is complete.

IncompleteNoBwe

2: The last-mile network probe test is incomplete because the bandwidth estimation is not available due to limited test resources.

Unavailable

3: The last-mile network probe test is not carried out, probably due to poor network conditions.

Enumerator

Low

Low contrast level.

Normal

(Default) Normal contrast level.

High

High contrast level.

Enumerator

Ok

0: The local audio is normal.

Failure

1: No specified reason for the local audio failure.

DeviceNoPermission

2: No permission to use the local audio device.

DeviceBusy

3: The microphone is in use.

RecordFailure

4: The local audio capturing fails. Check whether the capturing device is working properly.

EncodeFailure

5: The local audio encoding fails.

NoRecordingDevice

6: No audio recording device.

NoPlayoutDevice

7: No audio playout device.

RecordInvalidId

9: The ID of the local audio-capture device is invalid. Check the audio capture device ID.

PlayoutInvalidId

10: The ID of the local audio-playback device is invalid. Check the audio playback device ID.

Enumerator

Stopped

0: The local audio is in the initial state.

Recording

1: The capturing device starts successfully.

Encoding

2: The first audio frame encodes successfully.

Failed

3: The local audio fails to start.

Enumerator

OK

0: The local video is normal.

Failure

1: No specified reason for the local video failure.

DeviceNoPermission

2: No permission to use the local video capturing device.

DeviceBusy

3: The local video capturing device is in use.

CaptureFailure

4: The local video capture fails. Check whether the capturing device is working properly.

EncodeFailure

5: The local video encoding fails.

CaptureInBackground

6: The local video capturing device not available due to app did enter background.

CaptureMultipleForegroundApps

7: The local video capturing device not available because the app is running in a multi-app layout (generally on the pad).

DeviceNotFound

Since

v3.4.0

8: Fails to find a local video capture device.

LocalVideoStreamErrorDeviceInvalidId

10: (macOS and Windows only) The SDK cannot find the video device in the video device list. Check whether the ID of the video device is valid.

ScreenCaptureWindowMinmized

11: When calling startScreenCaptureByWindowId to share the window, the shared window is in a minimized state.

ScreenCaptureWindowClosed

Since

v3.2.0

12: The error code indicates that a window shared by the window ID has been closed, or a full-screen window shared by the window ID has exited full-screen mode. After exiting full-screen mode, remote users cannot see the shared window. To prevent remote users from seeing a black screen, Agora recommends that you immediately stop screen sharing.

Common scenarios for reporting this error code:

• When the local user closes the shared window, the SDK reports this error code.
• The local user shows some slides in full-screen mode first, and then shares the cpp of the slides. After the user exits full-screen mode, the SDK reports this error code.
• The local user watches web video or reads web document in full-screen mode first, and then shares the window of the web video or document. After the user exits full-screen mode, the SDK reports this error code.

Enumerator

Stopped

0: The local video is in the initial state.

Capturing

1: The local video capturing device starts successfully.

Encoding

2: The first video frame is successfully encoded.

Failed

3: Fails to start the local video.

Enumerator

Off

0: Do not output any log information.

Debug

0x080f: Output all log information. Set your log filter as DEBUG if you want to get the most complete log file.

Info

0x000f: Output CRITICAL, ERROR, WARNING, and INFO level log information. We recommend setting your log filter as this level.

Warning

0x000e: Output CRITICAL, ERROR, and WARNING level log information.

Error

0x000c: Output CRITICAL and ERROR level log information.

Critical

0x0008: Output CRITICAL level log information.

Enumerator

None

0: Do not output any log information.

Info

0x0001: (Default) Output FATAL, ERROR, WARN, and INFO level log information. We recommend setting your log filter as this level.

Warn

0x0002: Output FATAL, ERROR, and WARN level log information.

Error

0x0004: Output FATAL and ERROR level log information.

Fatal

0x0008: Output FATAL level log information.

Enumerator

Auto

0: (Default) Automatic mode. The SDK automatically enables or disables the low-light enhancement feature according to the ambient light to compensate for the lighting level or prevent overexposure, as necessary.

Manual

Manual mode. Users need to enable or disable the low-light enhancement feature manually.

Enumerator

HighQuality

0: (Default) Promotes video quality during low-light enhancement. It processes the brightness, details, and noise of the video image. The performance consumption is moderate, the processing speed is moderate, and the overall video quality is optimal.

Fast

Promotes performance during low-light enhancement. It processes the brightness and details of the video image. The processing speed is faster.

Enumerator

MediaDeviceStateIdle

0: The device is ready for use.

MediaDeviceStateActive

1: The device is in use.

MediaDeviceStateDisabled

2: The device is disabled.

MediaDeviceStateNotPresent

4: The device is not found.

MediaDeviceStateUnplugged

8: The device is unplugged.

MediaDeviceStateUnrecommended

16: The device is not recommended.

Enumerator

UnknownAudioDevice

-1: Unknown device type.

AudioPlayoutDevice

0: Audio playback device.

AudioRecordingDevice

1: Audio capturing device.

VideoRenderDevice

2: Video renderer.

VideoCaptureDevice

3: Video capturer.

AudioApplicationPlayoutDevice

4: Application audio playback device.

Attributes

storagePath

The absolute path (including the filename extensions) of the recording file. For example, C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.mp4 on Windows, /App Sandbox/Library/Caches/example.mp4 on iOS, /Library/Logs/example.mp4 on macOS, and /storage/emulated/0/Android/data/<package name>/files/example.mp4 on Android.

containerFormat

The format of the recording file. See MediaRecorderContainerFormat.

streamType

The recording content. See MediaRecorderStreamType.

maxDurationMs

The maximum recording duration, in milliseconds. The default value is 120,000.

recorderInfoUpdateInterval

The interval (ms) of updating the recording information. The value range is [1000,10000]. The SDK triggers the onRecorderInfoUpdated callback to report the updated recording information according to interval you set in this parameter.

Enumerator

Unknown

-1: The network type is unknown.

Disconnected

0: The SDK disconnects from the network.

LAN

1: The network type is LAN.

WIFI

2: The network type is Wi-Fi (including hotspots).

Mobile2G

3: The network type is mobile 2G.

Mobile3G

4: The network type is mobile 3G.

Mobile4G

5: The network type is mobile 4G.

Mobile5G

6: The network type is mobile 5G.

Enumerator

Adaptative

0: (Default) The output video always follows the orientation of the captured video. The receiver takes the rotational information passed on from the video encoder. This mode applies to scenarios where video orientation can be adjusted on the receiver.

• If the captured video is in landscape mode, the output video is in landscape mode.
• If the captured video is in portrait mode, the output video is in portrait mode.

FixedLandscape

1: In this mode, the SDK always outputs videos in landscape (horizontal) mode. If the captured video is in portrait mode, the video encoder crops it to fit the output. Applies to situations where the receiving end cannot process the rotational information. For example, CDN live streaming.

FixedPortrait

2: In this mode, the SDK always outputs video in portrait (portrait) mode. If the captured video is in landscape mode, the video encoder crops it to fit the output. Applies to situations where the receiving end cannot process the rotational information. For example, CDN live streaming.

Enumerator

High

The user's priority is high.

Normal

(Default) The user's priority is normal.

Enumerator

None

0: Reserved for future use.

UDP

1: The cloud proxy for the UDP protocol, that is, the Force UDP cloud proxy mode. In this mode, the SDK always transmits data over UDP.

TCP

2: The cloud proxy for the TCP (encryption) protocol, that is, the Force TCP cloud proxy mode. In this mode, the SDK always transmits data over TLS 443.

Local

3: Reserved for future use.

TCPProxyAutoFallbackType

4: The automatic mode. In this mode, the SDK attempts a direct connection to SD-RTN™ and automatically switches to TLS 443 if the attempt fails.

Enumerator

AdaptNone

0: The local video quality stays the same.

AdaptUpBandwidth

1: The local video quality improves because the network bandwidth increases.

AdaptDownBandwidth

2: The local video quality deteriorates because the network bandwidth decreases.

Enumerator

Unknown

0: The network quality is unknown.

Excellent

1: The network quality is excellent.

Good

2: The network quality is quite good, but the bitrate may be slightly lower than excellent.

Poor

3: Users can feel the communication slightly impaired.

Bad

4: Users cannot communicate smoothly.

VBad

5: The quality is so bad that users can barely communicate.

Down

6: The network is down and users cannot communicate at all.

Unsupported

7: Users cannot detect the network quality. (Not in use.)

Detecting

8: Detecting the network quality.

Enumerator

None

0: No error occurs.

WriteFailed

1: The SDK fails to write the recorded data to a file.

NoStream

2: The SDK does not detect audio and video streams to be recorded, or audio and video streams are interrupted for more than five seconds during recording.

OverMaxDuration

3: The recording duration exceeds the upper limit.

ConfigChanged

4: The recording configuration changes.

CustomStreamDetected

5: The SDK detects audio and video streams from users using versions of the SDK earlier than v3.0.0 in the COMMUNICATION channel profile.

Enumerator

Error

-1: An error occurs during the recording. See RecorderErrorCode for the reason.

Start

2: The audio and video recording starts.

Stop

3: The audio and video recording stops.

Enumerator

Internal

0: The SDK reports this reason when the audio state changes.

NetworkCongestion

1: Network congestion.

NetworkRecovery

2: Network recovery.

LocalMuted

3: The local user stops receiving the remote audio stream or disables the audio module.

LocalUnmuted

4: The local user resumes receiving the remote audio stream or enables the audio module.

RemoteMuted

5: The remote user stops sending the audio stream or disables the audio module.

RemoteUnmuted

6: The remote user resumes sending the audio stream or enables the audio module.

RemoteOffline

7: The remote user leaves the channel.

Enumerator

Stopped

0: The local audio is in the initial state. The SDK reports this state in the case of LocalMuted, RemoteMuted or RemoteOffline.

Starting

1: The first remote audio packet is received.

Decoding

2: The remote audio stream is decoded and plays normally. The SDK reports this state in the case of NetworkRecovery, LocalUnmuted or RemoteUnmuted.

Frozen

3: The remote audio is frozen. The SDK reports this state in the case of NetworkCongestion.

Failed

4: The remote audio fails to start. The SDK reports this state in the case of Internal.

Enumerator

Internal

0: The SDK reports this reason when the video state changes.

NetworkCongestion

1: The remote user's network is congested. If the network conditions are persistently poor, display a pop-up box in the application that says "The remote user's network conditions are poor".

NetworkRecovery

2: The remote user's network conditions are restored from congested to normal. You can display a pop-up box in the application that says "The remote user's network conditions have improved".

LocalMuted

3: The local user stops receiving the remote video stream or disables the video module. You can close the window to render the remote user's video and display a pop-up box in the application that says "You have stopped receiving video from the remote user".

LocalUnmuted

4: The local user resumes receiving the remote video stream or enables the video module. You can restore the window to render the remote user's video and display a pop-up box in the application that says "You have resumed receiving video from the remote user".

RemoteMuted

5: The remote user stops sending the video stream or disables the video module. You can close the window to render the remote user's video, use an icon in the list of users in the application user interface to show that the remote user has stopped sending video, and display a pop-up box in the application that says "The remote user has disabled the camera".

RemoteUnmuted

6: The remote user resumes sending the video stream or enables the video module. You can restore the window to render the remote user's video, use an icon in the list of users in the application user interface to show that the remote user has resumed sending video, and display a pop-up box in the application that says "The remote user has enabled the camera".

RemoteOffline

7: The remote user leaves the channel. You can close the window to render the remote user's video and remove the remote user from the user list in the application user interface.

AudioFallback

8: The remote audio-and-video stream falls back to the audio-only stream due to poor network conditions. You can close the window to render the remote user's video and display a pop-up box in the application that says "The remote user's network conditions are poor".

AudioFallbackRecovery

9: The remote audio-only stream switches back to the audio-and-video stream after the network conditions improve. You can restore the window to render the remote user's video and display a pop-up box in the application that says "The remote user's network conditions are poor".

Enumerator

Stopped

0: The remote video is in the initial state. The SDK reports this state in the case of LocalMuted, RemoteMuted or RemoteOffline.

Starting

1: The first remote video packet is received.

Decoding

2: The remote video stream is decoded and plays normally. The SDK reports this state in the case of NetworkRecovery, LocalUnmuted,RemoteUnmuted, or AudioFallbackRecovery.

Frozen

3: The remote video is frozen. The SDK reports this state in the case of NetworkCongestion or AudioFallback.

Failed

4: The remote video fails to start. The SDK reports this state in the case of Internal.

Enumerator

High

0: High-quality video stream.

Low

1: Low-quality video stream.

Enumerator

Hidden

1: Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Hidden mode. One dimension of the video may have clipped contents.

Fit

2: Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Fit mode. Areas that are not filled due to disparity in the aspect ratio are filled with black.

Adaptive

Deprecated:

3: This mode is deprecated.

FILL

4: The fill mode. In this mode, the SDK stretches or zooms the video to fill the display window.

Enumerator

OK

0: The RTMP or RTMPS streaming publishes successfully.

InvalidParameters

1: Invalid argument used. Please check the parameter setting. For example, if you do not call setLiveTranscoding to set the transcoding parameters before calling addPublishStreamUrl, the SDK returns this error.

EncryptedStreamNotAllowed

2: The RTMP or RTMPS streaming is encrypted and cannot be published.

ConnectionTimeout

3: Timeout for the RTMP or RTMPS streaming. Call the addPublishStreamUrl method to publish the streaming again.

InternalServerError

4: An error occurs in Agora's streaming server. Call the addPublishStreamUrl method to publish the streaming again.

RtmpServerError

5: An error occurs in the CDN server.

TooOften

6: The RTMP or RTMPS streaming publishes too frequently.

ReachLimit

7: The host publishes more than 10 URLs. Delete the unnecessary URLs before adding new ones.

NotAuthorized

8: The host manipulates other hosts' URLs. For example, the host updates or stops other hosts' streams. Check your app logic.

StreamNotFound

9: Agora's server fails to find the RTMP or RTMPS streaming.

FormatNotSupported

10: The format of the RTMP or RTMPS streaming URL is not supported. Check whether the URL format is correct.

NotBroadcaster

11: The user role is not host, so the user cannot use the CDN live streaming function. Check your application code logic.

TranscodingNoMixStream

The updateRtmpTranscoding or setLiveTranscoding method is called to update the transcoding configuration in a scenario where there is streaming without transcoding. Check your application code logic.

NetDown

14: Errors occurred in the host's network.

InvalidAppid

15: Your App ID does not have permission to use the CDN live streaming function. Refer to Prerequisites to enable the CDN live streaming permission.

UnPublishOK

100: The streaming has been stopped normally. After you call removePublishStreamUrl to stop streaming, the SDK returns this value.

Enumerator

Idle

0: The Media Push has not started or has ended. This state is also triggered after you remove a RTMP or RTMPS stream from the CDN by calling removePublishStreamUrl.

Connecting

1: The SDK is connecting to Agora's streaming server and the CDN server. This state is triggered after you call the addPublishStreamUrlmethod.

Running

2: The RTMP or RTMPS streaming publishes. The SDK successfully publishes the RTMP or RTMPS streaming and returns this state.

Recovering

3: The RTMP or RTMPS streaming is recovering. When exceptions occur to the CDN, or the streaming is interrupted, the SDK tries to resume RTMP or RTMPS streaming and returns this state.

• If the SDK successfully resumes the streaming, Running(2) returns.
• If the streaming does not resume within 60 seconds or server errors occur, Failure(4) returns. You can also reconnect to the server by calling the removePublishStreamUrl and addPublishStreamUrl methods.

Failure

4: The RTMP or RTMPS streaming fails. See the errCode parameter for the detailed error information. You can also call the addPublishStreamUrl method to publish the RTMP or RTMPS streaming again.

Disconnecting

5: The SDK is disconnecting from the Agora streaming server and CDN. When you call removePublishStreamUrl or stopRtmpStream to stop the streaming normally, the SDK reports the streaming state as Disconnecting, Idle in sequence.

Enumerator

FailedLoadImage

1: An error occurs when you add a background image or a watermark image in the media push.

UrlAlreadyInUse

2: The streaming URL is already being used for CDN live streaming. If you want to start new streaming, use a new streaming URL.

AdvancedFeatureNotSupport

3: The feature is not supported.

RequestTooOften

4: Reserved.

Enumerator

Disabled

0: No fallback behavior for the local/remote video stream when the uplink/downlink network conditions are poor. The quality of the stream is not guaranteed.

VideoStreamLow

1: Under poor downlink network conditions, the remote video stream, to which you subscribe, falls back to the low-quality (low resolution and low bitrate) video stream. This option is only valid for setRemoteSubscribeFallbackOption. This option is invalid for setLocalPublishFallbackOption method.

AudioOnly

2: Under poor uplink network conditions, the published video stream falls back to audio-only. Under poor downlink network conditions, the remote video stream, to which you subscribe, first falls back to the low-quality (low resolution and low bitrate) video stream; and then to an audio-only stream if the network conditions worsen.

Enumerator

Idle

0: The initial publishing state after joining the channel.

NoPublished

1: Fails to publish the local stream. Possible reasons:

• The local user calls muteLocalAudioStream(true) or muteLocalVideoStream(true) to stop sending the local media stream.
• The local user calls disableAudio or disableVideo to disable the local audio or video module.
• The local user calls enableLocalAudio(false) or enableLocalVideo(false) to disable the local audio or video capture.
• The role of the local user is audience.

Publishing

2: Publishing.

Published

3: Publishes successfully.

Enumerator

Idle

0: The initial subscribing state after joining the channel.

NoSubscribed

1: Fails to subscribe to the remote stream. Possible reasons:

• The remote user:
  • Calls muteLocalAudioStream(true) or muteLocalVideoStream(true) to stop sending local media stream.
  • Calls disableAudio or disableVideo to disable the local audio or video module.
  • Calls enableLocalAudio(false) or enableLocalVideo(false) to disable the local audio or video capture.
  • The role of the remote user is audience.
• The local user calls the following methods to stop receiving remote streams:
  • Calls muteRemoteAudioStream(true), muteAllRemoteAudioStreams(true) or setDefaultMuteAllRemoteAudioStreams(true) to stop receiving the remote audio streams.
  • Calls muteRemoteVideoStream(true), muteAllRemoteVideoStreams(true) or setDefaultMuteAllRemoteVideoStreams(true) to stop receiving the remote video streams.

Subscribing

2: Subscribing.

Subscribed

3: Subscribes to and receives the remote stream successfully.

Since

v3.5.1

Enumerator

Success

0: Super resolution is successfully enabled.

StreamOverLimitation

1: The original resolution of the remote video is beyond the range where super resolution can be applied.

UserCountOverLimitation

2: Super resolution is already being used to boost another remote user’s video.

DeviceNotSupported

3: The device does not support using super resolution.

Enumerator

Success

0: Successfully upload the log files.

NetError

1: Network error. Check the network connection and call uploadLogFile again to upload the log file.

ServerError

2: An error occurs in the Agora server. Try uploading the log files later.

Enumerator

Off

Turn off voice conversion effects and use the original voice.

Neutral

A gender-neutral voice. To avoid audio distortion, ensure that you use this enumerator to process a female-sounding voice.

Sweet

A sweet voice. To avoid audio distortion, ensure that you use this enumerator to process a female-sounding voice.

Solid

A steady voice. To avoid audio distortion, ensure that you use this enumerator to process a male-sounding voice.

Bass

A deep voice. To avoid audio distortion, ensure that you use this enumerator to process a male-sounding voice.

Enumerator

Quit

0: The user quits the call.

Dropped

1: The SDK times out and the user drops offline because no data packet is received within a certain period of time.

Attention: If the user quits the call and the message is not passed to the SDK (due to an unreliable channel), the SDK assumes the user dropped offline.

BecomeAudience

2: The user switches the client role from the host to the audience.

BaseLine

66: Baseline video codec profile. Generally used for video calls on mobile phones.

Main

77: Main video codec profile. Generally used in mainstream electronics such as MP4 players, portable video players, PSP, and iPads.

High

100: (Default) High video codec profile. Generally used in high-resolution live streaming or television.

Enumerator

VP8

Standard VP8.

H264

Standard H.264.

EVP

Enhanced VP8.

E264

Enhanced H.264.

Enumerator

H264

1: (Default) H.264.

H265

2: H.265.

Enumerator

None

(Default) No content hint.

Motion

Motion-intensive content. Choose this option if you prefer smoothness or when you are sharing a video clip, movie, or video game.

Details

Motionless content. Choose this option if you prefer sharpness or when you are sharing a picture, PowerPoint slides, or texts.

Enumerator

Auto

0: (Default) The SDK determines the mirror mode.

Enabled

1: Enable mirror mode.

Disabled

2: Disable mirror mode.

Enumerator

Auto

0: (Default) Automatic mode. The SDK automatically enables or disables the video noise reduction feature according to the ambient light.

Manual

Manual mode. Users need to enable or disable the video noise reduction feature manually.

Enumerator

HighQuality

0: (Default) Promotes video quality during video noise reduction. HighQuality balances performance consumption and video noise reduction quality. The performance consumption is moderate, the video noise reduction speed is moderate, and the overall video quality is optimal.

Fast

Promotes reducing performance consumption during video noise reduction. Fast prioritizes reducing performance consumption over video noise reduction quality. The performance consumption is lower, and the video noise reduction speed is faster. To avoid a noticeable shadowing effect (shadows trailing behind moving objects) in the processed video, Agora recommends that you use Fast when the camera is fixed.

Strength

Enhanced video noise reduction. Strength prioritizes video noise reduction quality over reducing performance consumption. The performance consumption is higher, the video noise reduction speed is slower, and the video noise reduction quality is better. If Strength is not enough for your video noise reduction needs, you can use Strength.

Enumerator

VoiceBeautifierOff

Turn off voice beautifier effects and use the original voice.

ChatBeautifierMagnetic

A more magnetic voice.

Attention: Agora recommends using this enumerator to process a male-sounding voice; otherwise, you may experience vocal distortion.

ChatBeautifierFresh

A fresher voice.

Attention: Agora recommends using this enumerator to process a female-sounding voice; otherwise, you may experience vocal distortion.

ChatBeautifierVitality

A more vital voice.

Attention: Agora recommends using this enumerator to process a female-sounding voice; otherwise, you may experience vocal distortion.

SingingBeautifier

Singing beautifier effect.

• If you call setVoiceBeautifierPreset(SingingBeautifier), you can beautify a male-sounding voice and add a reverberation effect that sounds like singing in a small room. Agora recommends using this enumerator to process a male-sounding voice; otherwise, you might experience vocal distortion.
• If you call setVoiceBeautifierParameters(SingingBeautifier, param1, param2), you can beautify a male- or female-sounding voice and add a reverberation effect.

TimbreTransformationVigorous

A more vigorous voice.

TimbreTransformationDeep

A deep voice.

TimbreTransformationMellow

A mellower voice.

TimbreTransformationFalsetto

Falsetto.

TimbreTransformationFull

A fuller voice.

TimbreTransformationClear

A clearer voice.

TimbreTransformationResounding

A more resounding voice.

TimbreTransformationRinging

A more ringing voice.

Deprecated

Deprecated as of v3.2.0.

Enumerator

Off

The original voice (no local voice change).

OldMan

The voice of an old man.

BabyBoy

The voice of a little boy.

BabyGirl

The voice of a little girl.

ZhuBaJie

The voice of Zhu Bajie, a character in Journey to the West who has a voice like that of a growling bear.

Ethereal

The ethereal voice.

Hulk

The voice of Hulk.

BEAUTY_VIGOROUS

A more vigorous voice.

BEAUTY_DEEP

A deeper voice.

BEAUTY_MELLOW

A mellower voice.

BEAUTY_FALSETTO

Falsetto.

BEAUTY_FULL

A fuller voice.

BEAUTY_CLEAR

A clearer voice.

BEAUTY_RESOUNDING

A more resounding voice.

BEAUTY_RINGING

A more ringing voice.

BEAUTY_SPACIAL

A more spatially resonant voice.

GENERAL_BEAUTY_VOICE_MALE_MAGNETIC

(For male only) A more magnetic voice. Do not use it when the speaker is a female; otherwise, voice distortion occurs.

GENERAL_BEAUTY_VOICE_FEMALE_FRESH

(For female only) A fresher voice. Do not use it when the speaker is a male; otherwise, voice distortion occurs.

GENERAL_BEAUTY_VOICE_FEMALE_VITALITY

(For female only) A more vital voice. Do not use it when the speaker is a male; otherwise, voice distortion occurs.

Attributes

filePath

The file path.

durationMs

The file duration (ms).

Attributes

uid

The user ID.

• In the local user's callback, uid = 0.
• In the remote users' callback, uid is the user ID of a remote user whose instantaneous volume is one of the three highest.

volume

The volume of the user. The value ranges between 0 (lowest volume) and 255 (highest volume). If the user calls startAudioMixing, the value of volume is the volume after audio mixing.

vad

The voice activity status of the local user.

• 0: The local user is not speaking.
• 1: The local user is speaking.

Attention:

• The vad parameter does not report the voice activity status of remote users. In the remote users' callback, the value of vad is always 0.
• To use this parameter, you must set to true when calling enableAudioVolumeIndication.

channelId

The name of the channel that the user is in.

Attributes

lighteningContrastLevel

contrast, often with lighteningLevel . The larger the value, the greater the contrast between light and dark. For more details, see LighteningContrastLevel.

lighteningLevel

The brightness level. The value ranges from 0.0 (original) to 1.0. The default is > . The greater the value, the greater the degree of whitening.

smoothnessLevel

The value ranges from 0.0 (original) to 1.0. The default value is 0.5. The greater the value, the greater the degree of skin grinding.

rednessLevel

The value ranges from 0.0 (original) to 1.0. The default value is 0.1. The larger the value, the greater the rosy degree.

Attributes

x

The x-coordinate (px) of the human face in the local video. The horizontal position relative to the origin, where the upper left corner of the captured video is the origin, and the x-coordinate is the upper left corner of the watermark.

y

The y-coordinate (px) of the human face in the local video. Taking the top left corner of the captured video as the origin, the y coordinate represents the relative longitudinal displacement of the top left corner of the human face to the origin.

width

The width (px) of the human face in the captured video.

height

The height (px) of the human face in the captured video.

distance

The distance between the human face and the device screen (cm).

Attributes

preference

The camera capture preference. For details, see CameraCaptureOutputPreference.

captureWidth

The width (px) of the video image captured by the local camera. To customize the width of the video image, set preference as Manual(3) first, and then use captureWidth to set the video width.

captureHeight

The height (px) of the video image captured by the local camera. To customize the height of the video image, set preference as Manual(3) first, and then use captureHeight.

cameraDirection

The camera direction. For details, see CameraDirection.

Attributes

channelName

The name of the channel.

token

The token that enables the user to join the channel.

uid

User ID.

Attributes

autoSubscribeAudio

Whether to automatically subscribe to all remote audio streams when the user joins a channel:

• true: (Default) Subscribe.
• false: Do not subscribe.

This member serves a similar function to the muteAllRemoteAudioStreams method. After joining the channel, you can call the muteAllRemoteAudioStreams method to set whether to subscribe to audio streams in the channel.

autoSubscribeVideo

Whether to subscribe to video streams when the user joins the channel:

• true: (Default) Subscribe.
• false: Do not subscribe.

This member serves a similar function to the muteAllRemoteVideoStreams method. After joining the channel, you can call the muteAllRemoteVideoStreams method to set whether to subscribe to video streams in the channel.

publishLocalAudio

whether to publish the local audio stream when the user joins a channel.

• true: (Default) Publish the local audio.
• false: Do not publish the local audio.

This member serves a similar function to the muteLocalAudioStream method. After the user joins the channel, you can call the muteLocalAudioStream method to set whether to publish the local audio stream in the channel.

publishLocalVideo

whether to publish the local video stream when the user joins a channel.

• true: (Default) Publish the local video.
• false: Do not publish the local video.

This member serves a similar function to the muteLocalVideoStream method. After the user joins the channel, you can call the muteLocalVideoStream method to set whether to publish the local audio stream in the channel.

Attributes

srcInfo

The information of the source channel ChannelMediaInfo. It contains the following members:

• channelName: The name of the source channel. The default value is , which means the SDK applies the name of the current channel.null
• uid: The unique ID to identify the relay stream in the source channel. The default value is 0, which means the SDK generates a random UID. You must set it as 0.
• token: The token for joining the source channel. It is generated with the channelName and uid you set in srcInfo.
  • If you have not enabled the App Certificate, set this parameter as the default value null , which means the SDK applies the App ID.
  • If you have enabled the App Certificate, you must use the token generated with the channelName and uid, and the uid must be set as 0.

destInfos

The information of the destination channel ChannelMediaInfo. It contains the following members:

• channelName: The name of the destination channel.
• uid: The unique ID to identify the relay stream in the destination channel. The value ranges from 0 to (2³²-1). To avoid UID conflicts, this `UID` must be different from any other `UID` in the destination channel. The default value is 0, which means the SDK generates a random `UID`. Do not set this parameter as the `UID` of the host in the destination channel, and ensure that this `UID` is different from any other `UID` in the channel.
• token: The token for joining the destination channel. It is generated with the channelName and uid you set in destInfos.
  • If you have not enabled the App Certificate, set this parameter as the default value null , which means the SDK applies the App ID.
  • If you have enabled the App Certificate, you must use the token generated with the channelName and uid.

Attributes

audienceLatencyLevel

The latency level of an audience member in interactive live streaming.

Attributes

strengthLevel

The level of color enhancement. The value range is [0.0, 1.0]. 0.0 is the default value, which means no color enhancement is applied to the video. The higher the value, the higher the level of color enhancement.

skinProtectLevel

The level of skin tone protection. The value range is [0.0, 1.0]. 0.0 means no skin tone protection. The higher the value, the higher the level of skin tone protection. The default value is 100.The default value is 1.0. When the level of color enhancement is higher, the portrait skin tone can be significantly distorted, so you need to set the level of skin tone protection; when the level of skin tone protection is higher, the color enhancement effect can be slightly reduced. Therefore, to get the best color enhancement effect, Agora recommends that you adjust strengthLevel and skinProtectLevel to get the most appropriate values.

The following table shows the SDK behaviors under different parameter settings:

Attributes

syncWithAudio

Whether to synchronize the data packet with the published audio packet.

• true: Synchronize the data packet with the audio packet.
• false: Do not synchronize the data packet with the audio packet.

When you set the data packet to synchronize with the audio, then if the data packet delay is within the audio delay, the SDK triggers the streamMessage callback when the synchronized audio packet is played out. Do not set this parameter as true if you need the receiver to receive the data packet immediately. Agora recommends that you set this parameter to `true` only when you need to implement specific functions, for example lyric synchronization.

ordered

Whether the SDK guarantees that the receiver receives the data in the sent order.

• true: Guarantee that the receiver receives the data in the sent order.
• false: Do not guarantee that the receiver receives the data in the sent order.

Do not set this parameter as true if you need the receiver to receive the data packet immediately.

Attributes

encryptionMode

The built-in encryption mode. See EncryptionMode. Agora recommends using AES128GCM2 or AES256GCM2 encrypted mode. These two modes support the use of salt for higher security.

encryptionKey

Encryption key in string type.

Attention: If you do not set an encryption key or set it as null, you cannot use the built-in encryption, and the SDK returns -2.

encryptionKdfSalt

Since

v3.4.5

Salt, 32 bytes in length. Agora recommends that you use OpenSSL to generate salt on the server side. See Media Stream Encryption for details.

Attention: This parameter takes effect only in AES128GCM2 or AES256GCM2 encrypted mode. In this case, ensure that this parameter is not 0.

Attributes

probeUplink

Sets whether to test the uplink network. Some users, for example, the audience members in a LIVE_BROADCASTING channel, do not need such a test.

• true: Test.
• false: Not test.

probeDownlink

Sets whether to test the downlink network:

• true: Test.
• false: Not test.

expectedUplinkBitrate

The expected maximum uplink bitrate (bps) of the local user. The value range is [100000, 5000000]. Agora recommends referring to setVideoEncoderConfiguration to set the value.

expectedDownlinkBitrate

The expected maximum downlink bitrate (bps) of the local user. The value range is [100000,5000000].

Attributes

packetLossRate

The packet loss rate (%).

jitter

The network jitter (ms).

availableBandwidth

The estimated available bandwidth (bps).

Attributes

state

uplinkReport

Results of the uplink last-mile network test. For details, see LastmileProbeOneWayResult.

downlinkReport

Results of the downlink last-mile network test. For details, see LastmileProbeOneWayResult.

rtt

The round-trip time (ms).

Attributes

width

The width of the video in pixels. The default value is 360.

• When pushing video streams to the CDN, the value range of width is [64,1920]. If the value is less than 64, Agora server automatically adjusts it to 64; if the value is greater than 1920, Agora server automatically adjusts it to 1920.
• When pushing audio streams to the CDN, set width and height as 0.

height

The height of the video in pixels. The default value is 640.

• When pushing video streams to the CDN, the value range of height is [64,1080]. If the value is less than 64, Agora server automatically adjusts it to 64; if the value is greater than 1080, Agora server automatically adjusts it to 1080.
• When pushing audio streams to the CDN, set width and height as 0.

videoFramerate

Frame rate (in fps) of the output video stream set for Media Push. The default value is 15 , and the value range is (0,30].

Attention: The Agora server adjusts any value over 30 to 30.

lowLatency

Deprecated

This parameter is deprecated.

Latency mode:

• true: Low latency with unassured quality.
• false: (Default) High latency with assured quality.

videoGop

GOP (Group of Pictures) in fps of the video frames for Media Push. The default value is 30.

videoCodecProfile

Video codec profile type for Media Push. Set it as 66, 77, or 100 (default). See VideoCodecProfileType for details.

Attention: If you set this parameter to any other value, Agora adjusts it to the default value.

videoCodecType

Video codec profile types for Media Push. See VideoCodecTypeForStream for details.

transcodingUsers

Manages the user layout configuration in the CDN live streaming. Agora supports a maximum of 17 transcoding users in a Media Push channel. See TranscodingUser for details.

transcodingExtraInfo

Reserved property. Extra user-defined information to send SEI for the H.264/H.265 video stream to the CDN live client. Maximum length: 4096 bytes. For more information on SEI, see SEI-related questions.

backgroundColor

The background color in RGB hex value. Value only. Do not include a preceeding #. For example, 0xFFB6C1 (light pink). The default value is 0x000000 (black).

backgroundImage

watermark

Deprecated

The watermark on the live video. Watermark images must be in the PNG format. See AgoraImage for details.

watermark

The watermark on the live video. Watermark images must be in the PNG format. See AgoraImage for details.

You can add one watermark, or add multiple watermarks using an array. This parameter is used with watermarkCount.

audioSampleRate

Self-defined audio sample rate. See AudioSampleRateType for details.

audioBitrate

Bitrate (Kbps) of the audio output stream for Media Push. The default value is 48, and the highest value is 128.

audioChannels

The number of audio channels for Media Push. Agora recommends choosing 1 (mono), or 2 (stereo) audio channels. Special players are required if you choose 3, 4, or 5.

• 1: (Default) Mono
• 2: Stereo.
• 3: Three audio channels.
• 4: Four audio channels.
• 5: Five audio channels.

audioCodecProfile

Audio codec profile type for Media Push. See AudioCodecProfileType for details.

userConfigExtraInfo

Reserved for future use. Extra user-defined information to send the Supplemental Enhancement Information (SEI) for the H.264/H.265 video stream to the CDN live client. Maximum length: 4096 Bytes.

userConfigExtraInfo

Reserved property. Extra user-defined information to send the Supplemental Enhancement Information (SEI) for the H.264/H.265 video stream to the CDN live client. Maximum length: 4096 Bytes.

Attributes

numChannels

The number of audio channels.

sentSampleRate

The sampling rate (Hz) of sending the local user's audio stream.

sentBitrate

The average bitrate (Kbps) of sending the local user's audio stream.

txPacketLossRate

The packet loss rate (%) from the local client to the Agora server before applying the anti-packet loss strategies.

Attributes

sentBitrate

The actual bitrate (Kbps) while sending the local video stream.

Attention: This value does not include the bitrate for resending the video after packet loss.

sentFrameRate

The actual frame rate (fps) while sending the local video stream.

Attention: This value does not include the frame rate for resending the video after packet loss.

encoderOutputFrameRate

The output frame rate (fps) of the local video encoder.

rendererOutputFrameRate

The output frame rate (fps) of the local video renderer.

targetBitrate

The target bitrate (Kbps) of the current encoder. This is an estimate made by the SDK based on the current network conditions.

targetFrameRate

The target frame rate (fps) of the current encoder.

qualityAdaptIndication

Quality adaption of the local video stream in the reported interval (based on the target frame rate and target bitrate).

encodedBitrate

The bitrate (Kbps) while encoding the local video stream.

Attention: This value does not include the bitrate for resending the video after packet loss.

encodedFrameWidth

The width of the encoded video (px).

encodedFrameHeight

The height of the encoded video (px).

encodedFrameCount

The number of the sent video frames, represented by an aggregate value.

codecType

The codec type of the local video.

txPacketLossRate

The video packet loss rate (%) from the local client to the Agora server before applying the anti-packet loss strategies.

captureFrameRate

The frame rate (fps) for capturing the local video stream.

Attributes

filePath

The absolute or relative path of the log file, which ends with \ or /. Ensure that the path for the log file exists and is writable. You can use this parameter to rename the log files.

fileSize

The size (KB) of a log file. The default value is 2014 KB. If you set fileSize to 1024 KB, the maximum aggregate size of the log files output by the SDK is 5 MB. If you set fileSize to less than 1024 KB, the setting is invalid, and the maximum size of a log file is still 1024 KB.

level

The output level of the SDK log file. See LogLevel.

Attributes

level

The low-light enhancement level. For details, see LowLightEnhanceLevel.

mode

The low-light enhancement mode. For details, see LowLightEnhanceMode.

Attributes

uid

User ID.

• For the receiver: The user ID of the user who sent the Metadata.
• For the sender: Ignore this value.

buffer

The buffer address of the sent or received Metadata.

timeStampMs

The timestamp (ms) of the Metadata.

Attributes

deviceId

The device ID.

deviceName

The device name.

Attributes

storagePath

The absolute path (including the filename extensions) of the recording file. For example, C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.mp4 on Windows, /App Sandbox/Library/Caches/example.mp4 on iOS, /Library/Logs/example.mp4 on macOS, and /storage/emulated/0/Android/data/<package name>/files/example.mp4 on Android.

containerFormat

The format of the recording file. See MediaRecorderContainerFormat.

streamType

The recording content. See MediaRecorderStreamType.

maxDurationMs

The maximum recording duration, in milliseconds. The default value is 120,000.

recorderInfoUpdateInterval

The interval (ms) of updating the recording information. The value range is [1000,10000]. The SDK triggers the onRecorderInfoUpdated callback to report the updated recording information according to interval you set in this parameter.

Attributes

fileName

The absolute path of the recording file.

durationMs

The recording duration, in milliseconds.

fileSize

The size of the recording file, in bytes.

Deprecated:

This class is deprecated. Please use the updateScreenCaptureRegion method to update the shared area.

Attributes

top

The coordinate of the top side of the shared area on the vertical axis.

left

The coordinate of the left side of the shared area on the horizontal axis.

bottom

The coordinate of the bottom side of the shared area on the vertical axis.

right

The coordinate of the right side of the shared area on the horizontal axis.

x

The horizontal offset from the top-left corner.

y

The vertical offset from the top-left corner.

width

The width of the target area.

height

The height of the target area.

Attributes

x

The horizontal offset from the top-left corner.

y

The vertical offset from the top-left corner.

width

The width of the target area.

height

The height of the target area.

Attributes

uid

The user ID of the remote user.

quality

The quality of the audio stream sent by the user. See NetworkQuality.

networkTransportDelay

The network delay (ms) from the sender to the receiver.

jitterBufferDelay

The network delay (ms) from the receiver to the jitter buffer.

Attention: This parameter does not take effect if the receiver is an audience member and audienceLatencyLevel of ClientRoleOptions is 1.

audioLossRate

The frame loss rate (%) of the remote audio stream in the reported interval.

numChannels

The number of audio channels.

receivedSampleRate

The sampling rate of the received audio stream in the reported interval.

receivedBitrate

The average bitrate (Kbps) of the received audio stream in the reported interval.

totalFrozenTime

The total freeze time (ms) of the remote audio stream after the remote user joins the channel. In a session, audio freeze occurs when the audio frame loss rate reaches 4%.

frozenRate

The total audio freeze time as a percentage (%) of the total time when the audio is available. The audio is considered available when the remote user neither stops sending the audio stream nor disables the audio module after joining the channel.

totalActiveTime

The total active time (ms) between the start of the audio call and the callback of the remote user.

The active time refers to the total duration of the remote user without the mute state.

publishDuration

The total duration (ms) of the remote audio stream.

qoeQuality

Quality of experience (QoE) of the local user when receiving the remote audio stream. See ExperienceQualityType.

qualityChangedReason

The reason for poor QoE of the local user when receiving the remote audio stream. See ExperiencePoorReason.

mosValue

The quality of the remote audio stream in the reported interval. The quality is determined by the Agora real-time audio MOS (Mean Opinion Score) measurement method. The return value range is [0, 500]. Dividing the return value by 100 gets the MOS score, which ranges from 0 to 5. The higher the score, the better the audio quality.

The subjective perception of audio quality corresponding to the Agora real-time audio MOS scores is as follows:

MOS score	Perception of audio quality
Greater than 4	Excellent. The audio sounds clear and smooth.
From 3.5 to 4	Good. The audio has some perceptible impairment but still sounds clear.
From 3 to 3.5	Fair. The audio freezes occasionally and requires attentive listening.
From 2.5 to 3	Poor. The audio sounds choppy and requires considerable effort to understand.
From 2 to 2.5	Bad. The audio has occasional noise. Consecutive audio dropouts occur, resulting in some information loss. The users can communicate only with difficulty.
Less than 2	Very bad. The audio has persistent noise. Consecutive audio dropouts are frequent, resulting in severe information loss. Communication is nearly impossible.

Attributes

uid

The user ID of the remote user sending the video stream.

delay

Deprecated:

In scenarios where audio and video are synchronized, you can get the video delay data from networkTransportDelay and jitterBufferDelay in RemoteAudioStats.

The video delay (ms).

width

The width (pixels) of the video.

height

The height (pixels) of the video.

receivedBitrate

The bitrate (Kbps) of the remote video received since the last count.

decoderOutputFrameRate

The frame rate (fps) of decoding the remote video.

rendererOutputFrameRate

The frame rate (fps) of rendering the remote video.

packetLossRate

The packet loss rate (%) of the remote video after using the anti-packet-loss technology.

rxStreamType

The type of the video stream.

totalFrozenTime

The total freeze time (ms) of the remote video stream after the remote user joins the channel. In a video session where the frame rate is set to 5 fps or higher, video freezing occurs when the time interval between two adjacent video frames is more than 500 ms.

frozenRate

The total video freeze time as a percentage (%) of the total time the video is available. The video is considered available as long as that the remote user neither stops sending the video stream nor disables the video module after joining the channel.

totalActiveTime

Since

v3.0.1

The total active time (ms) of the video.

As long as the remote user/host neither stops sending the video stream nor disables the video module after joining the channel, the video is available.

publishDuration

Since

v3.1.0

The total duration (ms) of the remote video stream.

Attributes

appId

The App ID issued by Agora for your app development project. Only users who use the same App ID can join the same channel and communicate with each other.

areaCode

The region for connection. This is an advanced feature and applies to scenarios that have regional restrictions. For details on supported regions, see AreaCode.

After specifying the region, the SDK connects to the Agora servers within that region.

logConfig

The configuration of the log files. See LogConfig.

By default, the SDK outputs five log files: agorasdk.log, agorasdk_1.log, agorasdk_2.log, agorasdk_3.log, and agorasdk_4.log.

Each log file has a default size of 512 KB and is encoded in UTF-8 format. The SDK writes the latest log 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 the latest log.

This class sets the properties of the watermark and background images in the live video.

Attributes

url

The HTTP/HTTPS URL address of the image in the live video. The maximum length of this parameter is 1024 bytes.

x

The x coordinate (pixel) of the image on the video frame (taking the upper left corner of the video frame as the origin).

y

The y coordinate (pixel) of the image on the video frame (taking the upper left corner of the video frame as the origin).

width

The width (pixel) of the image on the video frame.

height

The height (pixel) of the image on the video frame.

Attributes

duration

Call duration of the local user in seconds, represented by an aggregate value.

txBytes

The number of bytes sent.

rxBytes

The number of bytes received.

txAudioBytes

The total number of audio bytes sent, represented by an aggregate value.

txVideoBytes

The total number of video bytes sent, represented by an aggregate value.

rxAudioBytes

The total number of audio bytes received, represented by an aggregate value.

rxVideoBytes

The total number of video bytes received, represented by an aggregate value.

txKBitRate

Video transmission bitrate (Kbps), represented by an instantaneous value.

rxKBitRate

The receiving bitrate (Kbps), represented by an instantaneous value.

rxAudioKBitRate

Audio receive bitrate (Kbps), represented by an instantaneous value.

txAudioKBitRate

The bitrate (Kbps) of sending the audio packet.

rxVideoKBitRate

Video receive bitrate (Kbps), represented by an instantaneous value.

txVideoKBitRate

The bitrate (Kbps) of sending the video.

lastmileDelay

The client-to-server delay (milliseconds).

txPacketLossRate

The packet loss rate (%) from the client to the Agora server before applying the anti-packet-loss algorithm.

rxPacketLossRate

The packet loss rate (%) from the Agora server to the client before using the anti-packet-loss method.

userCount

The number of users in the channel.

cpuAppUsage

The CPU usage (%) of the app.

cpuTotalUsage

The system CPU usage (%).

Attention: The value of cpuTotalUsage is always reported as 0 in the leaveChannel callback.

gatewayRtt

The round-trip time delay (ms) from the client to the local router.

memoryAppUsageRatio

The memory ratio occupied by the app (%).

Attention: This value is for reference only. Due to system limitations, you may not get this value.

memoryTotalUsageRatio

The memory occupied by the system (%).

Attention: This value is for reference only. Due to system limitations, you may not get this value.

memoryAppUsageInKbytes

The memory size occupied by the app (KB).

Attention: This value is for reference only. Due to system limitations, you may not get this value.

Attributes

captureSignalVolume

The volume of the captured system audio. The value range is [0,100]. The default value is 100.

Attributes

dimensions

The maximum dimensions of encoding the shared region. The default value is 1,920 × 1,080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges.

If the screen dimensions are different from the value of this parameter, Agora applies the following strategies for encoding. Suppose dimensions are set to 1,920 x 1,080:

• If the value of the screen dimensions is lower than that of dimensions, for example, 1,000 x 1,000 pixels, the SDK uses 1,000 x 1,000 pixels for encoding.
• If the value of the screen dimensions is larger than that of dimensions, for example, 2,000 × 1,500, the SDK uses the maximum value next to 1,920 × 1,080 with the aspect ratio of the screen dimension (4:3) for encoding, that is, 1,440 × 1,080.

frameRate

The frame rate (fps) of the shared region. The default value is 5. Agora does not recommend setting it to a value greater than 15.

bitrate

The bitrate (Kbps) of the shared region. The default value is 0, which represents that the SDK works out a bitrate according to the dimensions of the current screen.

captureMouseCursor

Since

v2.4.1

Whether to capture the mouse in screen sharing:

• true: (Default) Capture the mouse.
• false: Do not capture the mouse.

windowFocus

Since

v3.1.0

Whether to bring the window to the front when calling the startScreenCaptureByWindowId method to share it:

• true:Bring the window to the front.
• false: (Default) Do not bring the window to the front.

excludeWindowList

The ID list of the cpp to be blocked. When calling startScreenCaptureByScreenRect to start screen sharing, you can use this parameter to block a specified window. When calling updateScreenCaptureParameters to update screen sharing configurations, you can use this parameter to dynamically block a specified window.

Attributes

captureAudio

Determines whether to capture system audio during screen sharing:

• true: Capture.
• false: (Default) Do not capture.

Attention: On Android, due to system limitations, capturing system audio is only available for Android API level 29 and later (that is, Android 10 and later).

audioParams

The audio configuration for the shared screen stream. See ScreenAudioParameters.

Attention: This parameter is only available for scenarios where captureAudio is true.

captureVideo

Determines whether to capture system video during screen sharing:

• true: Capture.
• false: (Default) Do not capture.

Attention: On Android, due to system limitations, screen capture is only available for Android API level 21 and later (that is, Android 5 and later).

videoParams

The video configuration for the shared screen stream. See ScreenVideoParameters.

Attention: This parameter is only available for scenarios where captureVideo is true.

Attributes

graphicsCardType

Graphics card type, including model information for the graphics card.

errCode

Error code that blocks the window when sharing the screen. See ExcludeWindowError.

Enumerator

ScreenScenarioDocument

1: (Default) Document. This scenario prioritizes the video quality of screen sharing and reduces the latency of the shared video for the receiver. If you share documents, slides, and tables, you can set this scenario.

ScreenScenarioGaming

2: Game. This scenario prioritizes the smoothness of screen sharing. If you share games, you can set this scenario.

ScreenScenarioVideo

3: Video. This scenario prioritizes the smoothness of screen sharing. If you share movies or live videos, you can set this scenario.

ScreenScenarioRdc

4: Remote control. This scenario prioritizes the video quality of screen sharing and reduces the latency of the shared video for the receiver. If you share the device desktop being remotely controlled, you can set this scenario.

Attributes

dimensions

The video encoding resolution. The default value is 1280 × 720. For recommended values, see Recommended video profiles.

If the aspect ratio is different between dimensions and the screen, the SDK adjusts the video encoding resolution according to the following rules (using an example value for dimensions of 1280 × 720):

• When the width and height of the screen are both lower than those of dimensions, the SDK uses the resolution of the screen for video encoding. For example, if the screen is 640 × 360, the SDK uses 640 × 360 for video encoding.
• When either the width or height of the screen is higher than that of dimensions, the SDK uses the maximum values that do not exceed those of dimensions while maintaining the aspect ratio of the screen for video encoding. For example, if the screen is 2000 × 1500, the SDK uses 960 × 720 for video encoding.

Attention:

• The billing of the screen sharing stream is based on the value of dimensions. When you do not pass in a value, Agora bills you at 1280 × 720; when you pass a value in, Agora bills you at that value. For details, see Pricing for Real-time Communication.
• This value does not indicate the orientation mode of the output ratio. For how to set the video orientation, see VideoOutputOrientationMode.
• Whether the SDK can support a resolution at 720P depends on the performance of the device. If you set 720P but the device cannot support it, the video frame rate can be lower.

frameRate

The video encoding frame rate (fps). The default value is 15. For recommended values, see Recommended video profiles.

bitrate

The video encoding bitrate (Kbps). For recommended values, see Recommended video profiles.

contentHint

The content hint of the screen sharing. See VideoContentHint.

Attributes

uid

The user ID of the host.

x

The x coordinate (pixel) of the host's video on the output video frame (taking the upper left corner of the video frame as the origin). The value range is [0, width], where width is the LiveTranscodingwidth set in .

y

The y coordinate (pixel) of the host's video on the output video frame (taking the upper left corner of the video frame as the origin). The value range is [0, height], where height is the LiveTranscodingheight set in .

width

The width (pixel) of the host's video.

height

The height (pixel) of the host's video.

zOrder

The layer index number of the host's video. The value range is [0, 100].

• 0: (Default) The host's video is the bottom layer.
• 100: The host's video is the top layer.

Attention:

• If the value is beyond this range, the SDK reports the error code ERR_INVALID_ARGUMENT.
• As of v2.3, the SDK supports setting zOrder to 0.

alpha

The transparency of the host's video. The value range is [0.0, 1.0].

• 0.0: Completely transparent.
• 1.0: (Default) Opaque.

audioChannel

The audio channel used by the host's audio in the output audio. The default value is 0, and the value range is [0, 5].

• 0: (Recommended) The defaut setting, which supports dual channels at most and depends on the upstream of the host.
• 1: The host's audio uses the FL audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first.
• 2: The host's audio uses the FC audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first.
• 3: The host's audio uses the FR audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first.
• 4: The host's audio uses the BL audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first.
• 5: The host's audio uses the BR audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first.
• 0xFF or a value greater than 5: The host's audio is muted, and the Agora server removes the host's audio.

Attention: If the value is not 0, a special player is required.

Attributes

uid

User ID

userAccount

The user account.

Attributes

width

The width (pixels) of the video.

height

The height (pixels) of the video.

Attributes

dimensions

frameRate

The frame rate (fps) of the encoding video frame. The default value is 15. See VideoFrameRate.

minFrameRate

The minimum encoding frame rate of the video. The default value is -1.

bitrate

The encoding bitrate (Kbps) of the video.

You can refer to the table below to set the bitrate according to your app scenario. If the bitrate you set is beyond the reasonable range, the SDK sets it within a reasonable range. You can also choose from the following options:

• Standard : (Recommended) Standard bitrate mode. In this mode, the video bitrate of the interactive streaming profile is twice that of the communication profile.
• Compatible: Adaptive bitrate mode. In this mode, the bitrate differs between the interactive streaming and communication profiles. If you choose this mode in the interactive streaming profile, the video frame rate may be lower than the set value.

Agora uses different video codecs for different profiles to optimize user experience. The communication profile prioritizes smoothness while the interactive streaming profile prioritizes video quality (a higher bitrate). Therefore, Agora recommends setting this parameter as Standard . You can also set the bitrate value of the Live-broadcasting profile to twice the bitrate value of the communication profile.

Dimensions	Frame rate (fps)	Bitrate (Kbps) for the communication profile	Bitrate (Kbps) for the interactive streaming profile
160 × 120	15	65	130
120 × 120	15	50	100
320 × 180	15	140	280
180 × 180	15	100	200
240 × 180	15	120	240
320 × 240	15	200	400
240 × 240	15	140	280
424 × 240	15	220	440
640 × 360	15	400	800
360 × 360	15	260	520
640 × 360	30	600	1200
360 × 360	30	400	800
480 × 360	15	320	640
480 × 360	30	490	980
640 × 480	15	500	1000
480 × 480	15	400	800
640 × 480	30	750	1500
480 × 480	30	600	1200
848 × 480	15	610	1220
848 × 480	30	930	1860
640 × 480	10	400	800
1280 × 720	15	1130	2260
1280 × 720	30	1710	3420
960 × 720	15	910	1820
960 × 720	30	1380	2760
1920 × 1080	15	2080	4160
1920 × 1080	30	3150	6300
1920 × 1080	60	4780	6500

minBitrate

The minimum encoding bitrate (Kbps) of the video.

The SDK automatically adjusts the encoding bitrate to adapt to the network conditions. Using a value greater than the default value forces the video encoder to output high-quality images but may cause more packet loss and sacrifice the smoothness of the video transmission. Unless you have special requirements for image quality, Agora does not recommend changing this value.

Attention: This parameter only applies to the interactive streaming profile.

orientationMode

The orientation mode of the encoded video. See VideoOutputOrientationMode.

degradationPreference

degradationPrefer

Video degradation preference under limited bandwidth. See DegradationPreference.

mirrorMode

Attention: By default, the video is not mirrored.

Attributes

level

Video noise reduction level. For details, see VideoDenoiserLevel.

mode

Video noise reduction mode. For details, see VideoDenoiserMode.

Attributes

backgroundSourceType

The type of the custom background image. See BACKGROUND_SOURCE_TYPE.

color

The type of the custom background image. The color of the custom background image. The format is a hexadecimal integer defined by RGB, without the # sign, such as 0xFFB6C1 for light pink. The default value is 0xFFFFFF, which signifies white. The value range is [0x000000, 0xffffff]. If the value is invalid, the SDK replaces the original background image with a white background image.

Attention: This parameter takes effect only when the type of the custom background image is BACKGROUND_COLOR.

source

The local absolute path of the custom background image. PNG and JPG formats are supported. If the path is invalid, the SDK replaces the original background image with a white background image.

Attention: This parameter takes effect only when the type of the custom background image is BACKGROUND_IMG.

blurDegree

The degree of blurring applied to the custom background image. See VirtualBackgroundBlurDegree.

Attention: This parameter takes effect only when the type of the custom background image is BACKGROUND_BLUR.

Attributes

visibleInPreview

Whether the watermark image is visible in the local video preview:

• true: (Default) The watermark image is visible in the local preview.
• false: The watermark image is not visible in the local preview.

positionInLandscapeMode

The area to display the watermark image in landscape mode.

positionInPortraitMode

The area to display the watermark image in portrait mode.

Attributes

beatsPerMeasure

The number of beats per measure, which ranges from 1 to 9. The default value is 4, which means that each measure contains one downbeat and three upbeats.

beatsPerMinute

The beat speed (beats/minute), which ranges from 60 to 360. The default value is 60, which means that the metronome plays 60 beats in one minute.

publish

Whether to publish the sound of the metronome to remote users:

• true: (Default) Publish the sound of the metronome. Both the local user and remote users can hear the metronome.
• false: Do not publish the sound of the metronome. Only the local user can hear the metronome.

Attributes

filePath

The absolute path (including the filename extensions) of the recording file. For example: C:\music\audio.aac .

Attention: Ensure that the directory for the log files exists and is writable.

recordingChannel

The recorded audio channel. The following values are supported:

• 1: (Default) Mono channel.
• Dual channel.

Attention: The actual recorded audio channel is related to the audio channel that you capture. If the captured audio is mono and recordingChannel is 2, the recorded audio is the dual-channel data that is copied from mono data, not stereo. If the captured audio is dual channel and recordingChannel is 1, the recorded audio is the mono data that is mixed by dual-channel data. The integration scheme also affects the final recorded audio channel. Therefore, to record in stereo, contact technical support for assistance.

recordingQuality

Recording quality. For details, see AudioRecordingQuality .

Attention: Note: This parameter applies to AAC files only.

recordingPosition

The recording content. For details, see AudioRecordingPosition .

recordingSampleRate

Recording sample rate (Hz).

• 16000
• (Default) 32000
• 44100
• 48000

Attention: If you set this parameter as 44100 or 48000, Agora recommends recording WAV files or AAV files whose recordingQuality is Medium or High for better recording quality.