# 空间音频 (/zh-CN/api-reference/rtc/android/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_ibasespatialaudioengine_clearremotepositions"></a>

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

## clearRemotePositions [#clearremotepositions]

移除所有远端用户的空间位置。

<a id="api_ibasespatialaudioengine_clearremotepositions__prototype"></a>

```java
public abstract int clearRemotePositions();
```

<a id="api_ibasespatialaudioengine_clearremotepositions__detailed_desc"></a>

调用该方法后，本地用户将无法再听到任何远端用户的声音。你也可以在离开频道后调用该方法以释放资源。

<a id="api_ibasespatialaudioengine_clearremotepositions__return_values"></a>

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

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

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

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

<a id="api_ilocalspatialaudioengine_create_ilocalspatialaudioengine"></a>

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

## create [#create]

创建一个 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ilocalspatialaudioengine) 实例。

<a id="api_ilocalspatialaudioengine_create_ilocalspatialaudioengine__prototype"></a>

```java
public static synchronized ILocalSpatialAudioEngine create()
```

<a id="api_ilocalspatialaudioengine_create_ilocalspatialaudioengine__detailed_desc"></a>

在调用 [initialize](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_initialize_ilocalspatialaudioengine) 之前调用该方法。

<a id="api_ilocalspatialaudioengine_create_ilocalspatialaudioengine__return_values"></a>

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

方法调用成功，返回 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ilocalspatialaudioengine) 实例。

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

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

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

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

## enableSpatialAudio [#enablespatialaudio]

启用或关闭空间音效。

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

```java
public abstract int enableSpatialAudio(boolean enabled);
```

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

你可以调用 [setRemoteUserSpatialAudioParams](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_irtcengine_setremoteuserspatialaudioparams) 设置远端用户的空间音效参数。

:::note
注：

- 你可以在加入频道前或加入频道后调用此方法。
- 此方法依赖空间音效动态库 libagora_spatial_audio_extension.so。如果该动态库被删除，则无法正常启用该功能。
:::

<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>

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

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/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/android/rtc-interface-class#class_ilocalspatialaudioengine)。

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

```java
public abstract int initialize(LocalSpatialAudioConfig config);
```

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

:::note
注：

- 请在调用 [create](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_create_ilocalspatialaudioengine) 方法后调用此方法。
- 在调用 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ilocalspatialaudioengine) 的其他方法前，必须先调用 [initialize](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_initialize_ilocalspatialaudioengine) 初始化 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ilocalspatialaudioengine)。
- 每个 App 仅支持创建一个 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ilocalspatialaudioengine) 实例。
:::

<a id="api_ilocalspatialaudioengine_initialize_ilocalspatialaudioengine__parameters"></a>

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

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

[ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ilocalspatialaudioengine) 的配置。详见 [LocalSpatialAudioConfig](/zh-CN/api-reference/rtc/android/class-localspatialaudioconfig)。

</Parameter>
</ParameterList>

<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/android/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>

```java
public abstract int muteAllRemoteAudioStreams(boolean mute);
```

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

调用该方法后，本地用户将停止或恢复订阅所有远端用户的音频流，包括后续加入频道的用户。

:::note
注：

