互动视频
  • iOS : Objective-C
  • Android
  • macOS
  • Windows
  • Linux
  • Web
  • 小程序
  • Electron
  • 概述
  • 限制说明
  • SDK 下载
  • 快速开始
  • 常用功能
  • 推拉流进阶
  • 视频进阶
  • 音频进阶
  • 其他功能
  • 废弃接口
  • API 文档
  • 常见错误码
  • 常见问题
  • AI教育
  • KTV 合唱
  • 视频直播
  • 视频通话
  • 游戏直播
  • 直播答题
  • 娃娃机

多房间

更新时间:2022-09-09 18:40

1 功能简介

同一个用户可以同时加入多个房间,并同时在多个房间内推流、拉流、发送实时消息和接收消息回调。

  1. 开发者需联系 ZEGO 技术支持开通多房间功能。
  2. 目前默认最多同时加入 5 个房间,如有更多需求,请联系 ZEGO 技术支持提供扩展能力。

1.1 应用场景

本功能可以隔离多个房间的消息及回调,实现更灵活的连麦业务。ZEGO 推荐用于跨房间连麦和在线教育的超级小班场景。

  • 跨房间连麦

主播 A 与主播 B 进行跨房间连麦,主播 A 可以通知房间 A 中所有观众登录主播 B 的房间进行拉流,主播 B 同样可以通知房间 B 中所有观众登录主播 A 的房间进行拉流。

  • 超级小班

老师进入大班房间推流,学生都登录大班房间拉流,同时登录小组房间与同组学生讨论和连麦。助教老师登录小组房间维持课堂秩序或解答学生问题。

2 前提条件

在实现多房间功能之前,请确保:

  • 已在 ZEGO 控制台 创建项目,并申请有效的 AppID 和 AppSign,详情请参考 控制台 - 项目管理
  • 已在项目中集成 ZEGO LiveRoom SDK(2021年6月18日以后),实现基本的实时音视频功能,详情请参考 快速开始 - 集成 等。
  • 已联系 ZEGO 技术支持开通多房间功能。

3 使用步骤

以同一用户加入两个房间为例,整体实现流程如下:

/Pics/LiveRoom/Common/MultiRoom.png

  1. 在初始化 SDK 之前,将房间模式设置为多房间。
  2. 初始化 SDK,根据实际需要,配置房间相关信息。
  3. 加入第一个房间,成功登录后,可在该房间内推流、拉流、发送和接收实时消息。
  4. 加入第二个房间,成功登录后,可在该房间内推流、拉流、发送和接收实时消息。
  5. 离开第一个和第二个房间,针对离开房间不做时序上的限制。

具体功能的实现如下:

3.1 设置多房间模式

必须在初始化 SDK 之前,将房间模式 ZegoAPIRoomMode 设置为多房间模式 “ ZEGOAPI_ROOM_MODE_MULTI_ROOM”。

// 设置房间模式为多房间模式
[ZegoLiveRoomApi setRoomMode:ZegoAPIRoomMode::ZEGOAPI_ROOM_MODE_MULTI_ROOM];

如果在没有开通多房间功能的情况下设置多房间模式,登录房间会失败报错,返回错误码为“62001016”。

3.2 登录房间

3.2.1 设置房间配置信息

  • 设置房间配置信息

调用 setRoomConfig 接口设置允许观众创建房间以及用户状态更新回调,在房间创建之前设置有效,多房间模式下必须带上房间 ID。

bool audienceCreateRoom = true;
bool userStateUpdate = false;
[api setRoomConfig:audienceCreateRoom userStateUpdate:userStateUpdate room:@"roomID"];
  • 设置房间最大在线人数

调用 setRoomMaxUserCount 接口设置房间最大在线人数,在房间创建之前设置有效,多房间模式下必须传入房间 ID。

[api setRoomMaxUserCount:100 room:@"roomid"];
  • 设置 Token

调用 setToken 接口设置房间的鉴权 Token,Token 的生成规则请参考 用户权限控制

在 Token 快要过期的前 30s,会收到 onTokenWillExpired 回调通知。重新生成 Token 后再调用 setToken 接口设置。

