产品文档 点播技术文档 iOS 点播 Core SDK

iOS 点播Core SDK(不含UI)

SDK 地址

最新版1.4.3 change log

适用于iOS8.0+。

功能简介

iOS 点播核心 SDK 提供对点播播放器的播放管理操作(不含UI),功能包括:

  • 视频播放功能:提供视频ID、请求url的token等参数开始播放,也支持视频加密播放
  • 播放控制方法:播放、暂停、停止、跳转至指定时间、变换视频清晰度和倍速播放
  • 视频播放代理:提供响应播放事件的代理方法,用于捕获和处理播放中的错误
  • 获取视频信息:当前播放状态、视频时长、视频缓存时长
  • 视频下载功能:需要视频ID、请求url的token等参数

SDK 集成

  • Podfile 中设置 source
source 'https://github.com/CocoaPods/Specs.git'
source 'http://git.baijiashilian.com/open-ios/specs.git'
  • Podfile 中引入 BJPlayerManagerCore
  pod 'BJPlayerManagerCore'
  • 配置ATS. 需要在info.plist里面增加 NSAllowsArbitraryLoads = true

1. 引入头文件

#import <BJPlayerManagerCore/BJPlayerManagerCore.h>

2. 全局设置

  • 使用下载功能时, 需要在下面的方法中设置下载的rootpath
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions;

SDK 使用

