IBaseSpatialAudioEngine

This class contains some of the APIs in the ILocalSpatialAudioEngine class.

The ILocalSpatialAudioEngine class inherits from IBaseSpatialAudioEngine.

muteAllRemoteAudioStreams

Stops or resumes subscribing to the audio streams of all remote users.

public abstract int muteAllRemoteAudioStreams(boolean mute);

After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users.

Note:
  • Call this method after joinChannel [2/2].
  • When using the spatial audio effect, if you need to set whether to stop subscribing to the audio streams of all remote users, Agora recommends calling this method instead of the muteAllRemoteAudioStreams method under RtcEngine.
  • After calling this method, you need to call updateSelfPosition and updateRemotePosition to update the spatial location of the local user and the remote user; otherwise, the settings in this method do not take effect.

Parameters

mute
Whether to stop subscribing to the audio streams of all remote users:
  • true: Stops subscribing to the audio streams of all remote users.
  • false: Subscribe to the audio streams of all remote users.

Returns

  • 0: Success.
  • < 0: Failure.

muteLocalAudioStream

Stops or resumes publishing the local audio stream.

public abstract int muteLocalAudioStream(boolean mute);
Note:
  • This method does not affect any ongoing audio recording, because it does not disable the audio capture device.
  • Call this method after joinChannel [2/2].
  • When using the spatial audio effect, if you need to set whether to publish the local audio stream, Agora recommends calling this method instead of the muteLocalAudioStream method under RtcEngine.

Parameters

mute
Whether to stop publishing the local audio stream.
  • true: Stop publishing the local audio stream.
  • false: Publish the local audio stream.

Returns

  • 0: Success.
  • < 0: Failure.

setAudioRecvRange

Sets the audio reception range of the local user.

public abstract int setAudioRecvRange(float range);

After the setting is successful, the local user can only hear the remote users within the setting range or belonging to the same team. You can call this method at any time to update the audio reception range.

Parameters

range
The maximum audio reception range. The unit is meters. The value must be greater than 0.

Returns

  • 0: Success.
  • < 0: Failure.

setDistanceUnit

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

public abstract int setDistanceUnit(float unit);

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

Parameters

unit
The number of meters that the game engine distance per unit is equal to. This parameter must be greater than 0.00. For example, setting unit as 2.00 means the game engine distance per unit equals 2 meters.

The larger the value is, the faster the sound heard by the local user attenuates when the remote user moves far away from the local user.

Returns

  • 0: Success.
  • < 0: Failure.

setMaxAudioRecvCount

Sets the maximum number of streams that a user can receive in a specified audio reception range.

public abstract int setMaxAudioRecvCount(int maxCount);

If the number of receivable streams exceeds the set value, the local user receives the maxCount streams that are closest to the local user. If there are users who belong to the same team as the local user in the room, the local user receives the audio of the teammates first. For example, when maxCount is set to 3, if there are five remote users in the room, two of whom belong to the same team as the local user, and three of whom belong to different teams but are within the audio reception range of the local user, the local user can hear the two teammates and the one user from a different team closest to the local user.

Parameters

maxCount
The maximum number of streams that a user can receive within a specified audio reception range.

Returns

  • 0: Success.
  • < 0: Failure.

setPlayerAttenuation

Sets the sound attenuation properties of the media player.

public abstract int setPlayerAttenuation(int playerId, double attenuation, boolean forceSet);
Since
v4.0.1

Parameters

playerId
The ID of the media player. You can get the media player ID by calling getMediaPlayerId.
attenuation
The sound attenuation coefficient of the remote user or media player. The value range is [0,1]. The values are as follows:
  • 0: Broadcast mode, where the volume and timbre are not attenuated with distance, and the volume and timbre heard by local users do not change regardless of distance.
  • (0,0.5): Weak attenuation mode, that is, the volume and timbre are only weakly attenuated during the propagation process, and the sound can travel farther than the real environment.
  • 0.5: (Default) simulates the attenuation of the volume in the real environment; the effect is equivalent to not setting the speaker_attenuation parameter.
  • (0.5,1]: Strong attenuation mode, that is, the volume and timbre attenuate rapidly during the propagation process.
