Cross-channel media stream relay

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

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:

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.

// Configure source channel information
ChannelMediaInfo srcChannelInfo = new ChannelMediaInfo(et_channel.getText().toString(), null, myUid);
ChannelMediaRelayConfiguration mediaRelayConfiguration = new ChannelMediaRelayConfiguration();
mediaRelayConfiguration.setSrcChannelInfo(srcChannelInfo);
// Configure target channel information
ChannelMediaInfo destChannelInfo = new ChannelMediaInfo(destChannelName, null, myUid);
mediaRelayConfiguration.setDestChannelInfo(destChannelName, destChannelInfo);
// Start cross-channel media stream relay
engine.startOrUpdateChannelMediaRelay(mediaRelayConfiguration);

Best practice is to set the UID of the source channel to 0, allowing the SDK to assign a random UID.
- The source channel token in srcChannelInfo should be different from the one used when joining the source channel. Generate a new token using the source channel name and uid = 0.
- For the destination channel, set the uid to 0, to allow the SDK to assign a random uid, or specify a uid, ensuring that it is different from all UIDs in the target channel.

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.

The updated configuration completely replaces the previous configuration.

Pause or resume media stream relay

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

engine.pauseAllChannelMediaRelay();
isPaused = true;
pause.setText(R.string.resume);

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

engine.resumeAllChannelMediaRelay();
isPaused = false;
pause.setText(R.string.pause);

Stop cross-channel media stream relay

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

engine.stopChannelMediaRelay();
et_channel_ex.setEnabled(true);
pause.setEnabled(false);
join_ex.setText(getString(R.string.join));
mediaRelaying = false;

If this method fails, call leaveChannel to leave the channel and stop cross-channel media stream relay.

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.

public void onChannelMediaRelayStateChanged(int state, int code) {
  switch (state) {
    case RELAY_STATE_CONNECTING:
      mediaRelaying = true;
      handler.post(() -> {
        et_channel_ex.setEnabled(false);
        join_ex.setEnabled(true);
        join_ex.setText(getText(R.string.stop));
        showLongToast("channel media Relay connected.");
      });
      break;
    case RELAY_STATE_FAILURE:
      mediaRelaying = false;
      handler.post(() -> {
        showLongToast(String.format("channel media Relay failed at error code: %d", code));
      });
    default:
      break;
  }
}

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:

Media stream forwarding status	status code
The source channel starts transmitting data to the target channel.	`RELAY_STATE_RUNNING`(2) and `RELAY_OK`(0)
Cross-channel media stream forwarding encounters an exception. You can troubleshoot based on the error code.	`RELAY_STATE_FAILURE`(3)
Media stream forwarding has stopped.	`RELAY_STATE_IDLE`(0) and `RELAY_OK`(0)

Sample project

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

API reference

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

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:

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.

// Configure source channel information
let config = AgoraChannelMediaRelayConfiguration()
config.sourceInfo = AgoraChannelMediaRelayInfo(token: nil)
isProcessing = true
// Configure target channel information
let destinationInfo = AgoraChannelMediaRelayInfo(token: nil)
config.setDestinationInfo(destinationInfo, forChannelName: destinationChannelName)
// Start cross-channel media stream forwarding
agoraKit.startOrUpdateChannelMediaRelay(config)

Best practice is to set the UID of the source channel to 0, allowing the SDK to assign a random UID.
- The source channel token in srcChannelInfo should be different from the one used when joining the source channel. Generate a new token using the source channel name and uid = 0.
- For the destination channel, set the uid to 0, to allow the SDK to assign a random uid, or specify a uid, ensuring that it is different from all UIDs in the target channel.

Update media stream relay channels

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

The updated configuration completely replaces the previous configuration.

Pause or resume media stream relay

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

isPauseRelaying = true
agoraKit.pauseAllChannelMediaRelay()

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

isPauseRelaying = false
agoraKit.resumeAllChannelMediaRelay()

Stop cross-channel media stream relay

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

isProcessing = true
isPauseRelaying = false
agoraKit.stopChannelMediaRelay()
pauseRelayButton.isEnabled = false

If this method fails, you can call leaveChannel to leave the channel, and cross-channel media stream relay will automatically stop.

Listen for cross-channel media stream status changes

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

