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

We provide an open-source demo project that implements channel media relay on GitHub. You can try the demo and view the source code.

Implementation

Before relaying media streams across channels, ensure that you have implemented the basic real-time communication functions in your project. For details, see Start Live Interactive Streaming.

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:

Note:

• 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:

Sample code

// Configures the source channel information, the destination channel information, and the number of destination channels.
// Note that the source channel token is different from the token used for joining the source channel. You need to generate the source channel token with the source channel name and a uid of 0.
ChannelMediaInfo *lpSrcinfo = new ChannelMediaInfo;
lpSrcinfo->channelName = nullptr;
lpSrcinfo->token = nullptr;
lpSrcinfo->uid = 0;
ChannelMediaInfo  *lpDestInfos = NULL;
int nDestCount = arrayDestInfos.size();    
for(int nIndex = 0; nIndex < nDestCount; nIndex++) {
        std::string strChannelName = arrayDestInfos[nIndex]["channelName"].asString();
        std::string strtoken  = arrayDestInfos[nIndex]["token"].asString();
        uid_t uid = arrayDestInfos[nIndex]["uid"].asUInt();

        lpDestInfos[nIndex].channelName = new char[strChannelName.length() + 1];
        lpDestInfos[nIndex].token = new char[strtoken.length() + 1];
        strcpy_s((char*)lpDestInfos[nIndex].channelName,strChannelName.length() + 1,strChannelName.c_str());
        strcpy_s((char*)lpDestInfos[nIndex].token,strtoken.length() + 1,strtoken.c_str());
        lpDestInfos[nIndex].uid = uid;
}
ChannelMediaRelayConfiguration cmrc;
cmrc.srcInfo = lpSrcinfo;
cmrc.destInfos = lpDestInfos;
cmrc.destCount = nDestCount;
int ret = 0;
// Starts the channel media relay.
ret = m_lpAgoraEngine->startChannelMediaRelay(cmrc);

// Updates the destination channels for media stream relay.
ChannelMediaInfo *lpUpdateDestInfos = new ChannelMediaInfo;
lpUpdateDestInfos->channelName = "test";
lpUpdateDestInfos->token = nullptr;
lpUpdateDestInfos->uid = 0;
cmrc.destInfos = lpUpdateDestInfos;
cmrc.destCount = 1;
ret = m_lpAgoraEngine->updateChannelMediaRelay(cmrc);    

API reference

• startChannelMediaRelay
• updateChannelMediaRelay
• stopChannelMediaRelay
• onChannelMediaRelayStateChanged
• onChannelMediaRelayEvent

Considerations

• The Agora RTC 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.