起播选档（初始码率选择）功能可让播放器在播放开始前，根据当前网络状况、用户历史偏好或您指定的策略，智能地选择最合适的初始清晰度（码率）。此功能旨在优化用户的首次观看体验，既能避免在弱网环境下因码率过高导致的起播缓慢或卡顿，也能避免在强网环境下因码率过低造成的画质不佳。
例如，您可以配置策略，实现在 Wi-Fi 环境下以 1080P 起播，而在移动网络下以 480P 起播，从而节省用户流量并加快起播速度。

全局初始化 #

你必须在 SDK 初始化时全局开启起播选档功能。在调用 initEnv 方法时，将 EnableStartSelect 参数设置为 true。

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

initEnv({
  // ... 其他初始化配置
  EnableStartSelect: true,
});

平台实现指引 #

由于 Android 与 iOS 原生层的实现逻辑不同，请根据目标平台参考相应的配置方式。

Android 端实现 #

创建起播选档策略

调用 createStartupConfig 创建起播选档策略对象，定义播放器在起播时的码率决策逻辑。

import { Dimensions, PixelRatio } from 'react-native';
import { createStartupConfig, ResolutionType } 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 startupConfig = createStartupConfig({
  screenWidth: screenWidthPx,  // 设备屏幕宽度（物理像素）
  screenHeight: screenHeightPx,  // 设备屏幕高度（物理像素）
  displayWidth: displayWidthPx, // 视频渲染区域的宽度（物理像素）
  displayHeight: displayHeightPx, // 视频渲染区域的高度（物理像素）
  defaultResolution: ResolutionType.High, // 默认清晰度。在无网络测速信息或初次播放时使用。
  wifiMaxResolution: ResolutionType.ExtremelyHigh, // Wi-Fi 下最高播放 1080P
  mobileMaxResolution: ResolutionType.SuperHigh,  // 移动网络下最高播放 720P
  userSelectedResolution: ResolutionType.SuperHigh, // 如果用户上次选择了 720P，则优先使用此档位
});

StartupConfigParams 对象详细参数如下：

监听选档结果

如需在 UI 上反馈最终选定的档位，可在创建配置时传入回调函数。

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

createStartupConfig(config, (resolution: ResolutionType) => {
  // 可在此更新 UI 上的清晰度标签
  console.log(`complete select resolution ${resolution}`)
})

绑定并开启起播选档

为播放器实例开启播放缓存，并为其绑定起播选档配置。

player.enablePlayCachedSource();
player.bindABRConfig(startupConfig);

iOS 端实现 #

iOS 端的起播选档实现较为简单，主要通过开启功能开关，由系统及 SDK 自动完成决策。

开启起播选档

在创建播放器实例后、设置播放源前，开启缓存和选档开关。

// 使用播放缓存
player.enablePlayCachedSource();
// 开启选档开关
player.enableStartupSelect();

监听选档结果

通过专有监听接口获取最终决策的清晰度。

player.setStartupSelectedResolutionListener((resolution: ResolutionType) => {
  console.log(`complete select resolution ${resolution}`)
})

进阶场景集成（仅 Android） #

结合预加载策略

如果您要将预加载策略与起播选档结合使用，需要设置PreloadTaskFactory 回调。此操作可确保在“自动档”模式下，SDK 能够决策出与起播档位相符的预加载档位。这保证了起播时能成功命中预加载的内容，从而加快视频的加载速度。

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

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

// 设置预加载任务
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: abrStartupConfig,    // 起播选档配置
    })

结合预渲染策略

如果您要将预渲染策略与起播选档结合使用，需要在预渲染的回调onPlayerCreated中开启相应的开关，并绑定选档配置，其他无差异。

import { createStartupConfig, ResolutionType } from '@volcengine/react-native-vod-player';
 
 const abrStartupConfig = createStartupConfig(config, (resolution) => {
   // ...
 });
 
 setPreRenderCallback({
     onPlayerCreated(player: TTVideoEngine, source: VideoSource) {
       // 打开播放缓存开关
       player.enablePlayCachedSource();
       // 绑定起播选档配置
       player.bindABRConfig(abrStartupConfig);
     }
 })