Cross-channel media stream relay

Prerequisites

• Ensure that you have implemented the SDK quickstart in your project.
• Contact support@agora.io 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. Calling this method before joining a channel fails. In live broadcasting, only hosts can call this method.

   // 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.
   • Cross-channel media stream relay doesn't support String-type user IDs. Join the channel with an int-type uid.

2. 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. Multiple hosts in a channel can forward media streams, and each host can forward to up to six target channels.

   The updated configuration completely replaces the previous configuration.

3. 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()

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

5. 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
     }
   }

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 MediaChannelRelay sample project for your reference. Download the project or view the source code for a more detailed example.

API reference

• startOrUpdateChannelMediaRelay
• stopChannelMediaRelay
• pauseAllChannelMediaRelay
• resumeAllChannelMediaRelay
• resumeAllChannelMediaRelay
• channelMediaRelayStateDidChange
• AgoraChannelMediaRelayConfiguration
• AgoraChannelMediaRelayInfo