iOS播放器SDK开发集成

1 概述

1.1 SDK简介

1.1.1 SDK业务简介

网易云视频播放器iOS SDK(以下简称“播放器 SDK”)是网易官网推出的软件开发工具包，提供简单，便捷的开发接口，帮助开发者在iOS平台上快速开发播放器应用。具有稳定、高效、功能全面的特点。

1.1.2 SDK技术简介

播放器 SDK 由以下所示的结构组成。其中，虚线框是播放器SDK大的功能模块，包括Network，Demuxer，Decoder，Sync和Output。实线框是每个功能模块的子模块。

在以上的五个功能模块中，Network、Demuxer和Decoder的软解码部分依赖ffmpeg。

1.2 设备和系统要求

支持iOS 7.0及以上系统
支持的CPU架构：armv7、arm64、i386、x86_64

1.3 功能特性

支持 HTTP/HTTPS、RTMP、HLS 协议的流媒体播放
支持常见的音视频文件播放（MP4、flv、MP3 等）
支持多种画面预览模式（填充，拉伸，裁剪）
支持硬件解码（iOS 8.0及以上）
支持音频后台播放
可高度定制化播放器UI控件
优化 RTMP 直播首屏秒开
优化 RTMP 直播累积延时
支持YUV／PCM回调
支持加密视频播放
支持显示播放信息（视频／音频）
支持点播倍速播放
支持多种缓冲策略
支持多实例播放

2 开发准备

2.1 准备工作

下载最新版的播放器SDK。下载地址1 下载地址2
准备 xcode 集成开发环境。
准备 iOS 运行环境：iOS 7.0 及以上系统，armv7、arm64、x86_64的CPU架构（目前暂不支持i386架构）。

2.2 集成SDK

本文是根据官网的播放器 Demo 来介绍 SDK 的集成，可在网易云官网下载最新的播放器 iOS Demo，来查看更多的实现细节。下载地址1 下载地址2

2.2.1 组件及资源

开发者需要将播放器 SDK 集成到应用中，包括静态库文件和相关的头文件。如下图所示：

播放器 SDK 包含 demo、libs 两个部分，在网易云视频官网可以下载 Demo 和 SDK 包。下载地址1 下载地址2

demo部分： 里面包含一个示例工程，通过 NELivePlayerViewController 来调用相关接口进行接入的例子。
libs目录： 存放播放器 SDK 的静态库文件和头文件，包括真机版本和模拟器(x86_64)版本，文件如下：


  NELivePlayerFramework.framework

2.2.1 集成准备

创建ViewController，如下图所示：
Subclass选择UIViewController，如下图所示：

2.2.2 快速集成

方法 1（推荐）：Cocoapods导入

执行 pod search NELivePlayer 搜索资源
如果搜索不到，请执行下述命令清除搜索列表缓存
```
 rm ~/Library/Caches/CocoaPods/search_index.json
```
Podfile 文件中增加如下代码：
```
 pod 'NELivePlayer', '~> 1.7.0'
```

方法 2 ：手动导入库文件

将 SDK 中的lib目录下framework导入到 App 工程。
集成添加播放器 SDK 到 App 工程，在TARGETS->Build Settings->Search Paths中设置。

注意: 直接集成Framework的时候，打包如果遇到下图的问题时，请按照以下方法处理：
1. 将Demo中的 StripFrameworks.sh 脚本文件导入到工程中
2. 在 Build Phases 中增加 Run Script 过程，填入如下命令(XXX表示脚本所在的相对路径)：
```
  "${SRCROOT}/xxx/StripFrameworks.sh"
```

2.2.3 使用

导入头文件。头文件存放的位置可以根据开发者的实际情况指定。

```objc
#import <NELivePlayerFramework/NELivePlayerFramework.h>
```

3 API概览

3.1 全局方法

类别	API名称	功能
设置日志等级	+ (void)setLogLevel: (NELPLogLevel) logLevel	设置的日志级别
SDK版本信息	+ (void)getSDKVersion	查询SDK的版本信息
日志文件路径	+ (void)getLogPath	查询日志文件路径
日志信息回调	+ (void)setLogCallback: (NELivePlayerLogCallback)logCallBack	设置日志回调
增加预调度任务	+ (void)addPreloadUrls:	增加预调度任务
删除预调度任务	+ (void)removePreloadUrls:	删除预调度任务
查询预调度任务	+ (void)queryPreloadTasks:	查询预调度任务
设置预调度结果有效期	+ (void)setPreloadResultValidityS:	预调度结果有效期
设置外部配置Audiosession	+ (void)setExternConfigAudioSession:	是否外部配置Audiosession

3.2 初始化方法

类别	API名称	功能
创建实例1	- (instancetype)init + (instancetype)new	系统初始化方法, 需要配合setUrl:接口使用
创建实例2	- (instancetype)initWithContentURL: (NSURL ) aUrl error: (NSError *) error	aUrl：待播放的URL error：返回失败原因
创建实例3	- (instancetype)initWithContentURL: (NSURL ) aUrl config: (NELPUrlConfig )config error: (NSError **) error	aUrl：待播放的URL config: 缓存和解密配置 error：返回失败原因

3.3 操作方法

类别	API名称	功能
显示	（属性）UIView *view	SDK生成, 只用于显示视频图像。
准备播放	- (void) prepareToPlay	初始化视频文件为播放做准备。设置数据源之后，播放前调用。
播放	- (void) play	播放。收到Prepare通知之后调用。
暂停	- (void) pause	暂停。直播该接口无效，仅针对点播。
关闭	- (void) shutdown	关闭。释放播放器之前调用，用于播放器资源释放。
截图	- (UIImage *)getSnapshot	截图。收到Prepare通知之后调用，纯音频文件该接口无效。
换源（常规视频）	- (int)switchContentUrl: (NSURL *) aUrl	播放过程中切换播放地址。注：只能用于常规视频的相互切换。
换源（通用）	- (int)switchContentUrl: (NSURL ) aUrl config:(NELPUrlConfig )config	播放过程中切换播放地址。
换源（加密视频） (即将废弃)	- (void)switchDecryptionUrl:(NSURL )aUrl transferToken:(NSString )transferToken accid:(NSString )accid appKey:(NSString )appKey token:(NSString *)token complete: (void(^)(NELPKeyCheckResult ret))complete	加密视频，播放过程中切换播放地址。 aUrl: 目标地址。 transferToken: 获取密钥的令牌。 accid: 视频云用户创建的其子用户id。 appKey: 开发者平台分配的AppKey。 token: 视频云用户子用户的token。 complete: 异步返回密钥检测结果。注：只能用于服务端管理密钥的类的加密视频相互切换。
换源（加密视频）（已知密钥） (即将废弃)	- (void)switchDecryptionKeyUrl:(NSURL )aUrl key:(NSString )key complete: (void(^)(NELPKeyCheckResult ret))complete	已知密钥的加密视频，播放过程中切换播放地址。 aUrl: 目标地址。 complete: 异步返回密钥检测结果。注：只能用于已知密钥视频的相互切换。

3.4 参数设置／查询

