# Cross-channel media stream relay (/en/realtime-media/rtc/build/join-and-manage-channels/cross-channel-media-relay/ios)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
Some special use-cases require cross-channel media stream forwarding functionality. RTC 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](/en/api-reference/faq/account/billing_free) every month. For usage beyond the free quota, please refer to [Pricing](/en/realtime-media/rtc/reference/pricing).
## Prerequisites
* Ensure that you have implemented the [SDK quickstart](/en/realtime-media/rtc/get-started-sdk) in your project.
* Contact [support@agora.io](mailto\: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.
```swift
// 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`.
```swift
isPauseRelaying = true
agoraKit.pauseAllChannelMediaRelay()
```
To resume forwarding the media stream to all target channels, call `resumeAllChannelMediaRelay`.
```swift
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.
```swift
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](#status-codes).
```swift
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:
| 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](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorachannelmediarelayerror). | `AgoraChannelMediaRelayStateFailure`(3) |
| Media stream forwarding has stopped. | `AgoraChannelMediaRelayStateIdle`(0) and `AgoraChannelMediaRelayErrorNone`(0) |
### Sample project
Agora provides an open-source [MediaChannelRelay](https://github.com/AgoraIO/API-Examples/blob/main/iOS/APIExample/APIExample/Examples/Advanced/MediaChannelRelay/MediaChannelRelay.swift) sample project for your reference. Download the project or view the source code for a more detailed example.
### API reference
* [`startOrUpdateChannelMediaRelay`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartcenginekit/startorupdatechannelmediarelay%28_:%29)
* [`stopChannelMediaRelay`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartcenginekit/stopchannelmediarelay%28%29)
* [`pauseAllChannelMediaRelay`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartcenginekit/pauseallchannelmediarelay%28%29)
* [`resumeAllChannelMediaRelay`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartcenginekit/resumeallchannelmediarelay%28%29)
* [`resumeAllChannelMediaRelay`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartcenginekit/resumeallchannelmediarelay%28%29)
* [`channelMediaRelayStateDidChange`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartcenginedelegate/rtcengine%28_\:channelmediarelaystatedidchange\:error:%29)
* [`AgoraChannelMediaRelayConfiguration`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorachannelmediarelayconfiguration)
* [`AgoraChannelMediaRelayInfo`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorachannelmediarelayinfo)