Audio Features

Audio Basic Features

adjustPlaybackSignalVolume

Adjusts the local playback volume of all remote users.

public abstract int adjustPlaybackSignalVolume(int volume);

If you need to adjust the local playback volume of a specific remote user, it is recommended to call adjustUserPlaybackSignalVolume.

Timing

You can call this method before or after joining a channel.

Parameters

volume
User volume, range [0,400]:
  • 0: Mute.
  • 100: (Default) Original volume.
  • 400: Four times the original volume (amplifies the audio signal by four times).

Return Values

  • 0: Success.
  • < 0: Failure.

adjustUserPlaybackSignalVolume

Adjusts the playback volume of a specified remote user.

public abstract int adjustUserPlaybackSignalVolume(int uid, int volume);

You can call this method to adjust the playback volume of a specified remote user. To adjust the volume for multiple remote users, call this method multiple times, once for each user.

Timing

Call this method after joining a channel.

Parameters

uid
The user ID of the remote user.
volume
User volume, range [0, 400]:
  • 0: Mute.
  • 100: (Default) Original volume.
  • 400: Four times the original volume (amplifies the audio signal by four times).

Return Values

  • 0: Success.
  • < 0: Failure.

adjustUserPlaybackSignalVolumeEx

Adjusts the playback volume of a specified remote user.

public abstract int adjustUserPlaybackSignalVolumeEx(int uid, int volume, RtcConnection connection);

You can call this method to adjust the playback volume of a specified remote user. To adjust the playback volume of multiple remote users, call this method multiple times, once for each user.

Scenario

This method applies to multi-channel scenarios.

Timing

Call this method after calling joinChannelEx.

Parameters

uid
User ID of the remote user.
volume
The volume of the user. The value range is [0, 400]:
  • 0: Mute.
  • 100: (Default) Original volume.
  • 400: Four times the original volume (amplifies the audio signal by four times).
connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.

disableAudio

Disables the audio module.

public abstract int disableAudio();

The audio module is enabled by default. You can call this method to disable it.

Note: This method resets the internal engine and takes some time to take effect. Agora recommends using the following APIs to control the audio module respectively:

Timing

You can call this method before or after joining a channel. It remains effective after leaving the channel.

Return Values

  • 0: Success.
  • < 0: Failure.

enableAudio

Enables the audio module.

public abstract int enableAudio();

After calling disableAudio to disable the audio module, you can call enableAudio to re-enable it.

Note:

Timing

You can call this method before or after joining a channel. It remains effective after leaving the channel.

Return Values

  • 0: Success.
  • < 0: Failure.

enableAudioVolumeIndication

Enables the reporting of user volume indications.

public abstract int enableAudioVolumeIndication(int interval, int smooth, boolean reportVad);

This method enables the SDK to periodically report the volume information of the local sending stream user and up to three remote users with the highest instantaneous volume to the app.

Timing

You can call this method before or after joining a channel.

Related Callbacks

After this method is successfully called, if there are users publishing streams in the channel, the SDK triggers the onAudioVolumeIndication callback based on the configured interval.

Parameters

interval
Sets the interval (ms) between two volume indications:
  • ≤ 0: Disable volume indication.
  • > 0: Interval (ms) between two volume indications. The value must be greater than 10, otherwise the onAudioVolumeIndication callback will not be received. It is recommended to set it greater than 100.
smooth
Sets the smoothing factor for the sensitivity of volume indication. Range is 0 to 10, recommended value is 3. The higher the value, the more sensitive the indication.
reportVad
  • true: Enable voice activity detection (VAD) for the local user. When enabled, the vad parameter in the onAudioVolumeIndication callback reports the local user's voice activity status.
  • false: (Default) Disable VAD for the local user. When disabled, the vad parameter in the onAudioVolumeIndication callback does not report the local user's voice activity status unless the engine automatically detects voice activity.

Return Values

  • 0: Success.
  • < 0: Failure.

enableAudioVolumeIndicationEx

Enables reporting of user audio volume indications.

public abstract int enableAudioVolumeIndicationEx(int interval, int smooth, boolean reportVad, RtcConnection connection);

This method enables the SDK to periodically report the volume information of the local user and up to three remote users with the highest instantaneous volume.

Scenario

This method applies to multi-channel scenarios.

Timing

Call this method after calling joinChannelEx.

Related Callbacks

If the method call succeeds and users in the channel publish audio streams, the SDK triggers the onAudioVolumeIndication callback based on the set interval.

Parameters

interval
The time interval (ms) between volume indications:
  • ≤ 0: Disables the volume indication.
  • > 0: Interval between indications. Must be greater than 10 to receive onAudioVolumeIndication callbacks. Recommended value: > 100.
smooth
The smoothing factor for sensitivity. Range: [0, 10]. Recommended: 3. Higher values make indications more sensitive.
reportVad
Whether to enable voice activity detection (VAD) for the local user:
  • true: Enables VAD. The vad parameter in the onAudioVolumeIndication callback reports the local user's voice activity.
  • false: (Default) Disables VAD. The vad parameter does not report local voice activity unless automatically detected by the engine.
connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.

setAudioProfile [1/2]

Sets the audio profile and scenario.

public abstract int setAudioProfile(int profile, int scenario);
Deprecated
This method is deprecated. Use setAudioProfile(int profile) to set the audio profile and setAudioScenario(int scenario) to set the audio scenario.

Scenario

This method applies to various audio scenarios. You can choose based on your actual needs. For example, in scenarios with high audio quality requirements (such as music teaching), it is recommended to set profile to AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) and scenario to AUDIO_SCENARIO_GAME_STREAMING (3). You can call this method before or after joining a channel.

Timing

You can call this method before or after joining a channel.

Parameters

profile
Audio profile, including sampling rate, bitrate, encoding mode, and number of channels. See profile:
  • DEFAULT (0): Default.
    • Live Broadcast: 48 kHz, music encoding, mono, max bitrate 64 Kbps.
    • Communication: 32 kHz, speech encoding, mono, max bitrate 18 Kbps.
  • SPEECH_STANDARD (1): 32 kHz, speech encoding, mono, max bitrate 18 Kbps.
  • MUSIC_STANDARD (2): 48 kHz, music encoding, mono, max bitrate 64 Kbps.
  • MUSIC_STANDARD_STEREO (3): 48 kHz, music encoding, stereo, max bitrate 80 Kbps.
  • MUSIC_HIGH_QUALITY (4): 48 kHz, music encoding, mono, max bitrate 96 Kbps.
  • MUSIC_HIGH_QUALITY_STEREO (5): 48 kHz, music encoding, stereo, max bitrate 128 Kbps.
scenario
Audio scenario. Different scenarios use different volume types. See scenario:
  • AUDIO_SCENARIO_DEFAULT (0): Default automatic scenario. The SDK selects suitable audio quality based on user role and audio routing.
  • AUDIO_SCENARIO_GAME_STREAMING (3): High-quality scenario, suitable for music playback.
  • AUDIO_SCENARIO_CHATROOM (5): Chatroom scenario, suitable for frequent role switching or mute/unmute actions.
  • AUDIO_SCENARIO_CHORUS (7): Real-time chorus scenario, suitable for low-latency environments. Call getAudioDeviceInfo to check if the device supports ultra-low latency. To experience ultra-low latency, ensure isLowLatencyAudioSupported = true.
  • AUDIO_SCENARIO_MEETING (8): Meeting scenario, voice-focused.
  • AUDIO_SCENARIO_AI_CLIENT (10): AI conversation scenario, only for interaction with agents created by Conversational AI Engine.

Return Values

  • 0: Success.
  • < 0: Failure.

setAudioProfile [2/2]

Sets the audio profile.

public abstract int setAudioProfile(int profile);

If you need to set the audio scenario, call setAudioScenario, or call create and set mAudioScenario in RtcEngineConfig.

Scenario

You can choose an appropriate audio profile based on your actual needs. For example, in scenarios such as music teaching that require high audio quality, it is recommended to set profile to AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4). If you need to set the audio scenario, you can call setAudioScenario, or call create [2/2] and set audioScenario in RtcEngineConfig.

Timing

You can call this method before or after joining a channel.

Parameters

profile
Audio profile, including sampling rate, bitrate, encoding mode, and number of channels:
  • DEFAULT (0): Default profile.
    • Live Broadcast: 48 kHz sampling rate, music encoding, mono, max bitrate 64 Kbps.
    • Communication: 32 kHz sampling rate, speech encoding, mono, max bitrate 18 Kbps.
  • SPEECH_STANDARD (1): 32 kHz, speech encoding, mono, max bitrate 18 Kbps.
  • MUSIC_STANDARD (2): 48 kHz, music encoding, mono, max bitrate 64 Kbps.
  • MUSIC_STANDARD_STEREO (3): 48 kHz, music encoding, stereo, max bitrate 80 Kbps.
  • MUSIC_HIGH_QUALITY (4): 48 kHz, music encoding, mono, max bitrate 96 Kbps.
  • MUSIC_HIGH_QUALITY_STEREO (5): 48 kHz, music encoding, stereo, max bitrate 128 Kbps.

Return Values

  • 0: Success.
  • < 0: Failure.

setAudioScenario

Sets the audio scenario.

public abstract int setAudioScenario(int scenario);

Scenario

This method applies to various audio scenarios. For example, in music teaching scenarios with high audio quality requirements, it is recommended to set scenario to AUDIO_SCENARIO_GAME_STREAMING (3).

Timing

You can call this method before or after joining a channel.

Parameters

scenario
Audio scenario. The device uses different volume types under different audio scenarios:
  • AUDIO_SCENARIO_DEFAULT (0): Default automatic scenario. The SDK selects the appropriate audio quality based on the user role and audio route.
  • AUDIO_SCENARIO_GAME_STREAMING (3): High-quality scenario, suitable for music playback.
  • AUDIO_SCENARIO_CHATROOM (5): Chatroom scenario, suitable for frequent role switching or muting/unmuting the microphone.
  • AUDIO_SCENARIO_CHORUS (7): Real-time chorus scenario, suitable for good network conditions and ultra-low latency requirements. Before using this enum value, you need to call getAudioDeviceInfo to check whether the audio device supports ultra-low latency capture and playback. To experience ultra-low latency, ensure the audio device supports ultra-low latency (isLowLatencyAudioSupported = true).
  • AUDIO_SCENARIO_MEETING (8): Meeting scenario, mainly for voice.
  • AUDIO_SCENARIO_AI_CLIENT (10): AI conversation scenario, only applicable when the user interacts with a conversational agent created by the Conversational AI Engine.

Return Values

  • 0: Success.
  • < 0: Failure.

onActiveSpeaker

Callback for the most active remote speaker.

public void onActiveSpeaker(int uid)
After successfully calling enableAudioVolumeIndication, the SDK continuously detects which remote user has the highest volume. The remote user with the most occurrences of highest volume within the current cycle is considered the most active speaker. When there are at least two users in the channel and an active remote speaker exists, the SDK triggers this callback and reports the user ID of the most active remote speaker.
  • If the most active remote speaker remains the same, the SDK triggers this callback only once.
  • If the most active remote speaker changes, the SDK triggers this callback again and reports the new user ID.

Trigger Timing

This callback is triggered when the most active remote speaker is detected.

Parameters

uid
User ID of the most active remote speaker.

onAudioQuality

Callback that reports statistics of the audio stream sent by each remote user.

public void onAudioQuality(int uid, int quality, short delay, short lost)
Deprecated
This method is deprecated. Use onRemoteAudioStats instead.

This callback is triggered every two seconds to report the audio quality of each remote user sending audio streams.

Parameters

uid
Remote user ID sending the audio stream.
quality
User's audio quality:
  • QUALITY_UNKNOWN (0): Unknown quality.
  • QUALITY_EXCELLENT (1): Excellent quality.
  • QUALITY_GOOD (2): Good network quality but slightly lower bitrate than excellent.
  • QUALITY_POOR (3): Slightly impaired call quality.
  • QUALITY_BAD (4): Unable to communicate smoothly.
  • QUALITY_VBAD (5): Very poor quality, almost unable to communicate.
  • QUALITY_DOWN (6): Network disconnected, completely unable to communicate.
  • QUALITY_DETECTING (8): Performing Last-mile network probe.
