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.
Agora provides the following open-source sample projects on GitHub. You can download them and refer to the source code.
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:
createAgoraRtcEngine
and initialize
to create and initialize IRtcEngine
.setChannelProfile
to set the channel profile as live streaming.createChannel
to create an IChannel
object with channelId
.setChannelEventHandler
of the IChannel
class to receive the callbacks in this channel.joinChannel
of the IChannel
class to join the channel.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.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.publish
of the IChannel
class, ensure that the user role is set as host by calling setClientRole
.IChannel
channel, and you must call unpublish
before publishing the local stream to another channel.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:
The following code demonstrates how to join an IRtcEngine
channel and an IChannel
channel, and publish the local stream in the IRtcEngine
channel.
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);
Enable the video module.
m_rtcEngine->enableVideo();
Set the channel profile as live streaming.
m_rtcEngine->setChannelProfile(CHANNEL_PROFILE_LIVE_BROADCASTING);
Set the usr role as host.
m_rtcEngine->setClientRole(CLIENT_ROLE_BROADCASTER);
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);
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);
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);
Leave and destroy IChannel
.
pChannel->leaveChannel();
pChannel->release();
Leave the IRtcEngine
channel, and destroy the IRtcEngine
object.
m_rtcEngine->leaveChannel();
m_rtcEngine->release(true);
If you set autoSubscribeAudio
or autoSubscribeVideo
as false, the method call of muteRemoteAudioStream
or muteRemoteVideoStream
does not take effect after joining an IChannel
channel.
joinChannel
in the IChannel
class provides the media subscription options (autoSubscribeAudio
and autoSubscribeVideo
) to determine whether to susbcribe to the remote streams after joining the channel. The default setting is to subscribe to all the streams automatically.If you need to subscribe to streams of specified users after joining an IChannel
channel, refer to the following steps:
setDefaultMuteAllRemoteAudioStreams(true)
or setDefaultMuteAllRemoteVideoStreams(true)
in the IChannel
class to not receive any audio or video streams.joinChannel
with default media subscription options to join the channel.muteRemoteAudioStream(false)
or muteRemoteVideoStream(false)
to subscribe to streams of the specified users.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.
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:
IRtcEngine
class, the SDK publishes the local stream by default.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)
:
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.IRtcEngine
and IChannel
classes:IRtcEngine
class, and Channel 2 using the IChannel
class, you cannot call publish
in the IChannel
class.IRtcEngine
class, and Channel 2 through the IChannel
class, you cannot call publish
in the IChannel
class.publish
method in the IChannel
class as an audience member.publish
in the IChannel
class, you need to call unpublish
in the IChannel
class. Otherwise, you cannot call joinChannel
in the IRtcEngine
class.