NSString *token = @"create token"; 
[api setToken:token room:@"roomid"];

3.2.2 注册房间回调接口

在登录房间前,注册房间相关的接口。

unsigned int  appID = 1;
NSData *appSign;
// 创建 ZegoLiveRoomApi 的单例对象
ZegoLiveRoomApi *api = [ZegoLiveRoomApi alloc] initWithAppID:appID appSignature:appSign;
// 当前对象实现 IRoomCallback 类
[api setRoomDelegate:self];

房间相关的所有回调接口都会带上房间 ID 参数,用于区分是哪个房间的回调。相关回调如下:

  • onKickOut :用户被踢出房间通知,会停止该用户在房间的推拉流。
// 参数 roomID 表示房间 ID
- (void)onKickOut:(int)reason roomID:(NSString *)roomID customReason:(NSString *)customReason;
  • onDisconnect :客户端与 server 断开通知,会停止该房间的推拉流。
// 参数 roomID 表示房间 ID
- (void)onDisconnect:(int)errorCode roomID:(NSString *)roomID;
  • onTempBroken :客户端与 server 的连接被动断开通知,不会停止该房间的推拉流。
// 参数 roomID 表示房间 ID
- (void)onTempBroken:(int)errorCode roomID:(NSString *)roomID;
  • onReconnect :客户端与 server 重连成功通知,不会停止该房间的推拉流。
// 参数 roomID 表示房间 ID
- (void)onReconnect:(int)errorCode roomID:(NSString *)roomID;

3.2.3 登录房间

传入房间 ID 等参数,调用 loginRoom 接口登录房间。

  • 单房间模式下,同一时间只能登录一个房间,调用 loginRoom 接口时,如果之前已经登录其他房间,SDK 内部会自动退出之前的房间,然后登录新房间。
  • 多房间模式下,同一时间可以登录多个房间,当超过最大房间个数后,会返回错误码“52005022”。
[api loginRoom:@"roomID" role:1 withCompletionBlock:^(int errorCode, NSArray<ZegoStream*> *streamList){}];

3.3 推流

传入房间 ID 等参数,调用 startPublishWithParams 接口在指定房间内推流。

ZegoAPIPublishStreamParams *params = [ZegoAPIPublishStreamParams new];
params.streamID = @"streamid";
params.streamTitle = @"title";
params.extraInfo = @"";
params.publishFlag = ZegoAPIPublishFlag::ZEGOAPI_JOIN_PUBLISH;
params.publishParams = @"";
params.channelIndex = ZegoAPIPublishChannelIndex::ZEGOAPI_CHN_MAIN;
params.roomID = @"roomid";

[api startPublishingWithParams:params];

多房间模式下,不支持 startPublishing 和 startPublishing2 接口,请使用 startPublishWithParams,必须指定关联的房间 ID。

3.4 拉流

传入房间 ID 等参数,调用 startPlayingStreamWithParams 接口在指定房间内拉流。

ZegoAPIPlayStreamParams *params = [ZegoAPIPlayStreamParams new];
params.streamID = @"streamid";
params.displayView = view; // display view
params.extraInfo = nil; // extra info
params.roomID = @"roomid";

api startPlayingStreamWithParams:params];

多房间模式下,不支持 startPlayingStream 接口,请使用 startPlayingStreamWithParams,必须指定关联的房间 ID。

3.5 发送、接收实时消息

  • 广播消息

调用 sendRoomMessage 接口发送广播消息,房间其他用户通过 onRecvRoomMessage 回调接收消息,可通过房间 ID 来区分是哪个房间发送的。

// 发送
[api sendRoomMessage:@"content" type:ZegoMessageType::ZEGO_TEXT category:ZegoMessageCategory::ZEGO_CHAT completion:^(int errorCode, NSString *roomId, unsigned long long messageId){}];

// 房间其他人收到消息,通过房间 ID 来区分是哪个房间发送的
- (void)onRecvRoomMessage:(NSString *)roomId messageList:(NSArray<ZegoRoomMessage*> *)messageList;
  • 弹幕消息

弹幕消息,主要用于大并发的场景,发送一些非必须到达的消息。

