IBaseSpatialAudioEngine

MuteAllRemoteAudioStreams

Unsubscribes from or resumes all remote users' audio streams.

public abstract int MuteAllRemoteAudioStreams(bool mute);

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

Note:

This method must be called after JoinChannel [2/2].
When using spatial audio, if you need to control whether to subscribe to all remote users' audio streams, it is recommended to call this method instead of IRtcEngine's MuteAllRemoteAudioStreams method.
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 unsubscribe from all remote users' audio streams:

true: Unsubscribe from all remote users' audio streams.
false: Subscribe to all remote users' audio streams.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

MuteLocalAudioStream

Stops or resumes publishing the local audio stream.

public abstract int MuteLocalAudioStream(bool mute);

Note:

This method does not affect the audio capturing state, as it does not disable the audio capture device.
You must call this method after JoinChannel [1/2] or JoinChannel [2/2].
When using spatial audio, to control whether to publish the local audio stream, it is recommended to call this method instead of IRtcEngine's MuteLocalAudioStream method.
After this method is successfully called, the remote user will receive 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. See Error Codes for details and troubleshooting.

MuteRemoteAudioStream

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

public abstract int MuteRemoteAudioStream(uint uid, bool mute);

Parameters

uid

User ID. Must be the same as the ID used when the user joined the channel.

mute

Whether to stop subscribing to the audio stream of the specified remote user.

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

0: Success.
< 0: Failure. See Error Codes for details and troubleshooting.

SetAudioRecvRange

Sets the audio reception range of the local user.

public abstract int SetAudioRecvRange(float range);

After this method is successfully called, the user can only hear remote users 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 range for receiving audio, in the distance unit of the game engine. The value must be greater than 0. The default value is 20.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and troubleshooting.

SetDistanceUnit

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

public abstract int SetDistanceUnit(float unit);

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

Parameters

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

Return Values

0: Success.
< 0: Failure. 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.

public abstract int 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 that are closest in distance.

Parameters

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

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

SetPlayerAttenuation

Sets the sound attenuation property of the media player.

public abstract int SetPlayerAttenuation(int playerId, double attenuation, bool forceSet);

Parameters

playerId

Media player ID.

attenuation

Sound attenuation coefficient of the media player, value range [0,1].

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, allowing sound to travel farther than in a real environment.
0.5: (Default) Simulates volume attenuation in a real environment. Equivalent to not setting the attenuation parameter.
(0.5,1]: Strong attenuation mode. Volume and tone attenuate rapidly during transmission.

forceSet

Whether to forcefully apply the sound attenuation effect for the media player:

true: Forcefully use attenuation to set the media player's sound attenuation effect. In this case, the audioAttenuation coefficient set in SpatialAudioZone does not apply to the media player.
false: Do not forcefully use attenuation to set the media player's sound attenuation effect. There are two cases:
- If the sound source and listener are inside and outside the isolation zone respectively, the sound attenuation effect is determined by the audioAttenuation in SpatialAudioZone.
- If the sound source and listener are both inside the same isolation zone or both outside, the sound attenuation effect is determined by the attenuation in this method.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

SetZones

Sets sound insulation zones.

public abstract int SetZones(SpatialAudioZone[] zones, uint zoneCount);

In a virtual interactive scenario, 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 listener are inside and outside the insulation zone respectively, a sound attenuation effect similar to that in a real environment with building partitions is experienced.

When the sound source and the listener are inside and outside the insulation zone respectively, the attenuation effect is determined by the attenuation coefficient in SpatialAudioZone.
If the user or media player are in the same insulation zone, SpatialAudioZone has no effect. The attenuation effect 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, simulating real-world sound attenuation.
If the sound source and the receiver belong to two different insulation zones, the receiver cannot hear the sound 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, make sure the number of members in the zones array matches the value of zoneCount, otherwise a crash may occur.
zoneCount: Number of sound insulation zones.

Return Values

0: Method call succeeds.
< 0: Method call fails. See Error Codes for details and resolution suggestions.

UpdatePlayerPositionInfo

Updates the spatial position of the media player.

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

After a successful update, the local user can hear the change in the spatial position 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

0: Method call succeeds.
< 0: Method call fails. See Error Codes for details and resolution suggestions.

UpdateSelfPosition

Updates the spatial position of the local user.

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

Under the ILocalSpatialAudioEngine class, this method must 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. Forward, right, and up correspond to the positive directions of Unity's Vector3 z, x, and y axes.
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. Forward, right, and up correspond to the positive directions of Unity's Vector3 z, x, and y axes.
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.
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.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and troubleshooting.