# Cross-channel media stream relay (/en/realtime-media/broadcast-streaming/build/connect-across-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. 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.

      
  
      
  
      
  
      
<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](../../reference/pricing).
  </CalloutDescription>
</CalloutContainer>

## Prerequisites

* Ensure that you have implemented the [SDK quickstart](../../index) in your project.
* Contact [technical support](https://agora-ticket.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",
});
```

2. Start cross-channel media stream relay

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

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

4. Update media stream relay channels

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

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

### 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`](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)