func rtcEngine(_ engine: AgoraRtcEngineKit,
      channelMediaRelayStateDidChange state: AgoraChannelMediaRelayState,
      error: AgoraChannelMediaRelayError) {

  LogUtils.log(message: "channelMediaRelayStateDidChange: \(state.rawValue) error \(error.rawValue)", level: .info)
  isProcessing = false

  switch state {
  case .running:
    isRelaying = true

  case .failure:
    showAlert(message: "Media Relay Failed: \(error.rawValue)")
    isRelaying = false

  case .idle:
    isRelaying = false

  default:
    break
  }
}

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:

Media stream forwarding status	status code
The source channel starts transmitting data to the target channel.	`AgoraChannelMediaRelayStateRunning`(2) and `AgoraChannelMediaRelayErrorNone`(0)
Cross-channel media stream forwarding encounters an exception. You can troubleshoot based on the error code.	`AgoraChannelMediaRelayStateFailure`(3)
Media stream forwarding has stopped.	`AgoraChannelMediaRelayStateIdle`(0) and `AgoraChannelMediaRelayErrorNone`(0)

Sample project

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

API reference

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

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:

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.

// Configure source channel information
let config = AgoraChannelMediaRelayConfiguration()
config.sourceInfo = AgoraChannelMediaRelayInfo(token: nil)
isProcessing = true
// Configure target channel information
let destinationInfo = AgoraChannelMediaRelayInfo(token: nil)
config.setDestinationInfo(destinationInfo, forChannelName: destinationChannelName)
// Start cross-channel media stream forwarding
agoraKit.startOrUpdateChannelMediaRelay(config)

Best practice is to set the UID of the source channel to 0, allowing the SDK to assign a random UID.
- The source channel token in srcChannelInfo should be different from the one used when joining the source channel. Generate a new token using the source channel name and uid = 0.
- For the destination channel, set the uid to 0, to allow the SDK to assign a random uid, or specify a uid, ensuring that it is different from all UIDs in the target channel.

Update media stream relay channels

The updated configuration completely replaces the previous configuration.

Pause or resume media stream relay

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

isPauseRelaying = true
agoraKit.pauseAllChannelMediaRelay()

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

isPauseRelaying = false
agoraKit.resumeAllChannelMediaRelay()

Stop cross-channel media stream relay

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

isProcessing = true
isPauseRelaying = false
agoraKit.stopChannelMediaRelay()
pauseRelayButton.isEnabled = false

If this method fails, you can call leaveChannel to leave the channel, and cross-channel media stream relay will automatically stop.

Listen for cross-channel media stream status changes

func rtcEngine(_ engine: AgoraRtcEngineKit,
      channelMediaRelayStateDidChange state: AgoraChannelMediaRelayState,
      error: AgoraChannelMediaRelayError) {

  LogUtils.log(message: "channelMediaRelayStateDidChange: \(state.rawValue) error \(error.rawValue)", level: .info)
  isProcessing = false

  switch state {
  case .running:
    isRelaying = true

  case .failure:
    showAlert(message: "Media Relay Failed: \(error.rawValue)")
    isRelaying = false

  case .idle:
    isRelaying = false

  default:
    break
  }
}

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:

Media stream forwarding status	status code
The source channel starts transmitting data to the target channel.	`AgoraChannelMediaRelayStateRunning`(2) and `AgoraChannelMediaRelayErrorNone`(0)
Cross-channel media stream forwarding encounters an exception. You can troubleshoot based on the error code.	`AgoraChannelMediaRelayStateFailure`(3)
Media stream forwarding has stopped.	`AgoraChannelMediaRelayStateIdle`(0) and `AgoraChannelMediaRelayErrorNone`(0)

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

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

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

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

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

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.

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.

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

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

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

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:

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.

// Configure source channel information
ChannelMediaInfo *m_srcInfo = new ChannelMediaInfo;
m_srcInfo->channelName = new char[szChannelId.size() + 1];
strcpy_s(const_cast<char *>(m_srcInfo->channelName), szChannelId.size() + 1,
		szChannelId.data());
// Note: The token for source channel is different from the token used when joining the source channel.
// It needs to be regenerated using the source channel name and uid = 0
m_srcInfo->token = APP_TOKEN;
// It is recommended to set the uid of the source channel to 0, allowing the SDK to assign a random uid.
m_srcInfo->uid = 0;

// Configure destination channel information
int nDestCount = m_vecChannelMedias.size();
ChannelMediaInfo *lpDestInfos = new ChannelMediaInfo[nDestCount];
for (int nIndex = 0; nIndex < nDestCount; nIndex++) {
	lpDestInfos[nIndex].channelName = m_vecChannelMedias[nIndex].channelName;
	lpDestInfos[nIndex].token = m_vecChannelMedias[nIndex].token;
	// Set the uid to 0, allowing the SDK to assign a random uid, or specify your own uid
	// Ensure that it is different from all uids in the target channels
	lpDestInfos[nIndex].uid = m_vecChannelMedias[nIndex].uid;
}

