ZFPlayer 3.0解析

9字数 532阅读 33043

详细介绍一下ZFPlayer 3.0的用法,如果你有什么问题或者建议可联系我。在3.0之前版本使用ZFPlayer,是不是在烦恼播放器SDK自定义、控制层自定义等问题。作者公司多个项目分别使用不同播放器SDK以及每个项目控制层都不一样,但是为了统一管理、统一调用,我特意写了这个播放器壳子。播放器SDK只要遵守ZFPlayerMediaPlayback协议,控制层只要遵守ZFPlayerMediaControl协议,可以实现自定义播放器和控制层。

目前支持的功能如下:

  • 普通模式的播放,类似于腾讯视频、爱奇艺等APP;
  • 列表普通模式的播放,包括手动点击播放、滑动到屏幕中间自动播放,wifi网络智能播放等等;
  • 列表的亮暗模式播放,类似于微博、UC浏览器视频列表等APP;
  • 列表视频滑出屏幕后停止播放、滑出屏幕后小窗播放;
  • 优雅的全屏,支持横屏和竖屏全屏模式;

播放器的主要类为ZFPlayerController,具体API请看下边这张图吧,后边我也会详细介绍。在之前版本收到好多开发朋友的Issues建议也好bug也好,ZFPlayer也是致力于解决这些问题和满足各位的建议。

ZFPlayer思维导图

ZFPlayerController(播放器的主要类)

初始化方式:

/// 普通播放的初始化
+ (instancetype)playerWithPlayerManager:(id<ZFPlayerMediaPlayback>)playerManager containerView:(UIView *)containerView;

/// 普通播放的初始化
- (instancetype)initWithPlayerManager:(id<ZFPlayerMediaPlayback>)playerManager containerView:(UIView *)containerView;

/// UITableView、UICollectionView播放的初始化
+ (instancetype)playerWithScrollView:(UIScrollView *)scrollView playerManager:(id<ZFPlayerMediaPlayback>)playerManager containerViewTag:(NSInteger)containerViewTag;

/// UITableView、UICollectionView播放的初始化
- (instancetype)initWithScrollView:(UIScrollView *)scrollView playerManager:(id<ZFPlayerMediaPlayback>)playerManager containerViewTag:(NSInteger)containerViewTag;

/// UIScrollView播放的初始化
+ (instancetype)playerWithScrollView:(UIScrollView *)scrollView playerManager:(id<ZFPlayerMediaPlayback>)playerManager containerView:(UIView *)containerView;

/// UIScrollView播放的初始化
- (instancetype)initWithScrollView:(UIScrollView *)scrollView playerManager:(id<ZFPlayerMediaPlayback>)playerManager containerView:(UIView *)containerView;

属性

/// 初始化时传递的容器视图,用来显示播放器view,和播放器view同等大小
@property (nonatomic, strong) UIView *containerView;

/// 初始化时传递的播放器manager,必须遵守`ZFPlayerMediaPlayback`协议
@property (nonatomic, strong) id<ZFPlayerMediaPlayback> currentPlayerManager;

/// 此属性是设置显示的控制层,自定义UIView遵守`ZFPlayerMediaControl`协议,实现相关协议就可以满足自定义控制层的目的。
@property (nonatomic, strong) UIView<ZFPlayerMediaControl> *controlView;

/// 通知的管理类
@property (nonatomic, strong, readonly) ZFPlayerNotification *notification;

/// 容器的类型(cell和普通View)
@property (nonatomic, assign, readonly) ZFPlayerContainerType containerType;

/// 播放器小窗的容器View
@property (nonatomic, strong, readonly) ZFFloatView *smallFloatView;

/// 播放器小窗是否正在显示
@property (nonatomic, assign, readonly) BOOL isSmallFloatViewShow;

ZFPlayerController (ZFPlayerTimeControl)

/// 当前播放视频的时间 
@property (nonatomic, readonly) NSTimeInterval currentTime;

/// 当前播放视频总时间 
@property (nonatomic, readonly) NSTimeInterval totalTime;

/// 当前播放视频缓冲时间 
@property (nonatomic, readonly) NSTimeInterval bufferTime;

/// 根据播放的时间和总时间,计算出当前播放的进度,取值范围0...1
@property (nonatomic, readonly) float progress;

