开发指南

服务端 API 文档

诚邀爱技术、爱分享的你,成为文档内容共建者> HOT

准备工作

  1. 开通 云点播 相关服务,未注册用户可注册账号 试用
  2. 下载 Xcode,如您已下载可略过该步骤,您可以进入 App Store 下载安装。
  3. 下载 Cocoapods,如您已下载可略过该步骤,您可以进入 Cocoapods官网 按照指引进行安装。

通过本文您可以学会

  • 如何集成腾讯云视立方 iOS 播放器 SDK
  • 如何使用播放器 SDK 进行点播播放
  • 如何使用播放器 SDK 底层能力实现更多功能

SDK 集成

步骤1:集成 SDK 开发包

下载和集成 SDK 开发包,请参见同目录下的 SDK 集成指引

步骤2:配置 License 授权

若您已获得相关 License 授权,需在 腾讯云视立方控制台 获取 License URL 和 License Key:
image
若您暂未获得 License 授权,需先参见 视频播放 License 获取相关授权。

获取到 License 信息后,在调用 SDK 的相关接口前,通过下面的接口初始化 License,建议在 - [AppDelegate application:didFinishLaunchingWithOptions:] 中进行如下设置:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    NSString * const licenceURL = @"<获取到的 licenseUrl>";
    NSString * const licenceKey = @"<获取到的 key>";

    //TXLiveBase 位于 "TXLiveBase.h" 头文件中
    [TXLiveBase setLicenceURL:licenceURL key:licenceKey]; 
    NSLog(@"SDK Version = %@", [TXLiveBase getSDKVersionStr]);
}

步骤3:创建 Player

视频云 SDK 中的 TXVodPlayer 模块负责实现点播播放功能。

TXVodPlayer *_txVodPlayer = [[TXVodPlayer alloc] init];
[_txVodPlayer setupVideoWidget:_myView insertIndex:0]

步骤4:渲染 View

接下来我们要给播放器的视频画面找个地方来显示,iOS 系统中使用 view 作为基本的界面渲染单位,所以您只需要准备一个 view 并调整好布局就可以了。

[_txVodPlayer setupVideoWidget:_myView insertIndex:0]

内部原理上讲,播放器并不是直接把画面渲染到您提供的 view(示例代码中的 _myView)上,而是在这个 view 之上创建一个用于 OpenGL 渲染的子视图(subView)。

如果您要调整渲染画面的大小,只需要调整您所常见的 view 的大小和位置即可,SDK 会让视频画面跟着您的 view 的大小和位置进行实时的调整。

如何做动画
针对 view 做动画是比较自由的,不过请注意此处动画所修改的目标属性应该是 transform 属性而不是 frame 属性。

[UIView animateWithDuration:0.5 animations:^{
     _myView.transform = CGAffineTransformMakeScale(0.3, 0.3); // 缩小1/3
 }];

步骤5:启动播放

TXVodPlayer 支持两种播放模式,您可以根据需要自行选择:

TXVodPlayer 内部会自动识别播放协议,您只需要将您的播放 URL 传给 startPlay 函数即可。

// 播放 URL 视频资源
NSString* url = @"http://1252463788.vod2.myqcloud.com/xxxxx/v.f20.mp4";
[_txVodPlayer startVodPlay:url];

// 播放沙盒本地视频资源
// 获取 Documents 路径
NSString *documentPath = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject];
// 获取本地视频路径
NSString *videoPath = [NSString stringWithFormat:@"%@/video1.m3u8",documentPath];
[_txVodPlayer startVodPlay:videoPath];

步骤6:结束播放

结束播放时,如果要退出当前的 UI 界面,要记得用 removeVideoWidget 销毁 view 控件,否则会产生内存泄露或闪屏问题。

// 停止播放
[_txVodPlayer stopPlay];
[_txVodPlayer removeVideoWidget]; // 记得销毁 view 控件

基础功能使用

1. 播放控制

开始播放

// 开始播放
[_txVodPlayer startVodPlay:url];

暂停播放

// 暂停播放
[_txVodPlayer pause];

恢复播放

// 恢复播放
[_txVodPlayer resume];

结束播放

// 结束播放
[_txVodPlayer stopPlay];

调整进度(Seek)

当用户拖拽进度条时,可调用 seek 从指定位置开始播放,播放器 SDK 支持精准 seek。

int time = 600; // int 类型时,单位为 秒
// 调整进度
[_txVodPlayer seek:time];

从指定时间开始播放

首次调用 startVodPlay之前,支持从指定时间开始播放。

