智能降码流接入指南

1. 功能说明

智能降码流用于优化在线歌曲在弱网环境下的起播和播放体验。SDK 会根据当前歌曲的实际资源、实测网速和播放状态，降低当前歌曲的视频或音频清晰度。

该功能具有以下边界：

默认关闭，由接入方显式开启。

只影响当前歌曲，不修改下一首歌曲或 SDK 的全局默认清晰度。

2. 开启功能

在播放器配置提交前开启智能降码流：

未调用 setEnableAutoBitrateDowngrade(true) 时，功能保持关闭。

分阶段起播超时属于基础播放保护，默认开启，不依赖智能降码流开关。关闭智能降码流后，资源解析、音频缓冲、MV 首帧和音视频整体起播仍有明确的超时上限。

3. 降级规则

3.1 MV 清晰度选择

SDK 不按 4K → 1080P → 720P → 480P 逐档试降，而是执行一次匹配：

获取服务端为当前歌曲实际返回的较低 MV 档位。

根据 MV 文件大小和歌曲时长估算各档位的平均带宽消耗。

综合实测网速、音频消耗和安全余量。

从高到低选择能够支持流畅播放的最高可用档位。

如果当前已经处于最低档、没有可降档资源，或者切换低档后仍无法播放，SDK 会关闭当前歌曲的 MV，并触发大图或本地视频兜底回调。

播放中切换视频清晰度复用播放器的无重播切换能力，不会重新播放歌曲。

3.2 音频降级边界

起播带宽不足时，可以同时降低当前歌曲的 MV 和 HQ 音频。

起播阶段 HQ 音频未及时达到可播放条件时，最多尝试一次普通音质。切换音质并重新解析 URL 后，新的音频下载阶段重新获得完整的超时预算。

MV 首帧超时或播放中 MV 多次缓冲时，只处理视频，不降低音频。

播放中明确发生音频资源持续不足时，HQ 音频最多尝试一次普通音质。

音频资源变化需要重建当前歌曲播放器，SDK 会恢复降级前的播放位置和暂停状态。

4. 降级结果回调

降级实际生效后，SDK 通过 KaraokePlayerListener.onAutoBitrateChanged 通知接入方。接入方可以根据 trigger 和 action 提示用户：

一次起播过程中可能先完成音频降级，随后再发生 MV 降档或关闭 MV。这些属于独立事件，SDK 会按实际生效结果分别回调。

4.1 AutoBitrateChangeInfo 字段

字段	说明
`trigger`	触发场景，见下表
`action`	`ACTION_*` 的按位组合，可以同时包含视频和音频降级
`oldVideoQuality/newVideoQuality`	降级前后的 MV 清晰度
`oldAudioQuality/newAudioQuality`	降级前后的音频清晰度
`networkSpeedKBps`	实测网速，单位 KB/s；`-1` 表示无法获取
`playbackRestarted`	是否因音频资源变化重建了当前歌曲播放器
`reason`	`REASON_BANDWIDTH_INSUFFICIENT` 或 `REASON_NETWORK_SPEED_UNKNOWN`
`attempt`	当前歌曲第几次执行智能降码流，从 1 开始

4.2 trigger 取值

常量	触发场景
`TRIGGER_STARTUP_BANDWIDTH_PREDICTED`	起播阶段检测到带宽不足
`TRIGGER_STARTUP_AUDIO_BUFFER_TIMEOUT`	起播音频缓冲未及时达到可播放条件
`TRIGGER_VIDEO_FIRST_FRAME_TIMEOUT`	MV 首帧软超时或硬超时
`TRIGGER_PLAYING_BUFFERING`	播放中 MV 多次缓冲
`TRIGGER_PLAYING_AUDIO_BUFFERING`	播放中音频资源持续不足

4.3 action 取值

常量	说明
`ACTION_DOWNGRADE_VIDEO`	已降低 MV 清晰度
`ACTION_CLOSE_VIDEO`	已关闭当前歌曲 MV，进入大图或本地视频兜底模式
`ACTION_DOWNGRADE_AUDIO`	已降低音频清晰度

5. MV 关闭后的兜底处理

当 MV 无法继续播放时，SDK 通过 onShowPicture 把歌曲封面地址和错误状态通知接入方。SDK 核心不会强制创建 UI 或占用接入方的视频容器，接入方可以自行显示歌曲封面、默认图片或本地循环视频。

智能降码流接入文档

智能降码流接入指南#

1. 功能说明#

2. 开启功能#

3. 降级规则#

3.1 MV 清晰度选择#

3.2 音频降级边界#

4. 降级结果回调#

4.1 AutoBitrateChangeInfo 字段#

4.2 trigger 取值#

4.3 action 取值#

5. MV 关闭后的兜底处理#