功能使用

注册SDK

申请并配置License请参见License集成指南。

请在较早的位置（使用推流SDK前）调用注册License接口。

[AlivcLiveBase registerSDK];

• 通过AlivcLiveBase类，可以设置日志级别、设置本地日志路径、获取SDK版本等。

• 在AlivcLiveBase#setObserver接口的onLicenceCheck方法，异步判断Licence是否配置成功。

配置推流参数

在需要使用推流器的ViewController中引用头文件#import <AlivcLivePusher/AlivcLivePusher.h>。

基本推流配置对应参数都有默认值，建议采用默认值，即您可以进行简单初始化，不做配置。

AlivcLivePushConfig *config = [[AlivcLivePushConfig alloc] init];//初始化推流配置类，也可使用initWithResolution来初始化。
config.resolution = AlivcLivePushResolution540P;//默认为540P，最大支持720P
config.fps = AlivcLivePushFPS20; //建议用户使用20fps
config.enableAutoBitrate = true; // 打开码率控制，默认为true
config.videoEncodeGop = AlivcLivePushVideoEncodeGOP_2;//默认值为2，关键帧间隔越大，延时越高。建议设置为1-2。
config.connectRetryInterval = 2000; // 单位为毫秒，重连时长2s，重连间隔设置不小于1秒，建议使用默认值即可。
config.previewMirror = false; // 默认为false，正常情况下都选择false即可。
config.orientation = AlivcLivePushOrientationPortrait; // 默认为竖屏，可设置home键向左或向右横屏。

推流（摄像头推流）

1. 初始化。

   在配置好推流参数后，可以使用推流SDK的initWithConfig方法进行初始化。示例代码如下：

   self.livePusher = [[AlivcLivePusher alloc] initWithConfig:config];

   说明

   AlivcLivePusher目前不支持多实例，所以一个init必须对应有一个destroy。

2. 注册推流回调。

   推流回调分为三种：

   • Info：主要做提示和状态检测使用。

   • Error：错误回调。

   • Network：主要为网络相关。

   注册delegate可接收对应的回调。示例代码如下：

   [self.livePusher setInfoDelegate:self];
   [self.livePusher setErrorDelegate:self];
   [self.livePusher setNetworkDelegate:self];

3. 开始预览。

   livePusher对象初始化完成之后，可以进行开始预览操作。预览时需要传入摄像头预览的显示view（继承自UIView）。示例代码如下：

   [self.livePusher startPreview:self.view];

4. 开始推流。

   预览成功后才可以开始推流，因此需监听AlivcLivePusherInfoDelegate的onPreviewStarted回调，在回调里面添加如下代码。

   [self.livePusher startPushWithURL:@"推流测试地址(rtmp://......)"];

   说明

   • 推流地址支持RTMP和超低延时直播RTS（artc://）推流地址，地址获取可参见生成推流地址和播放地址。

   • 阿里云视频直播暂不支持同一时间向同一个推流URL进行多路推流（第二路推流会被拒绝）。

/*切换前后摄像头*/
[self.livePusher switchCamera];
/*开启/关闭闪光灯，在前置摄像头时开启闪关灯无效*/
[self.livePusher setFlash:false]; 
/*焦距调整，即可实现采集画面的缩放功能。传入参数为正数，则放大焦距，传入参数为负数则缩小焦距。*/
CGFloat max = [_livePusher getMaxZoom];
[self.livePusher setZoom:MIN(1.0, max)]; 
/*手动对焦。手动聚焦需要传入两个参数:1.point 对焦的点（需要对焦的点的坐标);2.autoFocus 是否需要自动对焦，该参数仅对调用接口的该次对焦操作生效。后续是否自动对 焦沿用上述自动聚焦接口设置值。*/
[self.livePusher focusCameraAtAdjustedPoint:CGPointMake(50, 50) autoFocus:true];
/*设置是否自动对焦*/
[self.livePusher setAutoFocus:false];
/*镜像设置。镜像相关接口有两个，PushMirror推流镜像和PreviewMirror预览镜像。PushMirror设置仅对播放画面生效，PreviewMirror仅对预览画面生效，两者互不影响。*/
[self.livePusher setPushMirror:false];
[self.livePusher setPreviewMirror:false];

