Looking for the previous docs site? Visit the legacy docs homepage. (opens in a new tab)
Agora Docs

Cross-channel media stream relay

Updated

Forward the media stream from a source channel to multiple target channels at the same time

Some special use-cases require cross-channel media stream forwarding functionality. Video SDK enables you to relay the media stream of a host, from a source channel, to multiple target channels simultaneously. This functionality allows you to realize the following interactions:

  • The hosts publish and receive each other's audio and video streams while engaging in cross-channel real-time interaction.

  • The audience receive all audio and video streams from hosts and watch multiple hosts interact at the same time.

Due to its real-time and interactive nature, this feature enriches live broadcasts and game-play, It is especially suitable for live scenes such as co-hosting PK and online choir. It provides the audience with a better viewing experience, while bringing more traffic and revenue to the hosts.

Cross-channel media stream relay is included in Agora's policy of 10,000 free minutes every month. For usage beyond the free quota, please refer to Pricing.

Prerequisites

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",
});
  1. 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.

  1. 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.

  1. 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);
});
  1. 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

Contact Us

+1 (408) 879-5885

2804 Mission College Blvd.Santa Clara, CA, USA 95054

AgoraCopyright © 2026 AgoraAll rights reserved