ZegoChatroom Class Reference

Inherits from NSObject
Declared in ZegoChatroom.h

Overview

语聊房业务类

提供如下能力:1.房间操作 2.更新麦位 3.本地音量操作

语聊房(开发分类)

语聊房(IM分类)

语聊房(音频处理分类)

语聊房(信令分类)

Other Methods

  musicPlayer

音乐播放器

@property (strong, nonatomic, readonly, nullable) ZegoMusicPlayer *musicPlayer

Discussion

音乐播放器

在登录房间成功回调后方可使用;与 ZegoChatroom 一一对应,请不要自行创建。

Declared In

ZegoChatroom.h

  userInfo

当前用户

@property (strong, nonatomic, readonly) ZegoChatroomUser *userInfo

Discussion

当前用户

该对象由设置语聊房单例初始化配置方法进行赋值。语聊房中业务操作都是基于这个用户身份执行。

Declared In

ZegoChatroom.h

  roomID

当前登录房间ID

@property (copy, nonatomic, readonly, nullable) NSString *roomID

Discussion

当前登录房间ID

Declared In

ZegoChatroom.h

  liveConfig

语聊房上麦配置

@property (strong, nonatomic, readonly, nullable) ZegoChatroomLiveConfig *liveConfig

Discussion

语聊房上麦配置

Declared In

ZegoChatroom.h

  seats

语聊房麦位信息数组

@property (strong, nonatomic, readonly, nullable) NSArray<ZegoChatroomSeat*> *seats

Discussion

语聊房麦位信息数组

Declared In

ZegoChatroom.h

  loginStatus

房间登录状态

@property (assign, nonatomic, readonly) ZegoChatroomLoginStatus loginStatus

Discussion

房间登录状态

开发者可以使用该状态来限制操作的执行,如当前房间登录状态为已登录的情况下,才能执行上麦等操作。

Declared In

ZegoChatroom.h

  liveStatus

当前用户直播状态

@property (assign, nonatomic, readonly) ZegoChatroomUserLiveStatus liveStatus

Discussion

当前用户直播状态

开发者可以使用该状态来限制操作的执行,如只有当前直播状态为直播已连接状态,才能使用背景音乐播放功能。

Declared In

ZegoChatroom.h

  autoReconnectRoom

登录失败是否自动重连

@property (assign, nonatomic) BOOL autoReconnectRoom

Discussion

登录失败是否自动重连

默认值为YES。

Declared In

ZegoChatroom.h

  autoReconnectTimeout

登录自动重连超时时间(s)

@property (assign, nonatomic) NSUInteger autoReconnectTimeout

Discussion

登录自动重连超时时间(s)

如果打开登录失败自动重连,则该参数生效。

重试超过该时间自动断开,避免出现不符合用户预期的重连行为;0表示不会超时,默认600s。

Declared In

ZegoChatroom.h

+ setAppID:appSignature:user:

设置语聊房单例初始化配置

+ (BOOL)setAppID:(unsigned int)appID appSignature:(NSData *)appSignature user:(ZegoChatroomUser *)userInfo

Parameters

appID

Zego 派发的数字 ID, 开发者的唯一标识

appSignature

Zego 派发的签名, 用来校验对应 appID 的合法性

userInfo

当前用户,userID 及 userName 必须长度大于0,否则参数无效

Return Value

初始化配置是否成功

Discussion

设置语聊房单例初始化配置

初始化配置需要在获取单例前调用,当已存在单例时调用该方法,或者appID、appSignature、userInfo参数无效,将返回NO。

Declared In

ZegoChatroom.h

+ shared

获取语聊房单例

+ (instancetype)shared

Return Value

语聊房单例

Discussion

获取语聊房单例

获取语聊房单例前需要调用初始化配置,否则单例将返回空。

Declared In

ZegoChatroom.h

+ releaseShared

释放当前语聊房单例

+ (void)releaseShared

Discussion

释放当前语聊房单例

该方法会释放当前语聊房单例及相关占用资源。

Declared In

ZegoChatroom.h

– addDelegate:

添加ZegoChatroom代理

- (void)addDelegate:(id<ZegoChatroomDelegate>)delegate

Parameters

delegate

