# 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 [#prerequisites-3]

    * 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 [#implement-cross-channel-media-stream-relay-3]

    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 [#development-considerations-3]

    * 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 [#reference-3]

    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 [#api-reference-3]

    * [`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)