Web播放器SDK介面說明 - Apsara Video SDK

本文對阿里雲Web播放器SDK的屬性、方法和事件進行了說明，並提供了播放器介面的範例程式碼。

屬性

名稱	類型	說明
id	String	播放器外層容器的dom元素ID。
source	String	使用URL播放方式時，通過source屬性來指定視頻播放地址URL。說明 URL播放方式的播放優先順序最高，高於VID+PlayAuth、STS等其他播放方式，即使用VID+PlayAuth、STS等其他播放方式時，不能指定source屬性，若指定了source屬性，播放器將優先選擇source中的地址播放。建議僅設定一種播放方式。 URL播放方式支援多清晰度設定，通過source屬性來指定多路清晰度流的地址，更多資訊，請參見多清晰度播放。樣本如下： `source:’{“HD”:”address1”,”SD”:”address2”}’`
vid	String	媒體轉碼服務的媒體ID。
playauth	String	播放憑證，擷取播放憑證請參見擷取音視頻播放憑證。
height	String	播放器高度，取值： 100% 100px 說明 Chrome瀏覽器下Flash播放器分別不能小於397x297px。
width	String	播放器寬度，取值： 100% 100px 說明 Chrome瀏覽器下Flash播放器分別不能小於397x297px。
videoWidth	String	視頻寬度，僅H5模式支援。更多資訊，請參見設定顯示模式。
videoHeight	String	視頻高度，僅H5模式支援。更多資訊，請參見設定顯示模式。
preload	Boolean	播放器自動載入，目前僅H5模式可用。
cover	String	播放器預設封面圖片，請填寫正確的圖片URL地址。需要autoplay值為false時，才生效。Flash播放器封面也需要開啟允許跨域訪問。
isLive	Boolean	播放內容是否為直播，直播時會禁止使用者拖動進度條。預設值為false，播放直播流時需要設定為true。
autoplay	Boolean	播放器是否自動播放，在移動端autoplay屬性會失效。說明 Safari11不支援自動播放，如果需要，可通過按右鍵瀏覽器地址欄，選擇此網站的設定 > 允許全部自動播放來設定。
rePlay	Boolean	播放器自動迴圈播放。
useH5Prism	Boolean	指定使用H5播放器。
useFlashPrism	Boolean	指定使用Flash播放器。
playsinline	Boolean	H5是否內建播放，有的Android瀏覽器不起作用。
skinRes	Url	皮膚圖片，不建議隨意修改該欄位，如要修改，更多資訊，請參見設定播放器皮膚。
skinLayout	Array \| Boolean	功能組件布局配置，不傳該欄位使用預設布局。取值：false隱藏所有功能組件。更多資訊，請參見配置skinLayout屬性。
controlBarVisibility	String	控制台的實現，預設值為：hover。取值： click：點擊播放器地區。 hover：移動到播放器地區。 always：控制台一直顯示。 never：隱藏整個控制台。
showBarTime	String	控制欄自動隱藏時間，單位毫秒。
extraInfo	String	JSON串，用於定製性的介面參數，目前僅Flash支援，取值： fullTitle：測試頁面，全屏時顯示視頻標題。 m3u8BufferLength：播放HLS檔案時載入緩衝，ts檔案長度，單位為秒。
enableSystemMenu	Boolean	是否允許系統右鍵菜單顯示，預設為false。
format	String	指定播放地址格式，只有使用vid的播放方式時支援可選值，取值： mp4 hls或m3u8 flv mp3 預設為空白，僅H5支援。
mediaType	String	指定返迴音頻還是視頻，只有使用vid的播放方式時支援，預設值為video。取值： video：視頻。 audio：針對只包含音訊視頻格式，比如音訊MP4。僅H5支援。
qualitySort	String	指定排序方式，只有使用Vid + PlayAuth播放方式時支援。取值： desc：表示按倒序排序（即：從大到小排序）。 asc：示按正序排序（即：從小到大排序）。預設值：asc，僅H5支援。
definition	String	顯示視頻清晰度，多個使用半形逗號（,）分隔，比如：‘FD,LD’，此值是vid對應流清晰度的一個子集，僅H5模式支援。取值： FD（流暢） LD（標清） SD（高清） HD（超清） OD（原畫） 2K（2K） 4K（4K）
defaultDefinition	String	預設視頻清晰度，此值是vid對應流的一個清晰度，僅H5模式支援。取值： FD（流暢） LD（標清） SD（高清） HD（超清） OD（原畫） 2K（2K） 4K（4K）
autoPlayDelay	Number	延遲播放時間，單位：秒。更多資訊，請參見配置延遲播放。
autoPlayDelayDisplayText	String	延遲播放提示文本，更多資訊，請參見配置延遲播放。
language	String	國際化，預設為zh-cn。如果未設定，則採用瀏覽器語言。取值： zh-cn：中文。 en-us：英文。
languageTexts	JSON	自訂國際化文本JSON結構，key的值需要和language屬性值對應起來。樣本：{jp:{Play:”Play”}}自訂值請參見JSON結構。
snapshot	Boolean	是否啟用Flash截圖功能。取值： true：啟用。 false：禁用。（預設值）
snapshotWatermark	Object	H5設定截圖浮水印。
useHlsPluginForSafari	Boolean	Safari瀏覽器是否啟用HLS外掛程式播放，Safari 11除外。取值： true：啟用。 false：禁用。（預設值）
enableStashBufferForFlv	Boolean	H5播放FLV時，設定是否啟用播放緩衝，只在直播下起作用。取值： true：啟用。（預設值） false：禁用。
stashInitialSizeForFlv	Number	H5播放FLV時，初始緩衝大小，只在直播下起作用。預設32KB。當設定的值較小時，會提升起播速度，但是值太小時，可能會導致播放一小段之後卡頓。
loadDataTimeout	Number	緩衝多長時間後，提示使用者切換低清晰度，單位：秒。預設20秒。
waitingTimeout	Number	最大緩衝逾時時間，超過這個時間會有錯誤提示，單位：秒。預設60秒。
diagnosisButtonVisible	Boolean	是否顯示檢測按鈕，取值： true：顯示按鈕。 false：不顯示按鈕。預設值為true。
disableSeek	Boolean	禁用進度條的Seek，取值： true：禁用。 false：不禁用。預設值為false。說明僅Flash支援。
encryptType	Number	設定是否播放阿里雲視頻加密（私人加密）視頻，預設值為0，取值： 0：播放不加密視頻。 1：播放私人加密視頻。說明私人加密採用VID+playauth的方式進行播放。 Web端標準加密使用URL方式播放，請參見如何播放加密視頻。
progressMarkers	Array	進度條打點內容數組，更多資訊，請參見進度條標記。
vodRetry	Number	點播失敗重試次數，預設3次。
liveRetry	Number	直播播放失敗重試次數，預設5次。
hlsFrameChasing	Boolean	HLS直播模式下，是否開啟追幀。取值： true：開啟追幀。 false：不開啟追幀。（預設值）
chasingFirstParagraph	Number	第一段追幀，單位：秒。預設20秒。
chasingSecondParagraph	Number	第二段追幀，單位：秒。預設40秒。
chasingFirstSpeed	Number	第一段追幀的倍速，預設1.1倍速。
chasingSecondSpeed	Number	第二段追幀的倍速，預設1.2倍速。
flvFrameChasing	Boolean	FLV直播模式下，是否開啟追幀，取值： true：開啟追幀。 false：不開啟追幀。預設值為false。
keyShortCuts	Boolean	是否啟用快速鍵，取值： true：開啟快速鍵。 false：不開啟快速鍵。預設值為false。說明方向鍵（左右鍵）控制快進和快退，方向鍵（上下鍵）控制音量的增減，空格鍵暫停和播放。
keyFastForwardStep	Number	快進快退的時間長度，單位：秒。預設10秒。
rtsFallbackSource	String	RTS的降級地址（如HLS地址或FLV地址）。在使用超低延時直播RTS地址播放的情境下，當瀏覽器不相容RTS或RTS拉流失敗時，會自動降級到該地址播放。
rtsLoadDataTimeout	Number	配置RTS拉取不到資料的逾時時間（逾時會重試），單位：毫秒。預設為3000毫秒。
traceId	String	traceId為您自有的使用者唯一識別碼，將traceId傳入公用埋點，便於跟蹤上報日誌。正常情況下，Web播放器SDK已預設開啟日誌上報，傳遞traceId，可便於您標識使用者身份；如果不傳遞，Web播放器SDK會預設產生一個uuid（播放器SDK產生的唯一識別碼）並儲存在瀏覽器緩衝中。說明 Web播放器SDK 2.10.0及以上版本支援。
textTracks	Array	設定WebVTT外掛字幕，樣本如下： `textTracks:[{kind:'subtitles',label:'英文（美國）',src:'字幕地址',srclang:'en-US'}],` 欄位解釋如下： kind：vtt類型，取值包括subtitles和captions。 label：用於顯示的字幕名稱。 srclang：字幕語言。 src：字幕地址，請允許跨域訪問。說明 Web播放器SDK 2.12.0及以上版本支援。 WebVTT外掛字幕暫不支援以下瀏覽器： IE 安卓QQ瀏覽器、OPPO/一加的系統瀏覽器其他劫持video標籤的瀏覽器

