多房间管理
更新时间: 2024/09/18 16:26:13
在娱乐社交与在线教育场景中,App 用户往往需要同时加入多个房间,接收多个房间的音视频流。网易云信 NERTC SDK 提供多房间管理功能,隔离多个房间的消息和回调,在跨房间连麦场景和超级小班课场景都可以实现更灵活的房间管理业务。
功能概述
在 V4.5.0 及后续版本中,NERTC SDK 支持多房间管理功能,App 用户可以同时加入多个房间,接收多个房间的音视频流,且房间数量无限制。
多房间管理功能通常用于以下场景:
-
跨房间连麦与PK
跨房间连麦场景中,主播 A 房间中的用户和主播 B 可以同时加入彼此的房间进行连麦,与主播们另外加入一个公共房间的方案相比,同时加入多房间方案可以避免房间切换的复杂操作,直播体验更加友好。
-
超级小班课
超级小班课场景中,教师端加入大班房间,通过 RTC 或旁路推流实现课程直播,大班房间中的学生们各自加入小班房间,教师端也同时登录小班房间与学生端进行实时音视频互动,回答学生提问或组织讨论。根据场景需要,也可以配备一名助教老师登录小组房间,协助维持课堂秩序或解答学生问题。
V5.3.0 及之后版本,子房间支持调用 INERtcChannel#setExternalVideoSource
和 INERtcChannel#pushExternalVideoFrame
设置外部视频输入,详细的使用方法请参见 自定义视频采集。
V5.3.0 及之后版本,子房间支持调用 INERtcChannel#enableAudioVolumeIndication
监测子房间用户的实时音量,详细的使用方法请参见 监测发言者音量。
V5.3.0 及之后版本,子房间支持调用 INERtcChannel#switchCamera
或 INERtcChannel#switchCameraWithPosition
切换摄像头,详细的使用方法请参见 视频设备管理。
注意事项
- SDK 仅支持用户同一时间在一个房间内发布媒体流。如果用户已在房间 1 内发流,在房间 2 内调用发流相关方法时,这些方法会调用失败并返回 30005 错误码。
- 您可以在直播场景或通信场景中使用多房间功能,且房间数量无限制。
- 调用
INERtcEngine#leaveChannel
离开第一个加入的房间(主房间)时,会同时退出所有子房间。如果要离开单个子房间,请调用INERtcChannel#leaveChannel
接口。
实现方法
多房间管理功能通过 INERtcChannel
类和 NERtcChannelDelegate
类实现多房间控制。
通过 INERtcEngine
接口类的 joinChannelWithToken
方法加入第一个房间之后,如果需要同时加入其他房间,可以多次调用 INERtcEngineEx
接口类的 createChannel
,通过不同的 channelName
创建多个 INERtcChannel
对象,每个 INERtcChannel
对象对应一个房间,然后分别调用 INERtcChannel
中的 joinChannelWithToken
方法加入对应的房间。
API 时序
加入多房间
实现多房间功能的主要步骤如下:
-
初始化引擎。
调用
setupEngineWithContext:
方法,创建并初始化引擎。 -
创建并加入房间 1(主房间)。
调用 [
INERtcEngine
] 接口类的joinChannelWithToken
方法创建并加入房间 1。 -
创建并加入房间 2(子房间)。
- 调用
INERtcEngineEx
接口类的createChannel
方法,通过channelName
创建一个INERtcChannel
对象。 - 调用
INERtcChannel
类的setChannelDelegate
方法,接收房间 1 的回调通知。 - 调用
INERtcChannel
类的joinChannelWithToken
方法加入房间。
加入子房间时,您可以设置单独的 uid,该 uid 可以跟主房间的 uid 不一样。
用户加入子房间后,音视频流的状态如下:
- 音频:默认自动订阅房间内所有其他用户的音频流,但不发布本地音频流。如果您没有在其他房间发布音频流,您可以在加入房间后调用
INERtcChannel
类的enableLocalAudio
方法,设置参数为true
,发布音频流。 - 视频:默认不订阅房间内其他用户的视频流,也不发布本地视频流。您可以调用
INERtcChannel
类的相关接口,修改视频流的发布和订阅状态。
- 调用
-
创建并加入其他房间。
如果需要加入更多的房间,重复步骤 3 即可。
- 加入多个房间时,请确保每个房间的房间名不同。
- 同一时间,本地的音视频流只能发布到一个房间。如果需要调整发流的状态,请参考多房间时修改发流状态。
-
离开房间。
离开主房间时,会自动离开所有子房间。离开房间时请务必注意您离开的是主房间还是子房间,选择对应接口类中的方法,以免误操作。
例如本地用户加入了房间 1(主房间)、房间 2(子房间)、房间 3(子房间),用户可以随时离开任意一个子房间,不影响其他几个房间,但一旦离开了主房间,所有房间会自动离开。
- 调用
INERtcChannel#leaveChannel
离开子房间。 - 调用
INERtcEngine#leaveChannel
离开主房间。
- 调用
修改发流状态
同一时间,本地的音视频流只能发布到一个房间。 如果用户加入房间 1 并在房间 1 中发布音频或视频流,后续在其他房间中无法发布流,调用发流相关方法会报错 30005。例如,如果用户加入房间 1 后,如果使用默认配置,加入房间后 SDK 自动采集并发送本地音频流到房间 1。后续即使以音频发送开启的状态加入其他房间,也只能在房间 1 中发流。
如果需要调整发流的状态,请在发流的房间中停止发布音频流或视频流,然后在需要发流的房间中,开始发布音频流或视频流即可。
示例代码
objective-c //初始化
NERtcEngine *coreEngine = [NERtcEngine sharedEngine];
NERtcEngineContext *context = [[NERtcEngineContext alloc] init];
// 设置通话相关信息的回调
context.engineDelegate = self;
// 设置当前应用的appKey
context.appKey = AppKey;
[coreEngine setupEngineWithContext:context];
// 加入主房间
[[NERtcEngine sharedEngine] joinChannelWithToken:token
channelName:roomId
myUid:userId
completion:^(NSError * _Nullable error, uint64_t channelId, uint64_t elapesd, uint64_t uid) {
if (error) {
//加入失败
} else {
//加入成功
//这里加入成功后,才能加入子房间。
}
}];
//加入子房间建前要保证已经加入了主房间
NERtcChannel *channel = [[NERtcEngine sharedEngine] createChannel:@"channelName"];
[channel joinChannelWithToken:token completion:^(NSError * _Nullable error, uint64_t channelId, uint64_t elapesd, uint64_t uid) {
if (error) {
//加入子房间失败
} else {
//加入子房间成功
}
}];