快速进阶

更新时间：2025-08-22

正确释放播放器

保证App稳定、高效的运行，正确释放播放器非常重要。

目前主流的交互基本是这样的：

用户点击视频列表中的某一个视频，将播放UIpush到UINavigationController上;
播放UI开始加载视频并播放；

用户点击后退按钮退出播放，播放UI从UINavigationController pop 掉。

这里重点关注第3步，介绍释放播放器的时机、流程：

当用户点击后退按钮时，只调用播放器的stop方法;
Objectivec
```
1- (IBAction)onBackButton:(id)sender {
2    [self.player stop];
3}
```

等待播放器发送BDCloudMediaPlayerPlaybackDidFinishNotification通知后，再将播放UI从UINavigationController pop 掉。

Objectivec

1// 注册通知
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播放另一个视频时，可以按照下面的方式来操作：

Objectivec

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上供用户选择码率；

以上两步代码示例：

Objectivec

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:方法设置码率索引：

Objectivec

1 - (IBAction)onChangeBitrate:(id)sender {
2     NSInteger index = <bitrateIndex>;
3     [self.player setBitrateIndex:index];
4 }

多码率无缝切换

播放器不仅支持HLS的多码率快速切换，同时也支持HLS,MP4等主流媒体格式的无缝切换功能。具体操作如下：

Master playlist 的HLS格式多码率无缝切换

设置输入格式

Objectivec

1 - (void)setMediaInputType:(NSInteger)inputType {
2     [self.player setMediaItemsInputType:inputType];
3 }

在收到BDCloudMediaPlayerPlaybackIsPreparedToPlayNotification通知后，调用获取多码率列表的接口，显示到UI。

Objectivec

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 }

用户根据对应索引切换到指定码率。

Objectivec

1 - (void)changeBitrate:(NSInteger)index {
2     [self.player setMediaItemIndex:index];
3 }

当收到BDCloudMediaPlayerMediaChangeStartNotification 通知表示视频开始切换。
当收到BDCloudMediaPlayerMediaChangeEndNotification 通知表示切换结束，同时可以取BDCloudMediaPlayerMediaChangeEndResultUserInfoKey 的值判断切换是否成功。此时播放器缓冲播放完成后即会切换到新的码率显示。
当收到BDCloudMediaPlayerNaturalSizeChangedNotification 通知表示视频分辨率发生变化。

MP4等非嵌套码率的无缝切换

设置输入格式

Objectivec

1 - (void)setMediaInputType:(NSInteger)inputType {
2     [self.player setMediaItemsInputType:inputType];
3 }

设置多码率视频链接（注意这里和HLS的区别）

Objectivec

1 - (void)setMediaInputList:(NSArray *)inputList {
2     [self.player setMediaItems:inputList];
3 }

在收到BDCloudMediaPlayerPlaybackIsPreparedToPlayNotification通知后，调用获取多码率列表的接口，显示到UI。

Objectivec

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 }

用户根据对应索引切换到指定码率。

Objectivec

1 - (void)changeBitrate:(NSInteger)index {
2     [self.player setMediaItemIndex:index];
3 }

当收到BDCloudMediaPlayerMediaChangeStartNotification 通知表示视频开始切换。
当收到BDCloudMediaPlayerMediaChangeEndNotification 通知表示切换结束，同时可以取BDCloudMediaPlayerMediaChangeEndResultUserInfoKey 的值判断切换是否成功。此时播放器缓冲播放完成后即会切换到新的码率显示。
当收到BDCloudMediaPlayerNaturalSizeChangedNotification 通知表示视频分辨率发生变化。

播放HLS加密视频

百度智能云MCP服务支持转码成HLS加密视频。

不同的加密方式，播放时的方法略有不同：

PlayerBinding加密模式按普通视频播放即可。
自定义PlayerId、PlayerKey模式

播放之前需要先设置playerId和playerKey。

Objectivec

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。

Objectivec

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字段，例如User-Agent，可以使用接口setOptionValue。

Objectivec

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来响应下载任务的状态变化回调

Objectivec

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没有账号系统，可以传一个固定值)。

Objectivec

