自适应码率播放（Adaptive Bitrate Streaming, ABR）是播放器在播放过程中，根据当前网络带宽、设备性能等因素，自动、平滑地在多个清晰度（码率）档位间切换，以保障在网络波动时，用户仍能获得流畅、高质量的观看体验，最大程度减少卡顿。
例如，在 Wi-Fi 环境下，播放器可以自动选择 1080p 高清档位；当网络切换到移动数据或信号变差时，播放器自动降级到 720p 或更低的档位，避免播放中断。当网络恢复后，再自动切换回高清档位。

使用限制 #

• ABR 支持 MP4 和 HLS 两种视频格式。如果使用 MP4 格式，您需要确保不同清晰度的视频是帧对齐的。如不确定视频是否帧对齐，可以联系技术支持进行确认。
• 仅支持 Vid 模式和 VideoModel 模式下的 ABR。
• ABR 播放为增值功能。请确保您的 License 已包含 ABR 播放功能，详细步骤请见 License 管理。

核心接入流程 #

步骤 1：全局开启 ABR 功能 #

在 SDK 初始化阶段，将 EnableABR 设为 true，全局开启 ABR 功能。

import { initEnv, ResolutionType } from '@volcengine/react-native-vod-player';

initEnv({
  // ... 其他初始化配置
  /** 全局启用 ABR 策略模块 */
  EnableABR: true,
  /** 
   * iOS 专属：默认 ABR 清晰度。
   * 在播放器冷启动、或暂无网络测速信息时，首个视频起播将参考此档位。
   */
  DefaultABRResolution: ResolutionType.High
});

步骤 2：配置并绑定 ABR 策略 #

1. 创建策略对象：调用 createABRConfig 方法创建一个 ABR 策略对象，定义播放器在不同网络环境下的码率选择行为。

import {Dimensions, PixelRatio} from 'react-native';
import { createABRConfig } from '@volcengine/react-native-vod-player';

const screen = Dimensions.get('window');
const screenWidthPx = PixelRatio.getPixelSizeForLayoutSize(screen.width);
const screenHeightPx = PixelRatio.getPixelSizeForLayoutSize(screen.height);
const displayWidthPx = PixelRatio.getPixelSizeForLayoutSize(
  Math.min(screen.width, screen.height),
);
const displayHeightPx = Math.round(displayWidthPx * (16 / 9));

const abrConfig = createABRConfig({
  screenWidth: screenWidthPx,  // 设备屏幕宽度（物理像素）
  screenHeight: screenHeightPx,  // 设备屏幕高度（物理像素）
  displayWidth: displayWidthPx, // 视频渲染区域的宽度（物理像素）
  displayHeight: displayHeightPx, // 视频渲染区域的高度（物理像素）
  defaultResolution: ResolutionType.High, // 默认清晰度。在无网络测速信息或初次播放时使用。
  wifiMaxResolution: ResolutionType.ExtremelyHigh, // Wi-Fi 下最高播放 1080P
  mobileMaxResolution: ResolutionType.SuperHigh,  // 移动网络下最高播放 720P
});

ABRConfigParams 对象的详细参数说明如下：

2. 绑定到播放器：创建 ABR 策略对象后，在播放器准备好后调用 bindABRConfig 方法将其绑定到播放器实例。

// player 是通过 usePlayer() hook 获取的播放器实例
if (player && abrConfig) {
  player.bindABRConfig(abrConfig);
}

3. （可选）动态更新策略：若播放过程中发生场景变化（如进入全屏、视图尺寸改变），需要更新 ABR 配置以适应新的 View 大小或调整清晰度策略。

const newAbrConfig = createABRConfig(newConfig)

player.setABRConfig(newAbrConfig)

步骤 3：开启 ABR 播放 #

1. 开启平滑切换功能和播放源缓存：

// HLS 视频开启平滑切换
await player.enableHLSSeamlessSwitch(true);
// MP4 视频开启平滑切换
// await player.enableMP4SeamlessSwitch(true);

// 使用播放源缓存
player.enablePlayCachedSource();

