# 空间音频 (/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="toc_spatial_audio"></a>

<a id="api_ilocalspatialaudioengine_clearremotepositions"></a>

<a id="ariaid-title2"></a>

## ClearRemotePositions [#clearremotepositions]

删除所有远端用户的空间位置信息。

<a id="api_ilocalspatialaudioengine_clearremotepositions__prototype"></a>

```csharp
public abstract int ClearRemotePositions();
```

<a id="api_ilocalspatialaudioengine_clearremotepositions__detailed_desc"></a>

成功调用该方法后，本地用户将听不到所有远端用户。
离开频道后，为避免计算资源的浪费，你也可以调用该方法删除所有远端用户的空间位置信息。

<a id="api_ilocalspatialaudioengine_clearremotepositions__return_values"></a>

### 返回值 [#返回值]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类]

- [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine)

<a id="api_irtcengine_enablespatialaudio"></a>

<a id="ariaid-title3"></a>

## EnableSpatialAudio [#enablespatialaudio]

开启或关闭空间音频。

<a id="api_irtcengine_enablespatialaudio__prototype"></a>

```csharp
public abstract int EnableSpatialAudio(bool enabled);
```

<a id="api_irtcengine_enablespatialaudio__detailed_desc"></a>

开启空间音频后，你可以调用 [SetRemoteUserSpatialAudioParams](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_irtcengine_setremoteuserspatialaudioparams) 设置远端用户的空间音频参数。

:::note
注：

- 该方法在加入频道前后均可调用。
- 该方法依赖于空间音频动态库 `libagora_spatial_audio_extension.dll`，如果删除该动态库会导致无法正常开启该功能。
:::

<a id="api_irtcengine_enablespatialaudio__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="enabled"></a>
<Parameter name="enabled">

是否开启空间音频：

- true: 开启空间音频。
- false: 关闭空间音频。

</Parameter>
</ParameterList>

<a id="api_irtcengine_enablespatialaudio__return_values"></a>

### 返回值 [#返回值-1]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-1]

- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getlocalspatialaudioengine"></a>

<a id="ariaid-title4"></a>

## GetLocalSpatialAudioEngine [#getlocalspatialaudioengine]

获取 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine) 对象。

<a id="api_irtcengine_getlocalspatialaudioengine__prototype"></a>

```csharp
public abstract ILocalSpatialAudioEngine GetLocalSpatialAudioEngine();
```

<a id="api_irtcengine_getlocalspatialaudioengine__detailed_desc"></a>

:::note
注： 该方法需要在初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 对象后调用。
:::

<a id="api_irtcengine_getlocalspatialaudioengine__return_values"></a>

### 返回值 [#返回值-2]

一个 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine) 对象。

### 所属接口类 [#所属接口类-2]

- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)

<a id="api_ilocalspatialaudioengine_initialize_ilocalspatialaudioengine"></a>

<a id="ariaid-title5"></a>

## Initialize [#initialize]

初始化 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine)。

<a id="api_ilocalspatialaudioengine_initialize_ilocalspatialaudioengine__prototype"></a>

```csharp
public abstract int Initialize();
```

<a id="api_ilocalspatialaudioengine_initialize_ilocalspatialaudioengine__detailed_desc"></a>

:::note
注：

- 在调用 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine) 类的其他方法前，你需要先调用该方法初始化 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine)。
- SDK 只支持每个 App 创建一个 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine) 实例。
:::

<a id="api_ilocalspatialaudioengine_initialize_ilocalspatialaudioengine__return_values"></a>

### 返回值 [#返回值-3]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-3]

- [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine)

<a id="api_ibasespatialaudioengine_muteallremoteaudiostreams_ibasespatialaudioengine"></a>

<a id="ariaid-title6"></a>

## MuteAllRemoteAudioStreams [#muteallremoteaudiostreams]

取消或恢复订阅所有远端用户的音频流。

<a id="api_ibasespatialaudioengine_muteallremoteaudiostreams_ibasespatialaudioengine__prototype"></a>

