閱讀700 返回首頁    go 魔獸

iOS播放器SDK說明__SDK文檔及下載_API及SDK_視頻直播-阿裏雲

概述

AlivcMediaPlayer是一款基於IOS平台的多媒體視頻播放SDK。它為IOS的開發者提供了簡單易用的接口，幫助開發者方便快捷、低門檻的實現多媒體播放功能的開發。它支持HLS、RTMP、HTTP FLV、MP4等多種流媒體播放格式，視頻支持h264格式、音頻支持AAC格式。另外，針對直播用戶的需求，還增加了首幀秒開的功能；同時為了減少直播的延遲，增加了弱網條件下播放的跳幀功能。

版本和新增功能

功能 版本
支持HLS、RTMP、HTTP FLV、mp4等流格式

支持h264+aac

 v1.0
支持armv7、arm64 v2.0
支持直播首幀秒開

支持弱網條件下的丟幀策略

 v2.1
支持多實例、支持模擬器調試，支持https

支持帶切邊的視頻渲染模式

 v2.2
支持蘋果2017年1月1號後強製使用HTTPS的要求 v2.2.1

閱讀對象

本文檔麵向所有使用該SDK的開發人員、測試人員以及對此感興趣的用戶，要求開發者對播放器的基本功能有一定的了解。

開發準備

設備和係統版本

ios8.0及以上

iphone5及以上

安裝包下載及說明

安裝包下載

播放器SDK的完整下載包中包含demo、doc、lib等：

  1. demo：主要存放了調用SDK的示例工程，可以幫助用戶了解如何使用該SDK。
  2. lib：播放器SDK開發包，包含播放器framework文件，需要在您的工程中進行引用。其中，arm目錄下麵的framework僅支持armv7和arm64平台，arm&simulator目錄下麵的framework除了armv7、arm64外，還支持x86、x86_64，可以用作模擬器調試。

快速開發

開發環境配置

  1. 需要準備iOS的運行環境（XCode6.0以上版本，iOS SDK8.0以上版本），以及硬件CPU支持ARMv7、ARMv7s或ARM64的iOS設備。
  2. 在阿裏雲官網上注冊雲帳號，並開通視頻點播或視頻直播服務。方法如下：

視頻點播服務開通

視頻直播服務開通

3 . 通過訪問控製服務創建播放器專用子帳號及其AccessKey：

  • b. 在用戶管理中新建用戶：

新建用戶

注意勾選為該用戶自動生成AccessKey 選項：

新建用戶

創建子帳號成功，注意保存好該帳號的AccessKey：

新建用戶

  • c. 為子帳號分配調用播放器權限：

點擊授權鏈接：

授權

在可選授權策略名稱中搜索mts，將AliyunMTSPlayerAuth授予此子帳號：

授權

用戶權限驗證

用戶需要用申請得到的AccessKeyID和AccessKeySecret進行權限驗證，才能夠使用播放器。權限驗證需要通過實現AliVcAccessKeyProtocol協議來完成。

  1. [AliVcMediaPlayer setAccessKeyDelegate:self];

權限驗證可以在播放器創建之前進行，且播放多個視頻隻需要驗證一次即可。通過協議的getAccessKeyIDSecret接口，sdk可以獲取用戶的AccessKeyID和AccessKeySecret來完成驗證。

  1. NSString* accessKeyID = @"QxJIheGFRL926hFX";
  2. NSString* accessKeySecret = @"hipHJKpt0TdznQG2J4D0EVSavRH7mR";
  3. -(AliVcAccesskey*)getAccessKeyIDSecret
  4. {
  5.     AliVcAccesskey* accessKey = [[AliVcAccesskey alloc] init];
  6.     accessKey.accessKeyId = accessKeyID;
  7.     accessKey.accessKeySecret = accessKeySecret;
  8.     return accessKey;
  9. }

sdk包添加