float startTimeInSecond = 60; // 单位:秒
[_txVodPlayer setStartTime:startTimeInSecond];  // 设置开始播放时间
[_txVodPlayer startVodPlay:url];

2. 画面调整

  • view:大小和位置
    如需修改画面的大小及位置,直接调整 setupVideoWidget 的参数 view 的大小和位置,SDK 会让视频画面跟着您的 view 的大小和位置进行实时的调整。
  • setRenderMode:铺满或适应
    可选值 含义
    RENDER_MODE_FILL_SCREEN 将图像等比例铺满整个屏幕,多余部分裁剪掉,此模式下画面不会留黑边,但可能因为部分区域被裁剪而显示不全。
    RENDER_MODE_FILL_EDGE 将图像等比例缩放,适配最长边,缩放后的宽和高都不会超过显示区域,居中显示,画面可能会留有黑边。
  • setRenderRotation:画面旋转
    可选值 含义
    HOME_ORIENTATION_RIGHT home 在右边
    HOME_ORIENTATION_DOWN home 在下面
    HOME_ORIENTATION_LEFT home 在左边
    HOME_ORIENTATION_UP home 在上面

3. 变速播放

点播播放器支持变速播放,通过接口 setRate 设置点播播放速率来完成,支持快速与慢速播放,如 0.5X、1.0X、1.2X、2X 等。

// 设置1.2倍速播放
[_txVodPlayer setRate:1.2]; 
// 开始播放
[_txVodPlayer startVodPlay:url];

4. 循环播放

// 设置循环播放
[_txVodPlayer setLoop:true];
// 获取当前循环播放状态
[_txVodPlayer loop];

5. 静音设置

// 设置静音,true 表示开启静音, false 表示关闭静音
[_txVodPlayer setMute:true];

6. 屏幕截图

通过调用 snapshot 您可以截取当前视频为一帧画面,此功能只会截取当前直播流的视频画面,如果您需要截取当前的整个 UI 界面,请调用 iOS 的系统 API 来实现。

7. 贴片广告

播放器 SDK 支持在界面添加图片贴片,用于广告宣传等。实现方式如下:

  • autoPlay 为 NO,此时播放器会正常加载,但视频不会立刻开始播放。
  • 在播放器加载出来后、视频尚未开始时,即可在播放器界面查看图片贴片广告。
  • 待达到广告展示结束条件时,使用 resume 接口启动视频播放。

8. HTTP-REF

TXVodPlayConfig 中的 headers 可以用来设置 HTTP 请求头,例如常用的防止 URL 被到处拷贝的 Referer 字段(腾讯云可以提供更加安全的签名防盗链方案),以及用于验证客户端身份信息的 Cookie 字段。

NSMutableDictionary<NSString *, NSString *> *httpHeader = [[NSMutableDictionary alloc] init];
[httpHeader setObject:@"${Referer Content}" forKey:@"Referer"];
[_config setHeaders:httpHeader];
[_txVodPlayer setConfig:_config];

9. 硬件加速

对于蓝光级别(1080p)的画质,简单采用软件解码的方式很难获得较为流畅的播放体验,所以如果您的场景是以游戏直播为主,一般都推荐开启硬件加速。

软解和硬解的切换需要在切换之前先 stopPlay,切换之后再 startVodPlay,否则会产生比较严重的花屏问题。

[_txVodPlayer stopPlay];
_txVodPlayer.enableHWAcceleration = YES;
[_txVodPlayer startVodPlay:_flvUrl type:_type];

10. 清晰度设置

SDK 支持 hls 的多码率格式,方便用户切换不同码率的播放流。在收到 PLAY_EVT_PLAY_BEGIN 事件后,可以通过下面方法获取多码率数组。

NSArray *bitrates = [_txVodPlayer supportedBitrates]; //获取多码率数组
在播放过程中,可以随时通过 -[TXVodPlayer setBitrateIndex:]切换码率。切换过程中,会重新拉取另一条流的数据,因此会有稍许卡顿。SDK 针对腾讯云的多码率文件做过优化,可以做到切换无卡顿。

11. 码流自适应

SDK 支持 HLS 的多码流自适应,开启相关能力后播放器能够根据当前带宽,动态选择最合适的码率播放。在收到 PLAY_EVT_PLAY_BEGIN 事件后,可以通过下面方法开启码流自适应:

[_txVodPlayer setBitrateIndex:-1]; //index 参数传入-1
在播放过程中,可以随时通过 -[TXVodPlayer setBitrateIndex:] 切换其它码率,切换后码流自适应也随之关闭。

12. 开启平滑切换码率

在启动播放前,通过开启平滑切换码率,在播放过程中切换码率,可以达到无缝平滑切换不同清晰度。对比关闭平滑切换码率,切换过程比较耗时、体验更好,可以根据需求进行设置。