```csharp
public abstract int MuteAllRemoteAudioStreams(bool mute);
```

<a id="api_ibasespatialaudioengine_muteallremoteaudiostreams_ibasespatialaudioengine__detailed_desc"></a>

成功调用该方法后，本地用户会取消或恢复订阅所有远端用户的音频流，包括在调用该方法后加入频道的用户的音频流。

:::note
注：

- 该方法需要在 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2) 后调用。
- 在使用空间音频时，如需设置是否订阅所有远端用户的音频流，建议调用该方法替代 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 的 [MuteAllRemoteAudioStreams](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_muteallremoteaudiostreams_ibasespatialaudioengine) 方法。
- 在调用该方法后，你需要调用 [UpdateSelfPosition](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 和 [UpdateRemotePosition](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 更新本地用户和远端用户的空间位置，否则该方法中的设置不会生效。
:::

<a id="api_ibasespatialaudioengine_muteallremoteaudiostreams_ibasespatialaudioengine__parameters"></a>

### 参数 [#参数-1]

<ParameterList>
<a id="mute"></a>
<Parameter name="mute">

是否取消订阅所有远端用户的音频流：

- true: 取消订阅所有远端用户的音频流。
- false: 订阅所有远端用户的音频流。

</Parameter>
</ParameterList>

<a id="api_ibasespatialaudioengine_muteallremoteaudiostreams_ibasespatialaudioengine__return_values"></a>

### 返回值 [#返回值-4]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-4]

- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ibasespatialaudioengine)

<a id="api_ibasespatialaudioengine_mutelocalaudiostream_ibasespatialaudioengine"></a>

<a id="ariaid-title7"></a>

## MuteLocalAudioStream [#mutelocalaudiostream]

取消或恢复发布本地音频流。

<a id="api_ibasespatialaudioengine_mutelocalaudiostream_ibasespatialaudioengine__prototype"></a>

```csharp
public abstract int MuteLocalAudioStream(bool mute);
```

<a id="api_ibasespatialaudioengine_mutelocalaudiostream_ibasespatialaudioengine__detailed_desc"></a>

:::note
注：

- 该方法不影响音频采集状态，因为没有禁用音频采集设备。
- 该方法需要在 [JoinChannel [1/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel1) 或 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2) 后调用。
- 在使用空间音频时，如需设置是否发布本地音频流，建议调用该方法替代 [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 的 [MuteLocalAudioStream](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_mutelocalaudiostream_ibasespatialaudioengine) 方法。
- 成功调用该方法后，远端会触发 [OnUserMuteAudio](/zh-CN/api-reference/rtc/unity/audio/audio-basic#callback_irtcengineeventhandler_onusermuteaudio) 回调和 [OnRemoteAudioStateChanged](/zh-CN/api-reference/rtc/unity/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostatechanged) 回调。
:::

<a id="api_ibasespatialaudioengine_mutelocalaudiostream_ibasespatialaudioengine__parameters"></a>

### 参数 [#参数-2]

<ParameterList>
<a id="mute-1"></a>
<Parameter name="mute">

是否取消发布本地音频流。

- true: 取消发布本地音频流。
- false: 发布本地音频流。

</Parameter>
</ParameterList>

<a id="api_ibasespatialaudioengine_mutelocalaudiostream_ibasespatialaudioengine__return_values"></a>

### 返回值 [#返回值-5]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-5]

- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ibasespatialaudioengine)

<a id="api_ibasespatialaudioengine_muteremoteaudiostream_ibasespatialaudioengine"></a>

<a id="ariaid-title8"></a>

## MuteRemoteAudioStream [#muteremoteaudiostream]

取消或恢复订阅指定远端用户的音频流。

<a id="api_ibasespatialaudioengine_muteremoteaudiostream_ibasespatialaudioengine__prototype"></a>

```csharp
public abstract int MuteRemoteAudioStream(uint uid, bool mute);
```

<a id="api_ibasespatialaudioengine_muteremoteaudiostream_ibasespatialaudioengine__detailed_desc"></a>

<a id="api_ibasespatialaudioengine_muteremoteaudiostream_ibasespatialaudioengine__parameters"></a>

### 参数 [#参数-3]

<ParameterList>
<a id="uid"></a>
<Parameter name="uid">

用户 ID。需与用户加入频道时填写的用户 ID 一致。

</Parameter>
<a id="mute-2"></a>
<Parameter name="mute">

是否取消订阅指定远端用户的音频流。

- true: 取消订阅指定用户的音频流。
- false:（默认）订阅指定用户的音频流，SDK 根据本地用户和远端用户的距离决定是否订阅。

</Parameter>
</ParameterList>

<a id="api_ibasespatialaudioengine_muteremoteaudiostream_ibasespatialaudioengine__return_values"></a>

### 返回值 [#返回值-6]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-6]

- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ibasespatialaudioengine)

<a id="api_ilocalspatialaudioengine_release_ilocalspatialaudioengine"></a>

<a id="ariaid-title9"></a>

## Dispose [#dispose]

销毁 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine)。