使用xcode創建工程的方法如下：

  1. XCode創建一個iOS應用工程。

  2. 將SDK中的framework添加到工程中，如圖：

    xcode創建工程

    點擊“+”號後出現：

xcode創建工程

點擊“Add Other…”，選中framework.

xcode創建工程

點擊“Open”.

xcode創建工程

點擊“Finish”

xcode創建工程

完成framework的添加

  1. 將SDK中的頭文件AliyunPlayerSDK.h包含到工程中。

demo示例

在SDK中提供了Demo，此Demo是用播放器SDK開發了一個完整的視頻播放器，用戶可以參考Demo進行播放器的開發。

首先，我們來看一下組成播放器的基本模塊以及播放器的工作流程，見下圖：

demo示例

使用SDK開發播放器時，基本的開發步驟為：

  1. alloc播放器後，調用create創建播放器，並傳入view顯示窗口
  2. 注冊通知響應函數。
  3. 調用prepareToPlay準備開始播放，傳入要播放的視頻地址。
  4. 調用play接口進行播放。

下麵以demo為例來詳細說明上麵的這些步驟。

  1.     //將需要播放的視頻添加到視頻列表中
  2.     //如果需要播放本地視頻，則將本地視頻拷貝到應用程序的Document目錄下即可
  3.     -(void) addVideoToList
  4.     { 
  5.         //按照如下格式進行添加，videoName是在列表中顯示的名字
  6.         [videolists setObject:@"https://yourVideoAddress.m3u8" forKey:@"videoName"];
  7.     }
  2.     -(void) playVideo
  3.     { 
  4.         //新建播放器
  5.         player = [[AliVcMediaPlayer alloc] init];
  6.         //創建播放器，傳入顯示窗口
  7.         [player create:mShowView];
  8.         //注冊準備完成通知
  9.         [[NSNotificationCenter defaultCenter] addObserver:self
  10.            selector:@selector(OnVideoPrepared:) name:AliVcMediaPlayerLoadDidPreparedNotification object:player];
  11.         //注冊錯誤通知
  12.         [[NSNotificationCenter defaultCenter] addObserver:self
  13.            selector:@selector(OnVideoError:) name:AliVcMediaPlayerPlaybackErrorNotification object:player];
  14.         //傳入播放地址，初始化視頻，準備播放
  15.         [player prepareToPlay:mUrl];
  16.         //開始播放
  17.         [player play]; 
  18.     }

播放器可配置參數與可選功能

配置參數 用途描述
timeout 設置網絡超時斷開鏈接的時間
dropBufferDuration 設置直播過程中緩衝區視頻丟幀的起始時間，若緩衝區中視頻幀的時長超過這個值，則開始丟幀操作。設置這個參數可以控製直播延時的長度，參數值越小則直播的延遲越小。

seek功能

接口名稱 用途描述
seekTo seek到指定位置之前的最近的一個關鍵幀
seekToAccurate 精準跳轉到指定位置

除了上述可配置的功能和參數，AlivcMediaPlayer還定義了播放器的事件狀態通知和錯誤代碼，以方便開發者掌握播放器的運行狀態。

  1. -(void) OnVideoPrepared:(NSNotification *)notification 
  2. {
  3.     //收到完成通知後，獲取視頻的相關信息，更新界麵相關信息 
  4.     [self.playSlider setMinimumValue:0];
  5.     [self.playSlider setMaximumValue:player.duration];
  6. }
  8. -(void)OnVideoError:(NSNotification *)notification 
  9. {
  10.     AliVcMovieErrorCode error_code = player.errorcode;   
  11. }

若需要了解上述功能和接口的詳細用法，請參照下節的接口說明。

接口說明

SDK中提供了類AliVcMediaPlayer來實現播放器各種功能接口，同時，我們還提供了播放器的各種狀態通知，以及播放器的各種錯誤代碼。

接口名稱 功能描述
create 創建播放器
prepareToPlay 初始化視頻，準備播放
play 開始播放視頻
pause 暫停視頻播放
stop 停止視頻播放
reset 重置播放器
destroy 銷毀播放器
seekTo 跳轉到指定位置
seekToAccurate 精準跳轉到指定位置
view 設置播放顯示窗口
videoHeight 獲取視頻高度
videoWidth 獲取視頻寬度
livePlayer 設置播放器的直播點播模式
timeout 設置網絡超時時間
dropBufferDuration 緩衝區丟幀的起始長度
duration 獲取視頻長度
currentPosition 獲取當前視頻播放位置
bufferingPosition 獲取當前視頻緩衝位置
muteMode 播放器靜音模式
scalingMode 播放器渲染時的縮放模式
errorCode 播放器錯誤代碼
getSDKVersion 獲取播放器版本號
setUserID 設置用戶ID
setBussinessID 設置業務ID
getPropertyDouble 獲取double型性能參數
getPropertyLong 獲取Long型性能參數
getPropertyString 獲取String型性能參數
狀態事件通知名稱 通知內容
AliVcMediaPlayerLoadDidPreparedNotification 播放準備完成通知
AliVcMediaPlayerPlaybackDidFinishNotification 播放結束通知
AliVcMediaPlayerStartCachingNotification 開始緩衝通知
AliVcMediaPlayerEndCachingNotification 結束緩衝通知
AliVcMediaPlayerPlaybackErrorNotification 播放錯誤通知
AliVcMediaPlayerSeekingDidFinishNotification 跳轉結束通知
AliVcMediaPlayerFirstFrameNotification 首幀顯示通知
錯誤代碼AliVcMovieErrorCode 錯誤說明
ALIVC_SUCCESS 無錯誤
ALIVC_ ERR_ILLEGALSTATUS 非法的播放流程
ALIVC_ ERR_ NO_NETWORK 無網絡下播放網絡視頻
ALIVC_ ERR_ FUNCTION_DENIED 權限驗證失敗
ALIVC_ ERR_UNKOWN 未知錯誤
ALIVC_ ERR_ NO_INPUTFILE 無輸入文件
ALIVC_ ERR_ NO_VIEW 沒有設置顯示窗口
ALIVC_ ERR_ INVALID_INPUTFILE 無效的輸入文件
ALIVC_ ERR_ NO_ SUPPORT_CODEC 視頻壓縮格式不支持
ALIVC_ ERR_ NO_MEMORY 內存不足

下麵詳細介紹一下各個成員函數的具體使用：

create

- (AliVcMovieErrorCode) create: (UIView*)view

功能：創建播放器，並設置播放器顯示窗口。播放器內部會新建各個播放器變量並初始化，並啟動播放器內部流水線線程等。

參數：UIView* view，播放器顯示窗口

備注：如果創建播放器的時候view沒有，則可以傳遞nil，可以在後續需要設置view。

prepareToPlay

- (AliVcMovieErrorCode) prepareToPlay: (NSURL*)dataSource

功能：根據視頻文件內容初始化播放器實例，包括讀取視頻頭，解析視頻和音頻信息，並根據視頻和音頻信息初始化解碼器，創建下載（或讀取本地文件）、解碼、渲染線程等。

參數：(NSURL*)dataSource，當前播放視頻的文件名或URL

返回值：若播放器初始化成功，返回ALIVC_SUCCESS；否則返回失敗。

prepareToPlay的具體過程為：

  1. 驗證用戶是否有權限調用該函數。
  2. 驗證參數dataSource是否為空。
  3. 如果播放器是正在播放或者正在暫停狀態，則不能夠進行prepare，此時返回非法的播放流程錯誤ALIVC_ ERR_ ILLEGALSTATUS，如果播放器狀態是已經是準備完成狀態，則返回ALIVC_SUCCESS。
  4. 對視頻進行初始化，如果成功，則會發送LoadDidPreparedNotification通知，表示視頻初始化完成。如果失敗則會發送PlaybackErrorNotification通知，在錯誤通知中可以獲取到錯誤代碼。

