文档中心

实时音视频

开发指南

音频选路

在大规模音视频互动场景中，大量用户同时开麦发言会消耗巨大带宽和设备性能。开启音频选路功能后，RTC 引擎将智能托管音频订阅关系，识别活跃发言者并定向分发，减少每个客户端接收的音频流数量，从而在保障互动流畅度的同时，大幅降低客户端负载。

应用场景

场景	场景特点	核心痛点（无音频选路时）	音频选路如何解决
云端会议	上千人房间，参会者均可随时开麦发言并自由选择观看其他参会人的视频画面	多人同时发言，客户端需接收所有音频流，导致带宽激增。 CPU 处理大量音频解码与混音，易过载。声音嘈杂，有效信息难辨，会议效率低。	仅推送主要活跃发言者的音频流，降低带宽消耗，减轻设备负担；保障会议音频清晰，聚焦关键信息，提升沟通效率。
互动娱乐	上万人房间，互动嘉宾人数可超 500 人，观众可申请与嘉宾上麦互动	数百路音频流需下发海量听众，服务端带宽和客户端处理压力大，服务器带宽成本高昂。音频并发易致高延迟、卡顿，影响实时互动。	仅分发少量核心活跃音频流至所有听众，大幅节约服务器带宽成本，保障听众端流畅接收，支持并提升超大规模并发互动的体验和可行性。

开启或关闭音频选路

（可选）如果你还没创建应用，请先创建 RTC 应用。

应用创建成功后，音频选路默认为关闭状态。

说明

推荐使用不同的 appID 开发适用于不同场景的音视频应用。是否开启音频选路的应用场景差别较大，尽量避免在用户使用时进行切换。

进入功能配置 > 房间模式，选择目标应用，按需开启或关闭音频选路。

使用说明

Native/Web/Flutter/Electron 端

使用须知

开启音频选路功能后，请注意以下事项：

容量上限：房间内用户和媒体流容量会同步提升。详见用户和媒体流上限。

发布失败：流数量达上限后，PublishStream 返回 -1080（Web 端没有对应的错误码，会触发发布失败）。

订阅失败：订阅流达上限后，SubscribeStream 返回 -1070（Web 端没有对应的错误码，会触发发布失败）。

订阅逻辑变更：

视频订阅：仍需在客户端手动维护订阅关系。

音频订阅：

Native 端：支持取消订阅对方音频。例如，A 取消订阅 B 的音频，即使 B 的音频被选为活跃用户并推送，A 也不会收听到 B 的音频。

Web 端：不支持取消订阅某用户音频。

生效房间：仅对新创建的房间生效，不会影响已存在的房间模式。

激活条件：启用音频选路后，当房间内用户数超过 5 人时，部分 API 和回调的行为会发生变化。具体影响，请参见启用音频选路对相关接口的影响。

启用后对 API/回调的影响

启用音频选路后，部分接口和回调行为将发生变化，具体触发条件见下表（以 Windows SDK 为例）。

不同平台的实现步骤相同，但接口名称、参数名称可能略有差异。以下指南以 Windows RTC SDK 为例，参考对应平台的 API 文档获取更多信息。微信小程序端请参见微信小程序端使用音频选路。

API 行为变更

接口	关闭音频选路	开启音频选路
joinRoom (isAutoSubscribeAudio = true)	自动订阅音频。	无效，音频订阅关系由 RTC 系统智能托管。
subscribeStreamVideo subscribeStreamAudio	订阅指定用户音视频流。	视频：与关闭音频选路时相同。音频：无需调用，音频订阅关系由 RTC 系统智能托管。

回调行为变更

部分回调的行为将发生变化，具体如下表。你需要根据这些变化，调整相应的应用端逻辑。

