Co-hosting across channels is the process where the Agora Web SDK relays the media tracks of a host from a live-broadcast channel (source channel) to a maximum of four live-broadcast channels (destination channels). It has the following benefits:
Co-hosting across channels applies to scenarios such as an online singing contest, where hosts of different channels interact with each other.
Before proceeding, ensure that you have read the quickstart guides and implemented basic real-time audio and video functions in your project.
The Agora Web SDK provides the following methods for co-hosting across channels:
startChannelMediaRelay
updateChannelMediaRelay
stopChannelMediaRelay
API call sequence requirements:
- Call
startChannelMediaRelay
afterAgoraRTCClient.publish
succeeds.- Call
updateChannelMediaRelay
afterstartChannelMediaRelay
succeeds.
During a channel media relay, the SDK reports the states and error codes of the relay with the AgoraRTCClient.on("channel-media-relay-state")
callback, and the events of the relay with the AgoraRTCClient.on("channel-media-relay-event")
callback.
Notes:
- Any host in a live-broadcast channel can call
startChannelMediaRelay
to enable the media stream relay. The SDK relays the media stream of the host who calls the method.- After a relay starts, users in the destination channels receive the
AgoraRTCClient.on("user-published")
callback.- If the host of a destination channel drops offline or leaves the channel during the media relay, the host of the source channel receives the
AgoraRTCClient.on("user-left")
callback.
The client
object in the following sample code is created by calling AgoraRTC.createClient
.
Configure the media stream relay
const channelMediaConfig = new AgoraRTC.ChannelMediaRelayConfiguration();
// Set the source channel information.
// Set channelName as the source channel name. Set uid as the ID of the host whose stream is relayed. The token is generated with 0 and the source channel name.
channelMediaConfig.setSrcChannelInfo({
channelName: "srcChannel",
uid:<USER_UID>,
token: "yourSrcToken",
})
// Set the destination channel information. You can set a maximum of four destination channels.
// Set channelName as the destination channel name. Set uid as 0 or a 32-bit unsigned integer. To avoid UID conflicts, the uid must be different from any other user IDs in the destination channel. The token is generated with the uid and the destination channel name.
channelMediaConfig.addDestChannelInfo({
channelName: "destChannel1",
uid: 123,
token: "yourDestToken",
})
Start the media stream relay
client.startChannelMediaRelay(channelMediaConfig).then(() => {
console.log(`startChannelMediaRelay success`);
}).catch(e => {
console.log(`startChannelMediaRelay failed`, e);
})
Update the media stream relay configurations
// Remove a destination channel.
channelMediaConfig.removeDestChannelInfo("destChannel1")
// Update the configurations of the media stream relay.
client.updateChannelMediaRelay(channelMediaConfig).then(() => {
console.log("updateChannelMediaRelay success");
}).catch(e => {
console.log("updateChannelMediaRelay failed", e);
})
Stop the media stream relay
client.stopChannelMediaRelay().then(() => {
console.log("stop media relay success");
}).catch(e => {
console.log("stop media relay failed", e);
})
startChannelMediaRelay
updateChannelMediaRelay
stopChannelMediaRelay
AgoraRTCClient.on("channel-media-relay-state")
AgoraRTCClient.on("channel-media-relay-event")
updateChannelMediaRelay
.setSrcChannelInfo
), ensure that the setting of uid
is different from the UID of the current host and any other user in the source channel. Agora recommends setting this uid
as 0
.startChannelMediaRelay
again after it succeeds, you must call stopChannelMediaRelay
to quit the current relay.