IBaseSpatialAudioEngine

muteAllRemoteAudioStreams

Unsubscribes from or resumes the audio streams of all remote users.

abstract muteAllRemoteAudioStreams(mute: boolean): number;

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

abstract muteLocalAudioStream(mute: boolean): number;

Note:

This method does not affect audio capture status, as it does not disable the audio capture device.
This method must be called after joinChannel1 or joinChannel.
When using spatial audio, to configure whether to publish the local audio stream, it is recommended to call this method instead of the muteLocalAudioStream method of IRtcEngine.
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

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

muteRemoteAudioStream

Unsubscribes from or resumes the audio stream of a specified remote user.

abstract muteRemoteAudioStream(uid: number, mute: boolean): number;

Parameters

uid

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

mute

Whether to unsubscribe from the specified remote user's audio stream.

true: Unsubscribe from 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 resolution suggestions.

release

Destroys IBaseSpatialAudioEngine.

abstract release(): void;

This method releases all resources under IBaseSpatialAudioEngine. When spatial audio is no longer needed, you can call this method to release the resources for other operations. After calling this method, you can no longer use any APIs under IBaseSpatialAudioEngine.

setAudioRecvRange

Sets the audio reception range for the local user.

abstract setAudioRecvRange(range: number): number;

After this method is successfully called, 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 reception range.

Parameters

range: The maximum range for receiving audio, in distance units defined by the game engine. The value must be greater than 0. Default is 20.

Return Values

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

setDistanceUnit

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

abstract setDistanceUnit(unit: number): number;

The distance unit in the game engine is custom-defined, while the distance unit for the Agora spatial audio algorithm is in 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 game engine distance. The value must be greater than 0.00. 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 fades as the 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.

abstract setMaxAudioRecvCount(maxCount: number): number;

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 nearest sources.

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.

abstract setPlayerAttenuation(
    playerId: number,
    attenuation: number,
    forceSet: boolean
  ): number;

Parameters

playerId

Media player ID.

attenuation

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

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

forceSet

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

true: Forcibly use the attenuation value 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: Do not forcibly use the attenuation value. There are two cases:
- If the sound source and listener are inside and outside of the sound isolation zone respectively, the attenuation effect is determined by the audioAttenuation setting in SpatialAudioZone.
- If the sound source and listener are both inside or both outside the same sound isolation zone, the attenuation effect is determined by the attenuation value in this method.

Return Values

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

setZones

Sets sound insulation zones.

abstract setZones(zones: SpatialAudioZone, zoneCount: number): number;

In virtual interactive scenarios, you can use this method to set sound insulation zones and audio attenuation coefficients. When the audio source (can be a user or media player) and the listener are located inside and outside the zone respectively, the sound will be attenuated as in real environments when blocked by structures.

When the audio source and listener are inside and outside the zone respectively, the attenuation effect is determined by the attenuation coefficient in SpatialAudioZone.
If the user or media player is in the same zone, SpatialAudioZone has no effect, and the 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 to simulate real-world attenuation.
If the audio source and receiver are in different zones, the receiver cannot hear the audio source.

Note: If this method is called multiple times, the last configuration takes effect.

Parameters

zones: Configuration for sound insulation zones. See SpatialAudioZone. Setting this parameter to null clears all zones.
zoneCount: The number of sound insulation zones.

Return Values

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

updatePlayerPositionInfo

Updates the spatial position of the media player.

abstract updatePlayerPositionInfo(
    playerId: number,
    positionInfo: RemoteVoicePositionInfo
  ): number;

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

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

updateSelfPosition

Updates the spatial position of the local user.

abstract updateSelfPosition(
    position: number[],
    axisForward: number[],
    axisRight: number[],
    axisUp: number[]
  ): number;

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 forward, right, and up coordinate values respectively.
axisForward: Unit vector of the forward axis in the world coordinate system. This parameter is an array of length 3, representing the forward, right, and up coordinate values respectively.
axisRight: Unit vector of the right axis in the world coordinate system. This parameter is an array of length 3, representing the forward, right, and up coordinate values respectively.
axisUp: Unit vector of the up axis in the world coordinate system. This parameter is an array of length 3, representing the forward, right, and up coordinate values respectively.

Return Values

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