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.

• MultRtcChannel
• Breakout Class

Implementation

The SDK uses the RtcChannel and IRtcChannelEventHandler classes to support the multi-channel function.

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

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

1. Call create to create and initialize RtcEngine.
2. Call setChannelProfile to set the channel profile as live streaming.
3. Call createRtcChannel to create an RtcChannel object with channelId.
4. Call setRtcChannelEventHandler of the RtcChannel class to receive the callbacks in this channel.
5. Call joinChannel of the RtcChannel class to join the channel.
6. Choose either of the following ways to publish the local stream:
   • Publish the stream in an RtcEngine channel: Call setClientRole of the RtcEngine 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 RtcChannel channel: Call setClientRole of the RtcChannel 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 RtcEngine channel:

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

Sample code

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

1. Create and initialize RtcEngine.

   engine = RtcEngine.create(context.getApplicationContext(), getString(R.string.agora_app_id), iRtcEngineEventHandler);

2. Enable the video module.

   engine.enableVideo();

3. Set the channel profile as live streaming.

   engine.setChannelProfile(Constants.CHANNEL_PROFILE_LIVE_BROADCASTING);

4. Set the usr role as host.

   engine.setClientRole(IRtcEngineEventHandler.ClientRole.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.

   engine.joinChannel(accessToken, channelId, "Extra Optional Data", 0);

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

   rtcChannel = engine.createRtcChannel(channel2);
   rtcChannel.setRtcChannelEventHandler(new IRtcChannelEventHandler() {
            @Override
            // Listen for the onJoinChannelSuccess callback.
            // This callback occurs when the local user successfully joins the channel.
            public void onJoinChannelSuccess(RtcChannel rtcChannel, int uid, int elapsed) {
                super.onJoinChannelSuccess(rtcChannel, uid, elapsed);
                Log.i(TAG, String.format("onJoinChannelSuccess channel %s uid %d", channel2, uid));
            }
            @Override
            // Listen for the onUserJoinedcallback.
            // This callback occurs when a remote host joins a channel.
            public void onUserJoined(RtcChannel rtcChannel, int uid, int elapsed) {
                super.onUserJoined(rtcChannel, uid, elapsed);
                Log.i(TAG, "onUserJoined->" + uid);
            }
        });

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

   int ret = rtcChannel.joinChannel(null, "", 0, mediaOptions);
   return (ret == 0);

8. Leave and destroy RtcChannel.

   rtcChannel.leaveChannel();
   rtcChannel.destroy();

9. Leave the RtcEnginechannel, and destroy the RtcEngine object.

   engine.leaveChannel();``engine.destroy();

API reference

• createRtcChannel
• RtcChannel
• IRtcChannelEventHandler

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 RtcChannel channel.

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

1. Call setDefaultMuteAllRemoteAudioStreams(true) or setDefaultMuteAllRemoteVideoStreams(true) in the RtcChannel 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 RtcChannel, ensure that you specify the channel ID of the remote user in VideoCanvas when setting the remote video view.

// Set the remote user's view in the onUserJoined callback.
public void onUserJoined(RtcChannel rtcChannel, int uid, int elapsed) {
    super.onUserJoined(rtcChannel, uid, elapsed);
    Log.i(TAG, "onUserJoined->" + uid);
    showLongToast(String.format("user %d joined!", uid));
    Context context = getContext();
    if (context == null) {
        return;
    }
    handler.post(() ->
    {
        SurfaceView surfaceView = null;
        if (fl_remote2.getChildCount() > 0) {
            fl_remote2.removeAllViews();
        }
        // Create a SurfaceView object.
        surfaceView = RtcEngine.CreateRendererView(context);
        surfaceView.setZOrderMediaOverlay(true);
        // Add the SurfaceView object to the layout of remote users.
        fl_remote2.addView(surfaceView, new FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));
        // Set the remote video view.
        engine.setupRemoteVideo(new VideoCanvas(surfaceView, RENDER_MODE_FIT, channel2, uid));
    });
}

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 RtcEngine and RtcChannel classes:

• In the RtcEngine class, the SDK publishes the local stream by default.
• In the RtcChannel 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 RtcChannel 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 RtcEngine and RtcChannel classes:
  • In the communication profile, if you join Channel 1 using the RtcEngine class, and Channel 2 using the RtcChannel class, you cannot call publish in the RtcChannel class.
  • In the live streaming profile, if you join Channel 1 using the RtcEngine class, and Channel 2 through the RtcChannel class, you cannot call publish in the RtcChannel class.
  • In the live streaming profile, after joining multiple channels, you cannot call the publish method in the RtcChannel class as an audience member.
  • After calling publish in the RtcChannel class, you need to call unpublish in the RtcChannel class. Otherwise, you cannot call joinChannel in the RtcEngine class.