# 播放器 iOS SDK

# 简介

iOS SDK 支持播放视频、音频、Word/PDF文档、静态PPT、动态PPT 5种类型的资源播放。其中，视频中支持倍速播放、切换清晰度，水印、指纹等基本视频播放功能。其他资源功能，参考ESCloudPlayerView.h。

# 开发环境

支持iOS 9.0以上版本。
XCode 10以上版本。
依赖库：AVFoundation,Foundation,WebKit, CoreMedia, UIKit, AVKit。

# 快速集成

通过 CocoaPods (opens new window) 安装集成。

# 接入准备

请将下面代码加入到您的 Podfile 中：

pod 'ESCloudPlayerSDK'

在项目根目录下执行下列任意命令，集成最新的 SDK：

$ pod update

或者

$ pod install --repo-update

# 使用播放器

/// 初始化
_mediaPlayerView = [[ESCloudPlayerView alloc]initWithFrame:self.bounds];
_mediaPlayerView.delegate = self;
[self.view addSubview:_mediaPlayerView];

///加载资源
[_mediaPlayerView loadResourceWithToken:self.token resNo:self.resNo specifyStartPos:30 completionHandler:^(NSDictionary *_Nullable resource, NSError *_Nullable error) {

}];

ESCloudPlayerView对象建议通过约束布局，可参考Demo (opens new window)。

# 播放器

ESCloudPlayerView是UIView子类，是媒体资源显示层。

# 字段

以下ESCloudPlayerView 对象的字段适用资源类型有所限制，具体请参考字段描述。

# token

类型：NSString
属性：只读
描述：用于初始化播放器，调用loadResourceWithToken: resNo: specifyStartPos: completionHandler:传入。
用法：

[_mediaPlayerView loadResourceWithToken:self.token resNo:self.resNo specifyStartPos:30 completionHandler:^(NSDictionary *_Nullable resource, NSError *_Nullable error) {

}];

# resNo

类型：NSString
属性：只读
描述：用于初始化播放器，调用loadResourceWithToken: resNo: specifyStartPos: completionHandler:传入。
用法：

[_mediaPlayerView loadResourceWithToken:self.token resNo:self.resNo specifyStartPos:30 completionHandler:^(NSDictionary *_Nullable resource, NSError *_Nullable error) {

}];

# playMetas

类型：NSDictionary
属性：只读
描述：播放器元数据，初始化完成后会自动附值。

# mediType

类型：ESCloudPlayerResourceType
属性：只读
描述：初始化完成后会自动附值。
可用值：参考ESCloudPlayerView.h文件。

# delegate

类型：id<ESCloudPlayerProtocol>
属性：可读可写
描述：用于播放器事件回调，具体回调方法参考ESCloudPlayerProtocol。

# videoPreviewView

类型：UIView
属性：只读
描述：显示视频音频资源内容的View。

# definitionList

类型：NSArray<NSDictionary *>
属性：只读
描述：清晰度数组，只用于视频资源 。

key	value	描述
name	超清、高清、标清
level	shd、hd、sd
bandwidth		视频宽度

# resourceDeallocExeBlock

类型：block
描述：播放器手动stop、销毁回调，开发者可用于释放资源。

# initDefinition

类型：枚举ESCloudPlayerVideoDefinition
描述：初始化视频播放清晰度，如果没有，则取definitionList数组中的第一个。

# videoPlayerContoller

类型：id<QPVideoContollerProtocol>
属性：只读
描述：只用于视频、音频播放器控制播放，具体控制事件参考QPVideoContollerProtocol。

# pptPlayerContoller

类型：id<QPPPTContollerProtocol>
属性：只读
描述：只用于ppt控制播放，具体控制事件参考QPPPTContollerProtocol。

# docPlayerContoller

类型：id<QPDocumentContollerProtocol>
属性：只读
描述：只用于文档事件控制，具体控制事件参考QPDocumentContollerProtocol。

# 方法

# `- loadResourceWithToken: resNo: specifyStartPos: completionHandler:`

描述：加载媒体资源，需要经过JWT (opens new window)加密的token (opens new window), 以及资源id。
参数：token：令牌， resNo：资源号码， specifyStartPos：指定开始位置（单位：秒/页）。
用法：

