# 跨频道媒体流转发 (/zh-CN/realtime-media/rtc/build/advanced-channel/media-relay/macos) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 在实时互动场景下,跨频道媒体流转发功能可实现主播角色的媒体流从源频道同时转发进多个目标频道,其中: - 所有主播发布并接收彼此的音视频流,进行跨频道实时互动 - 观众可以接收到所有主播的音视频流,同时观看多位主播互动 该功能因其实时性和互动性,能够丰富直播玩法,尤其适用于连麦 PK、在线合唱等直播场景,为观众带来更好的观看体验的同时,也为主播带来更多的流量和收益。 :::info[信息] 跨频道媒体流享受声网[每月一万分钟免费](/zh-CN/reference/faq/account/billing_free)政策。超出免费额度的部分,计费详情请参考[跨频道媒体流转发计费](/zh-CN/realtime-media/rtc/reference/billing-strategy#跨频道媒体流转发)。 ::: ## 前提条件 [#前提条件-2] 在开始前,请确保满足以下条件: - 在你的项目中实现基本的实时音视频功能,详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。 - [联系技术支持](https://ticket.shengwang.cn/)开通跨频道媒体流转发功能。 ## 实现步骤 [#实现步骤-2] 参考如下流程图实现相关代码逻辑: ### 1. 开始跨频道媒体流转发 [#1-开始跨频道媒体流转发-2] 加入频道后,调用 `startOrUpdateChannelMediaRelay` 配置源频道和目标频道信息,开始转发媒体流。示例代码如下: ```swift // 配置源频道信息 // 推荐将源频道的 uid 设为 0,由 SDK 随机分配一个 uid // 注意 Token 与用户加入源频道时的 Token 不同,需要用源频道名和 uid = 0 重新生成 let config = AgoraChannelMediaRelayConfiguration() config.sourceInfo = AgoraChannelMediaRelayInfo(token: nil) isProcessing = true // 配置目标频道信息 // 你可以将 uid 设为 0,由 SDK 随机分配一个 uid,或自行指定 uid,并确保其与目标频道中的所有 uid 不同 let destinationInfo = AgoraChannelMediaRelayInfo(token: nil) config.setDestinationInfo(destinationInfo, forChannelName: destinationChannelName) // 开始跨频道媒体流转发 agoraKit.startOrUpdateChannelMediaRelay(config) ``` ### 2. 更新媒体流转发频道 [#2-更新媒体流转发频道-2] 成功调用 `startOrUpdateChannelMediaRelay` 后,如需将流转发到多个目标频道,或退出当前的转发频道,可以再次调用该方法添加或移除转发的目标频道。 :::info[信息] 更新后的配置会**全量替换**掉之前的配置。 ::: ### 3. 暂停/恢复转发媒体流 [#3-暂停恢复转发媒体流-2] 开始跨频道转发媒体流后,调用 `pauseAllChannelMediaRelay` 可以暂停向所有目标频道转发媒体流。示例代码如下: ```swift isPauseRelaying = true agoraKit.pauseAllChannelMediaRelay() ``` 暂停跨频道媒体流转发后,调用 `resumeAllChannelMediaRelay` 即可恢复向所有目标频道转发媒体流。示例代码如下: ```swift isPauseRelaying = false agoraKit.resumeAllChannelMediaRelay() ``` ### 4. 停止跨频道媒体流转发 [#4-停止跨频道媒体流转发-2] 成功开始跨频道媒体流转发后,可以调用 `stopChannelMediaRelay` 停止转发媒体流,一经停止,主播会退出所有目标频道。示例代码如下: ```swift isProcessing = true isPauseRelaying = false agoraKit.stopChannelMediaRelay() pauseRelayButton.isEnabled = false ``` :::info[信息] 如果该方法调用失败,可以调用 `leaveChannel` 离开频道,跨频道媒体流转发会自动停止。 ::: ### 5. 监听跨频道媒体流状态 [#5-监听跨频道媒体流状态-2] 在跨频道媒体流转发过程中,SDK 会通过 `channelMediaRelayStateDidChange` 回调报告媒体流转发的状态,你可以参考状态码的含义实现相关的业务逻辑。示例代码如下: ```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 } } ``` 主要的状态码、错误码及其对应的媒体流转发状态如下: | 媒体流转发状态 | 状态码和错误码 | | ---------------- | ---------------- | | 源频道开始向目标频道传输数据。 | `AgoraChannelMediaRelayStateRunning`(2) 和 `AgoraChannelMediaRelayErrorNone`(0) | | 跨频道媒体流转发出现异常。可根据[错误码](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged)进行排查。 | `AgoraChannelMediaRelayStateFailure`(3) | | 已停止媒体流转发。 | `AgoraChannelMediaRelayStateIdle`(0) 和 `AgoraChannelMediaRelayErrorNone`(0) | ## 参考信息 [#参考信息-2] ### 开发注意事项 [#开发注意事项-2] - 在直播场景中,只有角色为主播的用户才能调用 `startOrUpdateChannelMediaRelay` 开始跨频道媒体流转发。 - `startOrUpdateChannelMediaRelay` 必须在成功加入频道后调用,否则会报错。 - 一个频道内可以有多个主播转发媒体流,一个主播最多可以将媒体流转发至 6 个目标频道。 - 该功能不支持 String 型 `uid`,如需使用跨频道连麦功能,则要在普通连麦中也使用 Int 型 `uid`,否则跨频道连麦功能无法正常使用。 ### 示例项目 [#示例项目-2] 声网提供了开源的跨频道媒体流转发示例项目供你参考,你可以前往下载或查看其中的源代码。 ChannelMediaRelay} href="https://gitee.com/agoraio-community/API-Examples/blob/main/macOS/APIExample/Examples/Advanced/ChannelMediaRelay/ChannelMediaRelay.swift" /> ChannelMediaRelay} href="https://github.com/Shengwang-Community/API-Examples/blob/main/macOS/APIExample/Examples/Advanced/ChannelMediaRelay/ChannelMediaRelay.swift" /> ### API 参考 [#api-参考-2] - [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#startorupdatechannelmediarelay) - [`stopChannelMediaRelay`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengine_stopchannelmediarelay) - [`pauseAllChannelMediaRelay`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengine_pauseallchannelmediarelay) - [`resumeAllChannelMediaRelay`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengine_resumeallchannelmediarelay) - [`channelMediaRelayStateDidChange`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) - [`AgoraChannelMediaRelayConfiguration`](/zh-CN/api-reference/rtc/macos/class-channelmediarelayconfiguration) - [`AgoraChannelMediaRelayInfo`](/zh-CN/api-reference/rtc/macos/class-channelmediainfo)