多房间管理

更新时间: 2024/09/18 16:26:13

在娱乐社交与在线教育场景中,App 用户往往需要同时加入多个房间,接收多个房间的音视频流。网易云信 NERTC SDK 提供多房间管理功能,隔离多个房间的消息和回调,在跨房间连麦场景和超级小班课场景都可以实现更灵活的房间管理业务。

功能概述

在 V4.5.0 及后续版本中,NERTC SDK 支持多房间管理功能,App 用户可以同时加入多个房间,接收多个房间的音视频流,且房间数量无限制。

多房间管理功能通常用于以下场景:

  • 跨房间连麦与PK

    跨房间连麦场景中,主播 A 房间中的用户和主播 B 可以同时加入彼此的房间进行连麦,与主播们另外加入一个公共房间的方案相比,同时加入多房间方案可以避免房间切换的复杂操作,直播体验更加友好。

  • 超级小班课

    超级小班课场景中,教师端加入大班房间,通过 RTC 或旁路推流实现课程直播,大班房间中的学生们各自加入小班房间,教师端也同时登录小班房间与学生端进行实时音视频互动,回答学生提问或组织讨论。根据场景需要,也可以配备一名助教老师登录小组房间,协助维持课堂秩序或解答学生问题。

V5.3.0 及之后版本,子房间支持调用 IRtcChannel#setExternalVideoSourceIRtcChannel#pushExternalVideoFrame 设置外部视频输入,详细的使用方法请参见 自定义视频采集

V5.3.0 及之后版本,子房间支持调用 IRtcChannel#enableAudioVolumeIndication 监测子房间用户的实时音量,详细的使用方法请参见 监测发言者音量

注意事项

  • SDK 仅支持用户同一时间在一个房间内发布媒体流。如果用户已在房间 1 内发流,在房间 2 内调用发流相关方法时,这些方法会调用失败并返回 30005 错误码。
  • 您可以在直播场景或通信场景中使用多房间功能,且房间数量无限制。
  • 调用 IRtcEngine#leaveChannel 离开第一个加入的房间(主房间)时,会同时退出所有子房间。如果要离开单个子房间,请调用IRtcChannel#leaveChannel接口。

实现方法

多房间管理功能通过 IRtcChannel 类和 IRtcChannelEventHandler 类实现多房间控制。

通过 IRtcEngine 接口类的 joinChannel 方法加入第一个房间之后,如果需要同时加入其他房间,您可以多次调用 IRtcEngineEx 接口类的 createChannel,通过不同的 channel_name 创建多个 IRtcChannel 对象,每个 IRtcChannel 对象对应一个房间,然后分别调用 IRtcChannel 中的 joinChannel 方法加入对应的房间。

API 时序图

uml diagram

加入多房间

实现多房间功能的主要步骤如下:

  1. 初始化引擎。

    调用 createNERtcEngine 方法,创建引擎,并调用 initialize 方法初始化引擎。

  2. 创建并加入房间 1(主房间)。

    调用 IRtcEngine 接口类的 joinChannel 方法创建并加入房间 1。

  3. 创建并加入房间 2(子房间)。

    1. 调用 IRtcEngineEx 接口类的 createChannel 方法,通过 channel_name 创建一个 IRtcChannel 对象。
    2. 调用 IRtcChannel 类的 setChannelEventHandler 方法,接收房间 2 的回调通知。
    3. 调用 IRtcChannel 类的 joinChannel 方法加入房间。

    用户加入子房间后,音视频流的状态如下:

    • 音频:默认自动订阅房间内所有其他用户的音频流,但不发布本地音频流。如果您没有在其他房间发布音频流,您可以在加入房间后调用 IRtcChannel 类的 enableLocalAudio 方法,设置参数为 true,发布音频流。
    • 视频:默认不订阅房间内其他用户的视频流,也不发布本地视频流。您可以调用 IRtcChannel 类的相关接口,修改视频流的发布和订阅状态。
  4. 创建并加入其他子房间。

    如果需要加入更多的房间,重复步骤 3 即可。

    • 加入多个房间时,请确保每个房间的房间名不同。
    • 同一时间,本地的音视频流只能发布到一个房间。如果需要调整发流的状态,请参考多房间时修改发流状态
  5. 离开房间。

    离开主房间时,会自动离开所有子房间。离开房间时请务必注意您离开的是主房间还是子房间,选择对应接口类中的方法,以免误操作。

    例如本地用户加入了房间 1(主房间)、房间 2(子房间)、房间 3(子房间),用户可以随时离开任意一个子房间,不影响其他几个房间,但一旦离开了主房间,所有房间会自动离开。

    • 调用 IRtcChannel#leaveChannel 离开子房间。
    • 调用 IRtcEngine#leaveChannel 离开主房间。

修改发流状态

同一时间,本地的音视频流只能发布到一个房间。 如果用户加入房间 1 并在房间 1 中发布音频或视频流,后续在其他房间中无法发布流,调用发流相关方法会报错 30005。例如,如果用户加入房间 1 后,如果使用默认配置,加入房间后 SDK 自动采集并发送本地音频流到房间 1。后续即使以音频发送开启的状态加入其他房间,也只能在房间 1 中发流。

如果需要调整发流的状态,请在发流的房间中停止发布音频流或视频流,然后在需要发流的房间中,开始发布音频流或视频流即可。

示例代码

objective-c//加入房间。
rtc_engine_->joinChannel(token, channel_name, uid);

//创建子房间
nertc::IRtcChannel* channel_ = rtc_engine_->createChannel(channel_name2);

// 添加注册回调和事件。
channel_->setChannelEventHandler(channel_event_handler);
// 子房间加入房间。
channel_->joinChannel(token2, uid2);

// 继承 IRtcChannelEventHandler类中的回调与事件。
class ChannelEventHandler:public nertc::IRtcChannelEventHandler
{
public:
    ChannelEventHandler();
    virtual ~ ChannelEventHandler();
    
    // 注册 onJoinChannel回调。
    // 本地用户加入房间时,会触发该回调。
    virtual void onJoinChannel(nertc::channel_id_t   cid, 
                               nertc::uid_t          uid, 
                               nertc::NERtcErrorCode result, 
                               uint64_t              elapsed) override;
                               
    // 注册 onLeaveChannel 回调。
    // 本地用户成功离开房间时,会触发该回调。
    virtual void onLeaveChannel(nertc::NERtcErrorCode result) override;
}
// 离开子房间。
channel_->leaveChannel();

// 释放 IRtcChannel 对象。
channel_->release();
// 离开主房间。
rtc_engine_->leaveChannel();

// 释放 IRtcEngineEx 对象。
rtc_engine_->release();
此文档是否对你有帮助?
有帮助
去反馈
  • 功能概述
  • 注意事项
  • 实现方法
  • API 时序图
  • 加入多房间
  • 修改发流状态
  • 示例代码