delay
Network delay from sender to receiver (ms), including audio sampling preprocessing, network transmission, and jitter buffer delay.
lost
Packet loss rate (%) of audio data sent from the remote user to the receiver.

onAudioVolumeIndication

Callback that reports user volume information.

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

By default, this callback is disabled. You can enable it by calling the enableAudioVolumeIndication method. Once enabled, when a user sends an audio stream in the channel, the SDK triggers this callback at the interval set in enableAudioVolumeIndication. The SDK triggers two independent onAudioVolumeIndication callbacks to report the volume information of the local user sending audio and up to three remote users with the highest instantaneous volume.

Note: After enabling this callback, the SDK continues to report the local user's volume even if muteLocalAudioStream is called to mute the local user.
  • If a remote user's volume ranks in the top three but the user stops sending audio for more than 20 seconds, this callback will no longer include that user.
  • If all remote users stop sending audio for more than 20 seconds, the SDK stops triggering the remote user volume callback.

Parameters

speakers
Volume information of users. If this array is empty, it means there are no remote users in the channel or remote users are not sending audio. See AudioVolumeInfo.
totalVolume
Speaker volume, range [0, 255].
  • For local user callback, totalVolume is the volume of the local user sending audio.
  • For remote user callback, totalVolume is the sum of volumes of up to three remote users with the highest instantaneous volume.
  • If startAudioMixing is called, totalVolume is the mixed volume.

onFirstLocalAudioFramePublished

Callback when the first local audio frame is published.

public void onFirstLocalAudioFramePublished(int elapsed)
The SDK triggers this callback when any of the following conditions are met:
  • The local client enables the audio module and successfully calls joinChannel.
  • The local client calls muteLocalAudioStream(true) and then muteLocalAudioStream(false).
  • The local client calls disableAudio and then enableAudio.
  • The local client successfully pushes audio frames to the SDK using pushExternalAudioFrame.

Trigger Timing

This callback is triggered when the first local audio frame is published.

Parameters

elapsed
Time interval (ms) from the local user calling joinChannel to the SDK triggering this callback.

onFirstRemoteAudioDecoded

Callback when the first remote audio frame is decoded.

public void onFirstRemoteAudioDecoded(int uid, int elapsed)
Deprecated
This method is deprecated. Use onRemoteAudioStateChanged instead.

Trigger Timing

This callback is triggered in the following scenarios:
  • A remote user joins the channel and sends an audio stream for the first time.
  • The remote user's audio resumes from offline to online and starts sending audio again. Possible reasons include the remote user leaving the channel, disconnecting, calling muteLocalAudioStream to stop sending audio, or calling disableAudio to disable audio.

Parameters

uid
The user ID of the remote user.
elapsed
Time (ms) from the local user calling joinChannel to the SDK triggering this callback.

onFirstRemoteAudioFrame

Callback when the first audio frame from a remote user is received.

public void onFirstRemoteAudioFrame(int uid, int elapsed) {}
Deprecated
This method is deprecated. Use onRemoteAudioStateChanged instead.

Trigger Timing

This callback is triggered when the SDK receives the first audio frame from a remote user.

Parameters

uid
The user ID of the remote user.
elapsed
Time (ms) from the local user calling joinChannel to the SDK triggering this callback.

onLocalAudioStateChanged

Callback for changes in local audio stream state.

public void onLocalAudioStateChanged(int state, int reason)

When the state of the local audio stream changes, the SDK triggers this callback to report the current state, helping you troubleshoot audio issues.

Note: When the state is LOCAL_AUDIO_STREAM_STATE_FAILED (3), you can check the error information in the error parameter.

Trigger Timing

This callback is triggered when the state of the local audio stream changes.

Parameters

state
The state of the local audio:
  • LOCAL_AUDIO_STREAM_STATE_STOPPED (0): The local audio is in the initial state.
  • LOCAL_AUDIO_STREAM_STATE_RECORDING (1): The local audio capturing device is started successfully.
  • LOCAL_AUDIO_STREAM_STATE_ENCODING (2): The first frame of audio is encoded successfully.
  • LOCAL_AUDIO_STREAM_STATE_FAILED (3): Failed to start the local audio.
reason
The reason for the local audio state change:
  • LOCAL_AUDIO_STREAM_REASON_OK (0): The local audio state is normal.
  • LOCAL_AUDIO_STREAM_REASON_FAILURE (1): The reason for local audio failure is unclear. Prompt the user to rejoin the channel.
  • LOCAL_AUDIO_STREAM_REASON_DEVICE_NO_PERMISSION (2): No permission to use the local audio capturing device. Prompt the user to grant permission.
  • LOCAL_AUDIO_STREAM_REASON_DEVICE_BUSY (3): The microphone is occupied. Prompt the user to check if another app is using the microphone. Audio capturing will automatically resume about five seconds after the microphone is free, or you can try rejoining the channel.
  • LOCAL_AUDIO_STREAM_REASON_CAPTURE_FAILURE (4): Failed to capture local audio.
  • LOCAL_AUDIO_STREAM_REASON_ENCODE_FAILURE (5): Failed to encode local audio.
  • LOCAL_AUDIO_STREAM_REASON_INTERRUPTED (8): Local audio capturing is interrupted by a system phone call, smart assistant, or alarm. To continue capturing, prompt the user to end the phone call, smart assistant, or alarm.

onLocalAudioStats

Callback for local audio stream statistics.

public void onLocalAudioStats(LocalAudioStats stats) {}

This callback is triggered every two seconds.

Trigger Timing

This callback is triggered every two seconds.

Parameters

stats
Local audio statistics. See LocalAudioStats.

onRemoteAudioStateChanged

Callback for remote audio state change.

public void onRemoteAudioStateChanged(int uid, int state, int reason, int elapsed)

This callback is triggered when the audio state of a remote user in a voice/video call channel or a host in a live broadcast channel changes, and is used to report the current state of the remote audio stream.

Note: This callback may not work properly when the number of users (communication scenario) or hosts (live broadcast scenario) in the channel exceeds 32.

Trigger Timing

This callback is triggered when the audio state of a remote user changes.

Parameters

uid
The user ID of the remote user whose audio state has changed.
state
The remote audio state:
  • REMOTE_AUDIO_STATE_STOPPED (0): The remote audio is in the initial state. The SDK reports this state when REMOTE_AUDIO_REASON_LOCAL_MUTED, REMOTE_AUDIO_REASON_REMOTE_MUTED, or REMOTE_AUDIO_REASON_REMOTE_OFFLINE occurs.
  • REMOTE_AUDIO_STATE_STARTING (1): The first packet of remote audio data is received.
  • REMOTE_AUDIO_STATE_DECODING (2): The remote audio stream is decoded and playing normally. The SDK reports this state when REMOTE_AUDIO_REASON_NETWORK_RECOVERY, REMOTE_AUDIO_REASON_LOCAL_UNMUTED, or REMOTE_AUDIO_REASON_REMOTE_UNMUTED occurs.
  • REMOTE_AUDIO_STATE_FROZEN (3): The remote audio is frozen. The SDK reports this state when REMOTE_AUDIO_REASON_NETWORK_CONGESTION occurs.
  • REMOTE_AUDIO_STATE_FAILED (4): The remote audio failed to start. The SDK reports this state when REMOTE_AUDIO_REASON_INTERNAL occurs.
reason
The reason for the remote audio state change:
  • REMOTE_AUDIO_REASON_INTERNAL (0): The SDK reports this reason when the audio state changes.
  • REMOTE_AUDIO_REASON_NETWORK_CONGESTION (1): Network congestion.
  • REMOTE_AUDIO_REASON_NETWORK_RECOVERY (2): Network recovery.
  • REMOTE_AUDIO_REASON_LOCAL_MUTED (3): The local user stops receiving the remote audio stream or disables the audio module.
  • REMOTE_AUDIO_REASON_LOCAL_UNMUTED (4): The local user resumes receiving the remote audio stream or enables the audio module.
  • REMOTE_AUDIO_REASON_REMOTE_MUTED (5): The remote user stops sending the audio stream or disables the audio module.
  • REMOTE_AUDIO_REASON_REMOTE_UNMUTED (6): The remote user resumes sending the audio stream or enables the audio module.
  • REMOTE_AUDIO_REASON_REMOTE_OFFLINE (7): The remote user leaves the channel.
elapsed
The time (ms) from the local user calling joinChannel until the SDK triggers this callback.

onRemoteAudioStats

Callback that reports transport-layer statistics of each remote audio stream.

public void onRemoteAudioStats(RemoteAudioStats stats) {}

This callback is triggered every two seconds. If there are multiple remote users in the channel, the SDK triggers this callback for each user.

Parameters

stats
Statistics of the remote audio stream. See RemoteAudioStats.

onRemoteAudioTransportStats

Reports transport-layer statistics of each remote audio stream.

public void onRemoteAudioTransportStats(int uid, int delay, int lost, int rxKBitRate)
Deprecated
This callback is deprecated. Use onRemoteAudioStats instead.

This callback reports transport-layer statistics of remote audio streams, such as packet loss rate and network delay after the local user receives audio packets from a remote user.

Trigger Timing

This callback is triggered every 2 seconds during the call when the local user receives audio packets from a remote user.

Parameters

uid
Remote user ID, i.e., the user sending the audio stream.
delay
Network delay from the remote user to the receiver, in milliseconds.
lost
Packet loss rate of audio from the remote user to the receiver, in percentage (%).
rxKBitRate
Received audio bitrate in Kbps.

onUserMuteAudio

Callback when a remote user or host stops or resumes sending audio streams.

public void onUserMuteAudio(int uid, boolean muted)

This callback is triggered when a remote user calls muteLocalAudioStream.

Note: When the number of users (in communication scenario) or hosts (in live streaming scenario) in the channel exceeds 32, this callback may not work properly.

Trigger Timing

This callback is triggered when a remote user calls muteLocalAudioStream to stop or resume sending audio streams.

Parameters

uid
Remote user ID.
muted
Whether the remote user's audio stream is muted:
  • true: Audio stream is muted.
  • false: Audio stream is not muted.

Audio Capture

adjustRecordingSignalVolume

Adjusts the volume of the recorded audio signal.

public abstract int adjustRecordingSignalVolume(int volume);

If you only need to mute the audio signal, Agora recommends using the muteRecordingSignal method.

Timing

You can call this method before or after joining a channel.

Parameters

volume
User volume, range [0,400]:
  • 0: Mute.
  • 100: (Default) Original volume.
  • 400: Four times the original volume (amplifies the audio signal by four times).

Return Values

  • 0: Success.
  • < 0: Failure.

enableInEarMonitoring [1/2]

Enables or disables in-ear monitoring.

public abstract int enableInEarMonitoring(boolean enabled);
Note: You must use a wired or Bluetooth headset to hear the in-ear monitoring effect.

Timing

You can call this method before or after joining a channel.

Parameters

enabled
Whether to enable in-ear monitoring (default is false):
  • true: Enable in-ear monitoring.
  • false: Disable in-ear monitoring.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -8: Please ensure the current audio route is Bluetooth or wired headset.

enableInEarMonitoring [2/2]

Enables or disables the in-ear monitoring feature.

public abstract int enableInEarMonitoring(boolean enabled, int includeAudioFilters);
Note: You must use a wired or Bluetooth headset to hear the in-ear monitoring effect.

Timing

You can call this method before or after joining a channel.

Parameters

enabled
Whether to enable the in-ear monitoring feature.
  • true: Enable in-ear monitoring.
  • false: (Default) Disable in-ear monitoring.
