As of v3.0.0, the Agora Native 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
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
IChannel to join the channel.
The following are the major steps of implementing the multi-channel function:
initializeto create and initialize
setChannelProfileto set the channel profile as live streaming.
createChannelto create an
IChannelobject with a
IChannelclass to receive callbacks in this channel.
IChannelclass to set the user role.
IChannelclass to join the channel. After joining a channel, the user publishes the local streams and automatically subscribes to the streams of all the other users in the channel by default. You can set the publishing and subscribing states in
ChannelMediaOptionswhen joining a channel, and you can change the publishing and subscribing states in the methods with prefixes
IChannelclass after joining a channel.
Refer to the following API sequence to join multiple channels:
The following code demonstrates how to join an
IChannel channel, and then publish the local streams in the first channel.
Create and initialize
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.
Set the channel profile as interactive live streaming.
IChannel1 object, and listen for events in this channel.
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);
Set the user role as a host.
channelId to join the
IChannel1 channel. The SDK publishes the local streams and automatically subscribes to the streams of all the other users in the channel by default.
ChannelMediaOptions options1; options1.autoSubscribeAudio = true; options1.autoSubscribeVideo = true; options1.publishLocalAudio = true; options1.publishLocalVideo = true; pChannel1->joinChannel(APP_TOKEN, "", 0, options1);
IChannel2 object, and listen for events in this channel.
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);
Set the user role as an audience member. Note that audience members cannot publish local streams.
channelId to join the
IChannel2 channel. You need to set
false; otherwise, the user fails to join the channel.
ChannelMediaOptions options2; options2.autoSubscribeAudio = true; options2.autoSubscribeVideo = true; options2.publishLocalAudio = false; options2.publishLocalVideo = false; pChannel2->joinChannel(APP_TOKEN, "", 0, options2)
Leave and destroy the
Leave and destroy the
joinChannel in the
IChannel class provides the media-subscription options (
autoSubscribeVideo) that determine whether to automatically subscribe to the remote streams after joining the channel. The default setting is to subscribe to all the streams automatically. After a user joins a channel, you can change the subscribing state by calling
If you need to subscribe to the streams of specified users after joining an
IChannel channel, refer to the following steps:
autoSubscribeAudio = falseor
autoSubscribeVideo = falseof
ChannelMediaOptionsto unsubscribe from all remote users.
muteRemoteVideoStream(uid,false)to subscribe to specified remote users.
In video scenarios, if the remote user joins the channel using
IChannel, ensure that you specify the
channelId of the remote user in
VideoCanvas when setting the remote video view.
The SDK supports publishing local streams to only one channel at a time. Agora recommends setting the user role as an audience when joining a channel where the user do not need to publish streams, and setting
false when joining the channel.
In the interactive live streaming profile, if a user joins the first channel as a host, the SDK publishes local streams in the first channel by default. If the user needs to join a second channel, you need to change the publishing state according to your actual scenario:
setClientRole(AUDIENCE)) in the first channel and joining the second channel as a host (
If a user publishes local streams in a channel and you call the following methods in a second channel, the method call fails, and the SDK returns
publishLocalAudio = trueor
publishLocalVideo = truewhen joining the second channel.
muteLocalVideoStream(false)after joining the second channel.
As of v3.4.5, the
IChannel class changes as follows:
unpublish, and adds
muteLocalVideoStreaminstead. After joining a channel, you can set the publishing state of the audio stream and video stream separately.
IChannelclasses control the publishing state of each channel in their respective classes only.
ChannelMediaOptions. The default value is
true. You can call
joinChannelto join a channel and set the publishing state. If a user publishes streams in a channel, regardless of whether the user is a host or an audience member, they need to set
falsewhen joining other channels; otherwise, they fail to join the channel.
setClientRole(BROADCASTER), the local user publishes audio and video streams by default. You no longer need to call
Earlier than v3.4.5:
IRtcEnginetakes effect in channels created by both the
muteLocalVideoStreamtake effect when they are called before or after a user joins a channel.
joinChannelcannot set the publishing state of local streams.
IChannelclass does not publish local streams. You also need to call