添加的代理,内部弱引用

Discussion

添加ZegoChatroom代理

Declared In

ZegoChatroom.h

– removeDelegate:

移除ZegoChatroom代理

- (void)removeDelegate:(id<ZegoChatroomDelegate>)delegate

Parameters

delegate

移除的代理

Discussion

移除ZegoChatroom代理

Declared In

ZegoChatroom.h

– joinRoomWithRoomID:roomName:seatCount:liveConfig:

进入房间

- (void)joinRoomWithRoomID:(NSString *)roomID roomName:(nullable NSString *)roomName seatCount:(NSUInteger)seatCount liveConfig:(nullable ZegoChatroomLiveConfig *)config

Parameters

roomID

房间ID,只支持字母、数字、下划线,长度为1~127字节,需在同一 AppID 下全局唯一

roomName

房间名,长度为0~255字节,可空

seatCount

房间麦位数,必须大于0并小于等于12,如果进入房间时,房间没有麦位,则会以此为房间初始化同样数量的一组空麦位

config

直播上麦配置参数,可空,默认为普通质量娱乐场景

Discussion

进入房间

调用进入房间后,会先尝试获取房间内的麦位,如果获取成功则登录成功;如果获取失败则会尝试初始化房间麦位,如果初始化成功则登陆成功,否则登录失败。

Note: 该方法是异步操作,调用返回时并没有真正的加入到房间。在加入房间成功或者失败后,SDK 会触发语聊房登录状态、事件回调回调。

Note: 进入房间依赖的是指定房间的 roomID,roomName 仅为第一次进入房间初始化房间时的可选参数,客户可以选择不传。

Declared In

ZegoChatroom.h

– joinRoomWithRoomID:roomName:initialSeats:liveConfig:

进入房间(自定义麦位)

- (void)joinRoomWithRoomID:(NSString *)roomID roomName:(nullable NSString *)roomName initialSeats:(NSArray<ZegoChatroomSeat*> *)seats liveConfig:(nullable ZegoChatroomLiveConfig *)config

Parameters

roomID

房间ID,只支持字母、数字、下划线,长度为1~127字节,需在同一 AppID 下全局唯一

roomName

房间名,长度为0~255字节,可空

seats

房间初始麦位数组,需要数量大于0并小于等于12,如果进入房间时,房间没有麦位,会将房间的麦位数据初始化为传入值

config

直播上麦配置参数,可空,默认为普通质量娱乐场景

Discussion

进入房间(自定义麦位)

调用进入房间后,会先尝试获取房间内的麦位,如果获取成功则登录成功;如果获取失败则会尝试初始化房间麦位,如果初始化成功则登陆成功,否则登录失败。

Note: 该方法是异步操作,调用返回时并没有真正的加入到房间。在加入房间成功或者失败后,SDK 会触发语聊房登录状态、事件回调回调。

Note: 进入房间依赖的是指定房间的 roomID,roomName 仅为第一次进入房间初始化房间时的可选参数,客户可以选择不传。

Declared In

ZegoChatroom.h

– leaveRoom

离开当前房间

- (void)leaveRoom

Discussion

离开当前房间

如果用户已经进入房间,用户必须先调用本方法,才能创建或加入另一个房间。

Declared In

ZegoChatroom.h

– takeSeatAtIndex:completion:

麦位操作–上麦

- (void)takeSeatAtIndex:(NSUInteger)index completion:(nullable ZegoSeatUpdateCallback)completion

Parameters

index

上麦麦位索引

completion

完成回调

Discussion

麦位操作–上麦

已登录房间时调用有效。当前用户在指定麦位上麦,上麦成功后,将自动推送声音。

Note: 操作合法条件:index未越界,上麦麦位为空麦位,且当前用户未上麦(对当前用户已上麦在指定麦位的情况做了兼容处理,操作也将成功)。

Declared In

ZegoChatroom.h

– leaveSeatWithCompletion:

麦位操作–下麦

- (void)leaveSeatWithCompletion:(nullable ZegoSeatUpdateCallback)completion

Parameters

completion

完成回调

Discussion

麦位操作–下麦

已登录房间时调用有效。当前用户执行下麦操作,当下麦成功后,会停止推送声音。

