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

空间音频

  • iOS

更新时间不可用

clearRemotePositions:

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

Objective-C
- (int)clearRemotePositions NS_SWIFT_NAME(clearRemotePositions());

调用该方法后，你将无法再听到任何远端用户的声音。离开频道后，为避免资源浪费，也可以调用该方法。

返回值

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

所属接口类

enableSpatialAudio:

启用或关闭空间音效。

Objective-C
- (int)enableSpatialAudio:(BOOL)enabled NS_SWIFT_NAME(enableSpatialAudio(_:));

你可以在加入频道前或加入频道后调用该方法。启用空间音效后，可以调用 setRemoteUserSpatialAudioParams:params: 设置远端用户的空间音效参数。

注：

  • 该方法依赖空间音效动态库 AgoraSpatialAudioExtension.xcframework（iOS）或 AgoraSpatialAudioExtension.framework（macOS）。如果该动态库被删除，该功能将无法正常启用。

参数

参数名描述
enabled

是否启用空间音效：

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

返回值

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

所属接口类

sharedLocalSpatialAudioWithConfig:

初始化 AgoraLocalSpatialAudioKit 实例。

Objective-C
+ (instancetype _Nonnull)sharedLocalSpatialAudioWithConfig:(AgoraLocalSpatialAudioConfig*)config NS_SWIFT_NAME(sharedLocalSpatialAudio(with:));

注： 在调用 AgoraLocalSpatialAudioKit 的其他方法前，你必须先调用 sharedLocalSpatialAudioWithConfig: 方法初始化 AgoraLocalSpatialAudioKit 实例。

参数

参数名描述
config

AgoraLocalSpatialAudioKit 的配置。详见 AgoraLocalSpatialAudioConfig。

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

返回值

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

所属接口类

muteAllRemoteAudioStreams:

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

Objective-C
- (int)muteAllRemoteAudioStreams:(BOOL)mute NS_SWIFT_NAME(muteAllRemoteAudioStreams(_:));

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

注：

  • 请在调用 joinChannelByToken 方法后再调用此方法。
  • 使用空间音效时，如需设置是否停止订阅所有远端用户的音频流，声网建议调用此方法，而非 muteAllRemoteAudioStreams: 方法。
  • 调用此方法后，你需要调用 updateSelfPosition 和 updateRemotePosition 方法更新本地用户和远端用户的空间位置，否则该方法的设置不会生效。

参数

参数名描述
mute

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

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

返回值

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

所属接口类

muteLocalAudioStream:

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

Objective-C
- (int)muteLocalAudioStream:(BOOL)mute NS_SWIFT_NAME(muteLocalAudioStream(_:));

你可以通过该方法停止或恢复发布本地音频流。

该方法不会影响任何正在进行的音频录制，因为它不会禁用音频采集设备。 使用空间音效时，如果你需要设置是否停止订阅指定用户的音频流，声网推荐你调用该方法，而不是 AgoraRtcEngine 下的同名方法。

调用时机

请在加入频道后调用该方法。

相关回调

该方法成功调用后会触发远端的 rtcEngine:didAudioMuted:byUid: 和 rtcEngine:remoteAudioStateChangedOfUid:state:reason:elapsed: 回调。

参数

参数名描述
mute

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

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

返回值

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

所属接口类

muteRemoteAudioStream:mute:

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

Objective-C
- (int)muteRemoteAudioStream:(NSUInteger)uid mute:(BOOL)mute NS_SWIFT_NAME(muteRemoteAudioStream(_:mute:));

注： 调用该方法需在 joinChannelByToken:channelId:info:uid:joinSuccess: 或 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 方法之后进行。使用空间音效时，如需设置是否停止订阅指定用户的音频流，声网建议使用此方法，而非 muteRemoteAudioStream:mute: 方法。

参数

参数名描述
uid

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

mute

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

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

返回值

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

所属接口类

destroy

销毁 AgoraLocalSpatialAudioKit 实例。

Objective-C
+ (void)destroy NS_SWIFT_NAME(destroy());

