本文介绍拉流 SDK 进阶功能的接入方式，支持的进阶功能包括但不限于 RTM 协议拉流、QUIC 协议拉流、使用 IP 地址拉流、使用主备流、多档位手动切换、自适应码率（ABR）拉流、截图、画中画、SEI，以及订阅视频和音频数据。您可以根据实际业务需求，借助拉流 SDK 实现更复杂的功能。

前提条件 #

• 已完成基础功能接入。详见基础功能。
• 如需使用以下功能，确保使用高级版或试用版 License。
  • RTM 协议拉流
  • QUIC 协议拉流
  • FLV 低延时
  • 主备流切换
  • 自适应码率（ABR）拉流
  • SEI
  • 拉流超分
  • H.265 软解和硬解
  • 视频锐化
  • DRM 加密流播放

  注意

  试用版 License 仅用于项目测试，不支持续签。过期的试用版 License 会导致鉴权失败，进而中断服务。请在项目上线前升级为正式版 License。详见升级试用版 License 为基础版或高级版 License。

注意事项 #

真机调试：由于 SDK 使用了大量 iOS 系统的音视频接口，这些接口在模拟器下可能会出现异常，推荐您使用真机进行代码调试。

流降级策略与主备流切换 #

如果您只配置一个拉流地址，一旦因网络等问题导致使用该地址拉流失败，直播可能会卡顿，甚至无法播放。为降低单个地址异常带来的播放失败风险，您可以为一次播放配置多个拉流地址，并按需选择以下配置方式：

• 流降级策略：适用于希望播放器按优先级自动尝试多个拉流地址的场景。您可以为每个地址配置优先级和最大重试次数。播放器会优先尝试高优先级地址。如果该地址在重试次数用尽后仍不可用，播放器会切换到下一个优先级的地址。
• 主备流切换：适用于业务上已有明确主流列表和备流列表的场景。播放器会先在主流列表内按流降级策略尝试播放。只有当主流列表中的所有地址都播放失败后，才会自动切换到备流列表继续尝试。

• 流降级策略
  主流或备流列表中的播放顺序如下所示：
  1. 播放最高优先级的流：播放器会根据您设置的 priority，从高到低尝试播放当前列表中的流。
  2. 失败重试：如果当前流播放失败，播放器会根据该流的 retryMaxCount 进行重试。
  3. 切换到降级流：如果所有重试次数用尽后依然失败，播放器会放弃该流，并切换到当前列表中下一个优先级的流进行尝试。
• 主备流切换
  开启主备流后，播放器会按照以下顺序尝试播放流：
  1. 播放主流：播放器会首先尝试播放主流列表中的流。
  2. 切换到备流：如果主流列表中的所有流都播放失败，播放器会尝试播放备流列表中的流。
  3. 播放失败：如果备流列表中的所有流都播放失败，播放将彻底失败。

在此过程中，SDK 会通过以下回调通知您当前的状态：

• onInfo:info:：当一个流播放失败，且存在下一个可用流时触发。您可以通过该回调获取详细的错误信息，以便进行调试。
• onStreamFormatSwitch:fromStreamFormat:toStreamFormat:error:extraInfo:：当播放器切换流的格式时触发（例如，从 RTM 切换到 FLV）。
• onMainBackupSwitch:streamType:error:：当主流列表全部播放失败，播放器成功切换到备流列表时触发。
• onError:error:：当所有主流和备流都播放失败，播放最终结束时触发。

前提条件 #

通过以下任一方式，获取 RTM、FLV 等协议的拉流地址，用于配置主流列表或备流列表。同一列表内的降级顺序由各拉流地址的优先级决定。

• 功能调试阶段：使用地址生成器生成拉流地址。
• 功能正式上线：调用 GeneratePlayURL 或使用服务端 SDK 动态生成拉流地址。

接入说明 #

步骤一：配置降级策略

您可以通过配置 VeLivePlayerStream 的 priority 和 retryMaxCount，来自定义降级策略。

• priority：流的优先级。取值必须为 0（默认值）或正整数。取值越大，优先级越高。播放器会优先尝试播放高优先级的流。

  说明

  主流列表和备流列表的优先级是独立计算的，互不影响。

• retryMaxCount：流的最大重试次数，即总播放尝试次数（包含首次尝试）。例如，若取值为 3，则在首次播放失败后，播放器最多会再重试 2 次。取值如下：
  • -1（默认值）：使用 VeLivePlayerConfiguration 中 retryMaxCount 的取值。
  • 0：不会尝试播放当前流。
  • >0：具体次数。

// 创建 VeLivePlayerStreamData 实例。
VeLivePlayerStreamData *streamData = [[VeLivePlayerStreamData alloc] init];
NSMutableArray *mainStreams = [NSMutableArray new];

// 添加 RTM 主流 (最高优先级)。
VeLivePlayerStream *rtmStream = [[VeLivePlayerStream alloc] init];
rtmStream.url = @"https://xxx.sdp"; // 替换为实际 RTM 拉流地址。
rtmStream.format = VeLivePlayerFormatRTM;
rtmStream.type = VeLivePlayerStreamTypeMain;
rtmStream.protocol = VeLivePlayerProtocolTLS;
rtmStream.retryMaxCount = 3;
rtmStream.priority = 5; 
[mainStreams addObject:rtmStream];

// 添加 FLV 主流作为降级流。
VeLivePlayerStream *flvStream = [[VeLivePlayerStream alloc] init];
flvStream.url = @"https://xxx.flv"; // 替换为实际 FLV 拉流地址。
flvStream.format = VeLivePlayerFormatFLV;
flvStream.type = VeLivePlayerStreamTypeMain;
flvStream.protocol = VeLivePlayerProtocolTLS;
flvStream.retryMaxCount = 2; 
flvStream.priority = 4; 
[mainStreams addObject:flvStream];

streamData.mainStream = mainStreams;

// 配置播放源。
[self.livePlayer setPlayStreamData:streamData];

// 开始播放。
[self.livePlayer play];

// 创建 VeLivePlayerStreamData 实例。
VeLivePlayerStreamData *streamData = [[VeLivePlayerStreamData alloc] init];
// 配置主流列表。
NSMutableArray *mainStreams = [NSMutableArray new];

// 添加 RTM 主流 (最高优先级)。
VeLivePlayerStream *rtmStream = [[VeLivePlayerStream alloc] init];
rtmStream.url = @"https://xxx.sdp"; // 替换为实际 RTM 拉流地址。
rtmStream.format = VeLivePlayerFormatRTM;
rtmStream.type = VeLivePlayerStreamTypeMain;
rtmStream.protocol = VeLivePlayerProtocolTLS;
rtmStream.retryMaxCount = 3;
rtmStream.priority = 5; 
[mainStreams addObject:rtmStream];

// 添加 FLV 主流作为降级流。
VeLivePlayerStream *flvStream = [[VeLivePlayerStream alloc] init];
flvStream.url = @"https://xxx.flv"; // 替换为实际 FLV 拉流地址。
flvStream.format = VeLivePlayerFormatFLV;
flvStream.type = VeLivePlayerStreamTypeMain;
flvStream.protocol = VeLivePlayerProtocolTLS;
flvStream.retryMaxCount = 2; 
flvStream.priority = 4; 
[mainStreams addObject:flvStream];

streamData.mainStream = mainStreams;