includeAudioFilters
Note: This parameter takes effect only when enabled is true.
Audio filter types for in-ear monitoring:
  • EAR_MONITORING_FILTER_NONE (1 << 0): (1) No audio filter is added to in-ear monitoring.
  • EAR_MONITORING_FILTER_BUILT_IN_AUDIO_FILTERS (1 << 1): (2) Adds voice beautification audio filters to in-ear monitoring. If you implement effects like beautification or sound effects, users can hear the processed sound. This enum value supports bitwise OR combination.
  • EAR_MONITORING_FILTER_NOISE_SUPPRESSION (1 << 2): (4) Adds noise suppression audio filter to in-ear monitoring. This enum value supports bitwise OR combination.
  • EAR_MONITORING_FILTER_REUSE_POST_PROCESSING_FILTER (1 << 15): Reuses the audio filter processed by the sender for in-ear monitoring. This can reduce CPU usage but increases monitoring latency. Suitable for scenarios that are not sensitive to delay but require low CPU usage. This enum value only supports standalone use. When selected, other audio filter configurations are automatically disabled.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -8: Please ensure the current audio route is Bluetooth or wired headset.

enableLocalAudio

Enables or disables the local audio capture function.

public abstract int enableLocalAudio(boolean enabled);
enableLocalAudio controls whether to enable local audio capture and processing. When this method is called to disable or re-enable local audio capture, the local user may hear interruptions in remote audio playback. The difference between this method and muteLocalAudioStream is:
  • enableLocalAudio: Controls whether to enable local audio capture and processing.
  • muteLocalAudioStream: Only controls whether to send the local audio stream, without affecting the audio capture state.

Scenario

enableLocalAudio(false) is suitable for scenarios where only remote audio streams are received without sending locally captured audio. This method does not affect receiving remote audio streams.

Timing

You can call this method before or after joining a channel. Calling it before joining only sets the device state and takes effect immediately after joining.

Related Callbacks

Once the local audio function is disabled or re-enabled, the SDK triggers the onLocalAudioStateChanged callback to report LOCAL_AUDIO_STREAM_STATE_STOPPED (0) or LOCAL_AUDIO_STREAM_STATE_RECORDING (1).

Parameters

enabled
Whether to enable the local audio function:
  • true: (Default) Re-enable the local audio function, i.e., start the local audio capture device (e.g., microphone).
  • false: Disable the local audio function, i.e., stop local audio capture.

Return Values

  • 0: Success.
  • < 0: Failure.

muteRecordingSignal

Sets whether to mute the recording signal.

public abstract int muteRecordingSignal(boolean muted);
If you have called adjustRecordingSignalVolume to adjust the recording signal volume, when you call this method and set the parameter to true, the SDK performs the following:
  • Records the adjusted volume.
  • Mutes the recording signal.
When you call this method again and set the parameter to false, the recording signal volume is restored to the volume recorded before muting.

Timing

This method can be called before or after joining a channel.

Parameters

muted
Whether to mute the recording signal:
  • true: Mute the recording signal.
  • false: (default) Do not mute the recording signal.

Return Values

  • 0: Success.
  • < 0: Failure.

setInEarMonitoringVolume

Sets the in-ear monitoring volume.

public abstract int setInEarMonitoringVolume(int volume);

Timing

You can call this method before or after joining a channel.

Parameters

volume
User volume, range is [0, 400]. 0 means mute, 100 (default) means original volume, 400 means four times the original volume (amplifies the audio signal by four times).

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter setting, e.g., volume out of valid range (less than 0 or greater than 400).

Audio Pre-processing and Post-processing

Audio Effects

enableVoiceAITuner

Enables or disables the Voice AI Tuner.

public abstract int enableVoiceAITuner(boolean enabled, Constants.VOICE_AI_TUNER_TYPE type);

Supports enhanced audio quality and tone style adjustment.

Scenario

Social entertainment scenarios with high audio quality requirements, such as online karaoke, online podcasts, and showroom live streaming.

Timing

You can call this method before or after joining a channel.

Parameters
enabled
Whether to enable the Voice AI Tuner:
  • true: Enable the Voice AI Tuner.
  • false: (Default) Disable the Voice AI Tuner.
type
The audio effect type of the Voice AI Tuner. See VOICE_AI_TUNER_TYPE.
Return Values
  • 0: Success.
  • < 0: Failure.

getAudioEffectManager

Gets the IAudioEffectManager instance used to manage audio effect files.

public abstract IAudioEffectManager getAudioEffectManager();
Return Values

The IAudioEffectManager instance, if the method call succeeds.

setAdvancedAudioOptions

Sets advanced audio options.

public abstract int setAdvancedAudioOptions(AdvancedAudioOptions options);

If you have advanced audio processing needs, such as capturing and sending stereo audio, you can call this method.

Note: Call this method after calling joinChannel, enableAudio, and enableLocalAudio.
Parameters
options
Advanced audio options. See AdvancedAudioOptions.
Return Values
  • 0: Success.
  • < 0: Failure.

setAINSMode

Enables or disables the AI noise reduction feature and sets the noise reduction mode.

public abstract int setAINSMode(boolean enabled, int mode);
You can call this method to enable the AI noise reduction feature. Once enabled, the SDK automatically detects and reduces both stationary and non-stationary noise in the audio while preserving voice quality.
  • Stationary noise refers to noise signals with consistent statistical characteristics and minimal amplitude fluctuation over time. Common sources include:
    • TV;
    • Air conditioners;
    • Mechanical equipment.
  • Non-stationary noise refers to noise signals with large amplitude fluctuations over time. Common sources include:
    • Thunder;
    • Explosions;
    • Cracking sounds.
Note:
  • This method depends on the AI noise suppression dynamic library libagora_ai_noise_suppression_extension.so. If the library is removed, the feature cannot be enabled.
  • Agora does not recommend enabling this feature on devices running Android 6.0 or lower.
Scenario

In scenarios such as co-hosting, online education, and video conferencing, this feature can detect and reduce background noise to improve the experience.

Timing

You can call this method before or after joining a channel.

Parameters
enabled
Whether to enable AI noise reduction:
  • true: Enable AI noise reduction.
  • false: (Default) Disable AI noise reduction.
mode
AI noise reduction mode:
  • 0: (Default) Balanced mode. Balances noise reduction performance and latency.
  • 1: Aggressive mode. Suitable for scenarios requiring strong noise reduction, such as outdoor live streaming. Offers stronger noise reduction but may affect the original audio characteristics.
  • 2: Low-latency aggressive mode. Offers about half the latency of the balanced and aggressive modes. Suitable for scenarios requiring low-latency noise reduction, such as real-time online chorus.
Return Values
  • 0: Success.
  • < 0: Failure.

setAudioEffectParameters

Sets parameters for preset audio effects provided by the SDK.

public abstract int setAudioEffectParameters(int preset, int param1, int param2);
Since
Available since v3.2.0.
Call this method to set the following parameters for the local user who sends the audio stream:
  • 3D voice effect: Sets the cycle period of the 3D voice.
  • Pitch correction effect: Sets the basic mode and tonic of pitch correction.
Agora recommends binding this method to UI elements to allow users to interactively adjust pitch correction effects.To achieve better voice effects, it is recommended to call the following APIs before calling this method:
  • Call setAudioScenario to set the audio scenario to high-quality audio, i.e., AUDIO_SCENARIO_GAME_STREAMING (3).
  • Call setAudioProfile and set profile to MUSIC_HIGH_QUALITY (4) or MUSIC_HIGH_QUALITY_STEREO (5).
Note:
Parameters
preset
Preset audio effect options provided by the SDK:
  • ROOM_ACOUSTICS_3D_VOICE: 3D voice effect.
    • Before setting this enum value, you must set profile in setAudioProfile to MUSIC_STANDARD_STEREO (3) or MUSIC_HIGH_QUALITY_STEREO (5), otherwise the setting will not take effect.
    • After enabling this effect, users must use stereo playback devices to hear the expected result.
  • PITCH_CORRECTION: Pitch correction effect.
param1
  • When preset is ROOM_ACOUSTICS_3D_VOICE, this parameter indicates the cycle period of the 3D voice effect in seconds. The range is [1,60], and the default is 10, meaning the sound circles around you every 10 seconds.
  • When preset is PITCH_CORRECTION, this parameter indicates the basic mode of pitch correction:
    • 1: (Default) Natural major.
    • 2: Natural minor.
    • 3: Japanese pentatonic scale.
param2
  • When preset is ROOM_ACOUSTICS_3D_VOICE, set param2 to 0.
  • When preset is PITCH_CORRECTION, this parameter indicates the tonic of pitch correction:
    • 1: A
    • 2: A#
    • 3: B
    • 4: (Default) C
    • 5: C#
    • 6: D
    • 7: D#
    • 8: E
    • 9: F
    • 10: F#
    • 11: G
    • 12: G#
Return Values
  • 0: Success.
  • < 0: Failure.

setAudioEffectPreset

Sets the SDK's preset audio effects.

public abstract int setAudioEffectPreset(int preset);
Since
Available since v3.2.0.
This method does not change the gender characteristics of the original voice. After setting, all users in the channel can hear the effect. To achieve better voice effects, it is recommended to call the following methods before this:
  • Call setAudioScenario to set the audio scenario to high-quality mode, i.e., AUDIO_SCENARIO_GAME_STREAMING (3).
  • Call setAudioProfile and set the profile parameter to MUSIC_HIGH_QUALITY (4) or MUSIC_HIGH_QUALITY_STEREO (5).
Note:
Timing

You can call this method before or after joining a channel.

Parameters
preset
Preset audio effects:
  • AUDIO_EFFECT_OFF (0): Disable audio effect and use original voice.
  • ROOM_ACOUSTICS_KTV (1): Typical reverb style of KTV.
  • ROOM_ACOUSTICS_VOCAL_CONCERT (2): Typical reverb style of a concert hall.
  • ROOM_ACOUSTICS_STUDIO (3): Typical reverb style of a recording studio.
  • ROOM_ACOUSTICS_PHONOGRAPH (4): Typical reverb style of a vintage phonograph.
  • ROOM_ACOUSTICS_VIRTUAL_STEREO (5): Virtual stereo effect that renders mono audio into stereo. Requires setAudioProfile with profile set to MUSIC_HIGH_QUALITY (4) or MUSIC_HIGH_QUALITY_STEREO (5), otherwise invalid.
  • ROOM_ACOUSTICS_SPACIAL (6): More spatial audio effect.
  • ROOM_ACOUSTICS_ETHEREAL (7): More ethereal audio effect.
  • ROOM_ACOUSTICS_VIRTUAL_SURROUND_SOUND (8): Virtual surround sound effect. SDK generates simulated surround sound field based on stereo channel. Requires stereo playback device to hear expected effect.
  • ROOM_ACOUSTICS_CHORUS (9): Chorus effect, suitable for chorus scenes, enhances vocal layering and spatial sense.
  • ROOM_ACOUSTICS_3D_VOICE (10): 3D voice effect, makes the voice move around the user, default cycle is 10 seconds. Requires setAudioProfile with profile set to MUSIC_STANDARD_STEREO (3) or MUSIC_HIGH_QUALITY_STEREO (5), otherwise invalid. Requires stereo playback device.
  • VOICE_CHANGER_EFFECT_UNCLE (11): Uncle voice effect, recommended for male voice.
  • VOICE_CHANGER_EFFECT_OLDMAN (12): Old man voice effect, recommended for male voice.
  • VOICE_CHANGER_EFFECT_BOY (13): Boy voice effect, recommended for male voice.
  • VOICE_CHANGER_EFFECT_SISTER (14): Young female voice effect, recommended for female voice.
  • VOICE_CHANGER_EFFECT_GIRL (15): Girl voice effect, recommended for female voice.
  • VOICE_CHANGER_EFFECT_PIGKING (16): Pig King voice effect, bear-like roar.
  • VOICE_CHANGER_EFFECT_HULK (17): Hulk voice effect.
  • STYLE_TRANSFORMATION_RNB (18): R&B music style reverb. Requires setAudioProfile with profile set to MUSIC_HIGH_QUALITY (4) or MUSIC_HIGH_QUALITY_STEREO (5), otherwise invalid.
  • STYLE_TRANSFORMATION_POPULAR (19): Pop music style reverb. Requires setAudioProfile with profile set to MUSIC_HIGH_QUALITY (4) or MUSIC_HIGH_QUALITY_STEREO (5), otherwise invalid.
  • PITCH_CORRECTION (20): Pitch correction effect, adjusts pitch based on natural C major scale. After setting, you can call setAudioEffectParameters to adjust tuning mode and tonic.
