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.

create

Creates an ILocalSpatialAudioEngine instance.

public static synchronized ILocalSpatialAudioEngine create()

Call this method before calling initialize.

Return Values

The ILocalSpatialAudioEngine object, if the method call succeeds.

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.

initialize

Initializes the ILocalSpatialAudioEngine.

public abstract int initialize(LocalSpatialAudioConfig config);

Note:

Call this method after calling the create method.
You must call initialize to initialize ILocalSpatialAudioEngine before using any other method of ILocalSpatialAudioEngine.
Each app supports only one ILocalSpatialAudioEngine instance.

Parameters

config: Configuration for ILocalSpatialAudioEngine. See LocalSpatialAudioConfig.

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.

destroy

Destroys the ILocalSpatialAudioEngine instance.

public static synchronized void destroy()

After calling this method, you can no longer use any API under ILocalSpatialAudioEngine. To use spatial audio features again, wait until the destroy method completes, then call initialize to create a new ILocalSpatialAudioEngine instance.

Note: Call this method before calling the destroy method.

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.