类别	API名称	功能
设置播放的Url	- (NSError )setPlayUrl: (NSURL ) url	url: 播放Url 注：与创建实例方法1一同使用，仅限初始化后调用，不可用于URL切换。
设置播放的Url (带参)	- (NSError )setPlayUrl: (NSURL ) url config: (NELPUrlConfig *)config	url: 播放Url config: 缓存和解密配置注：与创建实例方法1一同使用，仅限初始化后调用，不可用于URL切换。
设置缓冲策略	- (void)setBufferStrategy: (NELPBufferStrategy) bufferStrategy	bufferStrategy: 播放时的缓冲策略注1：静态参数，在播放器初始化后 prepareToPlay之前调用。注2：直播类缓存2M，点播类缓存200M。
设置缓冲区大小	- (void)setBufferSize:(int)size	size: 缓冲区大小注1：动态参数，初始化之后随时可以设置。注2: 只针对NELPAntiJitte缓冲模式有效。注3: 5M - 150M
设置精确seek开关	- (void)setAccurateSeek:(BOOL)isOpen	isOpen: 是否开启注1：静态参数，需在开始播放之前设置。注2: 默认：开。
设置开启硬件编码	- (void)setHardwareDecoder: (BOOL) isOpen	isOpen：开启 or 关闭注：静态参数，需在开始播放之前设置。
设置拉流超时时间	- (void)setPlaybackTimeout:(long)timeout	timeout：超时时长。取值：[0, 30000] 毫秒注：静态参数，需在开始播放之前设置。
设置是否自动播放	（属性）BOOL shouldAutoplay	收到Prepared通知后是否需要调用play。 shouldAutoplay：自动 or 手动。注：静态参数，需在开始播放之前设置。
设置重试配置	- (void)setRetryConfig:(NELPRetryConfig *)config;	注：静态参数，需在开始播放之前设置。
设置后台是否暂停	- (void)setPauseInBackground:(BOOL)pause	pause: YES: 后台暂停 NO：后台继续注1：设置NO。SDK不做前后台事件监听。设置YES。点播在后台暂停，回到前台恢复。直播在后台停止拉流，回到前台重新拉流注2：动态参数，初始化之后随时可以设置。
设置屏幕显示模式	- (void)setScalingMode: (NELPMovieScalingMode) aScalingMode	aScalingMode：显示填充模式注：动态参数，初始化之后随时可以设置。
设置解密信息	- (void)setDecryptionTransferToken: (NSString ) transferToken accid:(NSString ) accid appKey:(NSString ) appKey token:(NSString ) token complete:(void(^)(NELPKeyCheckResult ret))complete	transferToken：密钥的令牌。 accid：视频云用户创建的其子用户id。 appKey：开发者平台分配的AppKey token：视频云用户子用户的token complete：异步返回密钥检测结果注1：不可与setDecryptionKey同时使用。注2：静态参数。开始播放之前设置。
设置FLV解密信息（已知密钥）	- (void)setDecryptionKey:(NSString *) key complete:(void(^)(NELPKeyCheckResult ret))complete	key：密钥。 complete：异步返回密钥检测结果注1：不可与setDecryptionTransferToken 同时使用。注2：静态接口。开始播放之前设置。
设置PCM数据回调格式	- - (int)setAudioPcmDataConfig: (NELivePlayerPcmConfig *) audioRawDataCB	解码后的音频数据回调格式。注：静态参数。开始播放之前设置。
设置PCM数据回调	- (int)registerGetAudioRawDataCB: (NELPAudioRawDataCB) audioRawDataCB	解码后的音频数据回调。注：动态参数，初始化之后随时可以设置。
设置YUV数据回调	- (int)registerGetVideoRawDataCB: (NELPVideoFormat) neVFormat and: (NELPVideoRawDataCB) videoRawDataCB	解码后的视频数据回调。 neVFormat：YUV格式注：仅限软解码方式。注：动态参数，初始化之后随时可以设置。
设置静音	- (void)setMute: (BOOL)isMute	isMute：YES：静音 NO：非静音注：动态参数，初始化之后随时可以设置。
设置音量	- (void)setVolume:(float)volume	volume：音量大小。[0, 1] 注：动态参数，初始化之后随时可以设置。
设置播放速度	（属性）float playbackSpeed	playbackSpeed：播放速度。[0.5, 2.0] 注1：仅针对点播文件生效。注2：动态参数，初始化之后随时可以设置。
设置/获取当前播放时间	（属性）NSTimeInterval currentPlaybackTime	get方法返回当前播放时间点，单位秒. set方法用于seek操作，单位秒。注1：直播不支持seek操作。注2：接收到Prepared通知之后才允许seek。
查询文件时长	（属性）NSTimeInterval duration	get方法返回文件时长，单位秒。注：直播该接口返回0。
查询缓冲的时长	（属性）NSTimeInterval playableDuration	get方法返回已经缓冲的视频时长，单位秒。注：若网络断开，只能播放到该时刻。
查询视频文件是否完成初始化	（属性）BOOL isPreparedToPlay	调用prepareToPlay方法后，进行视频初始化操作如果完成初始化，会发送Prepared通知，并将isPreparedToPlay置为YES
查询当前是否正在播放	（属性）(BOOL)isPlaying	YES：正在播放 NO：未在播放
查询当前播放状态	（属性）NELPMoviePlaybackState playbackState	播放状态变化： 1）调用initWithContentURL -> Paused状态 2) 调用prepareToPlay -> Playing状态 3）调用setCurrentPlaybackTime -> seeking状态 4）调用shutdown -> Stopped状态
查询当前加载状态	（属性）NELPMovieLoadState loadState	加载状态变化： 1) 调用prepareToPlay -> Playable状态 2）缓冲开始 -> Stalled状态 3）缓冲结束 -> PlaythroughOK状态
查询视频信息	- (void)getVideoInfo: (NELPVideoInfo *) videoInfo	获取视频信息。注：收到Prepared之后，可以查询。
查询音频信息	- (void)getAudioInfo: (NELPAudioInfo *) audioInfo	获取音频信息。注：收到Prepared之后，可以查询。
查询真实时间戳	（属性）NSTimeInterval currentPlaybackRealTime	（直播校时方案一）获取CDN透传的时间。注：收到Prepared之后，可以查询。
监听真实时间戳	- (void)setRealTimeListenerWithIntervalMS: (NSTimeInterval)intervalMS callback:(NELPCurrentTimestampCallCB)callback	（直播校时方案一）轮询真实时间戳。 intervalMS：查询间隔，单位毫秒 callback：查询结果注：收到Prepared之后，可以查询。
查询同步时间戳	（属性）NSTimeInterval currentSyncTimestamp	（直播校时方案二）获取推流时间戳。注：收到Prepared之后，可以查询。
监听同步时间戳	- (void)setSyncTimestampListenerWithIntervalMS: (NSTimeInterval)intervalMS callback:(NELPCurrentTimestampCallCB)callback	（直播校时方案二）轮询同步时间戳。 intervalMS：查询间隔，单位毫秒 callback：查询结果注：收到Prepared之后，可以查询。
透传自定义信息回调	- (void)registerSyncContentCB: (NELPSyncContentCB)contentCB	透传的自定义信息显示。 contentCB：信息播放回调
设置外挂字幕	- (NSError )setLocalSubtitleFile: (NSString )file	设置外挂字幕。 file：字幕路径注： 1. 目前只支持SRT格式字幕。 2. 设置为NULL关闭字幕。 3. 字幕中的特殊格式需要应用层处理
字幕显示回调	- (void)registSubtitleStatBlock:(NELivePlayerSubtitleBlock)block	设置字幕显示回调。 block：字幕显示／隐藏回调

3.5 通知介绍

通知	说明
NELivePlayerDidPreparedToPlayNotification	调用prepareToPlay之后，文件初始化完成后发出
NELivePlayerLoadStateChangedNotification	加载状态发生改变时发出
NELivePlayerPlaybackFinishedNotification	播放完成时发送。携带UserInfo字典: { NELivePlayerPlaybackDidFinishReasonUserInfoKey : [NSNumber], NELivePlayerPlaybackDidFinishErrorKey : [NSNumber] } NELivePlayerPlaybackDidFinishReasonUserInfoKey：结束原因 NELivePlayerPlaybackDidFinishErrorKey：错误码。播放完成时，无此字段。
NELivePlayerPlaybackStateChangedNotification	播放状态发生改变时发出
NELivePlayerHardwareDecoderOpenNotification	硬件解码器打开后发出
NELivePlayerFirstVideoDisplayedNotification	第一帧视频显示时发出
NELivePlayerFirstAudioDisplayedNotification	第一帧音频播放时发出
NELivePlayerReleaseSueecssNotification	资源释放时发出
NELivePlayerMoviePlayerSeekCompletedNotification	seek完成时发出，仅用于点播。携带UserInfo字典: { NELivePlayerMoviePlayerSeekCompletedErrorKey : [NSNumber], NELivePlayerMoviePlayerSeekCompletedTargetKey : [NSNumber] } NELivePlayerMoviePlayerSeekCompletedErrorKey：seek失败原因 NELivePlayerMoviePlayerSeekCompletedTargetKey：seek完成时的时间
NELivePlayerHttpCodeResponseNotification	播放过程中的Http状态信息通知。携带UserInfo字典。 NELivePlayerHttpCodeResponseInfoKey：HTTP状态信息key，value类型详见头文件
NELivePlayerRetryNotification	播放器失败重试通知。携带UserInfo字典。 NELivePlayerPlaybackDidRetryCountKey：播放器失败当前的重试次数

总体参数介绍

枚举值参数介绍

日志级别 NELPLogLevel

参数	说明
NELP_LOG_DEFAULT	log输出模式：默认
NELP_LOG_VERBOSE	log输出模式：输出详细
NELP_LOG_DEBUG	log输出模式：输出调试信息
NELP_LOG_INFO	log输出模式：输出标准信息
NELP_LOG_WARN	log输出模式：输出警告
NELP_LOG_ERROR	log输出模式：输出错误
NELP_LOG_FATAL	log输出模式：log输出模式：一些错误信息，如头文件找不到，非法参数使用
NELP_LOG_SILENT	log输出模式：不输出

错误码对照 NELPPLayerErrorCode

参数	说明
NELP_INIT_URL_FORMAT_ERROR	初始化的URL格式错误
NELP_INIT_URL_ISPUSH_ERROR	初始化的URL是推流地址
NELP_INIT_URL_PARSE_ERROR	初始化的URL解析错误（idx文件）
NELP_DECRYPTION_UNSUPPORT_PROTOCAL_ERROR	解密视频，协议不支持
NELP_DECRYPTION_KEY_CHECK_ERROR	解密视频，密钥错误
NELP_DECRYPTION_INPUT_INVALIED_ERROR	解密视频，输入错误
NELP_DECRYPTION_GET_KEY_TIMEOUT_ERROR	解密视频，获取密钥超时
NELP_DECRYPTION_UNKNOWN_ERROR	解密视频，未知错误
NELP_PLAY_HTTP_CONNECT_ERROR	播放过程中，HTTP连接失败
NELP_PLAY_RTMP_CONNECT_ERROR	播放过程中，RTMP连接失败
NELP_PLAY_STREAM_PARSE_ERROR	播放过程中，解析失败
NELP_PLAY_BUFFING_ERROR	播放过程中，缓冲失败
NELP_PLAY_AUDIO_OPEN_ERROR	播放过程中，音频相关操作初始化失败
NELP_PLAY_VIDEO_OPEN_ERROR	播放过程中，视频相关操作初始化失败
NELP_PLAY_STREM_IS_ERROR	播放过程中，没有音视频流
NELP_PLAY_AUDIO_DECODE_ERROR	播放过程中，音频解码失败
NELP_PLAY_VIDEO_DECODE_ERROR	播放过程中，视频解码失败
NELP_PLAY_AUDIO_RENDER_ERROR	播放过程中，音频播放失败
NELP_PLAY_VIDEO_RENDER_ERROR	播放过程中，视频播放失败
NELP_PLAY_UNKNOWN_ERROR	播放过程中，未知错误

缓冲模式 NELPBufferStrategy

参数	说明
NELPTopSpeed	极速模式，适用于视频直播，延时最小，网络抖动时容易发生卡顿，丢帧追赶
NELPLowDelay	网络直播低延时，适用于视频直播，延时低，网络抖动时偶尔有卡顿，丢帧追赶
NELPFluent	网络直播流畅，适用于视频直播，流畅性好，延时比低延时模式稍大，丢帧追赶
NELPAntiJitter	网络点播抗抖动，适用于视频点播和本地视频，抗抖动性强
NELPDelayPullUp	网络直播, 延时追赶策略，不丢帧1.2倍速播放追赶

