# Cross-channel media stream relay (/en/realtime-media/broadcast-streaming/build/connect-across-channels/cross-channel-media-relay/macos)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
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](/en/api-reference/faq/account/billing_free) every month. For usage beyond the free quota, please refer to [Pricing](../../reference/pricing).
## Prerequisites [#prerequisites-2]
* Ensure that you have implemented the [SDK quickstart](../../index) in your project.
* Contact [technical support](https://agora-ticket.agora.io/) to activate the cross-channel media stream relay feature.
## Implement cross-channel media stream relay [#implement-cross-channel-media-stream-relay-2]
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.
```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.
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.
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
}
}
```
### Development considerations [#development-considerations-2]
* 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 [#reference-2]
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 [#status-codes-2]
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 [#sample-project-2]
Agora provides an open-source [ChannelMediaRelay](https://github.com/AgoraIO/API-Examples/blob/main/macOS/APIExample/Examples/Advanced/ChannelMediaRelay/ChannelMediaRelay.swift) sample project for your reference. Download the project or view the source code for a more detailed example.
### API reference [#api-reference-2]
* [`startOrUpdateChannelMediaRelay`](https://api-ref.agora.io/en/video-sdk/macos/4.x/documentation/agorartckit/agorartcenginekit/startorupdatechannelmediarelay\(_:\))
* [`stopChannelMediaRelay`](https://api-ref.agora.io/en/video-sdk/macos/4.x/documentation/agorartckit/agorartcenginekit/stopchannelmediarelay\(\))
* [`pauseAllChannelMediaRelay`](https://api-ref.agora.io/en/video-sdk/macos/4.x/documentation/agorartckit/agorartcenginekit/pauseallchannelmediarelay\(\))
* [`resumeAllChannelMediaRelay`](https://api-ref.agora.io/en/video-sdk/macos/4.x/documentation/agorartckit/agorartcenginekit/resumeallchannelmediarelay\(\))
* [`resumeAllChannelMediaRelay`](https://api-ref.agora.io/en/video-sdk/macos/4.x/documentation/agorartckit/agorartcenginekit/resumeallchannelmediarelay\(\))
* [`channelMediaRelayStateDidChange`](https://api-ref.agora.io/en/video-sdk/macos/4.x/documentation/agorartckit/agorartcenginedelegate/rtcengine\(_\:channelmediarelaystatedidchange\:error:\))
* [`AgoraChannelMediaRelayConfiguration`](https://api-ref.agora.io/en/video-sdk/macos/4.x/documentation/agorartckit/agorachannelmediarelayconfiguration)
* [`AgoraChannelMediaRelayInfo`](https://api-ref.agora.io/en/video-sdk/macos/4.x/documentation/agorartckit/agorachannelmediarelayinfo)