本文對Web播放器SDK的屬性、方法、事件進行了說明,並提供了播放器介面的範例程式碼。
屬性
如果您在使用過程中遇見問題,可以參考Web播放器常見問題或播放異常自主排查。
名稱 | 類型 | 說明 |
id | String | 播放器外層容器的DOM元素ID。 |
source | String | 使用URL播放方式時,通過source屬性來指定視頻播放地址URL。 說明
|
vid | String | 媒體轉碼服務的媒體ID。 |
playauth | String | 播放憑證,擷取播放憑證請參見擷取音視頻播放憑證。 |
playConfig | JSON | 使用Vid方式(VidAuth和VidSts方式)播放時的自訂設定欄位,會透傳給點播介面。支援設定的自訂欄位及參數說明,請參見媒體播放自訂設定 PlayConfig。取值樣本:
|
authTimeout | Number | 通過Vid方式(VidAuth和VidSts方式)播放時,擷取到的視頻播放URL的有效時間長度。單位:秒,預設取值:7200。 請確保該時間長度大於視頻的實際時間長度,防止播放地址在播放完成前到期。 |
height | String | 播放器高度,取值:
說明 Chrome瀏覽器下Flash播放器解析度不能小於397x297px。 |
width | String | 播放器寬度,取值:
說明 Chrome瀏覽器下Flash播放器解析度不能小於397x297px。 |
autoSize | Boolean | String | 播放器尺寸自動適配視頻內容,可選值 'height', 'width'。 如,您可以指定 width: '500px', autoSize: 'height',播放器會保持寬度為 500px,高度根據視頻實際比例自動調整。 或者,您可以指定 height: '500px', autoSize: 'width',播放器會保持高度為 500px,寬度根據視頻實際比例自動調整 註:autoSize: true 等同於 autoSize: 'height',即預設是高度自適應。 |
videoWidth | String | 視頻寬度,僅H5模式支援。更多資訊,請參見設定顯示模式。 |
videoHeight | String | 視頻高度,僅H5模式支援。更多資訊,請參見設定顯示模式。 |
preload | Boolean | 播放器自動載入,目前僅H5模式可用。 |
cover | String | 播放器預設封面圖片,請填寫正確的圖片URL地址。需要autoplay值為false時,才生效。Flash播放器封面也需要開啟允許跨域訪問。 |
isLive | Boolean | 播放內容是否為直播,直播時會禁止使用者拖動進度條。預設值為false,播放直播流時需要設定為true。 |
autoplay | Boolean | 播放器是否自動播放,在移動端autoplay屬性會失效。取值:
說明 由於瀏覽器的限制,Web播放器SDK會出現自動播放失敗的情境,具體說明請參見自動播放。 |
autoplayPolicy | Object | 播放器自適應靜音自動播放策略。僅當
說明
|
rePlay | Boolean | 播放器自動迴圈播放。 |
useH5Prism | Boolean | 指定使用H5播放器。 |
useFlashPrism | Boolean | 指定使用Flash播放器。 |
playsinline | Boolean | H5是否內建播放,有些Android瀏覽器不起作用。 |
skinRes | Url | 皮膚圖片,不建議隨意修改該欄位,如要修改,請參見設定播放器皮膚。 |
skinLayout | Array | Boolean | 功能組件布局配置,不傳該欄位使用預設布局。取值:false表示隱藏所有功能組件。更多資訊,請參見配置skinLayout屬性。 |
skinLayoutIgnore | Array | 需要隱藏的UI組件。組件名稱請參見點播組件參數說明。配置樣本如下:
說明 skinLayoutIgnore的優先順序要高於skinLayout屬性。 |
controlBarVisibility | String | 控制台的實現,取值:
|
showBarTime | Number | 控制欄自動隱藏時間,單位:毫秒。 |
extraInfo | String | JSON串,用於定製性的介面參數,目前僅Flash支援,取值:
|
enableSystemMenu | Boolean | 是否允許系統右鍵菜單顯示,預設為false。 |
format | String | 指定播放地址格式,取值:
預設為空白,僅H5支援。 |
mediaType | String | 指定返迴音頻還是視頻,只有使用vid的播放方式時支援,預設值為video。取值:
|
qualitySort | String | 指定排序方式,只有使用Vid + PlayAuth播放方式時支援。取值:
預設值:asc,僅H5支援。 |
definition | String | 顯示視頻清晰度,多個使用半形逗號(,)分隔,比如:‘FD,LD’,此值是vid對應流清晰度的一個子集,僅H5模式支援。取值:
|
defaultDefinition | String | 預設視頻清晰度,此值是vid對應流的一個清晰度,僅H5模式支援。取值:
|
autoPlayDelay | Number | 延遲播放時間,單位:秒。更多資訊,請參見配置延遲播放。 |
autoPlayDelayDisplayText | String | 延遲播放提示文本,更多資訊,請參見配置延遲播放。 |
language | String | 國際化,預設為zh-cn。如果未設定,則採用瀏覽器語言。取值:
|
languageTexts | JSON | 自訂國際化文本JSON結構,key的值需要和language屬性值對應起來。樣本:{jp:{Play:”Play”}}自訂值請參見JSON結構。 |
snapshot | Boolean | 是否啟用Flash截圖功能。取值:
|
snapshotWatermark | Object | H5設定截圖浮水印。 |
useHlsPluginForSafari | Boolean | Safari瀏覽器是否啟用HLS外掛程式播放,Safari 11除外。取值:
|
enableStashBufferForFlv | Boolean | H5播放FLV時,設定是否啟用播放緩衝,只在直播下起作用。取值:
|
stashInitialSizeForFlv | Number | H5播放FLV時,初始緩衝大小,只在直播下起作用。預設32KB。 當設定的值較小時,會提升起播速度,但是值太小時,可能會導致播放一小段之後卡頓。 |
loadDataTimeout | Number | 緩衝多長時間後,提示使用者切換低清晰度,單位:秒。預設20秒。 |
waitingTimeout | Number | 最大緩衝逾時時間,超過這個時間會有錯誤提示,單位:秒。預設60秒。 |
diagnosisButtonVisible | Boolean | 是否顯示檢測按鈕,取值:
|
disableSeek | Boolean | 禁用進度條的Seek,取值:
|
encryptType | Number | 設定是否播放阿里雲視頻加密(私人加密)視頻,預設值為0,取值:
|
progressMarkers | Array | 進度條打點內容數組,更多資訊,請參見進度條標記。 |
vodRetry | Number | 點播失敗重試次數,預設3次。 |
liveRetry | Number | 直播播放失敗重試次數,預設5次。 |
hlsFrameChasing | Boolean | HLS直播模式下,是否開啟追幀。取值:
說明 僅2.21.0以下版本Web播放器SDK支援設定本參數,2.21.0及以上版本如需在HLS直播模式下設定追幀,請參考 |
chasingFirstParagraph | Number | 第一段追幀,單位:秒。預設20秒。 說明 僅2.21.0以下版本Web播放器SDK支援設定本參數,2.21.0及以上版本如需在HLS直播模式下設定追幀,請參考 |
chasingSecondParagraph | Number | 第二段追幀,單位:秒。預設40秒。 說明 僅2.21.0以下版本Web播放器SDK支援設定本參數,2.21.0及以上版本如需在HLS直播模式下設定追幀,請參考 |
chasingFirstSpeed | Number | 第一段追幀的倍速,預設1.1倍速。 說明 僅2.21.0以下版本Web播放器SDK支援設定本參數,2.21.0及以上版本如需在HLS直播模式下設定追幀,請參考 |
chasingSecondSpeed | Number | 第二段追幀的倍速,預設1.2倍速。 說明 僅2.21.0以下版本Web播放器SDK支援設定本參數,2.21.0及以上版本如需在HLS直播模式下設定追幀,請參考 |
hlsOption.maxLiveSyncPlaybackRate | Number | HLS直播模式下,設定直播追幀時的播放速度,預設為1,表示不追幀。
說明 僅2.21.0及以上版本Web播放器SDK支援設定本參數。 |
flvFrameChasing | Boolean | FLV直播模式下,是否開啟追幀,取值:
預設值為false。 |
keyShortCuts | Boolean | 是否啟用快速鍵,取值:
預設值為false。 說明 方向鍵(左右鍵)控制快進和快退,方向鍵(上下鍵)控制音量的增減,空格鍵暫停和播放。 |
keyFastForwardStep | Number | 快進快退的時間長度,單位:秒。預設為10秒。 |
rtsFallback | Boolean | 當瀏覽器不支援RTS或RTS拉流失敗時,播放器會自動嘗試使用FLV/HLS進行降級播放,且優先選擇延遲更低的FLV,當瀏覽器不支援FLV時,會選擇HLS。 此功能是預設開啟的,如果您需要禁用,可以傳false。 |
rtsFallbackType | String | 指定RTS降級到的協議,可選 HLS/FLV,預設不傳此參數,代表自動選擇,播放器會優先選擇延遲更低的FLV,如果瀏覽器不支援則降級到HLS。 |
rtsFallbackSource | String | 我們推薦使用播放器的預設降級策略,但是如果您希望指定固定的拉流地址進行降級,可以使用此參數。 |
traceId | String | traceId為您自有的使用者唯一識別碼,將traceId傳入公用埋點,便於跟蹤上報日誌。正常情況下,Web播放器SDK已預設開啟日誌上報,傳遞traceId,可便於您標識使用者身份;如果不傳遞,Web播放器SDK會預設產生一個uuid(播放器SDK產生的唯一識別碼)並儲存在瀏覽器緩衝中。 說明 Web播放器SDK 2.10.0及以上版本支援。 |
textTracks | Array | 設定WebVTT外掛字幕,樣本如下:
欄位解釋如下:
|
ratio | Number | 設定播放器按照固定比例縮放。例如:已知視頻長寬比為16:9,通過設定播放器參數為 |
extLanguageTexts | Object | 播放器SDK內建了一套中英文介面文案,您可以通過本屬性自訂部分介面的顯示文案。以修改解析度的顯示文案為例:HD預設顯示為高清,可以通過以下方式修改HD顯示為1080p。
|
speedLevels | Array | 設定自訂倍速列表數組,key表示倍速數值,text表示UI文本,若不傳則會使用預設列表。參數取值樣本如下:
|
logo | Array | 設定自訂Logo圖片。樣本如下:
欄位解釋如下:
|
license | Object | 如需使用播放品質監控、單點追查、播放H.265/H.266編碼協議視頻流等增值功能,請先填寫Web播放器SDK增值服務申請表單申請License授權後,再按如下方式接入License:
|
mute | Boolean | 設定是否靜音播放。在瀏覽器禁止自動播放時可以通過配置此參數進行靜音自動播放。詳情請參見自動播放。 |
clickPause | Boolean | 點擊視頻畫面進行暫停或播放。 |
disablePip | Boolean | 隱藏瀏覽器內建的畫中畫按鈕。 說明
|
env | String | 播放器的埋點資料預設會上傳到中國資料中心,如果您有海外資料合規需求,請傳入參數 env: 'SEA',資料將上傳到新加坡資料中心。 |
watchStartTime | Number | 單獨使用,代表開始播放的時間; 和 watchEndTime 配合使用,開啟區間播放功能,只能在開始和結束時間範圍內播放和拖拽進度條。 單位:秒 |
watchEndTime | Number | 和 watchStartTime 配合使用,開啟區間播放功能,只能在開始和結束時間範圍內播放和拖拽進度條。 如果參數值小於watchStartTime,則watchStartTime失效。 單位:秒 |
start | Number | 和 end 配合使用,截取視頻的一部分作為一個獨立的視頻。如:原視頻時間長度 60 秒,設定 start:10、end:30 後,視頻顯示時間長度為 20 秒,並從原視頻的第 10 秒開始播放。 |
end | Number | 和 start 配合使用,截取視頻的一部分作為一個獨立的視頻。如:原視頻時間長度 60 秒,設定 start:10、end:30 後,視頻顯示時間長度為 20 秒,並從原視頻的第 10 秒開始播放。 |
方法
方法需要在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會失效。 |
mute | 無 | 設定靜音。 |
unMute | 無 | 取消靜音。 |
loadByUrl | url(String),time(Number) | 直接播放視頻url,time為可選值(單位:秒)。目前只支援同種格式(MP4、FLV、HLS)之間切換。暫不支援直播RTMP流切換。 |
replayByVidAndPlayAuth | vid(String):視頻ID,playauth(String):播放憑證 | 目前只支援H5播放器。暫不支援不同格式視頻間的切換。暫不支援直播RTMP流切換。 可用於點播DRM流的切換,用法: |
replayByVidAndAuthInfo | 僅MPS使用者時使用參數順序為:vid(String)、accId(String)、accSecret(String)、stsToken(String)、authInfo(String)、domainRegion(String) | 目前只支援H5播放器。暫不支援不同格式視頻間的之間切換。暫不支援直播rtmp流切換。 |
setPlayerSize | w(String),h(String) | 設定播放器大小,取值:
Chrome瀏覽器下Flash播放器解析度不能小於397x297px。 |
setSpeed | speed(Number) | 手動設定播放的倍速,支援0.5~2倍速播放,倍速播放僅H5模式支援。移動端可能會失效,比如Android微信。倍速播放UI預設是開啟的。 說明 關掉倍速的方法:
|
setSanpshotProperties | width(Number):寬度,height(Number):高度,rate(Number):截圖品質 | 設定截圖參數,高度、寬度單位為px,截圖品質取值範圍為0-1之間的數字,預設是1。視頻截圖詳細說明請參見視頻截圖。 |
fullscreenService.requestFullScreen | 無 | 播放器全屏,僅H5支援。 |
fullscreenService.cancelFullScreen | 無 | 播放器退出全屏,iOS調用無效,僅H5支援。 |
fullscreenService.getIsFullScreen | 無 | 擷取播放器全屏狀態,僅H5支援。 |
getStatus | 無 | 擷取播放器狀態,取值:
|
setRotate | rotate(Number):旋轉角度 | 參數為旋轉角度,正數表示正時針旋轉,負數表示逆時針旋轉。樣本:setRotate(90)。更多資訊,請參見設定顯示模式。 |
getRotate | 無 | 擷取旋轉角度。更多資訊,請參見設定顯示模式。 |
setImage | image(String):鏡像類型 | 設定鏡像,取值:
樣本:setImage(‘horizon’)。更多資訊,請參見設定顯示模式。 |
dispose | 無 | 播放器銷毀。 |
setCover | cover(String):封面地址 | 設定封面。 |
setProgressMarkers | markers(Array):打點資料集合 | 設定打點資料。 |
setPreviewTime | time(Number):試看時間 | 設定試看時間,單位:秒。更多資訊,請參見試看。 |
getPreviewTime | 無 | 擷取試看時間。 |
isPreview | 無 | 是否試看。 |
getCurrentPDT | 無 | HLS的視頻格式支援即時擷取ProgramDateTime。 |
setTraceId | traceId(String):公用埋點 | 傳入公用埋點,用於日誌跟蹤,用法: 說明 Web播放器SDK 2.10.0及以上版本支援。 |
setTextTracks | textTracks(Array) | 設定一組WebVTT字幕,樣本如下:
說明 Web播放器SDK 2.12.0及以上版本支援。 |
setLogo | logo(Array) | 設定自訂Logo圖片。樣本如下:
各欄位的詳細解釋參考屬性:logo。 |
setWatchTime | startTime(Number), endTime(Number) | 動態更新當前視頻的 watchStartTime/watchEndTime |
setNextWatchTime | startTime(Number), endTime(Number) | 設定下一個視頻的 watchStartTime/watchEndTime。 如果您要使用 loadByUrl/replayByVidAndPlayAuth 切換視訊,且下一個視頻的播放區間和當前視頻不同,可以先調用 setNextWatchTime 設定下個視頻的區間。 |
setStartEnd | start(Number), end(Number) | 動態更新當前視頻的 start/end。 |
setNextStartEnd | start(Number), end(Number) | 設定下一個視頻的 start/end。 如果您要使用 loadByUrl/replayByVidAndPlayAuth 切換視訊,且下一個視頻的截取區間和當前視頻不同,可以先調用 setNextStartEnd 設定下個視頻的區間。 |
takeSnapshot | 無 | 截圖,返回的 base64 可以直接用 img.src 載入。 可以使用 setSanpshotProperties 設定截圖品質,snapshotWatermark 設定截圖浮水印。 註:部分移動端瀏覽器由於 video 被劫持(如 UC、QQ 瀏覽器),可能無法使用截圖功能。 |
事件
播放器事件
名稱 | 說明 |
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降級時觸發。其中,參數 |
settingSelected | 當設定列表(倍速、清晰度、字幕等)被選中時觸發。 說明 因開源倍速外掛程式與播放器設定不同步,使用它需自訂代碼並重新編譯。您可定義事件監聽,若需要使用播放器的
|
rtsTraceId | 當RTS拉流成功時觸發,通過訂閱該事件,可以擷取到RTS TraceId。列印日誌中的參數
|
autoplay | 自動播放成功或失敗時會觸發。回調參數 |
mutedAutoplay | 當 |
videoUnavailable | 當視頻編碼格式不支援導致視頻播放發生黑屏時觸發。例如在不支援H.265的瀏覽器上播放視頻,會出現視頻黑屏,只有聲音播放,此時會觸發該事件。 |
訂閱事件
通過播放器執行個體的on方法訂閱。樣本如下:
var handleReady = function(e) { console.log(e); } player.on('ready',handleReady);
通過播放器執行個體的off方法取消訂閱。樣本如下:
player.off('ready',handleReady);