自适应码流（Adaptive Bitrate Streaming, ABR）播放是指在播放过程中根据用户的网络状况动态地、无缝地切换到最合适的清晰度，从而在保障视频流畅播放的同时，为用户提供最佳的观看体验。本文指导您如何通过播放器 SDK 实现 ABR 播放：

• Vid 模式：适用于播放火山引擎点播服务生成的自研协议 DASH 和 HLS 视频。
• DirectUrl 模式：适用于播放标准协议的 HLS Master M3U8 视频。URL 可来自火山引擎或第三方服务。

前提条件

在集成 ABR 播放功能前，请确保您已完成以下操作：

• 获取 License：ABR 播放为增值功能。请确保您的 License 已包含 ABR 播放功能，详细步骤请见 License 管理。
• 集成高级版 SDK：参考集成 SDK 文档集成 1.47.2.3 或之后版本的高级版 SDK。
• 完成基础的 SDK 初始化：参考快速开始文档完成项目的基本配置和 SDK 初始化。

通用 ABR 配置

本节介绍 ABR 播放模式下通用的配置项，这些配置适用于 Vid 模式和 DirectUrl 模式。

初始化 ABR 功能

在 SDK 初始化之前，全局开启 ABR 相关的配置。

/// 1. 在 SDK 初始化之前，全局开启带宽检测模块，此模块是 ABR 功能的基础
[TTVideoEngine setGlobalForKey:VEGSKeyAlgoOptionEnableModuleBandwidth value:@(YES)];

/// 2. 设置 ABR 默认清晰度。此清晰度将在播放器冷启动、或无可用网络测速信息时作为首个起播视频的默认分辨率。
[TTVideoEngineStrategyABRAlgoConfig shareInstance].defaultResolution = TTVideoEngineResolutionTypeHD;

/// 3. 初始化 SDK
// configuration 是 SDK 初始化配置对象，需参考「快速开始」文档创建
[TTSDKManager startWithConfiguration:configuration];

开启/关闭 ABR

通过 configResolution 方法控制 ABR 功能的开启与关闭。

开启 ABR

指定清晰度档位为 TTVideoEngineResolutionTypeABRAuto 即可开启 ABR。开启 ABR 后，播放器将根据网络状况自动切换视频清晰度。同时，建议开启平滑切换开关以优化用户体验。

// 1. 开启平滑切换开关
[self.videoEngine setOptionForKey:VEKKeyPlayerHLSSeamlessSwitchEnable_BOOL value:@(YES)];

// 2. 指定清晰度档位为 TTVideoEngineResolutionTypeABRAuto 即可开启 ABR。
[self.videoEngine configResolution:TTVideoEngineResolutionTypeABRAuto];

关闭 ABR

通过指定一个固定的清晰度（例如 TTVideoEngineResolutionTypeFullHD），即可关闭 ABR 功能。

[self.videoEngine configResolution:TTVideoEngineResolutionTypeFullHD];

监听 ABR 事件回调

通过实现 TTVideoEngineABRDelegate 协议，您可以在 ABR 切换清晰度的关键节点接收事件通知，以便在业务层做出相应处理，例如更新 UI 状态。TTVideoEngineABRDelegate 协议提供了多个可选的事件回调方法，您可以按需实现。

/**
 * @locale zh
 * @type callback
 * @brief ABR 相关回调
 */
@protocol TTVideoEngineABRDelegate <NSObject>

@optional

/**
 * @locale zh
 * @type api
 * @brief ABR 当前选择档位回调
 * @param videoEngine egnine 实例
 * @param resolution 分辨率档位
 */
- (void)videoEngineAbrSelectResolution:(TTVideoEngine *)videoEngine resolution:(TTVideoEngineResolutionType)resolution;

/**
 * @locale zh
 * @type api
 * @brief 将要切换 ABR 选择档位的回调
 * @param videoEngine egnine 实例
 * @param resolution 分辨率档位
 */
- (void)videoEngineAbrWillSelectResolution:(TTVideoEngine *)videoEngine resolution:(TTVideoEngineResolutionType)resolution;

/**
 * @locale zh
 * @type api
 * @brief 切换 ABR 选择档位完成回调
 * @param videoEngine egnine 实例
 * @param resolution 分辨率档位
 */
- (void)videoEngineAbrEndSelectResolution:(TTVideoEngine *)videoEngine resolution:(TTVideoEngineResolutionType)resolution;

@end

回调实现示例：

@interface ExampleViewController () <TTVideoEngineABRDelegate>
// ...
@end

@implementation ExampleViewController

- (void)initializeVideoEngine {
    // ...
    self.videoEngine.abrDelegate = self;
}

#pragma mark -- TTVideoEngineABRDelegate (Event Listening)

- (void)videoEngineAbrWillSelectResolution:(TTVideoEngine *)videoEngine resolution:(TTVideoEngineResolutionType)resolution {
    NSLog(@"[ABR Event] 分辨率即将切换为: %@", @(resolution));
    // 可以在此显示“正在切换清晰度...”的 UI 提示
}

- (void)videoEngineAbrEndSelectResolution:(TTVideoEngine *)videoEngine resolution:(TTVideoEngineResolutionType)resolution {
    NSLog(@"[ABR Event] 分辨率已成功切换为: %@", @(resolution));
    // 可以在此更新 UI，移除提示
}

