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的时候,打包如果遇到下图的问题时,请按照以下方法处理:
将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: | 查询预调度任务 |
设置预调度结果有效期 | + (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 | 网络直播, 延时追赶策略 |
显示模式 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;
/**
初始化播放器
@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 点播加密视频的静态参数设置(即将废弃)
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 的详细说明,请打开下面的在线文档。