- 请在调用 `joinChannel` 方法后调用本方法。
- 使用空间音效时，如需设置是否停止订阅所有远端用户的音频流，声网推荐使用本方法，而非 [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) 下的同名方法。
- 调用本方法后，需要调用 [updateSelfPosition](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 和 [updateRemotePosition](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 方法更新本地用户和远端用户的空间位置，否则本方法的设置不会生效。
:::

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

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

<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/android/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>

```java
public abstract int muteLocalAudioStream(boolean mute);
```

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

:::note
注： [muteLocalAudioStream](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_mutelocalaudiostream_ibasespatialaudioengine) 方法不会影响任何正在进行的音频录制，因为它不会禁用音频采集设备。
请在调用 `joinChannel` 方法之后调用该方法。
使用空间音效时，如果需要设置是否停止发布本地音频流，声网推荐调用该方法，而不是 [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#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) 回调。
:::

<a id="api_ibasespatialaudioengine_mutelocalaudiostream_ibasespatialaudioengine__related"></a>

### 相关回调 [#相关回调]

该方法成功调用后会在远端客户端触发 [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) 回调。

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

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

<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/android/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>

```java
public abstract int muteRemoteAudioStream(int uid, boolean mute);
```

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

:::note
注：

- 请在调用 `joinChannel` 方法后调用此方法。
- 使用空间音效时，如需设置是否停止订阅指定用户的音频流，声网推荐调用此方法，而非 [muteRemoteAudioStream](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_muteremoteaudiostream_ibasespatialaudioengine) 方法。
:::

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

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

<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/android/rtc-interface-class#class_ibasespatialaudioengine)

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

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

## destroy [#destroy]

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

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

```java
public static synchronized void destroy()
```

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

调用该方法后，将无法再使用 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ilocalspatialaudioengine) 下的任何 API。如需再次使用空间音效功能，需等待 [destroy](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_release_ilocalspatialaudioengine) 方法执行完成后，再调用 [initialize](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_initialize_ilocalspatialaudioengine) 创建新的 [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ilocalspatialaudioengine) 实例。

:::note
注： 请在调用 [destroy](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_release_ilocalspatialaudioengine) 方法之前调用此方法。
:::

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

- [ILocalSpatialAudioEngine](/zh-CN/api-reference/rtc/android/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>

```java
public abstract int removeRemotePosition(int uid);
```

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

调用该方法成功后，你将不再听到指定远端用户的声音。离开频道后，为避免浪费计算资源，建议调用该方法移除指定远端用户的空间位置信息。否则，该用户的空间位置信息将持续保留。当远端用户数量超过通过 [setMaxAudioRecvCount](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setmaxaudiorecvcount) 设置的可接收音频流数量时，系统会根据相对距离自动取消订阅距离最远用户的音频流。

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

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

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

`uid`。该参数必须与用户加入频道时传入的用户 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/android/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>

```java
public abstract int setAudioRecvRange(float range);
```

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

你可以在任意时间调用该方法以更新音频接收范围。设置成功后，本地用户只能接收设定范围内或同一队伍中远端用户的音频。

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

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

<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/android/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>

```java
public abstract int setDistanceUnit(float unit);
```

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

在声网的空间音效算法中，距离以米为单位进行计算。SDK 默认将游戏引擎中的每个单位距离转换为 1 米。你可以调用该方法将游戏引擎中的每个单位距离转换为指定的米数。

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

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

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

游戏引擎中每个单位距离对应的米数。该参数必须大于 0.00，默认值为 1.00。例如，将该参数设置为 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/android/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>

```java
public abstract int setHeadphoneEQParameters(int lowGain, int highGain);
```

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

如果调用 [setHeadphoneEQPreset](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 后未达到预期效果，可以调用 [setHeadphoneEQParameters](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) 进一步调整耳机均衡器的低频和高频参数。

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

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

<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：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -1：发生通用错误。

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/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>

```java
public abstract int setHeadphoneEQPreset(int preset);
```

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

该方法主要用于空间音效场景中。你可以选择预设的耳机均衡器来聆听音频，以实现预期的音频体验。

:::note
注： 如果你使用的耳机本身已经具有良好的均衡效果，调用该方法可能不会带来显著提升，甚至可能降低体验。
:::

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

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

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

预设的耳机均衡器效果：

- `HEADPHONE_EQUALIZER_OFF`：关闭耳机均衡器，听到原始音频。
- `HEADPHONE_EQUALIZER_OVEREAR`：为头戴式耳机使用均衡器。
- `HEADPHONE_EQUALIZER_INEAR`：为入耳式耳机使用均衡器。

</Parameter>
</ParameterList>

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

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

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

  - -1：发生通用错误（无具体原因）。

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/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>

```java
public abstract int setMaxAudioRecvCount(int maxCount);
```

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

如果可接收的音频流数量超过该设置值，本地用户将接收距离其最近的 `maxCount` 条音频流。

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

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

<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/android/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>

```java
public abstract int setPlayerAttenuation(int playerId, double attenuation, boolean forceSet);
```

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

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

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

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

媒体播放器的 ID。你可以通过调用 [getMediaPlayerId](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-info#api_imediaplayer_getmediaplayerid) 获取该 ID。

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

远端用户或媒体播放器的声音衰减系数，取值范围为 [0,1]。具体说明如下：

- 0：广播模式，音量和音色不随距离衰减，本地用户听到的音量和音色不会因距离变化而变化。
- (0, 0.5)：弱衰减模式，音量和音色在传播过程中仅有轻微衰减，声音传播距离比真实环境更远。
- 0.5：（默认）模拟真实环境中的音量衰减效果，等效于未设置 `speaker_attenuation` 参数。
- (0.5, 1]：强衰减模式，音量和音色在传播过程中迅速衰减。

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

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

- true：强制使用 `attenuation` 设置媒体播放器的衰减效果，此时 [SpatialAudioZone](/zh-CN/api-reference/rtc/android/class-spatialaudiozone) 中 `audioAttenuation` 设置的隔音区衰减系数对媒体播放器无效。
- false：不强制使用 `attenuation` 设置媒体播放器的声音衰减效果，具体如下：

  - 如果声源和听众分别位于隔音区内外，声音衰减效果由 [SpatialAudioZone](/zh-CN/api-reference/rtc/android/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/android/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>

```java
public abstract int setRemoteAudioAttenuation(int uid, double attenuation, boolean forceSet);
```

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

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

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

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

用户 ID。该参数必须与用户加入频道时传入的用户 ID 相同。

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

用户的声音衰减系数，取值范围为 [0, 1]。具体取值说明如下：

- 0：广播模式，音量和音色不会随距离衰减，本地用户听到的音量和音色不会因距离变化。
- (0, 0.5)：弱衰减模式，音量和音色在传播过程中仅有轻微衰减，声音传播距离大于真实环境。
- 0.5：（默认）模拟真实环境中的音量衰减效果，等效于未设置 `speaker_attenuation` 参数。
- (0.5, 1]：强衰减模式，音量和音色在传播过程中快速衰减。

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

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

- true：强制使用 `attenuation` 设置用户的声音衰减效果，此时 [SpatialAudioZone](/zh-CN/api-reference/rtc/android/class-spatialaudiozone) 中 `audioAttenuation` 设置的隔音区衰减系数对该用户无效。
- false：不强制使用 `attenuation` 设置用户的声音衰减效果，具体如下：

  - 若声源和接收者分别位于隔音区内外，衰减效果由 [SpatialAudioZone](/zh-CN/api-reference/rtc/android/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/android/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>

```java
public abstract int setRemoteUserSpatialAudioParams(int uid, SpatialAudioParams params);
```

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

在调用 [enableSpatialAudio](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_irtcengine_enablespatialaudio) 后调用此方法。设置成功后，你可以听到具有空间感的远端用户的声音。

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

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

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

用户 ID，必须与该用户加入频道时使用的 ID 相同。

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

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

</Parameter>
</ParameterList>

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

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

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/android/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>

```java
int setSpatialAudioParams(SpatialAudioParams params);
```

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

若需关闭空间音效，请将 `params` 参数设置为 `null`。

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

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

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

媒体播放器的空间音效参数，详见 [SpatialAudioParams](/zh-CN/api-reference/rtc/android/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/android/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>

```java
public abstract int setZones(SpatialAudioZone[] zones);
```

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

在虚拟互动场景中，你可以使用该方法设置隔音区域及声音衰减系数。当声源（可以是用户或媒体播放器）和接收者分别处于隔音区域的内外时，可以体验到类似真实环境中声音遇到建筑隔断时的衰减效果：

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

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

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

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

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

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

</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/android/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>

```java
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>

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

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

媒体播放器的 ID。你可以通过调用 [getMediaPlayerId](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-info#api_imediaplayer_getmediaplayerid) 获取该 ID。

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

媒体播放器的空间位置，详见 [RemoteVoicePositionInfo](/zh-CN/api-reference/rtc/android/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/android/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>

```java
public abstract int updateRemotePosition(int uid, RemoteVoicePositionInfo posInfo);
```

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

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

:::note
注： 请在调用 `joinChannel` 方法后再调用此方法。
:::

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

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

<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/android/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/android/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>

```java
public abstract int updateSelfPosition(float[] position, float[] axisForward, float[] axisRight, float[] axisUp);
```

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

[updateSelfPosition](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 需要与 [updateRemotePosition](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 搭配使用。SDK 会根据该方法和 [updateRemotePosition](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 中的参数设置，计算本地用户与远端用户之间的相对位置，并据此计算空间音效参数。

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

### 参数 [#参数-18]

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

世界坐标系中的坐标。该参数为长度为 3 的数组，三个值依次表示前、右、上的坐标。

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

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

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

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

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

坐标系中 z 轴的单位向量。该参数为长度为 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/android/rtc-interface-class#class_ibasespatialaudioengine)