加入多频道

功能描述

为方便用户同时加入多个频道，接收多个频道的音视频流，Agora RTC Native SDK 3.0.0 及以上版本支持多频道管理，且频道数量无限制。

该功能可应用于类似超级小班课的场景：将一个互动大班里的学生分到不同的小班，学生可以在小班内进行实时音视频互动。根据场景需要，你还可以给每个小班可以配备一名助教老师。

示例项目

我们在 GitHub 提供两个实现了多频道功能的开源示例项目，你可以前往下载体验，参考源代码。

• MultiChannel
• Breakout Class

实现方法

SDK 提供 IChannel 类和 IChannelEventHandler 类实现多频道控制。

你可以多次调用 createChannel，通过不同的 channelId 创建多个 IChannel 对象（对应多个频道），然后分别调用 IChannel 中的 joinChannel 方法加入对应的频道。

实现多频道功能的主要步骤如下：

1. 调用 createAgoraRtcEngine 和 initialize 方法，创建并初始化 IRtcEngine。
2. 调用 setChannelProfile方法，将频道场景设置为直播。
3. 调用 createChannel 方法，通过 channelId 创建一个 IChannel 对象。
4. 调用 IChannel 类的 setChannelEventHandler方法，接收该频道的回调通知。
5. 调用 IChannel 类的 setClientRole 设置用户角色。
6. 调用 IChannel 类的 joinChannel 方法加入频道。用户加入频道后，默认发布本地流并自动订阅频道内所有其他用户的流。你可以在加入频道时通过ChannelMediaOptions 设置发布和订阅状态，也可以在加入频道后通过 IChannel 类的 muteLocal 和 muteRemote 为前缀的方法修改发布和订阅状态。
7. 如果需要加入更多的频道，重复步骤 3、4、5、6。

API 调用时序

加入多个频道的 API 时序如下：

示例代码

下面的示例代码演示了如何通过 IChannel 类加入多频道，并在加入的第一个频道中发布本地流。

1. 创建并初始化 IRtcEngine 对象。

   m_rtcEngine = createAgoraRtcEngine();
   RtcEngineContext context;
   std::string strAppID = GET_APP_ID;
   context.appId = strAppID.c_str();
   m_eventHandler.SetMsgReceiver(m_hWnd);
   context.eventHandler = &m_eventHandler;
   int ret = m_rtcEngine->initialize(context);

2. 启用视频模块。

   m_rtcEngine->enableVideo();

3. 将频道场景设置为直播场景。

   m_rtcEngine->setChannelProfile(CHANNEL_PROFILE_LIVE_BROADCASTING);

4. 创建并获取 IChannel1 对象，并监听该频道的回调通知。

   IChannel * pChannel1 = static_cast<IRtcEngine2 *>(m_rtcEngine)->createChannel(szChannelId.c_str());
   ChannelEventHandler* pEvt = new ChannelEventHandler;
   pEvt->setMsgHandler(GetSafeHwnd());
   m_channels.emplace_back(szChannelId, pChannel1, pEvt);
   pChannel1->setChannelEventHandler(pEvt);

5. 设置用户角色为主播。

   pChannel1->setClientRole(CLIENT_ROLE_BROADCASTER);

6. 传入 token 和 channelId, 加入 IChannel1 对象的频道，SDK 会默认发布本地流并自动订阅所有远端流。

   ChannelMediaOptions options1;
   options1.autoSubscribeAudio = true;
   options1.autoSubscribeVideo = true;
   options1.publishLocalAudio = true;
   options1.publishLocalVideo = true;
   pChannel1->joinChannel(APP_TOKEN, "", 0, options1);

7. 创建并获取 IChannel2 对象，并监听该频道的回调通知。

   IChannel * pChannel2 = static_cast<IRtcEngine2 *>(m_rtcEngine)->createChannel(szChannelId.c_str());
   ChannelEventHandler* pEvt = new ChannelEventHandler;
   pEvt->setMsgHandler(GetSafeHwnd());
   m_channels.emplace_back(szChannelId, pChannel2, pEvt);
   pChannel2->setChannelEventHandler(pEvt);

8. 设置用户角色为观众，无发流权限。

   pChannel2->setClientRole(CLIENT_ROLE_AUDIENCE);

