iOS 推流 SDK开发指南 - 微吼技术文档

1 概念说明
2 接入准备
3 工程配置
4 注册APP
5 设置第三方ID
6 LOG打印
7 获取roomID、access_token
8 代码对接
9 事件处理

1 概念说明

直播：直播的视频源是用户实时推送的。因此，用户停止推送后，播放端的画面也会随即停止，而且由于是实时直播，所以播放器在播直播的时候是没有进度条的。

推流：是指将音视频数据采集编码之后，推送到微吼云平台。微吼云 SDK 主要帮您解决在智能手机上的推流问题，它的接口非常简单易用。

2 接入准备

2.1 成为开发者

申请开通微吼云账号，提供用户资料，微吼服务人员在后台为用户开通平台账号，用户也可自行在官网进行账号注册，账号开通后，用户即可登录，成为一名开发者。

2.2 创建应用

登录微吼云平台后，控制台选择应用管理，进入应用管理页面点击创建应用，根据页面提示信息，完成应用创建。应用创建完成，您可以在控制台界面找到在应用管理界面您可以找到 AppID。

2.3 添加服务

应用创建完成后，默认开通直播服务，在直播服务下直播管理的【直播配置】页面查看AppID

2.4 SDK下载

SDK下载

3 工程配置

3.1 支持平台

SDK支持iOS 8.0以上系统

3.2 开发环境

Xcode 8或更高版本
OS X 10.10或更高版本

3.3 Xcode工程设置

下面通过一个简单的iOS Application工程，说明如和在Xcode工程中配置SDK。

3.3.1 拷贝SDK文件

在本例中，新建一个名字叫做VHSDKDemo的iOS工程，将下载下来的文件夹拷贝至工程目录。目录结构如下图所示：

3.3.2 添加库和Framework

libc++.tbd
libz2.1.0.tbd
libicucore.tbd
libz.tbd
libiconv.tbd
CoreTelephony.framework
MediaPlayer.framework
AVFoundation.framework
VideoToolbox.framework
AssetsLibrary.framework
OpenAL.framework
OpenGLES.framework
QuartzCore.framework
CoreMedia.framework
Security.framework

3.3.3 工程设置修改

AppDelegate.m 文件名修改为AppDelegate.mm
Build Setting 中 Enable Bitcode 设置为NO
设置Info.plist中 App Transport Security Settings -> Allow Arbitrary Loads 设置为 YES
设置Info.pplist中 Privacy - Camera Usage Description 是否允许使用相机
设置Info.pplist中 Privacy - Microphone Usage Description 是否允许使用麦克风

3.4 验证

下面在VHSDKDemo的代码中，调用SDK的接口，设置appID 获取SDK版本信息，以验证工程设置是否正确。

3.4.1 引用头文件

在AppDelegate.mm开头引用SDK的头文件：

#import "VHLiveBase.h"

3.4.2 添加调用代码

在application: didFinishLaunchingWithOptions:方法中添加代码：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [VHLiveBase registerApp:@"xxxxxxxxx"];//AppID：xxxxxxxxx
    [VHLiveBase setThirdPartyUserId:@"xxxxxxxx"];//第三方账号id：xxxxxxxx
    NSLog(@"SDK Version: %@",[VHLiveBase getSDKVersion]);
    return YES;
}

3.4.3 编译运行

如果前面各个步骤都操作正确的话，VHSDKDemo工程应该可以顺利编译通过。在Debug模式下运行APP，Xcode的Console窗格会打印出SDK的版本信息。

至此，工程配置完成。

4 注册APP

[VHLiveBase registerApp:@"xxxxxxxxx"];//AppID：xxxxxxxxx

5 设置第三方ID

[VHLiveBase setThirdPartyUserId:@"xxxxxxxx"];//第三方账号id：xxxxxxxx

6 LOG打印

在 VHLiveBase 中可以设置 log的级别，具体代码如下：

[VHLiveBase setLogLevel:VHLogLevelDebug];

7 获取roomID、access_token

获取roomID、access_token

8 代码对接

8.1 创建Publisher对象

先创建一个 Publisher 对象，我们后面主要用它来完成推流工作。

不过在创建 Publisher 对象之前，还需要您指定一个VHPublishConfig对象，该对象的用途是决定 Publisher 推流时各个环节的配置参数，比如推流用多大的分辨率、每秒钟要多少帧画面（FPS）等等。

VHPublishConfig 在configWithType之后便已经装配了一些我们反复调过的参数，如果您不需要自己定制这些配置，塞给Publisher对象就可以了。如果您有相关领域的经验基础，需要对这些默认配置进行调整，可以阅读进阶篇中的内容。

    // 创建 LivePushConfig 对象，该对象默认初始化为基础配置
    VHPublishConfig* config = [VHPublishConfig configWithType:VHPublishConfigTypeDefault];
    //在 config中您可以对推流的参数（如：前后置摄像头、分辨率、帧率，横竖屏推流等）做一些初始化操作，需要注意 config不能为nil
    _publisher = [[VHLivePublisher alloc] initWithConfig: config];

