开发指南

1 开发准备

开始前请确保下述前提条件已准备就绪:

解压后 SDK 包的 libs 文件夹中,包含了播放器的 libNELivePlayer.a、libssl.a、libcrypto.a 等库文件和 include 头文件。

2 集成SDK

本文是根据网易云视频官网的播放器 Demo 来介绍 SDK 的集成,可在网易云视频官网下载最新的播放器 iOS Demo,来查看更多的实现细节。

2.1 创建播放器工程

(1) 创建ViewController,如下图所示: pic

(2) Subclass选择UIViewController,如下图所示: pic

2.2 导入库文件

(1) 集成添加播放器 SDK 到 App 工程,在 xcode 工程设置库文件和头文件的搜索路径,在TARGETS->Build Settings->Search Paths中设置,如下图所示。

pic

注意:图中红框内为网易云视频demo中的库文件和头文件的路径,用户需要根据自己工程中的实际位置来设置。

(2) 将 SDK 中的lib目录下 libNELivePlayer.a、libssl.a、libcrypto.a 等库文件添加到 App 工程,如下图所示。

pic

(3) 将 SDK 中的 include 目录下的头文件添加到使用 SDK 的地方。

#import <NELivePlayer/NELivePlayer.h>   
#import <NELivePlayer/NELivePlayerController.h>

注意:头文件存放的位置可以根据开发者的实际情况指定,以上是根据 demo 作为示例

2.3 添加依赖框架

播放器 iOS SDK 运行需要添加相关依赖框架,在TARGETS -> Build Phases-> Link Binary With Libraries 中添加相关依赖框架。

其中,各个依赖框架的含义如下所示:

框架 含义
SystemConfiguration.framwork 网络框架
CoreTelephony.framwork 网络框架
CFNetwork.framwork 网络框架
libz.tbd 压缩工具
libbz2.tbd 压缩工具
libstdc++.tbd C++标准库
libiconv.tbd 字符集转换
Foundation.framwork 基础框架
OpenGLES.framework 提供2D和3D绘图的API
QuartzCore.framework 视频图像处理框架
CoreAudio.framework 播放和录制音频框架
CoreVideo.framework 播放和录制视频框架
CoreGraphics.framework 处理2D图像渲染
CoreMedia.framework 提供操作媒体的底层接口
AVFoundation.framework 提供用于管理和播放视频的接口
VideoToolBox.framework 视频硬件编解码库
AudioToolBox.framework 音频控制框架
UIKit.framework 界面框架

2.4 设置目标架构

在 XCode 中用户根据需要支持的CPU类型来配置 target 架构。 在TARGETS -> Build Settings -> Architectures -> Valid Architectures,如下图所示。

pic

2.5 实现播放功能

iOS SDK 的 API 形式与 MediaPlayer 保持一致。方便开发者可以快速的接入,详细的流程可参见 demo 源代码:
(1) 导入头文件
在NELivePlayerViewController.h中添加头文件。

#import <NELivePlayer/NELivePlayer.h>
#import <NELivePlayer/NELivePlayerViewController.h>

(2) 添加声明播放器属性
在NELivePlayerViewController.h中添加声明播放器属性,完成后如下所示:

#import <UIKit/UIKit.h>
#import <NELivePlayer/NELivePlayer.h>
#import <NELivePlayer/NELivePlayerViewController.h>

@interface NELivePlayerViewController : UIViewController

@property(nonatomic, strong) id<NELivePlayer> liveplayer;

@end

(3) 创建 NELivePlayerController 实例,并进行相关初始化工作

self.liveplayer = [[NELivePlayerController alloc] 
                     initWithContentURL:self.url];

若播放器初始化返回为 nil,则说明初始化失败,需要重新初始化,如下判断:

if (self.liveplayer == nil) {  
    NSLog(@"failed to initialize!");  
}

若首次初始化失败,请检查输入的播放器url是否为空。地址为空会导致初始化失败;
若前一次播放退出后再次进入时初始化失败,请检查资源是否未释放完成。需要等待资源释放完成才能进行初始化

self.url 是待播放的网络视频流或本地文件的路径。

(4) 设置播放器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;

示例中设置的是屏幕的大小,用户可以根据自己的实际需求来进行设置view的位置和大小

(5) 将播放器界面添加到当前视图

[self.view addSubview:self.liveplayer.view];

(6) 注册相关 Notification 用于监听播放过程中的各种消息
相关 Notification 可参见 API 文档和 demo 工程源代码,示例如下:

