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

空间音频

  • Flutter

更新时间不可用

clearRemotePositions

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

Dart
Future<void> clearRemotePositions();

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

enableSpatialAudio

开启或关闭空间音频。

Dart
Future<void> enableSpatialAudio(bool enabled);

开启空间音频后，你可以调用 setRemoteUserSpatialAudioParams 设置远端用户的空间音频参数。

注：

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

参数

参数名描述
enabled

是否开启空间音频：

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

getLocalSpatialAudioEngine

获取 LocalSpatialAudioEngine 对象。

Dart
LocalSpatialAudioEngine getLocalSpatialAudioEngine();

注： 该方法需要在初始化 RtcEngine 对象后调用。

返回值

一个 LocalSpatialAudioEngine 对象。

所属接口类

initialize

初始化 LocalSpatialAudioEngine。

Dart
Future<void> initialize();

注：

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

muteAllRemoteAudioStreams

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

Dart
Future<void> muteAllRemoteAudioStreams(bool mute);

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

注：

参数

参数名描述
mute

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

muteLocalAudioStream

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

Dart
Future<void> muteLocalAudioStream(bool mute);

注：

参数

参数名描述
mute

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

muteRemoteAudioStream

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

Dart
Future<void> muteRemoteAudioStream({required int uid, required bool mute});

参数

参数名描述
uid

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

mute

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

release

销毁 BaseSpatialAudioEngine。

Dart
abstract release(): void;

该方法释放 BaseSpatialAudioEngine 下的所有资源。当用户不需要使用空间音频时，你可以调用该方法将资源释放出来用于其他操作。 调用该方法后，你将无法再使用 BaseSpatialAudioEngine 下的任何 API。

所属接口类

removeRemotePosition

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

Dart
Future<void> removeRemotePosition(int uid);

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

参数

参数名描述
uid

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setAudioRecvRange

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

Dart
Future<void> setAudioRecvRange(double range);

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

参数

参数名描述
range

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setDistanceUnit

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

Dart
Future<void> setDistanceUnit(double unit);

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

参数

参数名描述
unit

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setHeadphoneEQParameters

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

Dart
Future<void> setHeadphoneEQParameters(
      {required int lowGain, required int highGain});

在空间音频场景下，如果在调用 setHeadphoneEQPreset 方法使用预设的耳机均衡效果后仍未达到预期，你可以通过调用该方法进一步调节耳机均衡效果。

参数

参数名描述
lowGain

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

highGain

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setHeadphoneEQPreset

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

Dart
Future<void> setHeadphoneEQPreset(HeadphoneEqualizerPreset preset);

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

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

参数

参数名描述
preset

预设的耳机均衡效果。详见 HeadphoneEqualizerPreset。

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setMaxAudioRecvCount

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

Dart
Future<void> setMaxAudioRecvCount(int maxCount);

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

参数

参数名描述
maxCount

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setPlayerAttenuation

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

Dart
Future<void> setPlayerAttenuation(
      {required int playerId,
      required double attenuation,
      required bool forceSet});

参数

参数名描述
playerId

媒体播放器 ID。

attenuation

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

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

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

  • true：强制使用 attenuation 设置媒体播放器的声音衰减效果，此时 SpatialAudioZone 中的 audioAttenuation 中设置的隔声区域衰减系数对媒体播放器不生效。

  • false：不强制使用 attenuation 设置媒体播放器的声音衰减效果，分为以下两种情况。

    • 如果音源和听声者分属于隔声区域内部和外部，则声音衰减效果由 SpatialAudioZone 中的 audioAttenuation 决定。
    • 如果音源和听声者在同一个隔声区域内或同在隔声区域外，则声音衰减效果由该方法中的 attenuation 决定。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setRemoteAudioAttenuation

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

Dart
Future<void> setRemoteAudioAttenuation(
      {required int uid, required double attenuation, required bool forceSet});

参数

参数名描述
uid

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

attenuation

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

forceSet

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

  • true：强制使用 attenuation 设置该用户的声音衰减效果，此时 SpatialAudioZone 中的 audioAttenuation 中设置的隔声区域衰减系数对该用户不生效。

  • false：不强制使用 attenuation设置用户的声音衰减效果，分为以下两种情况。

    • 如果音源和听声者分属于隔声区域内部和外部，则声音衰减效果由 SpatialAudioZone 中的 audioAttenuation 决定。
    • 如果音源和听声者在同一个隔声区域内或同在隔声区域外，则声音衰减效果由该方法中的 attenuation 决定。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setRemoteUserSpatialAudioParams

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

Dart
Future<void> setRemoteUserSpatialAudioParams(
    {required int uid, required SpatialAudioParams params});

该方法需要在 enableSpatialAudio 后调用。成功设置远端用户的空间音频参数后，本地用户听远端用户会有空间感。

参数

参数名描述
uid

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

params

空间音频参数。详见 SpatialAudioParams。

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setSpatialAudioParams

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

Dart
Future<void> setSpatialAudioParams(SpatialAudioParams params);

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

参数

参数名描述
params

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setZones

设置隔声区域。

Dart
Future<void> setZones(
      {required SpatialAudioZone zones, required int zoneCount});

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

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

参数

参数名描述
zones

隔声区域的设置。详见 SpatialAudioZone。当你将该参数设置为 NULL 时，表示清除所有隔声区域。

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

zoneCount

隔声区域的数量。

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

updatePlayerPositionInfo

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

Dart
Future<void> updatePlayerPositionInfo(
      {required int playerId, required RemoteVoicePositionInfo positionInfo});

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

调用时机

加入频道前后均可调用。

参数

参数名描述
playerId

媒体播放器 ID。

positionInfo

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

updateRemotePosition

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

Dart
Future<void> updateRemotePosition(
      {required int uid, required RemoteVoicePositionInfo posInfo});

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

注： 该方法需要在 joinChannel 后调用。

参数

参数名描述
uid

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

posInfo

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

updateSelfPosition

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

Dart
Future<void> updateSelfPosition(
      {required List<double> position,
      required List<double> axisForward,
      required List<double> axisRight,
      required List<double> axisUp});

参数

参数名描述
position

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

axisForward

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

axisRight

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

axisUp

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利