进阶功能

播放

短视频列表播放

针对典型的短视频列表播放场景，iOS播放器SDK提供了完善的列表播放功能，结合预加载等机制大幅改善短视频的起播速度。长视频场景不建议使用该功能。

1. 创建播放器。
   创建AliListPlayer播放器。示例如下：

   self.listPlayer = [[AliListPlayer alloc] init];
   [listPlayer setTraceID:@"xxxxxx"];  //TraceID为设备或用户的唯一标识符，通常为imei或idfa

2. 可选：设置监听器。
   创建列表播放时，监听器为非必须配置，但如果不设置，将无法收到播放器的播放失败、播放进度等事件通知，因此，建议您设置。

   播放器支持设置多个监听器，其中onPlayerEvent、onError较为重要，建议您设置。

   /**
    @brief 错误代理回调
    @param player 播放器player指针
    @param errorModel 播放器错误描述，参考AliVcPlayerErrorModel
    */
   - (void)onError:(AliPlayer*)player errorModel:(AVPErrorModel *)errorModel {
       //提示错误，及stop播放
   }
   /**
    @brief 播放器事件回调
    @param player 播放器player指针
    @param eventType 播放器事件类型，@see AVPEventType
    */
   -(void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
       switch (eventType) {
           case AVPEventPrepareDone: {
               // 准备完成
           }
               break;
           case AVPEventAutoPlayStart:
               // 自动播放开始事件
               break;
           case AVPEventFirstRenderedStart:
               // 首帧显示
               break;
           case AVPEventCompletion:
               // 播放完成
               break;
           case AVPEventLoadingStart:
               // 缓冲开始
               break;
           case AVPEventLoadingEnd:
               // 缓冲完成
               break;
           case AVPEventSeekEnd:
               // 跳转完成
               break;
           case AVPEventLoopingStart:
               // 循环播放开始
               break;
           default:
               break;
       }
   }
   /**
    @brief 视频当前播放位置回调
    @param player 播放器player指针
    @param position 视频当前播放位置
    */
   - (void)onCurrentPositionUpdate:(AliPlayer*)player position:(int64_t)position {
       // 更新进度条
   }
   /**
    @brief 视频缓存位置回调
    @param player 播放器player指针
    @param position 视频当前缓存位置
    */
   - (void)onBufferedPositionUpdate:(AliPlayer*)player position:(int64_t)position {
       // 更新缓冲进度
   }
   /**
    @brief 获取track信息回调
    @param player 播放器player指针
    @param info track流信息数组，参考AVPTrackInfo
    */
   - (void)onTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
       // 获取多码率信息
   }
   /**
    @brief 字幕显示回调
    @param player 播放器player指针
    @param index 字幕显示的索引号
    @param subtitle 字幕显示的字符串
    */
   - (void)onSubtitleShow:(AliPlayer*)player index:(int)index subtitle:(NSString *)subtitle {
       // 获取字幕进行显示
   }
   /**
    @brief 字幕隐藏回调
    @param player 播放器player指针
    @param index 字幕显示的索引号
    */
   - (void)onSubtitleHide:(AliPlayer*)player index:(int)index {
       // 隐藏字幕
   }
   /**
    @brief 获取截图回调
    @param player 播放器player指针
    @param image 图像
    */
   - (void)onCaptureScreen:(AliPlayer *)player image:(UIImage *)image {
       // 预览，保存截图
   }
   /**
    @brief track切换完成回调
    @param player 播放器player指针
    @param info 切换后的信息，可参考AVPTrackInfo
    */
   - (void)onTrackChanged:(AliPlayer*)player info:(AVPTrackInfo*)info {
       // 切换码率结果通知
   }
   //...

3. 设置预加载个数。
   合理设置预加载个数，能够有效的提高起播的速度。示例如下：

   //设置预加载个数。总共加载的个数为： 1 + count*2。
   self.listplyer.preloadCount = 2;

