Join multiple channels

Understand the tech

RTC SDK's multi-channel functionality is based on two key components:

• RtcConnection

  The RtcConnection object identifies a connection. It contains the following information:

  • Channel name
  • User ID of the local user

  You create multiple RtcConnection objects, each with a different channel name and user ID. Each RtcConnection instance can independently publish multiple audio streams and a single video stream.

• RtcEngineEx

  The class contains methods tailored for interacting with a designated RtcConnection object.

  To join multiple channels, you call joinChannelEx method in the RtcEngineEx class multiple times, using a different RtcConnection instance each time.

When joining multiple channels:

• Ensure that the user ID for each RtcConnection object is unique and nonzero.

• Configure publishing and subscribing options for the RtcConnection object in joinChannelEx.

• Pass the IRtcEngineEventHandler object to the eventHandler parameter when calling the joinChannelEx method to receive multiple channel-related event notifications.

Prerequisites

Ensure that you have implemented the SDK quickstart in your project.

Implementation

This section explains how to join a second channel as a host after you have already joined the first channel.

1. Declare variables for RtcEngineEx and RtcConnection objects.

   Java

   Kotlin

   private RtcEngineEx engine;
   private RtcConnection rtcConnection2 = new RtcConnection();

2. Initialize the engine instance.

   Java

   Kotlin

   engine = (RtcEngineEx) RtcEngine.create(config);

3. Join the channel using a random user ID.

   Java

   Kotlin

   private boolean joinSecondChannel() {
      ChannelMediaOptions option = new ChannelMediaOptions();
      mediaOptions.autoSubscribeAudio = true;
      mediaOptions.autoSubscribeVideo = true;
      rtcConnection2.channelId = "channel-2";
      rtcConnection2.localUid = new Random().nextInt(512)+512;
      int ret = engine.joinChannelEx("your token", rtcConnection2, mediaOptions,
        iRtcEngineEventHandler2);
      return (ret == 0);
    }

4. Listen for events in rtcConnection2 and set up the remote video in the onUserJoined callback.

   Java

   Kotlin

   private final IRtcEngineEventHandler iRtcEngineEventHandler2 = new IRtcEngineEventHandler() {
     @Override
     public void onJoinChannelSuccess(String channel, int uid, int elapsed) {
       Log.i(TAG, String.format("channel2 onJoinChannelSuccess channel %s uid %d", channel2, uid));
       showLongToast(String.format("onJoinChannelSuccess channel %s uid %d", channel2, uid));
     }
     @Override
     public void onUserJoined(int uid, int elapsed) {
       Log.i(TAG, "channel2 onUserJoined->" + uid);
       showLongToast(String.format("user %d joined!", uid));
       Context context = getContext();
       if (context == null) {
         return;
       }
       handler.post(() ->
       {
         // Display the remote video stream
         SurfaceView surfaceView = null;
         if (fl_remote2.getChildCount() > 0) {
           fl_remote2.removeAllViews();
         }
         // Create the rendering view through RtcEngine
         surfaceView = new SurfaceView(context);
         surfaceView.setZOrderMediaOverlay(true);
         // Add the view to the remote container
         fl_remote2.addView(surfaceView, new FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));
   
         // Set the remote view
         engine.setupRemoteVideoEx(new VideoCanvas(surfaceView, RENDER_MODE_FIT, uid), rtcConnection2);
       });
     }
   };

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Sample project

Agora provides the JoinMultipleChannels open-source sample project for your reference. Download the project or view the source code for a more detailed example.

API reference

• RtcEngineEx
• RtcConnection
• joinChannelEx
• setupRemoteVideoEx

Understand the tech

RTC SDK's multi-channel functionality is based on two key components:

• AgoraRtcConnection

  The AgoraRtcConnection object identifies a connection. It contains the following information:

  • Channel name
  • User ID of the local user

  You create multiple AgoraRtcConnection objects, each with a different channel name and user ID. Each AgoraRtcConnection instance can independently publish multiple audio streams and a single video stream.

• AgoraRtcEngineKit(Ex)

  The class contains methods tailored for interacting with a designated AgoraRtcConnection object.

  To join multiple channels, you call joinChannelExByToken method in the AgoraRtcEngineKit(Ex) class multiple times, using a different AgoraRtcConnection instance each time.

