需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

空间音频

  • Android

更新时间不可用

clearRemotePositions

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

Java
public abstract int clearRemotePositions();

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

返回值

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

所属接口类

create

创建一个 ILocalSpatialAudioEngine 实例。

Java
public static synchronized ILocalSpatialAudioEngine create()

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

返回值

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

所属接口类

enableSpatialAudio

启用或关闭空间音效。

Java
public abstract int enableSpatialAudio(boolean enabled);

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

注：

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

参数

参数名描述
enabled

是否启用空间音效：

  • true：启用空间音效。
  • false：关闭空间音效。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

initialize

初始化 ILocalSpatialAudioEngine。

Java
public abstract int initialize(LocalSpatialAudioConfig config);

注：

参数

参数名描述
config

ILocalSpatialAudioEngine 的配置。详见 LocalSpatialAudioConfig。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

muteAllRemoteAudioStreams

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

Java
public abstract int muteAllRemoteAudioStreams(boolean mute);

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

注：

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

参数

参数名描述
mute

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

  • true：停止订阅所有远端用户的音频流。
  • false：订阅所有远端用户的音频流。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

muteLocalAudioStream

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

Java
public abstract int muteLocalAudioStream(boolean mute);

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

相关回调

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

参数

参数名描述
mute

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

  • true：停止发布本地音频流。
  • false：发布本地音频流。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

muteRemoteAudioStream

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

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

注：

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

参数

参数名描述
uid

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

mute

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

  • true：停止订阅指定用户的音频流。
  • false：（默认）订阅指定用户的音频流。SDK 会根据本地用户与远端用户之间的距离决定是否订阅。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

destroy

销毁 ILocalSpatialAudioEngine 实例。

Java
public static synchronized void destroy()

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

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

所属接口类

removeRemotePosition

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

Java
public abstract int removeRemotePosition(int uid);

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

参数

参数名描述
uid

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setAudioRecvRange

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

Java
public abstract int setAudioRecvRange(float range);

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

参数

参数名描述
range

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setDistanceUnit

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

Java
public abstract int setDistanceUnit(float unit);

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

参数

参数名描述
unit

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setHeadphoneEQParameters

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

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

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

参数

参数名描述
lowGain

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

highGain

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。

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

    • -1：发生通用错误。

所属接口类

setHeadphoneEQPreset

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

Java
public abstract int setHeadphoneEQPreset(int preset);

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

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

参数

参数名描述
preset

预设的耳机均衡器效果：

  • HEADPHONE_EQUALIZER_OFF：关闭耳机均衡器，听到原始音频。
  • HEADPHONE_EQUALIZER_OVEREAR：为头戴式耳机使用均衡器。
  • HEADPHONE_EQUALIZER_INEAR：为入耳式耳机使用均衡器。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。

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

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

所属接口类

setMaxAudioRecvCount

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

Java
public abstract int setMaxAudioRecvCount(int maxCount);

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

参数

参数名描述
maxCount

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

setRemoteUserSpatialAudioParams

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

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

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

参数

参数名描述
uid

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

params

空间音效参数。详见 SpatialAudioParams。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setSpatialAudioParams

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

Java
int setSpatialAudioParams(SpatialAudioParams params);

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

参数

参数名描述
params

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setZones

设置隔音区域。

Java
public abstract int setZones(SpatialAudioZone[] zones);

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

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

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

参数

参数名描述
zones

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

updatePlayerPositionInfo

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

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

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

调用时机

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

参数

参数名描述
playerId

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

positionInfo

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

updateRemotePosition

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

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

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

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

参数

参数名描述
uid

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

posInfo

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利