实时音视频
实时音视频
文档指南
请输入
- 文档首页
实时音视频实时音视频开发指南音频选路
复制全文
下载 pdf音频选路
文档反馈
问问助手在大规模音视频互动场景中，大量用户同时开麦发言会消耗巨大带宽和设备性能。开启音频选路功能后，RTC 引擎将智能托管音频订阅关系，识别活跃发言者并定向分发，减少每个客户端接收的音频流数量，从而在保障互动流畅度的同时，大幅降低客户端负载。
应用场景
开启或关闭音频选路
- 登录 RTC 控制台。
- （可选）如果你还没创建应用，请先创建 RTC 应用。
- 应用创建成功后，音频选路默认为关闭状态。
说明
推荐使用不同的 appID 开发适用于不同场景的音视频应用。是否开启音频选路的应用场景差别较大，尽量避免在用户使用时进行切换。
- 进入功能配置 > 房间模式，选择目标应用，按需开启或关闭音频选路。
使用说明
Native/Web/Flutter/Electron 端
使用须知
开启音频选路功能后，请注意以下事项：
- 容量上限：房间内用户和媒体流容量会同步提升。详见用户和媒体流上限。
- 发布失败：流数量达上限后，PublishStream 返回 -1080（Web 端没有对应的错误码，会触发发布失败）。
- 订阅失败：订阅流达上限后，SubscribeStream 返回 -1070（Web 端没有对应的错误码，会触发发布失败）。
- 订阅逻辑变更：
- 视频订阅：仍需在客户端手动维护订阅关系。
- 音频订阅：
- Native 端：支持取消订阅对方音频。例如，A 取消订阅 B 的音频，即使 B 的音频被选为活跃用户并推送，A 也不会收听到 B 的音频。
- Web 端：不支持取消订阅某用户音频。
- 生效房间：仅对新创建的房间生效，不会影响已存在的房间模式。
- 激活条件：启用音频选路后，当房间内用户数超过 5 人时，部分 API 和回调的行为会发生变化。具体影响，请参见启用音频选路对相关接口的影响。
启用后对 API/回调的影响
启用音频选路后，部分接口和回调行为将发生变化，具体触发条件见下表（以 Windows SDK 为例）。
- API 行为变更
-
- 接口关闭音频选路开启音频选路自动订阅音频。无效，音频订阅关系由 RTC 系统智能托管。订阅指定用户音视频流。视频：与关闭音频选路时相同。音频：无需调用，音频订阅关系由 RTC 系统智能托管。
- 回调行为变更
- 部分回调的行为将发生变化，具体如下表。你需要根据这些变化，调整相应的应用端逻辑。
-
-
微信小程序端
微信小程序端的音频选路使用方式与 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主动获取混音流地址。在网络断开重连等场景下，可主动刷新并获取最新的音频选路混音流播放地址。
- 核心事件
-
-
示例代码
以下是在微信小程序中使用音频选路功能的典型流程。
// 1. 引入并初始化 SDK
const { Client } = require('./VolcEngineRTC_MiniApp');
const client = Client.init('YOUR_APP_ID');
// 2. 监听核心事件
// 监听房间模式变化
client.on('room-mode-change', (e) => {
if (e.currMode === 'MultiChat') {
console.log('房间已进入音频选路模式');
} else {
console.log('房间已切换为普通模式');
}
});
// 接收并播放混音流
client.on('on-push-track', (e) => {
// 使用 <live-player> 播放 e.url
});
// 混音流地址更新
client.on('update-url', (e) => {
if (e.pushed) { // 确保是混音流
// 更新混音流的 url
}
});
// 监听活跃发言者列表
client.on('on-active-speakers', (e) => {
// 在 UI 上更新活跃发言者列表
});
// 监听混音流播放失败
client.on('stream-failed', (e) => {
if (e.pushed) { // 确保是混音流
// 添加 UI 提示或重试逻辑
}
});
// 3. 加入房间并执行操作
async function joinAndSetup() {
try {
// 开启远端用户音量回调，以接收 ON_ACTIVE_SPEAKERS 事件
await client.enableAudioPropertiesReport(true);
// 加入房间
await client.join({
token: 'YOUR_TOKEN',
roomId: 'YOUR_ROOM_ID',
userId: 'YOUR_USER_ID',
});
// 发布自己的音频流
await client.publish();
// 将自己设置为高优先级发言者
await client.setAudioSelectionPriority(AudioSelectionPriority.High);
} catch (error) {
console.error('An error occurred:', error);
}
}
joinAndSetup();
启用后对 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
这个页面对您有帮助吗？
有用
有用
无用
无用