ZegoRangeAudio

Declared in ZegoExpressDefines.h

方法

setEventHandler:

- (void)setEventHandler:(nullable id<ZegoRangeAudioEventHandler>) handler;

设置范围语音回调。

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
handler	nullable id<ZegoRangeAudioEventHandler>	用于接收范围语音回调的对象。

详情

设置范围语音模块回调的接口，可接收麦克风开启状态回调通知 [onRangeAudioMicrophoneStateUpdate]。

业务场景：用于监听当前麦克风的连接状态。
调用时机：在初始化范围语音 [createRangeAudio] 之后。

支持版本：2.11.0 及以上。

setAudioReceiveRange:

- (void)setAudioReceiveRange:(float) range;

设置音频接收距离的最大范围。

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
range	float	音频范围，取值必须大于或等于 0。

详情

设置音频接收范围，超过该范围的音源声音会听不见。

业务场景：“全世界” 模式下设置收听者的听觉范围。
默认值：没有调用该函数时，只能接收本小队内的成员声音，无法接收小队外的所有声音。
调用时机：在初始化范围语音 [createRangeAudio] 之后。

支持版本：2.11.0 及以上。
注意事项：该功能只对小队以外的人生效。

setAudioReceiveRangeWithParam:

- (int)setAudioReceiveRangeWithParam:(ZegoReceiveRangeParam *) param;

设置音频接收范围的配置。

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
param	ZegoReceiveRangeParam *	音频接收范围的配置。

详情

设置音频接收范围，超过该范围的音源声音会听不见。

业务场景：“全世界” 模式下设置收听者的听觉范围。
默认值：没有调用该函数时，只能接收本小队内的成员声音，无法接收小队外的所有声音。
调用时机：在初始化范围语音 [createRangeAudio] 之后。

支持版本：3.7.0 及以上。
注意事项：该功能只对小队以外的人生效。

返回值

错误码，详情请参考常用错误码文档 https://doc-zh.zego.im/zh/4378.html

setPositionUpdateFrequency:

- (void)setPositionUpdateFrequency:(int) frequency;

设置SDK内部实时更新位置的频率

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
frequency	int	更新频率，取值必须大于15ms。

详情

设置SDK内部实时更新位置的频率最小15ms。

业务场景：对更新位置后，音频渐变灵敏度要求很高。
默认值：默认100ms。
调用时机：在初始化范围语音 [createRangeAudio] 之后。

支持版本：2.21.0 及以上。

setRangeAudioVolume:

- (void)setRangeAudioVolume:(int) volume;

设置范围语音音量

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
volume	int	音量，取值[0,200]。

详情

设置范围语音音量。

业务场景：当用户调用 [startPlayingStream] 拉取其他流时，可通过此接口来设置增大或者减少范围语音流的音量。
默认值：100。
调用时机：在初始化范围语音 [createRangeAudio] 之后。

支持版本：2.23.0 及以上。

setStreamVocalRange:vocalRange:

- (void)setStreamVocalRange:(NSString *) streamID vocalRange:(float) vocalRange;

设置流的发声范围

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
streamID	NSString *	拉流 ID。
vocalRange	float	流发声范围。

详情

设置流的发声范围。

业务场景：当用户调用 [startPlayingStream] 拉取其他流时，通过设置该流的发声范围，并且调用 [updateStreamPosition] 使此流也有范围语音效果, 调用后将以音源的发声范围进行距离衰减效果。
调用时机：在初始化范围语音 [createRangeAudio] 并且调用 [startPlayingStream] 之后。

支持版本：2.23.0 及以上。
注意事项：调用 [enableMicrophone] 开启范围语音时，会将流的资源切换成 RTC，无论原先调用 [startPlayingStream] 拉流时是否指定的资源为 RTC。如果确实需要指定流的资源为 CDN，请配置为拉自定义 CDN 流，并指定 CDN 地址信息。

setStreamVocalRangeWithParam:param:

- (int)setStreamVocalRangeWithParam:(NSString *) streamID param:(ZegoVocalRangeParam *) param;

设置流的发声范围

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
streamID	NSString *	拉流 ID。
param	ZegoVocalRangeParam *	流发声范围。

详情

设置流的发声范围。

业务场景：当用户调用 [startPlayingStream] 拉取其他流时，通过设置该流的发声范围，并且调用 [updateStreamPosition] 使此流也有范围语音效果, 调用后将以音源的发声范围进行距离衰减效果。
调用时机：在初始化范围语音 [createRangeAudio] 并且调用 [startPlayingStream] 之后。

支持版本：3.7.0 及以上。
注意事项：调用 [enableMicrophone] 开启范围语音时，会将流的资源切换成 RTC，无论原先调用 [startPlayingStream] 拉流时是否指定的资源为 RTC。如果确实需要指定流的资源为 CDN，请配置为拉自定义 CDN 流，并指定 CDN 地址信息。

返回值

