全部产品
云市场

基础播放器接口说明

更新时间:2019-04-16 20:56:20

AliVcPlayerDefine.h

播放器通知定义

  1. /**
  2. * AliVcMediaPlayerLoadDidPreparedNotification:播放器初始化视频文件完成通知,调用prepareToPlay函数,会发送该通知,代表视频文件已经准备完成,此时可以在这个通知中获取到视频的相关信息,如视频分辨率,视频时长等。
  3. * AliVcMediaPlayerPlaybackDidFinishNotification:播放完成通知,当视频正常播放完成后会收此通知。
  4. * AliVcMediaPlayerPlaybackStopNotification:当前调用播放器Stop接口时会收到此通知。
  5. * AliVcMediaPlayerStartCachingNotification:播放器开始缓冲视频时发送该通知,当播放网络文件时,网络状态不佳或者调用seekTo时,此通知告诉用户网络下载数据已经开始缓冲。
  6. * AliVcMediaPlayerEndCachingNotification:播放器结束缓冲视频时发送该通知,当数据已经缓冲完,告诉用户已经缓冲结束,来更新相关UI显示。
  7. * AliVcMediaPlayerPlaybackErrorNotification:播放器播放失败发送该通知,并在该通知中可以获取到错误码。
  8. * AliVcMediaPlayerSeekingDidFinishNotification:播放器位置改变完成后发送该通知。
  9. * AliVcMediaPlayerFirstFrameNotification:播放器状态首帧显示后发送的通知。
  10. 播放器通知发送逻辑:
  11. 1. 调用prepareToPlay成功后发送AliVcMediaPlayerLoadDidPreparedNotification通知,失败则会发送AliVcMediaPlayerPlaybackErrorNotification。
  12. 2. 调用play、pause、stop、prepareToPlay、seekTo失败后发送AliVcMediaPlayerPlaybackErrorNotification通知。
  13. 3. 调用stop/reset成功后播放视频结束发送AliVcMediaPlayerPlaybackStopNotification通知
  14. 4. 播放器自动播放结束会发送AliVcMediaPlayerPlaybackDidFinishNotification通知。
  15. 5. 调用seekTo成功后发送AliVcMediaPlayerSeekingDidFinishNotification通知。
  16. 6. AliVcMediaPlayerStartCachingNotification和AliVcMediaPlayerEndCachingNotification通知,这个是在网络视频缓冲数据不足以够播放后会发送此通知,一般网络视频在调用seekTo后会发送此通知。
  17. 7. AliVcMediaPlayerCircleStartNotification通知,开启循环播放模式,进入循环播放开始时发送此通知。
  18. 8. 播放视频第一帧时发送此通知。
  19. 9. 开启循环播放功能,在进入循环播放时发送此通知。
  20. 10. 接收播放答题时SEI数据.
  21. */
  22. ALIVC_EXTERN NSString * const AliVcMediaPlayerLoadDidPreparedNotification;
  23. ALIVC_EXTERN NSString * const AliVcMediaPlayerPlaybackErrorNotification;
  24. ALIVC_EXTERN NSString * const AliVcMediaPlayerPlaybackStopNotification;
  25. ALIVC_EXTERN NSString * const AliVcMediaPlayerPlaybackDidFinishNotification;
  26. ALIVC_EXTERN NSString * const AliVcMediaPlayerSeekingDidFinishNotification;
  27. ALIVC_EXTERN NSString * const AliVcMediaPlayerStartCachingNotification;
  28. ALIVC_EXTERN NSString * const AliVcMediaPlayerEndCachingNotification;
  29. ALIVC_EXTERN NSString * const AliVcMediaPlayerFirstFrameNotification;
  30. ALIVC_EXTERN NSString * const AliVcMediaPlayerCircleStartNotification;
  31. ALIVC_EXTERN NSString * const AliVcMediaPlayerSeiDataNotification;