/// 根据播放缓冲时间和总时间,计算出当前缓冲的进度,取值范围0...1
@property (nonatomic, readonly) float bufferProgress;

/// 调节播放进度
- (void)seekToTime:(NSTimeInterval)time completionHandler:(void (^ __nullable)(BOOL finished))completionHandler;

ZFPlayerController (ZFPlayerPlaybackControl)

/// 0...1.0,调节系统的声音,要是调节播放器声音可以使用播放器管理类设置
@property (nonatomic) float volume;

/// 系统静音,要是调节播放器静音可以使用播放器管理类设置
@property (nonatomic, getter=isMuted) BOOL muted;

// 0...1.0, 系统屏幕亮度
@property (nonatomic) float brightness;

/// 移动网络下自动播放, default is NO.
@property (nonatomic, getter=isWWANAutoPlay) BOOL WWANAutoPlay;

/// 当前播放的下标,只适用于设置了`assetURLs`
@property (nonatomic) NSInteger currentPlayIndex;

/// 在 `assetURLs`中是否是最后一个
@property (nonatomic, readonly) BOOL isLastAssetURL;

/// 在 `assetURLs`中是否是第一个
@property (nonatomic, readonly) BOOL isFirstAssetURL;

/// 当退到后台后是否暂停播放,前提是支持后台播放器模式,default is YES.
@property (nonatomic) BOOL pauseWhenAppResignActive;

/// 当播放器在玩播放时,它会被一些事件暂停,而不是用户点击暂停。
/// 例如,应用程序进入后台或者push到另一个视图控制器
@property (nonatomic, getter=isPauseByEvent) BOOL pauseByEvent;

/// 当前播放器控制器消失,而不是dealloc
@property (nonatomic, getter=isViewControllerDisappear) BOOL viewControllerDisappear;

/// 自定义AVAudioSession, default is NO.
@property (nonatomic, assign) BOOL customAudioSession;

/// 当播放器Prepare时候调用
@property (nonatomic, copy, nullable) void(^playerPrepareToPlay)(id<ZFPlayerMediaPlayback> asset, NSURL *assetURL);

///当播放器准备开始播放时候调用
@property (nonatomic, copy, nullable) void(^playerReadyToPlay)(id<ZFPlayerMediaPlayback> asset, NSURL *assetURL);

/// 当播放进度改变时候调用.
@property (nonatomic, copy, nullable) void(^playerPlayTimeChanged)(id<ZFPlayerMediaPlayback> asset, NSTimeInterval currentTime, NSTimeInterval duration);

/// 当缓冲进度改变时候调用
@property (nonatomic, copy, nullable) void(^playerBufferTimeChanged)(id<ZFPlayerMediaPlayback> asset, NSTimeInterval bufferTime);

/// 当播放状态改变时候调用
@property (nonatomic, copy, nullable) void(^playerPlayStateChanged)(id<ZFPlayerMediaPlayback> asset, ZFPlayerPlaybackState playState);

/// 当加载状态改变时候调用.
@property (nonatomic, copy, nullable) void(^playerLoadStateChanged)(id<ZFPlayerMediaPlayback> asset, ZFPlayerLoadState loadState);

/// 当播放失败时候调用.
@property (nonatomic, copy, nullable) void(^playerPlayFailed)(id<ZFPlayerMediaPlayback> asset, id error);

/// 当播放状态完成时候调用.
@property (nonatomic, copy, nullable) void(^playerDidToEnd)(id<ZFPlayerMediaPlayback> asset);

// 当播放器view的尺寸改变时候调用.
@property (nonatomic, copy, nullable) void(^presentationSizeChanged)(id<ZFPlayerMediaPlayback> asset, CGSize size);

/// 播放下一个,只适用于设置了`assetURLs`
- (void)playTheNext;

/// 播放上一个,只适用于设置了`assetURLs`
- (void)playThePrevious;

/// 播放某一个,只适用于设置了`assetURLs`
- (void)playTheIndex:(NSInteger)index;

/// 停止播放,并且把播放器view和相关通知移除
- (void)stop;

/// 切换当前的PlayerManager,适用场景:播放某一个视频时候使用特定的播放器管理类
- (void)replaceCurrentPlayerManager:(id<ZFPlayerMediaPlayback>)manager;