<a id="api_ilocalspatialaudioengine_release_ilocalspatialaudioengine__prototype"></a>

```csharp
public abstract void Dispose();
```

<a id="api_ilocalspatialaudioengine_release_ilocalspatialaudioengine__detailed_desc"></a>

该方法释放 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine) 下的所有资源。当用户不需要使用空间音频时，你可以调用该方法将资源释放出来用于其他操作。
调用该方法后，你将无法再使用 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine) 下的任何 API。如需再次使用空间音频，你需要等 [Dispose](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_release_ilocalspatialaudioengine) 执行结束后再调用 [Initialize](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_initialize_ilocalspatialaudioengine) 创建一个新的 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine)。

### 所属接口类 [#所属接口类-7]

- [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine)

<a id="api_ilocalspatialaudioengine_removeremoteposition"></a>

<a id="ariaid-title10"></a>

## RemoveRemotePosition [#removeremoteposition]

删除指定远端用户的空间位置信息。

<a id="api_ilocalspatialaudioengine_removeremoteposition__prototype"></a>

```csharp
public abstract int RemoveRemotePosition(uint uid);
```

<a id="api_ilocalspatialaudioengine_removeremoteposition__detailed_desc"></a>

成功调用该方法后，本地用户将听不到指定的远端用户。
离开频道后，为避免计算资源的浪费，你需要调用该方法删除指定远端用户的空间位置信息。否则，该用户的空间位置信息会一直被保存。当远端用户人数大于 [SetMaxAudioRecvCount](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setmaxaudiorecvcount) 中设定的可接收音频流数时，会按照相对距离依次自动取消订阅距离最远的用户的音频流。

<a id="api_ilocalspatialaudioengine_removeremoteposition__parameters"></a>

### 参数 [#参数-4]

<ParameterList>
<a id="uid-1"></a>
<Parameter name="uid">

用户 ID。需与用户加入频道时填写的用户 ID 一致。

</Parameter>
</ParameterList>

<a id="api_ilocalspatialaudioengine_removeremoteposition__return_values"></a>

### 返回值 [#返回值-7]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-8]

- [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine)

<a id="api_ibasespatialaudioengine_setaudiorecvrange"></a>

<a id="ariaid-title11"></a>

## SetAudioRecvRange [#setaudiorecvrange]

设置本地用户的音频接收范围。

<a id="api_ibasespatialaudioengine_setaudiorecvrange__prototype"></a>

```csharp
public abstract int SetAudioRecvRange(float range);
```

<a id="api_ibasespatialaudioengine_setaudiorecvrange__detailed_desc"></a>

设置成功后，用户只能听见设置范围内或属于同一队伍的远端用户。你可以随时调用该方法更新音频的接收范围。

<a id="api_ibasespatialaudioengine_setaudiorecvrange__parameters"></a>

### 参数 [#参数-5]

<ParameterList>
<a id="range"></a>
<Parameter name="range">

可接收音频的最大范围，单位为游戏引擎中的距离单位。该参数取值需大于 0，默认值为 20。