/*用户可以设置pauseImage后调用pause接口，从摄像头推流切换成静态图片推流，音频推流继续。*/
[self.livePusher pause];
/*从静态图片推流切换成摄像头推流，音频推流继续。*/
[self.livePusher resume];
/*推流状态下可调用停止推流，完成后推流停止。*/
[self.livePusher stopPush];
/*在预览状态下才可以调用停止预览，正在推流状态下，调用停止预览无效。预览停止后，预览画面定格在最后一帧。*/
[self.livePusher stopPreview];
/*推流状态下或者接收到所有Error相关回调状态下可调用重新推流，且Error状态下只可以调用此接口(或者reconnectPushAsync重连)或者调用destory销毁推流。完成后重新开始推流，重启ALivcLivePusher内部的一切资源，包括预览、推流等等restart。*/
[self.livePusher restartPush];
/*推流状态下或者接收到AlivcLivePusherNetworkDelegate相关的Error回调状态下可调用此接口, 且Error状态下只可以调用此接口(或者restartPush重新推流)或者调用destory销毁推流。完成后推流重连，重新链接推流RTMP。*/
[self.livePusher reconnectPushAsync];
/*销毁推流后，推流停止，预览停止，预览画面移除。AlivcLivePusher相关的一切资源销毁。*/
[self.livePusher destory];
self.livePusher = nil;
/*获取推流状态。*/
AlivcLivePushStatus status = [self.livePusher getLiveStatus];

录屏推流（屏幕共享推流）

ReplayKit是iOS 9引入的支持屏幕录制功能。iOS 10在ReplayKit中新增了调用第三方App扩展来直播屏幕内容的功能。在iOS 10及以上系统中，使用推流SDK配合Extension录屏进程，可以实现录屏直播。

1. 创建App Group。

   需登录Apple Developer ，完成以下操作：

   1. 在Certificates, IDs & Profiles 页面中注册App Group，具体操作步骤可以参考注册App Group。

   2. 回到Identifier页面，选择App IDs，然后单击您的App ID（主App进程与Extension录屏进程的 App ID需要进行同样的配置）启用App Group功能。具体操作步骤可以参考启用App Group。

   3. 完成后重新下载对应的Provisioning Profile并配置到XCode中。

   操作正确完成后Extension录屏进程可以和主App进程之间进行进程通信。

   说明

   创建App Group完成后需保存App Group Identifier值，作为后续步骤的输入内容。

2. 创建Extension录屏进程。

   iOS推流SDK Demo中实现了支持录屏直播的App扩展AlivcLiveBroadcast和AlivcLiveBroadcastSetupUI。App中具体创建Extension录屏进程如下：

   1. 在现有工程选择New > Target…，选择Broadcast Upload Extension，如下图：

   2. 修改Product Name，勾选Include UI Extension，单击Finish创建直播扩展和直播UI，如下图：

   3. 配置直播扩展Info.plist，在新创建的Target中，Xcode会默认创建名为SampleHandler的头文件和源文件，如下图：

      将AlivcLibReplayKitExt.framework拖到工程中，使得Extension Target依赖它。替换SampleHandler.m中的代码成如下代码（需将代码中的KAPP Group替换成上文第一步骤创建的App Group Identifier）。示例代码如下：

      
      #import "SampleHandler.h"
      #import <AlivcLibReplayKitExt/AlivcLibReplayKitExt.h>
      
      @implementation SampleHandler
      
      - (void)broadcastStartedWithSetupInfo:(NSDictionary<NSString *,NSObject *>
      *)setupInfo {
      
       //User has requested to start the broadcast. Setup info from the UI extension can
      be supplied but optional.
       [[AlivcReplayKitExt sharedInstance] setAppGroup:kAPPGROUP];
      }
      
      - (void)processSampleBuffer:(CMSampleBufferRef)sampleBuffer withType:(RPSampleBufferType)sampleBufferType {
       if (sampleBufferType != RPSampleBufferTypeAudioMic) {
       //声音由主App进程采集发送
       [[AlivcReplayKitExt sharedInstance] sendSampleBuffer:sampleBuffer withType:sampleBufferType];
       }
      }
      
      - (void)broadcastFinished {
      
       [[AlivcReplayKitExt sharedInstance] finishBroadcast];
      }
      @end
      
                                          

   在您的工程中，完成创建Broadcast Upload Extension的Target，在该Extension Target中集成为录屏扩展模块定制的AlivcLibReplayKitExt.framework。

