Introduction

As of v3.0.0, the Agora RTC SDK enables users to join an unlimited number of channels at a time and to receive the audio and video streams of all the channels.

Sample project

Agora provides the following open-source sample projects on GitHub. You can download them and refer to the source code.

• MultiChannel
• Breakout Class

Implementation

The SDK uses the IChannel and IChannelEventHandler classes to support the multi-channel function.

You can call createChannel multiple times, to create multiple IChannel objects with different channelId, and then call joinChannel in IChannel to join the channel.

The following are the major steps of implementing the multi-channel function:

1. Call createAgoraRtcEngine and initializeto create and initialize IRtcEngine.
2. Call setChannelProfile to set the channel profile as live streaming.
3. Call createChannel to create an IChannel object with channelId.
4. Call setChannelEventHandler of the IChannel class to receive the callbacks in this channel.
5. Call joinChannel of the IChannel class to join the channel.
6. Choose either of the following ways to publish the local stream:
   • Publish the stream in an IRtcEngine channel: Call setClientRole of the IRtcEngine class to set the user role as host, and then call joinChannel to join the channel. The SDK automatically publishes the local stream after joining the channel. This method applies to scenarios where the local stream is published in a fixed channel.
   • Publish the stream in an IChannel channel: Call setClientRole of the IChannel class to set the user role as host, and then call publish to publish the local stream. This method applies to scenarios where the local stream needs to be published to different channels.
7. Repeat Step 3, 4, and 5 to join more channels.

API call sequence

Refer to the following API sequence to join multiple channels and publish the local stream in an IRtcEngine channel:

Refer to the following API sequence to join multiple channels and publish the local stream in an IChannel channel:

Sample code

The following code demonstrates how to join an IRtcEngine channel and an IChannel channel, and publish the local stream in the IRtcEngine channel.

1. Create and initialize 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. Enable the video module.

   m_rtcEngine->enableVideo();

3. Set the channel profile as live streaming.

   m_rtcEngine->setChannelProfile(CHANNEL_PROFILE_LIVE_BROADCASTING);

4. Set the usr role as host.

   m_rtcEngine->setClientRole(CLIENT_ROLE_BROADCASTER);

5. Pass in token and channelId to join the IRtcEngine channel. The SDK automatically publishes the local stream after joining the channel.

   m_rtcEngine->joinChannel(APP_TOKEN, ChannelId, "", 0)；

6. Create an IChannel object, and listen for events in this channel.

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

7. Join the IChannel channel. The SDK subscribes to audio and video streams when the user joins the channel by default.

   pChannel->joinChannel(APP_TOKEN, "", 0, options);

8. Leave and destroy IChannel.

   pChannel->leaveChannel();
   pChannel->release();

9. Leave the IRtcEngine channel, and destroy the IRtcEngine object.

   m_rtcEngine->leaveChannel();
   m_rtcEngine->release(true);

API reference

• createChannel
• IChannel
• IChannelEventHandler

Considerations

Subscription limits

If you set autoSubscribeAudio or autoSubscribeVideo as false, the method call of muteRemoteAudioStream or muteRemoteVideoStream does not take effect after joining an IChannel channel.

If you need to subscribe to streams of specified users after joining an IChannel channel, refer to the following steps:

1. Call setDefaultMuteAllRemoteAudioStreams(true) or setDefaultMuteAllRemoteVideoStreams(true) in the IChannel class to not receive any audio or video streams.
2. Call joinChannel with default media subscription options to join the channel.
3. Call muteRemoteAudioStream(false) or muteRemoteVideoStream(false) to subscribe to streams of the specified users.

Set the remote video view

In video scenarios, if the remote user joins the channel using IChannel, ensure that you specify the channel ID of the remote user in VideoCanvas when setting the remote video view.

Limits on publishing the stream

The SDK supports publishing one stream to only one channel at a time, and the default behavior differs after the method call of joinChannel in the IRtcEngine and IChannel classes:

• In the IRtcEngine class, the SDK publishes the local stream by default.
• In the IChannel class, the SDK does not publish the local stream.

You must meet the following requirements to implement the multi-channel function. Otherwise, the SDK returns ERR_REFUSED(5):

• When joining multiple channels using the joinChannel method in the IChannel class: After calling publish for Channel 1, you need to call unpublish for Channel 1 before calling publish for Channel 2.
• When joining multiple channels using both the IRtcEngine and IChannel classes:
  • In the communication profile, if you join Channel 1 using the IRtcEngine class, and Channel 2 using the IChannel class, you cannot call publish in the IChannel class.
  • In the live streaming profile, if you join Channel 1 using the IRtcEngine class, and Channel 2 through the IChannel class, you cannot call publish in the IChannel class.
  • In the live streaming profile, after joining multiple channels, you cannot call the publish method in the IChannel class as an audience member.
  • After calling publish in the IChannel class, you need to call unpublish in the IChannel class. Otherwise, you cannot call joinChannel in the IRtcEngine class.