方法

方法需要在ready事件發生之後或建立播放器ready回調裡，H5模式下可以在建立播放器建構函式的回呼函數裡調用。樣本如下：

H5播放器

//H5 播放器
 var player = new Aliplayer({},function(player) {
    player.play();
 });

Flash播放器

//Flash 播放器
 player.on('ready',function(e) {
    player.play();
 });

名稱	參數	說明
play	無	播放視頻。
pause	無	暫停視頻。
replay	無	重播視頻。
seek	time	跳轉到某個已載入的時刻進行播放，時間單位：秒。
getCurrentTime	無	擷取當前的播放時刻，返回的時間單位：秒。
getDuration	無	擷取視頻總時間長度，返回的單位為秒，這個需要在視頻載入完成以後才可以擷取到，可以在play事件後擷取。
getVolume	無	擷取當前的音量，傳回值為0~1的實數。iOS和部分Android會失效。
setVolume	無	設定音量，vol為0~1的實數，iOS和部分Android會失效。
loadByUrl	url，time	直接播放視頻url，time為可選值（單位：秒）。目前只支援同種格式（MP4、FLV、HLS）之間切換。暫不支援直播RTMP流切換。
replayByVidAndPlayAuth	vid：視頻ID，playauth：播放憑證	目前只支援H5播放器。暫不支援不同格式視頻間的之間切換。暫不支援直播RTMP流切換。可用於點播DRM流的切換，用法：`player.replayByVidAndPlayAuth(vid,playauth)`。
replayByVidAndAuthInfo	僅MPS使用者時使用參數順序為：vid、accId、accSecret、stsToken、authInfo、domainRegion	目前只支援H5播放器。暫不支援不同格式視頻間的之間切換。暫不支援直播rtmp流切換。
setPlayerSize	w，h	設定播放器大小，取值： 400px 60% Chrome瀏覽器下Flash播放器分別不能小於397x297px。
setSpeed	speed	手動設定播放的倍速，支援0.5~2倍速播放，倍速播放僅H5模式支援。移動端可能會失效，比如Android微信。倍速播放UI預設是開啟的。說明關掉倍速的方法：目前無法單獨關閉或者自訂倍速，只能整體關掉設定。通過hack方式關掉倍速是通過樣式覆蓋來實現的： `.prism-setting-speed { display: none !important; }`
setSanpshotProperties	width：寬度，height：高度，rate：截圖品質	設定截圖參數。
fullscreenService.requestFullScreen	無	播放器全屏，僅H5支援。
fullscreenService.cancelFullScreen	無	播放器退出全屏，iOS調用無效，僅H5支援。
fullscreenService.getIsFullScreen	無	擷取播放器全屏狀態，僅H5支援。
getStatus	無	擷取播放器狀態，取值： init：初始化。 ready：準備。 loading：載入中。 play：播放。 pause：暫停。 playing：現正播放。 waiting：等待緩衝。 error：錯誤。 ended：結束。
setRotate	rotate：旋轉角度	參數為旋轉角度，正數為正時針旋轉，負數為逆時針旋轉。樣本：setRotate(90)。更多資訊，請參見設定顯示模式。
getRotate	無	擷取旋轉角度。更多資訊，請參見設定顯示模式。
setImage	image：鏡像類型	設定鏡像，取值： horizon：水平。 vertical：垂直。樣本：setImage(‘horizon’)。更多資訊，請參見設定顯示模式。
dispose	無	播放器銷毀。
setCover	cover：封面地址	設定封面。
setProgressMarkers	markers：打點資料集合	設定打點資料。
setPreviewTime	time：試看時間	設定試看時間，單位：秒。更多資訊，請參見試看。
getPreviewTime	無	擷取試看時間。
isPreview	無	是否試看。
getCurrentPDT	無	HLS的視頻格式支援即時擷取ProgramDateTime。
setTraceId	traceId：公用埋點	傳入公用埋點，用於日誌跟蹤，用法：`player.setTraceId(traceId);`。說明 Web播放器SDK 2.10.0及以上版本支援。
setTextTracks	textTracks	設定一組WebVTT字幕，樣本如下： `player.setTextTracks([{kind:'subtitles',label:'英文（美國）',src:'字幕地址',srclang:'en-US'}])` 說明 Web播放器SDK 2.12.0及以上版本支援。