Return Values
  • 0: Success.
  • < 0: Failure.

setLocalVoiceEqualization

Sets the local voice equalization effect.

public abstract int setLocalVoiceEqualization(Constants.AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain);
Timing

You can call this method before or after joining a channel.

Parameters
bandFrequency
Band index, range is 0 to 9, corresponding to the center frequency bands of 10 voice effects: 31, 62, 125, 250, 500, 1k, 2k, 4k, 8k, and 16k Hz. See AUDIO_EQUALIZATION_BAND_FREQUENCY.
bandGain
Gain value for each band in dB. Range is -15 to 15, default is 0.
Return Values
  • 0: Success.
  • < 0: Failure.

setLocalVoiceFormant

Sets the formant ratio to change the vocal timbre.

public abstract int setLocalVoiceFormant(double formantRatio);

The formant ratio affects the timbre of the voice. The smaller the value, the deeper the voice; the larger the value, the sharper the voice. If you want to change both timbre and pitch, it is recommended to use setLocalVoiceFormant and setLocalVoicePitch together.

Scenario

You can call this method to set the formant ratio of the local audio to change the voice timbre.

Timing

You can call this method before or after joining a channel.

Parameters
formantRatio
Formant ratio. Value range is [-1.0, 1.0]. (Default is 0.0)
Note: It is recommended to set this value within the range [-0.4, 0.6], otherwise the sound may be severely distorted.
Return Values
  • 0: Success.
  • < 0: Failure.

setLocalVoicePitch

Sets the pitch of the local voice.

public abstract int setLocalVoicePitch(double pitch);
Timing

You can call this method before or after joining a channel.

Parameters
pitch
Pitch of the local voice. Value range is [0.5, 2.0]. The smaller the value, the lower the pitch. (Default is 1.0, which means no change in pitch.)
Return Values
  • 0: Success.
  • < 0: Failure.

setLocalVoiceReverb

Sets the reverb effect of the local voice.

public abstract int setLocalVoiceReverb(Constants.AUDIO_REVERB_TYPE reverbKey, int value);

You can use the easier method setAudioEffectPreset to achieve preset reverb effects such as Pop, R&B, and KTV.

Note: You can call this method before or after joining a channel.
Parameters
reverbKey
Reverb key. See AUDIO_REVERB_TYPE.
value
Value of the reverb key.
Return Values
  • 0: Success.
  • < 0: Failure.

setVoiceBeautifierParameters

Sets parameters for preset voice beautifier effects.

public abstract int setVoiceBeautifierParameters(int preset, int param1, int param2);
Since
Available since v3.3.0.
To achieve better voice effects, it is recommended to call the following APIs before calling this method:
  • Call setAudioScenario to set the audio scenario to high-quality audio, i.e., AUDIO_SCENARIO_GAME_STREAMING (3).
  • Call setAudioProfile and set the profile parameter to MUSIC_HIGH_QUALITY (4) or MUSIC_HIGH_QUALITY_STEREO (5).
Note:
Parameters
preset
Preset audio effect option:
  • SINGING_BEAUTIFIER: Singing beautifier effect.
param1
Gender characteristic option for singing voice:
  • 1: Male voice.
  • 2: Female voice.
param2
Reverb effect option for singing voice:
  • 1: Small room reverb.
  • 2: Large room reverb.
  • 3: Hall reverb.
Return Values
  • 0: Success.
  • < 0: Failure.

setVoiceBeautifierPreset

Sets the preset voice beautifier effect.

public abstract int setVoiceBeautifierPreset(int preset);
Since
Added since v3.2.0.
You can set different voice beautifier effects for different scenarios. To achieve better voice effects, Agora recommends calling the following APIs before this method:
  • Call setAudioScenario to set the audio scenario to high-quality audio, i.e., AUDIO_SCENARIO_GAME_STREAMING (3).
  • Call setAudioProfile, and set profile to MUSIC_HIGH_QUALITY (4) or MUSIC_HIGH_QUALITY_STEREO (5).
Note:
Timing

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

Parameters
preset
Preset voice beautifier options:
  • VOICE_BEAUTIFIER_OFF: Disables the voice beautifier and uses the original voice.
  • CHAT_BEAUTIFIER_MAGNETIC: A more magnetic voice (male only).
  • CHAT_BEAUTIFIER_FRESH: A fresher voice (female only).
  • CHAT_BEAUTIFIER_VITALITY: A more energetic voice (female only).
  • SINGING_BEAUTIFIER: Singing beautifier effect.
    • Calling setVoiceBeautifierPreset with this option beautifies male voices and adds a reverb effect similar to singing in a small room. Recommended for male voices only, otherwise distortion may occur.
    • Calling setVoiceBeautifierParameters with this option beautifies both male and female voices and adds a reverb effect.
  • TIMBRE_TRANSFORMATION_VIGOROUS: A more powerful voice.
  • TIMBRE_TRANSFORMATION_DEEP: A deeper voice.
  • TIMBRE_TRANSFORMATION_MELLOW: A softer voice.
  • TIMBRE_TRANSFORMATION_FALSETTO: Falsetto.
  • TIMBRE_TRANSFORMATION_FULL: A fuller voice.
  • TIMBRE_TRANSFORMATION_CLEAR: A clearer voice.
  • TIMBRE_TRANSFORMATION_RESOUNDING: A louder voice.
  • TIMBRE_TRANSFORMATION_RINGING: A more penetrating voice.
  • ULTRA_HIGH_QUALITY_VOICE: Ultra high-quality voice that makes audio clearer and restores more details.
    • For better sound quality, Agora recommends calling setAudioProfile before this method, setting profile to MUSIC_HIGH_QUALITY (4) or MUSIC_HIGH_QUALITY_STEREO (5), and scenario to AUDIO_SCENARIO_GAME_STREAMING (3).
    • If your audio capture device already restores audio details well, Agora does not recommend enabling ultra high-quality voice, as the SDK may over-enhance details, resulting in unexpected audio effects.
Return Values
  • 0: Success.
  • < 0: Failure.

setVoiceConversionPreset

Sets the SDK's preset voice conversion effects.

public abstract int setVoiceConversionPreset(int preset);
Since
Available since v3.3.1.
You can call this method to set a preset voice conversion effect for the local user who is publishing the audio stream. Once set, all users in the channel can hear the effect. You can set different voice conversion effects for different scenarios. To achieve better audio effects, it is recommended to call the following APIs before this method:
  • Call setAudioScenario to set the audio scenario to high-quality audio, i.e., AUDIO_SCENARIO_GAME_STREAMING (3).
  • Call setAudioProfile and set the profile parameter to MUSIC_HIGH_QUALITY (4) or MUSIC_HIGH_QUALITY_STEREO (5).
Note:
Timing

You can call this method before or after joining a channel.

Parameters
preset
Options for the SDK's preset voice conversion effects:
  • VOICE_CONVERSION_OFF: Disable voice conversion and use the original voice.
  • VOICE_CHANGER_NEUTRAL: Neutral voice. Recommended for female voices to avoid distortion.
  • VOICE_CHANGER_SWEET: Sweet voice. Recommended for female voices to avoid distortion.
  • VOICE_CHANGER_SOLID: Deep voice. Recommended for male voices to avoid distortion.
  • VOICE_CHANGER_BASS: Bass voice. Recommended for male voices to avoid distortion.
Return Values
  • 0: Success.
  • < 0: Failure.

Stereo

enableSoundPositionIndication

Enables or disables stereo panning for remote users.

public abstract int enableSoundPositionIndication(boolean enabled);

Call this method before joining a channel. Once enabled, the local user can call setRemoteVoicePosition to track the position of remote users.

Parameters
enabled
Whether to enable stereo panning for remote users:
  • true: Enable stereo panning.
  • false: Disable stereo panning.
Return Values
  • 0: Success.
  • < 0: Failure.

setRemoteVoicePosition

Sets the spatial position and volume of a remote user's voice.

public abstract int setRemoteVoicePosition(int uid, double pan, double gain);

This method sets the spatial position and volume of a remote user's voice by adjusting the balance between the left and right audio channels. This helps the local user identify the position of the remote user and creates a sense of space. This method is suitable for large-scale multiplayer online games, such as battle royale games.

Note:
  • To make this method take effect, call enableSoundPositionIndication before joining a channel to enable stereo sound positioning for remote users.
  • For optimal voice positioning, it is recommended to use wired headphones.
  • Call this method after joining a channel.
Parameters
uid
The ID of the remote user.
pan
The spatial position of the remote user's voice. The range is from -1.0 to 1.0:
  • 0.0: (Default) The remote voice comes from the front.
  • -1.0: The remote voice comes from the left.
  • 1.0: The remote voice comes from the right.
gain
The volume of the remote user. The range is from 0.0 to 100.0. The default value is 100.0 (original volume of the remote user). The smaller the value, the lower the volume.
Return Values
  • 0: Success.
  • < 0: Failure.

setRemoteVoicePositionEx

Sets the 2D position and volume of the remote user's voice.

public abstract int setRemoteVoicePositionEx(int uid, double pan, double gain, RtcConnection connection);

This method sets the voice position and volume of a remote user. After calling this method, the difference between the left and right audio channels allows you to perceive the remote user's position in real time, creating a sense of space. This method is suitable for large-scale multiplayer online games, such as battle royale games.

Note:
  • For the best voice positioning effect, Agora recommends using wired headphones.
  • Call this method after joining the channel.
Scenario

This method applies to multi-channel scenarios.

Parameters
uid
Remote user ID.
pan
The voice position of the remote user. The value range is from -1.0 to 1.0:
  • -1.0: The remote voice comes from the left.
  • 0.0: (Default) The remote voice comes from the front.
  • 1.0: The remote voice comes from the right.
gain
The volume of the remote user. The value range is from 0.0 to 100.0, with a default value of 100.0. The smaller the value, the lower the volume.
connection
Connection information. See RtcConnection.
Return Values
  • 0: Success.
  • < 0: Failure.

Spatial Audio

clearRemotePositions

Removes all spatial positions of remote users.

public abstract int clearRemotePositions();

After calling this method, the local user will no longer hear any remote users. You can also call this method after leaving the channel to release resources.

Return Values
  • 0: Success.
  • < 0: Failure.

enableSpatialAudio

Enables or disables spatial audio.

public abstract int enableSpatialAudio(boolean enabled);

You can call setRemoteUserSpatialAudioParams to set the spatial audio parameters for remote users.

Note:
  • You can call this method before or after joining a channel.
  • This method depends on the spatial audio dynamic library libagora_spatial_audio_extension.so. If this dynamic library is deleted, the feature cannot be enabled properly.
Parameters
enabled
Whether to enable spatial audio:
  • true: Enable spatial audio.
  • false: Disable spatial audio.
Return Values
  • 0: Success.
  • < 0: Failure.

muteAllRemoteAudioStreams

Stops or resumes subscribing to all remote users’ audio streams.

public abstract int muteAllRemoteAudioStreams(boolean mute);

After calling this method, the local user will stop or resume subscribing to all remote users’ audio streams, including users who join the channel later.

Note:
  • Call this method after calling joinChannel.
  • When using spatial audio, if you need to set whether to stop subscribing to all remote users’ audio streams, Agora recommends using this method instead of the method with the same name under RtcEngine.
  • After calling this method, you need to call updateSelfPosition and updateRemotePosition to update the spatial positions of the local and remote users, otherwise the settings of this method will not take effect.
Parameters
mute
Whether to stop subscribing to all remote users’ audio streams:
  • true: Stop subscribing to all remote users’ audio streams.
  • false: Subscribe to all remote users’ audio streams.
Return Values
  • 0: Success.
  • < 0: Failure.

muteLocalAudioStream

Stops or resumes publishing the local audio stream.