错误码，详情请参考常用错误码文档 https://doc-zh.zego.im/zh/4378.html

updateStreamPosition:position:

- (void)updateStreamPosition:(NSString *) streamID position:(float[_Nonnull 3]) position;

更新流的位置

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
streamID	NSString *	拉流 ID。
position	float[_Nonnull 3]	自身在世界坐标系中的坐标，参数是长度为 3 的 float 数组，三个值依次表示前、右、上的坐标值。

详情

更新流的位置。

业务场景：当用户调用 [startPlayingStream] 拉取其他流时，调用 [setStreamVocalRange] 设置流发声位置后，再调用此接口设置该流的位置，使此流也有范围语音效果。
调用时机：在初始化范围语音 [createRangeAudio] 并且调用 [startPlayingStream] 之后。

支持版本：2.23.0 及以上。

updateSelfPosition:axisForward:axisRight:axisUp:

- (void)updateSelfPosition:(float[_Nonnull 3]) position axisForward:(float[_Nonnull 3]) axisForward axisRight:(float[_Nonnull 3]) axisRight axisUp:(float[_Nonnull 3]) axisUp;

更新自身的位置和朝向。

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
position	float[_Nonnull 3]	自身在世界坐标系中的坐标，参数是长度为 3 的 float 数组，三个值依次表示前、右、上的坐标值。
axisForward	float[_Nonnull 3]	自身坐标系前轴的单位向量，参数是长度为 3 的 float 数组，三个值依次表示前、右、上的坐标值。
axisRight	float[_Nonnull 3]	自身坐标系右轴的单位向量，参数是长度为 3 的 float 数组，三个值依次表示前、右、上的坐标值。
axisUp	float[_Nonnull 3]	自身坐标系上轴的单位向量，参数是长度为 3 的 float 数组，三个值依次表示前、右、上的坐标值。

详情

更新用户的位置和朝向，以便 SDK 计算出用户与音源距离以及左右耳立体声效果。

业务场景：当用户在游戏中操作的角色在世界地图中移动时，更新角色的位置信息以及头部朝向。
调用时机：在登录房间 [loginRoom] 后调用。

支持版本：2.11.0 及以上。
注意事项：在调用 [enableSpeaker] 打开扬声器之前如果没有调用该接口设置位置信息，则无法接收除小队以为其他人的声音。

updateAudioSource:position:

- (void)updateAudioSource:(NSString *) userID position:(float[_Nonnull 3]) position;

添加或更新音源位置信息。

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
userID	NSString *	发声者的 userID。
position	float[_Nonnull 3]	发声者在世界坐标系中的坐标，参数是长度为 3 的 float 数组，三个值依次表示前、右、上的坐标值。

详情

设置 userID 对应的音源在房间内游戏地图位置，以便 SDK 计算听者与音源的距离和方位。

业务场景：更新发声用户在游戏地图坐标中的位置。
调用时机：调用 [loginRoom] 登录房间后调用，登出房间后会清空记录的音源信息。

支持版本：2.11.0 及以上。

enableSpatializer:

- (void)enableSpatializer:(BOOL) enable;

开启或关闭 3D 音效。

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
enable	BOOL	是否开启 3D 音效。

详情

开启3D音效后将根据发声者相当于听者的位置模拟实际空间中的声音效果，直观的感受就是音源远近和方位发生变化时声音大小和左右声音差也会发生变化。

业务场景：第一人称射击类游戏或社交场景游戏中听声辨位功能。
默认值：没有调用该函数时，默认关闭 3D 音效。
调用时机：在初始化范围语音 [createRangeAudio] 之后。
相关接口：开启 3D 音效后，可使用 [updateAudioSource] 或 [updateSelfPosition] 改变位置和朝向来体验 3D 效果。

支持版本：2.11.0 及以上。
注意事项：该功能只对小队以外的人生效。

enableMicrophone:

- (void)enableMicrophone:(BOOL) enable;

开启或关闭麦克风。

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
enable	BOOL	是否开启麦克风。

详情

enable 为 "true" 时开启麦克风并推送音频流，为 "false" 时关闭麦克风并停止推送音频流。

业务场景：用户在房间内打开或关闭麦克风交流。
默认值：没有调用该函数时，默认关闭麦克风。
调用时机：在初始化范围语音 [createRangeAudio] 和登录房间 [loginRoom] 之后。
相关回调：通过回调 [onRangeAudioMicrophoneStateUpdate] 来获取麦克风开关状态变化。

支持版本：2.11.0 及以上。
注意事项：开启麦克风会自动使用主通道推音频流。

enableSpeaker:

- (void)enableSpeaker:(BOOL) enable;

开启或关闭扬声器。

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
enable	BOOL	是否开启扬声器。

详情

enable 为 "true" 时开启扬声器并拉取音频流，为 "false" 时关闭扬声器并停止拉取音频流。