8.2 设置并启动预览画面、delegate

delegate 推流事件代理
startCapture 启动手机摄像头采集画面，并将画面渲染到屏幕上。

    _publisher.delegate            = self;
    _publisher.preView.frame = _perView.bounds;
    [self.perView insertSubview:_publisher.preView atIndex:0];
    //开始视频采集、并显示预览界面
    [_publisher startCapture];

8.3 开始推流

经过 step1 和 step2 的准备之后，用下面这段代码就可以启动推流了：

roomId 推流房间id 可以通过调用 api 创建
accessToken 可以通过调用 api 获得

    NSString* roomId = @"lss_xxxxxx";
    NSString* accessToken = @"xxxxxxxxxx";
    [_publisher startPublish:roomId accessToken:accessToken];

8.4 切换前置或后置摄像头

默认是使用后置摄像头（可以通过修改 VHPublishConfig 的配置项 captureDevicePosition 来修改这个默认值），调用一次switchCamera 切换一次，注意切换摄像头前必须保证 VHPublishConfig 和 VHLivePublisher 对象都已经初始化。

// 默认是前置摄像头，可以通过修改 LivePushConfig 的配置项 frontCamera 来修改这个默认值
[_publisher switchCamera:AVCaptureDevicePositionBack];//AVCaptureDevicePositionFront

8.5 打开或关闭闪光灯

只有后置摄像头才可以打开闪光灯，另外该接口需要在启动预览之后调用

// 默认是前置摄像头，可以通过修改 LivePushConfig 的配置项 frontCamera 来修改这个默认值
if(!frontCamera) {
    BOOL bEnable = YES;
    //bEnable为YES，打开闪光灯; bEnable为NO，关闭闪光灯
    BOOL result = [_publisher torchMode: bEnable];
    //result为YES，打开成功;result为NO，打开失败
}

8.6 手动对焦

对焦点 [x,y] 取值范围[0.0 - 1.0]

// 手动对焦 point 对焦点 [x,y] [0.0 - 1.0]
 - (BOOL)focusCameraAtAdjustedPoint:(CGPoint)point;

8.7 变焦

变焦取值范围[1.0 - xx] xx 是系统相机支持最大变焦值

//变焦
 - (BOOL)zoomCamera:(CGFloat)zoomSize;

8.8 APP 切入后台

常规模式下，App一旦切到后台，摄像头的采集能力就会被 iOS 暂时停止掉，这就意味着 SDK 不能再继续采集并编码出音视频数据。

a. 注册切入后台通知

//先注册后退消息通知
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleEnterBackground:) 
    name:UIApplicationDidEnterBackgroundNotification object:nil];

b. 切后台处理

//收到通知后，调用beginBackgroundTaskWithExpirationHandler
 - (void)handleEnterBackground:(NSNotification *)notification
{
    [[UIApplication sharedApplication] beginBackgroundTaskWithExpirationHandler:^{
    }];
    [_publisher pause];
}

c. 切前台处理

//切前台处理
 - (void)handleEnterForeground:(NSNotification *)notification
{
    [_publisher resume];
}

8.9 停止推流

结束推流很简单，不过要做好清理工作，因为用于推流的 VHLivePublisher是不能多实例并行运转的，所以清理工作不当会导致下次直播遭受不良的影响。

//停止推流
 - (void)stopRtmpPublish {
    [_publisher stopPublish];
    _publisher.delegate = nil;
}

8.10 停止采集

停止音视频采集，并关闭预览画面

[_publisher stopCapture];//停止采集

8.11 销毁publisher

销毁初始化数据，同步销毁，如果感觉销毁太慢，可以开线程去销毁

[_publisher destoryObject];

9 事件处理

推流状态监听

SDK 通过 VHLivePublisherDelegate 代理来监听推流相关的事件

事件ID	数值	含义说明
VHPublishStatusNone	0
VHPublishStatusPushConnectSucceed	1	直播连接成功
VHPublishStatusUploadSpeed	2	直播上传速率
VHPublishStatusUploadNetworkException	3	发起端网络环境差
VHPublishStatusUploadNetworkOK	4	发起端网络环境恢复正常

错误通知

错误类型	数值	含义说明
VHPublishErrorNone	0
VHPublishErrorPusherError	1	推流相关错误@{code："10001" ,content: "xxxxx"}
VHPublishErrorAuthError	2	验证等相关错误
VHPublishErrorParamError	3	参数相关错误
VHPublishErrorCaptureError	4	采集相关错误