4. 添加或移除多个播放源。
   列表播放支持两种播放源：VidSts播放和UrlSource播放。Url为视频的播放地址，vid为点播视频的音视频ID（VideoId）。示例如下：

   • Url：播放地址可以是第三方点播地址或阿里云点播服务中的播放地址。阿里云播放地址可以调用获取音视频播放地址接口获取。建议您集成点播服务端SDK来获取音视频播放地址，免去自签名的麻烦。调用接口获取音视频播放地址的示例请参见开发者门户。
   • Vid：音视频ID，可以在音视频上传完成后通过控制台（路径：媒资库 > 音/视频。）或服务端接口（搜索媒体信息）获取。

   //添加vid播放源
   [self.listPlayer addVidSource:videoId uid:UUIDString];
   //添加URL播放源
   [self.listPlayer addUrlSource:URL uid:UUIDString];
   //移除某个源
   [self.listPlayer removeSource:UUIDString];

   说明

   • 不支持VidAuth播放和VidMps播放方式。
   • uid是视频的唯一标志。用于区分视频是否一样。如果uid一样，则认为视频是一样的。如果播放出现串流的情况，请注意查看是不是在不同的界面设置了同一个uid。uid没有格式限制，可以是任意的字符串。
5. 设置显示View。
   如果播放源有画面，需要设置View到播放器中，用来显示画面。示例代码如下：

   self.listPlayer.playerView = self.simplePlayScrollView.playView;

6. 播放视频源。
   添加了一个或多个播放源之后，调用 moveTo便可以自动播放某个视频源。示例如下：

   //UrlSource播放方式时使用此接口
   - (BOOL) moveTo:(NSString*)uid;
   //VidSts播放方式时使用此接口，需要传递STS临时凭证和临时AK对，请提前获取，获取方式请参见创建RAM角色并进行STS临时授权。
   - (BOOL) moveTo:(NSString*)uid accId:(NSString*)accId accKey:(NSString*)accKey token:(NSString*)token region:(NSString*)region;

7. 播放上一个、下一个视频。
   播放器提供了 moveToPrev， moveToNext接口用于播放上一个，下一个视频。示例如下：

   UrlSource播放源 VidSts播放源

   //移动到下一个视频。
   - (BOOL) moveToNext;
   //移动到上一个视频。
   - (BOOL) moveToPre;

   //移动到下一个视频。
   - (BOOL) moveToNext:(NSString*)accId accKey:(NSString*)accKey token:(NSString*)token region:(NSString*)region;
   // 移动到上一个视频。
   - (BOOL) moveToPre:(NSString*)accId accKey:(NSString*)accKey token:(NSString*)token region:(NSString*)region;

外挂字幕

iOS播放器SDK支持添加和切换外挂字幕，现已支持SRT、SSA、ASS、VTT这4种格式的字幕。示例如下：

1. 创建显示字幕的View。
   根据不同的字幕格式创建不同的View。

   // 初始化自定义subTitleLabel
   UILabel *subTitleLabel = [[UILabel alloc] initWithFrame:frame];
   // 将字幕添加至自定义的superView，superView是用户自定义的界面存在的父视图
   [superView addSubview:subTitleLabel];

2. 设置字幕相关监听。

   //  外挂字幕被添加
   - (void)onSubtitleExtAdded:(AliPlayer*)player trackIndex:(int)trackIndex URL:(NSString *)URL {}
   // 字幕头信息回调
   - (void)onSubtitleHeader:(AliPlayer *)player trackIndex:(int)trackIndex Header:(NSString *)header {}
   // 字幕显示回调
   - (void)onSubtitleShow:(AliPlayer*)player trackIndex:(int)trackIndex subtitleID:(long)subtitleID subtitle:(NSString *)subtitle {
       subTitleLabel.text = subtitle;
       subTitleLabel.tag = subtitleID;
   }
   // 字幕隐藏回调
   - (void)onSubtitleHide:(AliPlayer*)player trackIndex:(int)trackIndex subtitleID:(long)subtitleID {
       [subTitleLabel removeFromSuperview];
   }

3. 添加字幕。

   [self.player addExtSubtitle:URL];

4. 切换字幕。

   [self.player selectExtSubtitle:trackIndex enable:YES];

纯音频播放

AVPConfig *config = [self.player getConfig];
config.disableVideo = YES;
[self.player setConfig:config];

软硬解切换

//开启硬解，默认开启
self.player.enableHardwareDecoder = YES;

-(void)onPlayerEvent:(AliPlayer*)player eventWithString:(AVPEventWithString)eventWithString description:(NSString *)description {
    if (eventWithString == EVENT_SWITCH_TO_SOFTWARE_DECODER) {
        //切换到软解
    }
}

网络自适应切换视频清晰度