3. 在录屏推流主App进程中集成直播SDK。

   在录屏推流主App进程中创建AlivcLivePushConfig、AlivcLivePusher对象，设置外置推流ExternMainStream为True，AudioFromExternal为False（该配置表示音频仍通过SDK内部采集），调用StartScreenCapture开始接收Extension App屏幕数据，开始和结束推流。具体可参考以下操作步骤：

   1. 录屏推流主App进程中加入AlivcLivePusher.framework、AlivcLibRtmp.framework、RtsSDK.framework和AlivcLibReplayKitExt.framework的依赖。

   2. 初始化推流SDK，配置使用外部视频源。

      ExternMainStream设置为True，ExternVideoFormat设置为AlivcLivePushVideoFormatYUV420P，音频使用内部SDK采集AudioFromExternal设置为False，配置其他推流参数，请参见示例代码如下：

       self.pushConfig.externMainStream = true;
       self.pushConfig.externVideoFormat = AlivcLivePushVideoFormatYUV420P;
       self.pushConfig.audioSampleRate = 44100;
       self.pushConfig.audioChannel = 2;
       self.pushConfig.audioFromExternal = false;
       self.pushConfig.videoEncoderMode = AlivcLivePushVideoEncoderModeSoft;
       self.pushConfig.qualityMode = AlivcLivePushQualityModeCustom;
       self.pushConfig.targetVideoBitrate = 2500;
       self.pushConfig.minVideoBitrate = 2000;
       self.pushConfig.initialVideoBitrate = 2000;
       self.livePusher = [[AlivcLivePusher alloc] initWithConfig:self.pushConfig];
      
                                      

   3. 使用AlivcLivePusher来完成直播相关功能，调用如下函数：

      • 开始接收录屏数据。

        需将代码中的kAPPGroup替换成上文创建的App Group Identifier，示例代码如下：

        [self.livePusher startScreenCapture:kAPPGROUP];

      • 开始推流。

        示例代码如下：

        [self.livePusher startPushWithURL:self.pushUrl]

      • 结束推流。

        示例代码如下：

        [self.livePusher stopPush];
        [self.livePusher destory];
        self.livePusher = nil;

预览显示模式

推流SDK支持三种预览模式，预览显示模式不影响推流。

• ALIVC_LIVE_PUSHER_PREVIEW_SCALE_FILL ：预览显示时，铺满窗口。当视频比例和窗口比例不一致时，预览会有变形。

• ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FIT：预览显示时，保持视频比例。当视频比例与窗口比例不一致时，预览会有黑边。（默认）

• ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FILL：预览显示时，剪切视频以适配窗口比例。当视频比例和窗口比例不一致时，预览会裁剪视频。

示例代码如下：

mAlivcLivePushConfig.setPreviewDisplayMode(AlivcPreviewDisplayMode.ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FIT);

图片推流

为了更好的用户体验，SDK提供了后台图片推流和码率过低时进行图片推流的设置。当SDK退至后台时默认暂停推流视频，只推流音频，此时可以设置图片来进行图片推流。例如，在图片上提醒用户主播离开片刻，稍后回来。示例代码如下：

config.pauseImg = [UIImage imageNamed:@"图片.png"];//设置用户后台推流的图片

另外，当网络较差时您可以根据自己的需求设置推流一张静态图片。设置图片后，SDK检测到当前码率较低时，会推流此图片，避免视频流卡顿。示例代码如下：

config.networkPoorImg = [UIImage imageNamed:@"图片.png"];//设置网络较差时推流