2. 设置播放源的清晰度为 Auto。

   • 可以在构造播放源时直接指定：
   Vid 模式

   VideoModel 模式

   import { createVidSource, ResolutionType } from '@volcengine/react-native-vod-player';
      
      const source = createVidSource({
         vid: '******',
         playAuthToken: '************',
         resolution: ResolutionType.Auto
      })
   

   import { createVidSource, createVideoModelSource, ResolutionType } from '@volcengine/react-native-vod-player';
      
      const source = createVideoModelSource({
         vid: '******',
         duration: 634.567, // video duration
         resolution: ResolutionType.Auto, // default video resolution when start play
         playInfoList: [...]
      })
   

   • 也可以在构造播放源后，调用 configResolution 指定清晰度为 Auto：

   // 切换为自动选档（开启 ABR）
   player.configResolution(ResolutionType.Auto);
   
   // 切换为固定清晰度（关闭 ABR）
   player.configResolution(ResolutionType.High);
   

播放中的交互与监听 #

获取当前真实清晰度 #

• 主动获取：

const curRealResolution = player.getCurrentResolution();

• 回调监听：如果您需要实时更新 UI（例如清晰度选择按钮上的文字标签），建议通过监听清晰度变更事件来获取。

player.setListener({
  onVideoBitrateChanged: (resolution, bitrate) => {
    // 当 ABR 发生切档决策时回调
    // resolution 为具体档位（如 ResolutionType.High），而非 Auto
    console.log(`ABR 策略已自动切换清晰度至: ${resolution}`);
    updateUIScale(resolution);
  },
});

构建 UI 清晰度列表 #

在 Vid 和 VideoModel 模式下，supportedResolutionTypes() 方法仅返回视频源支持的固定档位。若需展示“自动”选项，需手动构建列表。

import { ResolutionType } from '@volcengine/react-native-vod-player';

const list = player.supportedResolutionTypes();
const listWithAuto = [ResolutionType.Auto, ...list];
// 渲染带自动档的清晰度列表
renderResolutionList(listWithAuto);

进阶使用 #

结合预加载策略 #

如果您要将预加载策略与 ABR 结合使用，就需要设置 PreloadTaskFactory 回调。这能确保在以“自动”档起播时，ABR 策略所选择的预加载清晰度与实际起播的清晰度保持一致，从而命中预加载缓存，加快起播速度。

import { setPreloadTaskConfig, ResolutionType } from '@volcengine/react-native-vod-player';

// 设置预加载任务的配置
setPreloadTaskConfig({
    preloadResolution: ResolutionType.Auto,
    ABRConfig: abrConfig
})

// 设置预加载任务
setPreloadTaskFactory()

结合自定义预加载 #

如果您使用自定义预加载，在创建预加载任务时，需将清晰度设置为 Auto 并传入 ABR 策略配置。这样，实际进行预加载的视频档位将由该 ABR 策略决定。

/**
 * 预加载配置接口
 */
export interface PreloadConfig {
  /** 预加载大小（字节），默认800KB */
  preloadSize?: number;
  /** 预加载清晰度, 仅安卓有效 */
  preloadResolution?: ResolutionType;
  /** 预加载选档配置, 仅安卓有效 */
  ABRConfig?: TTVideoABRStartupConfig | TTVideoABRConfig;
}

const taskId = preloadVidSource(
    vidSource,
    {
     preloadSize: 800 * 1024,
     preloadResolution: ResolutionType.Auto,  // 指定为Auto档
     ABRConfig: startupAbrConfig,    // ABR 策略配置
    })

结合预渲染策略 #

如果您要将预渲染策略与 ABR 结合使用，您需要在 onPlayerCreated 回调中开启 ABR 相关功能，并绑定 ABR 策略配置。

const abrStartupConfig = createStartupConfig(config, (resolution) => {
   // ...
 });
 
 setPreRenderCallback({
     async onPlayerCreated(player: TTVideoEngine, source: VideoSource) {
       // 打开播放缓存开关
       player.enablePlayCachedSource();
       // HLS 视频开启平滑切换
       await player.enableHLSSeamlessSwitch(true);
       // MP4 视频开启平滑切换
       // await player.enableMP4SeamlessSwitch(true);
       // 绑定 ABR 策略配置
       player.bindABRConfig(abrStartupConfig);
     }
 })