備注：該函數是異步函數，需要等待播放準備完成通知AliVcMediaPlayerLoadDidPreparedNotification，收到該通知後代表視頻初始化完成，同事還可以獲取到視頻的相關信息如：duration、videoWidth、videoHeight。

play

- (AliVcMovieErrorCode) play

功能：播放當前視頻

返回值：當播放視頻成功，返回ALIVC_SUCCESS，否則返回失敗。

play的具體過程為：

  1. 驗證是否有權限調用該函數
  2. 如果播放器是停止的狀態，則直接返回ALIVC_ ERR_ ILLEGALSTATUS錯誤；如果此時播放器為播放的狀態，直接返回ALIVC_SUCCESS。
  3. 如果播放器在暫停或者準備完成的狀態，則直接啟動視頻播放。

備注：播放器調用play進行播放，必須在播放器狀態為準備完成的狀態或者暫停的狀態才能進行播放，其他情況都不能夠將視頻播放起來。

pause

- (AliVcMovieErrorCode) pause

功能：暫停當前視頻播放

返回值：暫停視頻播放成功ALIVC_SUCCESS。否則返回失敗。

pause的具體過程為：

  1. 驗證是否有權限調用該函數。
  2. 如果此時播放器為暫停狀態，直接返回ALIVC_SUCCESS。
  3. 如果播放器狀態為停止或者準備完成狀態則返回錯誤的播放器狀態ALIVC_ ERR_ ILLEGALSTATUS。
  4. 其他情況則暫停視頻播放，並將播放器狀態設置為暫停狀態。

備注：調用pause函數將暫停視頻播放。一般在視頻正在播放的情況下調用此函數。

stop

- (AliVcMovieErrorCode) stop

功能：停止當前視頻播放，調用此函數則是結束視頻播放，視頻顯示為黑屏，並回到視頻播放起始點。

返回值：停止視頻播放成功ALIVC_SUCCESS。否則返回失敗。

stop的具體過程為：

  1. 驗證是否有權限調用該函數。
  2. 如果此時播放器的狀態為停止狀態，直接返回ALIVC_SUCCESS。
  3. 其他情況則停止視頻播放，並將播放器狀態設置為停止狀態，視頻停止後會發送視頻結束通知。

備注：調用該函數會釋放音視頻解碼、渲染線程。如果需要重新進行播放，則需要再調用prepareToPlay重新對視頻進行初始化。

seekTo

(AliVcMovieErrorCode) seekTo: (NSTimeInterval) newPos

功能：跳轉指定的播放位置附近

參數：newPos，單位為毫秒

返回值：跳轉成功ALIVC_SUCCESS。否則返回失敗。

seekTo的具體過程為：

  1. 驗證是否有權限調用該函數。
  2. 如果此時播放器的狀態為停止或準備完成狀態，返回錯誤的播放器狀態ALIVC_ ERR_ ILLEGALSTATUS。
  3. 其他情況則進行視頻跳轉，跳轉完成後會發送視頻跳轉結束通知AliVcMediaPlayerSeekingDidFinishNotification。

備注：該函數僅允許在點播或播放本地視頻過程中調用（直播禁用）。調用後視頻會跳轉到指定位置前最近的一個關鍵幀。參數的範圍為[0,duration]（duration為視頻的時長）。如果傳入的參數小於0，則播放器會自動將該參數修正到0；如果傳入參數大於duration，則修正到duration。

seekToAccurate

- (AliVcMovieErrorCode) seekToAccurate: (NSTimeInterval) newPos

功能：視頻跳轉到指定的播放位置。此函數能夠精確的跳轉到指定的位置，而seekTo隻能跳轉到附近的關鍵幀。

參數：newPos，單位為毫秒

備注：相比於seekTo函數，該函數跳轉的位置更精準，但是函數執行的時間也更長。

destroy

(AliVcMovieErrorCode) destroy