/**
 添加播放器view到cell上
 */
- (void)addPlayerViewToCell;

/**
 添加播放器view到容器view上.
 */
- (void)addPlayerViewToContainerView:(UIView *)containerView;

/**
 添加播放器到主window上.
 */
- (void)addPlayerViewToKeyWindow;

/**
 停止当前在view上的播放并移除播放器view.
 */
- (void)stopCurrentPlayingView;

/**
 停止当前在cell上的播放并移除播放器view.
 */
- (void)stopCurrentPlayingCell;

ZFPlayerController (ZFPlayerOrientationRotation)

/// 屏幕旋转管理类
@property (nonatomic, readonly) ZFOrientationObserver *orientationObserver;

///是否支持自动屏幕旋转。
/// iOS8.1~iOS8.3的值为YES,其他iOS版本的值为NO。
///这个属性用于UIViewController ' shouldAutorotate '方法的返回值。
@property (nonatomic, readonly) BOOL shouldAutorotate;

///是否允许视频方向旋转。
///默认值是YES。
@property (nonatomic) BOOL allowOrentitaionRotation;

/// 是否是全屏状态,当ZFFullScreenMode == ZFFullScreenModeLandscape,当currentOrientation是LandscapeLeft或者LandscapeRight,这个值是YES
/// 当ZFFullScreenMode == ZFFullScreenModePortrait,当视频全屏后,这个值是YES
@property (nonatomic, readonly) BOOL isFullScreen;

/// 锁定当前的屏幕方向,目的是禁止设备自动旋转
@property (nonatomic, getter=isLockedScreen) BOOL lockedScreen;

/// 隐藏系统的状态栏
@property (nonatomic, getter=isStatusBarHidden) BOOL statusBarHidden;

/// 使用设备方向旋转屏幕, default NO.
@property (nonatomic, assign) BOOL forceDeviceOrientation;

/// 播放器view当前方向
@property (nonatomic, readonly) UIInterfaceOrientation currentOrientation;

/// 当即将全屏时候会调用
@property (nonatomic, copy, nullable) void(^orientationWillChange)(ZFPlayerController *player, BOOL isFullScreen);

/// 当已经全屏时候会调用
@property (nonatomic, copy, nullable) void(^orientationDidChanged)(ZFPlayerController *player, BOOL isFullScreen);

/// 添加设备方向的监听
- (void)addDeviceOrientationObserver;

/// 移除设备方向的监听
- (void)removeDeviceOrientationObserver;

/// 当 ZFFullScreenMode == ZFFullScreenModeLandscape使用此API设置全屏切换
- (void)enterLandscapeFullScreen:(UIInterfaceOrientation)orientation animated:(BOOL)animated;

/// 当 ZFFullScreenMode == ZFFullScreenModePortrait使用此API设置全屏切换
- (void)enterPortraitFullScreen:(BOOL)fullScreen animated:(BOOL)animated;

/// 内部根据ZFFullScreenMode的值来设置全屏切换
- (void)enterFullScreen:(BOOL)fullScreen animated:(BOOL)animated;

ZFPlayerController (ZFPlayerViewGesture)

/// 手势的管理类
@property (nonatomic, readonly) ZFPlayerGestureControl *gestureControl;

/// 禁用哪些手势,默认支持单击、双击、滑动、缩放手势
@property (nonatomic, assign) ZFPlayerDisableGestureTypes disableGestureTypes;

///不支持的平移手势移动方向
@property (nonatomic) ZFPlayerDisablePanMovingDirection disablePanMovingDirection;

ZFPlayerController (ZFPlayerScrollView)

/// 初始化时候设置的scrollView
@property (nonatomic, readonly, nullable) UIScrollView *scrollView;

/// 只适用于列表播放时候是否自动播放,default is YES.
@property (nonatomic) BOOL shouldAutoPlay;

/// 移动网络自动播放,只有当“shouldAutoPlay”为YES时才支持,默认为NO
@property (nonatomic, getter=isWWANAutoPlay) BOOL WWANAutoPlay;

/// 当前播放的indexPath 
@property (nonatomic, nullable) NSIndexPath *playingIndexPath;

/// 初始化时候设置的containerViewTag,根据此tag在cell上找到播放器view显示的位置
@property (nonatomic) NSInteger containerViewTag;