</Parameter>
</ParameterList>

<a id="api_ibasespatialaudioengine_setaudiorecvrange__return_values"></a>

### 返回值 [#返回值-8]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-9]

- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ibasespatialaudioengine)

<a id="api_ibasespatialaudioengine_setdistanceunit"></a>

<a id="ariaid-title12"></a>

## SetDistanceUnit [#setdistanceunit]

设置游戏引擎单位距离的长度（米）。

<a id="api_ibasespatialaudioengine_setdistanceunit__prototype"></a>

```csharp
public abstract int SetDistanceUnit(float unit);
```

<a id="api_ibasespatialaudioengine_setdistanceunit__detailed_desc"></a>

游戏引擎里的距离单位是游戏引擎自定义的，而声网空间音频算法的距离单位为米。默认情况下，SDK 会将每单位的游戏引擎距离换算为一米。你可以调用该方法，将游戏引擎里的单位距离换算为指定的米数。

<a id="api_ibasespatialaudioengine_setdistanceunit__parameters"></a>

### 参数 [#参数-6]

<ParameterList>
<a id="unit"></a>
<Parameter name="unit">

每单位游戏引擎距离转换后的米数。该参数取值需大于 0.00，默认值为 1.00。例如，将 unit 设为 2.00，表示每单位的游戏引擎距离等于 2 米。
该值越大，当远端用户远离本地用户时，本地用户听到的声音衰减速度越快。

</Parameter>
</ParameterList>

<a id="api_ibasespatialaudioengine_setdistanceunit__return_values"></a>

### 返回值 [#返回值-9]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-10]

- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ibasespatialaudioengine)

<a id="api_irtcengine_setheadphoneeqparameters"></a>

<a id="ariaid-title13"></a>

## SetHeadphoneEQParameters [#setheadphoneeqparameters]

设置耳机均衡器的低频和高频参数。

<a id="api_irtcengine_setheadphoneeqparameters__prototype"></a>

```csharp
public abstract int SetHeadphoneEQParameters(int lowGain, int highGain);
```

<a id="api_irtcengine_setheadphoneeqparameters__detailed_desc"></a>

在空间音频场景下，如果在调用 [SetHeadphoneEQPreset](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 方法使用预设的耳机均衡效果后仍未达到预期，你可以通过调用该方法进一步调节耳机均衡效果。

<a id="api_irtcengine_setheadphoneeqparameters__parameters"></a>

### 参数 [#参数-7]

<ParameterList>
<a id="lowgain"></a>
<Parameter name="lowGain">

耳机均衡器的低频参数。取值范围为 [-10,10]，取值越大，声音越低沉。

</Parameter>
<a id="highgain"></a>
<Parameter name="highGain">

耳机均衡器的高频参数。取值范围为 [-10,10]，取值越大，声音越尖锐。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setheadphoneeqparameters__return_values"></a>

### 返回值 [#返回值-10]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败

  - -1：一般性的错误（未明确归类）。

### 所属接口类 [#所属接口类-11]

- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setheadphoneeqpreset"></a>

<a id="ariaid-title14"></a>

## SetHeadphoneEQPreset [#setheadphoneeqpreset]

设置预设的耳机均衡效果。

<a id="api_irtcengine_setheadphoneeqpreset__prototype"></a>

```csharp
public abstract int SetHeadphoneEQPreset(HEADPHONE_EQUALIZER_PRESET preset);
```

<a id="api_irtcengine_setheadphoneeqpreset__detailed_desc"></a>

该方法主要应用于空间音频场景下，你可以选择预设的耳机均衡器收听音频，以达到预期的音频体验。

:::note
注： 如果你使用的耳机已经具备良好的均衡效果，调用该方法时可能不会获得明显的体验提升效果，甚至可能导致体验下降。
:::

<a id="api_irtcengine_setheadphoneeqpreset__parameters"></a>

### 参数 [#参数-8]

<ParameterList>
<a id="preset"></a>
<Parameter name="preset">

预设的耳机均衡效果。详见 [HEADPHONE_EQUALIZER_PRESET](/zh-CN/api-reference/rtc/unity/enum-headphoneequalizerpreset)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setheadphoneeqpreset__return_values"></a>

### 返回值 [#返回值-11]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败

  - -1：一般性的错误（未明确归类）。

### 所属接口类 [#所属接口类-12]

- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)