Note: 操作合法条件:当前用户已经上麦(对当前用户已下麦情况做了兼容处理,操作也将成功)

Declared In

ZegoChatroom.h

– changeSeatTo:completion:

麦位操作–换麦

- (void)changeSeatTo:(NSUInteger)index completion:(nullable ZegoSeatUpdateCallback)completion

Parameters

index

换麦目标麦位索引

completion

完成回调

Discussion

麦位操作–换麦

已登录房间时调用有效。当前用户更换上麦的位置,换麦过程中,不会停止推送声音。

Note: 操作合法条件:index未越界,且目标麦位为空(对未上麦则执行换麦操作和换麦目标麦位为当前麦位等情况做了兼容处理,操作也将成功)。

Declared In

ZegoChatroom.h

– pickUp:atIndex:completion:

麦位操作–抱人上麦

- (void)pickUp:(ZegoChatroomUser *)user atIndex:(NSUInteger)index completion:(nullable ZegoSeatUpdateCallback)completion

Parameters

user

被抱上麦的用户

index

抱上麦麦位索引,必须小于当前总麦位数,否则操作失败

completion

完成回调

Discussion

麦位操作–抱人上麦

已登录房间时调用有效。让指定用户在指定麦位上麦,默认被抱用户上麦成功后将会自动推送声音。为了避免被抱人在不知情的情况下推送声音,开发者需在被抱麦的用户收到该回调时,主动禁用手机麦克风并提示。

Note: 操作合法条件:index未越界,当前用户未上麦,且目标麦位为空麦位(对被抱上麦用户已在指定麦位上麦的情况做了兼容处理,操作也将成功)。

Declared In

ZegoChatroom.h

– kickOut:completion:

麦位操作–抱人下麦

- (void)kickOut:(nullable ZegoChatroomUser *)user completion:(nullable ZegoSeatUpdateCallback)completion

Parameters

user

指定抱下麦的用户

completion

完成回调

Discussion

麦位操作–抱人下麦

已登录房间时调用有效。让指定用户下麦,操作成功后,被抱下用户将停止推送声音。

Note: 操作合法条件:指定的用户在麦位上。不管用户在那个麦位上,操作都会执行。

Declared In

ZegoChatroom.h

– muteSeat:atIndex:completion:

麦位操作–禁麦、解禁

- (void)muteSeat:(BOOL)mute atIndex:(NSUInteger)index completion:(nullable ZegoSeatUpdateCallback)completion

Parameters

mute

禁麦、解禁

index

指定麦位索引,必须小于当前总麦位数,否则操作失败

completion

完成回调

Discussion

麦位操作–禁麦、解禁

已登录房间时调用有效。将指定的麦位设置成禁麦位状态,或者解除禁麦位状态;其他用户听不到禁麦状态麦位上用户推送的声音。

Note: 操作合法条件:index未越界。

Declared In

ZegoChatroom.h

– closeSeat:atIndex:completion:

麦位操作–封麦、解封

- (void)closeSeat:(BOOL)close atIndex:(NSUInteger)index completion:(nullable ZegoSeatUpdateCallback)completion

Parameters

close

封麦、解封

index

指定麦位索引,必须小于当前总麦位数,否则操作失败

completion

完成回调

Discussion

麦位操作–封麦、解封

已登录房间时调用有效。将指定麦位设置为封麦状态,或者解除封麦状态;如果麦位设置封麦状态之前已经有用户在该麦位上,将会先将该用户被抱下麦,然后封麦。

Note: 操作合法条件:index未越界。

Declared In

ZegoChatroom.h

– runSeatOperationGroup:completion:

执行一组麦位操作

- (void)runSeatOperationGroup:(NS_NOESCAPE ZegoOperationGroupBlock)block completion:(nullable ZegoSeatUpdateCallback)completion

Parameters

block

执行麦位操作的context

completion

这组麦位操作的完成回调

Discussion

执行一组麦位操作

已登录房间时调用有效。执行一组麦位操作完成时,方法会按照顺序先一一执行操作组中每一个操作的完成回调,然后再执行组操作的完成回调。

