Agora Java API Reference for Android

Public Member Functions | Static Public Member Functions | List of all members
io.agora.spatialaudio.ILocalSpatialAudioEngine Class Referenceabstract
Inheritance diagram for io.agora.spatialaudio.ILocalSpatialAudioEngine:

## Public Member Functions
abstract int | initialize (LocalSpatialAudioConfig config)
| Initializes `ILocalSpatialAudioEngine`. More...
abstract int | updateRemotePosition (int uid, RemoteVoicePositionInfo posInfo)
| Updates the spatial position of the specified remote user. More...
abstract int | updateRemotePositionEx (int uid, RemoteVoicePositionInfo posInfo, RtcConnection connection)
abstract int | removeRemotePosition (int uid)
| Removes the spatial position of the specified remote user. More...
abstract int | removeRemotePositionEx (int uid, RtcConnection connection)
abstract int | clearRemotePositionsEx (RtcConnection connection)
abstract int | setRemoteAudioAttenuation (int uid, double attenuation, boolean forceSet)
| Sets the sound attenuation effect for the specified user. More...
Public Member Functions inherited from io.agora.spatialaudio.IBaseSpatialAudioEngine
abstract int | setMaxAudioRecvCount (int maxCount)
| Sets the maximum number of streams that a user can receive in a specified audio reception range. More...
abstract int | setAudioRecvRange (float range)
| Sets the audio reception range of the local user. More...
abstract int | setDistanceUnit (float unit)
| Sets the length (in meters) of the game engine distance per unit. More...
abstract int | updateSelfPosition (float[] position, float[] axisForward, float[] axisRight, float[] axisUp)
| Updates the spatial position of the local user. More...
abstract int | updatePlayerPositionInfo (int playerId, RemoteVoicePositionInfo positionInfo)
| Updates the spatial position of the media player. More...
abstract int | muteLocalAudioStream (boolean mute)
| Stops or resumes publishing the local audio stream. More...
abstract int | muteAllRemoteAudioStreams (boolean mute)
| Stops or resumes subscribing to the audio streams of all remote users. More...
abstract int | setZones (SpatialAudioZone[] zones)
| Sets the sound insulation area. More...
abstract int | setPlayerAttenuation (int playerId, double attenuation, boolean forceSet)
| Sets the sound attenuation properties of the media player. More...
abstract int | muteRemoteAudioStream (int uid, boolean mute)
abstract int | updateSelfPositionEx (float[] position, float[] axisForward, float[] axisRight, float[] axisUp, RtcConnection connection)
abstract int | clearRemotePositions ()
| Removes the spatial positions of all remote users. More...

## Static Public Member Functions
static synchronized ILocalSpatialAudioEngine | create ()
| Creates `ILocalSpatialAudioEngine`. More...
static synchronized void | destroy ()
| Destroys `ILocalSpatialAudioEngine`. More...

## Additional Inherited Members
Protected Member Functions inherited from io.agora.spatialaudio.IBaseSpatialAudioEngine
abstract int | release ()
| Releases all resources used by the music content center. More...

## Member Function Documentation

## ◆ create()

static synchronized ILocalSpatialAudioEngine io.agora.spatialaudio.ILocalSpatialAudioEngine.create | ( |  | ) |
| static

Creates `ILocalSpatialAudioEngine`.

Call this method before `initialize`.

Returns
  `ILocalSpatialAudioEngine`

## ◆ destroy()

static synchronized void io.agora.spatialaudio.ILocalSpatialAudioEngine.destroy | ( |  | ) |
| static

Destroys `ILocalSpatialAudioEngine`.

This method releases all resources under `ILocalSpatialAudioEngine`. When the user does not need to use the spatial audio effect, you can call this method to release resources for other operations. After calling this method, you can no longer use any of the APIs under `ILocalSpatialAudioEngine`. To use the spatial audio effect again, you need to wait until the `destroy` method execution to complete before calling `initialize` to create a new `ILocalSpatialAudioEngine`.

Note
  Call this method before the `destroy()` method under `RtcEngine`.

## ◆ initialize()

abstract int io.agora.spatialaudio.ILocalSpatialAudioEngine.initialize | ( | LocalSpatialAudioConfig | config | ) |
| abstract

Initializes `ILocalSpatialAudioEngine`.

Note
  - Call this method after calling `create`.
  - Before calling other methods of the `ILocalSpatialAudioEngine` class, you need to call this method to initialize `ILocalSpatialAudioEngine`.
  - The SDK supports creating only one `ILocalSpatialAudioEngine` instance for an app.

Parameters

  config | The configuration of `ILocalSpatialAudioEngine`. See `LocalSpatialAudioConfig`.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ updateRemotePosition()

abstract int io.agora.spatialaudio.ILocalSpatialAudioEngine.updateRemotePosition | ( | int | uid,
|  | RemoteVoicePositionInfo | posInfo
| ) |  |
| abstract

Updates the spatial position of the specified remote user.

After successfully calling this method, the SDK calculates the spatial audio parameters based on the relative position of the local and remote user.

Note
  Call this method after the `joinChannel(String token, String channelId, String optionalInfo, int uid)` or `joinChannel(String token, String channelId, int uid, ChannelMediaOptions options)` method.

Parameters

  uid | The user ID. This parameter must be the same as the user ID passed in when the user joined the channel.
  posInfo | The spatial position of the remote user. See `RemoteVoicePositionInfo`.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ removeRemotePosition()

abstract int io.agora.spatialaudio.ILocalSpatialAudioEngine.removeRemotePosition | ( | int | uid | ) |
| abstract

Removes the spatial position of the specified remote user.

After successfully calling this method, the local user no longer hears the specified remote user. After leaving the channel, to avoid wasting computing resources, call this method to delete the spatial position information of the specified remote user. Otherwise, the user's spatial position information will be saved continuously. When the number of remote users exceeds the number of audio streams that can be received as set in `setMaxAudioRecvCount`, the system automatically unsubscribes from the audio stream of the user who is furthest away based on relative distance.

Parameters

  uid | The user ID. This parameter must be the same as the user ID passed in when the user joined the channel.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRemoteAudioAttenuation()

abstract int io.agora.spatialaudio.ILocalSpatialAudioEngine.setRemoteAudioAttenuation | ( | int | uid,
|  | double | attenuation,
|  | boolean | forceSet
| ) |  |
| abstract

Sets the sound attenuation effect for the specified user.

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` of 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.