Spatial Audio

clearRemotePositions

Removes the spatial positions of all remote users.

virtual int clearRemotePositions() = 0;

After successfully calling this method, you will no longer hear any remote users. You can also call this method after leaving the channel to remove all remote user spatial positions and avoid resource waste.

Return Values

0: Success.
< 0: Failure.

enableSpatialAudio

Enables or disables spatial audio.

virtual int enableSpatialAudio(bool enabled) = 0;

After enabling spatial audio, you can call setRemoteUserSpatialAudioParams to set spatial audio parameters for remote users.

Note:

You can call this method either before or after joining a channel.
This method depends on the spatial audio dynamic library libagora_spatial_audio_extension.dll. If the library is deleted, this 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 ILocalSpatialAudioEngine.

virtual int initialize(const LocalSpatialAudioConfig& config) = 0;

Before calling other methods of ILocalSpatialAudioEngine, you must first call queryInterface to get the interface instance and initialize ILocalSpatialAudioEngine through this method. Each app supports creating only one ILocalSpatialAudioEngine instance.

Parameters

config: The configuration of ILocalSpatialAudioEngine. See LocalSpatialAudioConfig.

Return Values

0: The method call succeeds.
< 0: The method call fails.

muteAllRemoteAudioStreams

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

virtual int muteAllRemoteAudioStreams(bool mute) = 0;

After calling this method, the local user stops or resumes 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 IRtcEngine.
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.

virtual int muteLocalAudioStream(bool mute) = 0;

Note: This method does not affect any ongoing audio recording, as it does not disable the audio capturing device. You should call this method after calling the joinChannel method. When using spatial audio, if you need to control whether to stop publishing the local audio stream, it is recommended to call this method instead of the method with the same name under IRtcEngine.

Related Callbacks

After this method is successfully called, the remote side triggers the onUserMuteAudio and onRemoteAudioStateChanged callbacks.

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.

virtual int muteRemoteAudioStream(uid_t uid, bool mute) = 0;

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

User ID. This value must be the same as the user ID passed in when the user joined the channel.

mute

Whether to subscribe to the specified remote user's audio stream:

true: Stop subscribing to this user's audio stream.
false: (Default) Subscribe to this user's audio stream. The SDK determines whether to subscribe based on the distance between the local and remote users.

Return Values

0: Success.
< 0: Failure.

release

Releases all resources of ILocalSpatialAudioEngine.

virtual void release() = 0;

Call this method to release all resources under ILocalSpatialAudioEngine. After calling this method, you can no longer use any APIs under ILocalSpatialAudioEngine.

Note: Call this method before calling the release method.

removeRemotePosition

Removes the spatial position information of the specified remote user.

virtual int removeRemotePosition(uid_t uid) = 0;

After calling this method, the local user will no longer hear the specified remote user. After leaving the channel, to avoid wasting computing resources, it is recommended to call this method to remove the spatial position information of the remote user; otherwise, the information will be retained. When the number of remote users exceeds the maximum 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 value must be the same as the user ID passed in when the user joined the channel.

Return Values

0: The method call succeeds.
< 0: The method call fails.

setAudioRecvRange

Sets the local user's audio reception range.

virtual int setAudioRecvRange(float range) = 0;

After setting successfully, the local user can only hear remote users who are within the specified range or in the same team. You can call this method at any time to update the audio reception range.

Parameters

range: The maximum audio reception range in meters. This parameter must be greater than 0. The 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.

virtual int setDistanceUnit(float unit) = 0;

In Agora's spatial audio algorithm, distance is measured in meters, while the unit of distance in the game engine is customizable. By default, the SDK converts each unit of distance in the game engine to 1 meter. You can call the setDistanceUnit method to convert the 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. The default value is 1.00. For example, setting unit to 2.00 means each unit of distance in the game engine equals 2 meters. The larger the value, the faster the sound fades as the 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.

virtual int setHeadphoneEQParameters(int lowGain, int highGain) = 0;

In spatial audio scenarios, if calling setHeadphoneEQPreset does not achieve the desired headphone equalizer effect, you can further adjust it by calling this method.

Parameters

lowGain: Low frequency parameter of the headphone equalizer. The range is [-10, 10]. The larger the value, the fuller the sound.
highGain: High frequency parameter of the headphone equalizer. The range is [-10, 10]. The larger the value, the clearer the sound.

Return Values

0: Success.
< 0: Failure.
- -1: A general error occurred (no specific reason).

setHeadphoneEQPreset

Sets the preset headphone equalizer effect.

virtual int setHeadphoneEQPreset(HEADPHONE_EQUALIZER_PRESET preset) = 0;

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

Note: If your headphones already have a good equalizer, calling this method may not significantly improve the experience and could even degrade it.

Parameters

preset: Preset headphone equalizer effect. See HEADPHONE_EQUALIZER_PRESET.

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.

virtual int setMaxAudioRecvCount(int maxCount) = 0;

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

Parameters

maxCount: The maximum number of audio streams you can receive within the specified audio reception range. This value must be less than or equal to 16. The default is 10.

Return Values

0: Success.
< 0: Failure.

setPlayerAttenuation

Sets the audio attenuation properties for the media player.

virtual int setPlayerAttenuation(int playerId, double attenuation, bool forceSet) = 0;

Parameters

playerId

ID of the media player. You can get the device ID by calling getMediaPlayerId.

attenuation

Audio attenuation coefficient for the remote user or media player, value range: [0, 1]. Value descriptions:

0: Broadcast mode. Volume and timbre do not attenuate with distance. The local user hears consistent volume and timbre regardless of distance.
(0, 0.5): Weak attenuation mode. Volume and timbre attenuate slightly during propagation. Sound travels farther than in real environments.
0.5: (Default) Simulates real-world audio attenuation. Equivalent to not setting the speaker_attenuation parameter.
(0.5, 1]: Strong attenuation mode. Volume and timbre attenuate rapidly during propagation.