调试信息的key指,用于接口getAllDebugInfo信息返回值的dictionary的key的值

  1. //视频解码帧率,double值
  2. #define FLT_VIDEO_DECODE_FPS @"dec-fps"
  3. //视频下载帧率,double值
  4. #define FLT_VIDEO_OUTPUT_FPS @"out-fps"
  5. //视频stream index值,int64值
  6. #define INT64_SELECT_VIDEO_STREAM @"select_v"
  7. //音频stream index值,int64值
  8. #define INT64_SELECT_AUDIO_STREAM @"select_a"
  9. //视频缓冲的长度,int64值
  10. #define INT64_VIDEO_CACHE_DURATION @"vcache-dur"
  11. //音频缓冲的长度,int64值
  12. #define INT64_AUDIO_CACHE_DURATION @"acache-dur"
  13. //视频缓冲的字节数,int64值
  14. #define INT64_VIDEO_CACHE_BYTES @"vcache-bytes"
  15. //音频缓冲的字节数,int64值
  16. #define INT64_AUDIO_CACHE_BYTES @"acache-bytes"
  17. //视频缓冲的packet个数,int64值
  18. #define INT64_VIDEO_CACHE_PACKETS @"vcache-pkts"
  19. //音频缓冲的packet个数,int64值
  20. #define INT64_AUDIO_CACHE_PACKETS @"acache-pkts"
  21. //视频首帧显示时间,double值
  22. #define FLT_1ST_VFRAME_SHOW @"1st-vframeshow"
  23. //视频find stream info的时间
  24. #define FLT_FIND_STREAM_TIME @"find-stream"
  25. //视频open format 的时间
  26. #define FLT_OPEN_FORMAT_TIME @"open-format"
  27. //视频tcp dns解析的时间
  28. #define FLT_TCP_DNS_TIME @"tcp-dns-time"
  29. //视频tcp connect解析的时间
  30. #define FLT_TCP_CONNECT_TIME @"tcp-connect-time"
  31. //视频rtmp open解析的时间
  32. #define FLT_RTMP_OPEN_TIME @"rtmp-open-time"
  33. //视频http open解析的时间
  34. #define FLT_HTTP_OPEN_TIME @"http-open-time"

AliVcMediaPlayer.h

功能:基础播放器的管理类,用于创建播放器实例。

成员 功能
create 创建播放器,并设置播放器显示窗口
prepareToPlay 播放器初始化视频文件
play 播放当前视频
stop 停止当前视频播放
pause 暂停当前视频播放
seekTo 跳转视频到新的播放位置
reset 重置播放器
destroy 销毁播放器
getSDKVersion 获取SDK版本号
view 包含视频内容的view
currentPosition 获取当前视频播放位置,只读属性,获取单位为毫秒
videoHeight 获取视频高度,只读属性
videoWidth 获取视频宽度,只读属性
mediaType 设置是直播还是点播,1为直播,0为点播,默认为-1不进行设置
timeout 设置网络超时时间,单位毫秒
dropBufferDuration 当直播时,缓冲区数据大于dropBufferDuration时开始丢数据,单位毫秒,默认8000毫秒
duration 获取视频时长,只读属性,单位为毫秒
bufferingPostion 获取缓冲的时长,只读属性,单位为毫秒
setBussinessID 设置业务ID
isPlaying 是否正在播放
muteMode 设置静音模式
scalingMode 设置视频渲染的缩放模式
errorCode 获取播放器错误代码
volume 设置/获取音量
brightness 设置/获取屏幕亮度
printLog 控制台是否打印日志
getAllDebugInfo 获取播放器调试信息
playSpeed 设置倍数播放值
getAudioData 音频数据回调接口
circlePlay 循环播放控制
snapshot 截取当前正在播放图像
setRenderMirrorMode 设置渲染镜像
setRenderRotate 渲染视图角度
setReferer 防盗链参数

下面详细介绍一下各成员函数的具体使用:

create

  • -(AliVcMovieErrorCode) create: (UIView*)view;
    1. 功能:创建播放器,并设置播放器显示窗口。播放器内部会新建各个播放器变量并初始化,并启动播放器内部流水线线程等。
    2. 参数:UIView* view,播放器显示窗口
    3. 备注:如果创建播放器的时候view没有,则可以传递nil,可以在后续需要设置view

prepareToPlay

  • -(AliVcMovieErrorCode) prepareToPlay: (NSURL*)dataSource;
    1. 功能:播放器初始化视频文件,主要目的是分析视频文件内容,读取视频头信息,解析视频流中的视频和音频信息,并根据视频和音频信息去寻找解码器,创建播放线程等。
    2. 返回值:当初始化视频文件成功,返回ALIVC_SUCCESS,否则返回失败,具体的逻辑如下:
    3. 1. 验证视频源dataSource是否为空,为空则返回ALIVC_ERR_NO_INPUTFILE
    4. 2. 如果播放器是正在播放或者正在暂停状态,则不能够进行prepare,此时返回非法的播放流程错误ALIVC_ERR_ILLEGALSTATUS,如果播放器状态是已经是准备完成状态,则返回ALIVC_SUCCESS
    5. 3. 对视频进行初始化,如果成功,则会发送LoadDidPreparedNotification通知,表示视频初始化完成。如果失败则会发送PlaybackErrorNotification通知,在错误通知中可以获取到错误代码。
    6. * 备注:调用该函数完成后立即返回,需要等待准备完成通知AliVcMediaPlayerLoadDidPreparedNotification,收到该通知后代表视频初始化完成,视频准备完成后可以获取到视频的相关信息如:durationvideoWidthvideoHeight