public abstract int muteLocalAudioStream(boolean mute);
Note: The muteLocalAudioStream method does not affect any ongoing audio recording because it does not disable the audio capturing device. Call this method after calling joinChannel. When using spatial audio, if you need to set whether to stop publishing the local audio stream, Agora recommends calling this method instead of the method with the same name under RtcEngine. After this method is successfully called, the onUserMuteAudio and onRemoteAudioStateChanged callbacks are triggered on the remote client.
Related Callbacks

After this method is successfully called, the onUserMuteAudio and onRemoteAudioStateChanged callbacks are triggered on the remote client.

Parameters
mute
Whether to stop publishing the local audio stream:
  • true: Stop publishing the local audio stream.
  • false: Publish the local audio stream.
Return Values
  • 0: Success.
  • < 0: Failure.

muteRemoteAudioStream

Stops or resumes subscribing to the specified remote user’s audio stream.

public abstract int muteRemoteAudioStream(int uid, boolean mute);
Note:
  • Call this method after calling joinChannel.
  • When using spatial audio, if you need to set whether to stop subscribing to a specific user’s audio stream, Agora recommends calling this method instead of the muteRemoteAudioStream method.
Parameters
uid
Remote user ID. This parameter must match the user ID passed when the user joined the channel.
mute
Whether to subscribe to the specified remote user’s audio stream:
  • true: Stop subscribing to the specified user’s audio stream.
  • false: (Default) Subscribe to the specified user’s audio stream. The SDK decides whether to subscribe based on the distance between the local and remote users.
Return Values
  • 0: Success.
  • < 0: Failure.

removeRemotePosition

Removes the spatial position information of a specified remote user.

public abstract int removeRemotePosition(int uid);

After successfully calling this method, you will no longer hear the specified remote user's voice. After leaving the channel, to avoid wasting computing resources, it is recommended to call this method to remove the spatial position information of the specified remote user. Otherwise, the user's spatial position information will be retained. When the number of remote users exceeds the number of audio streams that can be received as set by setMaxAudioRecvCount, the system will automatically unsubscribe from the audio stream of the farthest user based on relative distance.

Parameters
uid
uid. This parameter must be the same as the user ID passed in when the user joined the channel.
Return Values
  • 0: Success.
  • < 0: Failure.

setAudioRecvRange

Sets the local user’s audio reception range.

public abstract int setAudioRecvRange(float range);

You can call this method at any time to update the audio reception range. After setting it successfully, the local user can only receive audio from remote users within the specified range or on the same team.

Parameters
range
Maximum audio reception range in meters. The value must be greater than 0. (Default is 20)
Return Values
  • 0: Success.
  • < 0: Failure.

setDistanceUnit

Sets the number of meters corresponding to each unit of distance in the game engine.

public abstract int setDistanceUnit(float unit);

In Agora’s spatial audio algorithm, distance is calculated in meters. By default, the SDK converts each unit of distance in the game engine to 1 meter. You can call this method to convert each unit of distance in the game engine to a specified number of meters.

Parameters
unit
The number of meters corresponding to each unit of distance in the game engine. The value must be greater than 0.00. Default is 1.00. For example, setting this parameter to 2.00 means each unit of distance in the game engine equals 2 meters. The larger the value, the faster the sound attenuates when a remote user moves away from the local user.
Return Values
  • 0: Success.
  • < 0: Failure.

setHeadphoneEQParameters

Sets the low and high frequency parameters of the headphone equalizer.

public abstract int setHeadphoneEQParameters(int lowGain, int highGain);

If calling setHeadphoneEQPreset does not achieve the desired effect, you can call setHeadphoneEQParameters to further adjust the low and high frequency parameters of the headphone equalizer.

Parameters
lowGain
Low frequency parameter of the headphone equalizer, range is [-10, 10]. The higher the value, the deeper the sound.
highGain
High frequency parameter of the headphone equalizer, range is [-10, 10]. The higher the value, the clearer the sound.
Return Values
  • 0: Success.
  • < 0: Failure.
    • -1: A general error occurred.

setHeadphoneEQPreset

Sets the preset headphone equalizer effect.

public abstract int setHeadphoneEQPreset(int preset);

This method is mainly used in spatial audio scenarios. You can select a preset headphone equalizer to listen to audio and achieve the desired audio experience.

Note: If your headphones already have good equalization, calling this method may not provide a noticeable improvement and may even reduce the experience.
Parameters
preset
Preset headphone equalizer effect:
  • HEADPHONE_EQUALIZER_OFF: Disable headphone equalizer and hear the original audio.
  • HEADPHONE_EQUALIZER_OVEREAR: Use equalizer for over-ear headphones.
  • HEADPHONE_EQUALIZER_INEAR: Use equalizer for in-ear headphones.
Return Values
  • 0: Success.
  • < 0: Failure.
    • -1: A general error occurred (no specific reason).

setMaxAudioRecvCount

Sets the maximum number of audio streams you can receive within the specified audio reception range.

public abstract int setMaxAudioRecvCount(int maxCount);

If the number of receivable audio streams exceeds this value, the local user will receive the maxCount audio streams closest to them.

Parameters
maxCount
The maximum number of audio streams you can receive within the specified audio reception range. The value must be less than or equal to 16. (Default is 10)
Return Values
  • 0: Success.
  • < 0: Failure.

setPlayerAttenuation

Sets the sound attenuation properties of the media player.

public abstract int setPlayerAttenuation(int playerId, double attenuation, boolean forceSet);
Parameters
playerId
The ID of the media player. You can get this ID by calling getMediaPlayerId.
attenuation
Sound attenuation coefficient of the remote user or media player. Value range: [0,1]. Details:
  • 0: Broadcast mode. Volume and tone do not attenuate with distance. The local user hears the same volume and tone regardless of distance.
  • (0, 0.5): Weak attenuation mode. Volume and tone attenuate slightly during transmission. Sound travels farther than in real environments.
  • 0.5: (Default) Simulates real-world volume attenuation. Equivalent to not setting the speaker_attenuation parameter.
  • (0.5, 1]: Strong attenuation mode. Volume and tone attenuate rapidly during transmission.
forceSet
Whether to forcefully set the media player’s sound attenuation effect:
  • true: Forcefully use the attenuation value to set the media player’s attenuation effect. In this case, the audioAttenuation setting in SpatialAudioZone has no effect on the media player.
  • false: Do not forcefully use the attenuation value to set the media player’s sound attenuation effect. Details:
    • If the sound source and listener are inside and outside the sound insulation zone respectively, the attenuation effect is determined by the audioAttenuation in SpatialAudioZone.
    • If the sound source and listener are inside the same or outside the same sound insulation zone, the attenuation effect is determined by the attenuation parameter in this method.
Return Values
  • 0: Success.
  • < 0: Failure.

setRemoteAudioAttenuation

Sets the audio attenuation effect for a specified user.

public abstract int setRemoteAudioAttenuation(int uid, double attenuation, boolean forceSet);
Parameters
uid
User ID. This parameter must be the same as the user ID passed in when the user joined the channel.
attenuation
Audio attenuation coefficient for the user, range [0, 1]. Value details:
  • 0: Broadcast mode. Volume and tone do not attenuate with distance. The local user hears consistent volume and tone regardless of distance.
  • (0, 0.5): Weak attenuation mode. Volume and tone attenuate slightly during transmission. Sound travels farther than in real environments.
  • 0.5: (Default) Simulates real-world volume attenuation. Equivalent to not setting the speaker_attenuation parameter.
  • (0.5, 1]: Strong attenuation mode. Volume and tone attenuate quickly during transmission.
forceSet
Whether to forcefully apply the user's audio attenuation effect:
  • true: Forcefully apply the attenuation setting. The audioAttenuation value set in SpatialAudioZone becomes ineffective for this user.
  • false: Do not forcefully apply the attenuation setting. Behavior:
    • If the source and receiver are inside and outside the zone respectively, the attenuation is determined by audioAttenuation in SpatialAudioZone.
    • If both are inside or both are outside the same zone, the attenuation is determined by the attenuation value in this method.
Return Values
  • 0: Success.
  • < 0: Failure.

setRemoteUserSpatialAudioParams

Sets the spatial audio parameters for a remote user.

public abstract int setRemoteUserSpatialAudioParams(int uid, SpatialAudioParams params);

Call this method after enableSpatialAudio. After successful configuration, you can hear the remote user's voice with spatial effects.

Parameters
uid
The user ID, which must be the same as the ID used when the user joins the channel.
params
Spatial audio parameters. See SpatialAudioParams.
Return Values
  • 0: Success.
  • < 0: Failure.

setSpatialAudioParams

Enables or disables spatial audio for the media player.

int setSpatialAudioParams(SpatialAudioParams params);

To disable spatial audio, set the params parameter to null.

Parameters
params
The spatial audio parameters for the media player. See SpatialAudioParams.
Return Values
  • 0: Success.
  • < 0: Failure.

setZones

Sets sound insulation zones.

public abstract int setZones(SpatialAudioZone[] zones);
In virtual interaction scenarios, you can use this method to set sound insulation zones and sound attenuation coefficients. When the sound source (can be a user or media player) and the receiver are inside and outside the sound insulation zone respectively, you can experience attenuation effects similar to real environments where sound is blocked by walls:
  • When the sound source and receiver are inside and outside the sound insulation zone respectively, the attenuation effect is determined by the sound attenuation coefficient in SpatialAudioZone.
  • If the user or media player is inside the same sound insulation zone, the attenuation effect is determined by the attenuation parameter in setPlayerAttenuation or setRemoteAudioAttenuation. If you do not call setPlayerAttenuation or setRemoteAudioAttenuation, the SDK uses a default sound attenuation coefficient of 0.5 to simulate real-world sound attenuation.
  • If the sound source and receiver are in two different sound insulation zones, the receiver cannot hear the sound source.
Note: If this method is called multiple times, the last setting will take effect.
Parameters
zones
Sound insulation zone settings. If this parameter is set to null, all sound insulation zones are cleared. See SpatialAudioZone.
Return Values
  • 0: Success.
  • < 0: Failure.

updatePlayerPositionInfo

Updates the spatial position of the media player.

public abstract int updatePlayerPositionInfo(int playerId, RemoteVoicePositionInfo positionInfo);

After calling this method, the local user can hear the spatial position changes of the media player.

Timing

This method can be called before or after joining a channel.

Parameters
playerId
The ID of the media player. You can get this ID by calling getMediaPlayerId.
positionInfo
The spatial position of the media player. See RemoteVoicePositionInfo.
Return Values
  • 0: Success.
  • < 0: Failure.

updateRemotePosition

Updates the spatial position of a specified remote user.

public abstract int updateRemotePosition(int uid, RemoteVoicePositionInfo posInfo);

After calling this method, the SDK calculates spatial audio parameters based on the relative position between the local and remote users.

Note: Call this method after calling the joinChannel method.
Parameters
uid
User ID. Must be the same as the user ID passed in when the user joined the channel.
posInfo
Spatial position of the remote user. See RemoteVoicePositionInfo.
Return Values
  • 0: Success.
  • < 0: Failure.

updateSelfPosition

Updates the local user's spatial position.

public abstract int updateSelfPosition(float[] position, float[] axisForward, float[] axisRight, float[] axisUp);

updateSelfPosition should be used together with updateRemotePosition. The SDK calculates the relative position between the local and remote users based on the parameters of this method and updateRemotePosition, and then calculates the spatial audio parameters accordingly.

Parameters
position
Coordinates in the world coordinate system. This parameter is an array of length 3, representing the forward, right, and up coordinates respectively.
axisForward
Unit vector of the x-axis in the coordinate system. This parameter is an array of length 3, representing the forward, right, and up coordinates respectively.
axisRight
Unit vector of the y-axis in the coordinate system. This parameter is an array of length 3, representing the forward, right, and up coordinates respectively.
axisUp
Unit vector of the z-axis in the coordinate system. This parameter is an array of length 3, representing the forward, right, and up coordinates respectively.
Return Values
  • 0: Success.
  • < 0: Failure.

