Skip to main content

You are looking at Interactive Live Streaming v3.x Docs. The newest version is  Interactive Live Streaming 4.x

Android
iOS
macOS
Windows C++
Windows C#
Unity
Flutter
React Native
Electron
Cocos Creator
Cocos2d-x

Co-host across Channels

Introduction

Co-hosting across channels refers to the process where the Agora SDK relays the media stream of a host from an interactive live streaming channel (source channel) to a maximum of four interactive live streaming channels (destination channels). It has the following benefits:

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

Co-hosting across channels applies to scenarios such as an online singing contest, where hosts of different channels interact with each other.

Sample project

Agora provides an open-source HostAcrossChannel sample project on GitHub. You can download the project to try it out or view the source code.

Implementation

To enable channel media relay, contact support@agora.io.

Before relaying media streams across channels, ensure that you have implemented the basic real-time communication functions in your project.

As of v2.9.0, the Agora Native SDK supports co-hosting across channels with the following methods:

  • startChannelMediaRelay
  • updateChannelMediaRelay
  • stopChannelMediaRelay

Once the channel media relay starts, the SDK relays the media streams of a host from the source channel to at most four destination channels.

During the relay, the SDK reports the states and events of the channel media relay with the onChannelMediaRelayStateChanged and onChannelMediaRelayEvent callbacks. Refer to the following codes and their corresponding states to implement your code logic:

State codesEvent codesThe media stream relay state
RELAY_STATE_RUNNING(2) and RELAY_OK(0)RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL(4)The channel media relay starts.
RELAY_STATE_FAILURE(3)/Exceptions occur for the media stream relay. Refer to the error parameter for troubleshooting.
RELAY_STATE_IDLE(0) and RELAY_OK(0)/The channel media relay stops.
  • Any host in an interactive live streaming channel can call the startChannelMediaRelay method to enable channel media stream relay. The SDK relays the media streams of the host who calls the method.
  • During the media stream relay, if the host of the destination channel drops offline or leaves the channel, the host of the source channel receives the onUserOffline callback.

API call sequence

Follow the API call sequence to implement your code logic:

1568962085119

Sample code


_26
// Initializes RtcEngine.
_26
engine = RtcEngine.create(context.getApplicationContext(), yourAppId, iRtcRngineEventHandler);
_26
_26
...
_26
_26
// Guides the user to set the destination channel name, and assigns the name to destChannelName.
_26
String destChannelName = et_channel_ex.getText().toString();
_26
if(destChannelName.length() == 0){
_26
showAlert("Destination channel name is empty!");
_26
}
_26
_26
// Configures the source channel information. For channelName, use the source channel name set by the user. For myUid, set it as 0.
_26
// Note that sourceChannelToken is different from the token used for joining the source channel. You need to generate sourceChannelToken with the source channel name and a uid of 0.
_26
ChannelMediaInfo srcChannelInfo = new ChannelMediaInfo(et_channel.getText().toString(), sourceChannelToken, myUid);
_26
ChannelMediaRelayConfiguration mediaRelayConfiguration = new ChannelMediaRelayConfiguration();
_26
mediaRelayConfiguration.setSrcChannelInfo(srcChannelInfo);
_26
_26
// Configures the destination channel information. Set destChannelName as the channel name set by the user. myUid is the user ID that the user uses in the destination channerl.
_26
ChannelMediaInfo destChannelInfo = new ChannelMediaInfo(destChannelName, destChannelToken, myUid);
_26
mediaRelayConfiguration.setDestChannelInfo(destChannelName, destChannelInfo);
_26
_26
// Calls startChannelMediaRelay to start relaying media streams across channels.
_26
engine.startChannelMediaRelay(mediaRelayConfiguration);
_26
_26
// Calls stopChannelMediaRelay to stop relaying media streams across channels.
_26
engine.stopChannelMediaRelay();


_16
// Uses the onChannelMediaRelayStateChanged callback to monitor the state of the channel media relay.
_16
public void onChannelMediaRelayStateChanged(int state, int code) {
_16
switch (state){
_16
case RELAY_STATE_CONNECTING:
_16
mediaRelaying = true;
_16
handler.post(() ->{
_16
showLongToast("channel media relay connected.");
_16
});
_16
break;
_16
case RELAY_STATE_FAILURE:
_16
mediaRelaying = false;
_16
handler.post(() ->{
_16
showLongToast(String.format("channel media relay failed at error code: %d", code));
_16
});
_16
}
_16
}

API reference

Considerations

  • The Agora Video SDK supports relaying media streams to a maximum of four destination channels. To add or delete a destination channel, call updateChannelMediaRelay.

  • This feature supports integer user IDs only.

  • When setting the source channel information, ensure that you set uid as 0, and the uid that you use to generate the token should also be set as 0.

  • To call startChannelMediaRelay again after it succeeds, you must call stopChannelMediaRelay to quit the current relay.

Interactive Live Streaming