显示模式 NELPMovieScalingMode

参数	说明
NELPMovieScalingModeNone	无缩放
NELPMovieScalingModeAspectFit	等比例缩放，某一边会有黑边填充
NELPMovieScalingModeAspectFill	等比例缩放，某一边可能会被裁减
NELPMovieScalingModeFill	全屏显示，画面宽高比可能与视频原始宽高比不一致

播放状态 NELPMoviePlaybackState

参数	说明
NELPMoviePlaybackStateStopped	停止状态
NELPMoviePlaybackStatePlaying	播放状态
NELPMoviePlaybackStatePaused	暂停状态，可调play继续播放
NELPMoviePlaybackStateSeeking	Seek状态

加载状态 NELPMovieLoadState

参数	说明
NELPMovieLoadStatePlayable	在该状态下，播放器初始化完成，可以播放。若shouldAutoplay 设置成YES，播放器初始化完成后会自动播放
NELPMovieLoadStatePlaythroughOK	在该状态下，在网络不好的情况下缓冲完成，可以播放
NELPMovieLoadStateStalled	在播放过程中网络不好需要缓冲数据的时候播放会自动暂停

加载状态 NELPMovieFinishReason

参数	说明
NELPMovieFinishReasonPlaybackEnded	正常播放结束
NELPMovieFinishReasonPlaybackError	播放发生错误导致结束
NELPMovieFinishReasonUserExited	人为退出(暂未使用，保留值)

回调视频的数据格式 NELPVideoFormat

参数	说明
NELP_YUV420	YUV 420

密钥校验结果 NELPKeyCheckResult

参数	说明
NELP_NO_ENCRYPTION	没有加密
NELP_ENCRYPTION_CHECK_OK	密钥正确
NELP_ENCRYPTION_UNSUPPORT_PROTOCAL	协议不支持
NELP_ENCRYPTION_KEY_CHECK_ERROR	密钥错误
NELP_ENCRYPTION_INPUT_INVALIED	输入错误
NELP_ENCRYPTION_GET_KEY_TIMEOUT	获取密钥超时
NELP_ENCRYPTION_UNKNOWN_ERROR	未知错误

切片清晰度 NELPMultiMediaType

参数	说明
NELP_MEDIA_INVALID	无效的
NELP_MEDIA_SD	低清
NELP_MEDIA_MD	标清
NELP_MEDIA_HD	高清
NELP_MEDIA_SHD	超清

切换切片结果 NELPSwitchStreamState

参数	说明
NELP_SWITCH_SUCCESS	切换成功
NELP_SWITCH_NO_STREAM	没有对应的流
NELP_SWITCH_FAILED	切换失败

结构体值参数介绍

视频信息 NELPVideoInfo

参数	说明
codec_type	视频编码器类型如: h264
width	视频宽度
height	视频高度
fps	视频的帧率
bitrate	码率 (单位: kb/s)

视频信息 NELPAudioInfo

参数	说明
codec_type	音频编码器类型如: aac
sample_rate	音频的采样率
bitrate	码率 (单位: kb/s)
numOfChannels	音频的通道数

回调的视频数据结构 NELPVideoRawData

参数	说明
width	视频宽度
height	视频高度
UsrData	视频数据

回调的音频数据结构 NELPAudioRawData

参数	说明
channels	通道数
samplerate	采样率
data_size	数据长度
usrData	音频数据

选择流的状态 NELPSwitchStreamResult

参数	说明
state	状态

4 如何使用SDK API接口

4.1 播放功能

1.首先头文件<NELivePlayer/NELivePlayerController.h>
2.使用初始化系列方法初始化播放器实例
3.监听播放器的相关通知
4.将显示图层添加到需要显示的页面上
5.设置相关的静态参数
6.调用prepareToPlay初始化视频源，等待接收prepare完成通知
7.收到prepare完成通知后，调用play进行播放（如果设置了shouldAutoplay，可以不用调用play）。
8.播放过程中根据需要设置动态参数
9.调用shutdown关闭播放器后，并将外部引用去除，资源释放后发出release通知
说明：释放之前一定要调用shutdown，否则资源无法释放，不要在dealloc中调用。

4.1.1 创建播放器实例

4.1.1.1 API介绍

SDK在初始化阶段，开启内部的播放相关服务，根据URL选择最优拉流结点。

4.1.1.2 API原型

不带URL系列的初始化接口。该系列初始化接口需要配合setPlayUrl接口一同使用。


/**
 * @brief 系统方法
 *
 * @return
 */
+ (instancetype)new;
- (instancetype)init;

/**
 *    @brief    初始化播放器
 *
 *    @param     isNeed 是否需要内部配置audiosession
 *
 *    @return    返回播放器实例
 */
- (instancetype)initWithNeedConfigAudioSession:(BOOL)isNeed;

带URL系列的初始化接口。

/**
 *    @brief    初始化播放器，输入播放文件路径
 *
 *    @param     aUrl     播放文件的路径
 *  @param     error     初始化错误原因
 *
 *    @return    返回播放器实例
 */
- (id)initWithContentURL:(NSURL *)aUrl
                   error:(NSError **)error;

/**
 初始化播放器

 @param aUrl 播放文件的路径
 @param config URL相关的配置信息
 @param error 初始化错误原因
 @return 返回播放器实例
 */
- (instancetype)initWithContentURL:(NSURL *)aUrl
                            config:(NELPUrlConfig *)config
                             error:(NSError **)error;


/**
 *    @brief    初始化播放器，输入播放文件路径 （准备废弃）
 *
 *    @param     aUrl     播放文件的路径
 *    @param     isNeed     是否需要内部配置audio session
 *  @param     error     初始化错误原因
 *
 *    @return    返回播放器实例
 */
- (id)initWithContentURL:(NSURL *)aUrl
  needConfigAudioSession:(BOOL)isNeed
                   error:(NSError **)error;

4.1.1.3 参数说明

参数	类型	说明
aUrl	NSURL	拉流地址
config	NELPUrlConfig	URL相关的配置
error	NSError	初始化失败原因

4.1.1.4 示例

/**(1) 导入头文件**/
#import <NELivePlayer/NELivePlayerViewController.h>

/**(2) 添加声明播放器属性**/
@interface NELivePlayerViewController : UIViewController
@property(nonatomic, strong) NELivePlayerViewController *liveplayer;
@end

/**(3) 创建 NELivePlayerController 实例，并进行相关初始化工作**/

//self.url 是待播放的网络视频流或本地文件的路径
/* 方式 一 */
NSError *error = nil;
self.liveplayer = [[NELivePlayerController alloc] initWithContentURL: self.url 
                                                               error: &error];

/* 方式 二 */
self.liveplayer = [[NELivePlayerController alloc] init];
NSError *error = [self.liveplayer setPlayUrl:url];

**(4) 设置播放器view的相关属性**  

// 显示位置，以屏幕大小为例，用户可以根据自己的实际需求来设置view的位置和大小
screenWidth  = CGRectGetWidth([UIScreen mainScreen].bounds);
screenHeight = CGRectGetHeight([UIScreen mainScreen].bounds);
self.playerView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, screenWidth, screenHeight-20)];
self.liveplayer.view.frame = self.playerView.bounds; 

//添加显示层
[self.view addSubview:self.liveplayer.view];

4.1.1.5 特殊说明

如果存在拉流地址非法的问题，可能会出现初始化失败，初始化失败不会有通知进行上报，返回nil，错误原因由error带回。

4.1.2 播放器的相关通知

4.1.2.1 API介绍

播放器的关键过程均由通知进行上报，因此在外部需要进行通知监听。

4.1.2.2 通知原型

//调用prepareToPlay后，播放器初始化视频文件完成后的消息通知。
NELP_EXTERN NSString *const NELivePlayerDidPreparedToPlayNotification;

//播放器加载状态发生改变时的消息通知。
NELP_EXTERN NSString *const NELivePlayerLoadStateChangedNotification;

//播放器播放完成或播放发生错误时的消息通知。
NELP_EXTERN NSString *const NELivePlayerPlaybackFinishedNotification;        

//播放器播放状态发生改变时的消息通知。
NELP_EXTERN NSString *const NELivePlayerPlaybackStateChangedNotification;

//播放器解码器打开后的消息通知，指示硬件解码是否开启。
NELP_EXTERN NSString *const NELivePlayerHardwareDecoderOpenNotification;

//播放器第一帧视频显示时的消息通知。
NELP_EXTERN NSString *const NELivePlayerFirstVideoDisplayedNotification;

//播放器第一帧音频播放时的消息通知。
NELP_EXTERN NSString *const NELivePlayerFirstAudioDisplayedNotification;

//播放器资源释放完成时的消息通知。
NELP_EXTERN NSString *const NELivePlayerReleaseSueecssNotification;

//seek完成时的消息通知，仅适用于点播，直播不支持。
NELP_EXTERN NSString *const NELivePlayerMoviePlayerSeekCompletedNotification;

//视频码流包解析异常时的消息通知。
NELP_EXTERN NSString *const NELivePlayerVideoParseErrorNotification;

//播放过程中的Http状态信息通知。
NELP_EXTERN NSString *const NELivePlayerHttpCodeResponseNotification;

// 播放器失败重试通知
NELP_EXTERN NSString *const NELivePlayerRetryNotification;

4.1.2.3 参数说明

部分通知会携带UserInfo字典来将信息进行上报：

播放完成：NELivePlayerPlaybackFinishedNotification 的UserInfo字典。

UserInfo字典结构:
     NELivePlayerPlaybackDidFinishReasonUserInfoKey : [NSNumber]
     NELivePlayerPlaybackDidFinishErrorKey          : [NSNumber]

