起播选档是指在视频开始播放前，根据用户的网络状况、设备信息及业务场景，智能选择一个最合适的清晰度进行播放。起播选档旨在优化视频的起播体验，在保障首帧速度的同时，尽可能提供更高的初始画质。与 ABR 播放的不同之处在于，起播选档仅在播放开始前进行一次选档决策。播放过程中，清晰度将保持不变，不会根据网络波动自动切换。本文适用于基于火山引擎自研协议的 Vid 或 VideoModel 播放源的起播选档。

初始化起播选档策略

在调用 FlutterTTSDKManager.startWithConfiguration 完成 SDK 的初始化之后，您需要紧接着调用 FlutterTTSDKManager.initStartupAutoSelectStrategy 来初始化起播选档策略模块。建议将 SDK 的初始化流程放在项目的 main.dart 文件 runApp 方法之前执行，以确保所有功能模块都能被正确初始化。

Future<void> initTTSDK() async {
     // 打开日志开关，便于调试
    FlutterTTSDKManager.openAllLog();
    
    // 注册插件日志, 可选择输出到控制台或本地文件，以便问题排查
    TTFLogger.onLog = (logLevel, msg) {
      print(msg);
    };

    // 参考集成 SDK 添加 License, 传入有效的 license 文件路径，如 'assets/VEVod.lic'
    String licPath = 'your license file path'; 
    // Android 平台请传入有效的渠道号，用于统计；iOS选填，默认为 App Store
    String channel = Platform.isAndroid ? 'your channel' : 'App Store';
    // 初始化配置
    TTSDKVodConfiguration vodConfig = TTSDKVodConfiguration();
    // 设置最大缓存 Size，默认 100 MB，可根据自身业务场景调整，超过缓存大小按照 LRU 规则清理
    vodConfig.cacheMaxSize = 300 * 1024 * 1024;
    
    // 传入在火山引擎点播控制台应用管理页面获取的 AppID
    TTSDKConfiguration sdkConfig =
        TTSDKConfiguration.defaultConfigurationWithAppIDAndLicPath(
            appID: 'your AppID', licenseFilePath: licPath, channel: channel);
    sdkConfig.vodConfiguration = vodConfig;
    await FlutterTTSDKManager.startWithConfiguration(sdkConfig);
    // 初始化起播选档策略模块
    await FlutterTTSDKManager.initStartupAutoSelectStrategy();
  }

配置起播选档

由于平台差异，iOS 与 Android 的起播选档配置方式有所不同。

Android 起播选档

在 Android 平台，您可以通过构建一个详细的配置对象来实现精细化的选档控制。

核心接入流程

1. 构建起播选档的配置对象 TTVideoABRStartupConfig。其中 displayWidth 和 displayHeight 是关键参数，请尽量将其设置为视频播放器控件的实际渲染尺寸，以保证选档的准确性。

   import 'dart:math' as math;
   
   // 获取屏幕和视频视图的尺寸
   final screenWidth = MediaQuery.of(context).size.width.toInt();
   final screenHeight = MediaQuery.of(context).size.height.toInt();
   final int minSide = math.min(screenWidth, screenHeight);
   
   // 创建起播选档配置实例
   TTVideoABRStartupConfig sharedAbrConfig = await TTVideoABRStartupConfig.create(
     screenWidth: screenWidth, // 当前设备的屏幕宽度
     screenHeight: screenHeight, // 当前设备的屏幕高度
     displayWidth: minSide, // 视频的实际展示宽度，关键参数
     displayHeight: (minSide / 9 * 16).toInt(), // 视频的实际展示高度，关键参数
     
     // ----- 可选配置 -----
     // 设置一个默认的起播清晰度，作为网络较差或信息不足时的兜底选项
     defaultResolution: TTVideoEngineResolutionType.TTVideoEngineResolutionTypeHD,
     // 限制 Wi-Fi 网络下，选档策略能选择的最高清晰度
     wifiMaxResolution: TTVideoEngineResolutionType.TTVideoEngineResolutionTypeFullHD,
     // 限制移动网络下，选档策略能选择的最高清晰度
     mobileMaxResolution: TTVideoEngineResolutionType.TTVideoEngineResolutionTypeHD_H,
     // 用户手动选择的清晰度。如果设置了此项，选档策略将优先采用该值，通常用于实现“记住用户的清晰度选择”功能
     userSelectedResolution: TTVideoEngineResolutionType.TTVideoEngineResolutionTypeFullHD,
     // 设置监听器，用于接收选档完成后的结果回调
     listener: TTVideoABRStartupResolutionListener(
       onResolutionSelected: (videoModel, resolution) {
          debugPrint('选档完成，最终选择的清晰度是: $resolution');
       },
     ),
   );
   

2. 在播放器上启用起播选档功能，并将上一步创建的配置实例绑定到播放器。

   // 启用起播选档功能
   await player.enableStartupAutoSelectBitrate(true);
   // 将配置实例绑定到播放器引擎
   await TTVideoABRStrategy.initEngine(player: player, config: sharedAbrConfig);
   

3. 正常设置 VideoModel 或 Vid 播放源并开始播放。SDK 将在内部根据您绑定的配置自动执行选档逻辑。

   final TTVideoPlayerView _playerView = TTVideoPlayerView(
     nativeViewType: NativeViewType.TextureView,
     onPlatformViewCreated: (viewId) async {
       await player.setPlayerContainerView(viewId);
       await player.setMediaSource(source); // source 应为 VidSource 或 VideoModelSource
       player.play();
     },
   );
   