forceSet

Whether to forcibly apply the audio attenuation effect for the media player:

true: Force the use of attenuation to set the media player's attenuation. The audioAttenuation setting in SpatialAudioZone will not apply to the media player.
false: Do not forcibly use attenuation to set the media player's audio attenuation. Details are as follows:
- If the sound source and listener are inside and outside the zone respectively, attenuation is determined by the audioAttenuation in SpatialAudioZone.
- If the sound source and listener are in the same zone or both outside, attenuation is determined by the attenuation in this method.

Return Values

0: Success.
< 0: Failure.

setRemoteAudioAttenuation

Sets the audio attenuation effect for a specified user.

virtual int setRemoteAudioAttenuation(uid_t uid, double attenuation, bool forceSet) = 0;

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, value range: [0,1]. The meanings of the values are as follows:

0: Broadcast mode. Volume and timbre do not attenuate with distance. The local user hears consistent volume and timbre regardless of distance.
(0, 0.5): Weak attenuation mode. Volume and timbre attenuate slightly during propagation. Sound travels farther than in real environments.
0.5: (Default) Simulates real-world audio attenuation. Equivalent to not setting the speaker_attenuation parameter.
(0.5, 1]: Strong attenuation mode. Volume and timbre attenuate rapidly during propagation.

forceSet

Whether to forcibly apply the audio attenuation effect for the user:

true: Force the use of attenuation to set the user's audio attenuation. The audioAttenuation setting in SpatialAudioZone will not apply to this user.
false: Do not forcibly use attenuation to set the user's audio attenuation. Details are as follows:
- If the sound source and receiver are inside and outside the zone respectively, the attenuation is determined by the audioAttenuation in SpatialAudioZone.
- If the sound source and receiver are in the same zone or both outside, the attenuation is determined by the attenuation in this method.

Return Values

0: Success.
< 0: Failure.

setRemoteUserSpatialAudioParams

Sets spatial audio parameters for remote users.

virtual int setRemoteUserSpatialAudioParams(uid_t uid, const agora::SpatialAudioParams& params) = 0;

Call this method after calling enableSpatialAudio. After setting successfully, you can hear remote users with spatial effects.

Parameters

uid: Remote user ID. This parameter must be the same as the user ID passed when you join the channel.
params: Spatial audio parameters. See SpatialAudioParams.

Return Values

0: Success.
< 0: Failure.

setSpatialAudioParams

Enables or disables spatial audio for the media player.

virtual int setSpatialAudioParams(const SpatialAudioParams& params) = 0;

After successfully calling this method to set the spatial audio parameters of the media player, the SDK enables spatial audio for the media player, allowing the local user to hear spatialized media resources. To disable spatial audio, set params to NULL.

Parameters

params: The spatial audio parameters of the media player. See SpatialAudioParams.

Return Values

0: Success.
< 0: Failure.

setZones

Sets sound insulation zones.

virtual int setZones(const SpatialAudioZone *zones, unsigned int zoneCount) = 0;

In virtual interactive scenarios, you can use this method to set sound insulation zones and their audio attenuation coefficients. When the sound source (user or media player) and receiver are inside and outside the zone respectively, it simulates real-world sound attenuation caused by buildings:

When the sound source and receiver are inside and outside the zone respectively, attenuation is determined by the coefficient in SpatialAudioZone.
When the user or media player is inside the same zone, it is not affected by SpatialAudioZone. Attenuation is determined by the attenuation parameter in setPlayerAttenuation or setRemoteAudioAttenuation. If neither method is called, the SDK uses a default attenuation coefficient of 0.5.
When the sound source and receiver are in two different zones, the receiver cannot hear the sound source.

Note: If this method is called multiple times, the last set of zones takes effect.

Parameters

zones: Sound insulation zone settings. Set to NULL to clear all zones. See SpatialAudioZone for details.
Note: On Windows, make sure the number of elements in the zones array equals the value of zoneCount, otherwise it may cause a crash.
zoneCount: Number of sound insulation zones.

Return Values

0: Success.
< 0: Failure.

updatePlayerPositionInfo

Updates the spatial position of the media player.

virtual int updatePlayerPositionInfo(int playerId, const RemoteVoicePositionInfo& positionInfo) = 0;

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

Timing

You can call this method 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 information of the media player. See RemoteVoicePositionInfo.

Return Values

0: Success.
< 0: Failure.

updateRemotePosition

Updates the spatial position of the specified remote user.

virtual int updateRemotePosition(uid_t uid, const RemoteVoicePositionInfo &posInfo) = 0;

Timing

Call this method after calling the joinChannel method.

Parameters

uid: User ID. This value must be the same as the user ID passed in when the user joined the channel.
posInfo: The spatial position of the remote user. See RemoteVoicePositionInfo.

Return Values

0: The method call succeeds.
< 0: The method call fails.

updateSelfPosition

Updates the local user's spatial position.

virtual int updateSelfPosition(const float position[3], const float axisForward[3], const float axisRight[3], const float axisUp[3]) = 0;

This method belongs to the ILocalSpatialAudioEngine class and needs to be used together with updateRemotePosition. The SDK calculates the relative position between the local user and the remote user based on the parameters of this method and updateRemotePosition, and generates spatial audio parameters accordingly.

Parameters

position: 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 along the x-axis of the coordinate system. This parameter is an array of length 3, representing the forward, right, and up coordinates respectively.
axisRight: Unit vector along the y-axis of the coordinate system. This parameter is an array of length 3, representing the forward, right, and up coordinates respectively.
axisUp: Unit vector along the z-axis of 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.