9. 传入 token 和 channelId, 加入 IChannel2 对象的频道。你需要设置 publishLocalAudio 和 publishLocalVideo 为 false，否则加入频道会失败。

   ChannelMediaOptions options2;
   options2.autoSubscribeAudio = true;
   options2.autoSubscribeVideo = true;
   options2.publishLocalAudio = false;
   options2.publishLocalVideo = false;
   pChannel2->joinChannel(APP_TOKEN, "", 0, options2)

10. 离开并销毁 IChannel2 对象的频道。

    info.channel2->leaveChannel();
    info.channel2->release();

11. 离开并销毁 IChannel1 对象的频道。

    info.channel1->leaveChannel();
    info.channel1->release();

12. 销毁 IRtcEngine 对象。

    m_rtcEngine->release(true);

API 参考

• createChannel
• IChannel 类
• IChannelEventHandler 类

开发注意事项

精细订阅限制

IChannel 中的 joinChannel 提供媒体订阅选项设置（autoSubscribeAudio 和 autoSubscribeVideo），可以控制在加入频道后是否自动订阅音频流和视频流，默认为自动订阅。在加入频道后，你也可以通过 muteRemoteAudioStream 或 muteRemoteAudioStream 修改订阅状态。

如果你需要在加入 IChannel 的频道时仅订阅指定用户的音频流或视频流，Agora 建议使用以下方法：

1. 调用 joinChannel 并在 ChannelMediaOptions 中设置 autoSubscribeAudio = false 或 autoSubscribeVideo = false 不订阅所有远端用户。
2. 在频道内，根据用户的选择，调用 muteRemoteAudioStream(uid,false) 或 muteRemoteVideoStream(uid,false) 订阅指定的远端用户。

设置远端视图

在视频场景中，如果远端用户是通过 IChannel 加入频道的，那么在设置远端视图时，还需要在 VideoCanvas 中指定该远端用户所在频道的 channelId，否则会无法渲染出远端视频画面。

发流限制

SDK 仅支持用户同一时间在一个频道内发布媒体流。Agora 推荐以观众角色加入无需发流的频道并在加入频道时设置 ChannelMediaOptions 中的 publishLocalAudio 和 publishLocalVideo 为 false。

在直播场景中，用户作为主播加入频道一后，SDK 默认发布本地流到频道一。如果用户需要加入频道二，则你需要根据实际场景修改发布状态：

• 如果用户无需在频道二发流，则 Agora 推荐用户作为观众（setClientRole(AUDIENCE)）加入频道二。
• 如果用户需要在频道二发流，则必须先停止当前的发布，再加入频道二。Agora 推荐先设置频道一的用户角色为观众（setClientRole(AUDIENCE)），再让用户作为主播（setClientRole(BROADCASTER)）加入频道二。

如果用户已在频道一内发流，并且在频道二内调用如下方法，则该方法会调用失败并返回 -5(ERR_REFUSED) 错误码。

• 在调用 joinChannel 方法加入频道二时使用 publishLocalAudio = true 和 publishLocalVideo = true。
• 在加入频道后调用 muteLocalAudioStream(false) 或 muteLocalVideoStream(false)。
• 调用 setClientRole(BROADCASTER)。

API 变更

自 3.4.5 版本起，IChannel 类有如下变更：

• 废弃 publish 和 unpublish，并新增 muteLocalAudioStream 和 muteLocalVideoStream 替代。加入频道后，你可以分别设置音频流和视频流的发布状态。IRtcEngine 类和 IChannel 类下的 muteLocalAudioStream 和 muteLocalVideoStream 分别控制各自频道的发布状态。
• 在 ChannelMediaOptions 中新增 publishLocalAudio 和 publishLocalVideo 成员，默认值为 true。你可以调用 joinChannel 加入频道并设置音视频流的发布状态。如果用户已在一个频道中发流，则不论用户是主播还是观众，都需要在加入其他频道时设置 publishLocalAudio 和 publishLocalVideo 为 false。否则，加入频道会失败。
• 调用 setClientRole(BROADCASTER) 默认发布本地流，无需再调用 publish。

在 3.4.5 之前版本中：

• 调用 IRtcEngine 类的 muteLocalAudioStream(true) 或 muteLocalVideoStream(true) 对 IRtcEngine 频道和 IChannel 频道都会生效。muteLocalAudioStream 和 muteLocalVideoStream 在加入频道前后调用均可生效。
• joinChannel 不可以设置本地流的发布状态。
• 调用 IChannel 类的 setClientRole(BROADCASTER) 不会发布本地流。你还需要调用 publish。