参数	类型	说明
NELivePlayerPlaybackDidFinishReasonUserInfoKey	NSString	播放器播放结束原因的key
NELivePlayerPlaybackDidFinishErrorKey	NSString	播放器播放结束具体错误码

seek完成：NELivePlayerMoviePlayerSeekCompletedNotification 的UserInfo字典。

UserInfo字典结构:
    NELivePlayerMoviePlayerSeekCompletedTargetKey : [NSNumber]
    NELivePlayerMoviePlayerSeekCompletedErrorKey  : [NSNumber]

参数	类型	说明
NELivePlayerMoviePlayerSeekCompletedErrorKey	NSString	seek失败时失败原因key
NELivePlayerMoviePlayerSeekCompletedTargetKey	NSString	seek完成时的时间key

HTTP状态信息通知：NELivePlayerHttpCodeResponseNotification 的UserInfo字典。

UserInfo字典结构:
    NELivePlayerWillAutoSwitchDefinitionInfoKey : [NELivePlayerMulitDefinitionModel]

播放器失败重试通知：NELivePlayerRetryNotification 的UserInfo字典。

UserInfo字典结构:
    NELivePlayerPlaybackDidRetryCountKey : [NSNumber]

4.1.2.4 示例

监听示例

// 播放器媒体流初始化完成后触发，收到该通知表示可以开始播放
[[NSNotificationCenter defaultCenter] addObserver: self
                                         selector: @selector(NELivePlayerDidPreparedToPlay:)
                                             name: NELivePlayerDidPreparedToPlayNotification
                                           object: nil];

// 播放器加载状态发生变化时触发，如开始缓冲，缓冲结束
[[NSNotificationCenter defaultCenter] addObserver: self
                                         selector: @selector(NeLivePlayerloadStateChanged:)
                                             name: NELivePlayerLoadStateChangedNotification
                                           object: nil];

// 正常播放结束或播放过程中发生错误导致播放结束时触发的通知    
[[NSNotificationCenter defaultCenter] addObserver: self
                                         selector: @selector(NELivePlayerPlayBackFinished:)
                                             name: NELivePlayerPlaybackFinishedNotification
                                           object: nil];

// 第一帧视频图像显示时触发的通知    
[[NSNotificationCenter defaultCenter] addObserver: self
                                         selector: @selector(NELivePlayerFirstVideoDisplayed:)
                                             name: NELivePlayerFirstVideoDisplayedNotification
                                           object: nil];

// 第一帧音频播放时触发的通知                                         
[[NSNotificationCenter defaultCenter] addObserver: self
                                         selector: @selector(NELivePlayerFirstAudioDisplayed:)
                                             name: NELivePlayerFirstAudioDisplayedNotification
                                           object: nil];


// 资源释放成功后触发的通知    
[[NSNotificationCenter defaultCenter] addObserver: self
                                         selector: @selector(NELivePlayerReleaseSuccess:)
                                             name: NELivePlayerReleaseSueecssNotification
                                           object: nil];

// 视频码流解析失败时触发的通知                                               
[[NSNotificationCenter defaultCenter] addObserver: self
                                         selector: @selector(NELivePlayerVideoParseError:)
                                             name: NELivePlayerVideoParseErrorNotification
                                           object: nil];

// seek完成通知
[[NSNotificationCenter defaultCenter] addObserver: self
                                         selector: @selector(NELivePlayerSeekComplete:)
                                             name: NELivePlayerMoviePlayerSeekCompletedNotification
                                           object: nil];

// HTTP状态通知                                               
[[NSNotificationCenter defaultCenter] addObserver: self
                                         selector: @selector(NELivePlayerHttpCodeResponse:)
                                             name: NELivePlayerHttpCodeResponseNotification
                                           object: nil];

响应示例。以带参数的通知响应示范，不带参数的请根据自定业务情景在响应方法中做相应的处理。

// 初始化完成通知响应
- (void)NELivePlayerDidPreparedToPlay:(NSNotification*)notification {
    [self.livepalyer play]; //如果设置shouldAutoplay为YES，此处可以不用调用play
}

// 播放完成通知响应
- (void)NELivePlayerPlayBackFinished:(NSNotification*)notification {
    NSDictionary *userInfo = [notification userInfo];
    NELPMovieFinishReason reason = [userInfo[NELivePlayerPlaybackDidFinishReasonUserInfoKey] integerValue];
    switch (reason) {
        case NELPMovieFinishReasonPlaybackEnded: //结束
            break;
        case NELPMovieFinishReasonPlaybackError: //失败
        {
           //获取错误码
            NSInteger code = [userInfo[NELivePlayerPlaybackDidFinishErrorKey] integerValue];
            break;
        }
    }
}

//HTTP状态响应
- (void)NELivePlayerHttpCodeResponse:(NSNotification *)notification {
    NSDictionary * userInfo = [notification userInfo];
    NELivePlayerHttpCodeModel *codeModel = userInfo[NELivePlayerHttpCodeResponseInfoKey];
    // http code: codeModel.code
    // http header: codeModel.header
}

4.1.3 常规静态参数设置

4.1.3.1 API介绍

设置拉流地址。（仅针对不带URL的初始化方式使用）
设置是否开启硬件解码，IOS 8.0以上支持硬件解码，默认为软件解码。
设置文件初始化完成之后是否自动播放。
设置播放缓冲策略。
设置拉流超时时间。

4.1.3.2 API原型

/**
 *    @brief    设置播放的url, 此接口需要在调用init或initWithNeedConfigAudioSession之后使用，调用详情请参考initWithNeedConfigAudioSession，
 *              设置之后一定要调用prepareToPlay才能收到准备播放信息
 *
 *    @param     url 目标地址
 *
 *    @return    设置的错误信息
 */
- (NSError *)setPlayUrl:(NSURL *)url;

/**
 @brief 设置播放的url

 @param url url
 @param config url 配置
 @return 设置的错误信息
 */
- (NSError *)setPlayUrl:(NSURL *)url
                 config:(NELPUrlConfig *)config;

/**
 *    @brief    设置是否开启硬件解码，仅IOS 8.0以上支持，默认不开启
 *
 *  @param     isOpen     YES：硬件解码 NO：软件解码
 *
 *    @return    无
 */
- (void)setHardwareDecoder :(BOOL)isOpen;

/**
 *    @brief    设置播放器初始化视频文件完成后是否自动播放，默认自动播放
 *
 *  @param     shouldAutoplay     YES：自动播放 NO：手动播放
 *
 *  @discussion 当设置为YES后，则在调用prepareToPlay初始化视频文件完成后会自动调用play方法进行播放
 *
 *    @return    无
 */
@property(nonatomic) BOOL shouldAutoplay;

/**
 * @brief  设置缓冲策略，在播放器初始化后，prepareToPlay之前调用
 *
 * @discussion 缓冲策略有直播低延时模式、直播流畅模式以及点播抗抖动模式，如果是直播，建议采用低延时模式或流畅模式，如果是点播或本地视频，建议采用抗抖动模式
 *
 * @return 无
 */
- (void)setBufferStrategy:(NELPBufferStrategy)bufferStrategy;

/**
 * @brief 设置拉流超时时间，在prepareToPlay之前调用
 *
 * @param timeout 超时时间 (单位: 毫秒 ms 范围:0 ~ 30000ms)
 *
 * @return 无
 */
- (void)setPlaybackTimeout:(long)timeout;

/**
 @brief 精确seek开关

 @param isOpen 是否打开。默认：Y。需要在Prepare之前设置。
 */
- (void)setAccurateSeek:(BOOL)isOpen;

/**
 @brief 设置重试

 @param config 重试相关配置。需要在Prepare之前设置.
 */
- (void)setRetryConfig:(nullable NELPRetryConfig *)config;

4.1.3.3 参数说明

无

4.1.3.4 特殊说明

静态参数，只可以在初始化之后，播放之前进行设置，播放的过程中不可设置。

4.1.3.5 示例

/设置播放缓冲策略，直播采用低延时模式或流畅模式，点播采用抗抖动模式，具体可参见API文档
[self.liveplayer setBufferStrategy:NELPLowDelay];

//设置视频文件初始化完成后是否自动播放，默认自动播放
[self.liveplayer setShouldAutoplay:YES]; 

//设置是否开启硬件解码，IOS 8.0以上支持硬件解码，默认为软件解码
[self.liveplayer setHardwareDecoder:isHardware];

//设置拉流超时时间
[self.liveplayer setPlaybackTimeout:30 *1000];

//设置自动切换分辨率
[self.liveplayer setAutoSwitchDefinition:NO];

4.1.4 点播加密视频的静态参数设置（2.3.0后废弃该接口）

4.1.4.1 API介绍

仅针对FLV点播的加密视频，直播流和非FLV点播视频忽略该步骤
密钥未知，使用flv的密钥的获取和验证接口，设置信息。
密钥已知，使用flv的验证接口，设置信息。

4.1.4.2 API原型

未知密钥的设置接口

/**
 * @brief 解密模块初始化，并校验密钥是否正确
 *
 * @param transferToken 获取密钥的令牌
 * @param accid 视频云用户创建的其子用户id
 * @param appKey 开发者平台分配的AppKey
 * @param token 视频云用户子用户的token
 * @param complete 异步返回密钥检测结果
 *
 * @discussion 该接口不可与setDecryptionKey同时使用
 *
 * @return ret 返回密钥检测的状态
 */
- (void)setDecryptionTransferToken:(NSString *)transferToken
                             accid:(NSString *)accid
                            appKey:(NSString *)appKey
                             token:(NSString *)token
                          complete:(void(^)(NELPKeyCheckResult ret))complete;

已知密钥的设置接口

/**
 * @brief 设置flv加密视频解密所需的密钥,在已知密钥的情况下可以调用该接口进行解密
 *
 * @param key 密钥
 * @param complete 异步返回密钥检测结果
 *
 * @discussion 该接口不可与initDecryption接口同时使用, 在prepareToPlay前调用
 * @return  ret 返回密钥检测的状态。不需要调用par
 */