prepareToPlay:videoKey:circleCount

  • (AliVcMovieErrorCode) prepareToPlay: (NSURL)url AndvideoKey:(NSString )videoKey AndcircleCount:(int)circleCount;
    1. 功能:播放加密视频
    2. videoKey: 加密key
    3. circleCount : 加密级别

play

  • -(AliVcMovieErrorCode) play;
    1. 功能:播放当前视频
    2. 返回值:当播放视频成功,返回ALIVC_SUCCESS,否则返回失败,具体见下述逻辑:
    3. 1.如果播放器是停止的状态,则直接返回ALIVC_ERR_ILLEGALSTATUS错误,如果此时播放器为播放的状态,直接返回ALIVC_SUCCESS
    4. 2.如果播放器在暂停或者准备完成的状态,则直接启动视频播放。
    5. 备注:播放器调用play进行播放,必须在播放器状态为准备完成的状态或者暂停的状态才能进行播放,其他情况都不能够将视频播放起来。

stop

  • -(AliVcMovieErrorCode) stop;
    1. 功能:停止当前视频播放,调用此函数则是结束视频播放,视频显示为黑屏,并回到视频播放起始点。
    2. 返回值:停止视频播放成功ALIVC_SUCCESS。否则返回失败。具体逻辑如下:
    3. 1.如果此时播放器的状态为停止状态,直接返回ALIVC_SUCCESS
    4. 2.其他情况则停止视频播放,并将播放器状态设置为Stopped,视频停止后会发送视频结束通知AliVcMediaPlayerPlaybackStopNotification
    5. 备注:该函数会停止掉内部音视频解码线程,如果需要重新进行播放,则需要再调用prepareToPlay进行重新对视频进行初始化。

pause

  • -(AliVcMovieErrorCode) pause;
    1. 功能:暂停当前视频播放
    2. 返回值:暂停视频播放成功ALIVC_SUCCESS。否则返回失败。具体逻辑如下:
    3. 1.如果此时播放器的状态为暂停状态,直接返回ALIVC_SUCCESS
    4. 2.如果播放器状态为停止或者准备完成状态则返回错误的播放器状态ALIVC_ERR_ILLEGALSTATUS
    5. 3.其他情况则暂停视频播放,并将播放器状态设置为暂停状态。
    6. 备注:播放器调用pause暂停视频播放,一般是在视频播放的情况下调用此函数。

seekTo

  • -(AliVcMovieErrorCode) seekTo: (NSTimeInterval) newPos;
    1. 功能:跳转视频到新的播放位置
    2. 参数:newPos,单位为毫秒
    3. 返回值:跳转成功ALIVC_SUCCESS。否则返回失败。具体逻辑如下:
    4. 1.如果此时播放器的状态为停止或准备完成状态,返回错误的播放器状态ALIVC_ERR_ILLEGALSTATUS
    5. 2.其他情况则进行视频跳转,返回等待视频跳转结束通知AliVcMediaPlayerSeekingDidFinishNotification
    6. 备注:该函数为异步函数,调用此函数后并不会立即进行视频跳转,需要等待视频跳转结束通知。参数的范围为[0,duration],如果传入的参数小于0,则播放器内部会自动跳转到0,如果传入参数大于duration,则会跳转到duration最后位置。

reset

  • -(AliVcMovieErrorCode) reset;
    1. 功能:重置播放器,其目的是将播放器所有状态恢复到最初位置,当播放器内部出现错误或其它问题时,调用此函数来进行恢复。
    2. 返回值:如果权限验证通过,则会返回ALIVC_SUCCESS
    3. 备注:该函数和stop函数的区别是,reset也能够实现stop的功能,但是reset会去销毁播放器内部的各种变量,然后重新进行变量初始化,view变量等会被设置成空,如果需要播放,则需要重新设置view,并且调用create重新初始化播放器内部各个变量。

destroy

  • -(AliVcMovieErrorCode) destroy;
    1. 功能:销毁播放器,该函数用来释放播放器内部的所有变量,退出所有线程。
    2. 备注:在退出播放器的时候必须调用该函数,用来进行内存释放,否则会存在内存泄露。

getPropertyDouble

  • -(double) getPropertyDouble:(int)property defaultValue:(double)defaultValue;
    1. 功能:获取SDK中日志的一些属性,double值。
    2. 返回值:返回double型日志属性。