功能：銷毀播放器，該函數用來釋放播放器的所有資源。

備注：在退出播放器的時候必須調用該函數，用來進行內存釋放，否則會存在內存泄露。

reset

(AliVcMovieErrorCode) reset

功能：重置播放器。當播放的過程中調用該函數，會先停止當前的播放行為，銷毀當前的播放器，然後創建一個新的播放器。

返回值：如果權限驗證通過，則會返回ALIVC_SUCCESS。

view

UIView *view

功能：設置包含視頻內容的view。

備注：需要在調用prepareToPlay之前設置view，當前view隻有視頻幀圖像，沒有相關控製組件，相當於iOS係統播放器MPMoviePlayerController的控製方式controlStyle為MPMovieControlStyleNone的效果。

currentPosition

NSTimeInterval currentPosition

功能：獲取當前視頻播放位置，隻讀屬性，獲取單位為毫秒。

備注：當播放器狀態為正在播放或暫停的狀態，能夠獲取到有效值，否則獲取值為無效的0。

videoWidth

int videoWidth

功能：獲取視頻寬度，隻讀屬性。

備注：當調用了prepareToPlay後，並不能立即獲得videoWidth的值，隻有當播放器發送了prepared通知後，videoWidth的值才有效，否則為默認值0。

videoHieght

int videoHeight

功能：獲取視頻高度，隻讀屬性。

備注：當調用了prepareToPlay後，並不能立即獲得videoHeight的值，隻有當播放器發送了prepared通知後，videoHeight的值才有效，否則為默認值0。

livePlayer

int livePlayer

功能：設置播放器是直播還是點播模式，設置為1為直播，設置為0為點播.默認值為-1不進行設置，由播放器自動判決。

備注：播放器自動判決會根據是否存在視頻長度來判定是直播還是點播，此時會存在一定的偏差。如果用戶知道自己的應用場景，應該設置此值使得播放器行為表現更加精確。

timeout

int timeout

功能：設置播放器網絡超時時間，默認為15000毫秒。

備注：當播放網絡視頻時候，如果網絡較差或者無網絡的情況下，播放器此時會等待timeout的時間才會拋出網絡異常的通知，用戶收到此通知後進行處理，否則會一直等待。

dropBufferDuration

int dropBufferDuration

功能：當播放器處理直播模式時，設置緩衝區開始丟幀的起始長度，默認為8000毫秒。

備注：當緩衝區的長度大於dropBufferDuration時候，播放器開始啟動丟幀策略，此時必須要保證緩衝區至少有一個I幀，否則會引起花屏，所以此值必須大於一個GOP的長度。

duration

NSTimeInterval duration

功能：獲取視頻時長，隻讀屬性，單位為毫秒。

備注：當調用了prepareToPlay後，並不能立即獲得duration的值，隻有當播放器發送了prepared通知後，duration的值才有效，否則為默認值0。

bufferingPosition

NSTimeInterval bufferingPostion

功能：獲取當前播放器已經緩衝好的位置。

備注：開始播放後，可以獲取此值，用來獲取已經下載好的位置。

muteMode

BOOL muteMode

功能：設置播放器是否靜音，YES位靜音。

備注：靜音指播放器的靜音，並不會影響係統音量。

scalingMode

ScalingMode scalingMode

功能：設置播放器渲染時的縮放模式，目前有兩種模式，scalingModeAspectFit：等比例縮放顯示，如果視頻長寬比和屏幕長寬比不一致時，會存在黑邊；scalingModeAspectFitWithCropping：帶裁邊的等比例縮放，如果視頻長寬比和屏幕長寬比不一致時，會進行裁邊處理以保持全屏顯示。

備注：默認為scalingModeAspectFitWithCropping模式，可以動態改變。

errorCode

AliVcMovieErrorCode errorCode

功能：播放器錯誤代碼，隻讀屬性。

備注：當播放器出現錯誤時，可以通過獲取這個屬性來獲取到錯誤的代碼，通過錯誤代碼可以了解到具體的錯誤原因。