ChannelMediaRelayConfiguration cmrc;
cmrc.srcInfo = m_srcInfo;
cmrc.destInfos = lpDestInfos;
cmrc.destCount = nDestCount;
int ret = 0;
// Start or update the cross-channel media stream relay
ret = m_rtcEngine->startOrUpdateChannelMediaRelay(cmrc);

Best practice is to set the UID of the source channel to 0, allowing the SDK to assign a random UID.
- The source channel token in srcChannelInfo should be different from the one used when joining the source channel. Generate a new token using the source channel name and uid = 0.
- For the destination channel, set the uid to 0, to allow the SDK to assign a random uid, or specify a uid, ensuring that it is different from all uids in the target channel.

Update media stream relay channels

The updated configuration completely replaces the previous configuration.

Pause or resume media stream relay

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

m_rtcEngine->pauseAllChannelMediaRelay();

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

m_rtcEngine->resumeAllChannelMediaRelay();

Stop cross-channel media stream relay

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

m_rtcEngine->stopChannelMediaRelay();
m_lstInfo.AddString(_T("stopChannelMediaRelay"));
m_btnStartMediaRelay.SetWindowText(CrossChannelStartMediaRelay);

If this method fails, you can call leaveChannel to leave the channel, and cross-channel media stream relay will automatically stop.

Listen for cross-channel media stream status changes

