Cross-channel media stream relay

Prerequisites

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

Implement cross-channel media stream relay

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

1. Configure cross-channel media stream relay

To create a cross-channel media stream relay configuration object, and set the source and target channel information, call createChannelMediaRelayConfiguration.

const channelMediaConfig = AgoraRTC.createChannelMediaRelayConfiguration();
// Set source channel information
channelMediaConfig.setSrcChannelInfo({
 channelName: "srcChannel",
 uid: <USER_UID>,
 token: "yourSrcToken",
});

// Set target channel information.
// It can be called multiple times, for up to 4 target channels
channelMediaConfig.addDestChannelInfo({
 channelName: "destChannel1",
 uid: 123,
 token: "yourDestToken",
});

2. Start cross-channel media stream relay

To start cross-channel media stream relay, call startChannelMediaRelay after calling AgoraRTCClient.publish.

client.startChannelMediaRelay(channelMediaConfig).then(() => {
 console.log(`startChannelMediaRelay success`);
}).catch(e => {
 console.log(`startChannelMediaRelay failed`, e);
});

client refers to the local client object you create using AgoraRTC.createClient.

3. Listen for cross-channel media stream status changes

During cross-channel media stream relay, the SDK reports the status of media stream relay through AgoraRTCClient.on("channel-media-relay-state") callback with state codes and error codes. Listen to the AgoraRTCClient.on("channel-media-relay-event") callback for relay events.

4. Update media stream relay channels

To add or remove target channels after successfully calling startChannelMediaRelay, call updateChannelMediaRelay.

// Remove a target channel
channelMediaConfig.removeDestChannelInfo("destChannel1");
// Update cross-channel media stream relay settings
client.updateChannelMediaRelay(channelMediaConfig).then(() => {
 console.log("updateChannelMediaRelay success");
}).catch(e => {
 console.log("updateChannelMediaRelay failed", e);
});

5. Stop cross-channel media stream relay

To stop cross-channel media stream relay, call stopChannelMediaRelay.

client.stopChannelMediaRelay().then(() => {
 console.log("stop media relay success");
}).catch(e => {
 console.log("stop media relay failed", e);
});

Development considerations

• This feature supports forwarding media streams to up to 4 target channels. If you want to add or remove target channels during forwarding, call the startOrUpdateChannelMediaRelay method.
• This feature does not support String usernames.
• Multiple hosts within a channel can forward media streams. The SDK forwards the stream of the host who calls the startChannelMediaRelay method.
• When setting the source channel information using setSrcChannelInfo, ensure that the uid is different from the current host's uid. Best practice is to set this uid to 0, allowing the server to randomly assign one.
• After successfully forwarding media streams by calling startChannelMediaRelay or updateChannelMediaRelay, users in the target channel receive the AgoraRTCClient.on("user-published") callback. During the media stream forwarding process, if a host in the target channel goes offline or leaves the channel, the host in the source channel receives the AgoraRTCClient.on("user-left") callback.
• After successfully calling startChannelMediaRelay, if you wish to call it again, you must first call stopChannelMediaRelay to exit the current forwarding state.

Reference

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

API reference

• startChannelMediaRelay
• updateChannelMediaRelay
• stopChannelMediaRelay
• AgoraRTCClient.on("channel-media-relay-state")
• AgoraRTCClient.on("channel-media-relay-event")