LocalSpatialAudioEngine
This class calculates user coordinates through the SDK to implement spatial audio.
This class inherits from BaseSpatialAudioEngine. Before calling other APIs under this class, you need to call the initialize method to initialize it.
clearRemotePositions
Deletes the spatial position information of all remote users.
Future<void> clearRemotePositions();
After this method is successfully called, the local user will no longer hear any remote users. After leaving the channel, you can also call this method to delete all remote users' spatial position information to avoid wasting computing resources.
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.
initialize
Initializes the LocalSpatialAudioEngine.
Future<void> initialize();
- You must call this method to initialize the LocalSpatialAudioEngine before calling other methods of the LocalSpatialAudioEngine class.
- The SDK supports only one LocalSpatialAudioEngine instance per app.
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.
removeRemotePosition
Deletes the spatial position information of the specified remote user.
Future<void> removeRemotePosition(int uid);
After this method is successfully called, the local user will no longer hear the specified remote user. After leaving the channel, to avoid wasting computing resources, you need to call this method to delete the spatial position information of the specified remote user. Otherwise, the user's spatial position information will continue to be stored. When the number of remote users exceeds the number of audio streams set in setMaxAudioRecvCount, the SDK will automatically unsubscribe from the audio streams of the farthest users based on relative distance.
Parameters
- uid
- User ID. Must match the user ID used when joining the channel.
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.
setRemoteAudioAttenuation
Sets the sound attenuation effect for a specified user.
Future<void> setRemoteAudioAttenuation(
{required int uid, required double attenuation, required bool forceSet});
Parameters
- uid
- User ID. Must match the user ID used when joining the channel.
- attenuation
- The sound attenuation coefficient for the specified user, ranging from [0,1].
- forceSet
- Whether to forcibly apply the sound attenuation effect for the user:
- true: Forces the use of
attenuationto set the user's sound attenuation effect. In this case, theaudioAttenuationvalue set in SpatialAudioZone has no effect on this user. - false: Does not forcibly apply
attenuationto the user. 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
audioAttenuationin 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
attenuationparameter in this method.
- If the audio source and listener are in and out of the sound insulation zone respectively, the attenuation effect is determined by
- true: Forces the use of
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.
updateRemotePosition
Updates the spatial position information of a remote user.
Future<void> updateRemotePosition(
{required int uid, required RemoteVoicePositionInfo posInfo});
After successfully calling this method, the SDK calculates spatial audio parameters based on the relative position of the local and remote users.
Parameters
- uid
- The user ID. It must be the same as the user ID used when the user joins the channel.
- posInfo
- The spatial position information of the remote user. See RemoteVoicePositionInfo.
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.