空间音频

clearRemotePositions

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

Java

public abstract int clearRemotePositions();

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

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

create

创建一个 ILocalSpatialAudioEngine 实例。

Java

public static synchronized ILocalSpatialAudioEngine create()

在调用 initialize 之前调用该方法。

返回值

方法调用成功，返回 ILocalSpatialAudioEngine 实例。

所属接口类

• ILocalSpatialAudioEngine

enableSpatialAudio

启用或关闭空间音效。

Java

public abstract int enableSpatialAudio(boolean enabled);

你可以调用 setRemoteUserSpatialAudioParams 设置远端用户的空间音效参数。

信息

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

参数

enabled

是否启用空间音效：

• true：启用空间音效。
• false：关闭空间音效。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

initialize

初始化 ILocalSpatialAudioEngine。

Java

public abstract int initialize(LocalSpatialAudioConfig config);

信息

• 请在调用 create 方法后调用此方法。
• 在调用 ILocalSpatialAudioEngine 的其他方法前，必须先调用 initialize 初始化 ILocalSpatialAudioEngine。
• 每个 App 仅支持创建一个 ILocalSpatialAudioEngine 实例。

参数

config

ILocalSpatialAudioEngine 的配置。详见 LocalSpatialAudioConfig。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• ILocalSpatialAudioEngine

muteAllRemoteAudioStreams

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

Java

public abstract int muteAllRemoteAudioStreams(boolean mute);

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

信息

• 请在调用 joinChannel 方法后调用本方法。
• 使用空间音效时，如需设置是否停止订阅所有远端用户的音频流，声网推荐使用本方法，而非 RtcEngine 下的同名方法。
• 调用本方法后，需要调用 updateSelfPosition 和 updateRemotePosition 方法更新本地用户和远端用户的空间位置，否则本方法的设置不会生效。

参数

mute

是否停止订阅所有远端用户的音频流：

• true：停止订阅所有远端用户的音频流。
• false：订阅所有远端用户的音频流。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

muteLocalAudioStream

停止或恢复发布本地音频流。

Java

public abstract int muteLocalAudioStream(boolean mute);

信息

muteLocalAudioStream 方法不会影响任何正在进行的音频录制，因为它不会禁用音频采集设备。 请在调用 joinChannel 方法之后调用该方法。 使用空间音效时，如果需要设置是否停止发布本地音频流，声网推荐调用该方法，而不是 RtcEngine 下的同名方法。 该方法成功调用后会在远端客户端触发 onUserMuteAudio 和 onRemoteAudioStateChanged 回调。

相关回调

该方法成功调用后会在远端客户端触发 onUserMuteAudio 和 onRemoteAudioStateChanged 回调。

参数

mute

是否停止发布本地音频流：

• true：停止发布本地音频流。
• false：发布本地音频流。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

muteRemoteAudioStream

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

Java

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

信息

• 请在调用 joinChannel 方法后调用此方法。
• 使用空间音效时，如需设置是否停止订阅指定用户的音频流，声网推荐调用此方法，而非 muteRemoteAudioStream 方法。

参数

uid

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

mute

是否订阅指定远端用户的音频流：

• true：停止订阅指定用户的音频流。
• false：（默认）订阅指定用户的音频流。SDK 会根据本地用户与远端用户之间的距离决定是否订阅。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

destroy

销毁 ILocalSpatialAudioEngine 实例。

Java

public static synchronized void destroy()

调用该方法后，将无法再使用 ILocalSpatialAudioEngine 下的任何 API。如需再次使用空间音效功能，需等待 destroy 方法执行完成后，再调用 initialize 创建新的 ILocalSpatialAudioEngine 实例。

信息

请在调用 destroy 方法之前调用此方法。

所属接口类

• ILocalSpatialAudioEngine

removeRemotePosition

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

Java

public abstract int removeRemotePosition(int uid);

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

参数

uid

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

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• ILocalSpatialAudioEngine

setAudioRecvRange

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

Java

public abstract int setAudioRecvRange(float range);

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

参数

range

最大音频接收范围，单位为米。该参数必须大于 0。（默认值为 20）

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

setDistanceUnit

设置游戏引擎中每个单位距离对应的米数。

Java

public abstract int setDistanceUnit(float unit);

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

参数

unit

游戏引擎中每个单位距离对应的米数。该参数必须大于 0.00，默认值为 1.00。例如，将该参数设置为 2.00 表示游戏引擎中每个单位距离等于 2 米。该值越大，当远端用户远离本地用户时，本地用户听到的声音衰减得越快。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

setHeadphoneEQParameters

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

Java

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