When joining multiple channels:

• Ensure that the user ID for each AgoraRtcConnection object is unique and nonzero.

• Configure publishing and subscribing options for the AgoraRtcConnection object in joinChannelExByToken.

• Pass the AgoraRtcEngineDelegate object to the delegate parameter when calling the joinChannelExByToken method to receive multiple channel-related event notifications.

Prerequisites

Ensure that you have implemented the SDK quickstart in your project.

Implementation

This section explains how to join a second channel as a host after you have already joined the first channel.

1. Define an AgoraRtcConnection object in your project's ViewController.swift file.

   let connection1 = AgoraRtcConnection()

2. Join the channel using a random user ID.

   var mediaOptions = AgoraRtcChannelMediaOptions()
   mediaOptions.autoSubscribeVideo = .of(true)
   mediaOptions.autoSubscribeAudio = .of(true)
   connection1.channelId = channelName1
   connection1.localUid = UInt.random(in: 1001...2000)
   var result = agoraKit.joinChannelEx(byToken: "your token", connection: connection1, delegate: channel1, mediaOptions: mediaOptions, joinSuccess: nil)
   channel1.channelId = channelName1
   channel1.connectionDelegate = self
   if result != 0 {
     self.showAlert(title: "Error", message: "joinChannel1 call failed: \(result), please check your params")
   }

3. Set up the remote video in the didJoinedOfUid callback.

   func rtcEngine(_ engine: AgoraRtcEngineKit, channelId: String, didJoinedOfUid uid: UInt, elapsed: Int) {
     LogUtils.log(message: "remote user join: \(uid) \(elapsed)ms", level: .info)
     // In this operation, only one remote video view is available
     // Here, we check if there's a view tagged with that UID
     let videoCanvas = AgoraRtcVideoCanvas()
     videoCanvas.uid = uid
     // The view to be bound
     videoCanvas.view = channelId == channelName1 ? channel1RemoteVideo.videoView : channel2RemoteVideo.videoView
     videoCanvas.renderMode = .hidden
     let connection = AgoraRtcConnection()
     agoraKit.setupRemoteVideoEx(videoCanvas, connection: connection)
   }

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Sample project

Agora offers the JoinMultiChannels open-source sample project for your reference. Download the project or view the source code for a more detailed example.

API reference

• AgoraRtcEngineKit
• AgoraRtcConnection
• joinChannelExByToken [1/2]
• setupRemoteVideoEx

Understand the tech

RTC SDK's multi-channel functionality is based on two key components:

• AgoraRtcConnection

  The AgoraRtcConnection object identifies a connection. It contains the following information:

  • Channel name
  • User ID of the local user

  You create multiple AgoraRtcConnection objects, each with a different channel name and user ID. Each AgoraRtcConnection instance can independently publish multiple audio streams and a single video stream.

• AgoraRtcEngineKit(Ex)

  The class contains methods tailored for interacting with a designated AgoraRtcConnection object.

  To join multiple channels, you call joinChannelExByToken method in the AgoraRtcEngineKit(Ex) class multiple times, using a different AgoraRtcConnection instance each time.

When joining multiple channels:

• Ensure that the user ID for each AgoraRtcConnection object is unique and nonzero.

• Configure publishing and subscribing options for the AgoraRtcConnection object in joinChannelExByToken.

• Pass the AgoraRtcEngineDelegate object to the delegate parameter when calling the joinChannelExByToken method to receive multiple channel-related event notifications.

Prerequisites

Ensure that you have implemented the SDK quickstart in your project.

Implementation

This section explains how to join a second channel as a host after you have already joined the first channel.

1. Define an AgoraRtcConnection object in your project's ViewController.swift file.

   let connection1 = AgoraRtcConnection()

2. Join the channel using a random user ID.

   var mediaOptions = AgoraRtcChannelMediaOptions()
   mediaOptions.autoSubscribeVideo = .of(true)
   mediaOptions.autoSubscribeAudio = .of(true)
   connection1.channelId = channelName1
   connection1.localUid = UInt.random(in: 1001...2000)
   var result = agoraKit.joinChannelEx(byToken: "your token", connection: connection1, delegate: channel1, mediaOptions: mediaOptions, joinSuccess: nil)
   channel1.channelId = channelName1
   channel1.connectionDelegate = self
   if result != 0 {
     self.showAlert(title: "Error", message: "joinChannel1 call failed: \(result), please check your params")
   }