调用 sendBigRoomMessage 接口发送弹幕消息,房间其他用户通过 onRecvBigRoomMessage 回调接收消息,可通过房间 ID 来区分是哪个房间发送的。

// 发送
[api sendBigRoomMessage:@"content" type:ZegoMessageType::ZEGO_TEXT category:ZegoMessageCategory::ZEGO_CHAT completion:^(int errorCode, NSString *roomId, NSString *messageId){}];

// 房间其他人收到消息,通过房间 ID 来区分是哪个房间发送的
- (void)onRecvBigRoomMessage:(NSString *)roomId messageList:(NSArray<ZegoBigRoomMessage*> *)messageList;
  • 自定义信令

自定义信令,指定房间里的用户(可以指定多个),发送特定的消息。

调用 sendCustomCommand 接口发送自定义信令,房间其他用户通过 onReceiveCustomCommand 回调接收消息,可通过房间 ID 来区分是哪个房间发送的。

// 发送
NSArray<ZegoUser*> *memberList = [NSMutableArray new];
...
[api sendCustomCommand:memberList content:@"content" room:@"roomid" completion:^)(int errorCode, NSString *roomID){}];

// 接收
- (void)onReceiveCustomCommand:(NSString *)fromUserID userName:(NSString *)fromUserName content:(NSString*)content roomID:(NSString *)roomID;
  • 房间附加信息

调用 setRoomExtraInfo 接口发送房间附加信息,房间其他用户通过 onRoomExtraInfoUpdated 回调接收消息,可通过房间 ID 来区分是哪个房间发送的。

// 发送,一个房间内只允许 1 个 key 
[api setRoomExtraInfo:@"key" value:@"value" room:@"roomid" completion:^(int errorCode, NSString *roomId,NSString *key){}];

// 接收,ZegoLiveRoomExtraInfoDelegate
- (void)onRoomExtraInfoUpdated:(NSString *)roomId roomExtraInfoList:(NSArray<ZegoRoomExtraInfo *> *)roomExtraInfoList;

发送实时消息的大小和频率限制可参考 限制说明

3.6 退出房间

传入房间 ID ,调用 logoutRoom 接口退出房间。

  • 单房间模式下,退出房间,同时会停止所有的推拉流。
  • 多房间模式下,退出房间必须传入房间 ID,只会退出指定房间,并停止该房间的推拉流。
[api logoutRoom:@"roomid"];

4 API 参考列表

方法 描述
+ setRoomMode: 设置房间模式
- loginRoom:role:withCompletionBlock: 登录房间
- logoutRoom: 退出房间
- setRoomDelegate: 设置直播房间相关信息通知的回调
- setRoomConfig:userStateUpdate:room: 设置房间配置信息
- setToken:room: 设置房间的鉴权 token
- setRoomMaxUserCount:room: 设置房间最大在线人数
- sendCustomCommand:content:room:completion: 发送自定义信令
- setIMDelegate 设置 IM 信息通知的回调对象
- sendRoomMessage:type:category:room:completion: 发送房间消息
- sendBigRoomMessage:type:category:room:completion: 发送不可靠信道消息
- startPlayingStreamWithParams: 播放多媒体流
– startPublishWithParams: 开始直播
- setRoomExtraInfoUpdateDelegate: 设置 RoomExtraInfo 通知的回调
- setRoomExtraInfo:value:completion: 更新房间属性 登录房间成功后使用

5 常见问题

1. 调用 setRoomMode 接口返回失败,是什么原因?

  • 是否在初始化 SDK 之前调用 setRoomMode 接口。
  • 是否特殊编包,带有 loginMultiRoom 接口是无法开启多房间模式的。
  • 是否特殊编包,无房间模式是无法开启多房间模式的。
  • 是否传入正确的参数。

2. 调用 loginRoom 登录失败,错误码为 “62001016”。是什么原因?

在没有开通多房间功能的情况下设置了多房间模式,登录房间会失败,返回错误码 62001016。

3. 调用 loginRoom 登录失败,错误码为 “52005022”。是什么原因?

同时登录的房间数超过最大房间个数后会返回错误码 52005022。目前默认最多同时加入 5 个房间,如有更多需求,请联系 ZEGO 技术支持提供扩展能力。