TXVodPlayConfig *_config = [[TXVodPlayConfig alloc]init];
// 设为 YES,在 IDR 对齐时可平滑切换码率, 设为 NO 时,可提高多码率地址打开速度
[_config setSmoothSwitchBitrate:YES];
[_txVodPlayer setConfig:_config];

13.播放进度监听

点播播放中的进度信息分为2种:加载进度播放进度,SDK 目前是以事件通知的方式将这两个进度实时通知出来的。更多事件通知内容参见 事件监听

-(void) onPlayEvent:(TXVodPlayer *)player event:(int)EvtID withParam:(NSDictionary*)param {
    if (EvtID == PLAY_EVT_PLAY_PROGRESS) {
            // 加载进度, 单位是秒, 小数部分为毫秒
            float playable = [param[EVT_PLAYABLE_DURATION] floatValue];
                [_loadProgressBar setValue:playable];

            // 播放进度, 单位是秒, 小数部分为毫秒
            float progress = [param[EVT_PLAY_PROGRESS] floatValue];
                [_seekProgressBar setValue:progress];

            // 视频总长, 单位是秒, 小数部分为毫秒
            float duration = [param[EVT_PLAY_DURATION] floatValue];
            // 可以用于设置时长显示等等
    }
}

14. 播放网速监听

通过 事件监听 方式,可以在视频播放卡顿时在显示当前网速。

  • 通过 onNetStatusNET_SPEED 获取当前网速。具体使用方法见 状态反馈(onNetStatus)
  • 监听到 PLAY_EVT_PLAY_LOADING 事件后,显示当前网速。
  • 收到 PLAY_EVT_VOD_LOADING_END 事件后,对显示当前网速的 view 进行隐藏。

15. 获取视频分辨率

播放器 SDK 通过 URL 字符串播放视频,URL 中本身不包含视频信息。为获取相关信息,需要通过访问云端服务器加载到相关视频信息,因此 SDK 只能以事件通知的方式将视频信息发送到您的应用程序中,更多内容参见 事件监听
分辨率信息

通过 onNetStatusVIDEO_WIDTHVIDEO_HEIGHT 获取视频的宽和高。具体使用方法见 状态反馈(onNetStatus)

16. 播放缓冲大小

在视频正常播放时,控制提前从网络缓冲的最大数据大小。如果不配置,则走播放器默认缓冲策略,保证流畅播放。

TXVodPlayConfig *_config = [[TXVodPlayConfig alloc]init];
[_config setMaxBufferSize:10];  // 播放时最大缓冲大小。单位:MB
[_txVodPlayer setConfig:_config];  // 把 config 传给 _txVodPlayer

17. 视频本地缓存

