空间音频
sharedLocalSpatialAudioWithConfig:
初始化 AgoraLocalSpatialAudioKit。
Objective-C
+ (instancetype _Nonnull)sharedLocalSpatialAudioWithConfig:(AgoraLocalSpatialAudioConfig* _Nonnull)config;
详情
信息
- 在调用 AgoraLocalSpatialAudioKit 类的其他方法前，你需要先调用该方法初始化 AgoraLocalSpatialAudioKit。
- SDK 只支持每个 App 创建一个 AgoraLocalSpatialAudioKit 实例。
参数
- config
- AgoraLocalSpatialAudioKit 的配置。详见 AgoraLocalSpatialAudioConfig。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
muteAllRemoteAudioStreams:
取消或恢复订阅所有远端用户的音频流。
Objective-C
- (int)muteAllRemoteAudioStreams:(BOOL)mute;
详情
成功调用该方法后，本地用户会取消或恢复订阅所有远端用户的音频流，包括在调用该方法后加入频道的用户的音频流。
信息
- 该方法需要在 joinChannelByToken:channelId:info:uid:joinSuccess: 或 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 后调用。
- 在使用空间音频时，如需设置是否订阅所有远端用户的音频流，建议调用该方法替代 AgoraRtcEngineKit 的 muteAllRemoteAudioStreams: 方法。
- 在调用该方法后，你需要调用 updateSelfPosition:axisForward:axisRight:axisUp: 和 updateRemotePosition:positionInfo: 更新本地用户和远端用户的空间位置，否则该方法中的设置不会生效。
参数
- mute
- 是否取消订阅所有远端用户的音频流：
YES: 取消订阅所有远端用户的音频流。NO: 订阅所有远端用户的音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
muteLocalAudioStream:
取消或恢复发布本地音频流。
Objective-C
- (int)muteLocalAudioStream:(BOOL)mute;
详情
信息
- 该方法不影响音频采集状态，因为没有禁用音频采集设备。
- 该方法需要在 joinChannelByToken:channelId:info:uid:joinSuccess: 或 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 后调用。
- 在使用空间音频时，如需设置是否发布本地音频流，建议调用该方法替代 AgoraRtcEngineKit 的 muteLocalAudioStream: 方法。
- 成功调用该方法后，远端会触发 rtcEngine:didAudioMuted:byUid: 回调和 rtcEngine:remoteAudioStateChangedOfUid:state:reason:elapsed: 回调。
参数
- mute
- 是否取消发布本地音频流。
YES: 取消发布本地音频流。NO: 发布本地音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
muteRemoteAudioStream:mute:
取消或恢复订阅指定远端用户的音频流。
Objective-C
- (int)muteRemoteAudioStream:(NSUInteger)uid mute:(BOOL)mute;
详情
自从
v4.0.1
信息
- 该方法需要在 joinChannelByToken:channelId:info:uid:joinSuccess: 或 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 后调用。
- 在使用空间音频时，如需设置是否订阅指定用户的音频流，建议调用该方法替代 AgoraRtcEngineKit 的 muteRemoteAudioStream:mute: 方法。
参数
- uid
- 用户 ID。需与用户加入频道时填写的用户 ID 一致。
- mute
- 是否取消订阅指定远端用户的音频流。
YES: 取消订阅指定用户的音频流。NO:（默认）订阅指定用户的音频流，SDK 根据本地用户和远端用户的距离决定是否订阅。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
updateRemotePosition:positionInfo:
更新远端用户的空间位置信息。
Objective-C
- (int)updateRemotePosition:(NSUInteger)uid positionInfo:(AgoraRemoteVoicePositionInfo* _Nonnull)posInfo;
详情
成功调用该方法后，SDK 会根据本地和远端用户的相对位置计算空间音频参数。
参数
- 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:));
详情
- 在 AgoraLocalSpatialAudioKit 类下，该方法需要和 updateRemotePosition:positionInfo: 搭配使用。SDK 会根据该方法和 updateRemotePosition:positionInfo: 设置的参数计算本地和远端用户之间的相对位置，从而计算用户的空间音频参数。
参数
- position
- 在世界坐标系中的坐标。该参数是长度为 3 的数组，三个值依次表示前、右、上的坐标值。
- axisForward
- 在世界坐标系前轴的单位向量。该参数是长度为 3 的数组，三个值依次表示前、右、上的坐标值。
- axisRight
- 在世界坐标系右轴的单位向量。该参数是长度为 3 的数组，三个值依次表示前、右、上的坐标值。
- axisUp
- 在世界坐标系上轴的单位向量。该参数是长度为 3 的数组，三个值依次表示前、右、上的坐标值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
destroy
Objective-C
+ (void)destroy NS_SWIFT_NAME(destroy());
详情
该方法释放 AgoraSpatialAudioKitBase 下的所有资源。当用户不需要使用空间音频时，你可以调用该方法将资源释放出来用于其他操作。
调用该方法后，你将无法再使用 AgoraSpatialAudioKitBase 下的任何 API。
信息
该方法需要在 AgoraRtcEngineKit 的 destroy 方法前调用。
destroy
Objective-C
+ (void)destroy;
详情
该方法释放 AgoraLocalSpatialAudioKit 下的所有资源。当用户不需要使用空间音频时，你可以调用该方法将资源释放出来用于其他操作。
调用该方法后，你将无法再使用 AgoraLocalSpatialAudioKit 下的任何 API。如需再次使用空间音频，你需要等 destroy 执行结束后再调用 sharedLocalSpatialAudioWithConfig: 创建一个新的 AgoraLocalSpatialAudioKit。
信息
该方法需要在 AgoraRtcEngineKit 的 destroy 方法前调用。
clearRemotePositions
removeRemotePosition:
删除指定远端用户的空间位置信息。
Objective-C
- (int) removeRemotePosition:(NSUInteger)uid;
详情
成功调用该方法后，本地用户将听不到指定的远端用户。
离开频道后，为避免计算资源的浪费，你需要调用该方法删除指定远端用户的空间位置信息。否则，该用户的空间位置信息会一直被保存。当远端用户人数大于 setMaxAudioRecvCount: 中设定的可接收音频流数时，会按照相对距离依次自动取消订阅距离最远的用户的音频流。
参数
- uid
- 用户 ID。需与用户加入频道时填写的用户 ID 一致。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setAudioRecvRange:
setDistanceUnit:
设置游戏引擎单位距离的长度（米）。
Objective-C
- (int)setDistanceUnit:(float)unit;
详情
游戏引擎里的距离单位是游戏引擎自定义的，而声网空间音频算法的距离单位为米。默认情况下，SDK 会将每单位的游戏引擎距离换算为一米。你可以调用该方法，将游戏引擎里的单位距离换算为指定的米数。
参数
- unit
- 每单位游戏引擎距离转换后的米数。该参数取值需大于 0.00，默认值为 1.00。例如，将 unit 设为 2.00，表示每单位的游戏引擎距离等于 2 米。
该值越大，当远端用户远离本地用户时，本地用户听到的声音衰减速度越快。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setHeadphoneEQParameters:highGain:
设置耳机均衡器的低频和高频参数。
Objective-C
- (int)setHeadphoneEQParameters:(int)lowGain highGain:(int)highGain;
详情
自从
v4.1.0
在空间音频场景下，如果在调用 setHeadphoneEQPreset: 方法使用预设的耳机均衡效果后仍未达到预期，你可以通过调用该方法进一步调节耳机均衡效果。
参数
- lowGain
- 耳机均衡器的低频参数。取值范围为 [-10,10]，取值越大，声音越低沉。
- highGain
- 耳机均衡器的高频参数。取值范围为 [-10,10]，取值越大，声音越尖锐。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败
- -1：一般性的错误（未明确归类）。
setHeadphoneEQPreset:
设置预设的耳机均衡效果。
Objective-C
- (int)setHeadphoneEQPreset:(AgoraHeadphoneEQPreset)preset;
详情
自从
v4.0.1
该方法主要应用于空间音频场景下，你可以选择预设的耳机均衡器收听音频，以达到预期的音频体验。
信息
如果你使用的耳机已经具备良好的均衡效果，调用该方法时可能不会获得明显的体验提升效果，甚至可能导致体验下降。
参数
- preset
- 预设的耳机均衡效果。详见 AgoraHeadphoneEQPreset。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败
- -1：一般性的错误（未明确归类）。
setMaxAudioRecvCount:
setPlayerAttenuation:playerId:forceSet:
设置媒体播放器的声音衰减属性。
Objective-C
- (int)setPlayerAttenuation:(double)attenuation playerId:(NSUInteger)playerId forceSet:(BOOL)forceSet;
详情
自从
v4.0.1
参数
- playerId
- 媒体播放器 ID。可通过 getMediaPlayerId 获取。
- attenuation
- 媒体播放器的声音衰减系数，取值范围为[0,1]。其中：
- 0：广播模式，即音量和音色均不随距离衰减，无论距离远近，本地用户听到的音量和音色都无变化。
- (0,0.5)：弱衰减模式，即音量和音色在传播过程中仅发生微弱衰减，跟真实环境相比，声音可以传播得更远。
- 0.5：（默认）模拟音量在真实环境下的衰减，效果等同于不设置 attenuation 参数。
- (0.5,1]：强衰减模式，即音量和音色在传播过程中发生迅速衰减。
- forceSet
- 是否强制设定媒体播放器的声音衰减效果：
YES：强制使用 attenuation 设置媒体播放器的声音衰减效果，此时 AgoraSpatialAudioZone 中的 audioAttenuation 中设置的隔声区域衰减系数对媒体播放器不生效。NO：不强制使用 attenuation 设置媒体播放器的声音衰减效果，分为以下两种情况。- 如果音源和听声者分属于隔声区域内部和外部，则声音衰减效果由 AgoraSpatialAudioZone 中的 audioAttenuation 决定。
- 如果音源和听声者在同一个隔声区域内或同在隔声区域外，则声音衰减效果由该方法中的 attenuation 决定。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setRemoteAudioAttenuation:userId:forceSet:
设置指定用户的声音衰减效果。
Objective-C
- (int) setRemoteAudioAttenuation:(double)attenuation userId:(NSUInteger)uid forceSet:(BOOL)forceSet;
详情
自从
v4.0.1
参数
- uid
- 用户 ID。需与用户加入频道时填写的用户 ID 一致。
- attenuation
- 针对该用户的声音衰减系数，取值范围为[0,1]。其中：
- 0：广播模式，即音量和音色均不随距离衰减，无论距离远近，本地用户听到的音量和音色都无变化。
- (0,0.5)：弱衰减模式，即音量和音色在传播过程中仅发生微弱衰减，跟真实环境相比，声音可以传播得更远。
- 0.5：（默认）模拟音量在真实环境下的衰减，效果等同于不设置 attenuation 参数。
- (0.5,1]：强衰减模式，即音量和音色在传播过程中发生迅速衰减。
- forceSet
- 是否强制设定该用户的声音衰减效果：
YES：强制使用 attenuation 设置该用户的声音衰减效果，此时 AgoraSpatialAudioZone 中的 audioAttenuation 中设置的隔声区域衰减系数对该用户不生效。NO：不强制使用 attenuation 设置用户的声音衰减效果，分为以下两种情况。- 如果音源和听声者分属于隔声区域内部和外部，则声音衰减效果由 AgoraSpatialAudioZone 中的 audioAttenuation 决定。
- 如果音源和听声者在同一个隔声区域内或同在隔声区域外，则声音衰减效果由该方法中的 attenuation 决定。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setRemoteUserSpatialAudioParams:params:
设置远端用户的空间音频参数。
Objective-C
- (int)setRemoteUserSpatialAudioParams:(NSUInteger)uid
params:(AgoraSpatialAudioParams* _Nonnull)params;
详情
该方法需要在 enableSpatialAudio: 后调用。成功设置远端用户的空间音频参数后，本地用户听远端用户会有空间感。
参数
- uid
- 用户 ID。需与用户加入频道时填写的用户 ID 一致。
- params
- 空间音频参数。详见 AgoraSpatialAudioParams。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setSpatialAudioParams:
开启或关闭媒体播放器的空间音频。
Objective-C
- (int)setSpatialAudioParams:(AgoraSpatialAudioParams* _Nonnull)params;
详情
成功设置媒体播放器的空间音频参数后，SDK 会开启媒体播放器的空间音频，即本地用户听媒体资源会有空间感。
如果需关闭媒体播放器的空间音频，你需要将 params 参数设为空。
参数
- params
- 媒体播放器的空间音频参数。详见 AgoraSpatialAudioParams。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setZones:
设置隔声区域。
Objective-C
- (int)setZones:(NSArray<AgoraSpatialAudioZone*> * _Nullable)zones NS_SWIFT_NAME(setZones(_:));
详情
自从
v4.0.1
在虚拟互动场景下，你可以通过该方法设置隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟听声者分属于隔声区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。
- 当音源跟听声者分属于隔声区域内部和外部时，声音的衰减效果由 AgoraSpatialAudioZone 中的声音衰减系数决定。
- 如果用户或媒体播放器同在一个隔声区域内，则不受 AgoraSpatialAudioZone 的影响，声音的衰减效果由 setPlayerAttenuation:playerId:forceSet: 或 setRemoteAudioAttenuation:userId:forceSet: 中的 attenuation 参数决定。如果不调用 setPlayerAttenuation:playerId:forceSet: 或 setRemoteAudioAttenuation:userId:forceSet:，则 SDK 默认声音的衰减系数为 0.5，即模拟声音在真实环境下的衰减。
- 如果音源跟接收者分别属于两个隔声区域，则接收者无法听到音源。
信息
如果多次调用该方法，以最后一次设置的隔声区域为准。
参数
- zones
- 隔声区域的设置。详见 AgoraSpatialAudioZone。当你将该参数设置为
nil时，表示清除所有隔声区域。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
updatePlayerPositionInfo:positionInfo:
更新媒体播放器的空间位置。
Objective-C
- (int)updatePlayerPositionInfo:(NSInteger)playerId positionInfo:(AgoraRemoteVoicePositionInfo* _Nonnull)positionInfo;
成功更新后，本地用户可以听到媒体播放器空间位置的变化。
调用时机
加入频道前后均可调用。
调用限制
无。
参数
- playerId
- 媒体播放器 ID。可通过 getMediaPlayerId 获取。
- positionInfo
- 媒体播放器的空间位置信息。详见 AgoraRemoteVoicePositionInfo。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
updateSelfTransform:
enableSpatialAudio:
开启或关闭空间音频。
Objective-C
- (int)enableSpatialAudio:(BOOL)enabled;
详情
开启空间音频后，你可以调用 setRemoteUserSpatialAudioParams:params: 设置远端用户的空间音频参数。
信息
- 该方法在加入频道前后均可调用。
- 该方法依赖于空间音频动态库
AgoraSpatialAudioExtension.xcframework，如果删除该动态库会导致无法正常开启该功能。
参数
- enabled
- 是否开启空间音频：
YES: 开启空间音频。NO: 关闭空间音频。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。