IBaseSpatialAudioEngine

muteAllRemoteAudioStreams

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

abstract muteAllRemoteAudioStreams(mute: boolean): number;

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

Note:

This method must be called after joinChannel.
When using spatial audio, if you need to set 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 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

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 the audio capture state because it does not disable the audio capture device.
This method must be called after joinChannel1 or joinChannel.
When using spatial audio, if you need to set whether to publish the local audio stream, it is recommended to call this method instead of IRtcEngine's muteLocalAudioStream method.
After successfully calling this method, the remote side triggers 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

Stops or resumes subscribing to 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 joining 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

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 you no longer need to use spatial audio, 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 successful setting, 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: Maximum range for receiving audio, measured in the distance units of 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 unit used by Agora's spatial audio algorithm is meters. By default, the SDK converts one game engine unit to one meter. You can call this method to convert one unit of the game engine's distance into the 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, if unit is set to 2.00, it 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 properties 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. 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 real environments.
0.5: (Default) Simulates sound attenuation in real environments. Equivalent to not setting the attenuation parameter.
(0.5,1]: Strong attenuation mode. Volume and tone attenuate rapidly during transmission.

forceSet

Whether to force the media player to use the specified attenuation effect:

true: Forces the media player to use the attenuation setting. In this case, the audioAttenuation setting in SpatialAudioZone does not affect the media player.
false: Does not force the media player to use the attenuation setting. Two scenarios:
- If the sound source and listener are in different zones (inside and outside the sound isolation zone), the attenuation effect is determined by audioAttenuation in SpatialAudioZone.
- If both are in the same zone or both outside the 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 sound source (which can be a user or media player) and the listener are in different zones, the sound experiences attenuation similar to real-world scenarios when encountering physical barriers.

When the sound source and listener are in different zones, the attenuation effect is determined by the audio attenuation coefficient in SpatialAudioZone.
If the user or media player is in the same zone, the attenuation effect is 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 sound source and receiver are in two different zones, the receiver cannot hear the sound source.

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

Parameters

zones: Configuration of sound insulation zones. See SpatialAudioZone. Setting this parameter to null clears all zones.
Note: On Windows, ensure that the number of elements in the zones array matches the value of zoneCount, otherwise a crash may occur.
zoneCount: 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 changes in the media player's spatial position.

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

Return Values

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