# Cross-channel media stream relay (/en/realtime-media/rtc/build/join-and-manage-channels/cross-channel-media-relay/web)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Some special use-cases require cross-channel media stream forwarding functionality. RTC 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.

      
  
      
  
      
  
      
<CalloutContainer type="info">
  <CalloutDescription>
    Cross-channel media stream relay is included in Agora's policy of [10,000 free minutes](/en/api-reference/faq/account/billing_free) every month. For usage beyond the free quota, please refer to [Pricing](/en/realtime-media/rtc/reference/pricing).
  </CalloutDescription>
</CalloutContainer>

## Prerequisites

* Ensure that you have implemented the [SDK quickstart](/en/realtime-media/rtc/get-started-sdk) in your project.
* Contact [support@agora.io](mailto\: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`.

   ```javascript
   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",
   });
   ```

   <CalloutContainer type="info">
     <CalloutDescription>
       * 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.
     </CalloutDescription>
   </CalloutContainer>

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

   ```javascript
   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.

   ```javascript
   // 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`.

   ```javascript
   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`](https://api-ref.agora.io/en/video-sdk/web/4.x/interfaces/iagorartcclient.html#startchannelmediarelay)
* [`updateChannelMediaRelay`](https://api-ref.agora.io/en/video-sdk/web/4.x/interfaces/iagorartcclient.html#updatechannelmediarelay)
* [`stopChannelMediaRelay`](https://api-ref.agora.io/en/video-sdk/web/4.x/interfaces/iagorartcclient.html#stopchannelmediarelay)
* [`AgoraRTCClient.on("channel-media-relay-state")`](https://api-ref.agora.io/en/video-sdk/web/4.x/interfaces/iagorartcclient.html#event_channel_media_relay_state)
* [`AgoraRTCClient.on("channel-media-relay-event")`](https://api-ref.agora.io/en/video-sdk/web/4.x/interfaces/iagorartcclient.html#event_channel_media_relay_event)