// 配置备流列表。
NSMutableArray *backupStreams = [NSMutableArray new];
// 添加 RTM 备流。
VeLivePlayerStream *rtmBackupStream = [[VeLivePlayerStream alloc] init];
rtmBackupStream.url = @"https://xxx.sdp"; // 替换为实际 RTM 拉流地址。
rtmBackupStream.format = VeLivePlayerFormatRTM;
rtmBackupStream.type = VeLivePlayerStreamTypeBackup;
rtmBackupStream.protocol = VeLivePlayerProtocolTLS;
rtmBackupStream.retryMaxCount = 3; 
rtmBackupStream.priority = 5; // 备流列表中的最高优先级。
[backupStreams addObject:rtmBackupStream];

// 添加 FLV 备流作为降级流。
VeLivePlayerStream *flvBackupStream = [[VeLivePlayerStream alloc] init];
flvBackupStream.url = @"https://xxx.flv"; // 替换为实际 FLV 拉流地址。
flvBackupStream.format = VeLivePlayerFormatFLV;
flvBackupStream.type = VeLivePlayerStreamTypeBackup;
flvBackupStream.protocol = VeLivePlayerProtocolTLS;
flvBackupStream.retryMaxCount = 3; 
flvBackupStream.priority = 4; 
[backupStreams addObject:flvBackupStream];
streamData.backupStream = backupStreams;

// 开启主备流切换。
streamData.enableMainBackupSwitch = YES;

// 配置播放源。
[self.livePlayer setPlayStreamData:streamData];

// 开始播放。
[self.livePlayer play];

// 创建 VeLivePlayerStreamData 实例。
VeLivePlayerStreamData *streamData = [[VeLivePlayerStreamData alloc] init];
NSMutableArray *mainStreams = [NSMutableArray new];

// 添加 ABR 多档位流的原始档位，priority 为 5。
VeLivePlayerStream *flvOriginStream = [[VeLivePlayerStream alloc] init];
flvOriginStream.url = @"https://xxx_origin.flv"; // 替换为实际 FLV 原始档位拉流地址。
flvOriginStream.format = VeLivePlayerFormatFLV;
flvOriginStream.type = VeLivePlayerStreamTypeMain;
flvOriginStream.protocol = VeLivePlayerProtocolTLS;
flvOriginStream.resolution = VeLivePlayerResolutionOrigin; // 清晰度档位标识。
flvOriginStream.bitrate = 2000;
flvOriginStream.retryMaxCount = 3;
flvOriginStream.priority = 5;
[mainStreams addObject:flvOriginStream];

// 添加 ABR 多档位流的超清档位，priority 为 5。
VeLivePlayerStream *flvUHDStream = [[VeLivePlayerStream alloc] init];
flvUHDStream.url = @"https://xxx_uhd.flv"; // 替换为实际 FLV 超清档位拉流地址。
flvUHDStream.format = VeLivePlayerFormatFLV;
flvUHDStream.type = VeLivePlayerStreamTypeMain;
flvUHDStream.protocol = VeLivePlayerProtocolTLS;
flvUHDStream.resolution = VeLivePlayerResolutionUHD; // 清晰度档位标识。
flvUHDStream.bitrate = 1800;
flvUHDStream.retryMaxCount = 3;
flvUHDStream.priority = 5;
[mainStreams addObject:flvUHDStream];

// 添加 ABR 多档位流的高清档位，priority 为 5。
VeLivePlayerStream *flvHDStream = [[VeLivePlayerStream alloc] init];
flvHDStream.url = @"https://xxx_hd.flv"; // 替换为实际 FLV 高清档位拉流地址。
flvHDStream.format = VeLivePlayerFormatFLV;
flvHDStream.type = VeLivePlayerStreamTypeMain;
flvHDStream.protocol = VeLivePlayerProtocolTLS;
flvHDStream.resolution = VeLivePlayerResolutionHD; // 清晰度档位标识。
flvHDStream.bitrate = 1500;
flvHDStream.retryMaxCount = 3;
flvHDStream.priority = 5;
[mainStreams addObject:flvHDStream];

// 添加普通 FLV 流作为降级流，priority 为 4。
VeLivePlayerStream *flvStream = [[VeLivePlayerStream alloc] init];
flvStream.url = @"https://xxx.flv"; // 替换为实际 FLV 拉流地址。
flvStream.format = VeLivePlayerFormatFLV;
flvStream.type = VeLivePlayerStreamTypeMain;
flvStream.protocol = VeLivePlayerProtocolTLS;
flvStream.retryMaxCount = 2;
flvStream.priority = 4;
[mainStreams addObject:flvStream];

streamData.mainStream = mainStreams;
    
// 配置默认启播档位。
streamData.defaultResolution = VeLivePlayerResolutionOrigin;

// 开启 ABR。
streamData.enableABR = YES;

// 配置播放源。
[self.livePlayer setPlayStreamData:streamData];

// 开始播放。
[self.livePlayer play];

步骤二：添加回调

按需添加以下回调，监听降级过程中的事件。

• 监听流格式切换，例如从 RTM 切换到 FLV。

  - (void)onStreamFormatSwitch:(TVLManager *_Nonnull)player fromStreamFormat:(VeLivePlayerFormat)fromStreamType toStreamFormat:(VeLivePlayerFormat)toStreamType error:(VeLivePlayerError *)error extraInfo:(NSDictionary *)extraInfo;
  

• 监听播放过程中遇到的可恢复问题。当一个流播放失败，但 SDK 即将执行恢复操作，例如切换到降级流时，会触发该回调。这表明播放仍在继续，您无需中断播放流程。您可以通过返回的错误信息了解流播放失败的具体原因，以便进行调试。

  - (void)onInfo:(TVLManager *_Nonnull)player info:(VeLivePlayerError *_Nonnull)info;
  

• 监听从主流切换到备流。

  - (void)onMainBackupSwitch:(TVLManager *_Nonnull)player streamType:(VeLivePlayerStreamType)streamType error:(VeLivePlayerError *)error;
  

• 监听播放最终结束，即所有流均播放失败。

  - (void)onError:(TVLManager *_Nonnull)player error:(VeLivePlayerError *_Nonnull)error;
  

RTM 协议拉流 #

RTM 协议拉流可将直播延迟降低至 1-2 秒，为观众提供优质的直播体验。

然而，RTM 的超低延迟特性也对网络环境提出了更高要求。在网络不稳定的情况下，可能会出现播放延迟、卡顿或失败。如果您希望在 RTM 拉流地址不可用时自动尝试 FLV 等其他协议的拉流地址，可以结合流降级策略或主备流切换使用。详见流降级策略与主备流切换。

前提条件 #

• 确保您已集成 1.50.1 及以上版本的拉流 SDK，并添加 LivePull-RTS 依赖。详见集成 iOS 拉流 SDK。
• 通过以下任一方式，获取 RTM、FLV 等协议的拉流地址。
  • 功能调试阶段：使用地址生成器生成拉流地址。
  • 功能正式上线：调用 GeneratePlayURL 或使用服务端 SDK 动态生成拉流地址。

接入说明 #

本文提供以下两个代码示例，分别对应了从简单到复杂的应用场景：

• 基础场景：演示在主流列表内，当高优先级的 RTM 流播放失败后，如何自动降级到 FLV 等其他协议的流。
• 进阶场景：在基础场景上，增加主备流切换机制。当主流列表中的所有流（包括 RTM 流和降级流）都不可用时，播放器会自动切换到备流列表进行重试。

建议您从基础场景开始了解。