推送外部音视频流

推流SDK支持将外部的音视频源输入进行推流，比如推送一个音视频文件。

1. 在推流配置里面进行外部音视频输入配置。

示例代码如下：

config.externMainStream = true;//开启允许外部流输入
config.externVideoFormat = AlivcLivePushVideoFormatYUVNV21;//设置视频数据颜色格式定义，这里设置为YUVNV21，可根据需求设置为其他格式。
config.externAudioFormat = AlivcLivePushAudioFormatS16;//设置音频数据位深度格式，这里设置为S16，可根据需求设置为其他格式

2. 插入外部视频数据。

示例代码如下：

/*只支持外部视频yuv和rbg格式的连续buffer数据，才可以通过sendVideoData接口，发送视频数据buffer、长度、宽高、时间戳、旋转角度*/
[self.livePusher sendVideoData:yuvData width:720 height:1280 size:dataSize pts:nowTime rotation:0];
/*如果外部视频数据是CMSampleBufferRef格式，可以使用sendVideoSampleBuffer接口*/
[self.livePusher sendVideoSampleBuffer:sampleBuffer]
/*也可以将 CMSampleBufferRef格式转化为连续buffer后再传递给sendVideoData接口， 以下为转换的参考代码*/
//获取samplebuffer长度
- (int) getVideoSampleBufferSize:(CMSampleBufferRef)sampleBuffer {
if(!sampleBuffer) {
 return 0;
}
int size = 0;
CVPixelBufferRef pixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer);
CVPixelBufferLockBaseAddress(pixelBuffer, 0);
if(CVPixelBufferIsPlanar(pixelBuffer)) {
 int count = (int)CVPixelBufferGetPlaneCount(pixelBuffer);
 for(int i=0; i<count; i++) {
 int height = (int)CVPixelBufferGetHeightOfPlane(pixelBuffer,i);
 int stride = (int)CVPixelBufferGetBytesPerRowOfPlane(pixelBuffer,i);
 size += stride*height;
 }
}else {
 int height = (int)CVPixelBufferGetHeight(pixelBuffer);
 int stride = (int)CVPixelBufferGetBytesPerRow(pixelBuffer);
 size += stride*height;
}
CVPixelBufferUnlockBaseAddress(pixelBuffer, 0);
return size;
}
//将samplebuffer转化为连续buffer
- (int) convertVideoSampleBuffer:(CMSampleBufferRef)sampleBuffer toNativeBuffer:(void*)nativeBuffer
{
if(!sampleBuffer || !nativeBuffer) {
 return -1;
}
CVPixelBufferRef pixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer);
CVPixelBufferLockBaseAddress(pixelBuffer, 0);
int size = 0;
if(CVPixelBufferIsPlanar(pixelBuffer)) {
 int count = (int)CVPixelBufferGetPlaneCount(pixelBuffer);
 for(int i=0; i<count; i++) {
 int height = (int)CVPixelBufferGetHeightOfPlane(pixelBuffer,i);
 int stride = (int)CVPixelBufferGetBytesPerRowOfPlane(pixelBuffer,i);
 void *buffer = CVPixelBufferGetBaseAddressOfPlane(pixelBuffer, i);
 int8_t *dstPos = (int8_t*)nativeBuffer + size;
 memcpy(dstPos, buffer, stride*height);
 size += stride*height;
 }
}else {
 int height = (int)CVPixelBufferGetHeight(pixelBuffer);
 int stride = (int)CVPixelBufferGetBytesPerRow(pixelBuffer);
 void *buffer = CVPixelBufferGetBaseAddress(pixelBuffer);
 size += stride*height;
 memcpy(nativeBuffer, buffer, size);
}
CVPixelBufferUnlockBaseAddress(pixelBuffer, 0);
return 0;
}

3. 插入音频数据。

示例代码如下：

/*只支持外部pcm格式的连续buffer数据，sendPCMData，发送音频数据buffer、长度、时间戳*/
[self.livePusher sendPCMData:pcmData size:size pts:nowTime];

配置水印

