Live streaming over multiple channels

Some special scenarios require live streaming over two or more separate channels. Depending on the scenario, the app joins both channels as host, both channels as audience, or one channel as host and the other as audience. For example, consider the case of an online singing contest, where hosts of different channels interact with each other. The audience receives streams from two channels while the contestants broadcast to both channels.

Agora Video SDK multi-channel live streaming allows you to join multiple channels at the same time and broadcast or receive live streaming over them. This page shows you how to implement two different multi-channel live streaming methods into your app using Video SDK. Choose the method that best fits your particular scenario.

Agora Video SDK provides the following approaches to implementing multi-channel live streaming:

• Channel media relay

  In channel media relay, one channel is used as the source channel from which live streaming is relayed to a second channel called the destination channel. The audience on the destination channel subscribes to the relayed media stream. A host can relay media stream to a maximum of four destination channels. Relaying media streams provides the following benefits:

  • All hosts in the channels can see and hear each other.
  • The audience in the channels can see and hear all hosts.

• Join multiple channels

  To join multiple channels, a host first sets up a primary channel and starts a live streaming event. The host then joins a second channel and publishes to the new channel. The audience joins either channel and subscribes to the host live streaming. The two channels are independent and users on one channels don't see users on the other channel. You can extend this functionality to join as many channels as required.

The following figure shows the workflow you need to implement to add multi-channel live streaming to your app:

To follow this procedure you must have implemented Get Started with Interactive Live Streaming.

In order to create the environment necessary to implement Agora multi-channel live streaming feature into your app, do the following:

• open the project you created in Get Started with Interactive Live Streaming.
• Contact support@agora.io to enable channel media relay.

This section shows you how to implement the following methods of multi-channel streaming:

• Channel media relay

• Join multiple channels

Choose the method that best suits your scenario and follow the step by step procedure.

In this example, you use a single Button to start and stop channel media relay.

To enable your users to start and stop relaying to another channel, add a Button to the user interface. In /app/res/layout/activity_main.xml, add the following code before </RelativeLayout>:

_9

<Button

_9

android:id="@+id/ChannelRelayButton"

_9

android:layout_width="wrap_content"

_9

android:layout_height="wrap_content"

_9

android:layout_below="@+id/LeaveButton"

_9

android:layout_alignEnd="@id/LeaveButton"

_9

android:layout_alignStart="@id/JoinButton"

_9

android:onClick="channelRelay"

_9

android:text="Start Channel Media Relay" />

You see an error in your IDE. This is because this layout refers to a method that you create later.

In your project, import the relevant libraries and declare the required variables.

1. Add the required libraries

   To implement media relay and access the UI elements, import the corresponding Agora and Android libraries. In /app/java/com.example.<projectname>/MainActivity, add the following to the list of import statements:

   
   

   _4

   import io.agora.rtc2.video.ChannelMediaInfo;

   _4

   import io.agora.rtc2.video.ChannelMediaRelayConfiguration;

   _4

   _4

   import android.widget.Button;

   
   

2. Declare the variables you need

   To store source and destination channel settings and manage channel relay, in /app/java/com.example.<projectname>/MainActivity, add the following variable declarations to the MainActivity class:

   
   

   _6

   private String destChannelName = "<name of the destination channel>";

   _6

   private String destChannelToken = "<access token for the destination channel>";

   _6

   private int destUid = 100; // User ID that the user uses in the destination channel.

   _6

   private String sourceChannelToken = "<access token for the source channel>"; // Generate with the channelName and uid = 0.

   _6

   private boolean mediaRelaying = false;

   _6

   private Button channelMediaButton;

   
   

3. Access the channel relay button

   In the onCreate method of the MainActivity class, add the following lines after setupVideoSDKEngine();:

   
   

   _1

   channelMediaButton = findViewById(R.id.ChannelRelayButton);

   
   

To enable app users to relay channel media to a destination channel, take the following steps:

1. Start or stop channel media relay

   When a user presses the button, the app starts relaying media from the source channel to the destination channel. If channel media relay is already running, the app stops it. To integrate this workflow, add the following method to the MainActivity class.

   
   

   _18

   public void channelRelay(View view) {

   _18

   _18

   if (mediaRelaying) {

   _18

   agoraEngine.stopChannelMediaRelay();

   _18

   } else {

   _18

   // Configure the source channel information.

   _18

   ChannelMediaInfo srcChannelInfo = new ChannelMediaInfo(channelName, sourceChannelToken, uid);

   _18

   ChannelMediaRelayConfiguration mediaRelayConfiguration = new ChannelMediaRelayConfiguration();

   _18

   mediaRelayConfiguration.setSrcChannelInfo(srcChannelInfo);

   _18

   _18

   // Configure the destination channel information.

   _18

   ChannelMediaInfo destChannelInfo = new ChannelMediaInfo(destChannelName, destChannelToken, destUid);

   _18

   mediaRelayConfiguration.setDestChannelInfo(destChannelName, destChannelInfo);

   _18

   _18

   // Start relaying media streams across channels

   _18

   agoraEngine.startChannelMediaRelay(mediaRelayConfiguration);

   _18

   }

   _18

   }

   
   