Audio Mixer

startLocalAudioMixer

Starts local audio mixing.

public abstract int startLocalAudioMixer(LocalAudioMixerConfiguration config);
This method supports merging multiple audio streams locally into one. For example, you can mix the audio captured by the local microphone, media player, sound card, and remote users into one audio stream and publish it to the channel.
  • To mix locally captured audio streams, set publishMixedAudioTrack to true in ChannelMediaOptions, and then publish the mixed audio stream to the channel.
  • To mix remote audio streams, ensure the remote audio streams are already published in the channel and that you have subscribed to the audio streams to be mixed.
Note: To ensure audio quality, it is recommended to mix no more than 10 audio streams.
Scenario
You can enable this feature in the following scenarios:
  • When using local video mixing, you can simultaneously capture and publish the audio stream associated with the mixed video stream.
  • In live streaming scenarios, users can receive audio streams in the channel, mix multiple audio streams locally, and forward the mixed stream to other channels.
  • In online classrooms, teachers can mix the audio from interactions with students locally and forward it to other channels.
Timing

You can call this method before or after joining a channel.

Parameters
config
Configuration parameters for local audio mixing. See LocalAudioMixerConfiguration.
Return Values
  • 0: Success.
  • < 0: Failure.
    • -7: The RtcEngine object has not been initialized. Please initialize the RtcEngine object before calling this method.

stopLocalAudioMixer

Stops local audio mixing.

public abstract int stopLocalAudioMixer();

After calling startLocalAudioMixer, you can call this method to stop audio mixing.

Timing

Call this method after calling startLocalAudioMixer.

Return Values
  • 0: Success.
  • < 0: Failure.
    • -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method.

updateLocalAudioMixerConfiguration

Updates local audio mixing configuration.

public abstract int updateLocalAudioMixerConfiguration(LocalAudioMixerConfiguration config);
Note: To ensure audio quality, it is recommended to mix no more than 10 audio streams.
Timing

Call this method after calling startLocalAudioMixer.

Parameters
config
Configuration for local audio mixing. See LocalAudioMixerConfiguration.
Return Values
  • 0: Success.
  • < 0: Failure.
    • -7: The RtcEngine object has not been initialized. Please initialize the RtcEngine object before calling this method.

Raw Audio Data

getEarMonitoringAudioParams

Sets the data format for the onEarMonitoringAudioFrame callback.

@CalledByNative public abstract AudioParams getEarMonitoringAudioParams();

When calling registerAudioFrameObserver to register an audio frame observer, you need to implement this callback. The SDK triggers this callback, and you can set the audio format in the return value of this callback.

Note: The SDK triggers the onEarMonitoringAudioFrame callback based on the sampling interval calculation formula you set in the return value. Sampling interval (seconds) = samplePerCall / (sampleRate × channel). Make sure the sampling interval is ≥ 0.01 seconds.

Return Values

Audio format for ear monitoring. See AudioParams.

getMixedAudioParams

Sets the data format for the onMixedAudioFrame callback.

@CalledByNative public abstract AudioParams getMixedAudioParams();

When calling registerAudioFrameObserver to register the audio frame observer, you need to implement this callback. After successfully registering the audio frame observer, the SDK triggers this callback, and you can set the audio format in the return value of this callback.

Note: The SDK triggers the onMixedAudioFrame callback based on the sampling interval calculation formula set in the return value. Sampling interval (seconds) = samplePerCall / (sampleRate × channel). Make sure the sampling interval is ≥ 0.01 seconds.

Return Values

Returns an AudioParams object upon successful method call. See AudioParams.

getObservedAudioFramePosition

Sets the audio data observation position.

@CalledByNative public abstract int getObservedAudioFramePosition();
After successfully registering the audio frame observer, the SDK calls this callback at each specific audio frame processing node to determine whether to trigger the following callbacks: You can set one or more positions to observe by modifying the return value of getObservedAudioFramePosition according to your scenario needs.To observe multiple positions, use the | (bitwise OR) operator. To conserve system resources, it is recommended to minimize the number of observed frame positions.

Return Values

Returns a bitmask to set observation positions. The possible values are:
  • POSITION_PLAYBACK (0x0001): Observes the playback audio after mixing from all remote users, corresponding to the onPlaybackAudioFrame callback.
  • POSITION_RECORD (0x0002): Observes the audio captured by the local user, corresponding to the onRecordAudioFrame callback.
  • POSITION_MIXED (0x0004): Observes the playback audio after mixing the local user and all remote users, corresponding to the onMixedAudioFrame callback.
  • POSITION_BEFORE_MIXING (0x0008): Observes the audio of a single remote user before mixing, corresponding to the onPlaybackAudioFrameBeforeMixing callback.
  • POSITION_EAR_MONITORING (0x0010): Observes the local user's in-ear monitoring audio, corresponding to the onEarMonitoringAudioFrame callback.

getPlaybackAudioParams

Sets the data format for the onPlaybackAudioFrame callback.

public abstract AudioParams getPlaybackAudioParams()

You need to register the callback when calling the registerAudioFrameObserver method. After successfully registering the audio observer, the SDK triggers this callback. You can set the audio format in the return value of this callback.

Note: The SDK calculates the sampling interval based on the AudioParams you set in the return value and triggers the onPlaybackAudioFrame callback accordingly. The formula for calculating the sampling interval is: Sampling interval (seconds) = samplePerCall / (sampleRate × channel). Make sure the sampling interval is ≥ 0.01 seconds.

Return Values

Returns an AudioParams object upon successful method call. See AudioParams.

getRecordAudioParams

Sets the audio format for the onRecordAudioFrame callback.

@CalledByNative public abstract AudioParams getRecordAudioParams();

After calling registerAudioFrameObserver to register the callback, the SDK triggers this callback. You can set the audio format in the return value of this callback.

Note: The SDK calculates the sampling interval and triggers the onRecordAudioFrame callback based on the AudioParams you set in the return value. Sampling interval (seconds) = samplePerCall / (sampleRate × channel). Make sure the sampling interval is ≥ 0.01 seconds.

Return Values

If the method call succeeds, returns an AudioParams object.

registerAudioFrameObserver

Registers an audio frame observer.

public abstract int registerAudioFrameObserver(IAudioFrameObserver observer);

After calling this method to register an audio frame observer, the SDK triggers the onMixedAudioFrame, onRecordAudioFrame, onPlaybackAudioFrame, onPlaybackAudioFrameBeforeMixing, or onEarMonitoringAudioFrame callback.

Timing

Call this method before joining a channel.

Related Callbacks

Related callbacks: onMixedAudioFrame, onRecordAudioFrame, onPlaybackAudioFrame, onPlaybackAudioFrameBeforeMixing, onEarMonitoringAudioFrame.

Parameters

observer
The audio frame observer instance. See IAudioFrameObserver. Set to null to release the instance. It is recommended to call this method after receiving the onLeaveChannel callback to release the audio frame observer.

Return Values

  • 0: Success.
  • < 0: Failure.

setEarMonitoringAudioFrameParameters

Sets the format of the ear monitoring audio data.

public abstract int setEarMonitoringAudioFrameParameters(int sampleRate, int channel, int mode, int samplesPerCall);

This method sets the format of the ear monitoring audio data reported in the onEarMonitoringAudioFrame callback.

Note:
  • Before calling this method, you must call enableInEarMonitoring and set includeAudioFilters to EAR_MONITORING_FILTER_BUILT_IN_AUDIO_FILTERS or EAR_MONITORING_FILTER_NOISE_SUPPRESSION.
  • The SDK calculates the sampling interval based on the samplesPerCall, sampleRate, and channel parameters. Sampling interval (seconds) = samplesPerCall / (sampleRate × channel). Ensure the sampling interval is ≥ 0.01 seconds. The SDK triggers the onEarMonitoringAudioFrame callback based on the sampling interval.

Parameters

sampleRate
The sampling rate reported in the onEarMonitoringAudioFrame callback. Can be set to 8000, 16000, 32000, 44100, or 48000 Hz.
channel
The number of audio channels reported in the onEarMonitoringAudioFrame callback:
  • 1: Mono.
  • 2: Stereo.
mode
Usage mode of the audio frame:
  • RAW_AUDIO_FRAME_OP_MODE_READ_ONLY (0): (Default) Read-only mode. For example, the user retrieves data via the Agora SDK and pushes RTMP or RTMPS streams.
  • RAW_AUDIO_FRAME_OP_MODE_READ_WRITE (2): Read-write mode. The user reads data from AudioFrame, modifies it, and plays it back. For example, the user has a custom audio effects module and performs voice preprocessing such as voice changing.
samplesPerCall
The number of samples per call reported in the onEarMonitoringAudioFrame callback, e.g., 1024 for media streaming.

Return Values

  • 0: Success.
  • < 0: Failure.

setMixedAudioFrameParameters

Sets the format of the mixed raw audio data used for capture and playback.

public abstract int setMixedAudioFrameParameters(int sampleRate, int channel, int samplesPerCall);

The SDK calculates the sampling interval based on the samplesPerCall, sampleRate, and channel parameters. Sampling interval (seconds) = samplesPerCall / (sampleRate × channel). Ensure the sampling interval is ≥ 0.01 seconds. The SDK triggers the onMixedAudioFrame callback based on the sampling interval.

Timing

Call this method before joining a channel.

Parameters

sampleRate
The sampling rate returned in the callback. Can be set to 8000, 16000, 32000, 44100, or 48000 Hz.
channel
Number of audio channels. Can be set to:
  • 1: Mono.
  • 2: Stereo.
samplesPerCall
Number of samples per callback, e.g., 1024 for media streaming.

Return Values

  • 0: Success.
  • < 0: Failure.

setPlaybackAudioFrameBeforeMixingParameters [1/2]

Sets the format of raw audio playback data before audio mixing.

public abstract int setPlaybackAudioFrameBeforeMixingParameters(int sampleRate, int channel);

The SDK triggers the onPlaybackAudioFrameBeforeMixing callback based on the sampling interval.

Timing

Call this method before joining a channel.

Related Callbacks

Related callback: onPlaybackAudioFrameBeforeMixing.

Parameters

sampleRate
The sample rate returned in the callback. You can set it to:
  • 8000: 8 kHz.
  • 16000: 16 kHz.
  • 32000: 32 kHz.
  • 44100: 44.1 kHz.
  • 48000: 48 kHz.
channel
The number of audio channels. You can set it to:
  • 1: Mono.
  • 2: Stereo.

Return Values

  • 0: Success.
  • < 0: Failure.

setPlaybackAudioFrameBeforeMixingParameters [2/2]

Sets the format of audio data returned in the onPlaybackAudioFrameBeforeMixing callback.

public abstract int setPlaybackAudioFrameBeforeMixingParameters(int sampleRate, int channel, int samplesPerCall);

Parameters

sampleRate
Sets the sample rate returned in the onPlaybackAudioFrameBeforeMixing callback. You can set it to (unit: Hz):
  • 8000
  • 16000
  • 32000
  • 44100
  • 48000
channel
Sets the number of audio channels returned in the onPlaybackAudioFrameBeforeMixing callback. You can set it to:
  • 1: Mono.
  • 2: Stereo.
samplesPerCall
Sets the number of samples returned in the onMixedAudioFrame callback.
Note: In RTMP streaming scenarios, it is recommended to set this to 1024.

Return Values

  • 0: Success.
  • < 0: Failure.

setPlaybackAudioFrameParameters

Sets the format of raw audio playback data.

public abstract int setPlaybackAudioFrameParameters(int sampleRate, int channel, int mode, int samplesPerCall);

The SDK calculates the sampling interval based on the samplesPerCall, sampleRate, and channel parameters. Sampling interval (in seconds) = samplesPerCall / (sampleRate × channel). Ensure that the sampling interval is ≥ 0.01 seconds. The SDK triggers the onPlaybackAudioFrame callback based on the sampling interval.

Timing

Call this method before joining a channel.

Related Callbacks

This method triggers the onPlaybackAudioFrame callback based on the sampling interval.

Parameters

