Cross-channel media stream relay

Prerequisites

• Ensure that you have implemented the SDK quickstart in your project.
• Contact support@agora.io 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",
   });

   • Set the source channel uid to a value different from the current host's uid. Best practice is to set it to 0 so the server assigns a random uid.
   • Cross-channel media stream relay doesn't support String usernames.

2. Start cross-channel media stream relay

   To start cross-channel media stream relay, call startChannelMediaRelay after calling AgoraRTCClient.publish. The SDK forwards the stream of the host who calls this method, and multiple hosts in a channel can forward media streams. To call startChannelMediaRelay again after a successful call, first call stopChannelMediaRelay.

   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. After you call startChannelMediaRelay or updateChannelMediaRelay successfully, users in the target channels receive the AgoraRTCClient.on("user-published") callback. If a host in a target channel goes offline or leaves the channel during relay, the host in the source channel receives the AgoraRTCClient.on("user-left") callback.

4. Update media stream relay channels

   To add or remove target channels after successfully calling startChannelMediaRelay, call updateChannelMediaRelay. You can forward a media stream to up to four target channels.

   // 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);
   });

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")