// 创建 VeLivePlayerStreamData 实例。
VeLivePlayerStreamData *streamData = [[VeLivePlayerStreamData alloc] init];
NSMutableArray *mainStreams = [NSMutableArray new];

// 添加 RTM 主流 (最高优先级)。
VeLivePlayerStream *rtmStream = [[VeLivePlayerStream alloc] init];
rtmStream.url = @"https://xxx.sdp"; // 替换为实际 RTM 拉流地址。
rtmStream.format = VeLivePlayerFormatRTM;
rtmStream.type = VeLivePlayerStreamTypeMain;
rtmStream.protocol = VeLivePlayerProtocolTLS;
rtmStream.retryMaxCount = 3;
rtmStream.priority = 5; 
[mainStreams addObject:rtmStream];

// 添加 FLV 主流作为降级流。
VeLivePlayerStream *flvStream = [[VeLivePlayerStream alloc] init];
flvStream.url = @"https://xxx.flv"; // 替换为实际 FLV 拉流地址。
flvStream.format = VeLivePlayerFormatFLV;
flvStream.type = VeLivePlayerStreamTypeMain;
flvStream.protocol = VeLivePlayerProtocolTLS;
flvStream.retryMaxCount = 2; 
flvStream.priority = 4; 
[mainStreams addObject:flvStream];

streamData.mainStream = mainStreams;

// 配置播放源。
[self.livePlayer setPlayStreamData:streamData];

// 开始播放。
[self.livePlayer play];

// 创建 VeLivePlayerStreamData 实例。
VeLivePlayerStreamData *streamData = [[VeLivePlayerStreamData alloc] init];
// 配置主流列表。
NSMutableArray *mainStreams = [NSMutableArray new];

// 添加 RTM 主流 (最高优先级)。
VeLivePlayerStream *rtmStream = [[VeLivePlayerStream alloc] init];
rtmStream.url = @"https://xxx.sdp"; // 替换为实际 RTM 拉流地址。
rtmStream.format = VeLivePlayerFormatRTM;
rtmStream.type = VeLivePlayerStreamTypeMain;
rtmStream.protocol = VeLivePlayerProtocolTLS;
rtmStream.retryMaxCount = 3;
rtmStream.priority = 5; 
[mainStreams addObject:rtmStream];

// 添加 FLV 主流作为降级流。
VeLivePlayerStream *flvStream = [[VeLivePlayerStream alloc] init];
flvStream.url = @"https://xxx.flv"; // 替换为实际 FLV 拉流地址。
flvStream.format = VeLivePlayerFormatFLV;
flvStream.type = VeLivePlayerStreamTypeMain;
flvStream.protocol = VeLivePlayerProtocolTLS;
flvStream.retryMaxCount = 2; 
flvStream.priority = 4; 
[mainStreams addObject:flvStream];

streamData.mainStream = mainStreams;

// 配置备流列表。
NSMutableArray *backupStreams = [NSMutableArray new];
// 添加 RTM 备流。
VeLivePlayerStream *rtmBackupStream = [[VeLivePlayerStream alloc] init];
rtmBackupStream.url = @"https://xxx.sdp"; // 替换为实际 RTM 拉流地址。
rtmBackupStream.format = VeLivePlayerFormatRTM;
rtmBackupStream.type = VeLivePlayerStreamTypeBackup;
rtmBackupStream.protocol = VeLivePlayerProtocolTLS;
rtmBackupStream.retryMaxCount = 3; 
rtmBackupStream.priority = 5; // 备流列表中的最高优先级。
[backupStreams addObject:rtmBackupStream];

// 添加 FLV 备流作为降级流。
VeLivePlayerStream *flvBackupStream = [[VeLivePlayerStream alloc] init];
flvBackupStream.url = @"https://xxx.flv"; // 替换为实际 FLV 拉流地址。
flvBackupStream.format = VeLivePlayerFormatFLV;
flvBackupStream.type = VeLivePlayerStreamTypeBackup;
flvBackupStream.protocol = VeLivePlayerProtocolTLS;
flvBackupStream.retryMaxCount = 3; 
flvBackupStream.priority = 4; 
[backupStreams addObject:flvBackupStream];
streamData.backupStream = backupStreams;

// 开启主备流切换。
streamData.enableMainBackupSwitch = YES;

// 配置播放源。
[self.livePlayer setPlayStreamData:streamData];

// 开始播放。
[self.livePlayer play];

FLV 低延时 #

开启 FLV 低延时后，FLV 协议拉流可将直播延迟降至 2-3 秒。

接入说明 #

在开始播放前，您可通过播放器的 setProperty:value: 高级接口开启 FLV 低延时。调用 setProperty:value: 接口时，需传入一组 Key-Value 配置。

Key

Value

Value 为 NSDictionary 类型，表示需要传入一个 Key-Value 形式的字典对象，用于配置 FLV 低延时功能。

• Key：NSString 类型。固定取值为 EnableLowLatencyFLV，表示是否开启 FLV 低延时。
• Value：NSNumber 类型。取值为 1 表示开启 FLV 低延时，取值为 0 表示关闭 FLV 低延时。默认值为 0。

示例代码如下所示。

[self.livePlayer setProperty:VeLivePlayerKeySetParamsLowLatencyFlv value:@{@"EnableLowLatencyFLV": @1}];

QUIC 协议拉流 #

视频直播拉流 SDK 支持 QUIC 协议拉流，该功能需要配合火山引擎视频直播服务使用。

前提条件 #

使用视频直播控制台的地址生成器，生成 FLV 拉流地址。

接入说明 #

配置 QUIC 拉流地址进行播放。代码示例如下所示。

VeLivePlayerStream *playStreamFLV = [[VeLivePlayerStream alloc]init];
playStreamFLV.url = @"https://pull.example.com/live/stream.flv"; // 替换为实际 FLV 拉流地址。
playStreamFLV.format = VeLivePlayerFormatFLV;
playStreamFLV.protocol = VeLivePlayerProtocolQUIC;

// 创建 VeLivePlayerStreamData
VeLivePlayerStreamData *streamData = [[VeLivePlayerStreamData alloc]init];
NSMutableArray <VeLivePlayerStream *> *mainStreams = [NSMutableArray arrayWithCapacity:1];

// 添加 FLV 流地址
[mainStreams addObject:playStreamFLV];

streamData.mainStream = mainStreams;

// 配置播放源
[self.livePlayer setPlayStreamData:streamData];

// 开始播放
[self.livePlayer play];

DRM 加密流播放 #

如需播放 DRM 加密流，请完成以下操作：

1. 参考最佳实践-直播 DRM 加密获取以下信息：
   • 获取 M3U8 格式的 DRM 加密流播放地址。
   • 调用 DescribeLicenseDRM 获取 DRM 授权许可 URL。该 URL 包含鉴权信息和过期时间。
   • 调用 DescribeCertDRM 获取 FairPlay 证书文件。
2. 在 iOS 项目中，调用 initWithType: 方法初始化播放器。

   self.livePlayer = [[TVLManager alloc] initWithType:VeLivePlayerTypeSystem];
   

   说明

   使用 initWithType: 方法初始化系统播放器后，将不支持以下功能接入。

   • 使用除 M3U8 格式外的其他播放地址
   • 主备流切换
   • 自适应码率拉流
   • 视频截图
   • 视频镜像
   • 自定义音视频渲染
   • 拉流超分
   • SEI