2. Monitor the channel media relay state

   To receive the state change notifications sent during media relay, you add a method to the IRtcEngineEventHandler. Your app responds to connection and failure events in the onChannelMediaRelayStateChanged event handler. In the MainActivity class, add the following method after private final IRtcEngineEventHandler mRtcEventHandler = new IRtcEngineEventHandler() {:

   
   

   _20

   @Override

   _20

   public void onChannelMediaRelayStateChanged(int state, int code) {

   _20

   // This example shows toast messages when the relay state changes,

   _20

   // a production level app needs to handle state change properly.

   _20

   switch (state) {

   _20

   case 1: // RELAY_STATE_CONNECTING:

   _20

   showMessage("Channel media relay connecting.");

   _20

   runOnUiThread(()-> channelMediaButton.setText("Connecting..."));

   _20

   break;

   _20

   case 2: // RELAY_STATE_RUNNING:

   _20

   mediaRelaying = true;

   _20

   showMessage("Channel media relay running.");

   _20

   runOnUiThread(()-> channelMediaButton.setText("Stop Channel Media Relay"));

   _20

   break;

   _20

   case 3: // RELAY_STATE_FAILURE:

   _20

   mediaRelaying = false;

   _20

   showMessage("Channel media relay failure. Error code: " + code);

   _20

   runOnUiThread(()-> channelMediaButton.setText("Start Channel Media Relay"));

   _20

   }

   _20

   }

   
   

3. Monitor channel media relay events

   To receive notifications of important channel relay events such as network disconnection, reconnection, and users joining channels, you add the onChannelMediaRelayEvent method to the IRtcEngineEventHandler. In the MainActivity class, add the following method after private final IRtcEngineEventHandler mRtcEventHandler = new IRtcEngineEventHandler() {:

   
   

   _13

   @Override

   _13

   public void onChannelMediaRelayEvent(int code) {

   _13

   switch (code) {

   _13

   case 0: // RELAY_EVENT_NETWORK_DISCONNECTED

   _13

   showMessage("User disconnected from the server due to a poor network connection.");

   _13

   break;

   _13

   case 1: // RELAY_EVENT_NETWORK_CONNECTED

   _13

   showMessage("Network reconnected");

   _13

   break;

   _13

   case 2: // RELAY_EVENT_PACKET_JOINED_SRC_CHANNEL

   _13

   showMessage("User joined the source channel");

   _13

   }

   _13

   }

   
   

The alternate approach to multi-channel live streaming is joining multiple channels. In this section, you learn how to implement joining a second channel in your app.

In this example, you use a single Button to join and leave a second channel. To add the Button, in /app/res/layout/activity_main.xml, add the following code before </RelativeLayout>:

_9

<Button

_9

android:id="@+id/secondChannelButton"

_9

android:layout_width="wrap_content"

_9

android:layout_height="wrap_content"

_9

android:layout_below="@+id/LeaveButton"

_9

android:layout_alignEnd="@id/LeaveButton"

_9

android:layout_alignStart="@id/JoinButton"

_9

android:onClick="joinSecondChannel"

_9

android:text="Join second channel" />

In your project, import the relevant libraries and declare the required variables.

1. Add the required libraries

   To connect to multiple channels and access the UI elements, import the corresponding Agora and Android libraries. In /app/java/com.example.<projectname>/MainActivity, add the following to the list of import statements:

   
   

   _4

   import io.agora.rtc2.RtcConnection;

   _4

   import io.agora.rtc2.RtcEngineEx;

   _4

   _4

   import android.widget.Button;

   
   

2. Declare the variables you need

   To join and manage a second channel, in /app/java/com.example.<projectname>/MainActivity, add the following declarations to the MainActivity class:

   
   

   _6

   private Button secondChannelButton;

   _6

   private RtcConnection rtcSecondConnection;

   _6

   private String secondChannelName = "<name of the second channel>";

   _6

   private int secondChannelUid = 100; // Uid for the second channel

   _6

   private String secondChannelToken = "<access token for the second channel>";

   _6

   private boolean isSecondChannelJoined = false; // Track connection state of the second channel

   
   

3. Enable the user to join another channel

   1. In the onCreate method of the MainActivity class, add the following lines after setupVideoSDKEngine();:

      
      

      _2

      secondChannelButton = findViewById(R.id.secondChannelButton);

      _2

      secondChannelButton.setEnabled(false);

      
      

   2. Enable this button when a user joins the initial channel. Add the following line to the joinChannel method after isJoined = true;:

      
      

      _1

      secondChannelButton.setEnabled(true);

      
      

To add multi-channel functionality to your app, take the following steps:

1. Use the multi-channel enabled RtcEngineEx interface

   In the Get Started code, the Agora Engine instance was declared as RtcEngine. To implement multi-channel functionality, you use the multi-channel interface of the Agora Engine RtcEngineEx. In order to switch to the multi-user interface, do the following:

   1. In the MainActivity class, replace the declaration private RtcEngine agoraEngine; with:

      
      

      _1

      private RtcEngineEx agoraEngine;

      
      

   2. In the setupVideoSDKEngine method, replace the line agoraEngine = RtcEngine.create(config); with the following:

      
      

      _1

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

      
      

2. Join a second channel

   When a user presses the button, the app joins a second channel. If the app is already connected to a second channel, it leaves the channel. To do this, add the following method to the MainActivity class.

   
   

   _27

   public void joinSecondChannel(View view) {

   _27

   _27

   if (isSecondChannelJoined) {

   _27

   agoraEngine.leaveChannelEx(rtcSecondConnection);

   _27

   _27

   } else {

   _27

   ChannelMediaOptions mediaOptions = new ChannelMediaOptions();

   _27

   _27

   if (audienceRole.isChecked()) { // Audience Role

   _27

   mediaOptions.autoSubscribeAudio = true;

   _27

   mediaOptions.autoSubscribeVideo = true;

   _27

   mediaOptions.clientRoleType = Constants.CLIENT_ROLE_AUDIENCE;

   _27

   } else { // Host Role

   _27

   mediaOptions.publishCameraTrack = true;

   _27

   mediaOptions.publishAudioTrack = true;

   _27

   mediaOptions.channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING;

   _27

   mediaOptions.clientRoleType = Constants.CLIENT_ROLE_BROADCASTER;

   _27

   }

   _27

   _27

   rtcSecondConnection = new RtcConnection();

   _27

   rtcSecondConnection.channelId = secondChannelName;

   _27

   rtcSecondConnection.localUid = secondChannelUid;

   _27

   _27

   agoraEngine.joinChannelEx(secondChannelToken, rtcSecondConnection, mediaOptions, secondChannelEventHandler);

   _27

   isSecondChannelJoined = true;

   _27

   }

   _27

   }

   
   

3. Receive callbacks from the second channel

   The IRtcEngineEventHandler implements channel callbacks. For the second channel, you create another instance of IRtcEngineEventHandler and register it with the Agora Engine when you join the channel using joinChannelEx. To create an instance named secondChannelEventHandler, add the following code to the MainActivity class:

   
   

   _40

   // Callbacks for the second channel

   _40

   private final IRtcEngineEventHandler secondChannelEventHandler = new IRtcEngineEventHandler() {

   _40

   @Override

   _40

   public void onJoinChannelSuccess(String channel, int uid, int elapsed) {

   _40

   showMessage(String.format("onJoinChannelSuccess channel %s uid %d", secondChannelName, uid));

   _40

   runOnUiThread(() -> {

   _40

   secondChannelButton.setText("Leave Second Channel");

   _40

   });

   _40

   }

   _40

   _40

   public void onLeaveChannel(RtcStats stats) {

   _40

   isSecondChannelJoined = false;

   _40

   showMessage("Left the channel " + secondChannelName);

   _40

   runOnUiThread(() -> {

   _40

   secondChannelButton.setText("Join Second Channel");

   _40

   });

   _40

   }

   _40

   _40

   @Override

   _40

   public void onUserJoined(int uid, int elapsed) {

   _40

   showMessage(String.format("user %d joined!", uid));

   _40

   _40

   // Create surfaceView for remote video

   _40

   remoteSurfaceView = new SurfaceView(getBaseContext());

   _40

   remoteSurfaceView.setZOrderMediaOverlay(true);

   _40

   _40

   FrameLayout container = findViewById(R.id.remote_video_view_container);

   _40

   _40

   // Add surfaceView to the container

   _40

   runOnUiThread(() -> {

   _40

   if (container.getChildCount() > 0) container.removeAllViews();

   _40

   container.addView(remoteSurfaceView);

   _40

   });

   _40

   _40

   // Setup remote video to render

   _40

   agoraEngine.setupRemoteVideoEx(new VideoCanvas(remoteSurfaceView,

   _40

   VideoCanvas.RENDER_MODE_HIDDEN, uid), rtcSecondConnection);

   _40

   remoteSurfaceView.setVisibility(View.VISIBLE);

   _40

   }

   _40

   };

   
   

4. Update the setupRemoteVideo method

   In this example, you display two remote videos from two different channels. To display a remote video in either frame, update the setupRemoteVideo method by doing the following:

   1. Replace the setupRemoteVideo(int uid) method with the following:

      
      

      _7

      private void setupRemoteVideo(int uid, FrameLayout container) {

      _7

      remoteSurfaceView = new SurfaceView(getBaseContext());

      _7

      remoteSurfaceView.setZOrderMediaOverlay(true);

      _7

      container.addView(remoteSurfaceView);

      _7

      agoraEngine.setupRemoteVideo(new VideoCanvas(remoteSurfaceView, VideoCanvas.RENDER_MODE_FIT, uid));

      _7

      remoteSurfaceView.setVisibility(View.VISIBLE);

      _7

      }

      
      

   2. To update the setupRemoteVideo method call, in onUserJoined under mRtcEventHandler, replace runOnUiThread(() -> setupRemoteVideo(uid)); with the following:

      
      

      _1

      runOnUiThread(() -> setupRemoteVideo(uid,findViewById(R.id.local_video_view_container)));

      
      

   3. For null safety, in onUserOffline under mRtcEventHandler, replace runOnUiThread(() -> remoteSurfaceView.setVisibility(View.GONE)); with the following:

      
      

      _3

      runOnUiThread(() -> {

      _3

      if (remoteSurfaceView != null) remoteSurfaceView.setVisibility(View.GONE);

      _3

      });

      
      

To ensure that you have implemented multi-channel live streaming into your app, follow the relevant testing procedure:

1. In Android Studio, open app/java/com.example.<projectname>/MainActivity and update appId, channelName and destChannelName.

2. Generate a temporary token in using appId and channelName. Use it to update token in MainActivity. Use the same values to generate another token and update sourceChannelToken.

3. Generate a third token in using appId and destChannelName. Use it to update destChannelToken in MainActivity.

4. In your browser, navigate to the Agora web demo and update App ID, Channel, and Token with the values for your temporary token, then click Join.

5. Repeat the previous step on a second device, but this time use appId, destChannelName, and destChannelToken to Join the channel.

6. Connect an Android device to your development device.

7. In Android Studio, click Run app. A moment later, you see the project installed on your device.

   If this is the first time you run your app, grant camera and microphone permissions.

8. Select Host and press Join. You see the video from the web browser demo app connected to channelName in the top frame of your Android device.

9. Press Start Channel Media Relay. You see the video from the web browser demo app connected to channelName relayed to the web browser demo app connected to destChannelName.

10. Press Stop Channel Media Relay. The media relaying is stopped.

1. In Android Studio, open app/java/com.example.<projectname>/MainActivity and update appId, channelName and secondChannelName.

2. Generate a temporary token in using appId and channelName. Use it to update token in MainActivity.

3. Generate a second token in using appId and secondChannelName. Use it to update secondChannelToken in MainActivity.

4. In your browser, navigate to the Agora web demo and update App ID, Channel, and Token with the values for your temporary token, then click Join.

5. Repeat the previous step on a second device, but this time use appId, secondChannelName, and secondChannelToken to Join the channel.

6. Connect an Android device to your development device.

7. In Android Studio, click Run app. A moment later, you see the project installed on your device.

   If this is the first time you run your app, grant camera and microphone permissions.

8. Select Audience

   1. Press Join. You see the video from the web browser demo app connected to channelName in the top frame of your Android device.
   2. Press Join Second Channel. You see the video from the web browser demo app connected to secondChannelName in the bottom frame of your Android device.
   3. Press Leave Second Channel and then Leave to exit both channels.

9. Select Host

   1. Press Join. You see the local video in the top frame of your Android device. The web browser demo app connected to channelName shows the video from your android device.
   2. Press Join Second Channel. You see the video from the web browser demo app connected to secondChannelName in the bottom frame of your Android device.
   3. Press Leave Second Channel to exit both channels.

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

• Ensure that each RtcConnection object has a unique user ID that is not 0.
• You can configure the publishing and subscribing options for the RtcConnection object in joinChannelEx.
• Each RtcConnection can publish multiple audio streams and a video stream simultaneously.

• RtcEngineEx
• joinChannelEx
• leaveChannelEx
• RtcConnection
• startChannelMediaRelay
• stopChannelMediaRelay
• updateChannelMediaRelay
• pauseAllChannelMediaRelay
• resumeAllChannelMediaRelay
• onChannelMediaRelayStateChanged
• onChannelMediaRelayEvent