Note: 只有有其中一个麦位操作失败,该组麦位操作将会全部失败。 @code 使用示例 [chatroom runSeatOperationGroup:^{ [chatroom closeSeat:YES atIndex:1 completion:completion]; [chatroom closeSeat:YES atIndex:2 completion:completion]; [chatroom closeSeat:YES atIndex:3 completion:nil]; } completion:^(NSError * _Nullable error) { NSLog(@“%@”, error); }]; @endcode

Declared In

ZegoChatroom.h

– muteMic:

禁用手机的麦克风

- (void)muteMic:(BOOL)mute

Parameters

mute

是否静音

Discussion

禁用手机的麦克风

禁用后自己上麦将静音,其他用户将听不到你推送的声音。

Note: 调用leaveRoom离开房间,之前设置禁用麦克风状态不会被重置; 即以禁用麦克风状态退出房间,执行创建或者加入新房间,当前的状态还是禁用麦克风。只有释放语聊房单例后,才会重置禁用麦克风状态值。

Declared In

ZegoChatroom.h

– muteSpeaker:

扬声器静音

- (void)muteSpeaker:(BOOL)mute

Parameters

mute

是否静音

Discussion

扬声器静音

开启静音模式后,其他上麦用户将被静音。

Note: 调用leaveRoom离开房间,之前设置扬声器静音状态不会被重置;即以扬声器静音状态退出房间,执行创建或者加入新房间,当前的状态还是扬声器静音。只有释放语聊房单例后,才会重置扬声器静音状态值。

Declared In

ZegoChatroom.h

– setPublishVolume:

设置本地推流音量

- (void)setPublishVolume:(NSUInteger)volume

Parameters

volume

音量范围[0,100],默认100

Discussion

设置本地推流音量

此方法与禁用手机麦克风互不影响。

Note: 调用leaveRoom离开房间,之前设置的本地推流音量不会被重置;即执行创建或者加入新房间,本地推拉音量还是保持上一次在房间内设置的值。只有释放语聊房单例后,才会重置本地推流音量值。

Declared In

ZegoChatroom.h

– setPlayVolume:

设置远程拉流音量

- (void)setPlayVolume:(NSUInteger)volume

Parameters

volume

音量范围[0,100],默认100

Discussion

设置远程拉流音量

此方法与开启静音模式互不影响。

Note: 调用leaveRoom离开房间,之前设置的远程拉流音量不会被重置; 即执行创建或者加入新房间,远程拉流音量还是保持上一次在房间内设置的值。只有释放语聊房单例后,才会重置远程拉流音量值。

Declared In

ZegoChatroom.h

– setCustomToken:

设置自定义token信息

- (void)setCustomToken:(nullable NSString *)token

Parameters

token

鉴权所需的 token

Discussion

设置自定义token信息

使用此方法验证登录时用户的合法性,进入房间前调用,token 的生成规则请联系即构。若不需要登录鉴权,则不需要调用此函数。

Note: 在登录房间前调用有效。

Declared In

ZegoChatroom.h

– setLiveExtraInfo:

设置直播额外信息

- (void)setLiveExtraInfo:(nullable NSString *)liveExtraInfo

Parameters

liveExtraInfo

直播额外信息

Discussion

设置直播额外信息

当用户主动修改他的直播额外信息,其他用户将会收到语聊房上麦者直播额外信息更新回调,在回调中将会获取到该用户主动修改后的直播额外信息。

Declared In

ZegoChatroom.h

Develop Methods

+ setUseTestEnv:

是否启用测试环境

+ (void)setUseTestEnv:(BOOL)useTestEnv

Parameters

useTestEnv

是否启用测试环境,默认为 NO。

Discussion

是否启用测试环境

在初始化 SDK 前调用。建议开发者在开发阶段设置为测试环境,使用由 Zego 提供的测试环境。上线前需切换为正式环境运营。

Declared In

ZegoChatroom.h

+ uploadLog

上报日志

+ (void)uploadLog

Discussion

上报日志

上传日志到后台便于分析问题。

在初始化 SDK 成功后即可调用。

Declared In

ZegoChatroom.h

+ setLogVerbose:

设置是否输出详细日志到控制台

+ (void)setLogVerbose:(BOOL)logVerbose

Parameters

logVerbose

