AgoraBaseSpatialAudioKit
该类包含 AgoraLocalSpatialAudioKit 类中的部分 API。
AgoraLocalSpatialAudioKit 类继承自 AgoraBaseSpatialAudioKit。
muteAllRemoteAudioStreams
取消或恢复订阅所有远端用户的音频流。
- (int)muteAllRemoteAudioStreams:(BOOL)mute;
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的音频流,包括在调用该方法后加入频道的用户的音频流。
注:
- 该方法需要在 joinChannelByToken [2/4] 后调用。
- 在使用空间音效时,如需设置是否订阅所有远端用户的音频流,Agora 推荐调用该方法替代 AgoraRtcEngineKit 的 muteAllRemoteAudioStreams 方法。
参数
- mute
-
是否取消订阅所有远端用户的音频流:
YES
: 取消订阅所有远端用户的音频流。NO
: 订阅所有远端用户的音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteLocalAudioStream
取消或恢复发布本地音频流。
- (int)muteLocalAudioStream:(BOOL)mute;
注:
- 该方法不影响音频采集状态,因为没有禁用音频采集设备。
- 该方法需要在 joinChannelByToken [2/4] 后调用。
- 在使用空间音效时,如需设置是否发布本地音频流,Agora 推荐调用该方法替代 AgoraRtcEngineKit 的 muteLocalAudioStream 方法。
参数
- mute
-
是否取消发布本地音频流。
YES
: 取消发布本地音频流。NO
: 发布本地音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAudioRecvRange
设置本地用户的音频接收范围。
- (int)setAudioRecvRange:(float)range;
设置成功后,用户只能听见设置范围内或属于同一队伍的远端用户。你可以随时调用该方法更新音频的接收范围。
参数
- range
- 可接收音频的最大范围,单位为米。取值需大于 0。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setDistanceUnit
设置游戏引擎单位距离的长度(米)。
- (int)setDistanceUnit:(float)unit;
游戏引擎里的距离单位是游戏引擎自定义的,而 Agora 空间音效算法的距离单位为米。默认情况下,SDK 会将每单位的游戏引擎距离换算为一米。你可以调用该方法,将游戏引擎里的单位距离换算为指定的米数。
参数
- unit
- 每单位游戏引擎距离转换后的米数,取值需大于 0.00。例如,将 unit 设为 2.00,表示每单位的游戏引擎距离等于 2 米。
该值越大,当远端用户远离本地用户时,本地用户听到的声音衰减速度越快。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setMaxAudioRecvCount
设置音频接收范围内最多可接收的音频流数。
- (int)setMaxAudioRecvCount:(NSUInteger)maxCount;
如果在音频接收范围内可接收的音频流数超过设置的值,则本地用户会接收音源距离较近的 maxCount 路音频。如果房间里有和本地用户属于同一队伍的用户,则本地用户会优先接收队员的音频。例如,当 maxCount 设为 3 时,如果房间里有 5 位远端用户,其中 2 位和本地用户属于同一队伍、3 位和本地用户属于不同队伍但在本地用户的音频接收范围内,则本地用户可以听到 2 位队友和 1 位离自己最近的不同队伍的用户。
参数
- maxCount
- 音频接收范围内最多可接收的音频流数。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
updatePlayerPositionInfo
更新媒体播放器的空间位置。
- (int)updatePlayerPositionInfo:(NSInteger)playerId positionInfo:(AgoraRemoteVoicePositionInfo* _Nonnull)positionInfo;
成功更新后,本地用户可以听到媒体播放器空间位置的变化。
参数
- playerId
- 媒体播放器 ID。可通过 getMediaPlayerId 获取。
- positionInfo
- 媒体播放器的空间位置信息。详见 AgoraRemoteVoicePositionInfo。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
updateSelfPosition
更新本地用户的空间位置。
- (int)updateSelfPosition:(NSArray<NSNumber*>* _Nonnull)position axisForward:(NSArray<NSNumber*>* _Nonnull)axisForward axisRight:(NSArray<NSNumber*>* _Nonnull)axisRight axisUp:(NSArray<NSNumber*>* _Nonnull)axisUp;
- 在 AgoraLocalSpatialAudioKit 类下,该方法需要和 updateRemotePosition 搭配使用。SDK 会根据该方法和 updateRemotePosition 设置的参数计算本地和远端用户之间的相对位置,从而计算用户的空间音效参数。
参数
- position
- 在世界坐标系中的坐标。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
- axisForward
- 在世界坐标系前轴的单位向量。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
- axisRight
- 在世界坐标系右轴的单位向量。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
- axisUp
- 在世界坐标系上轴的单位向量。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。