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.framework2.2.1 集成准备
创建ViewController，如下图所示：
Subclass选择UIViewController，如下图所示：
2.2.2 快速集成
方法 1（推荐）：Cocoapods导入
执行
pod search NELivePlayer搜索资源如果搜索不到，请执行下述命令清除搜索列表缓存
rm ~/Library/Caches/CocoaPods/search_index.jsonPodfile 文件中增加如下代码：
pod 'NELivePlayer', '~> 1.7.0'
方法 2 ：手动导入库文件
将 SDK 中的lib目录下framework导入到 App 工程。
集成添加播放器 SDK 到 App 工程，在TARGETS->Build Settings->Search Paths中设置。
注意: 直接集成Framework的时候，打包如果遇到下图的问题时，请按照以下方法处理：
将Demo中的
StripFrameworks.sh脚本文件导入到工程中在 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: | 查询预调度任务 |
3.2 初始化方法
| 类别 | API名称 | 功能 |
|---|---|---|
| 创建实例1 | - (instancetype)init + (instancetype)new |
系统初始化方法，需要配合setUrl:接口使用 |
| 创建实例2 | - (instancetype)initWithNeedConfigAudioSession:(BOOL) isNeed | isNeed：是否内部配置AudioSession |
| 创建实例3 | - (instancetype)initWithContentURL: (NSURL ) aUrl error: (NSError *) error |
aUrl：直接传递待播放的URL error：返回失败原因 |
| 创建实例4 | - (instancetype)initWithContentURL: (NSURL ) aUrl needConfigAudioSession: (BOOL) isNeed error: (NSError *) error |
aUrl:待播放的URL isNeed:是否内部配置AudioSession error:返回失败原因 |
3.3 操作方法
| 类别 | API名称 | 功能 |
|---|---|---|
| 显示 | （属性）UIView *view | SDK生成, 只用于显示视频图像。 |
| 准备播放 | - (void) prepareToPlay | 初始化视频文件为播放做准备。设置数据源之后，播放前调用。 |
| 播放 | - (void) play | 播放。收到Prepare通知之后调用。 |
| 暂停 | - (void) pause | 暂停。直播该接口无效，仅针对点播。 |
| 关闭 | - (void) shutdown | 关闭。释放播放器之前调用，用于播放器资源释放。 |
| 截图 | - (UIImage *)getSnapshot | 截图。收到Prepare通知之后调用，纯音频文件该接口无效。 |
| 换源 （常规视频） |
- (int)switchContentUrl: (NSURL *) aUrl | 播放过程中切换播放地址。 注：只能用于常规视频的相互切换。 |
| 换源 （加密视频） |
- (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: 异步返回密钥检测结果。 注：只能用于已知密钥视频的相互切换。 |
| 换分辨率 （多分辨率视频） |
- (void)switchMultiMedia:(NELPMultiMediaType) mediaType complete: (void(^)(NELPSwitchStreamResult ret))completionBlock |
多分辨率文件的各分辨率之间切换。 mediaType: 分辨率类型。 complete: 返回切换结果。 |
| 换源 （带外挂字幕） |
- (int)switchContentUrl:(NSURL )aUrl subtitle:(NSURL )file | 带外挂字幕的换源。 aUrl: 目标地址。 file: 外挂字幕文件。 |
3.4 参数设置／查询
| 类别 | API名称 | 功能 |
|---|---|---|
| 设置播放的Url | - (NSError )setPlayUrl: (NSURL ) url | url: 播放Url 注：与创建实例方法1或者2一同使用， 仅限初始化后调用，不可用于URL切换。 |
| 设置缓冲策略 | - (void)setBufferStrategy: (NELPBufferStrategy) bufferStrategy |
bufferStrategy: 播放时的缓冲策略 注1：静态参数，在播放器初始化后 prepareToPlay之前调用。 注2：直播类缓存2M，点播类缓存200M。 |
| 设置开启硬件编码 | - (void)setHardwareDecoder: (BOOL) isOpen | isOpen：开启 or 关闭 注：静态参数，需在开始播放之前设置。 |
| 设置拉流超时时间 | - (void)setPlaybackTimeout:(long)timeout | timeout：超时时长。取值：[0, 30000] 毫秒 注：静态参数，需在开始播放之前设置。 |
| 设置是否自动播放 | （属性）BOOL shouldAutoplay | 收到Prepared通知后是否需要调用play。 shouldAutoplay：自动 or 手动。 注：静态参数，需在开始播放之前设置。 |
| 设置是否自动切换 （idx多分辨率文件） |
（属性）BOOL autoSwitchDefinition | 网络不好的情况下自动切最低分辨率。 autoSwitchDefinition：开启 or 关闭。 注：静态参数，需在开始播放之前设置。 |
| 设置后台是否暂停 | - (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)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完成时的时间 |
| NELivePlayerVideoParseErrorNotification | 视频码流包解析异常时的发出 |
| NELivePlayerMulitDefinitionMediaNotification | 多分辨率视频的视频流条数通知。携带UserInfo字典。 NELivePlayerMulitDefinitionMediaInfoKey：分辨率信息key，value类型详见头文件 |
| NELivePlayerVideoParseErrorNotification | 视频码流包解析异常时的发出 |
| NELivePlayerMulitDefinitionMediaNotification | 即将自动切换至最低分辨率通知。携带UserInfo字典。 NELivePlayerWillAutoSwitchDefinitionInfoKey：分辨率信息key，value类型详见头文件 |
| NELivePlayerHttpCodeResponseNotification | 播放过程中的Http状态信息通知。携带UserInfo字典。 NELivePlayerHttpCodeResponseInfoKey：HTTP状态信息key，value类型详见头文件 |
总体参数介绍
枚举值参数介绍
日志级别 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_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 | 网络直播, 延时追赶策略 |
显示模式 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.首先头文件
- 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;
/**
* @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 | 拉流地址 |
| needConfigAudioSession | BOOL | 内部是否需要配置Audiosession |
| 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;
//不同清晰度视频流的条数通知。
NELP_EXTERN NSString *const NELivePlayerMulitDefinitionMediaNotification;
//即将自动切换至最低分辨率通知。
NELP_EXTERN NSString *const NELivePlayerWillAutoSwitchDefinitionNotification;
//播放过程中的Http状态信息通知。
NELP_EXTERN NSString *const NELivePlayerHttpCodeResponseNotification;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 |
- 清晰度文件相关的信息：NELivePlayerMoviePlayerSeekCompletedNotification 的UserInfo字典。
UserInfo字典结构:
{
NELivePlayerMulitDefinitionMediaInfoKey : [NELivePlayerMulitDefinitionModel]
}| 参数 | 类型 | 说明 |
|---|---|---|
| NELivePlayerMulitDefinitionMediaInfoKey | NSString | 清晰度信息提取key |
- 自动切换至最低分辨率通知：NELivePlayerWillAutoSwitchDefinitionNotification 的UserInfo字典。
UserInfo字典结构:
{
NELivePlayerWillAutoSwitchDefinitionInfoKey : [NELivePlayerMulitDefinitionModel]
}| 参数 | 类型 | 说明 |
|---|---|---|
| NELivePlayerWillAutoSwitchDefinitionInfoKey | NSString | 清晰度信息提取key |
- HTTP状态信息通知：NELivePlayerHttpCodeResponseNotification 的UserInfo字典。
UserInfo字典结构:
{
NELivePlayerWillAutoSwitchDefinitionInfoKey : [NELivePlayerMulitDefinitionModel]
}| 参数 | 类型 | 说明 |
|---|---|---|
| NELivePlayerWillAutoSwitchDefinitionInfoKey | NSString | 清晰度信息提取key |
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];
// idx文件视频流解析通知
[[NSNotificationCenter defaultCenter] addObserver: self
selector: @selector(NELivePlayerMediaNumber:)
name: NELivePlayerMulitDefinitionMediaNotification
object: nil];
// HTTP状态通知
[[NSNotificationCenter defaultCenter] addObserver: self
selector: @selector(NELivePlayerHttpCodeResponse:)
name: NELivePlayerHttpCodeResponseNotification
object: nil];
// idx文件分辨率自动切换通知
[[NSNotificationCenter defaultCenter] addObserver: self
selector: @selector(NELivePlayerWillAutoSwitched:)
name: NELivePlayerWillAutoSwitchDefinitionNotification
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
}
//多分辨率流的解析完成通知
- (void)NELivePlayerMediaNumber:(NSNotification *)notification {
NSDictionary * userInfo = [notification userInfo];
NELivePlayerMulitDefinitionModel *mdeiaNumberModel = userInfo[NELivePlayerMulitDefinitionMediaInfoKey];
// 支持的分辨率 ：mdeiaNumberModel.resolutions
// 正在播放的分辨率：isUsed
}
//多分辨率流的自动切换通知
- (void)NELivePlayerWillAutoSwitched:(NSNotification *)notification {
NSDictionary *info = [notification userInfo];
//即将切换的目标分辨率
NELPMultiMediaType type = (NELPMultiMediaType)[info[NELivePlayerWillAutoSwitchDefinitionInfoKey] integerValue];
}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 设置是否开启硬件解码，仅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 设置播放idx多分辨率文件时，遇到卡顿是否自动切换低分辨率
*
* @param shouldAutoplay YES：自动切换 NO：不自动切换
*
* @discussion 方法仅对idx多分辨率文件有效
*
* @return 无
*/
@property(nonatomic, assign) BOOL autoSwitchDefinition;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 FLV点播加密视频的静态参数设置
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介绍
- 属性设置完成后，需调用 prepareToPlay() 接口对待播放的视频文件进行初始化，初始化完成后会发
- NELivePlayerDidPreparedToPlayNotification 通知，并将 isPreparedToPlay 设置为 YES，
- 如果 shouldAutoplay 已经设置成 YES，则会自动调用 play 进行播放，
- 如果 shouldAutoplay 设置成 NO，则需要用户调用 play() 进行播放。
4.1.5.2 API原型
/**
* @brief 设置数据源，初始化视频文件为播放做准备，在播放前调用
*
* @discussion 当prepareToPlay完成时,若shouldAutoplay 为YES，则会自动调用play进行播放，
* 若shouldAutoplay为 NO，则需手动调用play进行播放
*
* @return 无
*/
- (void)prepareToPlay;4.1.5.3 参数说明
无
4.1.5.3 示例
[self.liveplayer prepareToPlay];4.1.6 开始播放
4.1.6.1 API介绍
若 shouldAutoplay 设置成NO，则在调用 prepareToPlay() 接口后，需要调用 play() 进行播放
4.1.6.2 API原型
/**
* @brief 开始播放
*
* @discussion
* 如果当前正在播放，则调用该方法将无效果\\\n
* 此时播放器状态为: NELPMoviePlaybackStatePlaying
*
* @return 无
*/
- (void)play;4.1.6.3 参数说明
无
4.1.6.4 示例
[self.liveplayer play];4.1.7 销毁播放器实例
4.1.7.1 API介绍
- 反初始化：释放底层播放器资源。释放完成后会发送NELivePlayerReleaseSueecssNotification通知。
4.1.7.2 API原型
/**
* @brief 停止播放，并释放播放器相关资源
*
* @discussion
* 在播放器退出时，需要调用该方法用于释放资源。
*
* @return 无
*/
- (void)shutdown;4.1.7.3 参数说明
无
4.1.7.4 示例
[self.liveplayer shutdown];
self.liveplayer = nil;4.1.7.5 特殊说明
只有在释放播放器资源时使用，调用之后，务必将外部内存引用置空，播放器资源释放完毕之后会发送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介绍
- 播放过程中，实现常规视频之间的切换。
- 播放过程中，实现未知密钥的flv加密视频之间的切换。
- 播放过程中，实现已知密钥的flv加密视频之间的切换。
4.2.2.2 API原型
/**
* @brief 播放过程中切换播放地址
*
* @param aUrl 待切换的播放地址
*
* @return >= 0 切换成功， < 0 切换失败
*/
- (int)switchContentUrl:(NSURL *)aUrl;/**
* @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 | 切换的目标地址 |
| transferToken | NSString | 获取密钥的令牌 |
| accid | NSString | 视频云用户创建的其子用户id |
| appKey | NSString | 开发者平台分配的AppKey |
| token | NSString | 视频云用户子用户的token |
| complete | NSError | 异步返回密钥检测结果 |
4.2.2.4 示例
无
4.2.2.5 特殊说明
- 接口只针对同种类型的视频之间的相互切换。常规视频只能切换至常规视频，未知密钥的加密视频只能切换到未知密钥的加密视频，已知密钥的加密视频只能切换到已知密钥的加密视频。
- 调用成功之后不需要调用prepareToPlay接口，切换成功之后会收到NELivePlayerDidPreparedToPlayNotification通知，失败会收到NELivePlayerPlaybackFinishedNotification通知。
- 密钥类的切换方法，如果密钥检测失败会直接通过回调返回，不再发送任何通知。
- 为安全起见，外部调用最好保持串行调用，调用后收到结果通知后，再进行下次的切换。
- 外部可以使用shutdown和init相关接口搭配使用，替换该功能。
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.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;
/**
@brief 播放过程中切换播放地址
@param aUrl 待切换的播放地址
@param file 字幕文件
@return >= 0 切换成功， < 0 切换失败
*/
- (int)switchContentUrl:(NSURL *)aUrl subtitle:(NSURL *)file;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 的详细说明，请打开下面的在线文档。