- (void)setDecryptionKey:(NSString *)key
                complete:(void(^)(NELPKeyCheckResult ret))complete;

4.1.4.3 参数说明

参数	类型	说明
transferToken	NSString	获取密钥的令牌
accid	NSString	视频云用户创建的其子用户id
appKey	NSString	开发者平台分配的AppKey
token	NSString	视频云用户子用户的token
complete	NSError	异步返回密钥检测结果

4.1.4.4 示例

NSString *transferToken = @"test";
NSString *accid = @"test";
NSString *appKey = @"test";
NSString *token = @"test";

__weak typeof(self) weakSelf = self;
[self.liveplayer setDecryptionTransferToken: transferToken
                                      accid: accid 
                                     appKey: appKey
                                      token: token
                                   complete: ^(NELPKeyCheckResult ret) {

            switch (ret) {
                case NELP_NO_ENCRYPTION:
                case NELP_ENCRYPTION_CHECK_OK:
                    [weakSelf.liveplayer prepareToPlay];
                    break;
                case NELP_ENCRYPTION_UNSUPPORT_PROTOCAL:
                    break;
                case NELP_ENCRYPTION_KEY_CHECK_ERROR:
                    break;
                case NELP_ENCRYPTION_INPUT_INVALIED:
                    break;
                case NELP_ENCRYPTION_UNKNOWN_ERROR:
                    break;
                case NELP_ENCRYPTION_GET_KEY_TIMEOUT:
                    break;
                default:
                    break;
            }
        }];

NSString *key = @"test";

__weak typeof(self) weakSelf = self;
[self.liveplayer setDecryptionKey: key 
                         complete: ^(NELPKeyCheckResult ret) {

        switch (ret) {
            case NELP_NO_ENCRYPTION:
            case NELP_ENCRYPTION_CHECK_OK:
                [weakSelf.liveplayer prepareToPlay];
                break;
            case NELP_ENCRYPTION_UNSUPPORT_PROTOCAL:
                break;
            case NELP_ENCRYPTION_KEY_CHECK_ERROR:
                break;
            case NELP_ENCRYPTION_INPUT_INVALIED:
                break;
            case NELP_ENCRYPTION_UNKNOWN_ERROR:
                break;
            case NELP_ENCRYPTION_GET_KEY_TIMEOUT:
                break;
            default:
                break;
        }
    }];

4.1.4.4 特殊说明

回调返回的是校验后的结果，用户需要根据返回的结果作出相应的操作，对于未加密和密钥校验正确的flv加密视频，可以继续进行下述步骤进行播放，其他情况需要根据不同的错误类型，检查出错原因，并重复上述操作，直至校验通过才能正常播放。

4.1.5 点播加密视频设置

4.1.5.1 API介绍

不提供专门的设置参数接口，原有的解密配置接口准备废弃
点播加密的配置和视频缓存的相关配置通过 NELPUrlConfig 类进行设置
初始化阶段通过initWithUrl:Config:或者setUrl:Config:接口进行设置
切换视频源通过switchContentWithUrl:Config:接口进行设置

4.1.5.2 API原型

/**
 初始化播放器

 @param aUrl 播放文件的路径
 @param config URL相关的配置信息
 @param error 初始化错误原因
 @return 返回播放器实例
 */
- (instancetype)initWithContentURL:(NSURL *)aUrl
                            config:(NELPUrlConfig *)config
                             error:(NSError **)error;

/**
 @brief 设置播放的url

 @param url url
 @param config url 配置
 @return 设置的错误信息
 */
- (NSError *)setPlayUrl:(NSURL *)url
                 config:(NELPUrlConfig *)config;

/**
 @brief 播放过程中切换播放地址(扩展)

 @param aUrl 待切换的播放地址
 @param config 播放地址相关的配置
 @return >= 0 切换成功， < 0 切换失败
 */
- (int)switchContentUrl:(NSURL *)aUrl config:(NELPUrlConfig *)config;

4.1.5.3 参数说明

NELPUrlConfig 配置类参数说明

参数	类型	说明
cacheConfig	NELPUrlCacheConfig	缓存配置
decryptionConfig	NELPUrlDecryptionConfig	解密配置

NELPUrlDecryptionConfig 类参数说明

参数	类型	说明
type	NELPUrlDecryptionType（只读）	解密类型（原始密钥或者视频云服务端管理的密钥解密）
originalKey	NSData（只读）	原始密钥
transferToken	NSData（只读）	原始密钥
accid	NSString（只读）	原始密钥
appKey	NSString（只读）	原始密钥
token	NSString（只读）	原始密钥

NELPUrlConfig 实例化方法

 快速构造方法（原始密钥解密）

 @param originalKey 原始密钥
 @return 配置实例
 */
+ (instancetype)configWithOriginalKey:(NSData *)originalKey;


/**
 快速构造方法（视频云服务端管理密钥解密）

 @param transferToken transferToken
 @param accid accid
 @param appKey appKey
 @param token token
 @return 配置实例
 */
+ (instancetype)configWithTransferToken:(NSString *)transferToken
                                  accid:(NSString *)accid
                                 appKey:(NSString *)appKey
                                  token:(NSString *)token;

4.1.5.4 示例

原始密钥解密设置

   NSData *oriKeyData = [NSData data]; //原始密钥
   NELPUrlConfig *urlConfig = [[NELPUrlConfig alloc] init];
   urlConfig.decryptionConfig = [NELPUrlDecryptionConfig configWithOriginalKey:oriKeyData];

   //初始化方式一
   player = [[NELivePlayerController alloc] initWithContentURL:url
                                                        config:urlConfig
                                                         error:&error];

   //初始化方式二
   player = [[NELivePlayerController alloc] init];
   [player setPlayUrl:url config:urlConfig];

   //切换方式
   [player switchContentUrl:url config:urlConfig];

视频云服务端负责管理密钥的视频解密

   NELPUrlConfig *urlConfig = [[NELPUrlConfig alloc] init];
   NSString *transferToken = @"test";
   NSString *accid = @"test";
   NSString *appKey = @"test";
   NSString *token = @"test";
   urlConfig.decryptionConfig = [NELPUrlDecryptionConfig configWithTransferToken:transferToken
                                                                           accid:accid
                                                                          appKey:appKey
                                                                           token:token];
    //初始化方式一
    player = [[NELivePlayerController alloc] initWithContentURL:url
                                                         config:urlConfig
                                                          error:&error];

    //初始化方式二
    player = [[NELivePlayerController alloc] init];
    [player setPlayUrl:url config:urlConfig];

    //切换方式
    [player switchContentUrl:url config:urlConfig];

4.1.5.5 特殊说明

新的解密设置接口，如果切换失败或者初始化过程中设置参数失败，会通过playerErrorCode的通知将错误带回。具体错误见头文件定义。

4.1.6 视频本地缓存设置

4.1.6.1 API介绍

不提供专门的接口配置视频的本地缓存
视频缓存的相关配置通过 NELPUrlConfig 类进行设置
初始化阶段通过initWithUrl:Config:或者setUrl:Config:接口进行设置
切换视频源通过switchContentWithUrl:Config:接口进行设置
缓存参数配置为YES时，如果指定缓存路径，则交由外部管理本地缓存，否则由SDK内部管理本地缓存
缓存参数配置为NO时，不进行本地缓存。
SDK内部管理本地缓存，当播放器实例销毁或者换源时会自动清空当前缓存的文件

4.1.6.2 API原型

/**
 初始化播放器

 @param aUrl 播放文件的路径
 @param config URL相关的配置信息
 @param error 初始化错误原因
 @return 返回播放器实例
 */
- (instancetype)initWithContentURL:(NSURL *)aUrl
                            config:(NELPUrlConfig *)config
                             error:(NSError **)error;

/**
 @brief 设置播放的url

 @param url url
 @param config url 配置
 @return 设置的错误信息
 */
- (NSError *)setPlayUrl:(NSURL *)url
                 config:(NELPUrlConfig *)config;

/**
 @brief 播放过程中切换播放地址(扩展)

 @param aUrl 待切换的播放地址
 @param config 播放地址相关的配置
 @return >= 0 切换成功， < 0 切换失败
 */
- (int)switchContentUrl:(NSURL *)aUrl config:(NELPUrlConfig *)config;

4.1.6.3 参数说明

NELPUrlConfig 配置类参数说明

参数	类型	说明
cacheConfig	NELPUrlCacheConfig	缓存配置
decryptionConfig	NELPUrlDecryptionConfig	解密配置

NELPUrlCacheConfig 缓存配置类参数说明

参数	类型	说明
isCache	BOOL	是否缓存。默认：NO。 YES:开启本地缓存，如果cacheRootPath为空，内部管理，否则外部管理。 NO: 关闭本地缓存
cacheRootPath	NSString	缓存路径

4.1.6.4 示例

    NELPUrlConfig *urlConfig = [[NELPUrlConfig alloc] init];
    urlConfig.cacheConfig = [[NELPUrlCacheConfig alloc] init];
    urlConfig.cacheConfig.isCache = YES;
    urlConfig.cacheConfig.cacheRootPath = nil;

    //初始化方式一
    player = [[NELivePlayerController alloc] initWithContentURL:url
                                                         config:urlConfig
                                                          error:&error];

    //初始化方式二
    player = [[NELivePlayerController alloc] init];
    [player setPlayUrl:url config:urlConfig];

    //切换方式
    [player switchContentUrl:url config:urlConfig];

4.1.6.5 特殊说明

缓存文件路径传根路径即可，路径文件夹可以不存在。
缓存文件路径文件夹下会根据内部规则自动生成缓存文件和map数据文件，播放本地缓存时缺一不可

4.1.7 失败重试参数设置

