Cross-channel media stream relay

Prerequisites

• Ensure that you have implemented the SDK quickstart in your project.
• Contact technical support to activate the cross-channel media stream relay feature.

Implement cross-channel media stream relay

The following figure shows the workflow you implement to facilitate cross-channel media stream relay:

To implement cross-channel media stream relay in your app, take the following steps:

1. Start cross-channel media stream relay

After joining a channel, call startOrUpdateChannelMediaRelay to configure the source and target channel information and start forwarding a media stream.

const srcChannelId = "srcChannel";
const destChannelId = "destChannel";
const uid = 0;
const token = "insert-your-token";

// Start cross-channel media stream forwarding
rtcEngine.startOrUpdateChannelMediaRelay({
  // Configure source channel information srcInfo
  srcInfo: {
    channelName: srcChannelId,
    uid: uid,
    token: token,
  },
  // Configure the target channel information destInfos
  destInfos: [
    {
      channelName: destChannelId,
      token: '', // A token to join the target channel
      uid: 0, // SDK randomly assigns a uid
    },
  ],
  // Number of target channels
  destCount: 1,
});

2. Update media stream relay channels

To forward the stream to multiple target channels or exit the current forwarding channel after staring channel media relay, call startOrUpdateChannelMediaRelay again to add or remove target channels for forwarding.

3. Pause or resume media stream relay

To pause forwarding the media stream to all target channels, call pauseAllChannelMediaRelay.

rtcEngine.pauseAllChannelMediaRelay();

To resume forwarding the media stream to all target channels, call resumeAllChannelMediaRelay.

rtcEngine.resumeAllChannelMediaRelay();

4. Stop cross-channel media stream relay

To stop forwarding the media stream, call stopChannelMediaRelay. When forwarding stops, the host exits all target channels.

rtcEngine.stopChannelMediaRelay();

5. Monitor cross-channel media stream status

During cross-channel media stream relay, the SDK reports changes in the status of media stream relay through the onChannelMediaRelayStateChanged callback. Implement the relevant business logic based on the status codes.

// Register event callback
rtcEngine.registerEventHandler(
  onChannelMediaRelayStateChanged: (state: ChannelMediaRelayState, code: ChannelMediaRelayError) => {
    console.log(`Cross-channel media stream forwarding status：${state}，Error Code：${code}`);
  },
);

Development considerations

• In live broadcast use cases, only users with the role of host can call startOrUpdateChannelMediaRelay to initiate cross-channel media stream forwarding.

• Call startOrUpdateChannelMediaRelay after successfully joining a channel; otherwise, the method call fails.

• Within a single channel, multiple hosts can forward media streams. Each host can forward a media stream to up to six target channels.

• This feature does not support String-type uid. To use cross-channel co-hosting, you must also use an int-type uid in regular co-hosting. Otherwise, cross-channel co-hosting will not work.

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Status codes

The main media stream forwarding states and their corresponding status codes are as follows:

Sample project

Agora provides an open-source ChannelMediaRelay sample project for your reference. Download the project or view the source code for a more detailed example.

API reference

• startOrUpdateChannelMediaRelay
• stopChannelMediaRelay
• pauseAllChannelMediaRelay
• resumeAllChannelMediaRelay
• onChannelMediaRelayStateChanged
• ChannelMediaRelayConfiguration
• ChannelMediaInfo