在短视频播放场景中,视频文件的本地缓存是很刚需的一个特性,对于普通用户而言,一个已经看过的视频再次观看时,不应该再消耗一次流量。

  • 格式支持:SDK 支持 HLS(m3u8)和 MP4 两种常见点播格式的缓存功能。
  • 开启时机:SDK 并不默认开启缓存功能,对于用户回看率不高的场景,也并不推荐您开启此功能。
  • 开启方法:开启此功能需要配置两个参数:本地缓存目录及缓存大小。
    //设置播放引擎的全局缓存目录
    NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
    NSString *documentsDirectory = [paths objectAtIndex:0];
    NSString *preloadDataPath = [documentsDirectory stringByAppendingPathComponent:@"/preload"];
    if (![[NSFileManager defaultManager] fileExistsAtPath:preloadDataPath]) {
         [[NSFileManager defaultManager] createDirectoryAtPath:preloadDataPath
                                   withIntermediateDirectories:NO
                                                    attributes:nil
                                                         error:&error];
    [TXPlayerGlobalSetting setCacheFolderPath:preloadDataPath];
    //设置播放引擎缓存大小
    [TXPlayerGlobalSetting setMaxCacheSize:200];
    // 开始播放
    [_txVodPlayer startVodPlay:url];                         
说明:

旧版本通过 TXVodPlayConfig#setMaxCacheItems 接口配置已经废弃,不推荐使用。

高级功能使用

1. 视频预播放

步骤1:视频预播放使用

在短视频播放场景中,预加载功能对于流畅的观看体验很有帮助:在观看当前视频的同时,在后台加载即将要播放的下一个视频 URL,这样一来,当用户真正切换到下一个视频时,已经不需要从头开始加载了,而是可以做到立刻播放。
预播放视频会有很好的秒开效果,但有一定的性能开销,如果业务同时有较多的视频预加载需求,建议结合 视频预下载 一起使用。
这就是视频播放中无缝切换的背后技术支撑,您可以使用 TXVodPlayer 中的 isAutoPlay 开关来实现这个功能,具体做法如下:

// 播放视频 A: 如果将 isAutoPlay 设置为 YES, 那么 startVodPlay调用会立刻开始视频的加载和播放
NSString* url_A = @"http://1252463788.vod2.myqcloud.com/xxxxx/v.f10.mp4";
_player_A.isAutoPlay = YES;
[_player_A startVodPlay:url_A];

// 在播放视频 A 的同时,预加载视频 B,做法是将 isAutoPlay 设置为 NO
NSString* url_B = @"http://1252463788.vod2.myqcloud.com/xxxxx/v.f20.mp4";
_player_B.isAutoPlay = NO;
[_player_B startVodPlay:url_B];
等到视频 A 播放结束,自动(或者用户手动切换到)视频 B 时,调用 resume 函数即可实现立刻播放。

注意:

设置了 autoPlay 为 false 之后,调用 resume 之前需要保证视频 B 已准备完成,即需要在监听到视频 B 的 PLAY_EVT_VOD_PLAY_PREPARED (2013 ,播放器已准备完成,可以播放)事件后调用。

-(void) onPlayEvent:(TXVodPlayer *)player event:(int)EvtID withParam:(NSDictionary*)param
{
    // 在视频 A 播放结束的时候,直接启动视频 B 的播放,可以做到无缝切换
    if (EvtID == PLAY_EVT_PLAY_END) {
            [_player_A stopPlay];
            [_player_B setupVideoWidget:mVideoContainer insertIndex:0];
            [_player_B resume];
        }
}

步骤2:视频预播放缓冲配置

  • 设置较大的缓冲可以更好的应对网络的波动,达到流畅播放的目的。
  • 设置较小的缓冲可以帮助节省流量消耗。
预播放缓冲大小

此接口针对预加载场景(即在视频启播前,且设置 player 的 AutoPlay 为 false),用于控制启播前阶段的最大缓冲大小。

TXVodPlayConfig *_config = [[TXVodPlayConfig alloc]init];
[_config setMaxPreloadSize:(2)];;  // 预播放最大缓冲大小。单位:MB, 根据业务情况设置去节省流量
[_txVodPlayer setConfig:_config];  // 把config 传给 _txVodPlayer

播放缓冲大小

在视频正常播放时,控制提前从网络缓冲的最大数据大小。如果不配置,则走播放器默认缓冲策略,保证流畅播放。

TXVodPlayConfig *_config = [[TXVodPlayConfig alloc]init];
[_config setMaxBufferSize:10];  // 播放时最大缓冲大小。单位:MB
[_txVodPlayer setConfig:_config];  // 把 config 传给 _txVodPlayer

2. 视频预下载

不需要创建播放器实例,预先下载视频部分内容,使用播放器时,可以加快视频启播速度,提供更好的播放体验。
在使用播放服务前,请确保先设置好 视频缓存

说明:

  • TXPlayerGlobalSetting 是全局缓存设置接口,原有 TXVodConfig 的缓存配置接口废弃。
  • 全局缓存目录和大小设置的优先级高于播放器 TXVodConfig 配置的缓存设置。

使用示例:

//设置播放引擎的全局缓存目录
NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
NSString *documentsDirectory = [paths objectAtIndex:0];
NSString *preloadDataPath = [documentsDirectory stringByAppendingPathComponent:@"/preload"];
if (![[NSFileManager defaultManager] fileExistsAtPath:preloadDataPath]) {
     [[NSFileManager defaultManager] createDirectoryAtPath:preloadDataPath 
                                                       withIntermediateDirectories:NO 
                                                                                          attributes:nil 
                                                                                                   error:&error]; //Create folder
}
[TXPlayerGlobalSetting setCacheFolderPath:preloadDataPath];

//设置播放引擎缓存大小
[TXPlayerGlobalSetting setMaxCacheSize:200];
NSString *m3u8url = "http://****";
int taskID = [[TXVodPreloadManager sharedManager] startPreload:m3u8url 
                                                                                                      preloadSize:10 
                                                                                      preferredResolution:1920*1080 
                                                                                                             delegate:self];


//取消预下载
[[TXVodPreloadManager sharedManager] stopPreload:taskID];

3. 视频下载

视频下载支持用户在有网络的条件下下载视频,随后在无网络的环境下观看。同时播放器 SDK 提供本地加密能力,下载后的本地视频仍为加密状态,仅可通过指定播放器对视频进行解密播放,可有效防止下载视频的非法传播,保护视频安全。
由于 HLS 流媒体无法直接保存到本地,因此也无法通过播放本地文件的方式实现 HLS 离线播放,对于该问题,您可以通过基于 TXVodDownloadManager 的视频下载方案实现 HLS 的离线播放。

注意:

  • TXVodDownloadManager 暂不支持缓存 MP4 。
  • 播放器 SDK 已支持 MP4 和 FLV 格式的本地文件播放。

步骤1:准备工作

TXVodDownloadManager 被设计为单例,因此您不能创建多个下载对象。用法如下:

TXVodDownloadManager *downloader = [TXVodDownloadManager shareInstance];
// 设置下载目录,优先以 ‘ TXPlayerGlobalSetting #setCacheFolderPath’ 设置为准
[downloader setDownloadPath:"<指定您的下载目录>"];

步骤2:开始下载

开始下载有两种方式:fileid 和 URL。

fileid 下载至少需要传入 appId 和 fileId,userName 不传入具体值时,默认为 “default”。注意:加密视频只能通过 Fileid 下载。

TXVodDownloadDataSource *source = [[TXVodDownloadDataSource alloc] init];    
source.appId = 1252463788;
source.fileId = @"4564972819220421305";
// // psign 即播放器签名,签名介绍和生成方式参见链接:https://cloud.tencent.com/document/product/266/42436
source.pSign = @"xxxxxxxxxx";

// 指定下载清晰度
// 可用枚举值有:原画: TXVodQualityOD, 流畅: TXVodQualityFLU, 标清: TXVodQualitySD, 高清: TXVodQualityHD, 全高清: TXVodQualityFHD, 2K: TXVodQuality2K, 4K:TXVodQuality4K
source.quality = TXVodQualityHD;  // 高清

// ** 注意如果是使用旧的 v2 协议下载,请通过 TXVodDownloadDataSource 中的 auth 属性来设置 appId 和 fileId 这些参数 **
// source.auth = auth;  ** 默认无需设置 **

[downloader startDownload:dataSource];

步骤3:任务信息

在接收任务信息前,需要先设置回调 delegate。

downloader.delegate = self;
可能收到的任务回调有:

回调信息含义
-[TXVodDownloadDelegate onDownloadStart:] 任务开始,表示 SDK 已经开始下载。
-[TXVodDownloadDelegate onDownloadProgress:] 任务进度,下载过程中,SDK 会频繁回调此接口,您可以在这里更新进度显示。
-[TXVodDownloadDelegate onDownloadStop:] 任务停止,当您调用是 stopDownload 停止下载,收到此消息表示停止成功。
-[TXVodDownloadDelegate onDownloadFinish:] 下载完成,收到此回调表示已全部下载。此时下载文件可以给 TXVodPlayer 播放。
-[TXVodDownloadDelegate onDownloadError:errorMsg:] 下载错误,下载过程中遇到网络断开会回调此接口,同时下载任务停止。所有错误码请参考 TXDownloadError

由于 downloader 可以同时下载多个任务,所以回调接口里带上了 TXVodDownloadMediaInfo 对象,您可以访问 URL 或 dataSource 判断下载源,同时还可以获取到下载进度、文件大小等信息。

步骤4:中断下载

停止下载请调用 -[TXVodDownloadManager stopDownload:] 方法,参数为 -[TXVodDownloadManager sartDownloadUrl:] 返回的对象。SDK 支持断点续传,当下载目录没有发生改变时,下次下载同一个文件时会从上次停止的地方重新开始。

步骤5:管理下载

  1. 获取所有用户账户的下载列表信息, 也可获取指定用户账户的下载列表信息。

    NSArray<TXVodDownloadMediaInfo *> *array = [[[TXVodDownloadManager shareInstance] getDownloadMediaInfoList] mutableCopy];
    // 获取默认 “default” 用户的下载列表
    for (TXVodDownloadMediaInfo *info in array) {
        if ([info.userName isEqualToString:@"default"]) {
            // 保存 “default” 用户的下载列表
        }
    }

  2. 获取 FileId 或 URL 相关的下载信息:
    2.1 通过接口 -[TXVodDownloadManager getDownloadMediaInfo:] 获取某个 Fileid 相关下载信息,包括当前下载状态,获取当前下载进度,判断是否下载完成等,需要传入 AppID、 Fileid 和 qualityId。

    // 获取某个 fileId 相关下载信息
    TXVodDownloadMediaInfo *sourceMediaInfo = [[TXVodDownloadMediaInfo alloc] init];
    TXVodDownloadDataSource *dataSource = [[TXVodDownloadDataSource alloc] init];
    dataSource.appId = 1252463788;
    dataSource.fileId = @"4564972819220421305";
    dataSource.pSign = @"psignxxxx";
    dataSource.quality = TXVodQualityHD;
    sourceMediaInfo.dataSource = dataSource;
    TXVodDownloadMediaInfo *downlaodMediaInfo =  [[TXVodDownloadManager shareInstance] getDownloadMediaInfo:sourceMediaInfo];
    
    // 获取下载文件总大小,单位:Byte,只针对 fileid 下载源有效。
    // 备注:总大小是指上传到腾讯云点播控制台的原始文件的大小,转自适应码流后的子流大小,暂时无法获取。
    downlaodMediaInfo.size; //  获取下载文件总大小
    downlaodMediaInfo.duration;   // 获取总时长
    downlaodMediaInfo.playableDuration; // 获取已下载的可播放时长
    downlaodMediaInfo.progress;   // 获取下载进度
    downlaodMediaInfo.playPath;   // 获取离线播放路径,传给播放器即可离线播放
    downlaodMediaInfo.downloadState;  // 获取下载状态,具体参考 STATE_xxx 常量
    [downlaodMediaInfo isDownloadFinished];  // 返回 YES 表示下载完成

    2.2 获取某个 URL 相关下载信息,需要传入 URL 信息即可。

    // 获取某个 fileId 相关下载信息
    TXVodDownloadMediaInfo *sourceMediaInfo = [[TXVodDownloadMediaInfo alloc] init];
    mediaInfo.url = @"videoURL";
    TXVodDownloadMediaInfo *downlaodMediaInfo =  [[TXVodDownloadManager shareInstance] getDownloadMediaInfo:sourceMediaInfo];

  3. 删除下载信息和相关文件:
    如果您不需要重新下载,请调用 -[TXVodDownloadManager deleteDownloadFile:] 方法删除文件,以释放存储空间。

步骤6:下载后离线播放

下载后的视频支持无网络的情况下进行播放,无需进行联网。下载完成后,即可进行播放。

NSArray<TXVodDownloadMediaInfo *> *mediaInfoList = [[TXVodDownloadManager shareInstance] getDownloadMediaInfoList];
TXVodDownloadMediaInfo *mediaInfo = [mediaInfoList firstObject]; // 根据情况找到当前的 media 对象
if (mediaInfo.downloadState == TXVodDownloadMediaInfoStateFinish) { // 判断是否下载完成
    [self.player startVodPlay:mediaInfo.playPath];
}

注意:

离线下载播放时,一定要通过获取下载列表并通过下载列表视频对象 TXVodDownloadMediaInfoPlayPath 进行播放,切勿直接保存 PlayPath 对象。

4. 加密播放

视频加密方案主要用于在线教育等需要对视频版权进行保护的场景。如果要对您的视频资源进行加密保护,就不仅需要在播放器上做改造,还需要对视频源本身进行加密转码,亦需要您的后台和终端研发工程师都参与其中。在 视频加密解决方案 中您会了解到全部细节内容。
在腾讯云控制台提取到 appId, 加密视频的 fileId 和 psign 后,可以通过下面的方式进行播放:

TXPlayerAuthParams *p = [TXPlayerAuthParams new];
p.appId = 1252463788; // 腾讯云账户的 appId
p.fileId = @"4564972819220421305"; // 视频的 fileId
// psign 即播放器签名,签名介绍和生成方式参见链接:https://cloud.tencent.com/document/product/266/42436
p.sign = @"psignxxxxx"; // 播放器签名
[_txVodPlayer startVodPlayWithParams:p];

5. 播放器配置

在调用 statPlay 之前可以通过 setConfig 对播放器进行参数配置,例如:设置播放器连接超时时间、设置进度回调间隔、设置缓存文件个数等配置,TXVodPlayConfig 支持配置的详细参数请单击 基础配置接口 了解。使用示例:

TXVodPlayConfig *_config = [[TXVodPlayConfig alloc]init];
[_config setEnableAccurateSeek:true];  // 设置是否精确 seek,默认 true
[_config setMaxCacheItems:5];  // 设置缓存文件个数为5
[_config setProgressInterval:200];  // 设置进度回调间隔,单位毫秒
[_config setMaxBufferSize:50];  // 最大预加载大小,单位 MB
[_txVodPlayer setConfig:_config];  // 把 config 传给 _txVodPlayer

启播时指定分辨率

播放 HLS 的多码率视频源,如果您提前知道视频流的分辨率信息,可以在启播前优先指定播放的视频分辨率。 播放器会查找小于或等于偏好分辨率的流进行启播,启播后没有必要再通过 setBitrateIndex 切换到需要的码流。

TXVodPlayConfig *_config = [[TXVodPlayConfig alloc]init];
// 传入参数为视频宽和高的乘积(宽 *  高),可以自定义值传入
[_config setPreferredResolution:720*1280];
[_txVodPlayer setConfig:_config];  // 把 config 传给 _txVodPlayer

设置播放进度回调时间间隔

TXVodPlayConfig *_config = [[TXVodPlayConfig alloc]init];
[_config setProgressInterval:200];  // 设置进度回调间隔,单位毫秒
[_txVodPlayer setConfig:_config];  // 把 config 传给 _txVodPlayer

6. HttpDNS 解析服务

移动解析(HTTPDNS)基于 HTTP 协议向 DNS 服务器发送域名解析请求,替代了基于 DNS 协议向运营商 Local DNS 发起解析请求的传统方式,可避免 Local DNS 造成域名劫持和跨网访问问题,解决移动互联网服务中域名解析异常带来的视频播放失败困扰。

注意:

HttpDNS 解析服务从 10.9 版本开始支持。

  1. 开通 HTTPDNS 解析服务
    您可以选择腾讯云或其它云提供商,开通 HTTPDNS 解析服务,确保开通成功后, 再集成到播放 SDK。

  2. 在播放 SDK 接入 HTTPDNS 解析服务
    下面以接入 腾讯云 HTTPDNS 为例子,展示如何在播放器 SDK 接入:

// 步骤1: 打开 HttpDNS 解析开关[TXLiveBase enableCustomHttpDNS:YES];
// 步骤2: 实现 HttpDNS 解析代理:TXLiveBaseDelegate#onCustomHttpDNS
- (void)onCustomHttpDNS:(NSString *)hostName ipList:(NSMutableArray<NSString *> *)list {
    // 把 hostName 解析到 ip 地址后,保存到 iPList,返回给 SDK 内部。注意:这里不要进行耗时的异步操作。
    // MSDKDnsResolver 是腾讯云提供的 HTTPDNS SDK 解析接口
    NSArray *result = [[MSDKDns sharedInstance] WGGetHostByName:hostName];
    NSString *ip = nil; 
    if (result && result.count > 1) {
         if (![result[1] isEqualToString:@"0"]) {
             ip = result[1];
         } else {
             ip = result[0];
         }
    }
         [list addObject:ip];
}

// 步骤3: 设置 HttpDNS 解析代理
[TXLiveBase sharedInstance].delegate = self;

播放器事件监听

您可以为 TXVodPlayer 对象绑定一个 TXVodPlayListener 监听器,即可通过 onPlayEvent(事件通知) 和 onNetStatus(状态反馈)向您的应用程序同步信息。

事件通知(onPlayEvent)

播放事件

事件 ID 数值 含义说明
PLAY_EVT_PLAY_BEGIN 2004 视频播放开始
PLAY_EVT_PLAY_PROGRESS 2005 视频播放进度,会通知当前播放进度、加载进度和总体时长
PLAY_EVT_PLAY_LOADING 2007 视频播放 loading,如果能够恢复,之后会有 LOADING_END 事件
PLAY_EVT_VOD_LOADING_END 2014 视频播放 loading 结束,视频继续播放
VOD_PLAY_EVT_SEEK_COMPLETE 2019 Seek 完成,10.3版本开始支持
VOD_PLAY_EVT_LOOP_ONCE_COMPLETE 6001 循环播放,一轮播放结束(10.8 版本开始支持)

结束事件

事件 ID 数值 含义说明
PLAY_EVT_PLAY_END 2006 视频播放结束
PLAY_ERR_NET_DISCONNECT -2301 网络断连,且经多次重连亦不能恢复,更多重试请自行重启播放
PLAY_ERR_HLS_KEY -2305 HLS 解密 key 获取失败

警告事件

如下的这些事件您可以不用关心,它只是用来告知您 SDK 内部的一些事件。

事件 ID 数值 含义说明
PLAY_WARNING_VIDEO_DECODE_FAIL 2101 当前视频帧解码失败
PLAY_WARNING_AUDIO_DECODE_FAIL 2102 当前音频帧解码失败
PLAY_WARNING_RECONNECT 2103 网络断连,已启动自动重连(重连超过三次就直接抛送 PLAY_ERR_NET_DISCONNECT 了)
PLAY_WARNING_HW_ACCELERATION_FAIL 2106 硬解启动失败,采用软解

连接事件

此外还有几个连接服务器的事件,主要用于测定和统计服务器连接时间:

事件 ID 数值 含义说明
PLAY_EVT_VOD_PLAY_PREPARED 2013 播放器已准备完成,可以播放。设置了 autoPlay 为 false 之后,需要在收到此事件后,调用 resume 才会开始播放
PLAY_EVT_RCV_FIRST_I_FRAME 2003 网络接收到首个可渲染的视频数据包(IDR)

画面事件

以下事件用于获取画面变化信息:

事件 ID 数值 含义说明
PLAY_EVT_CHANGE_RESOLUTION 2009 视频分辨率改变
PLAY_EVT_CHANGE_ROATION 2011 MP4 视频旋转角度

视频信息事件

事件 ID 数值 含义说明
PLAY_EVT_GET_PLAYINFO_SUCC 2010 成功获取播放文件信息

如果通过 fileId 方式播放且请求成功,SDK 会将一些请求信息通知到上层。您可以在收到PLAY_EVT_GET_PLAYINFO_SUCC 事件后,解析 param 获取视频信息。

视频信息 含义说明
EVT_PLAY_COVER_URL 视频封面地址
EVT_PLAY_URL 视频播放地址
EVT_PLAY_DURATION 视频时长

-(void) onPlayEvent:(TXVodPlayer *)player event:(int)EvtID withParam:(NSDictionary*)param
{
    if (EvtID == PLAY_EVT_VOD_PLAY_PREPARED) {
        //收到播放器已经准备完成事件,此时可以调用 pause、resume、getWidth、getSupportedBitrates 等接口
    } else if (EvtID == PLAY_EVT_PLAY_BEGIN) {
        // 收到开始播放事件
    } else if (EvtID == PLAY_EVT_PLAY_END) {
        // 收到开始结束事件
    }
}

状态反馈(onNetStatus)

状态反馈每0.5秒都会被触发一次,目的是实时反馈当前的推流器状态,它就像汽车的仪表盘,可以告知您目前 SDK 内部的一些具体情况,以便您能对当前视频播放状态等有所了解。

评估参数含义说明
CPU_USAGE当前瞬时 CPU 使用率
VIDEO_WIDTH视频分辨率 - 宽
VIDEO_HEIGHT视频分辨率 - 高
NET_SPEED当前的网络数据接收速度
VIDEO_FPS当前流媒体的视频帧率
VIDEO_BITRATE当前流媒体的视频码率,单位 kbps
AUDIO_BITRATE当前流媒体的音频码率,单位 kbps
V_SUM_CACHE_SIZE缓冲区(jitterbuffer)大小,缓冲区当前长度为0,说明离卡顿就不远了
SERVER_IP连接的服务器 IP

通过 onNetStatus 获取视频播放过程信息示例:

- (void)onNetStatus:(TXVodPlayer *)player withParam:(NSDictionary *)param {
    //获取当前 CPU 使用率
    float cpuUsage = [[param objectForKey:@"CPU_USAGE"] floatValue];
    //获取视频宽度
    int videoWidth = [[param objectForKey:@"VIDEO_WIDTH"] intValue];
    //获取视频高度
    int videoHeight = [[param objectForKey:@"VIDEO_HEIGHT"] intValue];
    //获取实时速率
    int  speed = [[param objectForKey:@"NET_SPEED"] intValue];
    //获取当前流媒体的视频帧率
    int fps = [[param objectForKey:@"VIDEO_FPS"] intValue];
    //获取当前流媒体的视频码率,单位 kbps
    int videoBitRate = [[param objectForKey:@"VIDEO_BITRATE"] intValue];
    //获取当前流媒体的音频码率,单位 kbps
    int audioBitRate = [[param objectForKey:@"AUDIO_BITRATE"] intValue];
    //获取缓冲区(jitterbuffer)大小,缓冲区当前长度为 0,说明离卡顿就不远了
    int jitterbuffer = [[param objectForKey:@"V_SUM_CACHE_SIZE"] intValue];
    //获取连接的服务器的 IP 地址
    NSString *ip = [param objectForKey:@"SERVER_IP"];
}

场景化功能

1. 基于 SDK 的 Demo 组件

基于播放器 SDK,腾讯云研发了一款 播放器组件,集质量监控、视频加密、极速高清、清晰度切换、小窗播放等功能于一体,适用于所有点播、直播播放场景。封装了完整功能并提供上层 UI,可帮助您在短时间内,打造一个媲美市面上各种流行视频 App 的播放软件。

2. 开源 Github

基于播放器 SDK,腾讯云研发了沉浸式视频播放器组件、视频 Feed 流、多播放器复用组件等,而且随着版本发布,我们会提供跟多的基于用户场景的组件。您可以通过 Player_iOS 下载体验。

目录