监听选档结果

您可以在创建 TTVideoABRStartupConfig 时传入监听器，以便在选档完成后获取最终选择的清晰度。

TTVideoABRStartupConfig sharedAbrConfig = await TTVideoABRStartupConfig.create(
  // ... 其他配置
  // 设置选档完成的回调监听
  listener: TTVideoABRStartupResolutionListener(
    onResolutionSelected: (videoModel, resolution) {
      // resolution 参数即为最终选定的清晰度档位
      debugPrint('选档已完成，最终清晰度为: $resolution');
    },
  ),
);

结合预加载策略（推荐）

为了实现最佳的短视频滑动体验，我们强烈建议将起播选档与预加载策略结合使用。这样可以确保预加载缓存的视频就是选档策略计算出的最佳清晰度，从而最大化地提升播放性能。

1. 首先开启预加载策略：

   // 建议在进入短视频页面时开启
   TTVideoEngineStrategy.enableEngineStrategy(
             strategyType: TTVideoEngineStrategyType.preload, scene: TTVideoEngineStrategyScene.smallVideo);
   

2. 设置预加载的播放源列表：

   // 构建需要预加载的播放源列表
   final List<TTVideoEngineMediaSource> sources = [];
   // ... 将您的 VidSource 或 VideoModelSource 添加到 sources 列表
   await TTVideoEngineStrategy.setStrategyVideoSources(videoSources: sources);
   

3. 构建起播选档配置。如果配置不变，可以与播放时共用同一个 sharedAbrConfig 实例。

   TTVideoABRStartupConfig sharedAbrConfig = await TTVideoABRStartupConfig.create(...);
   

4. 为预加载任务配置选档策略。此步骤会将选档逻辑注入到预加载流程中。当预加载任务执行时，会先根据选档配置决定加载哪个清晰度，然后再进行缓存。

   // 启用预加载任务工厂
   await TTVideoEngineStrategy.setPreloadTaskFactory();
   // 为预加载任务更新（设置）起播选档配置
   await TTVideoEngineStrategy.updatePreloadABRConfig(config: sharedAbrConfig!);
   

结合自定义预加载使用

// 构建起播选档配置
TTVideoEngineABRStartupConfig sharedAbrConfig = await TTVideoABRStartupConfig.create(...);

// 创建 Vid 播放源
final TTVideoEngineVidSource vidSource = TTVideoEngineVidSource.init(
           vid: <vid>,
           playAuthToken: <playAuthToken>,
           resolution: <TTVideoEngineResolutionType>); // 此处 resolution 可设为默认值

// 构建 Vid 的自定义预加载项
final TTVideoEnginePreloaderVidItem item =
 TTVideoEnginePreloaderVidItem.vidItemWithVideoSource(
  vidSource, // 预加载的 VidSource
  800 * 1024, // 预加载大小，默认 800KB
  abrStartupConfig: sharedAbrConfig, // 传入起播选档配置
);

// 添加预加载任务
await TTVideoEnginePreload.addTaskWithVidItem(item);

// 构建起播选档配置，可以复用播放时的配置实例
TTVideoABRStartupConfig sharedAbrConfig = await TTVideoABRStartupConfig.create(...);

// 构建 VideoModel 的自定义预加载项
final TTVideoEnginePreloaderVideoModelItem item =
 TTVideoEnginePreloaderVideoModelItem.videoModelItemWithSource(
  videoModelSource, // 预加载的 VideoModelSource
  800 * 1024, // 预加载大小，单位：字节。默认 800KB
  abrStartupConfig: sharedAbrConfig, // 传入起播选档配置
);

// 添加预加载任务
await TTVideoEnginePreload.addTaskWithVideoModelItem(item);

iOS 起播选档

相较于 Android，iOS 平台的起播选档配置更为简单。您只需在设置播放源前开启一个开关即可，该设置会自动应用于播放、预加载策略及自定义预加载场景。

设置起播选档

// 创建 Vid 播放源
TTVideoEngineVidSource source = TTVideoEngineVidSource.init(
        vid: <vid>,
        playAuthToken: <playAuthToken>,
        resolution: <TTVideoEngineResolutionType>); // 此处 resolution 可设为默认值
        
// 关键：在设置播放源之前，打开起播选档开关
await player.enableStartupAutoSelectBitrate(true);

// 设置播放源
player.setMediaSource(source);

// 创建 VideoModel 播放源
TTVideoEngineVideoModelSource videoModelSource = TTVideoEngineVideoModelSource.init(
  vid: 'v1234567890',
  resolution: TTVideoEngineResolutionType.TTVideoEngineResolutionType1080P, // 此处 resolution 可设为默认值
  playInfoList: items,
  duration: 123.45,
);

// 关键：在设置播放源之前，打开起播选档开关
await player.enableStartupAutoSelectBitrate(true);

// 设置播放源
player.setMediaSource(videoModelSource);

监听选档结果

为播放器实例设置 onVideoEngineAutoSelectResolution 回调函数。当选档完成后，该函数将被触发，并回传最终选择的清晰度。

player.onVideoEngineAutoSelectResolution = (TTVideoEngineResolutionType resolution) {
  // resolution 即为选档后的清晰度结果
  debugPrint('iOS 选档完成，最终清晰度为: $resolution');
};