[_mediaPlayerView loadResourceWithToken:@"token" resNo:@"resNo" specifyStartPos:30 completionHandler:^(NSDictionary *_Nullable playMetas, NSError *_Nullable error) {
    // 初始化结束
}];

playMetas 数据格式参考ESCloudPlayerView.playMetas

# `- destory`

描述：用于资源释放，会停止和移除现在正在播放和显示的内容。并无法重新开始。
用法：

[_mediaPlayerView destory];

# 接口协议

# `ESVideoContollerProtocol`视频、音频控制协议

只用于视频、音频播放控制，ESCloudPlayerView内部实现，无需开发者实现。

# 字段

默认字段如下所示：

# canPlay

类型：BOOL
属性：只读
描述：判断视频、音频是否可以播放。

# canToggle

类型：BOOL
属性：只读
描述：判断是否可以音视频切换。

# isPlaying

类型：BOOL
属性：只读
描述：判断视频、音频是否正在播放。

# isPreview

类型：BOOL
属性：只读
描述：判断视频、音频资源是否为试看。

# currentDuration

类型：NSTimeInterval
属性：只读
描述：当前播放时间点。

# duration

类型：NSTimeInterval
属性：只读
描述：播放时间总长度。

# playableDuration

类型：NSTimeInterval
属性：只读
描述：当前可播放(已缓冲)时间长度。

# 方法

# `- seekToTime: completionHandler:`

描述：跳转播放。
参数：要跳转的时间点，单位秒 。
用法：

[_mediaPlayerView.videoPlayerContoller seekToTime:20.0f completionHandler:^(BOOL finished) {
        
}];

# `- switchDefinition:`

描述：选择清晰度，若清晰度不存在则无法切换，音频资源不支持清晰度切换。
参数：ESCloudPlayerVideoDefinition
用法：

[_mediaPlayerView.videoPlayerContoller switchDefinition:ESCloudPlayerVideoDefinitionSHD];

# `- setRate:`

描述：倍数播放，默认1.0倍速播放，当rate=0时，暂停播放。
参数：类型float 。
用法：

[_mediaPlayerView.videoPlayerContoller setRate:1.5];

# `- toggleWithSpecifyStartPos: completionHandler:`

描述：音视频切换，若不可切换，则调用无效
参数：specifyStartPos ：指定开始位置（单位：秒/页）， completionHandler：切换回调。
用法：

    [self.mediaPlayerView.videoPlayerContoller toggleWithSpecifyStartPos:20 completionHandler:^(NSDictionary *_Nullable resource, NSError *_Nullable error) {
    }];

playMetas 数据格式参考ESCloudPlayerView.playMetas

# `- play`

描述：开始（继续）播放。
用法：

[_mediaPlayerView.videoPlayerContoller play];

# `- pause`

描述：暂停播放。
用法：

[_mediaPlayerView.videoPlayerContoller pause];

# `- stop`

描述：停止播放，停止后，不可以重新开始。
用法：

[_mediaPlayerView.videoPlayerContoller stop];

# `- showFingerprint: fadeTime:`

描述：视频指纹，默认未添加视频指纹，间隔是10s~20s随机，只支持视频资源。
参数：fpText：指纹显示文字，fTime：每次显示的时间。
用法：

[_mediaPlayerView.videoPlayerContoller showFingerprint:@"水印文字" fadeTime：10.0s];

# `- showWatermarkWithImageURL: position：`

描述：添加视频水印，默认位置左下角ESCloudPlayerWatermarkPositionBottomLeft，只支持视频资源。
参数：imageURL：水印图片URL 。
用法：

[_mediaPlayerView.videoPlayerContoller showWatermarkWithImageURL:URL];

# `ESPPTPlayerContoller`静态PPT资源控制协议

# 字段

# pageCount

类型：NSInteger
属性：只读
描述：ppt总页数。

# 方法

# `- nextPage`

描述：下一页。
用法：

[_mediaPlayerView.pptPlayerContoller nextPage];

# `- previousPage`

描述：上一页。
用法：

[_mediaPlayerView.pptPlayerContoller previousPage];

# `- scrollToPageAtIndex：`

描述：滚动到设定页数。
用法：

[_mediaPlayerView.pptPlayerContoller scrollToPageAtIndex:3];

# `ESDocumentContollerProtocol`文档（pdf、word、动态ppt）资源控制协议

# 字段