AVPMediaInfo *info = [self.player getMediaInfo];
NSArray<AVPTrackInfo*>* tracks = info.tracks;

//多码率切换
[self.player selectTrack:track.trackIndex];
//多码率切换并自适应
[self.player selectTrack:SELECT_AVPTRACK_TYPE_VIDEO_AUTO];

- (void)onTrackChanged:(AliPlayer*)player info:(AVPTrackInfo*)info {
    if (info.trackType == AVPTRACK_TYPE_VIDEO) {
        // video changed
    }
    // etc
}

截图

//截图回调
- (void)onCaptureScreen:(AliPlayer *)player image:(UIImage *)image {
    // 处理截图
}
//截取当前播放的画面
aliyunVodPlayer.snapshot();

试看

iOS播放器SDK通过配合点播服务配置，可以实现试看功能，支持VidSts和VidAuth（视频点播推荐使用此方式）两种播放方式。如何配置和使用试看功能，请参见点播试看。

AVPVidStsSource *source = [[AVPVidStsSource alloc] init];
....
VidPlayerConfigGenerator* vp = [[VidPlayerConfigGenerator alloc] init];
[vp setPreviewTime:20];//20秒试看
source.playConfig = [vp generatePlayerConfig];//设置给播放源
...

设置Referer

//先获取配置
AVPConfig *config = [self.player getConfig];
//设置referer
config.referer = referer;
....//其他设置
//设置配置给播放器
[self.player setConfig:config];

设置UserAgent

//先获取配置
AVPConfig *config = [self.player getConfig];
//设置userAgent
config.userAgent = userAgent;
....//其他设置
//设置配置给播放器
[self.player setConfig:config];

配置网络重试时间和次数

//先获取配置
AVPConfig *config = [self.player getConfig];
//设置网络超时时间，单位ms
config.networkTimeout = 5000;
//设置超时重试次数。每次重试间隔为networkTimeout。networkRetryCount=0则表示不重试，重试策略app决定，默认值为2
config.networkRetryCount = 2;
....//其他设置
//设置配置给播放器
[self.player setConfig:config];

配置缓存和延迟控制

//先获取配置
AVPConfig *config = [self.player getConfig];
//最大延迟。注意：直播有效。当延时比较大时，播放器SDK内部会追帧等，保证播放器的延时在这个范围内。
config.maxDelayTime = 5000;
// 最大缓冲区时长。单位ms。播放器每次最多加载这么长时间的缓冲数据。
config.maxBufferDuration = 50000;
//高缓冲时长。单位ms。当网络不好导致加载数据时，如果加载的缓冲时长到达这个值，结束加载状态。
config.highBufferDuration = 3000;
// 起播缓冲区时长。单位ms。这个时间设置越短，起播越快。也可能会导致播放之后很快就会进入加载状态。
config.startBufferDuration = 500;
//其他设置
//设置配置给播放器
[self.player setConfig:config];

设置HTTP Header

//先获取配置
AVPConfig *config = [self.player getConfig];
//定义header
NSMutableArray *httpHeaders = [[NSMutableArray alloc] init];
//比如使用httpdns时，需要设置Host。
[httpHeaders addObject:@"Host:example.com"];
//设置header
config.httpHeaders = httpHeaders;
....//其他设置
//设置配置给播放器
[self.player setConfig:config];

画中画

- (void)onPlayerEvent:(AliPlayer *)player eventType:(AVPEventType)eventType {
    switch (eventType) {
        case AVPEventPrepareDone:
        {
            [self.player setPictureInPictureEnable:YES];
        }
            break;
        default:
            break;
    }
}

性能

本地缓存

iOS播放器SDK提供了本地缓存的功能，能够让用户重复播放视频时，提高起播速度、提高seek速度、减少卡顿，也能达到节省流量的目的。

开启本地缓存

/**
 * 开启本地缓存，开启之后，就会缓存到本地文件中。
 * @param enable：本地缓存功能开关。true：开启，false：关闭，默认关闭。
 * @param maxBufferMemoryKB：新版本已废弃，暂无作用。
 * @param localCacheDir：必须设置，本地缓存的文件目录，为绝对路径。
 */
[AliPlayerGlobalSettings enableLocalCache:true maxBufferMemoryKB:1024 localCacheDir:@""];

