BaseSpatialAudioEngine

muteAllRemoteAudioStreams

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

Future<void> muteAllRemoteAudioStreams(bool mute);

After successfully calling this method, the local user will stop or resume subscribing to all remote users' audio streams, including those who join the channel after the method is called.

Note:

You must call this method after joinChannel.
When using spatial audio, to set whether to subscribe to all remote users' audio streams, it is recommended to call this method instead of the muteAllRemoteAudioStreams method of 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 in 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

When the method call succeeds, there is no return value; when it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

muteLocalAudioStream

Stops or resumes publishing the local audio stream.

Future<void> muteLocalAudioStream(bool mute);

Note:

This method does not affect the audio capture state, as it does not disable the audio capturing device.
You must call this method after joinChannel1 or joinChannel.
When using spatial audio, to set whether to publish the local audio stream, it is recommended to call this method instead of the muteLocalAudioStream method of RtcEngine.
After successfully calling this method, the remote side will trigger 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

When the method call succeeds, there is no return value; when it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

muteRemoteAudioStream

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

Future<void> muteRemoteAudioStream({required int uid, required bool mute});

Parameters

uid

The user ID. It must be the same as the user ID used when the user joins the channel.

mute

Whether to stop subscribing 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 determines whether to subscribe based on the distance between the local and remote users.

Return Values

When the method call succeeds, there is no return value; when it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

release

Destroys the BaseSpatialAudioEngine.

abstract release(): void;

This method releases all resources under BaseSpatialAudioEngine. When you no longer need to use spatial audio, you can call this method to release resources for other operations. After calling this method, you will no longer be able to use any API under BaseSpatialAudioEngine.

setAudioRecvRange

Sets the audio receive range for the local user.

Future<void> setAudioRecvRange(double range);

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

Parameters

range: Maximum range for receiving audio, in the distance unit used by the game engine. The value must be greater than 0. The default is 20.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setDistanceUnit

Sets the length (in meters) of one unit of distance in the game engine.

Future<void> setDistanceUnit(double unit);

The distance unit in the game engine is defined by the game engine itself, while the distance unit of the Agora spatial audio algorithm is in meters. By default, the SDK converts each unit of game engine distance to one meter. You can call this method to convert one unit of game engine distance to a specified number of meters.

Parameters

unit: The number of meters corresponding to one unit of game engine distance. The value must be greater than 0.00. The default is 1.00. For example, setting unit to 2.00 means one unit of game engine distance equals 2 meters. The larger the value, the faster the sound attenuation when the remote user moves away from the local user.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setMaxAudioRecvCount

Sets the maximum number of audio streams that can be received within the audio reception range.

Future<void> setMaxAudioRecvCount(int maxCount);

If the number of audio streams that can be received within the audio reception range exceeds the set value, the local user will receive the maxCount audio streams from the closest audio sources.

Parameters

maxCount: The maximum number of audio streams that can be received within the audio reception range. The value must be ≤ 16. The default value is 10.

Return Values

When the method call succeeds, there is no return value; when it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setPlayerAttenuation

Sets the sound attenuation properties of the media player.

Future<void> setPlayerAttenuation(
      {required int playerId,
      required double attenuation,
      required bool forceSet});

Parameters

playerId

Media player ID.

attenuation

The sound attenuation coefficient of the media player, ranging from [0,1].

0: Broadcast mode, where volume and timbre do not attenuate with distance. The local user hears no change in volume or timbre regardless of distance.
(0,0.5): Weak attenuation mode, where volume and timbre attenuate slightly during propagation. Compared to the real world, sound can travel farther.
0.5: (Default) Simulates attenuation in a real environment. Equivalent to not setting the attenuation parameter.
(0.5,1]: Strong attenuation mode, where volume and timbre attenuate rapidly during propagation.

forceSet

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

true: Forces the use of attenuation to set the media player's sound attenuation effect. In this case, the audioAttenuation value set in SpatialAudioZone has no effect on the media player.
false: Does not forcibly apply attenuation to the media player. Behavior depends on the following:
- If the audio source and listener are in and out of the sound insulation zone respectively, the attenuation effect is determined by audioAttenuation in SpatialAudioZone.
- If the audio source and listener are both inside or both outside the same sound insulation zone, the attenuation effect is determined by the attenuation parameter in this method.

Return Values

When the method call succeeds, there is no return value; when it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setZones

Sets sound insulation zones.

Future<void> setZones(
      {required SpatialAudioZone zones, required int zoneCount});

In virtual interactive scenarios, you can use this method to set sound insulation zones and sound attenuation coefficients. When the audio source (which can be a user or media player) and the listener are in and out of the sound insulation zone respectively, the user experiences attenuation similar to how sound is blocked by structures in the real world.

When the audio source and listener are in and out of the sound insulation zone respectively, the attenuation effect is determined by the sound attenuation coefficient in SpatialAudioZone.
If the user or media player is within the same sound insulation zone, the attenuation effect is not affected by SpatialAudioZone and is instead determined by the attenuation parameter in setPlayerAttenuation or setRemoteAudioAttenuation. If neither method is called, the SDK defaults to an attenuation coefficient of 0.5, simulating real-world sound attenuation.
If the audio source and receiver are in different sound insulation zones, the receiver cannot hear the audio source.

Note: If this method is called multiple times, the most recent configuration of sound insulation zones takes effect.

Parameters

zones: Configuration of sound insulation zones. See SpatialAudioZone. Setting this parameter to NULL clears all sound insulation zones.
Note: On the Windows platform, ensure that the number of elements in the zones array matches the value of zoneCount, otherwise a crash may occur.
zoneCount: The number of sound insulation zones.

Return Values

When the method call succeeds, there is no return value; when it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

updatePlayerPositionInfo

Updates the spatial position of the media player.

Future<void> updatePlayerPositionInfo(
      {required int playerId, required RemoteVoicePositionInfo positionInfo});

After a successful update, the local user can hear the spatial position changes of the media player.

Timing

Can be called before or after joining a channel.

Parameters

playerId: Media player ID.
positionInfo: Spatial position information of the media player. See RemoteVoicePositionInfo.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

updateSelfPosition

Updates the local user's spatial position.

Future<void> updateSelfPosition(
      {required List<double> position,
      required List<double> axisForward,
      required List<double> axisRight,
      required List<double> axisUp});

Under the LocalSpatialAudioEngine class, this method needs to be used together with updateRemotePosition. The SDK calculates the relative position between the local and remote users based on the parameters set by this method and updateRemotePosition, and then calculates the spatial audio parameters.

Parameters

position: Coordinates in the world coordinate system. This parameter is an array of length 3, representing the coordinates in the forward, right, and up directions respectively.
axisForward: Unit vector of the forward axis in the world coordinate system. This parameter is an array of length 3, representing the coordinates in the forward, right, and up directions respectively.
axisRight: Unit vector of the right axis in the world coordinate system. This parameter is an array of length 3, representing the coordinates in the forward, right, and up directions respectively.
axisUp: Unit vector of the up axis in the world coordinate system. This parameter is an array of length 3, representing the coordinates in the forward, right, and up directions respectively.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.