# pageCount

类型：NSInteger
属性：只读
描述：文档总页数。

# 方法

# `- nextPage`

描述：下一页。
用法：

[_mediaPlayerView.docPlayerContoller nextPage];

# `- previousPage`

描述：上一页。
用法：

[_mediaPlayerView.docPlayerContoller previousPage];

# `- scrollToPageAtIndex：`

描述：滚动到设定页数。
用法：

[_mediaPlayerView.docPlayerContoller scrollToPageAtIndex:3];

# 事件协议

ESCloudPlayerProtocol协议用于播放器事件回调，实现该协议的类，可以作为ESCloudPlayerView对象的事件代理。

# 资源加载完成，准备播放回调

/// 视频
- (void)mediaPlayerVideoOnPrepared:(NSArray<NSDictionary *> *)definitions;//清晰度
///音频
- (void)mediaPlayerAudioOnPrepared;
///文档
- (void)mediaPlayer:(ESCloudPlayerView *)playerView documentOnPrepared:(NSDictionary *)data;

描述：definitions为视频资源可用清晰度数组。
用法：

- (void)mediaPlayerVideoOnPrepared:(NSArray<NSDictionary *> *)definitions{
/// 保存视频清晰度操作
}

definitions 数据结构参考 ESCloudPlayerView.definitionList

# 资源播放过程中错误回调

- (void)mediaPlayer:(ESCloudPlayerView *)playerView onFail:(nonnull NSError *)error;

描述：用于播放视频、音频，以及加载文档时发生错误回调。
用法：

- (void)mediaPlayer:(ESCloudPlayerView *)playerView onFail:(nonnull NSError *)error{
/// 错误处理
}

# 视频、音频缓冲回调

/// 视频 音频开始缓冲
- (void)mediaPlayerStartBuffer:(ESCloudPlayerView *)playerView;

/// 视频 音频结束缓冲
- (void)mediaPlayerStopBuffer:(ESCloudPlayerView *)playerView error:(NSError * _Nullable)error;

描述： 视频音频开始缓冲，结束缓冲回调。
用法：

- (void)mediaPlayerStartBuffer:(ESCloudPlayerView *)playerView {
    MBProgressHUD *hud = [MBProgressHUD HUDForView:self.view];
    if (!hud) {
        [MBProgressHUD showHUDAddedTo:self.view animated:YES];
    }
}

- (void)mediaPlayerStopBuffer:(ESCloudPlayerView *)playerView error:(NSError * _Nullable)error{
    [MBProgressHUD hideHUDForView:self.view animated:YES];
}

# 视频、音频播放控制回调。

/// 暂停
- (void)mediaPlayerOnPause:(ESMediaPlayerView *)playerView ;
/// 开始（继续）播放
- (void)mediaPlayerOnResume:(ESMediaPlayerView *)playerView ;
/// 播放结束
- (void)mediaPlayerOnStop:(ESMediaPlayerView *)playerView ;

描述： 只用于视频、音频的暂停、开始（继续）、结束播放回调。
用法：

- (void)mediaPlayerOnPause:(ESCloudPlayerView *)playerView{
   ///更改UI播放状态
}
- (void)mediaPlayerOnResume:(ESCloudPlayerView *)playerView{
   ///更改UI播放状态
}

- (void)mediaPlayerOnStop:(ESCloudPlayerView *)playerView{
   ///更改UI播放状态
}

# 视频清晰度切换回调。

- (void)mediaPlayer:(ESCloudPlayerView *)playerView switchDefinitionStatusDidChange:(ESCloudSwitchDefinitionStatus)status;

描述：视频清晰度切换状态回调，ESCloudSwitchDefinitionStatus参考ESCloudPlayerView.h。
用法：

- (void)mediaPlayer:(ESCloudPlayerView *)playerView switchDefinitionStatusDidChange:(ESCloudSwitchDefinitionStatus)status{
    
}

# 视频、音频播放时间回调

///总时间
- (void)mediaPlayer:(ESCloudPlayerView *)playerView durationDidChange:(NSTimeInterval)duration;
/// 可播放（已缓存）时间
- (void)mediaPlayer:(ESCloudPlayerView *)playerView playableDurationDidChange:(NSTimeInterval)duration;
/// 当前已经播放时间
- (void)mediaPlayer:(ESCloudPlayerView *)playerView currentTimeDidChange:(NSTimeInterval)duration;