1    self.downloader = [[BDCloudMediaDownload alloc] initWithUser:@"<user>" delegate:self];

创建下载任务、开始下载

创建下载任务后，任务会进入到执行队列中，队列的最大并发数是4个。当超出最大并发数时，新创建的任务会处于等待执行的状态。

Objectivec

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:。

Objectivec

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}

任务的暂停和恢复

下载任务支持暂停和恢复:

暂停时，下载到本地的数据不会丢失;
恢复时，会从上次下载的位置继续下载。

Objectivec

1// 暂停任务
2[self.downloader suspendTask:task];
3
4// 恢复任务
5[self.downloader resumeTask:task];

断点续传

当App重新打开要继续上次未完成的下载时，需要先调用resumeUncompletedTasks方法(SDK内部会根据保存的任务状态，自动创建未完成的任务并加入下载队列)返回未完成的下载任务。

Objectivec

1self.downloader = [[BDCloudMediaDownload alloc] initWithUser:@"<user>" delegate:self];
2
3// 获取上次未下载完成的任务。
4self.tasks = [self.downloader resumeUncompletedTasks];

下载并显示缩略图

SDK 除了提供视频播放功能之外，还支持下载并显示缩略图。BDCloudSpriteManager提供缩略图相关接口。

注意：

缩略图的规则和获取需要配置MCP转码模板后转码才可使用。

Objectivec

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格式。

Objectivec

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消息后使用。对于同一个播放器示例，同一时刻只允许添加一个外挂字幕，添加新的外挂字幕会自动代替旧的外挂字幕。

Objectivec

1- (void)addExtSubtitleUrl:(NSString*)url;

外挂字幕成功读取后，会通过BDCloudMediaPlayerExtSubtitleOpenNotification消息通知，消息中使用BDCloudMediaPlayerExtSubtitleUrlKey记录相应的外挂字幕URL。

具体的字幕内容也会在BDCloudMediaPlayerTimedTextNotification消息中携带，这一点与内嵌字幕相同。

多音轨、多字幕切换

对于带有多个音轨、字幕轨的片源，可以通过下面的方式实现轨道的无缝切换。

先利用下面的接口获取当前片源所有的轨道信息

Objectivec

1(NSMutableArray *)getTrackInfo

返回的数组中每个元素为BDCloudMediaPlayerTrackInfo，在BDCloudMediaPlayerTrackInfo类中记录了每个轨道的媒体类型和语言信息。

根据轨道信息数组的下标进行切换

利用下面的接口可以执行轨道的选择和反选，传入的参数即对应第一步获取的轨道信息数组下标。

Objectivec

1 (void)selectTrack:(int)trackId
2 (void)deselectTrack:(int)trackId

查询当前选择的轨道

利用下面的接口可以获取当前选中的视频/音频/字幕轨，返回参数也对应第一步获取的轨道信息数组下标。

Objectivec

1(int)getSelectedTrack:(BDCloudTrackType)trackType

轨道变化回调

轨道的添加、切换都会通过BDCloudMediaPlayerTrackChangedNotification消息进行通知，该消息中BDCloudMediaPlayerTrackActionKey字段对应轨道添加或切换事件，BDCloudMediaPlayerTrackTypeKey字段对应轨道类型，BDCloudMediaPlayerTrackIdKey字段则对应轨道序号。

无缝切换与有感切换

播放器默认使能轨道的无缝切换（切换过程中无缓冲状态），如果需要切换为有感切换，可以在prepareToPlay之前设置下面的选项来实现

Objectivec

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方法的实现。

接口速查

功能列表

智能视频SDK VideoCreatingSDK

智能视频SDK VideoCreatingSDK

快速进阶

正确释放播放器

进度条相关

播放下一个视频

APM接入

多码率切换

多码率快速切换

多码率无缝切换

Master playlist 的HLS格式多码率无缝切换

MP4等非嵌套码率的无缝切换

播放HLS加密视频

设置HTTP请求的Header

下载HLS视频

普通HLS视频的下载

加密HLS视频的下载

任务的暂停和恢复

断点续传

下载并显示缩略图

网络视频加速

外挂字幕

多音轨、多字幕切换

AV1解码支持

常见错误码含义