3. Set up the remote video in the didJoinedOfUid callback.

   func rtcEngine(_ engine: AgoraRtcEngineKit, channelId: String, didJoinedOfUid uid: UInt, elapsed: Int) {
     LogUtils.log(message: "remote user join: \(uid) \(elapsed)ms", level: .info)
     // In this operation, only one remote video view is available
     // Here, we check if there's a view tagged with that UID
     let videoCanvas = AgoraRtcVideoCanvas()
     videoCanvas.uid = uid
     // The view to be bound
     videoCanvas.view = channelId == channelName1 ? channel1RemoteVideo.videoView : channel2RemoteVideo.videoView
     videoCanvas.renderMode = .hidden
     let connection = AgoraRtcConnection()
     agoraKit.setupRemoteVideoEx(videoCanvas, connection: connection)
   }

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Sample project

Agora offers the JoinMultiChannels open-source sample project for your reference. Download the project or view the source code for a more detailed example.

API reference

• AgoraRtcEngineKit
• AgoraRtcConnection
• joinChannelExByToken [1/2]
• setupRemoteVideoEx

Understand the tech

RTC SDK's multi-channel functionality is based on two key components:

• RtcConnection

  The RtcConnection object identifies a connection. It contains the following information:

  • Channel name
  • User ID of the local user

  You create multiple RtcConnection objects, each with a different channel name and user ID. Each RtcConnection instance can independently publish multiple audio streams and a single video stream.

• IRtcEngineEx

  The class contains methods tailored for interacting with a designated RtcConnection object.

  To join multiple channels, you call joinChannelEx method in the IRtcEngineEx class multiple times, using a different RtcConnection instance each time.

When joining multiple channels:

• Ensure that the user ID for each RtcConnection object is unique and nonzero.

• Configure publishing and subscribing options for the RtcConnection object in joinChannelEx.

• Pass the IRtcEngineEventHandler object to the eventHandler parameter when calling the joinChannelEx method to receive multiple channel-related event notifications.

Prerequisites

Ensure that you have implemented the SDK quickstart in your project.

Implementation

This section explains how to join a second channel as a host after you have already joined the first channel.

1. Define a connection and join the channel using a random user ID.

   agora::rtc::ChannelMediaOptions options2;
   options2.autoSubscribeAudio = false;
   options2.autoSubscribeVideo = false;
   options2.publishAudioTrack = false;
   options2.publishCameraTrack = false;
   options2.publishSecondaryCameraTrack = true;
   options2.clientRoleType = CLIENT_ROLE_BROADCASTER;
   // Define the connection
   connection.localUid = generateUid();
   connection.channelId = szChannelId.data();
   // Join the channel
   int ret = m_rtcEngine->joinChannelEx(APP_TOKEN, connection, options2, &m_camera2EventHandler);

2. Listen for the onUserJoined callback and set up the remote video.

   // Listen for the onUserJoined callback
   void CAGEngineEventHandler::onUserJoined(uid_t uid, int elapsed) {
     LPAGE_USER_JOINED lpData = new AGE_USER_JOINED;
   
     lpData->uid = uid;
     lpData->elapsed = elapsed;
   
     if (m_hMainWnd != NULL)
       ::PostMessage(m_hMainWnd, WM_MSGID(EID_USER_JOINED), (WPARAM)lpData, 0);
   }

3. Set up the remote video

   VideoCanvas canvas;
   canvas.renderMode = RENDER_MODE_FIT;
   canvas.uid = 123;
   canvas.view = videoWnd.GetSafeHwnd();
   
   connection.localUid = 123;
   connection.channelId = "channel123";
   
   // Set up the remote video
   rtcEngine->setupRemoteVideoEx(canvas, connection);

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Sample project

Agora provides the MultiChannels open-source sample project for your reference. Download the project or view the source code for a more detailed example.

API reference