/// 滑出屏幕后是否停止播放,如果设置为NO,滑出屏幕后则会小窗播放,defalut is YES.
@property (nonatomic) BOOL stopWhileNotVisible;

/**
当前播放器滚动滑出屏幕的百分比。
当`stopWhileNotVisible`为YES时使用的属性,停止当前正在播放的播放器。
当`stopWhileNotVisible`为NO时使用的属性,当前正在播放的播放器添加到小容器视图。
范围是0.0~1.0,defalut是0.5。
0.0是player将会消失。
1.0是player消失了。
*/
@property (nonatomic) CGFloat playerDisapperaPercent;

/**
当前播放器滚动到屏幕百分比来播放视频。
范围是0.0~1.0,defalut是0.0。
0.0是玩家将会出现。
1.0是播放器确实出现了。
 */
@property (nonatomic) CGFloat playerApperaPercent;

/// 如果列表播放时候有多个区,使用此API
@property (nonatomic, copy, nullable) NSArray <NSArray <NSURL *>*>*sectionAssetURLs;

/**
播放url的indexPath,而' assetURLs '或' sectionAssetURLs '不为空。

@param indexPath播放url的indexPath。
 */
- (void)playTheIndexPath:(NSIndexPath *)indexPath;

/**
播放url的indexPath,而' assetURLs '或' sectionAssetURLs '不为空。

@param indexPath播放url的indexPath
@param scrollToTop使用动画将当前单元格滚动到顶部。
*/
- (void)playTheIndexPath:(NSIndexPath *)indexPath scrollToTop:(BOOL)scrollToTop;

/**
播放url的indexPath,而' assetURLs '或' sectionAssetURLs '不为空。

@param indexPath播放url的indexPath
@param assetURL播放器URL。
@param scrollToTop使用动画将当前单元格滚动到顶部。
 */
- (void)playTheIndexPath:(NSIndexPath *)indexPath assetURL:(NSURL *)assetURL scrollToTop:(BOOL)scrollToTop;

/**
播放url的indexPath,而' assetURLs '或' sectionAssetURLs '不为空。

@param indexPath播放url的indexPath
@param scrollToTop使用动画将当前单元格滚动到顶部。
@param completionHandler滚动完成回调。
 */
- (void)playTheIndexPath:(NSIndexPath *)indexPath scrollToTop:(BOOL)scrollToTop completionHandler:(void (^ __nullable)(void))completionHandler;

ZFPlayerMediaPlayback—播放器SDK遵守的协议

  • 枚举类型:
///  播放状态:未知、播放中、暂停、失败、停止
typedef NS_ENUM(NSUInteger, ZFPlayerPlaybackState) {
    ZFPlayerPlayStateUnknown = 0, 
    ZFPlayerPlayStatePlaying,
    ZFPlayerPlayStatePaused,
    ZFPlayerPlayStatePlayFailed,
    ZFPlayerPlayStatePlayStopped
};
///  加载状态:未知、就绪、可以播放、自动播放、播放暂停
typedef NS_OPTIONS(NSUInteger, ZFPlayerLoadState) {
    ZFPlayerLoadStateUnknown        = 0,
    ZFPlayerLoadStatePrepare        = 1 << 0,
    ZFPlayerLoadStatePlayable       = 1 << 1,
    ZFPlayerLoadStatePlaythroughOK  = 1 << 2, 
    ZFPlayerLoadStateStalled        = 1 << 3,
};
///  播放画面拉伸模式:无拉伸、等比例拉伸不裁剪、部分内容裁剪按比例填充、非等比例填满
typedef NS_ENUM(NSInteger, ZFPlayerScalingMode) {
     ZFPlayerScalingModeNone,         
     ZFPlayerScalingModeAspectFit,  
     ZFPlayerScalingModeAspectFill,     
     ZFPlayerScalingModeFill     
};
  • 协议属性:
///  播放器视图继承于ZFPlayerView,处理一些手势冲突
@property (nonatomic) ZFPlayerView *view;

///  0...1.0,播放器音量,不影响设备的音量大小
@property (nonatomic) float volume;

///  播放器是否静音,不影响设备静音
@property (nonatomic, getter=isMuted) BOOL muted;