4.1.7.1 API介绍

针对播放器播放过程中出现的error，sdk内部根据配置会自动进行重连
可以配置重连的次数
可以配置默认两次重连的时间间隔
可以单独配置任意两次重连之间的时间间隔，不足的按照默认时间间隔进行重连

4.1.7.2 API原型

/**
 @brief 设置重试

 @param config 重试相关配置。需要在Prepare之前设置.
 @discussion 在播放出错时自动进行重试配置
 */
- (void)setRetryConfig:(nullable NELPRetryConfig *)config;

4.1.7.3 参数说明

NELPRetryConfig 配置类参数说明

参数	类型	说明
count	NSTimeInterval	重连次数
defaultIntervalS	NSTimeInterval	两次重连之间的默认时间间隔
customIntervalS	NSMutableArray	自定义重试时间间隔

count: -1 表示无限重试。默认值：0
defaultIntervalS：0 表示立即重试。默认值0
customIntervalS：nil 表示使用默认的时间间隔。如果数组元素个数大于重试次数，取前面的重试次数个值；如果小于，后面未配置的值使用默认时间间隔。

4.1.7.4 示例


    //--- init player ---//

   NELPRetryConfig *retryConfig = [[NELPRetryConfig alloc] init];
   retryConfig.count = 5;
   retryConfig.defaultIntervalS = 3;
   retryConfig.customIntervalS = @[@(2), @(1), @(4)];
   [player setRetryConfig:retryConfig];

   //--- prepareToPlay ---//

4.1.7.5 说明

重试期间会上抛重试通知NELivePlayerRetryNotification，携带的userInfo里有当前的重试次数
调用shutdown之后，自动停止所有的重试

4.1.8 视频文件初始化

4.1.8.1 API介绍

属性设置完成后，需调用 prepareToPlay() 接口对待播放的视频文件进行初始化，初始化完成后会发
NELivePlayerDidPreparedToPlayNotification 通知，并将 isPreparedToPlay 设置为 YES，
如果 shouldAutoplay 已经设置成 YES，则会自动调用 play 进行播放，
如果 shouldAutoplay 设置成 NO，则需要用户调用 play() 进行播放。

4.1.8.2 API原型

/**
 *    @brief    设置数据源，初始化视频文件为播放做准备，在播放前调用
 *
 *  @discussion 当prepareToPlay完成时,若shouldAutoplay 为YES，则会自动调用play进行播放，
 *              若shouldAutoplay为 NO，则需手动调用play进行播放
 *
 *    @return    无
 */
- (void)prepareToPlay;

4.1.8.3 示例

[self.liveplayer prepareToPlay];

4.1.9 开始播放

4.1.9.1 API介绍

若 shouldAutoplay 设置成NO，则在调用 prepareToPlay() 接口后，需要调用 play() 进行播放

4.1.9.2 API原型

/**
 *    @brief    开始播放
 *
 *  @discussion
 *  如果当前正在播放，则调用该方法将无效果\\\n
 *  此时播放器状态为: NELPMoviePlaybackStatePlaying
 *
 *    @return    无
 */
- (void)play;

4.1.9.3 示例

[self.liveplayer play];

4.1.10 销毁播放器实例

4.1.10.1 API介绍

反初始化：释放底层播放器资源。释放完成后会发送NELivePlayerReleaseSueecssNotification通知。

4.1.10.2 API原型

/**
 *    @brief    停止播放，并释放播放器相关资源
 *
 *  @discussion
 *  在播放器退出时，需要调用该方法用于释放资源。
 *
 *    @return    无
 */
- (void)shutdown;

4.1.10.3 示例

[self.liveplayer shutdown];
self.liveplayer = nil;

4.1.10.4 特殊说明

只有在释放播放器资源时使用，调用之后，务必将外部内存引用置空，播放器资源释放完毕之后会发送NELivePlayerReleaseSueecssNotification通知。
为安全起见，在与switchWithContentUrl接口混合调用时，请务必注意时序问题，保持串行。
要等待收到资源释放成功的消息通知后，才能将监听资源释放状态的监听器释放掉，否则资源释放成功的通知是无法接收到的。
不会阻塞主线程，可以在主线程里调用

4.2 播放控制

播放过程中的暂停、快进、播放等操作
换源、截图等操作
播放过程中的显示模式、倍速、音量、静音等动态参数设置

4.2.1 播放过程控制

4.2.1.1 API介绍

开始播放。详情请参见4.1.6节。
暂停播放。
拖动播放。执行完成后会收到NELivePlayerMoviePlayerSeekCompletedNotification通知。
停止播放。详情请参见4.1.7节。

4.2.1.2 API原型

/**
 *    @brief    暂停播放
 *
 *  @discussion
 *  调用play方法继续播放。如果当前播放已经暂停，则调用该方法将无效果。\\\n
 *  此时播放器状态为: NELPMoviePlaybackStatePaused
 *
 *  @warning 该接口只针对点播地址有效。
 *
 *    @return    无
 */
- (void)pause;

/**
 *    @brief    设置当前播放时间点(用于seek操作)以及获取当前播放的时间点
 *
 *    @param     currentPlaybackTime     当前要播放的时间点(单位：秒)
 *
 *  @discussion
 *  需要在播放器发送NELivePlayerDidPreparedToPlayNotification通知后，才能调用该set方法设置到某一时间点播放，\\\n
 *  此时isPreparedToPlay的值为 YES
 *
 *    @return    get操作返回的是当前播放的时间点
 *
 *  @see isPreparedToPlay
 */
@property(nonatomic)  NSTimeInterval currentPlaybackTime;

4.2.1.3 示例

[self.liveplayer pause];

[self.liveplayer setCurrentPlaybackTime:30];

4.2.1.4 特殊说明

拖动播放时需要先通过duration获取视频时长，根据时长按照比例进行时间设置。

4.2.2 换源操作

4.2.2.1 API介绍

播放过程中，实现常规视频之间的切换。
播放过程中，各种视频之间的切换。

4.2.2.2 API原型

/**
 * @brief 播放过程中切换播放地址
 *
 * @param aUrl 待切换的播放地址
 *
 * @return >= 0 切换成功， < 0 切换失败
 */
- (int)switchContentUrl:(NSURL *)aUrl;

/**
 @brief 播放过程中切换播放地址(扩展)

 @param aUrl 待切换的播放地址
 @param config 播放地址相关的配置
 @return >= 0 切换成功， < 0 切换失败
 */
- (int)switchContentUrl:(NSURL *)aUrl config:(NELPUrlConfig *)config;

/**
 * @brief 加密视频的切换（即将废弃）
 *
 * @param aUrl 待切换的播放地址
 * @param transferToken 获取密钥的令牌
 * @param accid 视频云用户创建的其子用户id
 * @param appKey 开发者平台分配的AppKey
 * @param token 视频云用户子用户的token
 * @param complete 异步返回密钥检测结果
 *
 * @discussion 切换成功后直接播放，不需要调用prepareToPlay。
 *
 * @return ret 返回密钥检测的状态
 */
- (void)switchDecryptionUrl:(NSURL *)aUrl
              transferToken:(NSString *)transferToken
                      accid:(NSString *)accid
                     appKey:(NSString *)appKey
                      token:(NSString *)token
                   complete:(void(^)(NELPKeyCheckResult ret))complete;

/**
 * @brief 已知密钥的情况下可以调用该接口进行切换（即将废弃）
 *
 * @param key 密钥
 * @param complete 异步返回密钥检测结果
 *
 * @discussion 切换成功后直接播放，不需要调用prepareToPlay。
 * @return     ret 返回密钥检测的状态。
 */
- (void)switchDecryptionKeyUrl:(NSURL *)aUrl
                           key:(NSString *)key
                      complete:(void(^)(NELPKeyCheckResult ret))complete;

4.2.2.3 参数说明

参数	类型	说明
aUrl	NSURL	切换的目标地址
config	NSString	缓冲和解密配置

4.2.2.4 示例

   NELPUrlConfig *urlConfig = [[NELPUrlConfig alloc] init];

   //配置缓存(非必须)
   urlConfig.cacheConfig = [[NELPUrlCacheConfig alloc] init];
   urlConfig.cacheConfig.isCache = YES;
   urlConfig.cacheConfig.cacheRootPath = nil;

    //配置解密(非必须)
    NSString *transferToken = @"test";
    NSString *accid = @"test";
    NSString *appKey = @"test";
    NSString *token = @"test";
    urlConfig.decryptionConfig = [NELPUrlDecryptionConfig configWithTransferToken:transferToken
                                                                            accid:accid
                                                                           appKey:appKey
                                                                            token:token];
    //切换
    [_player switchContentUrl:url config:urlConfig];

4.2.2.5 换源后保留的参数

针对用户已经设置过的参数，换源操作会对部分参数进行保留，详见下表：

参数	说明	是否保留
bufferStrategy	缓冲策略	保留
bufferSize	缓冲区大小	保留
HardwareDecoder	软硬件编码	保留
ShouldAutoplay	是否自动播放	保留
Mute	静音	保留
Mirror	镜像显示	保留
Volume	音量	保留
LoopCount	循环次数	保留
AccurateSeek	精确seek开关	保留
PlaybackSpeed	播放速度	保留
PlaybackTimeout	拉流超时时间	保留
OpenReceiveSyncData	是否接收同步透传的信息	保留
RetryConfig	自动重试配置	保留
SelectedAudioTrack	选择的音轨	保留
yuvCallback	YUV回调	保留
pcmConfig	PCM配置	保留
pcmCallback	PCM回调	保留
subtitleCallback	字幕回调	保留

4.2.2.6 特殊说明

switchContentUrl:只能进行普通源之间切换
switchContentUrl:config: 可以实现普通源和加密源之间的互切（普通-普通，普通-加密，加密-加密）
调用成功之后不需要调用prepareToPlay接口，切换成功之后会收到NELivePlayerDidPreparedToPlayNotification通知，失败会收到NELivePlayerPlaybackFinishedNotification通知。
为安全起见，外部调用请尽量在主线程调用