<a id="api_ibasespatialaudioengine_setmaxaudiorecvcount"></a>

<a id="ariaid-title15"></a>

## SetMaxAudioRecvCount [#setmaxaudiorecvcount]

设置音频接收范围内最多可接收的音频流数。

<a id="api_ibasespatialaudioengine_setmaxaudiorecvcount__prototype"></a>

```csharp
public abstract int SetMaxAudioRecvCount(int maxCount);
```

<a id="api_ibasespatialaudioengine_setmaxaudiorecvcount__detailed_desc"></a>

如果在音频接收范围内可接收的音频流数超过设置的值，则本地用户会接收音源距离较近的 `maxCount` 路音频。

<a id="api_ibasespatialaudioengine_setmaxaudiorecvcount__parameters"></a>

### 参数 [#参数-9]

<ParameterList>
<a id="maxcount"></a>
<Parameter name="maxCount">

音频接收范围内最多可接收的音频流数。该参数取值需 ≤ 16，默认值为 10。

</Parameter>
</ParameterList>

<a id="api_ibasespatialaudioengine_setmaxaudiorecvcount__return_values"></a>

### 返回值 [#返回值-12]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-13]

- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ibasespatialaudioengine)

<a id="api_ibasespatialaudioengine_setplayerattenuation"></a>

<a id="ariaid-title16"></a>

## SetPlayerAttenuation [#setplayerattenuation]

设置媒体播放器的声音衰减属性。

<a id="api_ibasespatialaudioengine_setplayerattenuation__prototype"></a>

```csharp
public abstract int SetPlayerAttenuation(int playerId, double attenuation, bool forceSet);
```

<a id="api_ibasespatialaudioengine_setplayerattenuation__detailed_desc"></a>

<a id="api_ibasespatialaudioengine_setplayerattenuation__parameters"></a>

### 参数 [#参数-10]

<ParameterList>
<a id="playerid"></a>
<Parameter name="playerId">

媒体播放器 ID。

</Parameter>
<a id="attenuation"></a>
<Parameter name="attenuation">

媒体播放器的声音衰减系数，取值范围为[0,1]。其中：

- 0：广播模式，即音量和音色均不随距离衰减，无论距离远近，本地用户听到的音量和音色都无变化。
- (0,0.5)：弱衰减模式，即音量和音色在传播过程中仅发生微弱衰减，跟真实环境相比，声音可以传播得更远。
- 0.5：（默认）模拟音量在真实环境下的衰减，效果等同于不设置 `attenuation` 参数。
- (0.5,1]：强衰减模式，即音量和音色在传播过程中发生迅速衰减。

</Parameter>
<a id="forceset"></a>
<Parameter name="forceSet">

是否强制设定媒体播放器的声音衰减效果：

- true：强制使用 `attenuation` 设置媒体播放器的声音衰减效果，此时 [SpatialAudioZone](/zh-CN/api-reference/rtc/unity/class-spatialaudiozone) 中的 `audioAttenuation` 中设置的隔声区域衰减系数对媒体播放器不生效。
- false：不强制使用 `attenuation` 设置媒体播放器的声音衰减效果，分为以下两种情况。

  - 如果音源和听声者分属于隔声区域内部和外部，则声音衰减效果由 [SpatialAudioZone](/zh-CN/api-reference/rtc/unity/class-spatialaudiozone) 中的 `audioAttenuation` 决定。
  - 如果音源和听声者在同一个隔声区域内或同在隔声区域外，则声音衰减效果由该方法中的 `attenuation` 决定。

</Parameter>
</ParameterList>

<a id="api_ibasespatialaudioengine_setplayerattenuation__return_values"></a>

### 返回值 [#返回值-13]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-14]

- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ibasespatialaudioengine)

<a id="api_ilocalspatialaudioengine_setremoteaudioattenuation"></a>

<a id="ariaid-title17"></a>

## SetRemoteAudioAttenuation [#setremoteaudioattenuation]

设置指定用户的声音衰减效果。

<a id="api_ilocalspatialaudioengine_setremoteaudioattenuation__prototype"></a>

```csharp
public abstract int SetRemoteAudioAttenuation(uint uid, double attenuation, bool forceSet);
```

<a id="api_ilocalspatialaudioengine_setremoteaudioattenuation__detailed_desc"></a>

<a id="api_ilocalspatialaudioengine_setremoteaudioattenuation__parameters"></a>

### 参数 [#参数-11]

<ParameterList>
<a id="uid-2"></a>
<Parameter name="uid">

用户 ID。需与用户加入频道时填写的用户 ID 一致。

</Parameter>
<a id="attenuation-1"></a>
<Parameter name="attenuation">

针对该用户的声音衰减系数，取值范围为[0,1]。其中：

</Parameter>
<a id="forceset-1"></a>
<Parameter name="forceSet">

是否强制设定该用户的声音衰减效果：

- true：强制使用 `attenuation` 设置该用户的声音衰减效果，此时 [SpatialAudioZone](/zh-CN/api-reference/rtc/unity/class-spatialaudiozone) 中的 `audioAttenuation` 中设置的隔声区域衰减系数对该用户不生效。
- false：不强制使用 `attenuation`设置用户的声音衰减效果，分为以下两种情况。

  - 如果音源和听声者分属于隔声区域内部和外部，则声音衰减效果由 [SpatialAudioZone](/zh-CN/api-reference/rtc/unity/class-spatialaudiozone) 中的 `audioAttenuation` 决定。
  - 如果音源和听声者在同一个隔声区域内或同在隔声区域外，则声音衰减效果由该方法中的 `attenuation` 决定。

</Parameter>
</ParameterList>

<a id="api_ilocalspatialaudioengine_setremoteaudioattenuation__return_values"></a>

### 返回值 [#返回值-14]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-15]

- [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine)

<a id="api_irtcengine_setremoteuserspatialaudioparams"></a>

<a id="ariaid-title18"></a>

## SetRemoteUserSpatialAudioParams [#setremoteuserspatialaudioparams]

设置远端用户的空间音频参数。

<a id="api_irtcengine_setremoteuserspatialaudioparams__prototype"></a>

```csharp
public abstract int SetRemoteUserSpatialAudioParams(uint uid, SpatialAudioParams param);
```

<a id="api_irtcengine_setremoteuserspatialaudioparams__detailed_desc"></a>

该方法需要在 [EnableSpatialAudio](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_irtcengine_enablespatialaudio) 后调用。成功设置远端用户的空间音频参数后，本地用户听远端用户会有空间感。

<a id="api_irtcengine_setremoteuserspatialaudioparams__parameters"></a>

### 参数 [#参数-12]

<ParameterList>
<a id="uid-3"></a>
<Parameter name="uid">

用户 ID。需与用户加入频道时填写的用户 ID 一致。

</Parameter>
<a id="param"></a>
<Parameter name="param">

空间音频参数。详见 [SpatialAudioParams](/zh-CN/api-reference/rtc/unity/class-spatialaudioparams)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setremoteuserspatialaudioparams__return_values"></a>

### 返回值 [#返回值-15]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-16]

- [IRtcEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine)

<a id="api_imediaplayer_setspatialaudioparams"></a>

<a id="ariaid-title19"></a>

## SetSpatialAudioParams [#setspatialaudioparams]

开启或关闭媒体播放器的空间音频。

<a id="api_imediaplayer_setspatialaudioparams__prototype"></a>

```csharp
public abstract int SetSpatialAudioParams(SpatialAudioParams spatial_audio_params);
```

<a id="api_imediaplayer_setspatialaudioparams__detailed_desc"></a>