class CAgoraCrossChannelEventHandler : public IRtcEngineEventHandler {
	virtual void onChannelMediaRelayStateChanged(
  CHANNEL_MEDIA_RELAY_STATE state,
  CHANNEL_MEDIA_RELAY_ERROR code) override {
		if (m_hMsgHanlder)
			::PostMessage(m_hMsgHanlder,
           WM_MSGID(EID_CHANNEL_MEDIA_RELAY_STATE_CHNAGENED),
           state, 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:

Media stream forwarding status	status code
The source channel starts transmitting data to the target channel.	`RELAY_STATE_RUNNING`(2) and `RELAY_OK`(0)
Cross-channel media stream forwarding encounters an exception. You can troubleshoot based on the error code.	`RELAY_STATE_FAILURE`(3)
Media stream forwarding has stopped.	`RELAY_STATE_IDLE`(0) and `RELAY_OK`(0)

Sample project

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

API reference

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

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:

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

Update media stream relay channels

The updated configuration completely replaces the previous configuration.

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();

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();

If this method fails, call leaveChannel to leave the channel and stop cross-channel media stream relay.

Monitor cross-channel media stream status

// 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:

Media stream forwarding status	status code
The source channel starts transmitting data to the target channel.	`RelayStateRunning`(2) and `RelayOk`(0)
Cross-channel media stream forwarding encounters an exception. You can troubleshoot based on the error code.	`RelayStateFailure`(3)
Media stream forwarding has stopped.	`RelayStateIdle`(0) and `RelayOk`(0)

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

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

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:

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.

// Configures the source channel information for media relay.
final srcChannelInfo = ChannelMediaInfo(
 channelName: sourceChannelName,
 token: srcToken, // Token generated with UID 0.
 uid: 0,
);

// Configures the destination channel information for media relay.
final destChannelInfo = ChannelMediaInfo(
 channelName: destChannelName,
 token: destToken,
 uid: 0,
);

// Creates the media relay configuration with source and destination channels.
final mediaRelayConfiguration = ChannelMediaRelayConfiguration(
 srcChannelInfo: srcChannelInfo,
 destInfos: {destChannelName: destChannelInfo},
);

// Starts relaying media streams from the source channel to the destination channel.
await engine.startOrUpdateChannelMediaRelay(mediaRelayConfiguration);

Best practice is to set the UID of the source channel to 0, allowing the SDK to assign a random UID.
- The source channel token in srcChannelInfo should be different from the one used when joining the source channel. Generate a new token using the source channel name and uid = 0.
- For the destination channel, set the uid to 0, to allow the SDK to assign a random uid, or specify a uid, ensuring that it is different from all UIDs in the target channel.

Update media stream relay channels

The updated configuration completely replaces the previous configuration.

Pause or resume media stream relay

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

await engine.pauseAllChannelMediaRelay();
isPaused = true;

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

await engine.resumeAllChannelMediaRelay();
isPaused = false;

Stop cross-channel media stream relay

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

await engine.stopChannelMediaRelay();
mediaRelaying = false;

If this method fails, call leaveChannel to leave the channel and stop cross-channel media stream relay.

Monitor cross-channel media stream status

engine.registerEventHandler(
 RtcEngineEventHandler(
  onChannelMediaRelayStateChanged: (state, code) {
   switch (state) {
    case ChannelMediaRelayState.relaying:
     mediaRelaying = true;
     print("Channel media relay connected.");
     break;
    case ChannelMediaRelayState.failure:
     mediaRelaying = false;
     print("Channel media relay failed with error code: $code");
     break;
    default:
     break;
   }
  },
 ),
);

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 following table shows the main forwarding states and their corresponding codes:

Forwarding status	State and error code
The source channel starts transmitting data to the target channel.	`ChannelMediaRelayState.relayRunning (2)`, `ChannelMediaRelayError.relayOk (0)`
Forwarding encounters an exception. Troubleshoot the issue based on the error code.	`ChannelMediaRelayState.relayFailure (3)`
Forwarding has stopped.	`ChannelMediaRelayState.relayIdle (0)`, `ChannelMediaRelayError.relayOk (0)`

API reference

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

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:

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

Update media stream relay channels

The updated configuration completely replaces the previous configuration.

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();

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();

If this method fails, call leaveChannel to leave the channel and stop cross-channel media stream relay.

Monitor cross-channel media stream status

// 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:

Media stream forwarding status	status code
The source channel starts transmitting data to the target channel.	`RelayStateRunning`(2) and `RelayOk`(0)
Cross-channel media stream forwarding encounters an exception. You can troubleshoot based on the error code.	`RelayStateFailure`(3)
Media stream forwarding has stopped.	`RelayStateIdle`(0) and `RelayOk`(0)

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

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

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 game, take the following steps:

Start cross-channel media stream relay

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

private void OnStartButtonClick()
{
  ChannelMediaRelayConfiguration config = new ChannelMediaRelayConfiguration();

  // Configure source channel
  config.srcInfo = new ChannelMediaInfo
  {
    channelName = this._appIdInput.channelName,
    uid = 0, // Let the SDK assign a random UID
    token = this._appIdInput.token // Regenerate token for source channel with UID 0
  };

  // Configure target channel (up to 6 supported)
  config.destInfos = new ChannelMediaInfo[1];
  config.destInfos[0] = new ChannelMediaInfo
  {
    channelName = this._appIdInput.channelName + "_2",
    uid = 0, // Random UID or specify a unique one
    token = this._appIdInput.token
  };
  config.destCount = 1;

  // Start media stream forwarding
  var nRet = RtcEngine.StartOrUpdateChannelMediaRelay(config);
  this.Log.UpdateLog(`StartOrUpdateChannelMediaRelay nRet: ${nRet}, New Channel: ${this._appIdInput.channelName}_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.

The updated configuration completely replaces the previous configuration.

Pause or resume media stream relay

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

private void onPauseAllButtonClick()
{
  var nRet = RtcEngine.PauseAllChannelMediaRelay();
  this.Log.UpdateLog(`onPauseAllButtonClick nRet: ${nRet}`);
}

To resume forwarding the media stream to all target channels, call ResumeAllChannelMediaRelay:

private void OnResumeAllButtonClick()
{
  var nRet = RtcEngine.ResumeAllChannelMediaRelay();
  this.Log.UpdateLog(`OnResumeAllButtonClick nRet: ${nRet}`);
}

Stop cross-channel media stream relay

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

private void OnStopButtonClick()
{
  var nRet = RtcEngine.StopChannelMediaRelay();
  this.Log.UpdateLog(`OnStopButtonClick nRet: ${nRet}`);
}

If this method fails, call LeaveChannel to leave the channel and stop cross-channel media stream relay.

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.

public override void OnChannelMediaRelayStateChanged(int state, int code)
{
  _channelMediaRelay.Log.UpdateLog(`OnChannelMediaRelayStateChanged state: ${state}, code: ${code}`);
}

Development considerations

In a live broadcast use-case, only hosts can call StartOrUpdateChannelMediaRelay.
StartOrUpdateChannelMediaRelay must be called after successfully joining the channel, otherwise an error is reported.
Multiple hosts can forward media streams in a channel. Each host can forward media streams to up to 6 target channels.
This function does not support String uids. Additionally, to use the cross-channel microphone function, use the Int type in the normal microphone function uid.

Contact Us

Contact Us