///  0.5...2,播放速率,正常速率为 1
@property (nonatomic) float rate;

///  当前播放时间
@property (nonatomic, readonly) NSTimeInterval currentTime;

///  播放总时间
@property (nonatomic, readonly) NSTimeInterval totalTime;

///  缓冲时间
@property (nonatomic, readonly) NSTimeInterval bufferTime;

///  视频播放定位时间
@property (nonatomic) NSTimeInterval seekTime;

///  视频是否正在播放中
@property (nonatomic, readonly) BOOL isPlaying;

///  视频播放视图的填充模式,默认不做任何拉伸
@property (nonatomic) ZFPlayerScalingMode scalingMode;

///  检查视频播放是否准备就绪,返回YES,调用play方法直接播放视频;返回NO,调用play方法内部自动调用prepareToPlay方法进行视频播放准备工作
@property (nonatomic, readonly) BOOL isPreparedToPlay;

///  媒体播放资源URL
@property (nonatomic) NSURL *assetURL;

///  视频的尺寸
@property (nonatomic, readonly) CGSize presentationSize;

///  视频播放状态
@property (nonatomic, readonly) ZFPlayerPlaybackState playState;

///  视频的加载状态
@property (nonatomic, readonly) ZFPlayerLoadState loadState;

///------------------------------------
///如果没有指定controlView,可以调用以下块。
///如果你指定了controlView,下面的代码块不能在外部调用,只能用于“ZFPlayerController”调用。
///------------------------------------

///  准备播放
@property (nonatomic, copy, nullable) void(^playerPrepareToPlay)(id<ZFPlayerMediaPlayback> asset, NSURL *assetURL);

/// 开始播放了
@property (nonatomic, copy, nullable) void(^playerReadyToPlay)(id<ZFPlayerMediaPlayback> asset, NSURL *assetURL);

///  播放进度改变
@property (nonatomic, copy, nullable) void(^playerPlayTimeChanged)(id<ZFPlayerMediaPlayback> asset, NSTimeInterval currentTime, NSTimeInterval duration);

///  视频缓冲进度改变
@property (nonatomic, copy, nullable) void(^playerBufferTimeChanged)(id<ZFPlayerMediaPlayback> asset, NSTimeInterval bufferTime);

///  视频播放状态改变
@property (nonatomic, copy, nullable) void(^playerPlayStatChanged)(id<ZFPlayerMediaPlayback> asset, ZFPlayerPlaybackState playState);

///  视频加载状态改变
@property (nonatomic, copy, nullable) void(^playerLoadStatChanged)(id<ZFPlayerMediaPlayback> asset, ZFPlayerLoadState loadState);

///  视频播放已经结束
@property (nonatomic, copy, nullable) void(^playerDidToEnd)(id<ZFPlayerMediaPlayback> asset);

// 视频的尺寸改变了
@property (nonatomic, copy, nullable) void(^presentationSizeChanged)(id<ZFPlayerMediaPlayback> asset, CGSize size);

///------------------------------------
/// end
///------------------------------------

  • 协议方法:
///  视频播放准备,中断除non-mixible之外的任何音频会话
- (void)prepareToPlay;

///  重新进行视频播放准备
- (void)reloadPlayer;

///  视频播放
- (void)play;

///  视频暂停
- (void)pause;

///  视频重新播放
- (void)replay;

///  视频播放停止
- (void)stop;

///  视频播放当前时间的画面截图
- (UIImage *)thumbnailImageAtCurrentTime;

///  替换当前媒体资源地址
- (void)replaceCurrentAssetURL:(NSURL *)assetURL;

///  调节播放进度
- (void)seekToTime:(NSTimeInterval)time completionHandler:(void (^ __nullable)(BOOL finished))completionHandler;

ZFPlayerMediaControl—控制层遵守的协议

  • 视频状态相关
///  视频播放准备就绪
- (void)videoPlayer:(ZFPlayerController *)videoPlayer prepareToPlay:(NSURL *)assetURL;

///  视频播放状态改变
- (void)videoPlayer:(ZFPlayerController *)videoPlayer playStateChanged:(ZFPlayerPlaybackState)state;

///  视频加载状态改变
- (void)videoPlayer:(ZFPlayerController *)videoPlayer loadStateChanged:(ZFPlayerLoadState)state;
  • 播放进度