// 播放器媒体流初始化完成后触发,收到该通知表示可以开始播放
[[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(NELivePlayerDidPreparedToPlay:)
                                                 name:NELivePlayerDidPreparedToPlayNotification
                                               object:_liveplayer];

// 播放器加载状态发生变化时触发,如开始缓冲,缓冲结束
[[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(NeLivePlayerloadStateChanged:)
                                                 name:NELivePlayerLoadStateChangedNotification
                                               object:_liveplayer];

// 正常播放结束或播放过程中发生错误导致播放结束时触发的通知    
[[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(NELivePlayerPlayBackFinished:)
                                                 name:NELivePlayerPlaybackFinishedNotification
                                               object:_liveplayer];

// 第一帧视频图像显示时触发的通知    
[[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(NELivePlayerFirstVideoDisplayed:)
                                                 name:NELivePlayerFirstVideoDisplayedNotification
                                               object:_liveplayer];

// 第一帧音频播放时触发的通知                                         
[[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(NELivePlayerFirstAudioDisplayed:)
                                                 name:NELivePlayerFirstAudioDisplayedNotification
                                               object:_liveplayer];


// 资源释放成功后触发的通知    
[[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(NELivePlayerReleaseSuccess:)
                                                 name:NELivePlayerReleaseSueecssNotification
                                               object:_liveplayer];

// 视频码流解析失败时触发的通知                                               
[[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(NELivePlayerVideoParseError:)
                                                 name:NELivePlayerVideoParseErrorNotification
                                               object:_liveplayer];

(5) 设置播放器相关属性
播放器实例初始化和设置播放url完成后,可以根据需求设置播放器相关属性。

//设置播放缓冲策略,直播采用低延时模式或流畅模式,点播采用抗抖动模式,具体可参见API文档
[self.liveplayer setBufferStrategy:NELPLowDelay];
//设置画面显示模式,默认按原始大小进行播放,具体可参见API文档
[self.liveplayer setScalingMode:NELPMovieScalingModeNone]; 
//设置视频文件初始化完成后是否自动播放,默认自动播放
[self.liveplayer setShouldAutoplay:YES]; 
//设置是否开启硬件解码,IOS 8.0以上支持硬件解码,默认为软件解码
[self.liveplayer setHardwareDecoder:isHardware];
//设置播放器切入后台后时暂停还是继续播放,默认暂停
[self.liveplayer setPauseInBackground:NO];

(6) flv点播加密视频的密钥获取和校验(直播流和非flv点播视频忽略该步骤)
对于flv点播的加密视频,需要密钥进行解密,然后再进行播放,用户需要调用该接口来获取密钥并验证密钥的正确性。

[self.liveplayer initDecryption:transferToken :accid :appKey :token :^(NELPKeyCheckResult ret) {
    NSLog(@"ret = %d", ret);
    switch (ret) {
        case NELP_NO_ENCRYPTION: //视频未加密
        case NELP_ENCRYPTION_CHECK_OK: //密钥获取并校验正确
            [self.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;
    }
}];

其中:
transferToken为获取密钥的令牌;
accid为视频云用户创建的其子用户id;
token为视频云用户子用户的token;
appKey为视频云用户子用户的token
ret为密钥校验结果的回调,校验正确才能继续prepareToPlay操作。

ret为密钥获取并校验后的结果,用户需要根据返回的结果做出相应的操作,对于未加密和密钥校验正确的flv加密视频,可以继续步骤7,否则需要退出并检查出错的原因,然后重复上述操作进行播放。

(7) 视频文件初始化
属性设置完成后,需调用 prepareToPlay() 接口对待播放的视频文件进行初始化,初始化完成后会发NELivePlayerDidPreparedToPlayNotification 通知,并将 isPrepareToPlay 设置为 YES, 如果 shouldAutoplay 已经设置成 YES,则会自动调用 play 进行播放, 如果 shouldAutoplay 设置成 NO,则需要用户调用 play() 进行播放。

[self.liveplayer prepareToPlay];

(8) 播放视频
如(6)所述,若 shouldAutoplay 设置成NO,则在调用 prepareToPlay() 接口后,需要调用 play() 进行播放。

[self.liveplayer play];

注意:在第一次调 play() 接口之前一定要调 prepareToPlay() 接口。

2.6 播放控制

(1) 暂停播放
在播放过程中需要暂停播放,可以调用 pause() 接口,调 play() 恢复播放。

[self.liveplayer pause];

注意:直播过程中不能暂停,暂停功能只适用于点播

(2) 拖动播放
在拖动进度条到某一时间点播放或者启动时从某一时间点播放可以调用 setCurrentPlaybackTime() 接口。 注意: 调用该接口一定要在收到 NELivePlayerDidPreparedToPlayNotification 通知后或者当 isPrepareToPlay 值为 YES 时才可以调用。

[self.liveplayer setCurrentPlaybackTime:currentPlayTime];

注意:该功能只适用于点播

(3) 退出播放
退出播放需要调用 shutdown() 接口,且需将创建的view remove掉,并将播放器置为空。

[self.liveplayer shutdown];
[self.liveplayer.view removeFromSuperview];
self.liveplayer = nil;

退出成功会收到 NELivePlayerReleaseSueecssNotification 通知。
要等待收到资源释放成功的消息通知后,才能将监听资源释放状态的监听器释放掉,否则资源释放成功的通知是无法接收到的

注意:若在播放过程中切换URL或者频繁进出,在后续进入的过程中,一定要等到资源释放成功的通知NELivePlayerReleaseSueecssNotification,否则进入的时候播放器会初始化失败。

2.7 后台播放

NELivePlayer SDK支持后台播放功能,可以与前台播放进行无缝切换。

[self.liveplayer setPauseInBackground:NO]; //NO为继续播放,YES为暂停

后台播放功能需要在xcode中配置background modes,如下图所示: pic

注意:对于直播,在后台不能处于暂停状态。若继续播放,则通过上述方法进行设置;若在后台不想继续播放,则需要在切入后台的过程中退出播放,释放相关资源,切回前台重新初始化播放。

2.8 切换播放地址功能

在播放过程中,用户可以直接调用 switchContentUrl()来切换播放地址。

url = [[NSURL alloc] initWithString:@"http://xxx.xxx.xxx.xxx/xxx.flv"];
[self.liveplayer switchContentUrl:url];

注意:该接口仅限于播放过程中切换播放地址或播放完成后播放下一个视频,第一次播放时不能调用该接口

2.9 截图功能

调用 getSnapshot() 接口来实现截图功能

UIImage *snapImage = [self.liveplayer getSnapshot];

截图结果以 UIImage 格式返回,开发者可根据自己的需求保存成 jpg 格式或 png 格式,并保存到指定位置,demo 默认以 jpg 格式保存在相册中。

通过以上操作,最终的播放效果下图所示:

pic

3 API说明

有关 API 的详细说明,请打开下面的在线文档。

网易云视频播放器NELivePlayer iOS SDK API详细文档