sampleRate
Sampling rate returned in the callback. Can be set to 8000, 16000, 24000, 32000, 44100, or 48000 Hz.
channel
Number of audio channels. Can be set to:
  • 1: Mono.
  • 2: Stereo.
mode
Usage mode of the audio frame:
  • RAW_AUDIO_FRAME_OP_MODE_READ_ONLY (0): (Default) Read-only mode. For example, the user obtains data through the Agora SDK and pushes RTMP or RTMPS streams.
  • RAW_AUDIO_FRAME_OP_MODE_READ_WRITE (2): Read-write mode. The user reads data from AudioFrame, modifies it, and then plays it. For example, the user has their own audio effect processing module and performs voice preprocessing, such as voice changing.
samplesPerCall
Number of data samples returned per call, e.g., 1024 for media streaming.

Return Values

  • 0: Success.
  • < 0: Failure.

setRecordingAudioFrameParameters

Sets the format of the captured raw audio data.

public abstract int setRecordingAudioFrameParameters(int sampleRate, int channel, int mode, int samplesPerCall);

The SDK calculates the sampling interval based on the samplesPerCall, sampleRate, and channel parameters. Sampling interval (in seconds) = samplesPerCall / (sampleRate × channel). Ensure the sampling interval is ≥ 0.01 seconds. The SDK triggers the onRecordAudioFrame callback based on the sampling interval.

Timing

Call this method before joining a channel.

Parameters

sampleRate
The sampling rate returned in the callback. Can be set to 8000, 16000, 32000, 44100, or 48000 Hz.
channel
Number of audio channels:
  • 1: Mono.
  • 2: Stereo.
mode
Usage mode of the audio frame:
  • 0: Read-only mode. For example, the user retrieves data via the Agora SDK and pushes RTMP or RTMPS streams.
  • 2: Read-write mode. The user reads data from AudioFrame, modifies it, and plays it back. For example, the user has a custom audio effects module and performs voice preprocessing such as voice changing.
samplesPerCall
Number of samples per call, e.g., 1024 for media streaming.

Return Values

  • 0: Success.
  • < 0: Failure.

onEarMonitoringAudioFrame

Callback for ear monitoring audio frames.

public abstract boolean onEarMonitoringAudioFrame(int type, int samplesPerChannel, int bytesPerSample, int channels, int samplesPerSec, ByteBuffer buffer, long renderTimeMs, int avsync_type);
This callback is used to retrieve ear monitoring audio data. To ensure the retrieved data meets expectations, Agora recommends setting the audio data format using one of the following methods:
Note: Method 1 takes precedence over Method 2. If you use Method 1 to set the audio data format, the settings in Method 2 will be ignored.

Parameters

type
Audio frame type.
samplesPerChannel
Number of samples per channel.
bytesPerSample
Number of bytes per audio sample. For example, each PCM audio sample typically occupies 16 bits (2 bytes).
channels
Number of channels:
  • 1: Mono.
  • 2: Stereo. If stereo, the data is in interleaved format.
samplesPerSec
Recording sample rate (Hz).
buffer
Audio buffer. Buffer size = samplesPerChannel × channels × bytesPerSample. See ByteBuffer.
renderTimeMs
Timestamp of the external audio frame (milliseconds). You can use this parameter to synchronize audio and video frames in scenarios such as using custom video sources.
avsync_type
Reserved parameter.

Return Values

  • true: Callback handled successfully.
  • false: Callback handling failed.

onMixedAudioFrame

Callback for retrieving the audio frame mixed from capture and playback.

public abstract boolean onMixedAudioFrame(String channelId, int type, int samplesPerChannel, int bytesPerSample, int channels, int samplesPerSec, ByteBuffer buffer, long renderTimeMs, int avsync_type);
Agora recommends setting the audio data format in one of the following two ways to ensure the format of the mixed audio frame from capture and playback meets expectations:
Note: The settings of setMixedAudioFrameParameters take precedence over getObservedAudioFramePosition. If you use Method 1 to set the audio data format, the settings in Method 2 will be ignored.

Parameters

channelId
Channel ID.
type
Audio frame type.
samplesPerChannel
Number of samples per channel.
bytesPerSample
Number of bytes per audio sample. For example, each PCM audio sample typically occupies 16 bits (2 bytes).
channels
Number of channels:
  • 1: Mono.
  • 2: Stereo. When using stereo, the data is in interleaved format.
samplesPerSec
Recording sample rate (Hz).
buffer
Audio buffer. Buffer size = samplesPerChannel × channels × bytesPerSample. See ByteBuffer.
renderTimeMs
Timestamp of the external audio frame (in milliseconds). You can use this parameter to synchronize audio and video frames in scenarios involving video or audio (including scenarios with external video sources).
avsync_type
Reserved parameter.

Return Values

  • true: Callback handled successfully.
  • false: Callback handling failed.

onPlaybackAudioFrame

Callback for retrieving the raw audio frame for playback.

public abstract boolean onPlaybackAudioFrame(String channelId, int type, int samplesPerChannel, int bytesPerSample, int channels, int samplesPerSec, ByteBuffer buffer, long renderTimeMs, int avsync_type);
You can set the audio data format in one of the following two ways:
Note: The settings of setPlaybackAudioFrameParameters take precedence over getObservedAudioFramePosition. If you use Method 1 to set the audio data format, the settings in Method 2 will be ignored.

Parameters

channelId
Channel ID.
type
Audio frame type.
samplesPerChannel
Number of samples per channel.
bytesPerSample
Number of bytes per audio sample. For example, each PCM audio sample typically occupies 16 bits (2 bytes).
channels
Number of channels:
  • 1: Mono.
  • 2: Stereo. For stereo, the data is interleaved.
samplesPerSec
Recording sample rate (Hz).
buffer
Audio buffer. Buffer size = samplesPerChannel × channels × bytesPerSample.
renderTimeMs
Timestamp of the external audio frame (in milliseconds). You can use this parameter to synchronize audio and video frames in scenarios involving video or audio (including scenarios with external video sources).
avsync_type
Reserved parameter.

Return Values

  • true: Callback handled successfully.
  • false: Callback handling failed.

onPlaybackAudioFrameBeforeMixing

Callback for retrieving audio frames of subscribed remote users before audio mixing.

public abstract boolean onPlaybackAudioFrameBeforeMixing(String channelId, int uid, int type, int samplesPerChannel, int bytesPerSample, int channels, int samplesPerSec, ByteBuffer buffer, long renderTimeMs, int avsync_type, int rtpTimestamp, long presentationMs);

Trigger Timing

This callback is triggered after retrieving the remote user's audio frame and before mixing.

Parameters

channelId
Channel ID.
uid
User ID of the subscribed remote user.
type
Audio frame type.
samplesPerChannel
Number of samples per channel.
bytesPerSample
Number of bytes per audio sample. For example, each PCM audio sample typically occupies 16 bits (2 bytes).
channels
Number of channels:
  • 1: Mono.
  • 2: Stereo. Stereo data is interleaved.
samplesPerSec
Recording sample rate (Hz).
buffer
Audio buffer. Buffer size = samplesPerChannel × channels × bytesPerSample.
renderTimeMs
Timestamp of the external audio frame (milliseconds). You can use this parameter to synchronize audio and video in scenarios such as using custom video sources.
avsync_type
Reserved parameter.
rtpTimestamp
RTP timestamp.
presentationMs
Presentation timestamp (milliseconds).

Return Values

  • true: Processing succeeded.
  • false: Processing failed.

onRecordAudioFrame

Callback for retrieving the captured audio frame.

public abstract boolean onRecordAudioFrame(String channelId, int type, int samplesPerChannel, int bytesPerSample, int channels, int samplesPerSec, ByteBuffer buffer, long renderTimeMs, int avsync_type);
You can set the audio data format using one of the following methods:
Note: The settings in setRecordingAudioFrameParameters take precedence over those in getObservedAudioFramePosition. If you set the audio data format using Method 1, the settings in Method 2 will be ignored.

Parameters

channelId
Channel ID.
type
Audio frame type.
samplesPerChannel
Number of samples per channel.
bytesPerSample
Number of bytes per audio sample. For example, each PCM audio sample typically takes 16 bits (2 bytes).
channels
Number of channels:
  • 1: Mono.
  • 2: Stereo. If stereo is used, the data is interleaved.
samplesPerSec
Recording sample rate (Hz).
buffer
Audio buffer. Buffer size = samplesPerChannel × channels × bytesPerSample.
renderTimeMs
Timestamp of the external audio frame (milliseconds). You can use this parameter to synchronize audio and video frames in scenarios such as using external video sources.
avsync_type
Reserved parameter.

Return Values

  • true: Callback handled successfully.
  • false: Callback handling failed.

Encoded Audio Data

registerAudioEncodedFrameObserver

Registers an observer for encoded audio data.

public abstract int registerAudioEncodedFrameObserver(AudioEncodedFrameObserverConfig config, IAudioEncodedFrameObserver observer);
Note: Call this method after joining a channel. You can use this method or startAudioRecording to configure the recording type and quality of the audio file, but using both is not recommended. Only the method called last takes effect.

Parameters

config
Configuration for the encoded audio observer. See AudioEncodedFrameObserverConfig.
observer
The observer for encoded audio data. See IAudioEncodedFrameObserver.

Return Values

  • 0: Success.
  • < 0: Failure.

onMixedAudioEncodedFrame

Callback for mixed encoded audio data of the local and all remote users.

public abstract void onMixedAudioEncodedFrame(ByteBuffer buffer, int samplesPerChannel, int channels, int samplesPerSec, int codecType);

After calling registerAudioEncodedFrameObserver and setting the audio configuration to AUDIO_ENCODED_FRAME_OBSERVER_POSITION_MIXED, you can use this callback to retrieve mixed encoded audio data.

Parameters

buffer
Audio buffer.
samplesPerChannel
Number of samples per channel.
channels
Number of channels:
  • 1: Mono.
  • 2: Stereo. If stereo, the data is interleaved.
samplesPerSec
Recording sample rate (Hz).
codecType
Audio codec type:
  • 1: OPUS.
  • 8: LC-AAC.
  • 9: HE-AAC.
  • 11: HE-AAC v2.

onPlaybackAudioEncodedFrame

Callback for retrieving encoded audio data of all remote users.

public abstract void onPlaybackAudioEncodedFrame(ByteBuffer buffer, int samplesPerChannel, int channels, int samplesPerSec, int codecType);

After calling registerAudioEncodedFrameObserver and setting the encoded audio to AUDIO_ENCODED_FRAME_OBSERVER_POSITION_PLAYBACK, you can use this callback to retrieve encoded audio data of all remote users.

Trigger Timing

This callback is triggered when encoded audio data of remote users is received.

Parameters

buffer
Audio buffer.
samplesPerChannel
Number of samples per channel.
channels
Number of channels:
  • 1: Mono.
  • 2: Stereo. If stereo, the data is interleaved.
samplesPerSec
Recording sample rate (Hz).
codecType
Audio codec type:
  • 1: OPUS.
  • 8: LC-AAC.
  • 9: HE-AAC.
  • 11: HE-AAC v2.

onRecordAudioEncodedFrame

Callback for encoded audio data of the local user.

public abstract void onRecordAudioEncodedFrame(ByteBuffer buffer, int samplesPerChannel, int channels, int samplesPerSec, int codecType);

After calling registerAudioEncodedFrameObserver and setting the encoded audio to AUDIO_ENCODED_FRAME_OBSERVER_POSITION_MIC, you can use this callback to retrieve the encoded audio data of the local user.

Parameters

buffer
Audio buffer.
samplesPerChannel
Number of samples per channel in the audio frame.
channels
Number of channels:
  • 1: Mono.
  • 2: Stereo. If stereo, the data is interleaved.
samplesPerSec
Recording sample rate (Hz).
codecType
Audio codec type:
  • 1: OPUS.
  • 8: LC-AAC.
  • 9: HE-AAC.
  • 11: HE-AAC v2.

Custom Audio Capture and Rendering

adjustCustomAudioPlayoutVolume