///  视频播放时间进度
- (void)videoPlayer:(ZFPlayerController *)videoPlayer
        currentTime:(NSTimeInterval)currentTime
          totalTime:(NSTimeInterval)totalTime;

///  视频缓冲进度
- (void)videoPlayer:(ZFPlayerController *)videoPlayer
         bufferTime:(NSTimeInterval)bufferTime;

///  视频定位播放时间
- (void)videoPlayer:(ZFPlayerController *)videoPlayer
       draggingTime:(NSTimeInterval)seekTime
          totalTime:(NSTimeInterval)totalTime;

///  视频播放结束
- (void)videoPlayerPlayEnd:(ZFPlayerController *)videoPlayer;

  • 锁屏
/// 设置播放器锁屏时的协议方法
- (void)lockedVideoPlayer:(ZFPlayerController *)videoPlayer lockedScreen:(BOOL)locked;

  • 屏幕旋转
///  播放器全屏模式即将改变
- (void)videoPlayer:(ZFPlayerController *)videoPlayer orientationWillChange:(ZFOrientationObserver *)observer;

///  播放器全屏模式已经改变
- (void)videoPlayer:(ZFPlayerController *)videoPlayer orientationDidChanged:(ZFOrientationObserver *)observer;

///  当前网络状态发生变化
- (void)videoPlayer:(ZFPlayerController *)videoPlayer reachabilityChanged:(ZFReachabilityStatus)status;

  • 手势方法
///  相关手势设置
- (BOOL)gestureTriggerCondition:(ZFPlayerGestureControl *)gestureControl
                    gestureType:(ZFPlayerGestureType)gestureType
              gestureRecognizer:(UIGestureRecognizer *)gestureRecognizer
                          touch:(UITouch *)touch;

///  单击
- (void)gestureSingleTapped:(ZFPlayerGestureControl *)gestureControl;

///  双击
- (void)gestureDoubleTapped:(ZFPlayerGestureControl *)gestureControl;

///  开始拖拽
- (void)gestureBeganPan:(ZFPlayerGestureControl *)gestureControl
           panDirection:(ZFPanDirection)direction
            panLocation:(ZFPanLocation)location;

///  拖拽中
- (void)gestureChangedPan:(ZFPlayerGestureControl *)gestureControl
             panDirection:(ZFPanDirection)direction
              panLocation:(ZFPanLocation)location
             withVelocity:(CGPoint)velocity;

///  拖拽结束
- (void)gestureEndedPan:(ZFPlayerGestureControl *)gestureControl
           panDirection:(ZFPanDirection)direction
            panLocation:(ZFPanLocation)location;

///  捏合手势变化
- (void)gesturePinched:(ZFPlayerGestureControl *)gestureControl
        scale:(float)scale;
        
  • scrollView上的播放器视图方法

/**
scrollView中的播放器视图将要出现的回调
 */
- (void)playerWillAppearInScrollView:(ZFPlayerController *)videoPlayer;

/**
scrollView中的播放器视图已经出现的回调
 */
- (void)playerDidAppearInScrollView:(ZFPlayerController *)videoPlayer;

/**
scrollView中的播放器视图即将消失的回调
 */
- (void)playerWillDisappearInScrollView:(ZFPlayerController *)videoPlayer;

/**
scrollView中的播放器视图已经消失的回调
 */
- (void)playerDidDisappearInScrollView:(ZFPlayerController *)videoPlayer;

/**
scrollView中的播放器视图正在显示的回调
 */
- (void)playerAppearingInScrollView:(ZFPlayerController *)videoPlayer playerApperaPercent:(CGFloat)playerApperaPercent;

/**
scrollView中的播放器视图正在消失的回调
 */
- (void)playerDisappearingInScrollView:(ZFPlayerController *)videoPlayer playerDisapperaPercent:(CGFloat)playerDisapperaPercent;

/**
小窗视图显示隐藏的回调
 */
- (void)videoPlayer:(ZFPlayerController *)videoPlayer floatViewShow:(BOOL)show;

代码传送门:https://github.com/renzifeng/ZFPlayer

Author

打赏作者

你的支持就是我的动力,请作者喝杯下午茶吧!


打赏作者

推荐阅读更多精彩内容