成功设置媒体播放器的空间音频参数后，SDK 会开启媒体播放器的空间音频，即本地用户听媒体资源会有空间感。
如果需关闭媒体播放器的空间音频，你需要将 `params` 参数设为空。

<a id="api_imediaplayer_setspatialaudioparams__parameters"></a>

### 参数 [#参数-13]

<ParameterList>
<a id="spatial_audio_params"></a>
<Parameter name="spatial_audio_params">

媒体播放器的空间音频参数。详见 [SpatialAudioParams](/zh-CN/api-reference/rtc/unity/class-spatialaudioparams)。

</Parameter>
</ParameterList>

<a id="api_imediaplayer_setspatialaudioparams__return_values"></a>

### 返回值 [#返回值-16]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-17]

- [IMediaPlayer](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imediaplayer)

<a id="api_ibasespatialaudioengine_setzones"></a>

<a id="ariaid-title20"></a>

## SetZones [#setzones]

设置隔声区域。

<a id="api_ibasespatialaudioengine_setzones__prototype"></a>

```csharp
public abstract int SetZones(SpatialAudioZone[] zones, uint zoneCount);
```

<a id="api_ibasespatialaudioengine_setzones__detailed_desc"></a>

在虚拟互动场景下，你可以通过该方法设置隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟听声者分属于隔声区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。

- 当音源跟听声者分属于隔声区域内部和外部时，声音的衰减效果由 [SpatialAudioZone](/zh-CN/api-reference/rtc/unity/class-spatialaudiozone) 中的声音衰减系数决定。
- 如果用户或媒体播放器同在一个隔声区域内，则不受 [SpatialAudioZone](/zh-CN/api-reference/rtc/unity/class-spatialaudiozone) 的影响，声音的衰减效果由 [SetPlayerAttenuation](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) 或 [SetRemoteAudioAttenuation](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) 中的 `attenuation` 参数决定。如果不调用 [SetPlayerAttenuation](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) 或 [SetRemoteAudioAttenuation](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation)，则 SDK 默认声音的衰减系数为 0.5，即模拟声音在真实环境下的衰减。
- 如果音源跟接收者分别属于两个隔声区域，则接收者无法听到音源。

:::note
注： 如果多次调用该方法，以最后一次设置的隔声区域为准。
:::

<a id="api_ibasespatialaudioengine_setzones__parameters"></a>

### 参数 [#参数-14]

<ParameterList>
<a id="zones"></a>
<Parameter name="zones">

隔声区域的设置。详见 [SpatialAudioZone](/zh-CN/api-reference/rtc/unity/class-spatialaudiozone)。当你将该参数设置为 `NULL` 时，表示清除所有隔声区域。

:::note
注： 在 Windows 平台上，需确保 `zones` 数组中的成员个数与 `zoneCount` 的值相等，否则会导致崩溃。
:::

</Parameter>
<a id="zonecount"></a>
<Parameter name="zoneCount">

隔声区域的数量。

</Parameter>
</ParameterList>

<a id="api_ibasespatialaudioengine_setzones__return_values"></a>

### 返回值 [#返回值-17]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-18]

- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ibasespatialaudioengine)

<a id="api_ibasespatialaudioengine_updateplayerpositioninfo"></a>

<a id="ariaid-title21"></a>

## UpdatePlayerPositionInfo [#updateplayerpositioninfo]

更新媒体播放器的空间位置。

<a id="api_ibasespatialaudioengine_updateplayerpositioninfo__prototype"></a>

```csharp
public abstract int UpdatePlayerPositionInfo(int playerId, RemoteVoicePositionInfo positionInfo);
```

<a id="api_ibasespatialaudioengine_updateplayerpositioninfo__detailed_desc"></a>

成功更新后，本地用户可以听到媒体播放器空间位置的变化。

<a id="api_ibasespatialaudioengine_updateplayerpositioninfo__timing"></a>

### 调用时机 [#调用时机]

加入频道前后均可调用。

<a id="api_ibasespatialaudioengine_updateplayerpositioninfo__parameters"></a>

### 参数 [#参数-15]