4.2.3 截图操作

4.2.3.1 API介绍

同步接口，返回当前播放时间点的视频图像，截图结果以 UIImage 格式返回，开发者可根据自己的需求保存成 jpg 格式或 png 格式，并保存到指定位置，demo 默认以 jpg 格式保存在相册中。

4.2.3.2 API原型

/**
 *    @brief    截图
 *
 *  @discussion
 *  调用prepareToPlay方法，播放器发出NELivePlayerDidPreparedToPlayNotification通知后，才能调用该方法。
 *
 *    @return    截图结果，以UIImage格式保存
 */
- (UIImage *)getSnapshot;

4.2.3.2 参数说明

无

4.2.3.3 示例

无

4.2.4 后台操作参数

4.2.4.1 API介绍

动态参数，设置后台是否需要继续播放视频。

4.2.4.2 API原型

/**
 *    @brief    设置播放器切入后台后的播放状态
 *
 *  @discussion
 *  若设置后台暂停，则在切入后台后播放器处于暂停状态，回到前台需要手动播放\\\n
 *  若设置后台继续播放，则在切入后台后音频继续播放，回到前台后音视频正常播放\\\n
 *
 *  注意：仅播放点播流时支持后台暂停；对于直播流，若在切入后台时不需要继续播放，则需要在切入后台的过程中将播放器关闭并释放相关资源，切回前台再重新开始播放。
 *
 *    @param     pause     YES：后台暂停 NO：继续播放
 *
 *    @return    无
 */
- (void)setPauseInBackground:(BOOL)pause;

4.2.4.3 参数介绍

参数	类型	说明
pause	BOOL	设置为NO：在进行前后台切换时，sdk内部不做处理。设置为YES：为在进入后台时sdk内部停止播放，回到前台后恢复播放。具体内部逻辑如下：直播：进入后台停止拉流，保留当前帧画面在屏幕上。回到前台后，重新拉流。点播：进入后台暂停，回到前台后继续播放。默认为：NO

4.2.4.4 示例

[self.liveplayer setPauseInBackground:YES];

4.2.5 操作相关的动态参数设置

4.2.5.1 API介绍

播放过程中相关的动态参数设置。

静音。
音量。
倍速。仅针对点播有效。
显示模式。

4.2.5.2 API原型

/**
 *    @brief    静音功能
 *
 *    @param     isMute     YES：开启静音 NO：关闭静音
 *
 *    @return    无
 */
- (void)setMute: (BOOL)isMute;

/**
 * @brief 设置播放音量
 *
 * @param volume  音量大小(范围 0.0 ~ 1.0，0.0为最小，1.0为最大)
 *
 * @return    无
 */
- (void)setVolume:(float)volume;

/**
 * @brief    设置播放速度，仅适用于点播
 *
 * @param    speed     播放速度(范围 0.5 ~ 2.0)
 *
 * @return    无
 */
@property (nonatomic) float playbackSpeed;

/**
 *    @brief    设置显示模式.
 *
 *  @param  aScalingMode 显示模式.
 *
 *  @discussion 共有以下4种显示模式，详见 NELPMovieScalingMode \\\n
 *  NELPMovieScalingModeNone,       //!< 无缩放  \\\n
 *  NELPMovieScalingModeAspectFit,  //!< 等比例缩放，某一边会有黑边填充  \\\n
 *  NELPMovieScalingModeAspectFill, //!< 等比例缩放，某一边可能会被裁减  \\\n
 *  NELPMovieScalingModeFill        //!< 全屏显示，画面宽高比可能与视频原始宽高比不一致
 *
 *    @return    无.
 */
- (void)setScalingMode: (NELPMovieScalingMode) aScalingMode;

4.2.5.3 参数介绍

参数	类型	说明
isMute	BOOL	默认为NO。YES:静音 NO:正常
volume	float	音量大小(范围 0.0 ~ 1.0，0.0为最小，1.0为最大)
playbackSpeed	float	播放速度(范围 0.5 ~ 2.0)
aScalingMode	NELPMovieScalingMode	显示模式

4.2.5.4 示例

//设置静音
[self.liveplayer setMute:NO];

//设置音量
[self.liveplayer setVolume:1.0];

//设置播放速度
[self.liveplayer setPlaybackSpeed:1.0];

//设置画面显示模式
[self.liveplayer setScalingMode:NELPMovieScalingModeNone];

4.3 查询参数

查询播放器当前的状态
查询文件的相关信息
查询时间的相关信息

4.3.1 状态相关参数

4.3.1.1 API介绍

播放详细状态
加载状态
初始化状态
播放/停止状态

4.3.1.2 API原型

/**
 *    @brief    获取当前播放状态 (只读)
 *
 *  @discussion 共有以下4种状态，详见 NELPMoviePlaybackState。
 *
 *  NELPMoviePlaybackStateStopped, // 停止状态 \\\n
 *  NELPMoviePlaybackStatePlaying, // 播放状态 \\\n
 *  NELPMoviePlaybackStatePaused,  // 暂停状态，可调play继续播放 \\\n
 *  NELPMoviePlaybackStateSeeking  // Seek状态 \\\n
 *
 *  播放状态的变换如下：\\\n
 *
 *  播放器调用initWithContentURL方法后处于NELPMoviePlaybackStatePaused状态，\\\n
 *  调用prepareToPlay方法，如果完成对视频文件的初始化则进入NELPMoviePlaybackStatePlaying状态；\\\n
 *  当调用setCurrentPlaybackTime方法时转成NELPMoviePlaybackStateSeeking状态，\\\n
 *  调用pause方法转NELPMoviePlaybackStatePaused状态，调用stop方法转到NELPMoviePlaybackStateStopped状态。
 *
 *    @return    当前播放状态
 */
@property(nonatomic, readonly)  NELPMoviePlaybackState playbackState;

/**
 *    @brief    获取当前加载状态 (只读)
 *
 *  @discussion 共有以下3种加载状态，详见 NELPMovieLoadState
 *
 *  NELPMovieLoadStatePlayable       = 1 << 0, // 在该状态下，播放器初始化完成，可以播放，若shouldAutoplay 设置成YES，播放器初始化完成后会自动播放 \\\n
 *  NELPMovieLoadStatePlaythroughOK  = 1 << 1, // 在该状态下，在网络不好的情况下缓冲完成，可以播放 \\\n
 *  NELPMovieLoadStateStalled        = 1 << 2, // 在播放过程中网络不好需要缓冲数据的时候播放会自动暂停 \\n
 *
 *  加载状态的变换如下：\\\n
 *  调用prepareToPlay方法，当视频文件初始化完成后，播放器会收到NELivePlayerLoadStateChangedNotification通知，此时的加载状态为 NELPMovieLoadStatePlayable \\\n
 *  当播放器需要缓冲的时候，缓冲开始时，播放会暂停，此时播放器会收到NELivePlayerLoadStateChangedNotification通知，此时的加载状态为 NEPMovieLoadStateStalled \\\n
 *  当缓冲结束时，播放会继续，此时播放器会收到NELivePlayerLoadStateChangedNotification通知，此时的加载状态为 NELPMovieLoadStatePlaythroughOK
 *
 *    @return    当前加载状态
 */
@property(nonatomic, readonly)  NELPMovieLoadState loadState;

/**
 * @brief 当前视频文件是否完成初始化（只读）
 *
 * @discussion
 *
 * 调用prepareToPlay方法后，如果播放器完成视频文件的初始化，会发送NELivePlayerDidPreparedToPlayNotification通知，并将isPreparedToPlay置为YES。
 *
 * @see prepareToPlay
 */
@property(nonatomic, readonly)  BOOL isPreparedToPlay;

/**
 * @brief 是否正在播放
 * @return YES:正在播放，NO:不在播放
 */
- (BOOL)isPlaying;

4.3.1.3 参数介绍

参数	类型	说明
playbackState	NELPMoviePlaybackState	播放器内部的各种详细状态
loadState	NELPMovieLoadState	播放器的加载状态
isPreparedToPlay	BOOL	资源初始化状态
isPlaying	BOOL	playbackState 的简单版，只标志是否在播放

4.3.1.4 示例

无

4.3.2 文件信息相关参数

4.3.2.1 API介绍

视频文件的相关信息
音频文件的相关信息

4.3.2.2 API原型

/**
 *    @brief    获取视频信息
 *
 *    @param     videoInfo     保存视频信息
 *
 *  @discussion
 *  调用prepareToPlay方法，播放器发出NELivePlayerDidPreparedToPlayNotification通知后，调用该方法才能获取到有效的视频信息。
 *  注意：其中帧率和码率都是从视频头中读取，若头中没有该信息，则返回0.
 *
 *    @return    无
 */
- (void)getVideoInfo :(NELPVideoInfo *)videoInfo;

/**
 *    @brief    获取音频信息
 *
 *    @param     audioInfo     保存音频信息
 *
 *  @discussion
 *  调用prepareToPlay方法，播放器发出NELivePlayerDidPreparedToPlayNotification通知后，调用该方法才能获取到有效的音频信息。
 *
 *    @return    无
 */
- (void)getAudioInfo :(NELPAudioInfo *)audioInfo;

4.3.2.3 参数介绍

参数	类型	说明
videoInfo	NELPVideoInfo	视频信息
audioInfo	NELPAudioInfo	音频信息

4.3.2.4 示例

//视频信息
NELPVideoInfo info;
memset(&info, 0, sizeof(NELPVideoInfo));
[self.liveplayer getVideoInfo:&info];

//音频信息
NELPAudioInfo audioInfo;
memset(&audioInfo, 0, sizeof(NELPAudioInfo));
[self.liveplayer getAudioInfo:&audioInfo];

