所有文档

          音视频处理 MCT

          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 下载管理相关 downloadTaskWithURLsuspendTaskresumeTaskcancelTaskstopAllTasksresumeUncompletedTasks接口
          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 删除所有下载数据 之前下载的所有视频将被清除。调用后,该对象将不再可用。

          下载及播放

          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:删除指定视频。

          上一篇
          接口说明
          下一篇
          版本更新记录