ApsaraVideo Live：功能使用

註冊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://）推流地址，地址擷取可參見產生推流地址和播流地址。

   • 阿里雲ApsaraVideo for Live暫不支援同一時間向同一個推流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];//開啟調試工具