1. 播放管理类初始化

  • 1.3.x 版本
    BJPlayerManager *playManger = [[BJPlayerManager alloc] init]; 
    playManager.delegate = self;//设置代理

  • 1.4.x 版本开始提供视频加密播放
    BJPlayerManagerType playType = BJPlayerManagerType_AVPlayer;
    BJPlayerManager *playManger = [[BJPlayerManager managerWithType: playType];
    playManager.delegate = self;//设置代理

2. 视频播放

1.设置视频播放源

//在线点播播放
    [self.playerManager setVideoID:vid token:token completion:^BOOL(PMVideoInfoModel * _Nonnull result, NSError * _Nonnull error) {
        return shouldAutoPlay;//block的返回值设置是否自动播放
    }];

 //本地视频播放
    [self.playerManager setVideoPath:path definition:definitionType completion:^BOOL(PMVideoInfoModel * _Nonnull result, NSError * _Nonnull error) {
        return shouldAutoPlay;//block的返回值设置是否自动播放
    }];

2.获取视频播放View, 设置frame

    playerManager.player.view.frame = CGRectMake(0, 0, SCREEN_WIDTH, SCREEN_WIDTH*9/16);
    [self.view addSubview:playerManager.player.view];//添加到目标视图

3.视频播放流程控制 BJPMControlProtocol

    [playerManager play];//播放 
    [playerManager plause];//暂停  
    [playerManager stop];//停止播放 
    [playerManager seek:time];//进度跳转 

  /*播放倍率 支持 [0.5, 2.0] 范围内的倍速设置, 该范围之外的倍速将不做任何响应 */
    [playerManager changeRate:rate];//切换倍速 
    [playerManager changeDefinition:(PMVideoDefinitionType)ddefineType];//切换淸晰度

4.视频播放代理方法

@required
//播放过程中出错(具体错误码参考下节)
- (void)videoplayer:(BJPlayerManager *)playerManager throwPlayError:(NSError *)error;

@optional

 视频播放完成的回调方法
- (void)videoDidFinishPlayInVideoPlayer:(BJPlayerManager *)playerManager;

// 播放器暂停的回调方法
- (void)videoPlayPauseInVideoPlayer:(BJPlayerManager *)playerManager;

5.视频信息获取


[self.playerManager getVideoInfoWithVid:vid token:token completion:(void(^)(PMVideoInfoModel * _Nullable videoInfo, NSError * _Nullable error))completion { // PMVideoInfoModel 为视频信息 }];

6.播放中的视频属性提供

  • 具体使用方法可以参考UI SDK的使用
//设置初始化播放时间
@property (nonatomic, assign) NSTimeInterval initialPlaybackTime;

//当前播放状态
@property (nonatomic, readonly) PMPlayState playState;

//视频的时长
@property (nonatomic, readonly) NSTimeInterval duration;

// 视频缓存时长
@property (nonatomic, readonly) NSTimeInterval cacheDuration;

// 当前播放倍速
@property (nonatomic, readonly) CGFloat playRate;

// 正片的当前的播放时间
@property (nonatomic, readonly) NSTimeInterval currentTime;

// 播放器实例
@property (readonly, nullable) PKMoviePlayerController *player;

// 播放信息
@property (nonatomic, readonly, nullable) PMVideoInfoModel *videoInfoModel;

// 当前播放清晰度
@property (nonatomic, readonly, nullable) PMVideoDefinitionInfoModel *currDefinitionInfoModel;

// 当前播放的CDN
@property (nonatomic, readonly, nullable) PMVideoCDNInfoModel *currCDNInfoModel;

7.播放通知

PMPlayStateChangeNotification; //播放状态改变通知
PMPlayerCreateNotification; //播放器实例被创建,即将播放视频
PMPlayerDestroyNotification; //播放器实例被销毁,用户退出
PMPlayerWillPlayNotification; //获取到播放信息后的通知
PMPlayerFileInvalidNotification; //播放地址无效的通知
PMPlayerFileNotExistNotification; //播放文件不存在的播通知
PMPlayerWillSeekNotification; //即将跳转到某一时刻
PMPlayerWillChangeDefinitionNotification; //即将切换清晰度
PMPlayerGetPlayInfoFailedNotification; //获取播放信息失败

3. 错误码

    BJPMErrorCodeLoading           = 1000,    //视频加载中
    BJPMErrorCodeLoadingEnd        = 1001,    //视频加载完成
    BJPMErrorCodeParse             = 1002,    //视频播放错误
    BJPMErrorCodeNetwork           = 1003,    //网络错误, 没有网络或是未知网络
    BJPMErrorCodeWWAN              = 1004,    //非WIFI环境
    BJPMErrorCodeWIFI              = 1005,    //wifi
    BJPMErrorCodeServer            = 1006,    //server端返回的错误
    BJPMErrorCodeApp               = 1007,    //app端的错误
    BJPMErrorCodeDownloadInvalid   = 1010,    //视频的url失效
    BJPMErrorCodeMissFile          = 1011,    //下载的文件丢失

4. 记忆播放

1.使用方法

  • 设置 BJPlayerManager 的 playTimeRecordEnabled 属性开关记忆播放。开启后记录 vid 对应的播放进度,每 5 秒【更新】一次播放进度,seek 时、停止播放时立即【更新】一次;
  • 如果 视频总时长 减去 当前进度 小于 N 秒,则视为播放结束,只移除记录、不添加,N 默认 5 秒,可自定义,参考 BJPlayerManager 的 ignorableRemainingTimeInterval 属性;
  • 调用 clearPlayTimeRecords 方法清除播放纪录。
  • 最多存 100 条,超过 100 条时顶掉最早的;

5. 视频下载 PMDownloadManager

1.初始设置

  • 注意:下载前需要先设置根路径, 然后调用单例方法, 否则代码抛出异常
  • 文件保存目录参考iOS官方文件存储文档.
  /* 下载根路径, folder需要是一个 存在的 文件夹, 如果不存在, 需要上层创建 */
  NSString *path = @"xxx/folder";
    [PMDownloadManager downloadManagerWithRootPath:path];

2.下载方法

参考头文件:PMDownloadManager.h

//点播下载
    [[PMDownloadManager downloadManager] addDownloadWithVid:vid token:token definionArray:definitionArray showFileName:showFileName];

//回放下载
    [[PMDownloadManager downloadManager] addDownloadWithClass:classID seesionID:sessionID token:token definionArray:defiArr showFileName:showname creatTime:@"creatTime"];

需要注意的是,由于我们使用了ID+token的视频下载方式, 因此是存在token过期的现象, 发生token失效或者下载url失效的问题时, 会向上层抛出BJPMErrorCodeDownloadInvalid (1010)的错误码,此时需要上层重新获取token,并调用下面的方法来重新设置token

/**
  下载中的任务发生了下载的url失效的错误,需要调用此方法,内部重新请求下载地址

 @param downloader 下载的任务
 @param token 新的token
 */
- (void)resetDownloadWithDownloader:(PMDownloader *)downloader token:(NSString *)token;

3.主要属性

/** 下载事件相关的代理 */
@property (nonatomic, weak  ) id<PMDownloadDelegate> downloadDelegate;

//下载过程中的数据 和 已经完成的数据
@property (nonatomic, readonly) NSArray <PMDownloader *> *downloadingList;
@property (nonatomic, readonly) NSArray <PMDownloadModel *> *finishedList;

4.下载代理方法

- (void)startDownload:(PMDownloader *)downloader;//开始下载
- (void)updateProgress:(PMDownloader *)downloader;//获取下载进度
- (void)finishedDownload:(PMDownloader *)downloader;//下载完成

/**
 下载时的错误回调, 包括开始下载之前和下载过程中的错误

 @param downloader 下载过程中的下载器实例, 可能为空
 @param beforeDownloadModel 下载开始前的错误model, 可能为空
 */
- (void)downloadFail:(nullable PMDownloader *)downloader beforeDownloadError:(nullable PMBeforeDownloadModel *)beforeDownloadModel;

5.分账户下载

  • 设置rootpath时, 需要传入绝对路径, 文件保存目录参考iOS官方文件存储文档.
  • 由于rootpath为绝对路径, 所以就需要在APP每次启动的时候,在- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 里面更新路径.
  • 分账户下载的rootpath是需要跟账户的唯一id(或者其他ID)相关联. 每次登陆一个新账户也需要清除上个账户的信息, 或者在退出账户时清理.

    [PMDownloadManager downloadManagerDestory];
    
  • 登录新账户时,也需要重新设置新账户的rootpath.

6.下载中的错误回调方法处理

详细参考demo中的对(void)downloadFail:(nullable PMDownloader *)downloader beforeDownloadError:(nullable PMBeforeDownloadModel *)beforeDownloadModel;代理方法的处理

git 地址

常见问题

  • app每次杀死重启之后,就找不到下载的finishedlist和downinglist?

    • 确认设置下载目录rootpath时,需要在'-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions'方法中设置的.
  • 下载时经常提示下载失败

    • SDK提供的下载方法是需要传递视频id+token,或者回放ID+sessionID+token 的, 用户可以在百家云的后台设置token的有效期,所以是存在token失效的问题的.
    • 在downloadManager的delegate回调方法中监听到BJPMErrorCodeDownloadInvalid错误码时,代表当前url失效了,需要再次获取新的token,然后调用我们提供的resetDownload...方法重新设置token.
  • 对于下载和播放的回调方法中抛出来的error的具体信息?

    • 通过 NSString *errMsg = [error.userInfo objectForKey:NSLocalizedDescriptionKey]; 一般都可以获取到详细的错误信息,可以帮助进一步定位错误.
  • 播放在线视频/下载视频时偶现提示1006错误码,提示服务端的错误

    • 出现1006的错误码时,大部分是token失效/token校验不通过 的情况,建议播放视频下载时总是获取最新的token. 另外下载过程中也需要注意BJPMErrorCodeDownloadInvalid的错误码,及时更新token
  • token验证失败,或者返回1010的错误码

    • 除了以上原因,传token参数的时候,请务必确认一下token里面不能包含空格,否则播放或者下载视频的时候,将有可能提示token验证失败.