推流SDK提供了添加水印功能，并且最多支持添加多个水印，水印图片必须为PNG格式图片。示例代码如下：

NSString *watermarkBundlePath = [[NSBundle mainBundle] pathForResource:
[NSString stringWithFormat:@"watermark"] ofType:@"png"];//设置水印图片路径
[config addWatermarkWithPath: watermarkBundlePath
 watermarkCoordX:0.1
 watermarkCoordY:0.1
 watermarkWidth:0.3];//添加水印

设置视频质量

视频质量支持三种模式：清晰度优先模式，流畅度优先模式，自定义模式。

config.qualityMode = AlivcLivePushQualityModeResolutionFirst；//清晰度优先模式

config.qualityMode = AlivcLivePushQualityModeFluencyFirst；//流畅度优先模式

config.qualityMode = AlivcLivePushQualityModeCustom//设置为自定义模式
config.targetVideoBitrate = 1400; //目标码率1400kbps
config.minVideoBitrate = 600; //最小码率600kbps
config.initialVideoBitrate = 1000; //初始码率1000kbps

设置自定义码率时，请参考阿里云推荐设置配置对应码率。推荐设置请参考下表内容：

分辨率自适应

开启动态调整推流分辨率功能后，当网络较差时会自动降低分辨率以提高视频的流畅度和清晰度。示例代码如下：

config.enableAutoResolution = YES; // 打开分辨率自适应，默认为NO

背景音乐

推流SDK提供了背景音乐播放、混音、降噪、耳返、静音等功能，背景音乐相关接口在开始预览之后才可调用。示例代码如下：

/*开始播放背景音乐。*/
[self.livePusher startBGMWithMusicPathAsync:musicPath];
/*停止播放背景音乐。若当前正在播放BGM，并且需要切换歌曲，只需要调用开始播放背景音乐接口即可，无需停止当前正在播放的背景音乐。*/
[self.livePusher stopBGMAsync];
/*暂停播放背景音乐，背景音乐开始播放后才可调用此接口。*/
[self.livePusher pauseBGM];
/*恢复播放背景音乐，背景音乐暂停状态下才可调用此接口。*/
[self.livePusher resumeBGM];
/*开启循环播放音乐*/
[self.livePusher setBGMLoop:true];
/*设置降噪开关。打开降噪后，将对采集到的声音中非人声的部分进行过滤处理。可能存在对人声稍微抑制作用，建议让用户自由选择是否开启降噪功能，默认不使用*/
[self.livePusher setAudioDenoise:true];
/*设置耳返开关。耳返功能主要应用于KTV场景。打开耳返后，插入耳机将在耳机中听到主播说话声音。关闭后，插入耳机无法听到人声。未插入耳机的情况下，耳返不起作用。*/
[self.livePusher setBGMEarsBack:true];
/*混音设置，提供背景音乐和人声采集音量调整。*/
[self.livePusher setBGMVolume:50];//设置背景音乐音量
[self.livePusher setCaptureVolume:50];//设置人声采集音量
/*设置静音。静音后音乐声音和人声输入都会静音。要单独设置音乐或人声静音可以通过混音音量设置接口来调整。*/
[self.livePusher setMute:isMute?true:false];

推流截图

推流SDK提供了本地视频流截图功能，示例代码如下：

/*设置截图回调*/
[self.livePushersetSnapshotDelegate:self];
/*调用截图API*/
[self.livePushersnapshot:1interval:1];

配置直播答题功能

直播答题功能可以通过在直播流里面插入SEI信息，播放器解析SEI来实现。在推流SDK里面提供了插入SEI的接口，在推流状态下，才能调用此接口。示例代码如下：

/*
msg: 需要插入流的SEI消息体，建议是JSON格式。阿里云播放器SDK可收到此SEI消息，解析后做具体展示。
repeatCount：发送的帧数。为了保证SEI不被丢帧，需设置重复次数，如设置100，则在接下去的100帧均插入此SEI消息。播放器会对相同的SEI进行去重处理。
delayTime：延时多少毫秒发送。
KeyFrameOnly：是否只发关键帧。
*/
[self.livePusher sendMessage:@"题目信息" repeatCount:100 delayTime:0 KeyFrameOnly:false];