<ParameterList>
<a id="playerid-1"></a>
<Parameter name="playerId">

媒体播放器 ID。

</Parameter>
<a id="positioninfo"></a>
<Parameter name="positionInfo">

媒体播放器的空间位置信息。详见 [RemoteVoicePositionInfo](/zh-CN/api-reference/rtc/unity/class-remotevoicepositioninfo)。

</Parameter>
</ParameterList>

<a id="api_ibasespatialaudioengine_updateplayerpositioninfo__return_values"></a>

### 返回值 [#返回值-18]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-19]

- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ibasespatialaudioengine)

<a id="api_ilocalspatialaudioengine_updateremoteposition"></a>

<a id="ariaid-title22"></a>

## UpdateRemotePosition [#updateremoteposition]

更新远端用户的空间位置信息。

<a id="api_ilocalspatialaudioengine_updateremoteposition__prototype"></a>

```csharp
public abstract int UpdateRemotePosition(uint uid, RemoteVoicePositionInfo posInfo);
```

<a id="api_ilocalspatialaudioengine_updateremoteposition__detailed_desc"></a>

成功调用该方法后，SDK 会根据本地和远端用户的相对位置计算空间音频参数。

:::note
注： 该方法需要在 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2) 后调用。
:::

<a id="api_ilocalspatialaudioengine_updateremoteposition__parameters"></a>

### 参数 [#参数-16]

<ParameterList>
<a id="uid-4"></a>
<Parameter name="uid">

用户 ID。需与用户加入频道时填写的用户 ID 一致。

</Parameter>
<a id="posinfo"></a>
<Parameter name="posInfo">

远端用户的空间位置信息。详见 [RemoteVoicePositionInfo](/zh-CN/api-reference/rtc/unity/class-remotevoicepositioninfo)。

</Parameter>
</ParameterList>

<a id="api_ilocalspatialaudioengine_updateremoteposition__return_values"></a>

### 返回值 [#返回值-19]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-20]

- [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine)

<a id="api_ibasespatialaudioengine_updateselfposition"></a>

<a id="ariaid-title23"></a>

## UpdateSelfPosition [#updateselfposition]

更新本地用户的空间位置。

<a id="api_ibasespatialaudioengine_updateselfposition__prototype"></a>

```csharp
public abstract int UpdateSelfPosition(float[] position, float[] axisForward, float[] axisRight, float[] axisUp);
```

<a id="api_ibasespatialaudioengine_updateselfposition__detailed_desc"></a>

- 在 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine) 类下，该方法需要和 [UpdateRemotePosition](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 搭配使用。SDK 会根据该方法和 [UpdateRemotePosition](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 设置的参数计算本地和远端用户之间的相对位置，从而计算用户的空间音频参数。

<a id="api_ibasespatialaudioengine_updateselfposition__parameters"></a>

### 参数 [#参数-17]

<ParameterList>
<a id="position"></a>
<Parameter name="position">

在世界坐标系中的坐标。该参数是长度为 3 的数组，三个值依次表示前、右、上的坐标值。前、右、上分别对应 Unity Vector3 的 z、x、y 轴的正方向。

</Parameter>
<a id="axisforward"></a>
<Parameter name="axisForward">

在世界坐标系前轴的单位向量。该参数是长度为 3 的数组，三个值依次表示前、右、上的坐标值。前、右、上分别对应 Unity Vector3 的 z、x、y 轴的正方向。

</Parameter>
<a id="axisright"></a>
<Parameter name="axisRight">

在世界坐标系右轴的单位向量。该参数是长度为 3 的数组，三个值依次表示前、右、上的坐标值。

</Parameter>
<a id="axisup"></a>
<Parameter name="axisUp">

在世界坐标系上轴的单位向量。该参数是长度为 3 的数组，三个值依次表示前、右、上的坐标值。

</Parameter>
</ParameterList>

<a id="api_ibasespatialaudioengine_updateselfposition__return_values"></a>

### 返回值 [#返回值-20]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-21]

- [IBaseSpatialAudioEngine](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ibasespatialaudioengine)