iOS-播放器-SDK-开发者指南
Cocoapods接入
使用Cocoapods接入方式非常简单,可移步Cocoapods接入方式。
如果使用Cocoapods接入方式,可跳过下面的 开发前准备
和 XCode工程配置
。
开发前准备
- 下载最新的播放器 iOS SDK。
- 准备 iOS 运行环境:iOS 7.0 及以上的所有系统。
- Xcode版本:推荐使用Xcode 8.1。
- 适配 CPU 指令集:armv7/armv7s、arm64、i386/x86_64。
- 申请账号并开通权限: 您需要登录百度智能云,在安全认证页面 获取 AK/SK。
- 添加 SDK 所依赖的 iOS 框架,音频编解码 API (AudioToolbox.framework) 及压缩工具(libbz2.tbd 和 libz.tbd)。
XCode工程配置
配置 App Transport Security (ATS)
从 iOS 9.0 和 OS X v10.11 开始,默认开启 App Transport Security (ATS) 功能。ATS 强制使用 HTTPS 访问 Web 服务,并且必须使用 TLS v1.2 以上版本保证通信的安全性。ATS 的详细需求请参考:Requirements for Connecting Using ATS
如果 app 支持 iOS 9.0 而且需要访问不满足上述要求的 Web 服务,必须在 info.plist 文件中使用 NSAppTransportSecurity
元素添加例外处理规则。NSAppTransportSecurity
的使用方法请参考:App Transport Security
由于 AK 鉴权所访问的服务也不满足 ATS 的需求, 需要在 info.plist 文件设置如下配置,修改 ATS 对域名 drm.media.baidubce.com
的访问行为。
<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>drm.media.baidubce.com</key>
<dict>
<key>NSIncludesSubdomains</key>
<true/>
<key>NSExceptionAllowInsecureHTTPSLoads</key>
<true/>
<key>NSExceptionRequiresForwardSecrecy</key>
<false/>
<key>NSExceptionMinimumTLSVersion</key>
<string>TLSv1.0</string>
</dict>
</dict>
</dict>
设置 Build Setting
- 设置 CPU 指令集
iOS SDK 支持 armv7、arm64、x86、x86_64 一共 4 种 CPU 架构。请检查"Build Settings->Architectures->Valid Architectures" 和 "Build Settings->Architectures-> Architectures" 设置,确保不包含其它CPU指令集。
- 关闭 Bitcode 编译选项
如果您使用XCode 7,请关闭Bitcode编译选项"Build Settings->Build Option->Enable Bitcode"。因为iOS SDK的库不包含Bitcode指令。
- 打开 Module 编译选项
如下图所示,打开Module选项"Build Settings->Apple LLVM - Language - Modules->Enable Modules(C and Objective-C)"有助于简化依赖库的配置
- 在
Build Settings
中设置Other Linker Flags
,加入参数-ObjC
添加iOS SDK的头文件
将Baidu-T5Player-SDK-iOS-x.x.x/include 目录下的头文件 CyberPlayerController.h 添加到 Xcode 工程。
添加iOS SDK的静态链接库
请在“Build Phases->Link Binary with Libraries” 添加iOS SDK的静态链接库。
添加iOS系统动态链接库
请在“Build Phases->Link Binary with Libraries” 添加下表所列的系统库 表 6 SDK 依赖的框架
框架名 | 说明 |
---|---|
libbz2.tbd | 压缩工具 |
libz.tbd | 压缩工具 |
AudioToolbox.framework | 音频处理工具 |
将iOS SDK的静态链接库和系统的动态链接库设置完毕,下图所示:
播放开发指南
下面介绍如何调用播放器 SDK 中已封装的 API 完成各项操作。
创建并设置 CyberPlayerController 实例
CyberPlayerController 是iOS SDK的核心API,开发者必须先创建此类的实例才能播放音视频。需要分别设置视频播放地址和百度智能云Access Key
- 设置百度智能云 Access key 百度智能云的用户实名认证后会分配一对Access Key 和 Private Key。在播放视频之前请传入Access Key,以便于SDK做鉴权认证。 如果没有传入Access Key、或者传入无效的Access Key,在播放过程中会显示警告信息。
- 设置视频播放地址 视频播放地址可以通过 property contentURL 或者 contentString 设置。 当播放器正在播放视频时,设置 contenString/contenURL 将不会导致播放新视频。如果希望播放新视频, 需要调用 prepareToplay 方法。
以下代码展示如何用视频播放地址 URL 和 Access Key 创建并设置 CyberPlayerController。
CyberPlayerController *cbPlayerController = [[CyberPlayerController alloc] init];
NSURL *url = [NSURL URLWithString:@”<video url>”];
cbPlayerController.contentURL = url;
NSString* msAK=@"<AccessKey>";
[cbPlayerController setAccessKey:msAK];
注意
- 当前版本只支持单实例 CyberPlayerController 对象,多实例将导致播放异常。
- 当前版本不支持百度影音资源(bdhd://开头的视频资源)。
播放视频
播放器在设置播放视频地址后,需要调用 prepareToPlay 方法对视频文件进行初始化工作。 初始化完成后将发送 CyberPlayerLoadDidPreparedNotification 通知,并将 isPreparedToPlay 属性置为 YES。 初始化完成后,如果 shouldAutoplay 属性为 YES,则自动调用 play 方法进行播放;如果 shouldAutoplay 属性为 NO,则等待调用 play 或 start 方法播放。
在开始阶段,播放器会先暂停一段时间,以便于缓存一定量的视频,用于冲销网络抖动所带来的卡顿,保证视频播放的流畅。此时间长度对应的 property 是 cachePauseTimeInSeconds (默认值为 1.0)。这个值越大,网络抖动对视频播放的影响越小,但是延迟会增大;反之值越小,网络抖动对视频播放的影响越大,播放的延迟越小。在直播的场景下,需要根据网络状况和视频码率,为 cachePauseTimeInSeconds 设置一个合适的值,以均衡播放卡顿和直播延时的需求。带宽高的时候,建议降低缓存以降低延迟;带宽低的时候,提高缓存以提高播放流畅度。
自动播放
cbPlayerController.shouldAutoplay = YES;
[cbPlayerController prepareToPlay];
此时,shouldAutoplay 属性为 YES,prepareToPlay 方法完成后将播放器自动调用 play 开始播放视频。
监听CyberPlayerLoadDidPreparedNotification通知
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(preparedDone:)
name:CyberPlayerLoadDidPreparedNotification
object:nil];
cbPlayerController.shouldAutoplay = NO
[cbPlayerController prepareToPlay];
同时新建 preparedDone 方法,并在该方法中调用 start 或 play 方法。
(void) preparedDone: (NSNotification*)aNotification {
[cbPlayerController start];
}
注意
如果调用 play 方法前未调用 prepareToPlay 完成播放器对视频文件的初始化,则播放器自动调用prepareToPlay 进行视频文件的初始化工作。
暂停播放
调用 pause 方法暂停视频播放,调用 play 或 start 方法重新开始播放。
[cbPlayerController pause];
改变播放位置
SDK 提供了多种改变播放位置的方式。
初始化时
当 isPreparedToPlay 属性为 NO 时,为了实现改变视频播放的初始时刻,三种方式都可以达到相同效果:
- 设置 initialPlaybackTime 属性。
- 设置 currentPlaybackTime 属性。
- 调用 seekto 方法。
播放过程中
当播放视频过程中调用 seekTo 或者设置 currentPlaybackTime 属性,将导致从指定位置开始播放。 如果当前视频为网络视频,可能触发缓冲 CyberPlayerStartCachingNotification 通知。 如果希望在UI 反应缓冲进度,请监听 CyberPlayerGotCachePercentNotification 通知。
HLS多码率/分辨率切换
对于HLS多码率视频,在播放器完成视频格式解析、准备开始播放时,可通过 getSupportedBitrates
方法展示码率列表或通过 getSupportedResolution
方法展示分辨率列表。码率与分辨率一一对应,一般分二档(低、高,默认值为低)或三档(低、中、高,默认值为中),建议根据终端用户的使用习惯选择展示码率或分辨率。启用手动切换时,可通过 getBitrateIndex
获取当前码率并用 selectBitrate
选用新码率。
停止播放
[cbPlayerController stop];
停止播放后,将发送 CyberPlayerPlaybackDidFinishNotification 通知。
注意
stop方法为异步操作,当它返回的时候不能马上调用 prepareToPlay 播放其它视频,必须等接收到 CyberPlayerPlaybackDidFinishNotification 后才能播放。
M3U8视频下载
播放器支持对M3U8视频进行下载和管理。
头文件
头文件 | 描述 | 关键信息 |
---|---|---|
CyberDownloader.h | 下载管理相关 | downloadTaskWithURL 、suspendTask 、resumeTask 、cancelTask 、stopAllTasks 、resumeUncompletedTasks 接口 |
CyberDownloadTask.h | 下载任务相关 | |
CyberMediaItem.h | 视频本地存储相关 | task.item.index属性 |
下载管理接口
接口 | 描述 | 说明 |
---|---|---|
downloadTaskWithURL |
新建下载任务 | 指定目标视频的URL及标题,新建任务并加入下载任务队列,任务是否执行取决于当前队列中正在执行的任务个数,默认支持4个任务同时下载 |
suspendTask |
暂停下载任务 | 与resumeTask 配合使用。任务暂停后,已下载视频仍存于用户本地,任务从下载队列出队 |
resumeTask |
恢复下载任务 | 与suspendTask 配合使用。任务恢复后,重新进入下载任务队列,基于已下载部分断点续传 |
cancelTask |
取消下载任务 | 相较于suspendTask ,被取消的任务不但从任务队列出队,对应视频也从用户本地删除 |
stopAllTasks |
批量停止下载任务 | 对本地视频的处理与suspendTask 相似,即仍将已下载视频存于用户本地。suspendTask 针对单个任务,stopAllTasks 为批量操作 |
resumeUncompletedTasks |
批量恢复下载任务 | resumeTask 针对单个任务,resumeUncompletedTasks 为批量操作 |
frozen |
冻结下载队列 | 当取消一些任务,且不希望处于等待状态的任务被调度时,可调用此方法。 |
clean |
删除所有下载数据 | 之前下载的所有视频将被清除。调用后,该对象将不再可用。 |
下载及播放
-
调用
initWithUser:delegate:
完成初始化。其中,
user
处理用户相关事件,delegate
处理任务相关事件。函数原型:
- (instancetype)initWithUser:(NSString*)user delegate:(id<CyberDownloaderDelegate>)delegate;
-
调用
downloadTaskWithURL:title:error:
创建下载任务。函数原型:
- (CyberDownloadTask*)downloadTaskWithURL:(NSString*)url title:(NSString*)title error:(NSError**)error;
downloadTaskWithURL:title:error:
首先检查error
返回值,值为CyberDownloadErrorCodeOK
表示视频可以下载,此时创建任务并加入下载任务队列(并未真正开始下载,队列有可用资源时,才会进一步调用taskStart
启动下载);否则请参照下述错误代码表进行调试:错误代码 描述 CyberDownloadErrorCodeAlreadyExists 视频文件已经存在且已下载完毕 CyberDownloadErrorCodeProtocolNotSupport 协议不支持 -
下载任务开始执行时,回调
taskStart:
。函数原型:
- (void)taskStart:(CyberDownloadTask*)task;
此时也可调用暂停(
suspendTask:
)、恢复(resumeTask:
)、取消(cancelTask:
)、批量停止(stopAllTasks:
)等接口对下载任务进行管理。 -
任务下载过程中回调
task:progress:
,通知任务进度。函数原型:
- (void)task:(CyberDownloadTask*)task progress:(float)progress;
-
任务下载结束后,回调
taskEnd:error:
。如果error为空,下载任务执行成功;否则,任务执行失败。函数原型:
- (void)taskEnd:(CyberDownloadTask*)task error:(NSError*)error;
-
下载成功后,将task.item.index属性,传给播放器进行本地播放。
此外,还可调用
mediaItems
查询本地下载完成及下载中的视频,或调用removeMediaItem:
删除指定视频。