iPhoneX适配

一般场景下，预览view的frame设置为全屏可以正常预览，由于iPhoneX屏幕比例的特殊性，所以iPhoneX下预览view设置为全屏大小会有画面拉伸的现象。建议iPhoneX不要使用全屏大小的view来预览。

推流过程中改变view的大小

请遍历您在调用startPreview或者startPreviewAsync接口时赋值的UIView。更改预览view的所有subView的frame。例如：

[self.livePusher startPreviewAsync:self.previewView];
for (UIView *subView in [self.previewView subviews]) {
 // ...
}

播放外部音效

如果您需要在推流页播放音效音乐等，由于SDK暂时与AudioServicesPlaySystemSound有冲突，建议您使用AVAudioPlayer，并且在播放后需要更新设置AVAudioSession、AVAudioPlayer播放音效示例代码：

- (void)setupAudioPlayer {
 NSString *filePath = [[NSBundle
mainBundle] pathForResource:@"sound" ofType:@"wav"];
 NSURL *fileUrl = [NSURL URLWithString:filePath];
 self.player = [[AVAudioPlayer alloc] initWithContentsOfURL:fileUrl error:nil];
 self.player.volume = 1.0;
 [self.player prepareToPlay];
}
 - (void)playAudio {
 self.player.volume = 1.0;
 [self.player play];
 // 配置AVAudioSession
 AVAudioSession *session = [AVAudioSession sharedInstance];
 [session setMode:AVAudioSessionModeVideoChat error:nil];
 [session overrideOutputAudioPort:AVAudioSessionPortOverrideSpeaker error:nil];
 [session setCategory:AVAudioSessionCategoryPlayAndRecord withOptions:AVAudioSessionCategoryOptionDefaultToSpeaker|AVAudioSessionCategoryOptionAllowBluetooth
| AVAudioSessionCategoryOptionMixWithOthers error:nil];
 [session setActive:YES error:nil];
}

退后台和接听电话

SDK内部已经做好退后台相关处理，无需您做操作。退入后台SDK默认继续推流音频，视频保留在最后一帧。您需要在App的Capabilities中打开Background Mode选项，选中Audio，AirPlay and Picture in Picture。保证App退后台可以正常采集音频。如图：

如果退后台时不需要保持音频推流，即退入后台停止推流且返回前台继续推流，您可以在退后台时将推流引擎销毁，在前台后重新创建推流引擎继续推流。

回调监听

推流SDK主要包含以下回调：

常用方法和接口

/*在自定义模式下，用户可以实时调整最小码率和目标码率。*/
[self.livePusher setTargetVideoBitrate:800];
[self.livePusher setMinVideoBitrate:200]
/*获取是否正在推流的状态*/
BOOL isPushing = [self.livePusher isPushing]; 
/*获取推流地址*/
NSString *pushURLString = [self.livePusher getPushURL];
/*获取推流性能调试信息。推流性能参数具体参数和描述参考API文档或者接口注释。*/
AlivcLivePushStatsInfo *info = [self.livePusher getLivePushStatusInfo];
/*获取版本号。*/
NSString *sdkVersion = [self.livePusher getSDKVersion];
/*设置log级别，根据需求过滤想要的调试信息*/
[self.livePusher setLogLevel:(AlivcLivePushLogLevelDebug)];

调试工具

SDK提供UI调试工具DebugView。DebugView为可移动的全局悬浮窗，添加后始终悬浮在视图的最上层。内含推流日志查看、推流性能参数实时检测、推流主要性能折线图表等debug功能。

示例代码如下：

[AlivcLivePusher showDebugView];//打开调试工具

连麦互动（互动版）

直播推流SDK互动版V4.4.4及以上版本提供基于RTC的连麦互动能力，V4.4.5及以上版本提供基于RTC的连麦PK互动能力，用户可以使用推流SDK互动版本完成主播和连麦观众超低延时（300ms以内）互动，直播连麦相关的功能使用，请参见连麦互动开发指南和主播PK互动开发指南。