业务场景：用户在房间内打开或关闭扬声器收听。
默认值：没有调用该函数时，默认关闭扬声器。
调用时机：在初始化范围语音 [createRangeAudio] 和登录房间 [loginRoom] 之后。

支持版本：2.11.0 及以上。
注意事项：开启扬声器会自动拉取房间内的音频流。

setRangeAudioMode:

- (void)setRangeAudioMode:(ZegoRangeAudioMode) mode;

设置范围语音模式。

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
mode	ZegoRangeAudioMode	范围语音模式。

详情

收听模式，可设置为 “全世界” 模式或 ”仅小队“ 模式。

业务场景：用户可选在 “全世界“ 模式下与所有人聊天（有距离限制），也可选择 ”仅小队“ 模式下团队内交流（无距离限制）。
默认值：没有调用该函数时，默认使用 “全世界” 模式。
调用时机：在初始化范围语音 [createRangeAudio] 之后。
相关接口：在 “全世界” 模式下可设置声音接收范围 [setAudioReceiveRange]，在 “仅小队” 模式下需要设置 [setTeamID] 加入对应小队才能听到队伍内的声音。

支持版本：2.11.0 及以上。
使用限制：不能与 [setRangeAudioCustomMode] 混用。

setRangeAudioCustomMode:listenMode:

- (void)setRangeAudioCustomMode:(ZegoRangeAudioSpeakMode) speakMode listenMode:(ZegoRangeAudioListenMode) listenMode;

设置范围语音的高阶自定义模式。

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
speakMode	ZegoRangeAudioSpeakMode	范围语音发声模式。
listenMode	ZegoRangeAudioListenMode	范围语音收听模式。

详情

可以分别设置发声模式和收听模式，以控制在世界和小队中的发声和收听行为。

业务场景：用户可通过选择发声模式来决定谁能收听到他的声音，也可通过选择收听模式来决定收听谁的声音。
默认值：没有调用该接口时，默认使用 “发声到所有” 模式和 “收听所有” 模式，也就是 “全世界” 模式。
调用时机：在初始化范围语音 [createRangeAudio] 之后。
相关接口：当希望收听来自世界的声音时，需要设置声音接收范围 [setAudioReceiveRange]。当希望在小队中发声和收听时，需要设置 [setTeamID] 加入对应小队。

支持版本：3.3.0 及以上。
使用限制：1. 不能与 [setRangeAudioMode] 混用；

与3.3.0之前的版本无法兼容。

setTeamID:

- (void)setTeamID:(NSString *) teamID;

设置队伍 ID

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
teamID	NSString *	队伍 ID，为空退出小队，最大长度为 64 字节的字符串。支持数字，英文字符和 '~', '!', '@', '#', '$', '', '^', '&', '*', '(', ')', '_', '+', '=', '-', ', ';', '’', ',', '.', '<', '>', '\'。

详情

设置队伍 ID 后，将能与同一队伍其他用户交流，且声音不会随距离方向产生变化；也可以通过设置空字符串来退出小队。

业务场景：用户加入小队交流或退出小队。
默认值：没有调用该函数时，默认不加入任何小队。
调用时机：在初始化范围语音 [createRangeAudio] 之后。

支持版本：2.11.0 及以上。
注意事项：小队内的声音不会有距离限制，也不会有 3D 音效。

muteUser:mute:

- (void)muteUser:(NSString *) userID mute:(BOOL) mute;

是否可接收指定用户音频数据。

Declared in ZegoExpressDefines.h

参数

名称	类型	描述
userID	NSString *	用户 ID。
mute	BOOL	是否可以接收指定远端用户的音频数据，“true” 表示禁止，“false” 表示接收，默认值为 “false”。

详情

在实时音视频互动过程中，本地用户可根据需要，通过此函数控制是否接收指定远端用户的音频数据，当开发者不接收音频收据时，可降低硬件和网络的开销。

业务场景：当开发者需要快速关闭、恢复远端音频时，可调用此函数，提升互动体验。
默认值：默认为 “false”，即接收所有用户的音频数据。
调用时机：在初始化范围语音 [createRangeAudio] 之后。
相关接口：可调用 [muteAllPlayStreamAudio] 函数控制是否接收所有音频数据。1. 当调用 [muteAllPlayStreamAudio(true)] 函数时，全局生效，即本地用户会禁止接收所有远端用户的音频数据，此时无论在 [muteAllPlayStreamAudio] 之前还是之后调用 [muteUser] 函数都不生效。2. 当调用 [muteAllPlayStreamAudio(false)] 函数时，本地用户可以接收所有远端用户的音频数据，此时可再通过 [muteUser] 函数控制是否接收指定用户的音频数据。调用 [muteUser(userID, true)] 函数则本地用户可以接收该 “userID” 之外的其他音频数据；调用 [muteUser(userID, false)] 函数则本地用户可以接收 “userID” 的音频数据。

支持版本：2.16.0 及以上。
注意事项：只有当 [muteAllPlayStreamAudio] 函数设置为 “false”时，此函数才有效。