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 依赖的框架

将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视频进行下载和管理。

头文件

下载管理接口

下载及播放

1. 调用initWithUser:delegate:完成初始化。

   其中，user处理用户相关事件，delegate处理任务相关事件。

   函数原型：

   - (instancetype)initWithUser:(NSString*)user delegate:(id<CyberDownloaderDelegate>)delegate;

2. 调用downloadTaskWithURL:title:error:创建下载任务。

   函数原型：

   - (CyberDownloadTask*)downloadTaskWithURL:(NSString*)url title:(NSString*)title error:(NSError**)error;

   downloadTaskWithURL:title:error:首先检查error返回值，值为CyberDownloadErrorCodeOK表示视频可以下载，此时创建任务并加入下载任务队列（并未真正开始下载，队列有可用资源时，才会进一步调用taskStart启动下载）；否则请参照下述错误代码表进行调试：

   错误代码	描述
   CyberDownloadErrorCodeAlreadyExists	视频文件已经存在且已下载完毕
   CyberDownloadErrorCodeProtocolNotSupport	协议不支持

3. 下载任务开始执行时，回调taskStart:。

   函数原型：

   - (void)taskStart:(CyberDownloadTask*)task;

   此时也可调用暂停（suspendTask:）、恢复（resumeTask:）、取消（cancelTask:）、批量停止（stopAllTasks:）等接口对下载任务进行管理。

4. 任务下载过程中回调task:progress:，通知任务进度。

   函数原型：

   - (void)task:(CyberDownloadTask*)task progress:(float)progress;

5. 任务下载结束后，回调taskEnd:error:。如果error为空，下载任务执行成功；否则，任务执行失败。

   函数原型：

   - (void)taskEnd:(CyberDownloadTask*)task error:(NSError*)error;

6. 下载成功后，将task.item.index属性，传给播放器进行本地播放。

   此外，还可调用mediaItems查询本地下载完成及下载中的视频，或调用removeMediaItem:删除指定视频。