# 空间音频 (/zh-CN/api-reference/rtc/android/4.6.0/audio/pre-and-post-processing/spatial-audio)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## clearRemotePositions [#clearremotepositions]
移除所有远端用户的空间位置。
```java
public abstract int clearRemotePositions();
```
调用该方法后,本地用户将无法再听到任何远端用户的声音。你也可以在离开频道后调用该方法以释放资源。
### 返回值 [#返回值]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类]
- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ibasespatialaudioengine)
## create [#create]
创建一个 ILocalSpatialAudioEngine 实例。
```java
public static synchronized ILocalSpatialAudioEngine create()
```
在调用 [initialize](/zh-CN/api-reference/rtc/android/audio/pre-and-post-processing/spatial-audio#api_ilocalspatialaudioengine_initialize_ilocalspatialaudioengine) 之前调用该方法。
### 返回值 [#返回值-1]
方法调用成功,返回 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ilocalspatialaudioengine) 实例。
### 所属接口类 [#所属接口类-1]
- [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ilocalspatialaudioengine)
## enableSpatialAudio [#enablespatialaudio]
启用或关闭空间音效。
```java
public abstract int enableSpatialAudio(boolean enabled);
```
你可以调用 [setRemoteUserSpatialAudioParams](/zh-CN/api-reference/rtc/android/audio/pre-and-post-processing/spatial-audio#api_irtcengine_setremoteuserspatialaudioparams) 设置远端用户的空间音效参数。
注:
- 你可以在加入频道前或加入频道后调用此方法。
- 此方法依赖空间音效动态库 libagora_spatial_audio_extension.so。如果该动态库被删除,则无法正常启用该功能。
### 参数 [#参数]
#### `enabled` [#enabled]
是否启用空间音效:
- true:启用空间音效。
- false:关闭空间音效。
### 返回值 [#返回值-2]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-2]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## initialize [#initialize]
初始化 ILocalSpatialAudioEngine。
```java
public abstract int initialize(LocalSpatialAudioConfig config);
```
注:
- 请在调用 create 方法后调用此方法。
- 在调用 ILocalSpatialAudioEngine 的其他方法前,必须先调用 initialize 初始化 ILocalSpatialAudioEngine。
- 每个 App 仅支持创建一个 ILocalSpatialAudioEngine 实例。
### 参数 [#参数-1]
#### `config` [#config]
[ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ilocalspatialaudioengine) 的配置。详见 [LocalSpatialAudioConfig](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-localspatialaudioconfig)。
### 返回值 [#返回值-3]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ilocalspatialaudioengine)
## muteAllRemoteAudioStreams [#muteallremoteaudiostreams]
停止或恢复订阅所有远端用户的音频流。
```java
public abstract int muteAllRemoteAudioStreams(boolean mute);
```
调用该方法后,本地用户将停止或恢复订阅所有远端用户的音频流,包括后续加入频道的用户。
注:
- 请在调用 joinChannel 方法后调用本方法。
- 使用空间音效时,如需设置是否停止订阅所有远端用户的音频流,声网推荐使用本方法,而非 RtcEngine 下的同名方法。
- 调用本方法后,需要调用 updateSelfPosition 和 updateRemotePosition 方法更新本地用户和远端用户的空间位置,否则本方法的设置不会生效。
### 参数 [#参数-2]
#### `mute` [#mute]
是否停止订阅所有远端用户的音频流:
- true:停止订阅所有远端用户的音频流。
- false:订阅所有远端用户的音频流。
### 返回值 [#返回值-4]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ibasespatialaudioengine)
## muteLocalAudioStream [#mutelocalaudiostream]
停止或恢复发布本地音频流。
```java
public abstract int muteLocalAudioStream(boolean mute);
```
:::info[注]
[muteLocalAudioStream](/zh-CN/api-reference/rtc/android/audio/pre-and-post-processing/spatial-audio#api_ibasespatialaudioengine_mutelocalaudiostream_ibasespatialaudioengine) 方法不会影响任何正在进行的音频录制,因为它不会禁用音频采集设备。 请在调用 `joinChannel` 方法之后调用该方法。 使用空间音效时,如果需要设置是否停止发布本地音频流,声网推荐调用该方法,而不是 [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) 下的同名方法。 该方法成功调用后会在远端客户端触发 [onUserMuteAudio](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onusermuteaudio) 和 [onRemoteAudioStateChanged](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostatechanged) 回调。
:::
### 相关回调 [#相关回调]
该方法成功调用后会在远端客户端触发 [onUserMuteAudio](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onusermuteaudio) 和 [onRemoteAudioStateChanged](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostatechanged) 回调。
### 参数 [#参数-3]
#### `mute` [#mute-1]
是否停止发布本地音频流:
- true:停止发布本地音频流。
- false:发布本地音频流。
### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ibasespatialaudioengine)
## muteRemoteAudioStream [#muteremoteaudiostream]
停止或恢复订阅指定远端用户的音频流。
```java
public abstract int muteRemoteAudioStream(int uid, boolean mute);
```
注:
- 请在调用 joinChannel 方法后调用此方法。
- 使用空间音效时,如需设置是否停止订阅指定用户的音频流,声网推荐调用此方法,而非 muteRemoteAudioStream 方法。
### 参数 [#参数-4]
#### `uid` [#uid]
远端用户 ID。该参数必须与用户加入频道时传入的用户 ID 相同。
#### `mute` [#mute-2]
是否订阅指定远端用户的音频流:
- true:停止订阅指定用户的音频流。
- false:(默认)订阅指定用户的音频流。SDK 会根据本地用户与远端用户之间的距离决定是否订阅。
### 返回值 [#返回值-6]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-6]
- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ibasespatialaudioengine)
## destroy [#destroy]
销毁 ILocalSpatialAudioEngine 实例。
```java
public static synchronized void destroy()
```
调用该方法后,将无法再使用 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ilocalspatialaudioengine) 下的任何 API。如需再次使用空间音效功能,需等待 [destroy](/zh-CN/api-reference/rtc/android/audio/pre-and-post-processing/spatial-audio#api_ilocalspatialaudioengine_release_ilocalspatialaudioengine) 方法执行完成后,再调用 [initialize](/zh-CN/api-reference/rtc/android/audio/pre-and-post-processing/spatial-audio#api_ilocalspatialaudioengine_initialize_ilocalspatialaudioengine) 创建新的 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ilocalspatialaudioengine) 实例。
:::info[注]
请在调用 [destroy](/zh-CN/api-reference/rtc/android/audio/pre-and-post-processing/spatial-audio#api_ilocalspatialaudioengine_release_ilocalspatialaudioengine) 方法之前调用此方法。
:::
### 所属接口类 [#所属接口类-7]
- [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ilocalspatialaudioengine)
## removeRemotePosition [#removeremoteposition]
移除指定远端用户的空间位置信息。
```java
public abstract int removeRemotePosition(int uid);
```
调用该方法成功后,你将不再听到指定远端用户的声音。离开频道后,为避免浪费计算资源,建议调用该方法移除指定远端用户的空间位置信息。否则,该用户的空间位置信息将持续保留。当远端用户数量超过通过 [setMaxAudioRecvCount](/zh-CN/api-reference/rtc/android/audio/pre-and-post-processing/spatial-audio#api_ibasespatialaudioengine_setmaxaudiorecvcount) 设置的可接收音频流数量时,系统会根据相对距离自动取消订阅距离最远用户的音频流。
### 参数 [#参数-5]
#### `uid` [#uid-1]
`uid`。该参数必须与用户加入频道时传入的用户 ID 相同。
### 返回值 [#返回值-7]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-8]
- [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ilocalspatialaudioengine)
## setAudioRecvRange [#setaudiorecvrange]
设置本地用户的音频接收范围。
```java
public abstract int setAudioRecvRange(float range);
```
你可以在任意时间调用该方法以更新音频接收范围。设置成功后,本地用户只能接收设定范围内或同一队伍中远端用户的音频。
### 参数 [#参数-6]
#### `range` [#range]
最大音频接收范围,单位为米。该参数必须大于 0。(默认值为 20)
### 返回值 [#返回值-8]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-9]
- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ibasespatialaudioengine)
## setDistanceUnit [#setdistanceunit]
设置游戏引擎中每个单位距离对应的米数。
```java
public abstract int setDistanceUnit(float unit);
```
在声网的空间音效算法中,距离以米为单位进行计算。SDK 默认将游戏引擎中的每个单位距离转换为 1 米。你可以调用该方法将游戏引擎中的每个单位距离转换为指定的米数。
### 参数 [#参数-7]
#### `unit` [#unit]
游戏引擎中每个单位距离对应的米数。该参数必须大于 0.00,默认值为 1.00。例如,将该参数设置为 2.00 表示游戏引擎中每个单位距离等于 2 米。该值越大,当远端用户远离本地用户时,本地用户听到的声音衰减得越快。
### 返回值 [#返回值-9]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-10]
- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ibasespatialaudioengine)
## setHeadphoneEQParameters [#setheadphoneeqparameters]
设置耳机均衡器的低频和高频参数。
```java
public abstract int setHeadphoneEQParameters(int lowGain, int highGain);
```
如果调用 [setHeadphoneEQPreset](/zh-CN/api-reference/rtc/android/audio/pre-and-post-processing/spatial-audio#api_irtcengine_setheadphoneeqpreset) 后未达到预期效果,可以调用 [setHeadphoneEQParameters](/zh-CN/api-reference/rtc/android/audio/pre-and-post-processing/spatial-audio#api_irtcengine_setheadphoneeqparameters) 进一步调整耳机均衡器的低频和高频参数。
### 参数 [#参数-8]
#### `lowGain` [#lowgain]
耳机均衡器的低频参数,取值范围为 [-10, 10]。值越大,声音越深沉。
#### `highGain` [#highgain]
耳机均衡器的高频参数,取值范围为 [-10, 10]。值越大,声音越清晰。
### 返回值 [#返回值-10]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
- -1:发生通用错误。
### 所属接口类 [#所属接口类-11]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## setHeadphoneEQPreset [#setheadphoneeqpreset]
设置预设的耳机均衡器效果。
```java
public abstract int setHeadphoneEQPreset(int preset);
```
该方法主要用于空间音效场景中。你可以选择预设的耳机均衡器来聆听音频,以实现预期的音频体验。
:::info[注]
如果你使用的耳机本身已经具有良好的均衡效果,调用该方法可能不会带来显著提升,甚至可能降低体验。
:::
### 参数 [#参数-9]
#### `preset` [#preset]
预设的耳机均衡器效果:
- HEADPHONE_EQUALIZER_OFF:关闭耳机均衡器,听到原始音频。
- HEADPHONE_EQUALIZER_OVEREAR:为头戴式耳机使用均衡器。
- HEADPHONE_EQUALIZER_INEAR:为入耳式耳机使用均衡器。
### 返回值 [#返回值-11]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
- -1:发生通用错误(无具体原因)。
### 所属接口类 [#所属接口类-12]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## setMaxAudioRecvCount [#setmaxaudiorecvcount]
设置你在指定音频接收范围内可接收的最大音频流数量。
```java
public abstract int setMaxAudioRecvCount(int maxCount);
```
如果可接收的音频流数量超过该设置值,本地用户将接收距离其最近的 `maxCount` 条音频流。
### 参数 [#参数-10]
#### `maxCount` [#maxcount]
你在指定音频接收范围内可接收的最大音频流数量。该参数的取值应小于或等于 16。(默认值为 10)
### 返回值 [#返回值-12]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-13]
- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ibasespatialaudioengine)
## setPlayerAttenuation [#setplayerattenuation]
设置媒体播放器的声音衰减属性。
```java
public abstract int setPlayerAttenuation(int playerId, double attenuation, boolean forceSet);
```
### 参数 [#参数-11]
#### `playerId` [#playerid]
媒体播放器的 ID。你可以通过调用 [getMediaPlayerId](/zh-CN/api-reference/rtc/android/playback/media-player/mediaplayer-info#api_imediaplayer_getmediaplayerid) 获取该 ID。
#### `attenuation` [#attenuation]
远端用户或媒体播放器的声音衰减系数,取值范围为 [0,1]。具体说明如下:
- 0:广播模式,音量和音色不随距离衰减,本地用户听到的音量和音色不会因距离变化而变化。
- (0, 0.5):弱衰减模式,音量和音色在传播过程中仅有轻微衰减,声音传播距离比真实环境更远。
- 0.5:(默认)模拟真实环境中的音量衰减效果,等效于未设置 speaker_attenuation 参数。
- (0.5, 1]:强衰减模式,音量和音色在传播过程中迅速衰减。
#### `forceSet` [#forceset]
是否强制设置媒体播放器的声音衰减效果:
- true:强制使用 attenuation 设置媒体播放器的衰减效果,此时 SpatialAudioZone 中 audioAttenuation 设置的隔音区衰减系数对媒体播放器无效。
- false:不强制使用 attenuation 设置媒体播放器的声音衰减效果,具体如下:
- 如果声源和听众分别位于隔音区内外,声音衰减效果由 SpatialAudioZone 中的 audioAttenuation 决定。
- 如果声源和听众位于同一隔音区内或同一隔音区外,声音衰减效果由本方法中的 attenuation 参数决定。
### 返回值 [#返回值-13]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-14]
- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ibasespatialaudioengine)
## setRemoteAudioAttenuation [#setremoteaudioattenuation]
设置指定用户的声音衰减效果。
```java
public abstract int setRemoteAudioAttenuation(int uid, double attenuation, boolean forceSet);
```
### 参数 [#参数-12]
#### `uid` [#uid-2]
用户 ID。该参数必须与用户加入频道时传入的用户 ID 相同。
#### `attenuation` [#attenuation-1]
用户的声音衰减系数,取值范围为 [0, 1]。具体取值说明如下:
- 0:广播模式,音量和音色不会随距离衰减,本地用户听到的音量和音色不会因距离变化。
- (0, 0.5):弱衰减模式,音量和音色在传播过程中仅有轻微衰减,声音传播距离大于真实环境。
- 0.5:(默认)模拟真实环境中的音量衰减效果,等效于未设置 speaker_attenuation 参数。
- (0.5, 1]:强衰减模式,音量和音色在传播过程中快速衰减。
#### `forceSet` [#forceset-1]
是否强制设置用户的声音衰减效果:
- true:强制使用 attenuation 设置用户的声音衰减效果,此时 SpatialAudioZone 中 audioAttenuation 设置的隔音区衰减系数对该用户无效。
- false:不强制使用 attenuation 设置用户的声音衰减效果,具体如下:
- 若声源和接收者分别位于隔音区内外,衰减效果由 SpatialAudioZone 中的 audioAttenuation 决定;
- 若声源和接收者位于同一隔音区或同一隔音区外,衰减效果由本方法中的 attenuation 决定。
### 返回值 [#返回值-14]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-15]
- [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ilocalspatialaudioengine)
## setRemoteUserSpatialAudioParams [#setremoteuserspatialaudioparams]
设置远端用户的空间音效参数。
```java
public abstract int setRemoteUserSpatialAudioParams(int uid, SpatialAudioParams params);
```
在调用 [enableSpatialAudio](/zh-CN/api-reference/rtc/android/audio/pre-and-post-processing/spatial-audio#api_irtcengine_enablespatialaudio) 后调用此方法。设置成功后,你可以听到具有空间感的远端用户的声音。
### 参数 [#参数-13]
#### `uid` [#uid-3]
用户 ID,必须与该用户加入频道时使用的 ID 相同。
#### `params` [#params]
空间音效参数。详见 [SpatialAudioParams](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-spatialaudioparams)。
### 返回值 [#返回值-15]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-16]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## setSpatialAudioParams [#setspatialaudioparams]
启用或关闭媒体播放器的空间音效。
```java
int setSpatialAudioParams(SpatialAudioParams params);
```
若需关闭空间音效,请将 `params` 参数设置为 `null`。
### 参数 [#参数-14]
#### `params` [#params-1]
媒体播放器的空间音效参数,详见 [SpatialAudioParams](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-spatialaudioparams)。
### 返回值 [#返回值-16]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-17]
- [IMediaPlayer](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_imediaplayer)
## setZones [#setzones]
设置隔音区域。
```java
public abstract int setZones(SpatialAudioZone[] zones);
```
在虚拟互动场景中,你可以使用该方法设置隔音区域及声音衰减系数。当声源(可以是用户或媒体播放器)和接收者分别处于隔音区域的内外时,可以体验到类似真实环境中声音遇到建筑隔断时的衰减效果:
- 当声源和接收者分别处于隔音区域的内外时,声音的衰减效果由 SpatialAudioZone 中的声音衰减系数决定。
- 如果用户或媒体播放器处于同一个隔音区域内,则声音衰减效果由 setPlayerAttenuation 或 setRemoteAudioAttenuation 中的 attenuation 参数决定。如果你未调用 setPlayerAttenuation 或 setRemoteAudioAttenuation,SDK 默认的声音衰减系数为 0.5,用于模拟真实环境中的声音衰减。
- 如果声源和接收者分别处于两个不同的隔音区域,接收者将无法听到声源。
:::info[注]
如果多次调用该方法,以最后一次设置的隔音区域为准。
:::
### 参数 [#参数-15]
#### `zones` [#zones]
隔音区域设置。当该参数设置为 `null` 时,表示清除所有隔音区域。详见 [SpatialAudioZone](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-spatialaudiozone)。
### 返回值 [#返回值-17]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-18]
- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ibasespatialaudioengine)
## updatePlayerPositionInfo [#updateplayerpositioninfo]
更新媒体播放器的空间位置。
```java
public abstract int updatePlayerPositionInfo(int playerId, RemoteVoicePositionInfo positionInfo);
```
调用该方法后,本地用户可以听到媒体播放器空间位置的变化。
### 调用时机 [#调用时机]
该方法可以在加入频道前或加入频道后调用。
### 参数 [#参数-16]
#### `playerId` [#playerid-1]
媒体播放器的 ID。你可以通过调用 [getMediaPlayerId](/zh-CN/api-reference/rtc/android/playback/media-player/mediaplayer-info#api_imediaplayer_getmediaplayerid) 获取该 ID。
#### `positionInfo` [#positioninfo]
媒体播放器的空间位置,详见 [RemoteVoicePositionInfo](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-remotevoicepositioninfo)。
### 返回值 [#返回值-18]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-19]
- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ibasespatialaudioengine)
## updateRemotePosition [#updateremoteposition]
更新指定远端用户的空间位置。
```java
public abstract int updateRemotePosition(int uid, RemoteVoicePositionInfo posInfo);
```
调用该方法后,SDK 会根据本地用户与远端用户之间的相对位置计算空间音效参数。
:::info[注]
请在调用 `joinChannel` 方法后再调用此方法。
:::
### 参数 [#参数-17]
#### `uid` [#uid-4]
用户 ID,必须与该用户加入频道时传入的用户 ID 相同。
#### `posInfo` [#posinfo]
远端用户的空间位置。详见 [RemoteVoicePositionInfo](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-remotevoicepositioninfo)。
### 返回值 [#返回值-19]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-20]
- [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ilocalspatialaudioengine)
## updateSelfPosition [#updateselfposition]
更新本地用户的空间位置。
```java
public abstract int updateSelfPosition(float[] position, float[] axisForward, float[] axisRight, float[] axisUp);
```
[updateSelfPosition](/zh-CN/api-reference/rtc/android/audio/pre-and-post-processing/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 需要与 [updateRemotePosition](/zh-CN/api-reference/rtc/android/audio/pre-and-post-processing/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 搭配使用。SDK 会根据该方法和 [updateRemotePosition](/zh-CN/api-reference/rtc/android/audio/pre-and-post-processing/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 中的参数设置,计算本地用户与远端用户之间的相对位置,并据此计算空间音效参数。
### 参数 [#参数-18]
#### `position` [#position]
世界坐标系中的坐标。该参数为长度为 3 的数组,三个值依次表示前、右、上的坐标。
#### `axisForward` [#axisforward]
坐标系中 x 轴的单位向量。该参数为长度为 3 的数组,三个值依次表示前、右、上的坐标。
#### `axisRight` [#axisright]
坐标系中 y 轴的单位向量。该参数为长度为 3 的数组,三个值依次表示前、右、上的坐标。
#### `axisUp` [#axisup]
坐标系中 z 轴的单位向量。该参数为长度为 3 的数组,三个值依次表示前、右、上的坐标。
### 返回值 [#返回值-20]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-21]
- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ibasespatialaudioengine)