是否输出详细日志到控制台,默认为 NO。

Discussion

设置是否输出详细日志到控制台

Declared In

ZegoChatroom.h

IM Methods

– addIMDelegate:

添加ZegoChatroomIM代理

- (void)addIMDelegate:(id<ZegoChatroomIMDelegate>)delegate

Parameters

delegate

添加的代理,内部弱引用

Discussion

添加ZegoChatroomIM代理

Declared In

ZegoChatroom.h

– removeIMDelegate:

移除ZegoChatroomIM代理

- (void)removeIMDelegate:(id<ZegoChatroomIMDelegate>)delegate

Parameters

delegate

移除的代理

Discussion

移除ZegoChatroomIM代理

Declared In

ZegoChatroom.h

– setChatroomEnableUserStateUpdate:

设置房间是否广播用户状态

- (void)setChatroomEnableUserStateUpdate:(BOOL)enable

Parameters

enable

用户进入、退出房间是否广播,默认NO

Discussion

设置房间是否广播用户状态

在创建房间前设置有效,退出房间后重置回NO;在enable为YES的情况下,用户进入、退出房间会触发 didUserJoin/didUserLeave 回调。

Declared In

ZegoChatroom.h

– sendChatroomMessage:type:completion:

发送房间内广播消息

- (void)sendChatroomMessage:(NSString *)content type:(NSInteger)type completion:(ZegoSendChatroomMsgCallback)completion

Parameters

content

消息内容

type

消息类型,由业务端自行定义,SDK只负责透传

completion

完成回调

Discussion

发送房间内广播消息

登录房间成功后方可调用。

Declared In

ZegoChatroom.h

AudioProcessing Methods

  enableLoopback

开启采集监听(耳返)

@property (assign, nonatomic) BOOL enableLoopback

Discussion

开启采集监听(耳返)

开启采集监听,主播方讲话后,会听到自己的声音,默认NO;直播时连接耳麦才能听到耳返。

Declared In

ZegoChatroom.h

  virtualStereoAngle

虚拟立体声角度

@property (assign, nonatomic) int virtualStereoAngle

Discussion

虚拟立体声角度

自己直播的虚拟立体声中声源的角度,范围为[0,180],90代表正前方(没有虚拟立体声效果),0和180分别对应最右边和最左边,默认90。

直播为双声道才有效,直播中动态设置不同的值都会立即生效。

Declared In

ZegoChatroom.h

  voiceChangeValue

变声音调

@property (assign, nonatomic) float voiceChangeValue

Discussion

变声音调

自己直播的变声音调,范围为[-8.0,8.0],0代表没有变声效果,值越高音调越高,反之音调越低,默认0。

变声音效仅对采集的声音有效(不影响MusicPlayer的混声),直播中动态设置不同的值都会立即生效。

Declared In

ZegoChatroom.h

  audioReverbConfig

音频混响配置

@property (strong, nonatomic, nullable) ZegoChatroomAudioReverbConfig *audioReverbConfig

Discussion

音频混响配置

可空,为空表示没有混响效果,默认空。

直播中动态设置不同的配置都会立即生效。

Declared In

ZegoChatroom.h

CustomCommand Methods

– addCMDDelegate:

添加ZegoChatroom信令代理

- (void)addCMDDelegate:(id<ZegoChatroomCMDDelegate>)delegate

Parameters

delegate

添加的代理,内部弱引用

Discussion

添加ZegoChatroom信令代理

Declared In

ZegoChatroom.h

– removeCMDDelegate:

移除ZegoChatroom信令代理

- (void)removeCMDDelegate:(id<ZegoChatroomCMDDelegate>)delegate

Parameters

delegate

移除的代理

Discussion

移除ZegoChatroom信令代理

Declared In

ZegoChatroom.h

– sendCustomCommand:memberList:completion:

发送信令

- (void)sendCustomCommand:(NSString *)content memberList:(NSArray<ZegoChatroomUser*> *)memberList completion:(nullable ZegoSendCustomCmdCallback)completion

Parameters

content

信令内容

memberList

信令接收对象列表

completion

完成回调

Discussion

发送信令

登录房间成功后方可调用。

Declared In

ZegoChatroom.h