/**
 @brief 本地缓存文件自动清理相关的设置。
 @param expireMin：新版本已废弃，暂无作用。
 @param maxCapacityMB：最大缓存容量。单位：兆，默认值20GB，在清理时，如果缓存总容量超过此大小，则会以cacheItem为粒度，按缓存的最后时间排序，一个一个的删除最旧的缓存文件，直到小于等于最大缓存容量。
 @param freeStorageMB：磁盘最小空余容量。单位：兆，默认值0，在清理时，同最大缓存容量，如果当前磁盘容量小于该值，也会按规则一个一个的删除缓存文件，直到freeStorage大于等于该值或者所有缓存都被清理掉。
 */
[AliPlayerGlobalSettings setCacheFileClearConfig:0 maxCapacityMB:0 freeStorageMB:0];

/**
 * 获取加载url的hash值回调，用来做url唯一的id，必须要保证每个url都不一样。
 */

// 需要自己实现这个函数并把函数指针交给setCacheUrlHashCallback
static NSString *CaheUrlHashHandle(NSString *url) {
    return @"xxx";
}

[AliPlayerGlobalSettings setCacheUrlHashCallback:&CaheUrlHashHandle];

开启或关闭单个URL的本地缓存

//先获取配置
AVPConfig *config = [self.player getConfig];
//是否针对播放的URL开启本地缓存，默认值为true。当AliPlayerGlobalSettings处的本地缓开启时，且同时开启此处的本地缓存，即设置为true，该URL的本地缓存才会生效；若此处设置为false，则关闭该URL的本地缓存。
config.enableLocalCache = false;
....//其他设置

//设置配置给播放器
[self.player setConfig:config];

大缓存

通过设置数据的最大缓冲区时长可以在播放视频时通过缓存视频数据到内存中，从而提高播放性能和观看体验。当最大缓冲区时长设置过大时，会造成缓冲区对内存的消耗。通过启用大缓存，可以将视频数据缓存到文件中，从而降低内存的占用，进一步提高播放器性能。

当mMaxBufferDuration设置超过50000 ms时，通过开启本地缓存触发大缓存功能自动启用。操作流程如下：

1. 开启全局本地缓存。
   本地缓存功能默认关闭，如需使用，需要手动开启。通过 AliPlayerGlobalSettings中的 enableLocalCache控制。代码示例请参见 本地缓存中的 开启本地缓存。
2. 开启URL的本地缓存。
   代码示例请参见 本地缓存中的 开启或关闭单个URL的本地缓存。

预加载

iOS播放器SDK提供预加载功能，是对本地缓存功能的升级，通过设置视频缓存的内存占用大小，更能提升视频的起播速度。

[AliPlayerGlobalSettings enableNetworkBalance: false];

1. 开启本地缓存功能，详细操作请参见本地缓存。
2. 获取AliMediaLoader实例。

   AliMediaLoader实例为单例，即无论获取多少次，创建的都是同一个实例。

   [AliMediaLoader shareInstance];

3. 配置AliMediaLoader。

   //配置回调，并开始加载。
   // url：为视频文件地址。 duration：加载的时长大小，单位：毫秒。
   [[AliMediaLoader shareInstance] load:obj.url duration:1000];
   // 设置回调代理
   [[AliMediaLoader shareInstance] setAliMediaLoaderStatusDelegate:self];
   
   @protocol AliMediaLoaderStatusDelegate <NSObject>
   @optional
   
   /**
    @brief 错误回调
    @param url 加载url
    @param code 错误码
    @param msg 错误描述
    */
   - (void)onError:(NSString *)url code:(int64_t)code msg:(NSString *)msg;
   
   /**
    @brief 完成回调
    @param url 加载url
    */
   - (void)onCompleted:(NSString *)url;
   
   /**
    @brief 取消回调
    @param url 加载url
    */
   - (void)onCanceled:(NSString *)url;
   
   @end

4. 可选：删除加载文件。
   可按需删除加载文件，以节省空间。iOS播放器SDK不提供删除接口，需要在App删除加载目录下的文件。

获取下载速度

- (void)onCurrentDownloadSpeed:(AliPlayer *)player speed:(int64_t)speed {
    int speed_ = speed;
}

网络特性

使用HTTP/2

[AliPlayerGlobalSettings setUseHttp2:true];

视频下载

