Cross-channel media stream relay

Some special scenarios require cross-channel media stream forwarding functionality. Video SDK enables you to relay the media stream of a host, from a source channel, to multiple target channels simultaneously. This functionality allows you to realize the following interactions:

• The hosts publish and receive each other's audio and video streams while engaging in cross-channel real-time interaction.

• The audience receive all audio and video streams from hosts and watch multiple hosts interact at the same time.

Due to its real-time and interactive nature, this feature enriches live broadcasts and game-play, It is especially suitable for live scenes such as co-hosting PK and online choir. It provides the audience with a better viewing experience, while bringing more traffic and revenue to the hosts.

Information

Cross-channel media stream relay is included in Agora's policy of 10,000 free minutes every month. For usage beyond the free quota, please refer to Pricing.

• Ensure that you have implemented the SDK quickstart in your project.
• Contact technical support to activate the cross-channel media stream relay feature.

The following figure shows the workflow you implement to facilitate cross-channel media stream relay:

To implement cross-channel media stream relay in your app, take the following steps:

1. Start cross-channel media stream relay

   After joining a channel, call startOrUpdateChannelMediaRelay to configure the source and target channel information and start forwarding a media stream.

   
   

   _9

   // Configure source channel information

   _9

   ChannelMediaInfo srcChannelInfo = new ChannelMediaInfo(et_channel.getText().toString(), null, myUid);

   _9

   ChannelMediaRelayConfiguration mediaRelayConfiguration = new ChannelMediaRelayConfiguration();

   _9

   mediaRelayConfiguration.setSrcChannelInfo(srcChannelInfo);

   _9

   // Configure target channel information

   _9

   ChannelMediaInfo destChannelInfo = new ChannelMediaInfo(destChannelName, null, myUid);

   _9

   mediaRelayConfiguration.setDestChannelInfo(destChannelName, destChannelInfo);

   _9

   // Start cross-channel media stream relay

   _9

   engine.startOrUpdateChannelMediaRelay(mediaRelayConfiguration);

   
   
   information

   • Best practice is to set the UID of the source channel to 0, allowing the SDK to assign a random UID.
   • The source channel token in srcChannelInfo should be different from the one used when joining the source channel. Generate a new token using the source channel name and uid = 0.
   • For the destination channel, set the uid to 0, to allow the SDK to assign a random uid, or specify a uid, ensuring that it is different from all UIDs in the target channel.

2. Update media stream relay channels

   To forward the stream to multiple target channels or exit the current forwarding channel after staring channel media relay, call startOrUpdateChannelMediaRelay again to add or remove target channels for forwarding.

   Note

   The updated configuration completely replaces the previous configuration.

3. Pause or resume media stream relay

   To pause forwarding the media stream to all target channels, call pauseAllChannelMediaRelay.

   
   

   _3

   engine.pauseAllChannelMediaRelay();

   _3

   isPaused = true;

   _3

   pause.setText(R.string.resume);

   
   

   To resume forwarding the media stream to all target channels, call resumeAllChannelMediaRelay.

   
   

   _3

   engine.resumeAllChannelMediaRelay();

   _3

   isPaused = false;

   _3

   pause.setText(R.string.pause);

   
   

4. Stop cross-channel media stream relay

   To stop forwarding the media stream, call stopChannelMediaRelay. When forwarding stops, the host exits all target channels.

   
   

   _5

   engine.stopChannelMediaRelay();

   _5

   et_channel_ex.setEnabled(true);

   _5

   pause.setEnabled(false);

   _5

   join_ex.setText(getString(R.string.join));

   _5

   mediaRelaying = false;

   
   
   Note

   If this method fails, call leaveChannel to leave the channel and stop cross-channel media stream relay.

5. Monitor cross-channel media stream status

   During cross-channel media stream relay, the SDK reports changes in the status of media stream relay through the onChannelMediaRelayStateChanged callback. Implement the relevant business logic based on the status codes.

   
   

   _20

   public void onChannelMediaRelayStateChanged(int state, int code) {

   _20

   switch (state) {

   _20

   case RELAY_STATE_CONNECTING:

   _20

   mediaRelaying = true;

   _20

   handler.post(() -> {

   _20

   et_channel_ex.setEnabled(false);

   _20

   join_ex.setEnabled(true);

   _20

   join_ex.setText(getText(R.string.stop));

   _20

   showLongToast("channel media Relay connected.");

   _20

   });

   _20

   break;

   _20

   case RELAY_STATE_FAILURE:

   _20

   mediaRelaying = false;

   _20

   handler.post(() -> {

   _20

   showLongToast(String.format("channel media Relay failed at error code: %d", code));

   _20

   });

   _20

   default:

   _20

   break;

   _20

   }

   _20

   }

   
   

• In live broadcast scenarios, only users with the role of a host can call startOrUpdateChannelMediaRelay to initiate cross-channel media stream forwarding.
• startOrUpdateChannelMediaRelay must be called after successfully joining a channel, or it will result in an error.
• Within a single channel, multiple hosts can forward media streams. A single host can forward a media stream to up to 6 target channels.
• This feature does not support String type uid. If you need to use the cross-channel co-hosting feature, you must also use Integer type uid in regular co-hosting; otherwise, the cross-channel co-hosting feature will not work properly.

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

The main media stream forwarding states and their corresponding status codes are as follows:

Media stream forwarding status	status code
The source channel starts transmitting data to the target channel.	RELAY_STATE_RUNNING(2) and RELAY_OK(0)
Cross-channel media stream forwarding encounters an exception. You can troubleshoot based on the error code.	RELAY_STATE_FAILURE(3)
Media stream forwarding has stopped.	RELAY_STATE_IDLE(0) and RELAY_OK(0)

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

• startOrUpdateChannelMediaRelay
• stopChannelMediaRelay
• pauseAllChannelMediaRelay
• resumeAllChannelMediaRelay
• onChannelMediaRelayStateChanged
• ChannelMediaRelayConfiguration
• ChannelMediaInfo