# 空间音频 (/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## clearRemotePositions [#clearremotepositions]
删除所有远端用户的空间位置信息。
```dart
Future clearRemotePositions();
```
成功调用该方法后,本地用户将听不到所有远端用户。
离开频道后,为避免计算资源的浪费,你也可以调用该方法删除所有远端用户的空间位置信息。
### 返回值 [#返回值]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类]
- [LocalSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ilocalspatialaudioengine)
## enableSpatialAudio [#enablespatialaudio]
开启或关闭空间音频。
```dart
Future enableSpatialAudio(bool enabled);
```
开启空间音频后,你可以调用 [setRemoteUserSpatialAudioParams](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_irtcengine_setremoteuserspatialaudioparams) 设置远端用户的空间音频参数。
:::note
注:
- 该方法在加入频道前后均可调用。
- 该方法依赖于空间音频动态库 `libagora_spatial_audio_extension.dll`,如果删除该动态库会导致无法正常开启该功能。
:::
### 参数 [#参数]
是否开启空间音频:
- true: 开启空间音频。
- false: 关闭空间音频。
### 返回值 [#返回值-1]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)
## getLocalSpatialAudioEngine [#getlocalspatialaudioengine]
获取 [LocalSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ilocalspatialaudioengine) 对象。
```dart
LocalSpatialAudioEngine getLocalSpatialAudioEngine();
```
:::note
注: 该方法需要在初始化 [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) 对象后调用。
:::
### 返回值 [#返回值-2]
一个 [LocalSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ilocalspatialaudioengine) 对象。
### 所属接口类 [#所属接口类-2]
- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)
## initialize [#initialize]
初始化 [LocalSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ilocalspatialaudioengine)。
```dart
Future initialize();
```
:::note
注:
- 在调用 [LocalSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ilocalspatialaudioengine) 类的其他方法前,你需要先调用该方法初始化 [LocalSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ilocalspatialaudioengine)。
- SDK 只支持每个 App 创建一个 [LocalSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ilocalspatialaudioengine) 实例。
:::
### 返回值 [#返回值-3]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [LocalSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ilocalspatialaudioengine)
## muteAllRemoteAudioStreams [#muteallremoteaudiostreams]
取消或恢复订阅所有远端用户的音频流。
```dart
Future muteAllRemoteAudioStreams(bool mute);
```
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的音频流,包括在调用该方法后加入频道的用户的音频流。
:::note
注:
- 该方法需要在 [joinChannel](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_joinchannel2) 后调用。
- 在使用空间音频时,如需设置是否订阅所有远端用户的音频流,建议调用该方法替代 [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) 的 [muteAllRemoteAudioStreams](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_muteallremoteaudiostreams_ibasespatialaudioengine) 方法。
- 在调用该方法后,你需要调用 [updateSelfPosition](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 和 [updateRemotePosition](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 更新本地用户和远端用户的空间位置,否则该方法中的设置不会生效。
:::
### 参数 [#参数-1]
是否取消订阅所有远端用户的音频流:
- true: 取消订阅所有远端用户的音频流。
- false: 订阅所有远端用户的音频流。
### 返回值 [#返回值-4]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [BaseSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ibasespatialaudioengine)
## muteLocalAudioStream [#mutelocalaudiostream]
取消或恢复发布本地音频流。
```dart
Future muteLocalAudioStream(bool mute);
```
:::note
注:
- 该方法不影响音频采集状态,因为没有禁用音频采集设备。
- 该方法需要在 `joinChannel1` 或 [joinChannel](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_joinchannel2) 后调用。
- 在使用空间音频时,如需设置是否发布本地音频流,建议调用该方法替代 [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) 的 [muteLocalAudioStream](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_mutelocalaudiostream_ibasespatialaudioengine) 方法。
- 成功调用该方法后,远端会触发 [onUserMuteAudio](/zh-CN/api-reference/rtc/flutter/audio/audio-basic#callback_irtcengineeventhandler_onusermuteaudio) 回调和 [onRemoteAudioStateChanged](/zh-CN/api-reference/rtc/flutter/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostatechanged) 回调。
:::
### 参数 [#参数-2]
是否取消发布本地音频流。
- true: 取消发布本地音频流。
- false: 发布本地音频流。
### 返回值 [#返回值-5]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [BaseSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ibasespatialaudioengine)
## muteRemoteAudioStream [#muteremoteaudiostream]
取消或恢复订阅指定远端用户的音频流。
```dart
Future muteRemoteAudioStream({required int uid, required bool mute});
```
### 参数 [#参数-3]
用户 ID。需与用户加入频道时填写的用户 ID 一致。
是否取消订阅指定远端用户的音频流。
- true: 取消订阅指定用户的音频流。
- false:(默认)订阅指定用户的音频流,SDK 根据本地用户和远端用户的距离决定是否订阅。
### 返回值 [#返回值-6]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-6]
- [BaseSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ibasespatialaudioengine)
## release [#release]
销毁 [BaseSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ibasespatialaudioengine)。
```dart
abstract release(): void;
```
该方法释放 [BaseSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ibasespatialaudioengine) 下的所有资源。当用户不需要使用空间音频时,你可以调用该方法将资源释放出来用于其他操作。
调用该方法后,你将无法再使用 [BaseSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ibasespatialaudioengine) 下的任何 API。
### 所属接口类 [#所属接口类-7]
- [BaseSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ibasespatialaudioengine)
## removeRemotePosition [#removeremoteposition]
删除指定远端用户的空间位置信息。
```dart
Future removeRemotePosition(int uid);
```
成功调用该方法后,本地用户将听不到指定的远端用户。
离开频道后,为避免计算资源的浪费,你需要调用该方法删除指定远端用户的空间位置信息。否则,该用户的空间位置信息会一直被保存。当远端用户人数大于 [setMaxAudioRecvCount](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setmaxaudiorecvcount) 中设定的可接收音频流数时,会按照相对距离依次自动取消订阅距离最远的用户的音频流。
### 参数 [#参数-4]
用户 ID。需与用户加入频道时填写的用户 ID 一致。
### 返回值 [#返回值-7]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-8]
- [LocalSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ilocalspatialaudioengine)
## setAudioRecvRange [#setaudiorecvrange]
设置本地用户的音频接收范围。
```dart
Future setAudioRecvRange(double range);
```
设置成功后,用户只能听见设置范围内或属于同一队伍的远端用户。你可以随时调用该方法更新音频的接收范围。
### 参数 [#参数-5]
可接收音频的最大范围,单位为游戏引擎中的距离单位。该参数取值需大于 0,默认值为 20。
### 返回值 [#返回值-8]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-9]
- [BaseSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ibasespatialaudioengine)
## setDistanceUnit [#setdistanceunit]
设置游戏引擎单位距离的长度(米)。
```dart
Future setDistanceUnit(double unit);
```
游戏引擎里的距离单位是游戏引擎自定义的,而声网空间音频算法的距离单位为米。默认情况下,SDK 会将每单位的游戏引擎距离换算为一米。你可以调用该方法,将游戏引擎里的单位距离换算为指定的米数。
### 参数 [#参数-6]
每单位游戏引擎距离转换后的米数。该参数取值需大于 0.00,默认值为 1.00。例如,将 unit 设为 2.00,表示每单位的游戏引擎距离等于 2 米。
该值越大,当远端用户远离本地用户时,本地用户听到的声音衰减速度越快。
### 返回值 [#返回值-9]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-10]
- [BaseSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ibasespatialaudioengine)
## setHeadphoneEQParameters [#setheadphoneeqparameters]
设置耳机均衡器的低频和高频参数。
```dart
Future setHeadphoneEQParameters(
{required int lowGain, required int highGain});
```
在空间音频场景下,如果在调用 [setHeadphoneEQPreset](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 方法使用预设的耳机均衡效果后仍未达到预期,你可以通过调用该方法进一步调节耳机均衡效果。
### 参数 [#参数-7]
耳机均衡器的低频参数。取值范围为 [-10,10],取值越大,声音越低沉。
耳机均衡器的高频参数。取值范围为 [-10,10],取值越大,声音越尖锐。
### 返回值 [#返回值-10]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-11]
- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)
## setHeadphoneEQPreset [#setheadphoneeqpreset]
设置预设的耳机均衡效果。
```dart
Future setHeadphoneEQPreset(HeadphoneEqualizerPreset preset);
```
该方法主要应用于空间音频场景下,你可以选择预设的耳机均衡器收听音频,以达到预期的音频体验。
:::note
注: 如果你使用的耳机已经具备良好的均衡效果,调用该方法时可能不会获得明显的体验提升效果,甚至可能导致体验下降。
:::
### 参数 [#参数-8]
预设的耳机均衡效果。详见 [HeadphoneEqualizerPreset](/zh-CN/api-reference/rtc/flutter/enum-headphoneequalizerpreset)。
### 返回值 [#返回值-11]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-12]
- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)
## setMaxAudioRecvCount [#setmaxaudiorecvcount]
设置音频接收范围内最多可接收的音频流数。
```dart
Future setMaxAudioRecvCount(int maxCount);
```
如果在音频接收范围内可接收的音频流数超过设置的值,则本地用户会接收音源距离较近的 `maxCount` 路音频。
### 参数 [#参数-9]
音频接收范围内最多可接收的音频流数。该参数取值需 ≤ 16,默认值为 10。
### 返回值 [#返回值-12]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-13]
- [BaseSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ibasespatialaudioengine)
## setPlayerAttenuation [#setplayerattenuation]
设置媒体播放器的声音衰减属性。
```dart
Future setPlayerAttenuation(
{required int playerId,
required double attenuation,
required bool forceSet});
```
### 参数 [#参数-10]
媒体播放器 ID。
媒体播放器的声音衰减系数,取值范围为[0,1]。其中:
- 0:广播模式,即音量和音色均不随距离衰减,无论距离远近,本地用户听到的音量和音色都无变化。
- (0,0.5):弱衰减模式,即音量和音色在传播过程中仅发生微弱衰减,跟真实环境相比,声音可以传播得更远。
- 0.5:(默认)模拟音量在真实环境下的衰减,效果等同于不设置 `attenuation` 参数。
- (0.5,1]:强衰减模式,即音量和音色在传播过程中发生迅速衰减。
是否强制设定媒体播放器的声音衰减效果:
- true:强制使用 `attenuation` 设置媒体播放器的声音衰减效果,此时 [SpatialAudioZone](/zh-CN/api-reference/rtc/flutter/class-spatialaudiozone) 中的 `audioAttenuation` 中设置的隔声区域衰减系数对媒体播放器不生效。
- false:不强制使用 `attenuation` 设置媒体播放器的声音衰减效果,分为以下两种情况。
- 如果音源和听声者分属于隔声区域内部和外部,则声音衰减效果由 [SpatialAudioZone](/zh-CN/api-reference/rtc/flutter/class-spatialaudiozone) 中的 `audioAttenuation` 决定。
- 如果音源和听声者在同一个隔声区域内或同在隔声区域外,则声音衰减效果由该方法中的 `attenuation` 决定。
### 返回值 [#返回值-13]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-14]
- [BaseSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ibasespatialaudioengine)
## setRemoteAudioAttenuation [#setremoteaudioattenuation]
设置指定用户的声音衰减效果。
```dart
Future setRemoteAudioAttenuation(
{required int uid, required double attenuation, required bool forceSet});
```
### 参数 [#参数-11]
用户 ID。需与用户加入频道时填写的用户 ID 一致。
针对该用户的声音衰减系数,取值范围为[0,1]。其中:
是否强制设定该用户的声音衰减效果:
- true:强制使用 `attenuation` 设置该用户的声音衰减效果,此时 [SpatialAudioZone](/zh-CN/api-reference/rtc/flutter/class-spatialaudiozone) 中的 `audioAttenuation` 中设置的隔声区域衰减系数对该用户不生效。
- false:不强制使用 `attenuation`设置用户的声音衰减效果,分为以下两种情况。
- 如果音源和听声者分属于隔声区域内部和外部,则声音衰减效果由 [SpatialAudioZone](/zh-CN/api-reference/rtc/flutter/class-spatialaudiozone) 中的 `audioAttenuation` 决定。
- 如果音源和听声者在同一个隔声区域内或同在隔声区域外,则声音衰减效果由该方法中的 `attenuation` 决定。
### 返回值 [#返回值-14]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-15]
- [LocalSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ilocalspatialaudioengine)
## setRemoteUserSpatialAudioParams [#setremoteuserspatialaudioparams]
设置远端用户的空间音频参数。
```dart
Future setRemoteUserSpatialAudioParams(
{required int uid, required SpatialAudioParams params});
```
该方法需要在 [enableSpatialAudio](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_irtcengine_enablespatialaudio) 后调用。成功设置远端用户的空间音频参数后,本地用户听远端用户会有空间感。
### 参数 [#参数-12]
用户 ID。需与用户加入频道时填写的用户 ID 一致。
空间音频参数。详见 [SpatialAudioParams](/zh-CN/api-reference/rtc/flutter/class-spatialaudioparams)。
### 返回值 [#返回值-15]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-16]
- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)
## setSpatialAudioParams [#setspatialaudioparams]
开启或关闭媒体播放器的空间音频。
```dart
Future setSpatialAudioParams(SpatialAudioParams params);
```
成功设置媒体播放器的空间音频参数后,SDK 会开启媒体播放器的空间音频,即本地用户听媒体资源会有空间感。
如果需关闭媒体播放器的空间音频,你需要将 `params` 参数设为空。
### 参数 [#参数-13]
媒体播放器的空间音频参数。详见 [SpatialAudioParams](/zh-CN/api-reference/rtc/flutter/class-spatialaudioparams)。
### 返回值 [#返回值-16]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-17]
- [MediaPlayer](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayer)
## setZones [#setzones]
设置隔声区域。
```dart
Future setZones(
{required SpatialAudioZone zones, required int zoneCount});
```
在虚拟互动场景下,你可以通过该方法设置隔声区域和声音衰减系数。当音源(可以为用户或媒体播放器)跟听声者分属于隔声区域内部和外部时,会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。
- 当音源跟听声者分属于隔声区域内部和外部时,声音的衰减效果由 [SpatialAudioZone](/zh-CN/api-reference/rtc/flutter/class-spatialaudiozone) 中的声音衰减系数决定。
- 如果用户或媒体播放器同在一个隔声区域内,则不受 [SpatialAudioZone](/zh-CN/api-reference/rtc/flutter/class-spatialaudiozone) 的影响,声音的衰减效果由 [setPlayerAttenuation](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) 或 [setRemoteAudioAttenuation](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) 中的 `attenuation` 参数决定。如果不调用 [setPlayerAttenuation](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) 或 [setRemoteAudioAttenuation](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation),则 SDK 默认声音的衰减系数为 0.5,即模拟声音在真实环境下的衰减。
- 如果音源跟接收者分别属于两个隔声区域,则接收者无法听到音源。
:::note
注: 如果多次调用该方法,以最后一次设置的隔声区域为准。
:::
### 参数 [#参数-14]
隔声区域的设置。详见 [SpatialAudioZone](/zh-CN/api-reference/rtc/flutter/class-spatialaudiozone)。当你将该参数设置为 `NULL` 时,表示清除所有隔声区域。
:::note
注: 在 Windows 平台上,需确保 `zones` 数组中的成员个数与 `zoneCount` 的值相等,否则会导致崩溃。
:::
隔声区域的数量。
### 返回值 [#返回值-17]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-18]
- [BaseSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ibasespatialaudioengine)
## updatePlayerPositionInfo [#updateplayerpositioninfo]
更新媒体播放器的空间位置。
```dart
Future updatePlayerPositionInfo(
{required int playerId, required RemoteVoicePositionInfo positionInfo});
```
成功更新后,本地用户可以听到媒体播放器空间位置的变化。
### 调用时机 [#调用时机]
加入频道前后均可调用。
### 参数 [#参数-15]
媒体播放器 ID。
媒体播放器的空间位置信息。详见 [RemoteVoicePositionInfo](/zh-CN/api-reference/rtc/flutter/class-remotevoicepositioninfo)。
### 返回值 [#返回值-18]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-19]
- [BaseSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ibasespatialaudioengine)
## updateRemotePosition [#updateremoteposition]
更新远端用户的空间位置信息。
```dart
Future updateRemotePosition(
{required int uid, required RemoteVoicePositionInfo posInfo});
```
成功调用该方法后,SDK 会根据本地和远端用户的相对位置计算空间音频参数。
:::note
注: 该方法需要在 [joinChannel](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_joinchannel2) 后调用。
:::
### 参数 [#参数-16]
用户 ID。需与用户加入频道时填写的用户 ID 一致。
远端用户的空间位置信息。详见 [RemoteVoicePositionInfo](/zh-CN/api-reference/rtc/flutter/class-remotevoicepositioninfo)。
### 返回值 [#返回值-19]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-20]
- [LocalSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ilocalspatialaudioengine)
## updateSelfPosition [#updateselfposition]
更新本地用户的空间位置。
```dart
Future updateSelfPosition(
{required List position,
required List axisForward,
required List axisRight,
required List axisUp});
```
- 在 [LocalSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ilocalspatialaudioengine) 类下,该方法需要和 [updateRemotePosition](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 搭配使用。SDK 会根据该方法和 [updateRemotePosition](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 设置的参数计算本地和远端用户之间的相对位置,从而计算用户的空间音频参数。
### 参数 [#参数-17]
在世界坐标系中的坐标。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
在世界坐标系前轴的单位向量。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
在世界坐标系右轴的单位向量。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
在世界坐标系上轴的单位向量。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
### 返回值 [#返回值-20]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-21]
- [BaseSpatialAudioEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ibasespatialaudioengine)