getSDKVersion

- (NSString *) getSDKVersion

功能：獲取SDK版本號。

返回值：返回NSString類型的版本號。

備注：當開發者反饋問題時，請使用該方法獲得SDK版本號並隨同問題一起反饋。

getPropertyDouble

-(double) getPropertyDouble:(int)property defaultValue:(double)defaultValue

功能：獲取一些性能參數。

返回值：返回double型的參數。

備注：同類型的函數還有getPropertyLong，getPropertyString等。這些鍵值如下：

標識符 數值
FFP_ PROP_ DOUBLE_ OPEN_ FORMAT_TIME 18001
FFP_ PROP_ DOUBLE_ FIND_ STREAM_TIME 18002
FFP_ PROP_ DOUBLE_ OPEN_ STREAM_TIME 18003
FFP_ PROP_ DOUBLE_ 1st_ VFRAME_ SHOW_TIME 18004
FFP_ PROP_ DOUBLE_ 1st_ AFRAME_ SHOW_TIME 18005
FFP_ PROP_ DOUBLE_ 1st_ VPKT_ GET_TIME 18006
FFP_ PROP_ DOUBLE_ 1st_ APKT_ GET_TIME 18007
FFP_ PROP_ DOUBLE_ 1st_ VDECODE_TIME 18008
FFP_ PROP_ DOUBLE_ 1st_ ADECODE_TIME 18009
FFP_ PROP_ DOUBLE_ DECODE_TYPE 18010
FFP_ PROP_ DOUBLE_ LIVE_ DISCARD_DURATION 18011
FFP_ PROP_ DOUBLE_ LIVE_ DISCARD_CNT 18012
FFP_ PROP_ DOUBLE_ DISCARD_ VFRAME_CNT 18013
FFP_ PROP_ DOUBLE_ RTMP_ OPEN_DURATION 18040
FFP_ PROP_ DOUBLE_ RTMP_ OPEN_RTYCNT 18041
FFP_ PROP_ DOUBLE_ RTMP_ NEGOTIATION_DURATION 18042
FFP_ PROP_ DOUBLE_ HTTP_ OPEN_DURATION 18060
FFP_ PROP_ DOUBLE_ HTTP_ OPEN_RTYCNT 18061
FFP_ PROP_ DOUBLE_ HTTP_ REDIRECT_CNT 18062
FFP_ PROP_ DOUBLE_ TCP_ CONNECT_TIME 18080
FFP_ PROP_ DOUBLE_ TCP_ DNS_TIME 18081
FFP_ PROP_ INT64_ VIDEO_ CACHED_DURATION 20005
FFP_ PROP_ INT64_ AUDIO_ CACHED_DURATION 20006
FFP_ PROP_ INT64_ VIDEO_ CACHED_BYTES 20007
FFP_ PROP_ INT64_ AUDIO_ CACHED_BYTES 20008
FFP_ PROP_ INT64_ VIDEO_ CACHED_PACKETS 20009
FFP_ PROP_ INT64_ AUDIO_ CACHED_PACKETS 20010
FFP_ PROP_ INT64_ SELECTED_ VIDEO_STREAM 20001
FFP_ PROP_ INT64_ SELECTED_ AUDIO_STREAM 20002

版本更新說明

1.0 原始版本，調用硬件的mediaPlayer接口實現

2.0 改用硬件的mediaCodec接口實現

2.1 增加直播秒開功能、緩衝區丟幀策略等。

2.2 支持模擬器、支持多實例、支持https、增加靜音功能、添加視頻渲染時的縮放模式

2.2.1 支持蘋果2017年1月1號後強製使用HTTPS的要求

最後更新：2016-12-06 17:59:56

  上一篇：go Android播放器SDK說明__SDK文檔及下載_API及SDK_視頻直播-阿裏雲
  下一篇：go 直播API概述__直播API_API及SDK_視頻直播-阿裏雲