接口	关闭音频选路	开启音频选路
onUserJoined	远端可见用户加入房间，或房内不可见用户切换为可见的回调。	房间内可见用户数 >500 后，该回调不触发。如果你需要完整的房间内用户名单，需要自行维护用户列表。
onUserLeave	远端可见用户下线或转为隐身	房间内可见用户数 >500 后，该回调不触发
onRoomStats （Web 端无此回调）	2 秒一次的房间内通话统计信息回调	房间内可见用户数 >500 后，回调的 RtcRoomStats{user_count} 值无效
onUserPublishStream	房间内新增远端摄像头/麦克风采集的媒体流回调	只能收到视频流触发的相关回调
onNetworkQuality	报告房间内用户的网络质量评分	回调有视频流的用户信息或远端活跃用户的网络质量评分
onRemoteStreamStats	订阅的远端用户发布的流在周期内的网络质量信息。	Native 端回调有视频流的用户信息或远端活跃用户的音频流传输信息。 Web 端不回调音频数据信息，视频与关闭音频选路行为一致。
onRemoteAudioPropertiesReport	订阅的远端用户的音频信息。	只回调远端活跃用户的音频信息。
onUserStartAudioCapture	远端用户开启音频采集	开启音频选路后，不会触发，与房间内用户数无关。
onUserStopAudioCapture	远端用户停止音频采集	开启音频选路后，不会触发，与房间内用户数无关。
onUserStartVideoCapture	远端用户开启视频采集	如果远端用户未发布视频流，不会收到该回调。如果远端用户发布视频流，则该回调将伴随 onUserPublishStream 触发一次。当监听 onUserStartVideoCapture 和 onUserPublishStream 时，可以认为远端已经开启视频采集。
onUserStopVideoCapture	远端用户停止视频采集	不会触发。当远端用户停止视频采集时，会触发 onUserPublishStreamVideo。当监听到 onUserPublishStreamVideo 时，可以认为远端已经停止视频采集。

微信小程序端

微信小程序端的音频选路使用方式与 Native、Web 等端有所不同。本节介绍微信小程序端接入音频选路的方法。

使用须知

微信小程序 RTC SDK 版本不低于 3.4.0。

其他注意事项：

音频订阅由系统托管：音频选路模式下，小程序端无法也无需调用 subscribe 或 unsubscribe 控制单个用户音频流。所有音频通过一路混音流下发。

活跃发言者列表：ON_ACTIVE_SPEAKERS 事件返回的列表是了解当前哪些用户正在被混音播放的唯一途径。你需要根据此列表更新 UI，例如展示正在说话的用户。

混音流播放失败：务必监听 STREAM_FAILED 事件。当 pushed 为 true 时，表示混音流播放失败。此时可向用户显示提示，或调用 refreshPushTrackUrl 手动恢复。

管理和监听选路状态

开启音频选路后，微信小程序 SDK 提供以下 API 和事件，用于管理和监听选路相关状态。

核心 API 和事件

核心 API

API 名称	功能描述
setAudioSelectionPriority	设置自身音频优先级。可将优先级设置为 High 或 Low，高优先级的用户被选为活跃发言者的可能性更大。
enableAudioPropertiesReport	开启或关闭远端用户发言回调。开启后，当活跃发言者变化时，通过 ON_ACTIVE_SPEAKERS 事件接收当前活跃发言者信息。
refreshPushTrackUrl	主动获取混音流地址。在网络断开重连等场景下，可主动刷新并获取最新的音频选路混音流播放地址。

核心事件

事件名称	触发时机与说明
ROOM_MODE_CHANGE	房间模式变更。房间内人数跨越阈值时，房间模式在“普通模式”和“音频选路模式”之间切换时触发。
ON_PUSH_TRACK	接收到混音流。房间进入音频选路模式时，SDK 通过此事件回调混音流播放地址（url），需使用此地址进行播放。
ON_ACTIVE_SPEAKERS	活跃发言者列表更新。开启 enableAudioPropertiesReport 后，服务端活跃发言者列表变化时，SDK 通过此事件回调最新的 activeSpeakers 用户 ID 列表。
STREAM_FAILED	流播放失败。混音流（pushed: true）因网络等原因播放失败且重试无效后触发。
UPDATE_URL	流地址更新。混音流（pushed: true）的播放地址因服务器调度等原因变更时触发，提供新的 url。

示例代码

以下是在微信小程序中使用音频选路功能的典型流程。

启用后对 API/回调的影响

API / 回调	普通模式（或音频选路未激活时）	音频选路模式激活后
音频订阅	通过 subscribe 订阅指定用户的音频流。	无需订阅音频。客户端自动接收服务端下发的混音流，不支持手动订阅或取消订阅单个用户音频。
视频订阅	通过 subscribe 订阅指定用户的视频流。	维持不变。视频订阅逻辑仍需由小程序端自行维护。

功能变更日志

Native，Electron 和 Flutter SDK v3.39 开始支持音频选路。

Web SDK v4.49 开始支持音频选路。

微信小程序 SDK v3.4.0 开始支持音频选路。

2023 年 6 月 8 日起，RTC 不再区分房间模式，只区分是否开启音频选路。

如果此前你已经在控制台开启相关配置，后台会自动为你切换到对应的配置。你也可以在下表中查看变更前后的配置对应关系。

变更前	变更后
普通模式（不开启音频选路）	不开启音频选路
普通模式（开启音频选路）	开启音频选路
大会模式	开启音频选路
大会模式 – 游戏场景	不开启音频选路

最近更新时间：2026.09.28 10:19:26

这个页面对您有帮助吗？

有用

无用