事件

播放器事件

名稱	說明
ready	播放器視頻初始化按鈕渲染完畢。播放器UI初始設定需要此事件後觸發，避免UI被初始化所覆蓋。說明播放器提供的方法需要在該事件發生後才可以調用。
play	視頻由暫停恢複為播放時觸發。
pause	視頻暫停時觸發。
canplay	能夠開始播放音頻和視頻時發生，會多次觸發，僅H5播放器。
playing	播放中，會觸發多次。
ended	當前視頻播放完畢時觸發。
liveStreamStop	直播流中斷時觸發。HLS直播流在重試5次未成功後觸發。提示上層流中斷或需要重新載入視頻。說明如果HLS直播流斷流或者出錯，播放器會自動重試5次，不需要上層添加重試邏輯。
onM3u8Retry	HLS直播流中斷後重試事件，每次斷流只觸發一次。
hideBar	控制欄自動隱藏事件。
showBar	控制欄自動顯示事件。
waiting	資料緩衝事件。
timeupdate	播放位置發生改變時觸發，僅H5模式播放器。可通過getCurrentTime方法，得到當前播放時間。
snapshoted	截圖完成事件。
requestFullScreen	全屏事件，僅H5模式支援。
cancelFullScreen	取消全屏事件，iOS下不會觸發，僅H5模式支援。
error	錯誤事件。
startSeek	開始拖拽，參數返回拖拽點的時間。
completeSeek	完成拖拽，參數返回拖拽點的時間。
resolutionChange	直播情況下，推流端切換了解析度。
seiFrame	HLS或FLV收到SEI訊息。
rtsFallback	當RTS降級時觸發。其中，參數`reason`為降級的原因，`fallbackUrl`為降級到的地址。
settingSelected	當設定列表（倍速、清晰度、字幕等）被選中時觸發。 `/** * 設定列表被選中，如切換倍速到1.25X： * {name: '倍速', type: 'speed', text: '1.25X', key: 1.25} */`
rtsTraceId	當RTS拉流成功時觸發，通過訂閱該事件，可以擷取到RTS TraceId。回呼函數的參數中traceId為拉流的TraceId，source為當前RTS流的播放地址。 `player.on('rtsTraceId', function(data) { console.log('[EVENT]rtsTraceId', data.paramData); })`

訂閱事件

通過播放器執行個體的on方法訂閱。樣本如下：

var handleReady = function(e)
{
 console.log(e);
}
player.on('ready',handleReady);

通過播放器執行個體的off方法取消訂閱。樣本如下：
```
player.off('ready',handleReady);
```