@end

配置 ABR 播放实例参数（可选）

除了监听事件，您还可以通过实现 TTVideoEngineABRDelegate 协议中的 videoEngineAbrConfig 方法，来主动为 ABR 算法提供配置，从而精细化控制其行为，例如限制不同网络环境下的最高播放清晰度。
TTVideoEngineStrategyABRConfig 参数说明如下：

/**
 * @locale zh
 * @type keytype
 * @brief ABR 相关配置对象，用于对 TTVideoEngine 实例进行配置
 */
@interface TTVideoEngineStrategyABRConfig : NSObject

/**
 * @locale zh
 * @brief WiFi 网络下允许 ABR 切换的最高清晰度档位。
 * @discussion 设置此项可避免在 WiFi 环境下无限制地上切到过高分辨率，节省带宽。
 */
@property (nonatomic, assign) TTVideoEngineResolutionType wifiMaxResolution;

/**
 * @locale zh
 * @brief 移动网络下允许 ABR 切换的最高清晰度档位。
 * @discussion 移动网络通常带宽有限且可能产生流量费用，限制最高分辨率可优化用户体验和流量消耗。
 */
@property (nonatomic, assign) TTVideoEngineResolutionType mobileMaxResolution;

@end

在您的 TTVideoEngineABRDelegate 代理实现中，添加 videoEngineAbrConfig: 方法，并返回一个配置好的 TTVideoEngineStrategyABRConfig 实例。

#pragma mark -- TTVideoEngineABRDelegate (Parameter Configuration)

/**
 * @locale zh
 * @type api
 * @brief 获取 ABR 配置回调
 * @param videoEngine 播放器实例
 * @return 返回 ABR 配置实例
 * @discussion SDK 会在需要时调用此方法来获取 ABR 运行参数。
 */
- (TTVideoEngineStrategyABRConfig *)videoEngineAbrConfig:(TTVideoEngine *)videoEngine {
    // 创建配置实例
    TTVideoEngineStrategyABRConfig *abrConfig = [[TTVideoEngineStrategyABRConfig alloc] init];

    // 根据业务逻辑设置参数，例如从全局设置中读取限制
    abrConfig.wifiMaxResolution = TTVideoEngineResolutionType1080P; // WiFi 环境最高 1080P
    abrConfig.mobileMaxResolution = TTVideoEngineResolutionTypeHD;  // 移动网络最高 720P

    return abrConfig;
}

Vid 模式下的 ABR 播放

如需在 Vid 播放模式下实现火山引擎自研协议 DASH 和 HLS 视频的 ABR 播放，您仅需按照通用 ABR 配置章节中的指引完成 ABR 的初始化、开启/关闭以及回调设置，然后正常开始播放即可。

DirectUrl 模式下 Master M3U8 视频的 ABR 播放

本节指导您在 DirectUrl 模式下实现标准协议 HLS Master M3U8 视频的 ABR 播放。Master M3U8 视频的 URL 可以来自火山引擎视频点播服务，也可以来自第三方服务。

注意事项

请务必确保您的 Master M3U8 文件中，每个 #EXT-X-STREAM-INF 标签内都包含 RESOLUTION 和 AVERAGE-BANDWIDTH 两个属性。示例：

#EXT-X-STREAM-INF:BANDWIDTH=2628000,AVERAGE-BANDWIDTH=2500000,RESOLUTION=...
/path/to/1080p.m3u8

核心接入流程

1. 通用配置：按照通用 ABR 配置章节，完成 ABR 的初始化、回调设置。

2. 开启 Master M3U8 ABR 特有设置：在播放器设置 URL 之前，额外进行以下配置：

   // 1. 开启平滑切换开关
   [self.videoEngine setOptionForKey:VEKKeyPlayerHLSSeamlessSwitchEnable_BOOL value:@(YES)];
   
   // 2. 开启 Master M3U8 的 ABR 开关，使 SDK 能够解析并应用 ABR 策略。
   [self.videoEngine setOptionForKey:VEKKeyStrategyEnableMasterM3u8ABR_BOOL value:@(YES)];
   
   // 3. 传入 Master M3U8 中分辨率字符串和 SDK 清晰度枚举的映射。
   // 业务需根据实际 Master M3U8 文件中包含的分辨率字符串进行设置，以下为示例。
   NSDictionary<NSString *, NSNumber *> *resolutionMap = @{
       @"640x360": @(TTVideoEngineResolutionTypeSD),
       @"854x480": @(TTVideoEngineResolutionTypeHD),
       @"960x540": @(TTVideoEngineResolutionTypeHD_H),
       @"1280x720": @(TTVideoEngineResolutionTypeFullHD),
       @"1920x1080": @(TTVideoEngineResolutionType1080P)
   };
   self.videoEngine.resolutionMap = resolutionMap;
   
   // 4. 开启 ABR，指定清晰度档位为 TTVideoEngineResolutionTypeABRAuto。
   [self.videoEngine configResolution:TTVideoEngineResolutionTypeABRAuto];
   
   // 5. 设置播放 URL 并开始播放
   

3. ABR 回调和参数配置：与 Vid 模式相同，通过监听 ABR 事件回调和配置 ABR 播放实例参数（可选）章节的指引来监听和调整 ABR 行为。