• RtcEngineEx
• RtcConnection
• joinChannelEx
• setupRemoteVideoEx

Understand the tech

RTC SDK's multi-channel functionality is based on two key components:

• RtcConnection

  The RtcConnection object identifies a connection. It contains the following information:

  • Channel name
  • User ID of the local user

  You create multiple RtcConnection objects, each with a different channel name and user ID. Each RtcConnection instance can independently publish multiple audio streams and a single video stream.

• IRtcEngineEx

  The class contains methods tailored for interacting with a designated RtcConnection object.

  To join multiple channels, you call JoinChannelEx method in the IRtcEngineEx class multiple times, using a different RtcConnection instance each time.

When joining multiple channels:

• Ensure that the user ID for each RtcConnection object is unique and nonzero.

• Configure publishing and subscribing options for the RtcConnection object in JoinChannelEx.

• Use the connection parameter in each callback to identify the corresponding channel.

Prerequisites

Ensure that you have implemented the SDK quickstart in your project.

Implementation

This section explains how to join a second channel as a host after you have already joined the first channel.

1. Join the second channel

   Call JoinChannelEx to join the second channel:

   ChannelMediaOptions options2 = new ChannelMediaOptions();
   // Automatically subscribe to remote audio
   options2.autoSubscribeAudio.SetValue(true);
   // Automatically subscribe to remote video
   options2.autoSubscribeVideo.SetValue(true);
   // Publish audio from the microphone
   options2.publishMicrophoneTrack.SetValue(true);
   // Publish video from the camera
   options2.publishCameraTrack.SetValue(true);
   // Set the user role to broadcaster
   options2.clientRoleType.SetValue(CLIENT_ROLE_TYPE.CLIENT_ROLE_BROADCASTER);
   // Join the second channel with a unique user ID
   ret = RtcEngine.JoinChannelEx(_token, new RtcConnection(_channelName, UID2), options2);
   Debug.Log("JoinChannelEx returns: " + ret);

2. Set up remote user video

   Listen for the OnUserJoined callback and call SetForUser to set up video rendering for the remote user:

   public override void OnUserJoined(RtcConnection connection, uint uid, int elapsed)
   {
     Debug.Log(string.Format("OnUserJoined uid: {0}, elapsed: {1}", uid, elapsed));
     // Create a view for the remote user
     var videoSurface = MakeImageSurface(uid.ToString());
     // Set up video rendering
     videoSurface.SetForUser(uid, connection.channelId, VIDEO_SOURCE_TYPE.VIDEO_SOURCE_REMOTE);
     // Callback when the Texture size changes
     videoSurface.OnTextureSizeModify += (int width, int height) =>
     {
       var transform = videoSurface.GetComponent<RectTransform>();
       if (transform)
       {
         // If rendering in a RawImage, set the RawImage size
         transform.sizeDelta = new Vector2(width / 2, height / 2);
         transform.localScale = Vector3.one;
       }
       else
       {
         // If rendering in a MeshRenderer, set the MeshRenderer size
         float scale = (float)height / (float)width;
         videoSurface.transform.localScale = new Vector3(-1, 1, scale);
       }
       Debug.Log("OnTextureSizeModify: " + width + " " + height);
     };
   }
   
   private static VideoSurface MakeImageSurface(string goName)
   {
     GameObject go = new GameObject { name = goName };
     // Add RawImage for rendering
     go.AddComponent<RawImage>();
     // Make the object draggable
     go.AddComponent<UIElementDrag>();
   
     var canvas = GameObject.Find("VideoCanvas");
     if (canvas != null)
     {
       go.transform.parent = canvas.transform;
       Debug.Log("Video view added");
     }
     else
     {
       Debug.Log("Canvas is null, video view not added");
     }
   
     // Set transform properties
     go.transform.Rotate(0f, 0f, 180f);
     go.transform.localPosition = Vector3.zero;
     go.transform.localScale = new Vector3(2f, 3f, 1f);
   
     // Add VideoSurface component
     var videoSurface = go.AddComponent<VideoSurface>();
     return videoSurface;
   }

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

API reference

• IRtcEngineEx
• RtcConnection
• JoinChannelEx
• VideoSurface
• OnUserJoined