进阶功能

播放

短视频列表播放

针对典型的短视频列表播放场景，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对，请提前获取，获取方式请参见创建角色并进行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];

性能

本地缓存

AVPCacheConfig *config = [[AVPCacheConfig alloc] init];
//开启缓存功能
config.enable = YES;
//能够缓存的单个文件最大时长。超过此长度则不缓存
config.maxDuration = 100;
//缓存目录的位置，需替换成app期望的路径
config.path = @"please use your cache path here";
//缓存目录的最大大小。超过此大小，将会删除最旧的缓存文件
config.maxSizeMB = 200;
//设置缓存配置给到播放器
[self.player setCacheConfig:config];

-(void)onPlayerEvent:(AliPlayer*)player eventWithString:(AVPEventWithString)eventWithString description:(NSString *)description {
    if (eventWithString == EVENT_PLAYER_CACHE_SUCCESS) {
        //缓存成功事件。
    }else if (eventWithString == EVENT_PLAYER_CACHE_ERROR) {
        //缓存失败事件。
    }
}

预加载

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

1. 开启本地缓存功能。
   本地缓存功能默认关闭，如需使用，需要手动开启。通过AliPlayerGlobalSettings中的enableLocalCache控制。

   /**
    * 开启本地缓存，开启之后，就会缓存到本地文件中。
    * @param enable：本地缓存功能开关。true：开启，false：关闭，默认关闭。
    * @param maxBufferMemoryKB：必须设置，设置能够缓存的单个视频源文件的最大内存占用大小，超过此大小则不缓存，单位：KB。
    * @param localCacheDir：必须设置，本地缓存的文件目录，为绝对路径。
    */
   [AliPlayerGlobalSettings enableLocalCache:true maxBufferMemoryKB:1024 localCacheDir:@""];
   
   /**
    @brief 本地缓存文件自动清理相关的设置
    @param expireMin：设置缓存的过期时间。单位：分钟，默认值30天，过期的缓存不管容量多大，都会被删除。
    @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带有鉴权参数，预加载和播放时鉴权参数会变化，可以将URL的鉴权参数去掉后再计算md5值。例如：带有鉴权参数的视频播放URL为http://****.mp4?aaa，则加载时使用http://****.mp4计算md5值。
   • 如果服务器同时支持HTTP和HTTPS协议，但是不同的协议指向的媒体文件是同一个，则可以将请求头去掉或者统一后再计算md5值。例如：
     • 视频播放URL为https://****.mp4和http://****.mp4，则加载时使用****.mp4计算md5值。
     • 视频播放URL为https://****.mp4，加载时统一为http://****.mp4后再计算md5值。
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];

视频下载

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

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

   下载SDK支持私有加密的下载。为了保证安全性，需要配置一个加密校验文件到播放器。（建议在Application中配置一次即可）。示例如下：

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

   注意 如果是安全下载，并且加密校验文件与App信息不一致，会导致下载失败。
2. 设置监听事件。
   下载器提供了多个事件监听。示例如下：

   -(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 {
       //下载成功
   }

3. 准备下载源。
   通过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];

4. 准备成功后选择下载项。
   准备成功后，会回调onPrepared方法。选择某个Track进行下载：

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

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

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

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

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

视频加密播放

Native RTS播放

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

异常处理

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

相关文档

• 接口说明
• 错误码查询