3. 配置加密流播放地址。

   NSString *playUrl = @"http://pull.example.com/live/stream.m3u8"; // 替换为实际的加密流播放地址。
   [self.livePlayer setPlayUrl:playUrl];
   

4. 实现播放器 observer 的 getDrmResourceLoaderCertificateData: 和 getDrmResourceLoaderLicenseUrl: 回调，向 SDK 提供 FairPlay 证书数据和 DRM 授权许可 URL。

   - (NSData *)getDrmResourceLoaderCertificateData:(TVLManager *)player { 
       NSString *filePath = [[NSBundle mainBundle] pathForResource:@"testfairplay" ofType:@"cer"]; // 将 testfairplay 替换为实际 FairPlay 证书文件名。
       NSData *certificate = [NSData dataWithContentsOfFile:filePath]; 
       return certificate; 
   } 
    
   - (NSString *)getDrmResourceLoaderLicenseUrl:(TVLManager *)player { 
       return @"https://drmtest/license"; // 替换为实际 DRM 授权许可 URL。
   }
   

5. 播放 DRM 加密流。

   [self.livePlayer play];
   

使用 IP 地址拉流 #

播放器支持通过设置播放域名的 IP 地址进行拉流，以降低播放首帧时间。

前提条件 #

请先获取直播播放地址并解析出 IP 地址。

接入说明 #

使用播放器的 setUrlHostIP: 接口将 IP 地址与域名关联起来，播放器将直接根据 IP 地址进行拉流播放。代码示例如下所示。

[self.livePlayer setPlayUrl:@"https://pull.example.com/live/stream.flv"]; // 替换为实际直播播放地址。

// 配置直播播放地址中的域名与其解析出的 IP 地址的映射关系。
NSMutableArray<NSString *> *ipList = [[NSMutableArray alloc] initWithCapacity:1];
[ipList addObject:@"xxx.xxx.xxx.xxx"]; // 替换为该域名解析出的实际 IP 地址。

NSMutableDictionary* ipHost = [[NSMutableDictionary alloc] initWithCapacity:1];
[ipHost setObject:ipList forKey:@"pull.example.com"]; // 将 pull.example.com 替换为实际直播播放地址中的域名。

// 设置域名与 IP 地址的映射关系。
[self.livePlayer setUrlHostIP:ipHost];

// 开始播放。
[self.livePlayer play];  
    

多档位手动切换 #

播放器支持配置多档位的直播拉流地址，通过接口可以实现多档位直播流的切换。

前提条件 #

获取源流和各档位转码流拉流地址。如您使用了火山引擎视频直播服务，请先登录控制台完成转码配置，再获取拉流地址，获取方法如下所示。

• 功能调试阶段：使用地址生成器生成拉流地址。
• 功能正式上线：调用 GeneratePlayURL 或使用服务端 SDK 动态生成拉流地址。

本文的接入说明以下列拉流地址为例。

接入说明 #

1. 配置多档位地址进行播放。代码示例如下所示。

   // 配置多档位流地址
   VeLivePlayerStream *playStreamOrigin = [[VeLivePlayerStream alloc]init];
   playStreamOrigin.url = @"https://pull.example.com/live/123456.flv"; // 替换为实际原始档位拉流地址。
   playStreamOrigin.resolution = VeLivePlayerResolutionOrigin; // 原始档位
       
   VeLivePlayerStream *playStreamUHD = [[VeLivePlayerStream alloc]init];
   playStreamUHD.url = @"https://pull.example.com/live/123456_uhd.flv"; // 替换为实际超清档位拉流地址。
   playStreamUHD.resolution = VeLivePlayerResolutionUHD; // 超清档位
       
   VeLivePlayerStream *playStreamHD = [[VeLivePlayerStream alloc]init];
   playStreamHD.url = @"https://pull.example.com/live/123456_hd.flv"; // 替换为实际高清档位拉流地址。
   playStreamHD.resolution = VeLivePlayerResolutionHD; // 高清档位
       
   VeLivePlayerStream *playStreamSD = [[VeLivePlayerStream alloc]init];
   playStreamSD.url = @"https://pull.example.com/live/123456_sd.flv"; // 替换为实际标清档位拉流地址。
   playStreamSD.resolution = VeLivePlayerResolutionSD; // 标清档位
       
   VeLivePlayerStream *playStreamLD = [[VeLivePlayerStream alloc]init];
   playStreamLD.url = @"https://pull.example.com/live/123456_ld.flv"; // 替换为实际流畅档位拉流地址。
   playStreamLD.resolution = VeLivePlayerResolutionLD; // 流畅档位
       
   // 创建播放源
   VeLivePlayerStreamData *streamData = [[VeLivePlayerStreamData alloc]init];
       
   // 添加多档位流
   NSMutableArray <VeLivePlayerStream *> *mainStreams = [NSMutableArray arrayWithCapacity:1];
   [mainStreams addObject:playStreamOrigin];
   [mainStreams addObject:playStreamUHD];
   [mainStreams addObject:playStreamHD];
   [mainStreams addObject:playStreamSD];
   [mainStreams addObject:playStreamLD];
   streamData.mainStream = mainStreams;
       
   // 配置默认启播档位
   streamData.defaultResolution = VeLivePlayerResolutionOrigin;
       
   // 配置播放源
   [self.livePlayer setPlayStreamData:streamData];
       
   // 开始播放
   [self.livePlayer play];
   
   

2. 通过调用播放器的 switchResolution: 接口可以实现多个档位之间的手动切换。代码示例如下所示。

   [self.livePlayer switchResolution:VeLivePlayerResolutionUHD]; // 切换到超清档位
   
   

3. 当档位切换成功时，会触发 VeLivePlayerObserver 的 onResolutionSwitch:resolution:error:reason: 回调。代码示例如下所示。

   - (void)onResolutionSwitch:(TVLManager *)player resolution:(VeLivePlayerResolution)resolution error:(VeLivePlayerError *)error reason:(VeLivePlayerResolutionSwitchReason)reason  {
      // 档位切换回调
   }
   
   

自适应码率（ABR）拉流 #

自适应码率（ABR，adaptive bitrate）拉流可在网络变化时自动切换到更合适的清晰度档位，降低卡顿风险。

iOS 拉流 SDK 支持以下 ABR 拉流模式：

• RTM-ABR 流：面向 RTM 播放的服务端 ABR 能力。播放器只需使用一个 RTM-ABR 拉流地址，服务端会根据观众的网络状况自动选择并切换清晰度档位，在弱网环境下减少卡顿，同时保留 RTM 的低延迟播放体验。
• FLV 流：客户端 ABR 能力。您需要提供多个 FLV 拉流地址及对应的码率信息，SDK 会根据网络状况在这些地址之间自动切换。

RTM-ABR 流 #

前提条件

• 添加 ABR 配置时，配置多个 ABR 子流，并在协议类型中选择 RTM-ABR。详见 ABR 配置。
• 通过以下任一方式获取 RTM-ABR 拉流地址：
  • 功能调试阶段：使用地址生成器，选择起播清晰度档位（后缀）后，在 ABR多码率地址页签获取 RTM 地址。详见地址生成器。
  • 功能正式上线：调用 GeneratePlayURL 或使用服务端 SDK，将 StreamType 设置为 abr，动态生成 RTM-ABR 拉流地址。不同后缀对应不同的起播清晰度档位，请从返回结果中选择一个 Protocol 取值为 rtm-abr、Tag 取值为 RTM-ABR-NativeSDK 的地址起播。

  注意

  不要在普通 RTM 拉流地址后手动追加 rtmabr=true。只有完成 RTM-ABR 配置并使用生成的 RTM-ABR 地址时，RTM-ABR 才会生效。

接入说明

设置 RTM-ABR 拉流地址并开始播放。

[self.livePlayer setPlayUrl:@"https://pull.example.com/live/test_uhd.sdp?rtmabr=true"]; // 替换为实际 RTM-ABR 拉流地址。

// 开始播放。
[self.livePlayer play];

FLV 流 #

前提条件

获取源流和各档位转码流拉流地址。如您使用了火山引擎视频直播服务，请先登录控制台完成转码配置，再获取拉流地址，获取方法如下所示。

• 功能调试阶段：使用地址生成器生成拉流地址。
• 功能正式上线：调用 GeneratePlayURL 或使用服务端 SDK 动态生成拉流地址。

本文的接入说明以下列拉流地址为例。

接入说明

1. 配置多档位地址进行播放。代码示例如下所示。

   // 配置多档位流地址
   VeLivePlayerStream *playStreamOrigin = [[VeLivePlayerStream alloc]init];
   playStreamOrigin.url = @"https://pull.example.com/live/123456.flv"; // 替换为实际原始档位拉流地址。
   playStreamOrigin.resolution = VeLivePlayerResolutionOrigin; // 原始档位
   playStreamOrigin.bitrate = 2500;
       
   VeLivePlayerStream *playStreamUHD = [[VeLivePlayerStream alloc]init];
   playStreamUHD.url = @"https://pull.example.com/live/123456_uhd.flv"; // 替换为实际超清档位拉流地址。
   playStreamUHD.resolution = VeLivePlayerResolutionUHD; // 超清档位
   playStreamUHD.bitrate = 2500;
       
   VeLivePlayerStream *playStreamHD = [[VeLivePlayerStream alloc]init];
   playStreamHD.url = @"https://pull.example.com/live/123456_hd.flv"; // 替换为实际高清档位拉流地址。
   playStreamHD.resolution = VeLivePlayerResolutionHD; // 高清档位
   playStreamHD.bitrate = 1000;
       
   VeLivePlayerStream *playStreamSD = [[VeLivePlayerStream alloc]init];
   playStreamSD.url = @"https://pull.example.com/live/123456_sd.flv"; // 替换为实际标清档位拉流地址。
   playStreamSD.resolution = VeLivePlayerResolutionSD; // 标清档位
   playStreamSD.bitrate = 800;
       
   VeLivePlayerStream *playStreamLD = [[VeLivePlayerStream alloc]init];
   playStreamLD.url = @"https://pull.example.com/live/123456_ld.flv"; // 替换为实际流畅档位拉流地址。
   playStreamLD.resolution = VeLivePlayerResolutionLD; // 流畅档位
   playStreamLD.bitrate = 500;
       
   // 创建播放源
   VeLivePlayerStreamData *streamData = [[VeLivePlayerStreamData alloc]init];
       
   // 添加多档位流
   NSMutableArray <VeLivePlayerStream *> *mainStreams = [NSMutableArray arrayWithCapacity:1];
   [mainStreams addObject:playStreamOrigin];
   [mainStreams addObject:playStreamUHD];
   [mainStreams addObject:playStreamHD];
   [mainStreams addObject:playStreamSD];
   [mainStreams addObject:playStreamLD];
   streamData.mainStream = mainStreams;
       
   // 配置默认启播档位
   streamData.defaultResolution = VeLivePlayerResolutionOrigin;
   
   // 开启 ABR
   streamData.enableABR = YES;
       
   // 配置播放源
   [self.livePlayer setPlayStreamData:streamData];
       
   // 开始播放
   [self.livePlayer play];
   
   

2. ABR 档位自动切换时，会触发 VeLivePlayerObserver 的 onResolutionSwitch:resolution:error:reason: 回调。代码示例如下所示。

   - (void)onResolutionSwitch:(TVLManager *)player resolution:(VeLivePlayerResolution)resolution error:(VeLivePlayerError *)error reason:(VeLivePlayerResolutionSwitchReason)reason  {
      // 档位切换回调
   }
   
   

平滑切档 #

平滑切档功能可确保在观众手动切换直播清晰度（如超清、高清、标清）时，音画能够无缝衔接，从而避免出现黑屏或卡顿，提升观看体验。

要使用此功能，您需要为播放器配置一个包含多档位清晰度的同源流列表，并开启平滑切档开关。配置后，当观众手动切换清晰度档位时，播放器会在不同码率的流之间平滑过渡，保障直播音画的连续性和稳定性。

前提条件 #

准备同一源流不同清晰度档位的拉流地址。

如使用视频直播的推流地址进行推流，请确保已完成：

• 添加域名：在同一域名空间下，添加推流域名和拉流域名。详见添加域名。
• 配置转码：在该域名空间下，为不同清晰度档位添加转码配置。详见转码配置。
• 获取拉流地址：获取源流和各档位转码流的拉流地址。
  • 功能调试阶段：使用地址生成器生成拉流地址。
    • 地址类型: 选择拉流地址。
    • 选择域名: 选择添加转码配置时使用的域名空间下的拉流域名。
    • AppName 和 StreamName：填写与推流地址一致的 AppName 和 StreamName。例如推流地址为 rtmp://push.example.com/live/test?authinfo，则 AppName 为 live，StreamName 为 test。
  • 功能正式上线：调用 GeneratePlayURL 或使用服务端 SDK 动态生成拉流地址。
    示例
    下表列出了不同档位的 FLV 拉流地址及对应码率的示例值。
    

  档位	FLV 拉流地址	码率（kbps）
  原始（Origin）	https://pull.example.com/live/123456.flv	2500
  超清（UHD）	https://pull.example.com/live/123456_uhd.flv	2500
  高清（HD）	https://pull.example.com/live/123456_hd.flv	1000
  标清（SD）	https://pull.example.com/live/123456_sd.flv	800
  流畅（LD）	https://pull.example.com/live/123456_ld.flv	500

接入说明 #

1. 配置各清晰度档位的流并将 enableSmoothSwitchResolution 属性设置为 YES，开启平滑切档。

   // 配置各清晰度档位的流。
   // 原始档位。
   VeLivePlayerStream *playStreamOrigin = [[VeLivePlayerStream alloc]init];
   playStreamOrigin.url = @"https://pull.example.com/live/123456.flv"; // 替换为实际原始档位拉流地址。
   playStreamOrigin.format = VeLivePlayerFormatFLV; // 流格式。
   playStreamOrigin.resolution = VeLivePlayerResolutionOrigin; // 清晰度档位标识。
   playStreamOrigin.type = VeLivePlayerStreamTypeMain; // 主备流类型，用于区分主流和备流。
   playStreamOrigin.bitrate = 2500; // 码率。单位：kbps。
   
   // 超清档位。    
   VeLivePlayerStream *playStreamUHD = [[VeLivePlayerStream alloc]init];
   playStreamUHD.url = @"https://pull.example.com/live/123456_uhd.flv"; // 替换为实际超清档位拉流地址。
   playStreamUHD.format = VeLivePlayerFormatFLV; // 流格式。
   playStreamUHD.resolution = VeLivePlayerResolutionUHD; // 清晰度档位标识。
   playStreamUHD.type = VeLivePlayerStreamTypeMain; // 主备流类型，用于区分主流和备流。
   playStreamUHD.bitrate = 2500; // 码率。单位：kbps。
    
   // 高清档位。    
   VeLivePlayerStream *playStreamHD = [[VeLivePlayerStream alloc]init];
   playStreamHD.url = @"https://pull.example.com/live/123456_hd.flv"; // 替换为实际高清档位拉流地址。
   playStreamHD.format = VeLivePlayerFormatFLV; // 流格式。
   playStreamHD.resolution = VeLivePlayerResolutionHD; // 清晰度档位标识。
   playStreamHD.type = VeLivePlayerStreamTypeMain; // 主备流类型，用于区分主流和备流。
   playStreamHD.bitrate = 1000; // 码率。单位：kbps。
       
   // 标清档位。    
   VeLivePlayerStream *playStreamSD = [[VeLivePlayerStream alloc]init];
   playStreamSD.url = @"https://pull.example.com/live/123456_sd.flv"; // 替换为实际标清档位拉流地址。
   playStreamSD.format = VeLivePlayerFormatFLV; // 流格式。
   playStreamSD.resolution = VeLivePlayerResolutionSD; // 清晰度档位标识。
   playStreamSD.type = VeLivePlayerStreamTypeMain; // 主备流类型，用于区分主流和备流。
   playStreamSD.bitrate = 800; // 码率。单位：kbps。
   
   // 流畅档位。    
   VeLivePlayerStream *playStreamLD = [[VeLivePlayerStream alloc]init];
   playStreamLD.url = @"https://pull.example.com/live/123456_ld.flv"; // 替换为实际流畅档位拉流地址。
   playStreamLD.format = VeLivePlayerFormatFLV; // 流格式。
   playStreamLD.resolution = VeLivePlayerResolutionLD; // 清晰度档位标识。
   playStreamLD.type = VeLivePlayerStreamTypeMain; // 主备流类型，用于区分主流和备流。
   playStreamLD.bitrate = 500; // 码率。单位：kbps。
       
   // 创建播放源。
   VeLivePlayerStreamData *streamData = [[VeLivePlayerStreamData alloc]init];
       
   // 添加各清晰度档位的流。
   NSMutableArray <VeLivePlayerStream *> *mainStreams = [NSMutableArray arrayWithCapacity:5];
   [mainStreams addObject:playStreamOrigin];
   [mainStreams addObject:playStreamUHD];
   [mainStreams addObject:playStreamHD];
   [mainStreams addObject:playStreamSD];
   [mainStreams addObject:playStreamLD];
   streamData.mainStream = mainStreams;
       
   // 配置默认启播档位。
   streamData.defaultResolution = VeLivePlayerResolutionSD;
   
   // 开启平滑切档功能。
   streamData.enableSmoothSwitchResolution = YES;
       
   // 配置播放源。
   [self.livePlayer setPlayStreamData:streamData];
       
   // 开始播放。
   [self.livePlayer play];
   

2. 在直播期间，当观众手动切换清晰度档位时，您可以调用 switchResolution: 方法切换清晰度档位，并实现平滑切档。示例代码如下所示。

   // 切换到超清档位。
   [self.livePlayer switchResolution:VeLivePlayerResolutionUHD];
   

3. 添加清晰度档位切换回调 onResolutionSwitch:resolution:error:reason:，监听清晰度档位切换结果。当清晰度档位发生变化时，SDK 可触发该回调，并返回切换后的清晰度档位、档位切换原因等信息。

   - (void)onResolutionSwitch:(TVLManager *_Nonnull)player resolution:(VeLivePlayerResolution)resolution error:(VeLivePlayerError *)error reason:(VeLivePlayerResolutionSwitchReason)reason;
   

截图 #

截图功能允许您在播放器中截取当前直播画面并生成一张图片。

接入说明 #

1. 通过调用播放器的 snapshot 接口可以实现截图功能。截图仅在播放器播放成功后可以生效。代码示例如下所示。

   int result = [self.livePlayer snapshot];
   

2. 截图成功后，会触发 VeLivePlayerObserver 的 onSnapshotComplete:image: 回调，并将截取的图片数据传递给回调方法。代码示例如下所示。

   - (void)onSnapshotComplete:(TVLManager *)player image:(UIImage *)image  {
      // 截图成功回调，参数 image 为截图的图片数据
   }
   

SEI #

SEI（Supplemental Enhancement Information）是直播流中的附加信息，可用于传递自定义数据或元数据。

接入说明 #

• 字符串 SEI 消息
  1. 在调用 play 方法前，开启播放器的 enableSei 属性。开启后，播放器将接收字符串 SEI 消息。代码示例如下所示。

     // 创建播放器初始化配置。
     VeLivePlayerConfiguration *config = [[VeLivePlayerConfiguration alloc]init];
     
     // 开启字符串 SEI 消息接收功能。
     config.enableSei = YES;
             
     // 初始化配置。
     [self.livePlayer setConfig:config];
     

  2. 当播放器接收到字符串 SEI 消息时，会触发 onReceiveSeiMessage:message: 回调。代码示例如下所示。

     - (void)onReceiveSeiMessage:(TVLManager *_Nonnull)player message:(NSString *_Nonnull)message  {
        // 字符串 SEI 消息回调。
     }
     

• 二进制 SEI 消息
  1. 在调用 play 方法前，开启播放器的 enableBinarySei 属性。开启后，播放器将接收二进制 SEI 消息，且不再触发字符串 SEI 消息回调。代码示例如下所示。

     // 创建播放器初始化配置。
     VeLivePlayerConfiguration *config = [[VeLivePlayerConfiguration alloc]init];
     
     // 开启二进制 SEI 消息接收功能。
     config.enableBinarySei = YES;
             
     // 初始化配置。
     [self.livePlayer setConfig:config];
     

  2. 当播放器接收到二进制 SEI 消息时，会触发 onReceiveBinarySeiMessage:message: 回调。代码示例如下所示。

     - (void)onReceiveBinarySeiMessage:(TVLManager *_Nonnull)player message:(NSData *_Nonnull)message  {
        // 二进制 SEI 消息回调。
     }
     

订阅视频数据 #

通过订阅解码后的视频数据，您可以获取视频帧数据并进行自定义的处理和渲染操作。播放器支持多种视频帧数据的回调，并提供了相应的参数和格式选项。

前提条件 #

视频帧像素格式和视频数据封装格式的枚举和含义如下表所示。

配置订阅视频数据前，请您根据需要选择格式组合。格式组合需要遵循下表中提供的 VeLivePlayerPixelFormat 和 VeLivePlayerVideoBufferType 的对应关系。

接入说明 #

1. 您可以调用播放器的 enableVideoFrameObserver:pixelFormat:bufferType: 接口开启或关闭视频帧数据订阅功能。接口参数说明如下表所示。
   

   参数	类型	说明
   enable	BOOL	是否开启视频帧回调。
   pixelFormat	VeLivePlayerPixelFormat	视频帧像素格式。
   bufferType	VeLivePlayerVideoBufferType	视频数据封装格式。

   代码示例如下所示。

   [self.livePlayer enableVideoFrameObserver:YES pixelFormat:VeLivePlayerPixelFormatNV12 bufferType:VeLivePlayerVideoBufferTypePixelBuffer];
   

2. 解码后的视频帧数据会通过 VeLivePlayerObserver 的 onRenderVideoFrame:videoFrame: 回调返回。代码示例如下所示。

   - (void)onRenderVideoFrame:(TVLManager *)player videoFrame:(VeLivePlayerVideoFrame *)videoFrame  {
      // 视频帧数据回调
   }
   
   

   VeLivePlayerVideoFrame 参数说明如下表所示。
   

   参数	类型	说明
   bufferType	VeLivePlayerVideoBufferType	视频帧数据封装格式
   pixelFormat	VeLivePlayerPixelFormat	视频帧像素格式
   width	NSInteger	视频帧的宽度，单位为 px
   height	NSInteger	视频帧的高度，单位为 px
   pts	int64_t	视频帧的渲染时间戳，单位为 ms
   pixelBuffer	CVPixelBufferRef	bufferType 为 VeLivePlayerVideoBufferTypePixelBuffer 时的视频数据
   sampleBuffer	CMSampleBufferRef	bufferType 为 VeLivePlayerVideoBufferTypeSampleBuffer 时的视频数据
   data	NSData*	bufferType 为 VeLivePlayerVideoBufferTypeNSData 时的视频数据

订阅音频数据 #

通过订阅解码后的音频数据，您可以获取音频帧数据并进行自定义的处理和渲染操作。

播放器支持的音频帧数据格式为 PCM Float32，数据封装格式为 NSData。

接入说明 #

1. 您可以调用播放器的 enableAudioFrameObserver:enableRendering: 接口开启或关闭音频帧数据订阅功能。接口参数说明如下表所示。
   

   参数	类型	说明
   enable	BOOL	是否开启音频帧回调。
   enableRendering	BOOL	是否开启播放器渲染。当不需要播放器内部进行音频播放时，可以将该参数值配置为 NO。

   代码示例如下所示。

   // 订阅音频帧数据，打开播放器内部音频渲染
   [self.livePlayer enableAudioFrameObserver:YES enableRendering:YES];
   

2. 解码后的音频帧数据会通过 VeLivePlayerObserver 的 onRenderAudioFrame:audioFrame: 回调返回。代码示例如下所示。

   - (void)onRenderAudioFrame:(TVLManager *)player audioFrame:(VeLivePlayerAudioFrame *)audioFrame  {
      // 音频帧数据回调
   }
   

   VeLivePlayerAudioFrame 参数说明如下表所示。
   

   参数	数据类型	说明
   bufferType	VeLivePlayerAudioBufferType	音频帧数据封装格式
   sampleRate	int	音频采样率，单位为 Hz
   channels	int	声道数
   bitDepth	int	音频位深度
   pts	CMTime	音频渲染时间戳，单位为 ms
   data	NSData*	PCM 音频数据
   samples	int	音频采样点个数

拉流超分 #

超分，即超分辨率技术（Super-Resolution, SR）是指从观测到的低分辨率图像重建出相应的高分辨率图像的过程，移动端实时超分，是指利用算法技术在端上对低分辨率的帧进行实时重建，产生高分辨率的帧显示在屏幕上，从而改善视频内容的细节与对比度，全面提升视频的播放清晰度和观看体验的优化手段。

前提条件 #

自 1.51.3 版本开始，如需使用拉流超分功能，集成拉流 SDK 时需在拉流组件基础上额外添加 LivePull-BMF 依赖。详见集成 iOS 拉流 SDK。

接入说明 #

1. 自 1.51.3 版本开始，需引入 VeLivePlayer+SuperResolution.h 头文件。
   动态库

   静态库

   #import <TTSDKFramework/VeLivePlayer+SuperResolution.h>
   

   #import <TTSDK/VeLivePlayer+SuperResolution.h>
   

2. 调用播放器的 setEnableSuperResolution: 方法开启或关闭拉流超分。

   [self.livePlayer setEnableSuperResolution:YES];
   

   参数名	类型	说明
   enable	BOOL	是否开启超分。默认值为 NO。 YES：开启。 NO：关闭。

3. 开启超分时，如果开启失败，播放器会通过 VeLivePlayerObserver 中的 onStreamFailedOpenSuperResolution:error: 回调进行通知。代理方法签名如下所示。

   - (void)onStreamFailedOpenSuperResolution:(TVLManager *_Nonnull)player error:(VeLivePlayerError *_Nullable)error; 
   

   开启超分失败的常见原因如下：
   • 流的实际分辨率不在超分支持范围内。
   • 流的实际帧率不在超分支持范围。
   • 当前机型不支持超分。

域名解析 #

直播拉流 SDK 支持调用火山引擎 HTTPDNS 服务对拉流地址的预解析，以此来降低播放首帧时长。

接入说明 #

1. 开通云解析 DNS 服务。
2. 登录移动解析 HTTPDNS 控制台。
3. 左侧导航栏选择实例信息，记录您的鉴权密钥，包含 Service ID 和 Secret Key。
   
4. 在拉流客户端调用 setVeHttpDNSAuth:key: 方法配置调用 HTTPDNS 服务需要使用的鉴权密钥，代码示例如下所示。

   [VeLiveCommon setVeHttpDNSAuth:@"http_dns_serviceID" key:@"http_dns_key"]; // 分别替换为实际的 Service ID 和 Secret Key。
   

5. 调用 prefetchDomains: 方法进行域名解析，解析成功后的 IP 地址会自动设置给播放器，代码示例如下所示。

   [VeLiveCommon prefetchDomains:@[
       @"pull01.example.com", // 替换为实际拉流域名。
       @"pull02.example.com" // 替换为实际拉流域名。
   ]];
   

自定义 HTTP 请求头 #

设置播放器发起 HTTP 请求时携带的自定义请求头。常用于传递鉴权令牌（Token）、Cookie 或业务追踪标识等额外信息。

接入说明 #

在开始播放前，您可通过播放器的 setProperty:value: 高级接口设置自定义 HTTP 请求头。 调用 setProperty:value: 接口时，需传入一组 Key-Value 配置。

Key

Value

Value 为 NSDictionary 类型，表示需要传入一个 Key-Value 形式的字典对象，用于设置自定义 HTTP 请求头。

• Key： NSString 类型，请求头名称。
• Value：NSString 类型，请求头值。

示例代码如下所示。

• 如需设置一个 HTTP 请求头

  [self.livePlayer setProperty:VeLivePlayerKeySetParamsHttpHeaders value:@{@"key": @"value"}]; // 分别替换为实际的请求头名称和请求头值。
  

• 如需设置多个 HTTP 请求头

  [self.livePlayer setProperty:VeLivePlayerKeySetParamsHttpHeaders
                            value:@{
                              @"key1": @"value1", // 分别替换为实际的请求头名称和请求头值。
                              @"key2": @"value2", // 分别替换为实际的请求头名称和请求头值。
                              @"key3": @"value3" // 分别替换为实际的请求头名称和请求头值。
                            }];
  

H.265 软解和硬解 #

SDK 高级版或试用版 License 默认开启 H.265 硬解（硬件解码）和软解（软件解码）功能。播放 H.265 编码的视频流时，SDK 会优先尝试使用 H.265 硬解。如果 H.265 硬解失败，SDK 会自动切换为 H.265 软解。

请在调用 play 前，通过播放器初始化配置开启或关闭硬解。示例代码如下所示。

VeLivePlayerConfiguration *config = [VeLivePlayerConfiguration new];
config.enableHardwareDecode = YES;
// 初始化播放器
[self.livePlayer setConfig:config];

• YES：开启硬解。
• NO：关闭硬解，只使用软解。

您可以通过监听 onStatistics:statistics: 回调，并结合 VeLivePlayerStatistics 的 isHardWareDecode 属性，判断当前播放的流是否使用了硬解。

视频锐化 #

视频锐化指在设备本地对视频画面进行增强处理，从而提升画面边缘和纹理细节表现的能力。播放视频时，SDK 可以实时增强画面边缘和纹理细节，从而让画面看起来更清晰，提升观看体验。

前提条件 #

自 1.51.3 版本开始，如需使用视频锐化功能，集成拉流 SDK 时需在拉流组件基础上额外添加 LivePull-BMF 依赖。详见集成 iOS 拉流 SDK。

接入说明 #

1. 自 1.51.3 版本开始，需引入 VeLivePlayer+SuperResolution.h 头文件。
   动态库

   静态库

   #import <TTSDKFramework/VeLivePlayer+SuperResolution.h>
   

   #import <TTSDK/VeLivePlayer+SuperResolution.h>
   

2. 调用播放器的 setEnableSharpen: 方法开启或关闭视频锐化。

   [self.livePlayer setEnableSharpen:YES];
   

   参数名	类型	说明
   enable	BOOL	是否开启视频锐化。默认值为 NO。取值如下： YES：开启。 NO：关闭。

3. 开启视频锐化时，如果开启失败，播放器会通过 VeLivePlayerObserver 的 onError:error: 回调进行通知。代理方法签名如下所示。

   - (void)onError:(TVLManager *_Nonnull)player error:(VeLivePlayerError *_Nonnull)error;
   

   开启视频锐化失败的常见原因如下：
   • 流的实际分辨率不在视频锐化支持范围内。
   • 流的实际帧率不在视频锐化支持范围内。
   • 当前机型不支持视频锐化。
   • 当前 License 不支持视频锐化。

画中画 #

画中画功能通过将播放器窗口缩小并置于界面一角，允许观众在观看直播的同时浏览其他内容或打开其他应用，从而提升用户体验。

前提条件 #

• 已集成 1.51.2 及以上版本的 SDK。

  说明

  如集成 1.51.2 以下版本的 SDK，可以集成画中画解决方案版本，从而实现画中画功能。详见画中画解决方案版本。

• iOS 15.0 及以上系统。
• 在 Xcode 中，为您的 App Target 开启画中画所需的后台模式。
  1. 单击 Signing & Capabilities 页签下的 + Capability，并双击添加 Background Modes。
     
  2. 在 Background Modes 区域，选择 Audio, AirPlay, and Picture in Picture 复选框。
     
• 引导观众在其设备上开启系统级设置，即在设置 > 通用 > 画中画页面开启自动开启画中画开关，从而在 App 进入后台时自动开启画中画播放直播画面。
  

接入说明 #

1. 导入画中画头文件。
   静态库集成

   动态库集成

   如使用静态库集成 SDK，使用 #import <TTSDK/VeLivePlayer+PictureInPicture.h> 导入画中画头文件。

   如使用动态库集成 SDK，使用 #import <TTSDKFramework/VeLivePlayer+PictureInPicture.h> 导入画中画头文件。

2. 判断当前设备是否支持画中画。

   if ([TVLManager isPictureInPictureSupported]) {
       // 根据设备是否支持画中画，执行相应的业务逻辑。
   }
   

3. 初始化自研播放器，并开启画中画功能。画中画功能默认关闭。

   TVLManager *player = [[TVLManager alloc]initWithType:VeLivePlayerTypeOwn];
   player.enablePictureInPicture = YES;
   

   说明

   画中画功能仅支持自研播放器，不支持系统播放器。

4. 设置 App 进入后台时是否自动启动画中画。该设置仅对当前播放器生效，不会修改用户设备上的系统级画中画设置。
   默认情况下，App 进入后台时会自动启动画中画。如果您不希望 App 进入后台时自动启动画中画，可将 canStartPictureInPictureAutomaticallyFromInline 设置为 NO。以下示例代码开启 App 进入后台时自动启动画中画

   player.canStartPictureInPictureAutomaticallyFromInline = YES;
   

5. 如需监听画中画的启动、停止等时机，可自定义以下画中画代理方法。SDK 内部已处理了画中画所需的关键代理方法，多数场景下您无需额外实现。

   @property (nonatomic, weak, nullable) id<AVPictureInPictureControllerDelegate> pictureInPictureDelegate;
   @property (nonatomic, weak, nullable) id<AVPictureInPictureSampleBufferPlaybackDelegate> pictureInPicturePlaybackDelegate;
   

6. 在开始拉流播放后，可手动开启画中画。

   [player startPictureInPicture];
   

   如当前已进入画中画模式，可手动停止画中画。

   [player stopPictureInPicture];
   

7. 如需判断当前是否已成功启动画中画，可调用以下方法。

   BOOL isStarted = [TVLManager isPictureInPictureStarted];
   

8. 如需手动更新画中画的播放按钮状态和进度显示，可调用 invalidatePictureInPicturePlaybackState。SDK 内部会自动处理，多数场景下您无需手动调用该方法。

   [player invalidatePictureInPicturePlaybackState];
   

画中画解决方案版本 #

如果您集成的 SDK 为 1.51.2 以下版本，可以集成画中画解决方案版本，从而实现画中画功能。

按需选择以下集成方式：

pod 'VeLivePictureInPicture', :git => 'https://github.com/volcengine/VeLiveQuickStartDemo.git', :branch => 'main'

pod 'VeLivePictureInPicture', :path => './'

集成画中画解决方案版本后，API 使用方式与 1.51.2 及以上版本的 SDK 相同，详见接入说明。

高级接口配置 #

去除 SDK 自动拼接的 Query 参数 #

拉流 SDK 可能会在拉流地址后追加 Query 参数，例如 session_id。这类参数用于标识同一次拉流会话，方便排查播放问题时，在客户端日志和 CDN 日志中定位同一次拉流。如需保持实际请求地址不增加由 SDK 自动追加的 Query 参数，可以开启该功能。开启后，会从实际请求地址中去除 SDK 自动拼接的 Query 参数，但原始拉流地址中已存在的 Query 参数会被保留。

接入说明

在开始播放前，您可通过播放器的 setProperty:value: 高级接口设置是否去除 SDK 自动拼接的 Query 参数。调用 setProperty:value: 接口时，需传入一组 Key-Value 配置。

Key

Value

Value 为 NSNumber 类型，表示是否去除 SDK 自动拼接的 Query 参数。默认值为 0。

• 1：去除 SDK 自动拼接的 Query 参数。
• 0：保留 SDK 自动拼接的 Query 参数。

示例代码如下所示。

[self.livePlayer setProperty:@"VeLivePlayerKeySetParamsRemoveQueryParams" value:@1];

效果示例

例如拉流地址为：

https://pull.example.com/live/test.flv?auth_key=1779891783-0-0-e1f5a2a****4b5fe21cb3efdc89af901

SDK 发起播放请求时自动拼接了 session_id：

https://pull.example.com/live/test.flv?auth_key=1779891783-0-0-e1f5a2a****4b5fe21cb3efdc89af901&session_id=xxx

开启该功能后，实际请求会去除 session_id，并保留原始拉流地址中的鉴权参数 auth_key：

https://pull.example.com/live/test.flv?auth_key=1779891783-0-0-e1f5a2a****4b5fe21cb3efdc89af901