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

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

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.

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

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

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.

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.

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

To understand and respond to changes in the media relay state, refer to the CHANNEL_MEDIA_RELAY_STATE and CHANNEL_MEDIA_RELAY_ERROR enums in the API reference.

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