getPropertyLong

  • -(double) getPropertyLong:(int)property defaultValue:(double)defaultValue;
    1. 功能:获取SDK中日志的一些属性,double值。
    2. 返回值:返回int64型日志属性。

getPropertyString

  • -(double) getPropertyString:(int)property defaultValue:(double)defaultValue;
    1. 功能:获取SDK中日志的一些属性,double值。
    2. 返回值:返回字符型日志属性。。

isPlaying

  • -(BOOL)isPlaying;
    1. 功能:是否正在播放

view

  • @property(nonatomic, retain) UIView *view;
    1. 功能:包含视频内容的view
    2. * 备注:需要在调用prepareToPlay之前设置view,当前view只有视频帧图像,没有相关控制组件,相当于iOS系统播放器MPMoviePlayerController的控制方式controlStyleMPMovieControlStyleNone的效果。

currentPosition

  • @property(nonatomic, readonly) NSTimeInterval currentPosition;
    1. 功能:获取当前视频播放位置,只读属性,获取单位为毫秒。
    2. 备注:当播放器状态为正在播放或暂停的状态,能够获取到有效值,否则获取值为无效0

videoHeight

  • @property(nonatomic, readonly) int videoHeight; `
    1. 功能:获取视频高度,只读属性。
    2. 备注:当调用了prepareToPlay后,并不能立即获得videoHeight的值,只有当播放器发送了prepared通知后,videoHeight的值才有效,否则为默认值0

videoWidth

  • @property(nonatomic, readonly) int videoWidth;
    1. 功能:获取视频宽度,只读属性。
    2. 备注:当调用了prepareToPlay后,并不能立即获得videoWidth的值,只有当播放器发送了prepared通知后,videoWidth的值才有效,否则为默认值0

mediaType

  • @property(nonatomic, readwrite) MediaType mediaType;`
    1. 功能:设置是直播还是点播,1为直播,0为点播,默认为-1不进行设置
    2. 备注:设置了是直播还是点播,不由播放器自动判定

timeout

  • @property(nonatomic, readwrite) int timeout;
    1. 功能:设置网络超时时间,单位毫秒
    2. 备注:当播放网络流时,设置网络超时时间,默认15000毫秒

dropBufferDuration

  • @property(nonatomic, readwrite) int dropBufferDuration;
    1. 功能:当直播时,缓冲区数据大于dropBufferDuration时开始丢数据,单位毫秒,默认8000毫秒
    2. 备注:必须大于一个GOP的长度。

duration

  • @property(nonatomic, readonly) NSTimeInterval duration;
    1. 功能:获取视频时长,只读属性,单位为毫秒。
    2. 备注:当调用了prepareToPlay后,并不能立即获得duration的值,只有当播放器发送了prepared通知后,duration的值才有效,否则为默认值0

bufferingPostion

  • @property(nonatomic, readonly) NSTimeInterval bufferingPostion;
    1. 功能:获取缓冲的时长,只读属性,单位为毫秒。
    2. 备注:当调用了prepareToPlay后,并且开始播放后,才能获取该值。

scalingMode

  • @property(nonatomic, readwrite) ScalingMode scalingMode;
    1. 功能:获取缓冲的时长,只读属性,单位为毫秒。
    2. 备注:当调用了prepareToPlay后,并且开始播放后,才能获取该值。

muteMode

  • @property(nonatomic, readwrite) BOOL muteMode;`
    1. 功能:设置是否静音,YES为静音

keepLastFrame

  • @property(nonatomic, readwrite) BOOL keepLastFrame;
    1. 功能:设置stop或者播放结束后是否保留显示最后一帧,默认YES显示

errorCode

  • @property(nonatomic, readonly) AliVcMovieErrorCode errorCode;`
    1. 功能:获取播放器错误代码(只读)

其中,AliVcMovieErrorCode为枚举类型,各枚举值含义以及对应返回的params为:

枚举变量 含义 value
ALIVC_SUCCESS 无错误 0
ALIVC_ERR_INVALID_PARAM 参数非法,请检查输入参数 4001
ALIVC_ERR_INVALID_INPUTFILE 无效的输入,请检查输入地址或者网络链接 4003
ALIVC_ERR_NO_INPUTFILE 没有设置视频源 4004
ALIVC_ERR_LOADING_TIMEOUT 视频加载超时,请检查网络状况 4008
ALIVC_ERR_VIDEO_FORMAT_UNSUPORTED 视频格式不支持 4011
ALIVC_ERR_NO_SUPPORT_CODEC 视频编码格式不支持 4019
ALIVC_ERR_ILLEGALSTATUS 非法的播放器状态,当前状态是xx 4021
ALIVC_ERR_NO_MEMORY 没有足够的内存 4023