该方法会释放 AgoraLocalSpatialAudioKit 下的所有资源。当你不再需要使用空间音效时，可以调用该方法释放资源。调用该方法后，将无法再使用 AgoraLocalSpatialAudioKit 下的任何 API。如需再次使用空间音效，需等待 destroy 方法执行完成后，再调用 sharedLocalSpatialAudioWithConfig: 创建新的 AgoraLocalSpatialAudioKit 实例。

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

所属接口类

removeRemotePosition:

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

Objective-C
- (int)removeRemotePosition:(NSUInteger)uid NS_SWIFT_NAME(removeRemotePosition(_:));

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

参数

参数名描述
uid

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

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

返回值

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

所属接口类

setAudioRecvRange:

设置你可接收的音频范围。

Objective-C
- (int)setAudioRecvRange:(float)range NS_SWIFT_NAME(setAudioRecvRange(_:));

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

参数

参数名描述
range

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

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

返回值

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

所属接口类

setDistanceUnit:

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

Objective-C
- (int)setDistanceUnit:(float)unit NS_SWIFT_NAME(setDistanceUnit(_:));

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

参数

参数名描述
unit

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

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

返回值

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

所属接口类

setHeadphoneEQParameters:highGain:

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

Objective-C
- (int)setHeadphoneEQParameters:(int)lowGain highGain:(int)highGain NS_SWIFT_NAME(setHeadphoneEQParameters(_:highGain:));

如果你调用 setHeadphoneEQPreset: 方法后未达到预设的耳机均衡效果，可以通过调用该方法进一步调整耳机均衡效果。

参数

参数名描述
lowGain

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

highGain

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

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

返回值

  • 0：方法调用成功。

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

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

所属接口类

setHeadphoneEQPreset:

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

Objective-C
- (int)setHeadphoneEQPreset:(AgoraHeadphoneEQPreset)preset NS_SWIFT_NAME(setHeadphoneEQPreset(_:));

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

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

参数

参数名描述
preset

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

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

返回值

  • 0：方法调用成功。

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

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

所属接口类

setMaxAudioRecvCount:

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

Objective-C
- (int)setMaxAudioRecvCount:(NSUInteger)maxCount NS_SWIFT_NAME(setMaxAudioRecvCount(_:));

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

参数

参数名描述
maxCount

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

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

返回值

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

所属接口类

setPlayerAttenuation:playerId:forceSet:

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

Objective-C
- (int)setPlayerAttenuation:(double)attenuation playerId:(NSUInteger)playerId forceSet:(BOOL)forceSet NS_SWIFT_NAME(setPlayerAttenuation(_:playerId:forceSet:));

参数

参数名描述
attenuation

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

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

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

forceSet

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

  • YES：强制使用 attenuation 设置媒体播放器的衰减效果，此时在 AgoraSpatialAudioZone 中通过 audioAttenuation 设置的隔音区衰减系数对媒体播放器无效。

  • NO：不强制使用 attenuation 设置媒体播放器的声音衰减效果，具体如下：

    • 如果声源和听众分别位于隔音区内外，声音衰减效果由 AgoraSpatialAudioZone 中的 audioAttenuation 决定。
    • 如果声源和听众位于同一隔音区内，或都在隔音区外，声音衰减效果由本方法中的 attenuation 参数决定。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setRemoteAudioAttenuation:uid:forceSet:

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

Objective-C
- (int)setRemoteAudioAttenuation:(double)attenuation uid:(NSUInteger)uid forceSet:(BOOL)forceSet NS_SWIFT_NAME(setRemoteAudioAttenuation(_:uid:forceSet:));

参数

参数名描述
attenuation

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

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

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

forceSet

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

  • YES：强制使用 attenuation 设置该用户的声音衰减效果，此时 AgoraSpatialAudioZone 中 audioAttenuation 设置的隔音区衰减系数对该用户无效。

  • NO：不强制使用 attenuation 设置该用户的声音衰减效果，具体如下：

    • 若声源和接收者分别位于隔音区内外，衰减效果由 AgoraSpatialAudioZone 中的 audioAttenuation 决定；
    • 若声源和接收者位于同一隔音区内或同一隔音区外，衰减效果由本方法中的 attenuation 决定。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setRemoteUserSpatialAudioParams:params:

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