Adjusts the volume of the custom audio track for local playback.

public abstract int adjustCustomAudioPlayoutVolume(int trackId, int volume);

If you want to change the volume for local playback, you need to call this method again.

Note: Make sure to call createCustomAudioTrack to create a custom audio track before calling this method.

Parameters

trackId
Audio track ID. Set to the custom audio track ID returned by createCustomAudioTrack.
volume
Volume of the audio source, ranging from 0 to 100.
  • 0: Mute.
  • 100: Original volume.

Return Values

  • 0: Success.
  • < 0: Failure.

adjustCustomAudioPublishVolume

Adjusts the volume of the custom audio track for remote playback.

public abstract int adjustCustomAudioPublishVolume(int trackId, int volume);

If you want to change the volume for remote playback, you need to call this method again.

Note: Make sure to call createCustomAudioTrack to create a custom audio track before calling this method.

Parameters

trackId
Audio track ID. Set to the custom audio track ID returned by createCustomAudioTrack.
volume
Volume of the audio source, ranging from 0 to 100.
  • 0: Mute.
  • 100: Original volume.

Return Values

  • 0: Success.
  • < 0: Failure.

createCustomAudioTrack

Creates a custom audio track.

public abstract int createCustomAudioTrack(Constants.AudioTrackType trackType, AudioTrackConfig config)
You can publish a custom audio source by following these steps:
  1. Call this method to create a custom audio track and get the track ID.
  2. Call joinChannel to join a channel. In ChannelMediaOptions, set publishCustomAudioTrackId to the track ID obtained in step 1, and set publishCustomAudioTrack to true.
  3. Call pushExternalAudioFrame and set trackId to the track ID from step 2 to publish the corresponding custom audio source in the channel.
Note: You must call this method before joining a channel.

Parameters

trackType
The type of the custom audio track. See AudioTrackType.
Note: If this parameter is set to AUDIO_TRACK_DIRECT, you must set publishMicrophoneTrack in ChannelMediaOptions to false when joining the channel, otherwise the join will fail and return error code -2.
config
Configuration of the custom audio track. See AudioTrackConfig.

Return Values

  • If the method call succeeds, returns the audio track ID as the unique identifier for the track.
  • If the method call fails, returns 0xffffffff.

destroyCustomAudioTrack

Destroys the specified audio track.

public abstract int destroyCustomAudioTrack(int trackId);

Parameters

trackId
The custom audio track ID returned by createCustomAudioTrack.

Return Values

  • 0: Success.
  • < 0: Failure.

enableCustomAudioLocalPlayback

Enables or disables local playback of external audio sources.

public abstract int enableCustomAudioLocalPlayback(int trackId, boolean enabled);

You can call adjustCustomAudioPlayoutVolume to adjust the local playback volume of the custom audio track.

Note: Make sure to call createCustomAudioTrack to create a custom audio track before calling this method.

Parameters

trackId
Audio track ID, should be the custom audio track ID returned by createCustomAudioTrack.
enabled
Whether to play the external audio source:
  • true: Play the external audio source.
  • false: (Default) Do not play the external audio source.

Return Values

  • 0: Success.
  • < 0: Failure.

pullPlaybackAudioFrame [1/2]

Pulls mixed remote audio data for playback.

public abstract int pullPlaybackAudioFrame(byte[] data, int lengthInByte);

Before calling this method, call setExternalAudioSink and set enabled to true to enable external audio rendering.

Note: pullPlaybackAudioFrame and onPlaybackAudioFrame can both be used to obtain mixed remote audio data. After enabling external audio rendering (by calling setExternalAudioSink), you can no longer get data from onPlaybackAudioFrame. Choose pullPlaybackAudioFrame or onPlaybackAudioFrame based on your actual needs. Differences:
  • pullPlaybackAudioFrame: The app pulls audio data from the SDK. The SDK adjusts the frame buffer to help handle latency and avoid audio jitter.
  • onPlaybackAudioFrame: The SDK pushes audio data to the app via callback. If there is delay in processing, it may cause jitter.
This method is only for pulling mixed remote audio data. To get data from other stages like capture or playback, use registerAudioFrameObserver to register related callbacks.

Timing

You need to call this method after joining a channel.

Parameters

data
Output parameter. The remote audio data to pull.
lengthInByte
Data length in bytes. This depends on audio duration, and the sampleRate and channels set in setExternalAudioSink. Formula: lengthInByte = sampleRate / 1000 × 2 × channels × duration (ms).

Return Values

  • 0: Success.
  • < 0: Failure.

pullPlaybackAudioFrame [2/2]

Pulls remote audio data.

public abstract int pullPlaybackAudioFrame(ByteBuffer data, int lengthInByte);

Before calling this method, you need to call setExternalAudioSink and set enabled to true to enable and configure external audio playback. After calling this method successfully, the app pulls decoded and mixed audio data for playback.

Note:
  • This method must be called after joining a channel.
  • Differences from onPlaybackAudioFrame:
    • onPlaybackAudioFrame: The SDK pushes audio data to the app. Processing delay may cause jitter.
    • pullPlaybackAudioFrame: The app pulls remote audio data. The SDK adjusts the frame buffer to avoid jitter in external playback.

Parameters

data
Receives the pulled remote audio data. See ByteBuffer.
lengthInByte
Byte length of the remote audio data. This depends on audio duration, and the sampleRate and channels set in setExternalAudioSink. lengthInByte = sampleRate / 1000 × 2 × channels × duration (ms).

Return Values

  • 0: Success.
  • < 0: Failure.

pushExternalAudioFrame

Pushes external audio data to the app.

public abstract int pushExternalAudioFrame(byte[] data, long timestamp)
Deprecated
This method is deprecated. Use pushExternalAudioFrame(byte[] data, long timestamp, int sampleRate, int channels, Constants.BytesPerSample bytesPerSample, int trackId) instead.

Parameters

data
Audio data buffer.
timestamp
Timestamp of the audio data.

Return Values

  • 0: Success.
  • < 0: Failure.

setExternalAudioSink

Sets the external audio renderer.

public abstract int setExternalAudioSink(boolean enabled, int sampleRate, int channels);

After enabling the external audio renderer, you can call pullPlaybackAudioFrame to pull remote audio frames. The app can process the remote audio and apply desired effects for playback.

Note: After enabling the external audio renderer, the app cannot receive any audio data from the onPlaybackAudioFrame callback.

Scenario

Applicable to scenarios where external audio data is used for playback.

Timing

Call this method before joining a channel.

Parameters

enabled
Whether to enable the external audio renderer:
  • true: Enable.
  • false: (Default) Disable.
sampleRate
Sample rate (Hz) of the external audio renderer. Supported values:
  • 16000
  • 32000
  • 44100
  • 48000
channels
Number of channels of the external audio renderer:
  • 1: Mono.
  • 2: Stereo.

Return Values

  • 0: Success.
  • < 0: Failure.

setExternalAudioSource [1/2]

Sets the external audio source.

public abstract int setExternalAudioSource(boolean enabled, int sampleRate, int channels);
Deprecated
This method is deprecated. Use createCustomAudioTrack instead.

Call this method before joinChannel and startPreview.

Parameters

enabled
Whether to enable the external audio source:
  • true: Enable.
  • false: (Default) Disable.
sampleRate
Sample rate (Hz) of the external audio source. Supported values:
  • 8000
  • 16000
  • 32000
  • 44100
  • 48000.
channels
Number of channels of the external audio source:
  • 1: Mono.
  • 2: Stereo.

Return Values

  • 0: Success.
  • < 0: Failure.

setExternalAudioSource [2/2]

Sets external audio source parameters.

public abstract int setExternalAudioSource(boolean enabled, int sampleRate, int channels, boolean localPlayback, boolean publish);
Deprecated
This method is deprecated. Use createCustomAudioTrack instead.

Timing

Call this method before joining a channel.

Parameters

enabled
Whether to enable the external audio source:
  • true: Enable external audio source.
  • false: (Default) Do not enable external audio source.
sampleRate
Sample rate (Hz) of the external audio source. Available values:
  • 8000
  • 16000
  • 32000
  • 44100
  • 48000.
channels
Number of channels in the external audio source. Available values:
  • 1: Mono.
  • 2: Stereo.
localPlayback
Whether to play the external audio source locally:
  • true: Play external audio source.
  • false: (Default) Do not play external audio source.
publish
Whether to publish the audio to remote users:
  • true: (Default) Publish audio to remote users.
  • false: Do not publish audio to remote users.

Return Values

  • 0: Success.
  • < 0: Failure.

Audio Spectrum

disableAudioSpectrumMonitor

Disables audio spectrum monitoring.

public abstract int disableAudioSpectrumMonitor();

After calling enableAudioSpectrumMonitor, you can call this method to disable audio spectrum monitoring.

Note: You can call this method before or after joining a channel.

Return Values

  • 0: Success.
  • < 0: Failure.

enableAudioSpectrumMonitor

Enables the audio spectrum monitoring feature.

public abstract int enableAudioSpectrumMonitor(int intervalInMS);

You can register an audio spectrum observer and call this method to obtain audio spectrum data of local or remote users.

Scenario

You can call this method before or after joining a channel.

Related Callbacks

onLocalAudioSpectrum and onRemoteAudioSpectrum callbacks.

Parameters

intervalInMS
The time interval in milliseconds at which the SDK triggers the onLocalAudioSpectrum and onRemoteAudioSpectrum callbacks. This parameter must not be less than 10; otherwise, the method call fails. (Default: 100)

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter.

registerAudioSpectrumObserver

Registers an audio spectrum observer.

public abstract int registerAudioSpectrumObserver(IAudioSpectrumObserver observer);

After successfully registering the audio spectrum observer and calling enableAudioSpectrumMonitor to enable audio spectrum monitoring, the SDK triggers the callbacks you implement in IAudioSpectrumObserver based on the configured interval.

Note: You can call this method before or after joining a channel.

Parameters

observer
The audio spectrum observer. See IAudioSpectrumObserver.

Return Values

  • 0: Success.
  • < 0: Failure.

unRegisterAudioSpectrumObserver

Unregisters the audio spectrum observer.

public abstract int unRegisterAudioSpectrumObserver(IAudioSpectrumObserver observer);

After calling registerAudioSpectrumObserver, you can call this method if you want to disable audio spectrum monitoring.

Note: You can call this method before or after joining a channel.

Parameters

observer
The audio spectrum observer. See IAudioSpectrumObserver.

Return Values

  • 0: Success.
  • < 0: Failure.

onLocalAudioSpectrum

Callback for local audio spectrum data.

@CalledByNative boolean onLocalAudioSpectrum(AudioSpectrumInfo data);

After successfully calling registerAudioSpectrumObserver to implement the onLocalAudioSpectrum callback and calling enableAudioSpectrumMonitor to enable audio spectrum monitoring, the SDK triggers this callback before encoding at the interval you set to report the local user's audio spectrum data.

Trigger Timing

This callback is triggered by the SDK before encoding at the interval you set, after enabling audio spectrum monitoring and setting the interval.

Parameters

data
Audio spectrum data of the local user. See AudioSpectrumInfo.

Return Values

Whether spectrum data is received:
  • true: Spectrum data is received.
  • false: Spectrum data is not received.

onRemoteAudioSpectrum

Callback for remote audio spectrum data.

boolean onRemoteAudioSpectrum(UserAudioSpectrumInfo[] userAudioSpectrumInfos, int spectrumNumber);

After successfully calling registerAudioSpectrumObserver and enableAudioSpectrumMonitor to enable audio spectrum monitoring, the SDK triggers this callback at the interval you set.

Trigger Timing

This callback is triggered at the interval you set after successfully calling registerAudioSpectrumObserver and enabling audio spectrum monitoring.

Parameters

userAudioSpectrumInfos
Audio spectrum information of remote users. The array length equals the number of remote users detected by the SDK. If this array is null, it means no remote user audio spectrum is detected. See UserAudioSpectrumInfo.
spectrumNumber
The number of remote users.

Return Values

  • true: Spectrum data is received.
  • false: Spectrum data is not received.