iOS播放器SDK提供了点播服务视频的下载功能，允许用户通过阿里云播放器将视频缓存至本地观看。同时，提供了普通下载和安全下载两种下载方式。

• 普通下载：下载后的视频数据未经过阿里云加密，用户可以用第三方播放器播放。
• 安全下载：下载后的视频数据经过阿里云加密。第三方播放器无法播放。仅支持使用阿里云的播放器进行播放。

使用说明

• 仅VidSts和VidAuth方式支持视频下载功能。
• 使用播放器的视频下载功能，需要在点播控制台开启并配置下载模式，详细操作请参见下载设置。
• 视频下载支持断点续传。

操作步骤

1. 可选：配置安全下载的加密校验文件。仅安全下载需要配置，普通下载无需配置。
   说明 请确保配置的加密校验文件与App信息一致，否则会导致视频下载失败。

   如果设置为安全下载方式，则需要将在点播控制台生成的密钥文件配置到播放器SDK中，用于视频下载和播放的解密验证，密钥文件的生成请参见 安全下载。

   建议在Application中配置一次即可，示例如下：

   NSString *encrptyFilePath = [[NSBundle mainBundle] pathForResource:@"encryptedApp" ofType:@"dat"];
   [AliPrivateService initKey:encrptyFilePath];

2. 创建并设置下载器。
   示例如下：

   AliMediaDownloader *downloader = [[AliMediaDownloader alloc] init];
   [downloader setSaveDirectory:self.downLoadPath];
   [downloader setDelegate:self];

3. 设置监听事件。
   下载器提供了多个事件监听。示例如下：

   -(void)onPrepared:(AliMediaDownloader *)downloader mediaInfo:(AVPMediaInfo *)info {
       //准备下载项成功
   }
   -(void)onError:(AliMediaDownloader *)downloader errorModel:(AVPErrorModel *)errorModel {
       //下载出错
   }
   -(void)onDownloadingProgress:(AliMediaDownloader *)downloader percentage:(int)percent {
       //下载进度百分比
   }
   -(void)onProcessingProgress:(AliMediaDownloader *)downloader percentage:(int)percent {
       //处理进度百分比
   }
   -(void)onCompletion:(AliMediaDownloader *)downloader {
       //下载成功
   }

4. 准备下载源。
   通过 preapre方法准备下载源。下载源支持AVPVidStsSource和AVPVidAuthSource两种。以AVPVidStsSource举例，示例如下：

   //创建VidSts
   AVPVidStsSource* stsSource = [[AVPVidStsSource alloc] init];
   stsSource.vid = source.vid;//视频vid
   stsSource.region = DEFAULT_SERVER.region;//接入区域
   stsSource.securityToken = DEFAULT_SERVER.securityToken;//安全token
   stsSource.accessKeySecret = DEFAULT_SERVER.accessKeySecret;//临时akSecret
   stsSource.accessKeyId = DEFAULT_SERVER.accessKeyId;//临时akId
   //准备下载源
   [downloader prepareWithVid:stsSource];

5. 准备成功后，选择下载项。
   准备成功后，会回调 onPrepared方法。返回的TrackInfo中会包含各视频流的清晰度等信息，请选择一个Track进行下载，示例如下：

   -(void)onPrepared:(AliMediaDownloader *)downloader mediaInfo:(AVPMediaInfo *)info {
       NSArray<AVPTrackInfo*>* tracks = info.tracks;
       //比如：下载第一个TrackInfo
       [downloader selectTrack:[tracks objectAtIndex:0].trackIndex];
   }

6. 更新下载源并开始下载。
   为了防止VidSts和VidAuth过期，建议更新下载源的信息后开始下载。示例如下：

   //更新下载源
   [downloader updateWithVid:vidSource]
   //开始下载
   [downloader start];

7. 下载成功或失败后，释放下载器。
   下载成功后，调用 destroy释放下载器。

   [self.downloader destroy];
   self.downloader = nil;

视频加密播放

Native RTS播放

iOS播放器SDK集成Native RTS SDK实现Native端低延时直播功能，详情请参见阿里云播放器SDK集成Native RTS SDK实现说明（iOS端）。

异常处理

使用阿里云播放器播放视频发生异常时，可借助单点探查功能快速定位问题，详细内容，请参见单点追查。

相关文档

• 接口说明
• 错误码查询
• iOS播放器常见问题