Objective-C
- (int)setRemoteUserSpatialAudioParams:(NSUInteger)uid
                                  params:(AgoraSpatialAudioParams* _Nonnull)params NS_SWIFT_NAME(setRemoteUserSpatialAudioParams(_:params:));

调用 enableSpatialAudio: 方法后，使用该方法设置远端用户的空间音效参数。成功设置后，你可以听到具有空间感的远端用户的声音。

参数

参数名描述
uid

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

params

空间音效参数。详见 AgoraSpatialAudioParams。

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

返回值

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

所属接口类

setSpatialAudioParams:

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

Objective-C
- (int)setSpatialAudioParams:(AgoraSpatialAudioParams* _Nonnull)params NS_SWIFT_NAME(setSpatialAudioParams(_:));

成功设置媒体播放器的空间音效参数后，SDK 会为媒体播放器启用空间音效。若需关闭媒体播放器的空间音效，请将 params 参数设为 nil。

参数

参数名描述
params

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

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

返回值

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

所属接口类

setZones:

设置声源隔音区域。

Objective-C
- (int)setZones:(NSArray<AgoraSpatialAudioZone*> * _Nullable)zones NS_SWIFT_NAME(setZones(_:));

在虚拟互动场景中，你可以使用此方法设置隔音区域和声音衰减系数。

  • 当声源（可以是用户或媒体播放器）和接收者分别处于隔音区域的内外部时，声音的衰减效果由 AgoraSpatialAudioZone 中的声音衰减系数决定。
  • 如果用户或媒体播放器处于同一个隔音区域内，则不受 AgoraSpatialAudioZone 的影响，声音衰减效果由 setPlayerAttenuation:playerId:forceSet: 或 setRemoteAudioAttenuation:userId:forceSet: 中的 attenuation 参数决定。如果你未调用上述方法，SDK 默认的声音衰减系数为 0.5，用于模拟真实环境中的声音衰减。
  • 如果声源和接收者分别处于两个不同的隔音区域内，接收者将无法听到声源的声音。

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

参数

参数名描述
zones

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

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

返回值

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

所属接口类

updatePlayerPositionInfo:positionInfo:

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

Objective-C
- (int)updatePlayerPositionInfo:(NSInteger)playerId positionInfo:(AgoraRemoteVoicePositionInfo* _Nonnull)positionInfo NS_SWIFT_NAME(updatePlayerPositionInfo(_:positionInfo:));

调用时机

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

参数

参数名描述
playerId

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

positionInfo

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

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

返回值

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

所属接口类

updateRemotePosition:positionInfo:

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

Objective-C
- (int)updateRemotePosition:(NSUInteger)uid positionInfo:(AgoraRemoteVoicePositionInfo*)posInfo NS_SWIFT_NAME(updateRemotePosition(_:positionInfo:));

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

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

参数

参数名描述
uid

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

posInfo

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

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

返回值

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

所属接口类

updateSelfPosition:axisForward:axisRight:axisUp:

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

Objective-C
- (int)updateSelfPosition:(simd_float3)position axisForward:(simd_float3)axisForward axisRight:(simd_float3)axisRight axisUp:(simd_float3)axisUp NS_SWIFT_NAME(updateSelfPosition(_:axisForward:axisRight:axisUp:));

你需要将该方法与 updateRemotePosition:positionInfo: 方法配合使用。SDK 会根据这两个方法中的参数设置计算本地用户与远端用户之间的相对位置，并据此计算空间音效参数。

参数

参数名描述
position

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

axisForward

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

axisRight

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

axisUp

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

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

返回值

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

所属接口类

updateSelfTransform:

更新坐标转换。

Objective-C
- (int)updateSelfTransform:(simd_float4x4)transform NS_SWIFT_NAME(updateSelfTransform(_:));

适用场景

当你使用原生 iOS 框架（如 SceneKit 或 RealityKit）时，可以调用此方法将位置向量直接传递给上述框架进行渲染。

参数

参数名描述
transform

转换参数。是一个 4 × 4 的矩阵。

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

返回值

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

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利