volume

  • @property(nonatomic, readwrite) float volume;`
    1. 功能:设置/获取音量接口
    2. 备注:此接口操作的是系统的音量接口, 范围为0.0-1.0

brightness

  • @property(nonatomic, readwrite) float brightness;
    1. 功能:设置/获取屏幕亮度接口
    2. 备注:此接口操作的是系统的屏幕亮度接口, 范围为0.0-1.0

playSpeed

  • @property(nonatomic, readwrite) float playSpeed;
    1. 功能:播放器倍数播放,支持0.5~2倍速播放(默认值为1
    2. 备注:建议档位为0.5倍(慢速播放)、1倍(正常播放)、1.25倍(加速播放)、1.5倍(加速播放)、2倍(加速播放)

printLog

  • @property(nonatomic, readwrite) BOOL printLog;
    1. 功能:控制台是否打印日志
    2. 备注:YES表示打印日志,NO表示不打印,一般用于开发者调试使用

circlePlay

  • @property(nonatomic, readwrite) BOOL circlePlay;
    1. 功能:循环播放控制。

getAudioData

  • -(void) getAudioData:(void (^)(NSData *data))block;
    1. 功能:当视频播放时将音频数据回调。
    2. 备注:这个回调中不能做耗时操作。因为底层播放会在回调结束之后继续,所以如果耗时,会导致音频播放有问题。

setRenderRotate

  • -(void) setRenderRotate:(RenderRotate)rotate;
    1. 功能:设置渲染视图角度

setRenderMirrorMode

  • -(void) setRenderMirrorMode:(RenderMirrorMode)mirrorMode;`
    1. 功能:设置渲染镜像

snapshot

  • -(UIImage*) snapshot;
    1. 功能:截取当前正在播放图像。

setReferer

  • -(void)setReferer:(NSString *)referer;
    1. 功能:设置referer
    2. 控制台设置防盗链流程:
    3. 1.控制台-防盗链-开启防盗链。
    4. 2.添加黑白名单(黑名单:如果设置referer是被添加的域名,则不能访问,白名单:如果设置的referer被添加到白名单的域名才可以访问)。<br>
    5. 3.默认不选中允许空referer,如果允许空refer,则客户端不设置referer是可以访问的。如果设置了,但是错误的,则不能访问。

getSDKVersion

  • -(NSString *) getSDKVersion;
    1. 功能:获取SDK版本号。
    2. 返回值:返回NSString类型的版本号。
    3. 备注:当开发者反馈问题时,请使用该方法获得SDK版本号并随同问题一起反馈。

getAllDebugInfo

  • -(NSDictionary*)getAllDebugInfo;
    1. 功能:获取播放器调试信息,返回调试信息字典

调试信息字典为键值对,值统一为NSNumber,key的定义如下

key定义 含义 value类型
FLT_VIDEO_DECODE_FPS 视频解码帧率 double
FLT_VIDEO_OUTPUT_FPS 视频下载帧率 double
INT64_SELECT_VIDEO_STREAM 视频stream index值 LONGLONG
INT64_SELECT_AUDIO_STREAM 音频stream index值 LONGLONG
INT64_VIDEO_CACHE_DURATION 视频缓冲的长度 LONGLONG
INT64_AUDIO_CACHE_DURATION 音频缓冲的长度 LONGLONG
INT64_VIDEO_CACHE_BYTES 视频缓冲的字节数 LONGLONG
INT64_AUDIO_CACHE_BYTES 音频缓冲的字节数 LONGLONG
INT64_VIDEO_CACHE_PACKETS 视频缓冲的packet个数 LONGLONG
INT64_AUDIO_CACHE_PACKETS 音频缓冲的packet个数 LONGLONG
FLT_1ST_VFRAME_SHOW 视频首帧显示时间 LONGLONG
FLT_FIND_STREAM_TIME 视频find stream info的时间 LONGLONG
FLT_OPEN_STREAM_TIME 视频open stream的时间 LONGLONG
FLT_TCP_DNS_TIME 视频tcp dns解析的时间 LONGLONG
FLT_TCP_CONNECT_TIME 视频tcp connect解析的时间 LONGLONG
FLT_RTMP_OPEN_TIME 视频rtmp open解析的时间 LONGLONG
FLT_HTTP_OPEN_TIME 视频http open解析的时间 LONGLONG

备注:YES表示打印日志,NO表示不打印,一般用于开发者调试使用