forceSet
Whether to force the sound attenuation effect of the media player:
  • true: Force attenuation to set the attenuation of the user. At this time, the attenuation coefficient of the sound insulation area set in the audioAttenuation in the SpatialAudioZone does not take effect for the user.
  • false: Do not force attenuation e to set the user's sound attenuationffect, as shown in the following two cases.
    • If the sound source and listener are inside and outside the sound isolation area, the sound attenuation effect is determined by the audioAttenuation in SpatialAudioZone.
    • If the sound source and the listener are in the same sound insulation area or outside the same sound insulation area, the sound attenuation effect is determined by attenuation in this method.

Returns

  • 0: Success.
  • < 0: Failure.

setRemoteAudioAttenuation

Sets the sound attenuation effect for the specified user.

public abstract int setRemoteAudioAttenuation(int uid, double attenuation, boolean forceSet);
Since
v4.0.1

Parameters

uid
The user ID. This parameter must be the same as the user ID passed in when the user joined the channel.
attenuation
For the user's sound attenuation coefficient, the value range is [0,1]. The values are as follows:
  • 0: Broadcast mode, where the volume and timbre are not attenuated with distance, and the volume and timbre heard by local users do not change regardless of distance.
  • (0,0.5): Weak attenuation mode, that is, the volume and timbre are only weakly attenuated during the propagation process, and the sound can travel farther than the real environment.
  • 0.5: (Default) simulates the attenuation of the volume in the real environment; the effect is equivalent to not setting the speaker_attenuation parameter.
  • (0.5,1]: Strong attenuation mode, that is, the volume and timbre attenuate rapidly during the propagation process.
forceSet
Whether to force the user's sound attenuation effect:
  • true: Force attenuation to set the sound attenuation of the user. At this time, the attenuation coefficient of the sound insulation area set in the audioAttenuation in the SpatialAudioZone does not take effect for the user.
  • false: Do not force attenuation to set the user's sound attenuation effect, as shown in the following two cases.
    • If the sound source and listener are inside and outside the sound isolation area, the sound attenuation effect is determined by the audioAttenuation in SpatialAudioZone.
    • If the sound source and the listener are in the same sound insulation area or outside the same sound insulation area, the sound attenuation effect is determined by attenuation in this method.

Returns

  • 0: Success.
  • < 0: Failure.

setZones

Sets the sound insulation area.

public abstract int setZones(SpatialAudioZone[] zones);
Since
v4.0.1

In virtual interactive scenarios, you can use this method to set the sound insulation area and sound attenuation coefficient. When the sound source (which can be the user or the media player) and the listener belong to the inside and outside of the sound insulation area, they can experience the attenuation effect of sound similar to the real environment when it encounters a building partition.

  • When the sound source and the listener belong to the inside and outside of the sound insulation area, the sound attenuation effect is determined by the sound attenuation coefficient in SpatialAudioZone.
  • If the user or media player is in the same sound insulation area, it is not affected by SpatialAudioZone, and the sound attenuation effect is determined by the attenuation parameter in setPlayerAttenuation or setRemoteAudioAttenuation. If you do not call setPlayerAttenuation or setRemoteAudioAttenuation, the default sound attenuation coefficient of the SDK is 0.5, which simulates the attenuation of the sound in the real environment.
  • If the sound source and the receiver belong to two sound insulation areas, the receiver cannot hear the sound source.
Note: If this method is called multiple times, the last sound insulation area set takes effect.

Parameters

zones
Sound insulation area settings. See SpatialAudioZone.

Returns

  • 0: Success.
  • < 0: Failure.

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.

Parameters

playerId
The ID of the media player. You can get the media player ID by calling getMediaPlayerId.
positionInfo
The spatial position of the media player. See RemoteVoicePositionInfo.

Returns

  • 0: Success.
  • < 0: Failure.

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 needs to be used with updateRemotePosition. The SDK calculates the relative position between the local and remote users according to this method and the parameter settings in updateRemotePosition, and then calculates the user's spatial audio effect parameters.

Parameters

position
The coordinates in the world coordinate system. This parameter is an array of length 3, and the three values represent the front, right, and top coordinates in turn.
axisForward
The unit vector of the x axis in the coordinate system. This parameter is an array of length 3, and the three values represent the front, right, and top coordinates in turn.
axisRight
The unit vector of the y axis in the coordinate system. This parameter is an array of length 3, and the three values represent the front, right, and top coordinates in turn.
axisUp
The unit vector of the z axis in the coordinate system. This parameter is an array of length 3, and the three values represent the front, right, and top coordinates in turn.

Returns

  • 0: Success.
  • < 0: Failure.