快速进阶
正确释放播放器
保证App稳定、高效的运行,正确释放播放器非常重要。
目前主流的交互基本是这样的:
- 用户点击视频列表中的某一个视频,将
播放UI
push到UINavigationController
上; 播放UI
开始加载视频并播放;-
用户点击后退按钮退出播放,
播放UI
从UINavigationController
pop 掉。这里重点关注第3步,介绍释放播放器的时机、流程:
-
当用户点击后退按钮时,只调用播放器的
stop
方法;Objectivec1- (IBAction)onBackButton:(id)sender { 2 [self.player stop]; 3}
-
等待播放器发送
BDCloudMediaPlayerPlaybackDidFinishNotification
通知后,再将播放UI
从UINavigationController
pop 掉。Objectivec1// 注册通知 2- (void)setupNotifications { 3 [[NSNotificationCenter defaultCenter] addObserver:self 4 selector:@selector(onPlayerFinish:) 5 name:BDCloudMediaPlayerPlaybackDidFinishNotification 6 object:nil]; 7 } 8 9 // 等到Finish通知后再pop 10- (void)onPlayerFinish:(NSNotification*)notification { 11 // 如果同时有多个播放器实例的话,最好判断下通知里的object是否跟持有的是同一个。 12 if (notification.object != self.player) { 13 return; 14 } 15 16 // pop UI 17 [self.navigationController popViewControllerAnimated:YES]; 18 }
这样的流程可以保证在退出
播放UI
时,播放器内部本次播放相关资源也已释放完毕,有利于复用播放器实例,发起下一次播放。 -
进度条相关
视频播放器进度条上包括下列3个信息:
- 视频总时长
duration
- 当前播放时间
currentPlaybackTime
- 当前缓冲时间
playableDuration
在收到BDCloudMediaPlayerPlaybackIsPreparedToPlayNotification
通知后,可以获取duration
确定进度条的maximumValue
(直播视频可能获取到的值为零)。并启动一个每秒触发一次的NSTimer
,来实时获取currentPlaybackTime
和playableDuration
,更新进度条。
注意: iOS系统没有提供带缓冲进度的进度条,需要用户自行实现。
播放下一个视频
正在播放视频时,如果想放弃当前的播放,并立即在当前播放UI
播放另一个视频时,可以按照下面的方式来操作:
1- (IBAction)onPlayNext:(id)sender {
2 // 停止当前视频的播放。
3 [self.player stop];
4
5 // reset播放器到初始状态。
6 [self.player reset];
7
8 // 开始下一个视频的初始化和播放流程。
9 self.player.contentString = @"<next url>";
10 self.player.shouldAutoplay = YES;
11 [self.player prepareToPlay];
12}
APM接入
APM SDK 提供数据监控、发送、后台报表处理与展示能力。实时性强,能够及时上报用户在点播、直播中的卡顿、网速等信息,方便运营方及时调整策略和调度。
SDK不直接依赖APM SDK
,在运行时动态检查App是否接入了APM SDK
。
多码率切换
多码率快速切换
当播放的是HLS多码率视频时,播放器支持在播放过程中实时切换码率。具体操作步骤如下:
- 在收到
BDCloudMediaPlayerPlaybackIsPreparedToPlayNotification
通知后,调用获取多码率列表的接口; -
将多码率列表显示在
播放UI
上供用户选择码率;以上两步代码示例:
1 - (void)onPlayerPrepared:(NSNotification*)notification {
2 // 如果同时有多个播放器实例的话,最好判断下通知里的object是否跟持有的是同一个。
3 if (notification.object != self.player) {
4 return;
5 }
6
7 // 获取多码率列表。
8 NSArray<BDCloudMediaPlayerBitrateItem*>* items = [self.player getSupportedBitrates];
9
10 // 将码率列表显示在UI上。
11 [self showBitrateList:items];
12 }
- 用户选择码率时,调用
setBitrateIndex:
方法设置码率索引:
1 - (IBAction)onChangeBitrate:(id)sender {
2 NSInteger index = <bitrateIndex>;
3 [self.player setBitrateIndex:index];
4 }
多码率无缝切换
播放器不仅支持HLS的多码率快速切换,同时也支持HLS,MP4等主流媒体格式的无缝切换功能。具体操作如下:
Master playlist 的HLS格式多码率无缝切换
- 设置输入格式
1 - (void)setMediaInputType:(NSInteger)inputType {
2 [self.player setMediaItemsInputType:inputType];
3 }
- 在收到BDCloudMediaPlayerPlaybackIsPreparedToPlayNotification通知后,调用获取多码率列表的接口,显示到UI。
1 - (void)onPlayerPrepared:(NSNotification*)notification {
2 // 如果同时有多个播放器实例的话,最好判断下通知里的object是否跟持有的是同一个。
3 if (notification.object != self.player) {
4 return;
5 }
6
7 // 获取多码率列表。
8 NSArray* bitrates = [self.player getMediaItems];
9
10 // 获取当前码率索引
11 int index = (int)[self.player mediaItemIndex];
12
13 // 将码率列表显示在UI上。
14 [self.actions updateBitrateList:bitrates index:index];
15 }
- 用户根据对应索引切换到指定码率。
1 - (void)changeBitrate:(NSInteger)index {
2 [self.player setMediaItemIndex:index];
3 }
- 当收到BDCloudMediaPlayerMediaChangeStartNotification 通知表示视频开始切换。
- 当收到BDCloudMediaPlayerMediaChangeEndNotification 通知表示切换结束,同时可以取BDCloudMediaPlayerMediaChangeEndResultUserInfoKey 的值判断切换是否成功。此时播放器缓冲播放完成后即会切换到新的码率显示。
- 当收到BDCloudMediaPlayerNaturalSizeChangedNotification 通知表示视频分辨率发生变化。
MP4等非嵌套码率的无缝切换
- 设置输入格式
1 - (void)setMediaInputType:(NSInteger)inputType {
2 [self.player setMediaItemsInputType:inputType];
3 }
- 设置多码率视频链接(注意这里和HLS的区别)
1 - (void)setMediaInputList:(NSArray *)inputList {
2 [self.player setMediaItems:inputList];
3 }
- 在收到BDCloudMediaPlayerPlaybackIsPreparedToPlayNotification通知后,调用获取多码率列表的接口,显示到UI。
1 - (void)onPlayerPrepared:(NSNotification*)notification {
2 // 如果同时有多个播放器实例的话,最好判断下通知里的object是否跟持有的是同一个。
3 if (notification.object != self.player) {
4 return;
5 }
6
7 // 获取多码率列表。
8 NSArray* bitrates = [self.player getMediaItems];
9
10 // 获取当前码率索引
11 int index = (int)[self.player mediaItemIndex];
12
13 // 将码率列表显示在UI上。
14 [self.actions updateBitrateList:bitrates index:index];
15 }
- 用户根据对应索引切换到指定码率。
1 - (void)changeBitrate:(NSInteger)index {
2 [self.player setMediaItemIndex:index];
3 }
- 当收到BDCloudMediaPlayerMediaChangeStartNotification 通知表示视频开始切换。
- 当收到BDCloudMediaPlayerMediaChangeEndNotification 通知表示切换结束,同时可以取BDCloudMediaPlayerMediaChangeEndResultUserInfoKey 的值判断切换是否成功。此时播放器缓冲播放完成后即会切换到新的码率显示。
- 当收到BDCloudMediaPlayerNaturalSizeChangedNotification 通知表示视频分辨率发生变化。
播放HLS加密视频
百度智能云MCP服务支持转码成HLS加密视频。
不同的加密方式,播放时的方法略有不同:
- PlayerBinding加密模式 按普通视频播放即可。
-
自定义PlayerId、PlayerKey模式
播放之前需要先设置
playerId
和playerKey
。
1 (void)play {
2 // 先设置`playerId`和`playerKey`。
3 [self.player setPlayerID:@"<playerId>" key:@"<playerKey>"];
4
5 // 再播放视频。
6 self.player.contentString = @"<url>";
7 self.player.shouldAutoplay = YES;
8 [self.player prepareToPlay];
9 }
-
Token模式
播放之前需要先设置
token
。
1 (void)play {
2 // 先设置`token`。
3 [self.player setToken:@"<token>"];
4
5 // 再播放视频。
6 self.player.contentString = @"<url>";
7 self.player.shouldAutoplay = YES;
8 [self.player prepareToPlay];
9 }
设置HTTP请求的Header
如果需要设置常见的一些HTTP Header字段,例如User-Agent
,可以使用接口setOptionValue
。
1NSString* value = @"User-Agent: <your user agent>";
2[player setOptionValue:value
3 forKey:@"headers"
4 ofCategory:BDCloudMediaPlayerOptionCategoryFormat];
说明:
如果需要设置多个HTTP Header字段,需要按照HTTP规范,将多个字段使用
\r\n
连接起来。
下载HLS视频
SDK 除了提供视频播放功能之外,还支持 HLS 视频的下载。类BDCloudMediaDownload
提供下载相关接口。
普通HLS视频的下载
下面介绍下载的基本流程:
- 实现
BDCloudMediaDownloadDelegate
来响应下载任务的状态变化回调
1 // 任务开始
2 - (void)taskStart:(BDCloudMediaDownloadTask*)task {
3 }
4
5 // 任务的进度汇报
6 - (void)task:(BDCloudMediaDownloadTask*)task progress:(float)progress {
7 NSLog(@"任务%@, 下载进度 %.2f", task, progress);
8 }
9
10 // 任务完成,error为nil表示下载成功。
11 - (void)taskEnd:(BDCloudMediaDownloadTask*)task error:(NSError*)error {
12 if (!error) {
13 NSLog(@"下载成功!");
14 // 获取离线视频的本地路径,拿到之后就可以离线播放。
15 NSString* path = [task.item.path stringByAppendingPathComponent task.item.index];
16 }
17 }
-
创建下载器
下载器初始化时,需要传入用户名,用于在本地区分不同登录用户的下载存储(如果App没有账号系统,可以传一个固定值)。
1 self.downloader = [[BDCloudMediaDownload alloc] initWithUser:@"<user>" delegate:self];
-
创建下载任务、开始下载
创建下载任务后,任务会进入到执行队列中,队列的最大并发数是4个。当超出最大并发数时,新创建的任务会处于等待执行的状态。
1 NSError* error;
2 BDCloudMediaDownloadTask* task = [self.downloader downloadTaskWithURL:@"<url>" title:@"<title>" error:&error];
注意:
- 传入的
url
必须以http
或https
开头,以.m3u8
结尾。- 如果传入的
url
曾经下载成功,并且也没有调用过removeMediaItem
接口对视频数据进行清理,创建下载任务将会失败,error的code会被赋值为BDCloudMediaDownloadErrorCodeAlreadyExists
。
加密HLS视频的下载
加密HLS
视频的下载与普通的HLS
视频下载相比,多出设置认证信息的过程,只需要实现代理方法task:needAuthentication:
。
1- (void)task:(BDCloudMediaDownloadTask*)task needAuthentication:(NSMutableDictionary*)parameters {
2 // 当下载的视频是PlayerID, PlayerKey加密方式时,需要在parameters里设置playerId
3 [parameters setObject:@"<playerId>" forKey:@"playerId"];
4
5 // 当下载的视频是token加密方式时,需要在parameters里设置token
6 [parameters setObject:@"<token>" forKey:@"token"];
7}
任务的暂停和恢复
下载任务支持暂停和恢复:
- 暂停时,下载到本地的数据不会丢失;
- 恢复时,会从上次下载的位置继续下载。
1// 暂停任务
2[self.downloader suspendTask:task];
3
4// 恢复任务
5[self.downloader resumeTask:task];
断点续传
当App重新打开要继续上次未完成的下载时,需要先调用resumeUncompletedTasks
方法(SDK内部会根据保存的任务状态,自动创建未完成的任务并加入下载队列)返回未完成的下载任务。
1self.downloader = [[BDCloudMediaDownload alloc] initWithUser:@"<user>" delegate:self];
2
3// 获取上次未下载完成的任务。
4self.tasks = [self.downloader resumeUncompletedTasks];
下载并显示缩略图
- SDK 除了提供视频播放功能之外,还支持下载并显示缩略图。
BDCloudSpriteManager
提供缩略图相关接口。
注意:
- 缩略图的规则和获取需要配置MCP转码模板后转码才可使用。
1// 1. 初始化雪碧图渲染配置并设置必要属性。
2BDCloudSpriteRenderConfiguration *renderConfig = [BDCloudSpriteRenderConfiguration defaultConfiguration];
3renderConfig.row = <雪碧图中缩略图的行数>;
4renderConfig.column = <雪碧图中缩略图的列数> ;
5renderConfig.thumbnailDuration = <每个缩略图的时间间隔>;
6
7// 2. 初始化雪碧图下载配置并设置必要属性。
8BDCloudSpriteDownloadConfiguration *downloadConfig = [BDCloudSpriteDownloadConfiguration defaultConfiguration];
9downloadConfig.imageList = <雪碧图的URL列表>;
10downloadConfig.maxThreadNum = <下载开启的做大线程数>;
11downloadConfig.path = <下载地址>;
12
13// 3. 初始化雪碧图渲染控制类,并添加显示的画布。
14BDCloudSpriteManager *manager = [BDCloudSpriteManager initWithRenderConfig:renderConfig downloadConfig:downloadConfig];
15manager.renderView.frame = <画布frame>;
16[self.view addSubView:manager.renderView]
17[manager startDownload:nil];
18
19// 4. 用户收到下载成功回调后,根据时间戳显示缩略图。
20[manager renderTime:<显示时间戳>];
网络视频加速
SDK 除了提供视频播放功能之外,还支持MP4格式的网络视频加速。BDCloudMediaSourceManager
提供网络视频加速播放。包含以下功能:
- 视频预下载。
- 边播边存。
注意:
- 当前网络视频加速只支持mp4格式。
1// 1. 预下载视频。
2[[BDCloudMediaSourceManager sharedInstance] download:url size:downloadSize complete:^(BOOL succ, NSError *error) {
3 NSLog(@"pre download succ = %d, error = %@",error);
4}];
5
6// 2. 开启边播边存
7[BDCloudMediaSourceManager sharedInstance].autoWriteCache = YES;
8
9// 3. 播放器设置网络代理。
10self.player.proxy = [BDCloudMediaSourceManager sharedInstance];
11
12// 4. 预下载完成后,和常规播放流程一样,设置url后开始播放,就会自动通过代理进行播放
13[self.player prepareToPlay];
外挂字幕
通过下面的接口,可以给播放器添加外挂字幕,当前支持的字幕格式有srt/ass/ssa/webvtt。需要注意的是,该接口需要在收到播放器BDCloudMediaPlayerPlaybackIsPreparedToPlayNotification
消息后使用。对于同一个播放器示例,同一时刻只允许添加一个外挂字幕,添加新的外挂字幕会自动代替旧的外挂字幕。
1- (void)addExtSubtitleUrl:(NSString*)url;
外挂字幕成功读取后,会通过BDCloudMediaPlayerExtSubtitleOpenNotification
消息通知,消息中使用BDCloudMediaPlayerExtSubtitleUrlKey
记录相应的外挂字幕URL。
具体的字幕内容也会在BDCloudMediaPlayerTimedTextNotification
消息中携带,这一点与内嵌字幕相同。
多音轨、多字幕切换
对于带有多个音轨、字幕轨的片源,可以通过下面的方式实现轨道的无缝切换。
- 先利用下面的接口获取当前片源所有的轨道信息
1(NSMutableArray *)getTrackInfo
返回的数组中每个元素为BDCloudMediaPlayerTrackInfo
,在BDCloudMediaPlayerTrackInfo
类中记录了每个轨道的媒体类型和语言信息。
- 根据轨道信息数组的下标进行切换
利用下面的接口可以执行轨道的选择和反选,传入的参数即对应第一步获取的轨道信息数组下标。
1 (void)selectTrack:(int)trackId
2 (void)deselectTrack:(int)trackId
- 查询当前选择的轨道
利用下面的接口可以获取当前选中的视频/音频/字幕轨,返回参数也对应第一步获取的轨道信息数组下标。
1(int)getSelectedTrack:(BDCloudTrackType)trackType
- 轨道变化回调
轨道的添加、切换都会通过BDCloudMediaPlayerTrackChangedNotification
消息进行通知,该消息中BDCloudMediaPlayerTrackActionKey
字段对应轨道添加或切换事件,BDCloudMediaPlayerTrackTypeKey
字段对应轨道类型,BDCloudMediaPlayerTrackIdKey
字段则对应轨道序号。
- 无缝切换与有感切换
播放器默认使能轨道的无缝切换(切换过程中无缓冲状态),如果需要切换为有感切换,可以在prepareToPlay
之前设置下面的选项来实现
1 [self.player setOptionIntValue:0
2 forKey:@"enable-smooth-track-change"
3 ofCategory:BDCloudMediaPlayerOptionCategoryPlayer];
AV1解码支持
目前仅在播放器SDK全媒体版中,集成了单独的AV1软件解码器。
如果使用播放器SDK流媒体版播放AV1片源,则通过BDCloudMediaPlayerPlaybackDidFinishNotification
通知错误,错误码为10003,含义为解码器不支持当前格式。相关处理代码可以参考Demo工程中的PlayerViewModel.m
文件。
常见错误码含义
常见错误码分为播放内核错误、鉴权错误、其他错误三类,具体定义和含义解释可以参考Demo工程PlayerViewModel.m
中getReadableErrorMsg
方法的实现。