大小流、回退与带宽控制

双流/小流、订阅回退策略、动态订阅（Dynacast）、编码参数与带宽估算。

版本 v1.1.0 · 更新于 2026-10-26 · 修订 1

弱网下最重要的不是「把码率调低」，而是让每一端都能按自己的带宽选择看点。这一页讲大小流、订阅回退、动态订阅与编码参数这四件事，以及它们在你代码里的确切方法名。

四个概念

概念	作用	Web 端方法
双流（dual stream）	发布端同时发大流和小流；订阅端按带宽选	`enableDualStream()` / `setDualStreamMode(mode, streamParameter)`
订阅回退（fallback）	带宽不够时自动降级到小流、再到纯音频	`setStreamFallbackOption(uid, fallbackType)`
远端流类型	手动指定：看大流还是小流	`setRemoteVideoStreamType(uid, streamType)` / `setRemoteDefaultVideoStreamType(streamType)`
小流参数	控制小流的分辨率/帧率/码率上限	`setLowStreamParameter(streamParameter)`

典型配置

javascript

import AgoraRTC from '@nimeet/rtc-web';

const client = AgoraRTC.createClient({ mode: 'rtc' });
await client.join(appId, 'weekly-sync', token, uid);

// 1) 发布端开启双流（发布前设置生效）
client.setLowStreamParameter({ width: 320, height: 180, framerate: 15, bitrate: 150 });
await client.enableDualStream();

// 2) 订阅端：网络差时自动降级到小流、再降级到纯音频
await client.setStreamFallbackOption(remoteUid, 2);

// 3) 或者手动控制：只订阅小流
await client.setRemoteVideoStreamType(remoteUid, 1);   // 1 = 小流

// 4) 全局默认：新出现的远端用户默认用小流（大屏布局再单独调大）
await client.setRemoteDefaultVideoStreamType(1);

什么时候用哪个

场景	建议
1v1 通话	不需要双流；直接按带宽调 `encoderConfig`
小班课（< 10 人）	主讲人大流，其余订阅小流，`setStreamFallbackOption(uid, 2)`
大班课/直播（观众多）	观众全部小流或纯音频；主播端开双流
屏幕共享演示	共享流用「优先清晰度」，摄像头流用小流
移动端弱网	订阅小流 + 纯音频回退，配合音量指示

编码参数

javascript

// 摄像头轨道创建时指定
const cameraTrack = await AgoraRTC.createCameraVideoTrack({
  encoderConfig: { width: 1280, height: 720, frameRate: 20, bitrateMax: 1500 },
});

// 运行中调整（部分端支持）
cameraTrack.setEncoderConfiguration({ width: 640, height: 360, frameRate: 15 });

参数	建议值	说明
分辨率	1v1: 720p；小班课: 640×360 或 720p；大班课观众: 不订阅视频	分辨率对带宽影响最大
帧率	15–20fps（内容型）/ 24–30fps（人物）	降到 15 通常比降分辨率体感更差
码率上限	360p ≈ 500kbps，720p ≈ 1.5Mbps	与服务端 `usage` 计量口径一致
降级偏好	`maintain-framerate` / `maintain-resolution` / `balanced`	屏幕共享优先清晰度，人物优先帧率

事件与观测

事件	用途
`stream-fallback`	某用户的流发生了回退（可提示「对方网络较差」）
`stream-type-changed`	大流/小流切换完成
`network-quality`	周期上报上行/下行质量（1–6 级）
`getRTCStats()`	本地/远端统计，字段口径与水晶球一致

把这些事件上报到 POST /v1/analytics/quality 就能在水晶球里看到质量曲线（示例 09-quality-ingest.mjs）。

常见问题

现象	原因	处理
`enableDualStream` 报 `NOT_SUPPORTED`	当前媒体栈未提供 simulcast	改为单流 + 按带宽调编码参数
切换小流后画面仍然卡	大流已订阅且未解除	先 `setRemoteVideoStreamType` 再观察 `stream-type-changed`
回退没有发生	发布端没开双流	回退的前提是存在小流
观众端 CPU 高	订阅了多路大流	默认小流 + 只订阅可见用户
码率降不下来	编码参数被轨道初始化固定	创建轨道时就设对，运行中调整不是所有端都支持

大小流、回退与带宽控制

四个概念#

典型配置#

什么时候用哪个#

编码参数#

事件与观测#

常见问题#