描述： 只用于视频、音频资源播放总时间、可播放（已缓存）时间、已经播放时间改变回调。
用法：

- (void)mediaPlayer:(ESCloudPlayerView *)playerView durationDidChange:(NSTimeInterval)duration {
///设置UI播放总时间
}

- (void)mediaPlayer:(ESCloudPlayerView *)playerView playableDurationDidChange:(NSTimeInterval)duration {
///设置UI播放可播放时间
}

- (void)mediaPlayer:(ESCloudPlayerView *)playerView currentTimeDidChange:(NSTimeInterval)duration {
///设置UI播放进度
}

# 静态PPT 滚动回调

- (void)mediaPlayer:(ESCloudPlayerView *)playerView pptScrollPageAtIndex:(NSInteger)index;

描述： PPT 发生滚动时回调。

# PPT 点击回调

- (void)mediaPlayer:(ESCloudPlayerView *)playerView pptTapPageAtIndex:(NSInteger)index;

描述： PPT 点击当前页回调。

# Document 浏览到最后一页回调

- (void)mediaPlayerDocumentOnEnd:(ESCloudPlayerView *)playerView;

# Document 当前页改变时回调

- (void)mediaPlayer:(ESCloudPlayerView *)playerView documentPagechanged:(NSInteger)index;

描述： index 当前页数。

# DEMO

# 视频控制层

视频控制层可根据需求自己定制，Demo中视频控制层包括了以下功能：

清晰度选择。
倍数播放选择。
开始（继续）播放。
暂停播放。
全屏旋转。
播放进度显示。

其他功能，参考Demo (opens new window)

← 播放器 Android SDK 播放器小程序SDK →

# 播放器 iOS SDK

# 简介

# 开发环境

# 快速集成

# 接入准备

# 使用播放器

# 播放器

# 字段

# token

# resNo

# playMetas

# mediType

# delegate

# videoPreviewView

# definitionList

# resourceDeallocExeBlock

# initDefinition

# videoPlayerContoller

# pptPlayerContoller

# docPlayerContoller

# 方法

# - loadResourceWithToken: resNo: specifyStartPos: completionHandler:

# - destory

# 接口协议

# ESVideoContollerProtocol视频、音频控制协议

# 字段

# canPlay

# canToggle

# isPlaying

# isPreview

# currentDuration

# duration

# playableDuration

# 方法

# - seekToTime: completionHandler:

# - switchDefinition:

# - setRate:

# - toggleWithSpecifyStartPos: completionHandler:

# - play

# - pause

# - stop

# - showFingerprint: fadeTime:

# - showWatermarkWithImageURL: position：

# ESPPTPlayerContoller静态PPT资源控制协议

# 字段

# pageCount

# 方法

# - nextPage

# - previousPage

# - scrollToPageAtIndex：

# ESDocumentContollerProtocol文档（pdf、word、动态ppt）资源控制协议

# 字段

# pageCount

# 方法

# - nextPage

# - previousPage

# - scrollToPageAtIndex：

# 事件协议

# 资源加载完成，准备播放回调

# 资源播放过程中错误回调

# 视频、音频缓冲回调

# 视频、音频播放控制回调。

# 视频清晰度切换回调。

# 视频、音频播放时间回调

# 静态PPT 滚动回调

# PPT 点击回调

# Document 浏览到最后一页回调

# Document 当前页改变时回调

# DEMO

# 视频控制层

# `- loadResourceWithToken: resNo: specifyStartPos: completionHandler:`

# `- destory`

# `ESVideoContollerProtocol`视频、音频控制协议

# `- seekToTime: completionHandler:`

# `- switchDefinition:`

# `- setRate:`

# `- toggleWithSpecifyStartPos: completionHandler:`

# `- play`

# `- pause`

# `- stop`

# `- showFingerprint: fadeTime:`

# `- showWatermarkWithImageURL: position：`

# `ESPPTPlayerContoller`静态PPT资源控制协议

# `- nextPage`

# `- previousPage`

# `- scrollToPageAtIndex：`

# `ESDocumentContollerProtocol`文档（pdf、word、动态ppt）资源控制协议

# `- nextPage`

# `- previousPage`

# `- scrollToPageAtIndex：`