4.3.2.5 特殊说明

一定要在收到NELivePlayerDidPreparedToPlayNotification通知后再获取，否则会获取不到。

4.3.3 时间信息相关参数

4.3.3.1 API介绍

获取视频时长
获取当前播放时间
获取当前的缓冲时间

4.3.3.2 API原型

/**
 *    @brief    获取多媒体文件总时长(单位: 秒) (只读)
 *
 *  @discussion
 *  调用prepareToPlay方法后，不能立即获得duration值。只有在播放器发送NELivePlayerDidPreparedToPlayNotification通知后，获取的duration值才有效，\\\n
 *  这也意味着isPreparedToPlay值为YES时，duration值才有效。\\\n
 *
 *  如果播放的是直播视频，则duration值为0。
 *
 *    @return    多媒体文件总时长(单位: 秒)
 *
 *  @see isPreparedToPlay
 */
@property(nonatomic, readonly)  NSTimeInterval duration;

/**
 *    @brief    设置当前播放时间点(用于seek操作)以及获取当前播放的时间点
 *
 *    @param     currentPlaybackTime     当前要播放的时间点(单位：秒)
 *
 *  @discussion
 *  需要在播放器发送NELivePlayerDidPreparedToPlayNotification通知后，才能调用该set方法设置到某一时间点播放，\\\n
 *  此时isPreparedToPlay的值为 YES
 *
 *    @return    get操作返回的是当前播放的时间点
 *
 *  @see isPreparedToPlay
 */
@property(nonatomic)  NSTimeInterval currentPlaybackTime;

/**
 *    @brief    获取当前可播放的视频时长(单位：秒) (只读)
 *
 *  @discussion 当播放网络视频时，该值表示已经缓冲的视频的最大时长，若此时网络端开，则只能播放到该时刻为止。
 *
 *    @return    当前缓冲时长(单位：秒)
 */
@property(nonatomic, readonly)  NSTimeInterval playableDuration;

4.3.3.3 参数介绍

参数	类型	说明
duration	NSTimeInterval	视频时长
currentPlaybackTime	NSTimeInterval	当前播放的时间
playableDuration	NSTimeInterval	缓冲时长

4.3.3.4 特殊说明

当前播放时间和缓冲时长内部更新，外部需要开启定时器轮询，并根据该值更新UI。

4.3.4 播放的实时信息相关参数

4.3.4.1 API介绍

实时信息的获取，包括音/视频接收码率，接收帧率，播放帧率，音/视频缓存时长，音/视频缓存大小，音视频播放时间差

4.3.4.2 API原型

/**
 @brief 获取文件播放的实时信息

 @return 信息结构体
 */
- (NELivePlayerRealTimeInfo *)getMediaRealTimeInfo;

4.3.4.3 返回参数介绍

参数	类型	说明
videoReceiveBitrate	NSTimeInterval	视频接收的码率
videoReceiveFramerate	NSTimeInterval	视频接收的楨率
videoPlayFramerate	NSTimeInterval	视频播放的楨率
videoCacheDuration	NSTimeInterval	视频缓存的时长
videoCacheBytes	NSTimeInterval	视频缓存的大小
audioReceiveBitrate	NSTimeInterval	音频接收的码率
audioCacheDuration	NSTimeInterval	音频缓存的时长
audioCacheBytes	NSTimeInterval	音频缓存的大小
AVPlayTimeDifference	NSTimeInterval	音频和视频的播放时间差

4.3.4.4 特殊说明

需要收到preparedToPlay通知之后再查询

4.4 数据回调

4.4.1 API介绍

视频YUV数据的回调
音频PCM数据的回调

4.4.2 API原型

/**
 * @brief 注册获取视频帧数据的回调(只支持软件解码)，用户需要实现回调函数cb来接收视频帧
 *
 * @param mFormat         回调的视频数据格式
 * @param videoRawDataCB  获取视频数据的回调函数
 *
 * @return < 0 获取失败
 */
- (int)registerGetVideoRawDataCB:(NELPVideoFormat)neVFormat and:(NELPVideoRawDataCB)videoRawDataCB;

/**
 * @brief 注册获取音频帧数据的回调，用户需要实现回调函数cb来接收音频帧
 *
 * @param audioRawDataCB  获取音频数据的回调函数
 *
 * @return < 0 获取失败
 */
- (int)registerGetAudioRawDataCB:(NELPAudioRawDataCB)audioRawDataCB;

4.4.3 参数介绍

参数	类型	说明
neVFormat	NELPVideoFormat	视频回调的格式，目前只支持YUV
videoRawDataCB	NELPVideoRawDataCB	视频回调
audioRawDataCB	NELPAudioRawDataCB	音频回调

4.4.4 示例

无

4.4.4 特殊说明

目前回调只支持软解码，硬件解码不支持回调。

4.5 时间戳校对方案

4.5.1 CDN透传方案的时间戳校对

4.5.1.1 API介绍

查询透传时间戳
监听透传时间戳

4.5.1.2 API原型

/**
 同步时间戳监听
 @param interval 查询间隔，单位毫秒
 @param callback 查询结果
 */
@property (nonatomic, readonly) NSTimeInterval currentPlaybackRealTime;

/**
 真实时间戳监听
 @param interval 查询间隔，单位毫秒
 @param callback 查询结果
 */
- (void)setRealTimeListenerWithIntervalMS:(NSTimeInterval)intervalMS
                                 callback:(NELPCurrentTimestampCallCB)callback;

4.5.1.3 参数介绍

参数	类型	说明
currentPlaybackRealTime	NSTimeInterval	推流端透传的时间戳
intervalMS	NSTimeInterval	上报透传时间戳的间隔
callback	NELPCurrentTimestampCallCB	上报的透传时间戳

4.5.1.4 示例

无

4.5.1.5 特殊说明

给用户提供两种不同的方式查询当前透传的时间戳。
为节省性能，监听方式建议在需要的时候开启，不需要的时候传入回调nil，进行关闭。

4.5.2 视频流同步方案的时间戳校对

4.5.2.1 API介绍

查询同步时间戳
监听同步时间戳

4.5.2.2 API原型

/**
 同步时间戳监听
 @param interval 查询间隔，单位毫秒
 @param callback 查询结果
 */
@property (nonatomic, readonly) NSTimeInterval currentSyncTimestamp;

/**
 同步时间戳监听
 @param interval 查询间隔，单位毫秒
 @param callback 查询结果
 */
- (void)setSyncTimestampListenerWithIntervalMS:(NSTimeInterval)intervalMS
                                      callback:(NELPCurrentTimestampCallCB)callback;

4.5.2.3 参数介绍

参数	类型	说明
currentPlaybackRealTime	NSTimeInterval	推流端同步的时间戳
intervalMS	NSTimeInterval	上报同步时间戳的间隔
callback	NELPCurrentTimestampCallCB	上报的同步时间戳

4.5.2.4 示例

无

4.5.1.5 特殊说明

给用户提供两种不同的方式查询当前同步的时间戳。
为节省性能，监听方式建议在需要的时候开启，不需要的时候传入回调nil，进行关闭。

4.6 外挂字幕

支持SRT格式的本地外挂字幕载入，包括字幕开启，关闭，切换和换源等操作。

4.5.1 API介绍

设置本地外挂字幕
设置外挂字幕状态回调
同时切换视频源和字幕

4.5.2 API原型

/**
 * @brief 设置本地外挂字幕文件（仅支持点播，格式SRT）
 *
 * @discussion 可以通过传递不同的文件路径完成字幕切换，设置为NULL时清空字幕。
 *
 * @param file 文件路径URL.请务必传入 [NSURL fileURLWithPath:path] 生成的对象！
 *
 * @return error 设置成功返回nil 失败返回具体错误类型
 */
- (NSError *)setLocalSubtitleFile:(NSURL *)file;

/**
 * @brief 设置字幕文件显示状态回调（仅支持点播）
 *
 * @discussion 字幕回调的信息不处理字幕中的格式信息，需要应用层根据业务需求自行处理。
 *
 * @param block 回调
 */
- (void)registSubtitleStatBlock:(NELivePlayerSubtitleBlock)block;

4.5.3 参数介绍

参数	类型	说明
file	NSURL	字幕文件路径
block	NELivePlayerSubtitleBlock	字幕状态回调
aUrl	NSURL	目标地址

4.5.4 示例


    NSString *srtPath1 = [[NSBundle mainBundle] pathForResource:@"1" ofType:@"srt"];

    //设置外挂字幕
    NSURL *url = [NSURL fileURLWithPath:srtPath1];
    [self.player setLocalSubtitleFile:url];

    //关闭外挂字幕
//    [self.player setSubtitleFile:NULL];

    //切换外挂字幕
//    NSString *srtPath2 = @"test2";
//    NSURL *url2 = [NSURL fileURLWithPath:srtPath2];
//    [self.player setSubtitleFile:url];
//    [self.player setSubtitleFile:url2];

    //设置监听
    __weak typeof(self) weakSelf = self;
    [self.player registSubtitleStatBlock:^(BOOL isShown, NSInteger subtitleId, NSString *subtitleText) {
        //在这里处理字幕。
        //isShow: 表示该条字幕是显示还是隐藏  subtitleId：字幕的ID  subtitleText：字幕的内容
    }];

4.5.5 特殊说明

字幕只支持SRT格式，且只支持点播
回调的字幕没有对字幕里html的格式标签做处理，需要应用层根据需要自行处理
回调的字幕可能会有额外的信息字幕，额外的信息字幕包含{}，时间段可能会与正常的字幕有交叉，需要应用层自行处理

5 总结

通过以上操作，最终的播放效果下图所示：

有关 API 的详细说明，请打开下面的在线文档。

网易云视频播放器NELivePlayer iOS SDK API详细文档

点播

产品介绍

服务端API文档

上传SDK

播放器SDK