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

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