如果调用 setHeadphoneEQPreset 后未达到预期效果，可以调用 setHeadphoneEQParameters 进一步调整耳机均衡器的低频和高频参数。

参数

lowGain

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

highGain

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

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -1：发生通用错误。

所属接口类

• RtcEngine

setHeadphoneEQPreset

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

Java

public abstract int setHeadphoneEQPreset(int preset);

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

信息

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

参数

preset

预设的耳机均衡器效果：

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

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -1：发生通用错误（无具体原因）。

所属接口类

• RtcEngine

setMaxAudioRecvCount

设置你在指定音频接收范围内可接收的最大音频流数量。

Java

public abstract int setMaxAudioRecvCount(int maxCount);

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

参数

maxCount

你在指定音频接收范围内可接收的最大音频流数量。该参数的取值应小于或等于 16。（默认值为 10）

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

setPlayerAttenuation

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

Java

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

参数

playerId

媒体播放器的 ID。你可以通过调用 getMediaPlayerId 获取该 ID。

attenuation

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

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

forceSet

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

• true：强制使用 attenuation 设置媒体播放器的衰减效果，此时 SpatialAudioZone 中 audioAttenuation 设置的隔音区衰减系数对媒体播放器无效。
• false：不强制使用 attenuation 设置媒体播放器的声音衰减效果，具体如下：
  • 如果声源和听众分别位于隔音区内外，声音衰减效果由 SpatialAudioZone 中的 audioAttenuation 决定。
  • 如果声源和听众位于同一隔音区内或同一隔音区外，声音衰减效果由本方法中的 attenuation 参数决定。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

setRemoteAudioAttenuation

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

Java

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

参数

uid

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

attenuation

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

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

forceSet

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

• true：强制使用 attenuation 设置用户的声音衰减效果，此时 SpatialAudioZone 中 audioAttenuation 设置的隔音区衰减系数对该用户无效。
• false：不强制使用 attenuation 设置用户的声音衰减效果，具体如下：
  • 若声源和接收者分别位于隔音区内外，衰减效果由 SpatialAudioZone 中的 audioAttenuation 决定；
  • 若声源和接收者位于同一隔音区或同一隔音区外，衰减效果由本方法中的 attenuation 决定。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• ILocalSpatialAudioEngine

setRemoteUserSpatialAudioParams

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

Java

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

在调用 enableSpatialAudio 后调用此方法。设置成功后，你可以听到具有空间感的远端用户的声音。

参数

uid

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

params

空间音效参数。详见 SpatialAudioParams。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

setSpatialAudioParams

启用或关闭媒体播放器的空间音效。

Java

int setSpatialAudioParams(SpatialAudioParams params);

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

参数

params

媒体播放器的空间音效参数，详见 SpatialAudioParams。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMediaPlayer

setZones

设置隔音区域。

Java

public abstract int setZones(SpatialAudioZone[] zones);

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

• 当声源和接收者分别处于隔音区域的内外时，声音的衰减效果由 SpatialAudioZone 中的声音衰减系数决定。
• 如果用户或媒体播放器处于同一个隔音区域内，则声音衰减效果由 setPlayerAttenuation 或 setRemoteAudioAttenuation 中的 attenuation 参数决定。如果你未调用 setPlayerAttenuation 或 setRemoteAudioAttenuation，SDK 默认的声音衰减系数为 0.5，用于模拟真实环境中的声音衰减。
• 如果声源和接收者分别处于两个不同的隔音区域，接收者将无法听到声源。

信息

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

参数

zones

隔音区域设置。当该参数设置为 null 时，表示清除所有隔音区域。详见 SpatialAudioZone。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

updatePlayerPositionInfo

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

Java

public abstract int updatePlayerPositionInfo(int playerId, RemoteVoicePositionInfo positionInfo);

调用该方法后，本地用户可以听到媒体播放器空间位置的变化。

调用时机

该方法可以在加入频道前或加入频道后调用。

参数

playerId

媒体播放器的 ID。你可以通过调用 getMediaPlayerId 获取该 ID。

positionInfo

媒体播放器的空间位置，详见 RemoteVoicePositionInfo。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

updateRemotePosition

更新指定远端用户的空间位置。

Java

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

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

信息

请在调用 joinChannel 方法后再调用此方法。

参数

uid

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

posInfo

远端用户的空间位置。详见 RemoteVoicePositionInfo。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• ILocalSpatialAudioEngine

updateSelfPosition

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

Java

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

updateSelfPosition 需要与 updateRemotePosition 搭配使用。SDK 会根据该方法和 updateRemotePosition 中的参数设置，计算本地用户与远端用户之间的相对位置，并据此计算空间音效参数。

参数

position

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

axisForward

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

axisRight

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

axisUp

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

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine