CDN加速

Android播放器

更新时间:2021-07-23 10:59:57

IOS播放器SDK下载地址

第一章 产品概述

1.1. 产品简介

  CNCMediaPlayer SDK 是一个功能齐全、易于集成的视频播放器 SDK,支持点播和直播。支持设置缓冲时间、延时追等来降低直播时延,支持后台播放时不解码视频以降低 cpu 消耗。
  SDK 以工程库的方式提供,并分为 2 部分:CNCRelease 目录下是核心的 framework 动态库;CNCMediaPlayerLibDemo 目录是 demo 代码(包括 UI 部分和手势操作等功能部分),必要时可自行修改。
  SDK 内嵌鉴权模块,必须鉴权成功才能正常使用。
  SDK 接口与系统播放器 MPMoviePlayerController 接口几乎保持一致,零学习成本接入。

1.2. 适用环境

1.2.1. 开发环境

  操作系统:MacOS
  IDE:Xcode。

1.2.2. 运行环境

  设备:iPhone4s 及以后的设备
  系统:iOS8 及以上
  架构:armv7、arm64

1.2.3. 版本说明

  SDK 的代码文件和 framework 只有一份,而底层库分为 2 个版本:完整版(full)和直播版(live)。直播版仅保证支持 RTMP、HTTP、HTTPS、 FLV、HLS,so 库体积较小。而完整版不仅支持直播,还支持点播的各种格式,framework库体积较大。可根据自身业务情况选择相应的 framework 库。
  ✓ 轻量版
  ✓ 完整版

1.2.4. 主功能项

  ✓ 支持播放截屏
  ✓ 支持自定义亮度音量调节
  ✓ 支持视频画面缩放模式
  ✓ 支持直播延时追赶
  ✓ 支持直播时移
  ✓ 支持静音播放
  ✓ 支持软硬解
  ✓ 支持 H.265/HEVC 播放
  ✓ 支持首屏加速
  ✓ 支持后台不解码,更节约性能
  ✓ 支持后台播放
  ✓ 支持多种格式录制(mp4,mov,flv,gif)
  ✓ 支持 sock4 sock5 http https 代理
  ✓ 支持更精准的缓存控制
  ✓ 支持 opensles 音频加速
  ✓ 支持点播本地缓存
  ✓ 支持点播循环播放
  ✓ 支持获取原始视频的 yuv 数据和 pcm 数据
  ✓ 支持点播精准 seek
  ✓ 支持 cache 内 seek
  ✓ 支持点播 HLS 码率自适应
  ✓ 支持直播低延迟
  ✓ 支持多开播放器
  ✓ 支持局部录屏
  ✓ 支持 mp4、hls 解密播放
  ✓ 支持 dash 播放
  ✓ 支持 dash 设置默认码率
  ✓ 支持 dash 码率切换
  ✓ 支持预加载
  ✓ 支持 DNS 缓存控制
  ✓ 支持连接超时设置
  ✓ 支持音频兼容模式
  ✓ 支持分辨率重建

第二章 集成方案

  接口定义请下载包后,参考包内API说明文档:iOS播放器SDK_API文档/index.html

2.1. 工程配置

2.1.1. 文件说明

  移动端 SDK-IOS 版本提供的是 Framework,
  完整版为 CNCMediaPlayerFramework.framework,
  直播版为 CNCLiveMediaPlayerFramework.framework

2.1.2. 工程配置

添加 framework 到工程中

工信部网络安全大检查来袭,你准备好了吗?

添加 Embedded Binaries

工信部网络安全大检查来袭,你准备好了吗?

2.1.3. 其他配置

  若Framework不在工程根目录内部,则需要在工程的Build Setting中的Framework Search Pahts中添加framework的所在路径。
  在工程的Info.plist添加如下Http权限

工信部网络安全大检查来袭,你准备好了吗?

  在工程的TARGETS—>Capabilities中打开Background Modes,并选择第一个Audio,AirPlay,and Picture in Picture

工信部网络安全大检查来袭,你准备好了吗?

2.2. 鉴权

SDK 内部会检查鉴权结果,请求鉴权的接口为:

+ (CNC_MediaPlayer_ret_Code)regist_app:(NSString *_Nonnull)app_id
auth_key:(NSString *_Nonnull)auth_key;

SDK 提供异步鉴权接口:

+ (void)async_regist_app:(NSString *_Nonnull)app_id auth_key:(NSString *_Nonnull)auth_key;

理论上一个自然日内只会发起一次网络鉴权(可能较耗时),为避免在 SDK 内部发起网络鉴权请求,建议在 app 启动时调用。

2.3. 初始化播放器

CNCMediaPlayerController类中的view,是播放器的渲染视图,初始化CNCMediaPlayerController之后对view进行frame的设置后,在需要展示的父视图上对view进行addSubview,即可完成播放布局。

self.player = [[CNCMediaPlayerController alloc] initWithContentURL:self.URL option:option];
[self.viewFullScreen addSubview:self.player.view];

2.4. 播放器参数配置

初始化播放之后,对播放器做初始化配置(请参考 CNCPlayerSetting 类),示例代码如下,具体配置项在后面介绍

//debug 模式下可选debug,若日志太多干扰,可选warn
        [self.player setLogLevel:CNC_MediaPlayer_Loglevel_Debug];
        
        //设置直播或者点播
        [self.player setPlayMode:self.setting.isLive ? CNC_MEDIA_PLAYER_MODE_LIVE : CNC_MEDIA_PLAYER_MODE_VOD];
        
        //设置是否自动播放
        [self.player setShouldAutoPlay:self.setting.isAutoPlay];
        
        //设置解码方式:(软解、硬解)
        [self.player setVideoDecoderMode:self.setting.isHardware ? CNC_VIDEO_DECODER_MODE_HARDWARE : CNC_VIDEO_DECODER_MODE_SOFTWARE];
        
        //设置延时追赶(直播场景下使用,如果在点播使用会导致缓存不断被清除)
        [self.player setShouldAutoClearCache:self.setting.isAutoClearCache];
        
        //设置是否后台播放
        [self.player setAbleVideoPlayingInBackground:self.setting.isPlayBackground];
        
        //设置是否进行后台视频解码,不解码可以节约设备资源,节省电量
        [self.player setDisableVideoDecodeInBackground:self.setting.isDisableDecodeBackground];
        
        //设置快启,加快首屏
        [self.player accelerateOpen:self.setting.isAccelerateOpen];
        
        //设置是否兼容其他app的音频,开启时其他app的音频不会中断播放器音频,否则其他app的音频播放会中断播放器的播放
        [self.player setMixOtherPlayer:self.setting.isMixOtherPlayer];
        
        //设置缓冲最小时长,卡顿时需加载到这里设置的时长才会恢复播放状态
        [self.player setMinBufferTime:self.setting.minBufferTime];
        
        //设置延时追赶时间,缓存时长超过此阈值时,进行追赶
        [self.player setMaxCacheTime:self.setting.maxCacheTime];
        
        //设置低延时模式,延时追赶采用变速播放进行,使追赶更加平滑,点播不生效
        [self.player setShouldLowLatencyMode:self.setting.isLowLatencyMode];
        
        //设置HLS码率自适应
        [self.player setHLSAdaptation:self.setting.isHLSAdaptation];
        
        //设置HLS码率自适应的默认播放码率
        [self.player setDefaultHLSBitrate:self.setting.HLSDefaultBitrate];
        
        //设置解码前缓冲队列大小,默认15MB,设置值较大时则加载更多但影响内存占用
        [self.player setMaxBufferSize:self.setting.maxBufferSize];
        
        //设置缩放模式,参见CncMpVideoScalingMode
        [self.player setScalingMode:CNC_MP_VIDEO_SCALE_MODE_ASPECTFIT];
        
       /*
        设置是否开启精准seek
        精准seek会在触发seek时找到相应位置的关键帧后,
        快速解码到seek位置,不会产生找关键帧而导致seek后位置左右跳动
        */
        [self.player setEnableAccurateSeek:self.setting.isAccurateSeek];
        
        //设置循环播放次数
        [self.player setLoop:self.setting.loopCount];
        
        //设置HLS解密参数
        [_player openHLSEncryption:self.setting.isOpenHLSEncryption withVideoID:self.setting.hlsDecryptionVideoId];
);

2.5. 启动播放器

  ✓ 初始化播放器(必须)
  ✓ 完成播放器布局(必须)
完成配置参数(未设置则启动时以默认参数进行播放)
在完成以上事项之后可以启动播放器。启动播放器是异步操作,调用CNCMediaPlayerController 的实例方法 prepareToPlay,示意代码如下:

[self.player prepareToPlay];

第三章 重要类

3.1. CNCMediaPlayerController

播放器实例,该类包括

  ✓ 创建播放器
  ✓ 使用播放器
  ✓ 管理播放器
  ✓ 销毁播放器

详细接口参见类接口或者直接查阅 API 文档

3.2. CNCMediaPlayerSDK

播放器工具类,该类包括

  ✓ 鉴权功能
  ✓ 日志系统开关
  ✓ 截图/水印
  ✓ 点播缓存开关及存储策略
  ✓ 其他全局设定

3.3. CNCMediaPlayerComDef

播放器宏定义部分

  ✓ 通知字段
  ✓ 键值对定义
  ✓ 各参数枚举

第四章 功能说明

4.1. 直播业务

直播模式,需在播放器实体类设置属性为 CNC_MEDIA_PLAYER_MODE_LIVE

@property (nonatomic) CNCMediaPlayerMode playMode;

直播模式与点播的区别

  ✓ 支持直播回看功能:时移(需服务端配置配合)
  ✓ 支持延时追赶功能(超过设置的缓存阈值则情况缓存)
  ✓ 支持低延时模式(通过调整播放器速率对缓存大小进行控制)

4.2. 点播业务

点播模式,需在播放器实体类设置属性为 CNC_MEDIA_PLAYER_MODE_VOD

@property (nonatomic) CNCMediaPlayerMode
playMode;

直播模式与点播的区别

  ✓ 支持播放器进度拖拉:SEEK 功能
  ✓ 支持点播精准 SEEK
  ✓ 支持点播缓存 SEEK
  ✓ 支持点播缓存
  ✓ 支持点播循环播放

4.3. 解码方式

支持解码方式的选择

  ✓ 软解
   基于 ffmpeg,支持 HEVC。
   通用性强、兼容性好;比较消耗 CPU。

  ✓ 硬解
   基于 iOS VTB:VideoToolBox,只能在 iOS8 以上支持,iOS11 以上才支持 HEVC,通用性较差、兼容性较差;调用 GPU 参与解码,节约 CPU 性能消耗,更省电。

4.4. 手势控制

手势控制的功能包括:

  ✓ 控制音量大小
  ✓ 控制屏幕亮度
  ✓ 划屏拖拉进度条
  ✓ 双击切换画面比例

4.5. 后台播放

设置播放器是否允许后台播放。
需在播放器实体类设置属性

// 后台播放 1)YES 允许后台播放  2)NO 禁止后台播放

@property (nonatomic) BOOL ableVideoPlayingInBackground;

播放器 SDK 实现了对前后台的监听监听,只设置此参数即可实现后台播放

4.6. 后台播放不解码

  仅软解支持
  当使用软解播放时,进入后台默认解码视频,在后台时仍然占用较多的 cpu,SDK 支持设置后台不解码以降低 cpu 的消耗。

//后台解码,允许后台播放下设置该变量生效,只针对软解,1)YES:程序在后台时,只进行音频解码,不进行视频解码 2)进入后台,音视频仍旧在解码

@property (nonatomic) BOOL disableVideoDecodeInBackground;

4.7. 直播延时追赶

  直播对于视频延时比较敏感,SDK 提供延时追赶的功能,默认关闭,如下配置开启:

//延时追赶 1)YES:当缓存大于 maxCacheTime 时,会清除内存临时缓存,以播放最新的数据 2)NO:关闭该功能

@property (nonatomic, assign) BOOL shouldAutoClearCache;

  直播场景下使用,如果在点播使用会导致缓存不断被清除。

延时追赶阈值
  SDK 默认延时超过 5000ms 开始追赶,这个阈值可配置(最小 500):

//直播时的延时追赶时间 本地缓存 cacheDuration 超过 maxCacheTime 后,播放最新视频信息,单位是毫秒

@property (nonatomic) NSTimeInterval maxCacheTime;

4.8. 直播低延时模式

  直播低延时模式与延时追赶的作用是一样的,都是降低直播的延,区别于延时追赶的实现方式是用控制播放速度的方式

  • 缓存大于上限阈值时加快播放速度。
  • 缓存低于下限阈值时降低播放速度。

  低延时模式的效果在于可以实现无感知的、非跳跃式进行直播的延时追赶。 接口实现为设置播放器实例属性:

//低延时模式,使用变速播放进行延时追赶,仅供测试 暂不提供使用

@property (nonatomic, assign) BOOL shouldLowLatencyMode;

4.9. 缓冲阈值

  缓冲,是指在网络条件较差等情况下导致的接收不到足够的数据进行播放时,播放器等待接收到足够的数据后再继续播放的过程。
  缓冲阈值,单位是毫秒,即当播放器缓冲直至视频数据时长到达设定的阈值时,返回播放状态。缓冲阈值默认 0,最小值是 0,最大值是 5000。当设为 0 时即认为不缓冲,可以一定程度降低延时。

//缓冲时长 最低播放时长,即至少加载 minBufferTime 可进行播放,单位是毫秒

@property (nonatomic) NSTimeInterval minBufferTime;

4.10. 秒开

  通过优化拉流解析模块,加快首屏渲染的速度。将大部分流的首屏加载时间 优化到 1 秒以内。
  通过设置以下属性开启:

//是否开启秒开 YES/NO, 需要在 prepare 之前设置

@property (nonatomic) BOOL accelerateOpen;

4.11. 录制/录屏

支持将直播或点播视频流录制成 MP4/MOV 或 GIF 文件。
&emsp支持 2 种模式的录制:录视频源模式、录制屏幕。前两种模式都是录制视频源,不同之处在于:
  ✓ 录视频源模式侧重还原视频源本身。
  ✓ 模拟录屏模式侧重还原实际观看到的场景,比如播放过程中的卡顿也会体现在录制结果中。

录屏还提供:

  • 全屏录制
  • 指定 UIView 录制
  • 任意区域录制

录制的相关接口开始录制与结束录制,考虑到录制 GIF 的性能问题,为录制 GIF 增加一个缩放比例,在性能不高的设备上可以适当调低 GIF 录制的缩放比例,达到牺牲清晰度保证帧率的效果,接口如下:

/**
 开始录制视频
 @param filename    录制输出文件名称
 @param format      录制输出文件格式目前支持gif/MP4/FLV
 @param maxTime     录屏的最长时间单位(ms)是、GIF最大不超过3000ms MP4/FLV最大不超过60000ms
 @param minTime     录屏的最短时间单位(ms)是、GIF最小低于100ms MP4/FLV最大小不低于30000ms
 @return -1         开始失败 其他值表示成功
 */
- (int)startRecordingWithFilename:(NSString *)filename format:(NSString *)format minTime:(int) minTime maxTime:(int)maxTime;

/**
 开始录制视频
 @param filename    录制输出文件名称
 @param format      录制输出文件格式目前支持gif/MP4/FLV
 @param maxTime     录屏的最长时间单位(ms)是、GIF最大不超过3000ms MP4/FLV最大不超过60000ms
 @param minTime     录屏的最短时间单位(ms)是、GIF最小低于100ms MP4/FLV最大小不低于30000ms
 @param scale       format为@"gif"时有效,控制gif缩放比例 范围在270~480
 @return -1         开始失败 其他值表示成功
 */
- (int)startRecordingWithFilename:(NSString *)filename format:(NSString *)format minTime:(int) minTime maxTime:(int)maxTime gifScale:(int)scale;

/**
 结束录制视频
 @return YES 结束录制成功,也可通过通知CNCMediaPlayerStatusCodeNotification异步获取
 */
- (BOOL) stopRecording;

录屏的相关接口相对录制增加了:

  • 控制界面的显示和隐藏,
  • 可取消录屏
  • 重置录屏

接口如下:

/**
 显示录屏控制视图
 @param recorderCtrlView 控制录屏的视图
 @param type 录屏类型
 @return 是否显示成功
 */
- (BOOL)showRecorderView:(nonnull UIView *) recorderCtrlView type:(CNC_MediaPlayer_Screen_Record_Type) type;

/**
 显示录屏控制视图,并指定录制的范围(图层)

 @param recorderCtrlView 控制录屏的视图
 @param toRecordView 需要录制的图层
 @param type 录屏类型
 @return 是否显示成功
 */
-(BOOL)showRecorderView:(nonnull UIView *)recorderCtrlView toRecordView:(UIView *_Nullable)toRecordView type:(CNC_MediaPlayer_Screen_Record_Type)type;

/**
 隐藏录屏控制视图
 与
 - (BOOL)showRecorderView:(nonnull UIView *) recorderCtrlView type:(CNC_MediaPlayer_Screen_Record_Type) type
 对应,用于隐藏/移除录屏控制视图
 */
-(void)hideRecorderCtrlView;

/**
 显示录屏控制视图,并指定录制的范围(图层且任意区域)
 显示录屏控制视图,并指定录制的范围(图层)
 
 @param recorderCtrlView 控制录屏的视图
 @param toRecordView 需要录制的图层
 @param type 录屏类型
 @param option 额外参数,目前支持rect字段,可在指定toRecordView中裁剪相应区域进行录屏
 @return 是否显示成功
 */
-(BOOL)showRecorderView:(UIView *)recorderCtrlView toRecordView:(UIView *)toRecordView type:(CNC_MediaPlayer_Screen_Record_Type)type option:(NSDictionary *) option;

/**
 开始录制屏幕
 @param filename            录屏输出文件名称
 @param format              录制输出文件格式目前支持mov
 @param minTime             录屏的最长时间单位(ms)最大不超过6000ms
 @param minTime             录屏的最短时间单位(ms)最大小不低于3000ms
 @param handler             录屏开始的回调,正常开始error为nil,若为SDK自动结束录制,handle中的error会附带录制成功或录制失败的信息
 @param exceptionHandler    录屏过程中的异常回调,例如磁盘空间不足/录制时间不足/超出时限/异常中断等回调
 @return                    -1 开始失败 其他值表示成功
 */
- (int)startScreenRecordWithFilename:(NSString *_Nonnull)filename  format:(NSString *_Nonnull)format minTime:(int) minTime maxTime:(int)maxTime handler:(nullable void(^)(NSError * __nullable error))handler exceptionHandler:(nullable void(^)(NSDictionary * __nullable object,NSError * __nullable error))exceptionHandler;

/**
 结束录制屏幕
 @para handle 主动调用stopScreenRecord后,若是录制失败,handle中的error参数会附带错误信息
 @return dictionary有值 结束录制成功  dictionary为nil则结束录制失败
 */
- (NSDictionary *_Nonnull)stopScreenRecordWithHandler:(nullable void(^)(NSDictionary * __nullable object, NSError * __nullable error))handler;

/**
 取消录制屏幕
 @para handle handle中的error参数会附带错误信息
 @return YES 结束录制成功
 */
- (int)discardScreenRecordWithHandler:(nullable void(^)(NSError * __nullable error))handler;

/**
 重新录屏,取消之前录制的结果,录制文件及产生的临时文件被删除,录制界面恢复开始录制之前的界面.可重新开始录制
 @param handler 异常回调
 @return 重置成功与否返回值 大于0成功
 */
-(int)resetScreenRecordWithHandler:(void (^_Nullable)(NSError * _Nullable))handler;

调用示例请参考 demo 代码。

4.12. 截屏

支持对当前显示 UIView 的截图,接口如下:

/**
截屏
@return 返回当前时刻的屏幕截图
*/
+ (UIImage *_Nonnull) screenShot;

4.13. 静音

支持基于播放器实例的静音而不影响其他播放器或者外部系统音量。可单独对每个播放器分别设置是否静音。
接口及调用示例:

//设置当前播放器静音与否静音
@property (nonatomic) BOOL mute;

//调用示例
[_player setMute:mute];

4.14. 代理

支持设置 socks5/sock4/http/https 代理,如果设置这四种代理之一,客户端将不直接与流媒体服务器交互,而是通过代理服务器间接和流媒体服务器交 互。四种代理的接口一致,并且同一时刻只能设置一种代理模式。调用示例参考 demo 代码,接口如下:

/**
 打开socks5代理功能,代理互斥,开启socks5则关闭socks4及HTTP/HTTPS代理
 @param     user    用户名
 @param     pwd     密码
 @param     ip      ip地址
 @param     port    端口号
 @return 返回小于0为失败
         -1:ip为空
         -2:port为空
         -3:user为空
         -4:pwd为空
 */
- (int)enableSocks5:(NSString *_Nonnull) user pwd:(NSString *_Nonnull) pwd ip:(NSString *_Nonnull) ip port:(NSString *_Nullable)port;

/**
 打开socks4代理功能 开启socks4则关闭socks5及HTTP/HTTPS代理
 @param ip ip地址
 @param port 端口号
 @return 返回小于0为失败
         -1:ip为空
         -2:port为空
 */
- (int)enableSocks4WithIP:(NSString *_Nonnull) ip port:(NSString *_Nonnull)port;

/**
 开启HTTP/HTTPS 代理 开启HTTP/HTTPS 则关闭socks4及socks5代理
 @param user 用户名
 @param pwd 密码
 @param ip ip地址
 @param port 端口号
 @param https BOOL 是否HTTPS
 @return 返回小于0为失败
         -1:ip为空
         -2:port为空
 */
- (int)enableHttpProxyWithUsername:(NSString *_Nullable) user pwd:(NSString *_Nullable) pwd IP:(NSString *_Nonnull) ip port:(NSString *_Nonnull)port isHtpps:(BOOL) https;

/**
 关闭socks5功能
 @return 关闭成功与否返回小于0为失败
 */
- (int)disableSocks5;

4.15. 直播时移回看

时移,是指观众可以在限定范围内回放过去时间的直播内容,SDK 支持网宿时移回看的直播视频源(若有需要,请联系网宿技术支持团队协助开通),相关接口如下:

/**
 *  设置时移key和上限value    如果要加载其他URL或者重新设置key和maxtime,需要先调用closeTimeShift
 *  @param key  时移参数 nil为默认值
 *  @param maxtime  时移上限时间
 */
- (void)openTimeshiftWithKey:(NSString *_Nullable)key andMaxTime:(NSInteger)maxtime;

/**
 *  时移开启下调用生效,时移至time时间前
 *  @param time 要时移的时间
 */
- (void)timeshiftWithtime:(NSInteger)time;

/**
 *  关闭时移
 */
- (void)closeTimeShift;

调用示例代码请参考 demo 代码。

4.16. 变速播放

支持网宿点播倍速播放,SDK 支持自定[0.5,2]倍速播放。启用变速时建议不要使用录制/录屏,该功能对手机性能要求高。变速播放,对应录屏和录制,音视频速度也是变的。

//播放速率 精确到小数点后一位 范围 0.5~2.0 prepare 之后设置
@property (nonatomic) float playBackRate;

4.17. SEI

支持 h264 数据的 sei 扩展字段。可解析推流段的 SEI 数据,并在收到 sei 数据的时候通过监听通知 CNCMediaPlayerWSCustomSEI,完成将数据通知给应用层的操作。
调用示例如下:

// sei上报通知
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(cncPlayerGetSEI:) name:CNCMediaPlayerWSCustomSEI object:self.player];

4.18. 点播缓存

点播缓存是指,点播播放过的视频数据可以缓存在本地,在下一次播放相同 URL 的视频源时不再需要请求网络,而是通过读取本地缓存数据即可播放。
接口如下:

/*! @brief 开启点播缓存功能
 * @param   open    是否开启点播缓存功能
 * @param   folderPath  点播缓存文件存放文件夹路径 未传值则默认存放于沙盒Document下的cnc_cache_video目录
 * @return 开启成功返回YES
 */
+ (BOOL)openLocalCache:(BOOL)open withFolderPath:(NSString *_Nullable)folderPath;

/*! @brief 设置点播缓存视频个数上限
 * @param   cacheVideoCount    缓存视频个数上限
 * @return  无
 * @see setLocalCacheVideoSize:
 * @remark  该方法与setLocalCacheVideoSize:若同时设置,则优先生效setLocalCacheVideoSize:
 */
+ (void)setLocalCacheVideoCount:(NSUInteger)cacheVideoCount;

/*! @brief 设置点播缓存视频大小上限
 * @param   cacheVideoSize    缓存视频大小上限
 * @return  无
 * @see setLocalCacheVideoCount:
 * @remark  该方法与setLocalCacheVideoCount:若同时设置,则优先生效setLocalCacheVideoSize:
 */
+ (void)setLocalCacheVideoSize:(NSUInteger)cacheVideoSize;

4.19. 循环播放

支持点播的循环播放,即播放结束时从头开始继续播放。接口如下:

/**
* 点播循环播放次数
* 设置为 0:重复循环播放
* 设置为大于 0:循环播放设置次数
*/
@property (nonatomic) NSUInteger loop;

4.20. 精准 SEEK

  精准 SEEK 是相对普通 SEEK 而言的,普通的 SEEK 会在结束点时向前或向后找关键帧,效果会呈现拖到指定的秒数会向前或者向后跳一定的时间。
  精准 SEEK 则是通过向前查找关键帧后,解码但不渲染,快速追赶到 SEEK 的位置时才进行渲染,这样可以避免 SEEK 时产生的跳动问题。

/**
* 点播精准 seek
* YES:seek 时直接播放当前时间点的画面
* NO:seek 时播放当前时间点所在 gop 的 i 帧
*/
@property (nonatomic) BOOL enableAccurateSeek;

4.21. HLS 码率自适应

  支持点播 HLS 码率自适应,会根据当前的网络变化来自动播放适用的码率;当手动设置播放码率时,自适应功能自动关闭,这种情况下,若当前的网络不适合播放设置的码率时,会发出建议降低码率的通知。

设置码率自适应接口有

  • HLS 码率自适应的开关
  • 默认 HLS 码率的设置
  • 手动切换 HLS 码率
  • 关闭 HLS 码率自适应
//是否开启hls码率自适应,与默认设置hls码率不冲突,但当手动设置一次后,自动适应失效
@property (nonatomic, assign) BOOL HLSAdaptation;
//设置默认播放的hls码率,需要知道多码率列表的具体码率值,设置才会生效
@property (nonatomic) int64_t defaultHLSBitrate;
/**
 关闭hls码率自适应
 @return 关闭成功与否返回 小于0为失败
 */
- (BOOL)closeHLSAdaptation;
/**
 播放过程中手动设置hls播放码率
 @param bitrate 设置的码率
 @return 设置成功与否返回 小于0为失败
 */
- (BOOL)selectBitrate:(int64_t)bitrate;

4.22. 多播放器

  当前播放器版本支持播放器多开,播放器多开即创建多个播放器实例,步骤于创建单个播放器实例一致,使用功能也一致。

  除此之外需要注意的点:

  • 通知的监听通过 object 字段判断通知来源于哪个播放器
  • 录屏是全局的,因此从哪个实例开启效果是一样的
  • 录制是分开控制的,可以同时进行录制,但性能消耗大,不建议

4.23. HLS 解密

播放器 SDK 支持 HLS 格式的加密视频,通过初始化设置解密的 VideoID 可实现

/**
 开启/关闭HLS解密功能
 @param isOpen 是否开启
 @param videoID 加密视频的videoID
 需要在prepare之前设置
 */
- (BOOL)openHLSEncryption:(BOOL)isOpen withVideoID:(NSString *_Nonnull)videoID;

4.24. MP4 解密

播放器 SDK 支持 MP4 格式的 DRM 加密视频,SDK 默认开启 MP4 解密功能,支持播放带 DRM 加密的 MP4 视频文件,同时不影响播放正常 MP4.

4.25. DASH

播放器 SDK v1.7.1 及以上支持 DASH 协议,并支持设置 DASH 默认播放码率 及手动切换 DASH 码率,调用示例参考 demo 代码,接口如下:

/**
 在拉取Dash协议的流时,启播之前设置默认启播Bandwidth,用于已知流存在这一Bandwidth时生效,若指定Bandwidth不存在,则不生效。
 需要在prepare之前设置
 @param videoBandwidth 启播视频Bandwidth
 @param audioBandwidth 启播音频Bandwidth
 @return 0 为成功
 */
- (int)setDefaultDashVideoBandwidth:(int) videoBandwidth audioBandwidth:(int) audioBandwidth;

/**
 在拉取Dash协议的流时,启播之前设置Dash Bandwidth列表获取回调
 需要在prepare之后设置
 @param vBlock 视频Bandwidth列表获取回调
 @param aBlock 音频Bandwidth列表获取回调
 @return 0 为成功
 */
- (int)setDashVideoBandwidthBlock:(CNCMediaPlayerDashBandWidthListBlock) vBlock audioBandwidthBlock:(CNCMediaPlayerDashBandWidthListBlock) aBlock;

/**
 在拉取Dash协议的流时,播放过程中切换Dash Bandwidth,从列表中获取的Bandwidth列表指定适合当前网络状况的Bandwidth进行设置,可以切换Dash列表中不同的流
 需要在prepare之后设置
 @param videoBandwidth 切换视频Bandwidth ,值为0,则不切换,保持当前Bandwidth
 @param audioBandwidth 切换音频Bandwidth ,值为0,则不切换,保持当前Bandwidth
 @return 0 为成功
 */
- (int)selectedDashVideoBandwidth:(int) videoBandwidth audioBandwidth:(int) audioBandwidth;

4.26. 预加载

  预加载即通过播放器过程中空闲的带宽资源对用户可能继续观看的视频内容进行预先加载一定的数据量,已达到更快首屏响应速度及快速播放的效果。
  播放器 SDK 从 v1.7.1 开始支持预加载功能。
  预加载功能通过 CNCMediaPlayerPreloadMgr 类实现管理。详细接口可参见文件 CNCMediaPlayerPreloadMgr.h,详细调用代码可参考 demo。这里简单介绍使用步骤

  • 初始化
/**
初始化预加载管理模块
@param cfg 管理模块的配置,包括预加载数最大个数等
@return 管理模块实例
*/
  • 加载
/**
 加载播放
 @param item 播放器参数,包括url、播放器配置、预加载数据量
 @return 状态码,   
        0代表当前要加载的播放器处理队列中,相当于切换到下一个视频进行播放的操作,
        1为当前要加载的播放器不在队列中,先进行预加载,再设为当前播放器,相当于切换到不在预加载队列里的视频
 */
- (int)load:(CNCMediaPlayerPreloadVideoItem *) item;
  • 预加载
/**
 预加载播放器
 预加载成功后,只请求设定的预加载数据量,处于prepared状态,可直接调用play进行播放
 @param item 播放器参数,包括url、播放器配置、预加载数据量
 @return 状态码,0为成功       
 */
- (int)preload:(CNCMediaPlayerPreloadVideoItem *) item;
  • 卸载
/**
 释放播放器
 通过item的url找到预加载队列中的播放器进行shutdown,并从队列中移除
 @param item 播放器参数,包括url、播放器配置、预加载数据量
 @return 状态码
        0为成功
        -1为预加载队列中找不到与item的url匹配的播放器
 */
- (int)unload:(CNCMediaPlayerPreloadVideoItem *) item;
  • 关闭
/**
 关闭预加载管理模块  
 释放预加载队列中所有播放器,清空预加载列表及其他参数
 @return 状态码 0为成功
 */
- (int)shutdown;
   -1为预加载队列中找不到与item的url匹配的播放器

预加载策略通过 CNCMediaPlayerPreloadConfig 进行配置,主要是对个数及每个预加载视频的缓存大小及预加载的配置类型进行控制

  • 预加载个数
    个数取值不小于 0,可依据实际场景设置。

  • 单个预加载的缓存数据量
    预加载数据量为 tcp 读取数据量大小,应不低于某些视频格式的媒体头,如果太少则无法拉取首帧,就达不到首屏秒开的效果。

  • 卸载策略
    卸载策略指的是用户切换播放视频时,当前播放的视频是否要清空的策略,当前卸载策略由 App 层控制,为避免持续高内存 demo 层实现的是清空。调用者可根据具体情况,也可以选择牺牲内存,减少网络请求数据量的方式。Demo层通过宏定义 Release 进行控制。
    开启 Release 宏,切换视频调用 unload 清空缓存重新预加载
    关闭 Release 宏,切换视频调用 pause 不清空当前视频缓存

    #define Release //切换视频时卸载清空,重新预加载
    #ifdef Release
    if (index >= [self.itemArray count]) {
    NSLog(@"unloadIndex = %lu outof bound(%lu)",(unsigned long)index,(unsigned long)[self.itemArray count]);
    return;
    }
    int ret = [self.preloadMgr unload:[self.itemArray objectAtIndex:index]];
    #else
    [self pauseIndex:index];
    #endif
  • 配置类型
      预加载类型参见枚举 PreloadConfigType,当前版本主要用于控制网络状态变化时的管理是由 SDK 控制还是由调用者控制。
      SDK 控制策略为网络从断开变为连通时,仅预加载完成且未处于播放器状态的视频不进行刷新,其他未完成预加载或者当前播放的视频均要刷新。
      调用者如有个性化需求可将 type 设置为 advanced,在 app 层自行监听网络状态变化,自行管理。

    PreloadConfigType 枚举

    typedef NS_ENUM(NSInteger, PreloadConfigType) {
    CNC_PreloadConfigType_Normal = 0,//将断网重连管理交给SDK处理
    CNC_PreloadConfigType_Advanced = 1,//SDK仅管理预加载,网路状态变化由上层自行处理
    };

    App 层进行网络监听,可参见 demo 层代码:

    - (void)addNetworkNotification
    

4.27. 连接超时

播放器 SDK v1.7.2 版本以上支持连接超时设置,通过设置连接超时可在超时 时间达到时得到错误信息回调。
由于播放的 URL 可能存在域名和 IP 两种,注意事项:

  • 带 IP 连接超时,最大超时阈值 75s
  • 带域名需先解析 DNS,DNS 解析超时默认最大阈值 30s
  • 关闭连接超时功能默认超时时间为 15s

设置方法:

//设置连接超时策略 单位毫秒,当连接等待超过预设值时,返回超时错误需要在 prepare 之前设置
@property (nonatomic) NSUInteger cncConnectTimeout;

4.28. DNS 缓存控制

播放器 SDK v1.7.2 版本以上支持DNS缓存控制,设置超时时间,并在超时时间以内对同一个域名不再发起 DNS 请求,而是通过之前的解析IP直接去建连,这样有利于减少重复的DNS请求,加快首屏。

//开启 DNS 缓存超时策略 单位毫秒 设为 0 时清空当前 dns 缓存需要在 prepare 之前设置
@property (nonatomic) NSUInteger cncDNSTimeout;

4.29. Buffer 控制

播放器支持对缓冲 Buffer 进行控制,对 Buffer 进行控制有助于优化缓冲加载 策略,加快首屏,减少卡顿率。

  • 控制策略
    首屏策略:为了使首屏进一步得到优化,在首帧渲染之前,采用尽快播放策略,在此阶段不受 Buffer 设置阈值控制,系统检测缓存大于 100ms 即可播放。
    播放策略:为了降低播放过程中卡顿可适当加大缓存 buffer 的大小,一旦缓存不足,进入缓冲时,缓存再次达到设置阈值时再进行播放。可避免频繁卡顿及频繁缓冲。

  • 控制类型
    缓存时长:可设置缓存阈值为时间单位,缓存达到可播放时长才可进行播放
    缓存大小:可设置缓存阈值为字节单位,缓存达到多少字节才可进行播放。

    //直播时的延时追赶时间 本地缓存cacheDuration超过maxCacheTime后,播放最新视频信息,单位是毫秒
    @property (nonatomic) NSTimeInterval    maxCacheTime;
    //缓冲时长 最低播放时长,即至少加载minBufferTime可进行播放,单位是毫秒
    @property (nonatomic) NSTimeInterval minBufferTime;

4.30. 兼容模式

  播放器 SDK 支持对 iOS 音频系统的兼容模式。
  开启兼容模式,其他播放器在后台时能够在启用播放器时不会暂停,会同时播放,但是此时后台播放打开时,正在后台播放的播放器可能在受到来电或者 Siri 干扰后,能正常重启播放
  关闭兼容模式:其他播放器在后台时能够在启用播放器时使其他 app 的播放器暂停,但是此时后台播放打开时,正在后台播放的播放器可能在受到来电或者 Siri 干扰后,无法重启播放。
  设置播放器实例的 mixOtherPlayer 属性,接口如下:

/**
 *  系统音频兼容
 *  是否兼容其他后台播放器,如其他音乐播放器等
 *  NO:其他播放器在后台时能够在启用播放器时使其他app的播放器暂停,但是此时后台播放打开时,正在后台播放的播放器可能在受到来电或者Siri干扰后,无法重启播放。
 *  YES:其他播放器在后台时能够在启用播放器时不会暂停,会同时播放,但是此时后台播放打开时,正在后台播放的播放器可能在受到来电或者Siri干扰后,能正常重启播放。
 */
@property (nonatomic) BOOL  mixOtherPlayer;

4.31. CC 字幕

播放器支持字幕格式有两种:

  • 内置字幕:流自带的,例如 mp4 格式的 movtext 编码的字幕流。
  • 外挂字幕:指定 URL 或者本地路径的字幕,格式一般为 srt:
1
00:00:00,000 --> 00:00:05,000
字幕第一行

2
00:00:3,000 --> 00:00:20,000
字幕第二行

4.31.1. 字幕显示与隐藏

字幕的显示与隐藏通过调用如下接口实现。

/**
 cc字幕选项设置,prepared之后生效
 @param opt
    KEY:CNCMediaPlayerOptionSubtitlePath NSDictionary {@"en":@"……1.mp4.en.srt"}
    KEY:open @"0":关闭 ,@"1":开启
    KEY:from @"0":使用内置字幕 @"1":使用外挂字幕
    KEY:key  传入多字幕键值对的key值,匹配key值,存在则切换到相应字幕
 */
- (void)cncClosedCaptionOption:(NSDictionary *) opt;

在 opt 中传入 1 或者 0 控制显示与隐藏

[_player cncClosedCaptionOption:@{@"open":sch.on ? @"1" : @"0"}];

4.31.2. 内外置字幕

播放器可以指定 key:from 来指定显示内置或者外挂字幕。当内外置字幕同时存在时可指定显示内置或者外挂字幕。
在 opt 中传入 1 或者 0 控制显示与隐藏

// KEY:from @"0":使用内置字幕 @"1":使用外挂字幕
[_player cncClosedCaptionOption:@{@"from": @"1"}];

4.31.3. 多字幕实时切换

播放器支持对同一个视频源传入多个字幕的功能,当需要同时指定多个字幕(例如多语言字幕)时,可指定key:CNCMediaPlayerOptionSubtitlePath 进行设置。

// KEY:from @"0":使用内置字幕 @"1":使用外挂字幕
[_player cncClosedCaptionOption:@{ CNCMediaPlayerOptionSubtitlePath: @{@"en",@"/var/……/EN.SRT",@"cn",@"/var/……/CN.SRT"}}];

当需要切换时调用 key:key 进行切换

// KEY:key  传入多字幕键值对的key值,匹配key值,存在则切换到相应字幕
// KEY:key 传入的"en",@"cn"
[_player cncClosedCaptionOption:@{@"key": @"en"}];

4.31.4. 字幕颜色设置

播放器支持对字幕颜色进行调整,

// KEY:color @"0":使用内置字幕 @"1":使用外挂字幕
[_player cncClosedCaptionOption:@{@"color": [UIColor WhiteColor]}];

4.32. Fairplay DRM

播放器 SDK 支持 Fairplay DRM 资源的播放,通过初始化 CNCFairPlayStreamPlayer 来获得 DRM 播放器实例,具体方法如下:

//CertUrl 为请求证书地址
self.player = [[CNCFairPlayStreamPlayer alloc] initWithContentURLString:self.resourceUrlStr option:@{CertUrl:self.certUrlStr}];
[self.player prepareToPlay];

4.33. 其他功能

4.33.1. 分辨率重建

分辨率重建(非必须,需集成基于帝视的第三方 framework 支持)
播放器 SDK 支持集成第三方分辨率重建 framework。App 必须同时集成
✓ 播放器 SDK
✓ IVToolKit.framework
✓ CNCMediaPlayerLibMng.framework。
集成步骤

[option setObject:versionFullIVKey forKey:CNCMediaPlayerOptionIVDevKey];
[option setObject:@"1" forKey:CNCMediaPlayerOptionIsOpenIV];
self.player = [[CNCMediaPlayerController alloc] initWithContentURL:self.URL option:option];

接口说明:

/**
 超分辨率-IV API
 超分辨率显示模式枚举
 */
typedef NS_ENUM(NSInteger, CNCMediaPlayerLibIVDisplayMode) {
    CNCMediaPlayerLibIVDisplayMode_LR,//渲染画面显示原始视频
    CNCMediaPlayerLibIVDisplayMode_LRSR,//渲染画面显示对比视频,根据percent比例调整显示比例
    CNCMediaPlayerLibIVDisplayMode_SR//渲染画面显示超分视频
};
/**
 超分辨率-IV API
 超分辨率部分参数数据回调block
 @param detect_fps 当前渲染实时帧率
 @param detect_value 探测当前视频渲染320*180p的分辨率所花的时间 单位ms
 @param output_w 超分处理后输出的分辨率宽
 @param output_h 超分处理后输出的分辨率高
 */
typedef void (^CNCMediaPlayerLibIVStateInfoBlock)(float detect_fps, double detect_value, int output_w, int output_h);

/**
 超分辨率-IV API
 设置超分辨率显示模式 详见枚举:CNCMediaPlayerLibIVDisplayMode
 @param mode 参考CNCMediaPlayerLibIVDisplayMode
 @return 是否调用成功
 */
- (BOOL)cncMediaPlayerLibMngSetDisplayMode:(CNCMediaPlayerLibIVDisplayMode)mode;


/**
 超分辨率-IV API

 @param block 设置超分辨率附加信息回调,传入相应block可以获取超分辨率附加信息回调 详见CNCMediaPlayerLibIVStateInfoBlock
 @return 是否调用成功
 */
- (BOOL)cncMediaPlayerLibMngSetExtraBlock:(CNCMediaPlayerLibIVStateInfoBlock _Nullable )block;


/**
 超分辨率-IV API
 设置超分模型

 @param modelName 设置模型名称
 @param error 错误信息
 */
- (void)cncMediaPlayerLibMngLoadIVModelName:(NSString *_Nonnull)modelName error:(NSError *_Nullable*_Nullable)error;

;

第五章 接口说明

5.1. 接口说明

参见文档《iOS 播放器 SDK_API 文档》index.html

5.2. 通知监听

/// 发现流信息通知
CNC_EXTERN NSString * const CNCMediaPlayerFindStreamInfoNotification;

/// 准备好播放
CNC_EXTERN NSString * const CNCMediaPlayerLoadDidPrepareNotification;

/// 播放状态改变
CNC_EXTERN NSString * const CNCMediaPlayerPlayStateDidChangeNotification;

/// 加载状态改变
CNC_EXTERN NSString * const CNCMediaPlayerLoadStateDidChangeNotification;

/// 播放结束
CNC_EXTERN NSString * const CNCMediaPlayerPlayDidFinishNotification;

/// 视频比例改变
CNC_EXTERN NSString * const CNCMediaPlayerScalingModeDidChangeNotification;

/// 视频分辨率改变
CNC_EXTERN NSString * const CNCMediaPlayerResolutionChangedNotification;

/// 开启硬解
CNC_EXTERN NSString * const CNCMediaPlayerVideoDecoderOpenNotification;

/// 首帧视频渲染
CNC_EXTERN NSString * const CNCMediaPlayerFirstVideoFrameRenderedNotification;

/// 首帧音频渲染
CNC_EXTERN NSString * const CNCMediaPlayerFirstAudioFrameRenderedNotification;

/// seek成功并结束
CNC_EXTERN NSString * const CNCMediaPlayerDidSeekCompleteNotification;

/// 鉴权成功
CNC_EXTERN NSString * const CNCMediaPlayerSDKInitDidFinishNotification;

/// 播放器状态通知
CNC_EXTERN NSString * const CNCMediaPlayerStatusCodeNotification;

/// 播放器释放完成
CNC_EXTERN NSString * const CNCMediaPlayerDidShutdown;

/// HTTP协议视频请求返回值通知
CNC_EXTERN NSString * const CNCMediaPlayerHTTPRCodeNotification;

/// 录制状态通知
CNC_EXTERN NSString * const CNCMediaPlayerRecordingStatusCodeNotification;

/// 录屏状态通知
CNC_EXTERN NSString * const CNCMediaPlayerScreenRecordingStatusCodeNotification;

///发现流数据变更
CNC_EXTERN NSString * const CNCMediaPlayerFindNewStream;

///dash video bandwidth发生改变时通知
CNC_EXTERN NSString * const CNCMediaPlayerDashVideoChanged;

///dash audio bandwidth发生改变时通知
CNC_EXTERN NSString * const CNCMediaPlayerDashAudioChanged;

///dash 初始化bandwidth时通知
CNC_EXTERN NSString * const CNCMediaPlayerDashInitBandwidth;

5.3. 状态码说明

以下为代码中常用错误码定义,其余枚举类型详见 CNCMediaPlayerComDef.h 文件

工信部网络安全大检查来袭,你准备好了吗?