Aliplayer API說明 - ApsaraVideo VOD

本文對Aliplayer支援的屬性、方法、事件進行詳細說明。

說明

屬性

初始化Aliplayer可以設定多種屬性，包括授權License、播放資源資訊、播放器樣式資訊、播允許存取為等。

名稱	類型	說明
id	String	播放器外層容器的DOM元素ID。
source	String	使用URL播放方式時，通過source屬性來指定視頻播放地址URL。說明 URL播放方式的播放優先順序最高，高於VidAuth、VidSts等其他播放方式，即使用VidAuth、VidSts等其他播放方式時，不能指定source屬性，若指定了source屬性，播放器將優先選擇source中的地址播放。建議僅設定一種播放方式。 URL播放方式支援多清晰度設定，通過source屬性來指定多路清晰度流的地址，更多資訊，請參見多清晰度播放。樣本如下： `source:’{“HD”:”address1”,”SD”:”address2”}’`
vid	String	媒體轉碼服務的媒體ID。
playauth	String	播放憑證，擷取播放憑證請參見擷取音視頻播放憑證。
customVodServer	String	自訂點播代理網域名稱（適用於2.32.0及以上版本VidAuth播放方式）。需部署專屬請求代理服務，當預設點播網域名稱（*.aliyuncs.com）無法訪問時，播放器會自動降級至您的代理服務，可有效規避電訊廠商劫持風險，顯著提升播放穩定性與成功率。
playConfig	JSON	使用Vid方式（VidAuth和VidSts方式）播放時的自訂設定欄位，會透傳給點播介面。支援設定的自訂欄位及參數說明，請參見媒體播放自訂設定 PlayConfig。取值樣本： `{"PlayDomain":"vod.test_domain","PreviewTime":"20","MtsHlsUriToken":"yqCD7******oVjslp5Q"}`
authTimeout	Number	通過Vid方式（VidAuth和VidSts方式）播放時，擷取到的視頻播放URL的有效時間長度。單位：秒，預設取值：7200。請確保該時間長度大於視頻的實際時間長度，防止播放地址在播放完成前到期。
height	String	播放器高度，取值： 100% 100px
width	String	播放器寬度，取值： 100% 100px
autoSize	Boolean \| String	播放器尺寸自動適配視頻內容，可選值 'height', 'width'。如，您可以指定 width: '500px', autoSize: 'height'，播放器會保持寬度為 500px，高度根據視頻實際比例自動調整。或者，您可以指定 height: '500px', autoSize: 'width'，播放器會保持高度為 500px，寬度根據視頻實際比例自動調整註：autoSize: true 等同於 autoSize: 'height'，即預設是高度自適應。
videoWidth	String	視頻寬度，更多資訊請參見設定顯示模式。
videoHeight	String	視頻高度，更多資訊請參見設定顯示模式。
preload	Boolean	播放器自動載入。
cover	String	播放器預設封面圖片，請填寫正確的圖片URL地址。需要autoplay值為false時，才生效。
isLive	Boolean	播放內容是否為直播，直播時會禁止使用者拖動進度條。預設值為false，播放直播流時需要設定為true。
autoplay	Boolean	播放器是否自動播放，在移動端autoplay屬性會失效。取值： true：開啟自動播放。 false（預設值）：關閉自動播放。說明由於瀏覽器的限制，Web播放器SDK會出現自動播放失敗的情境，具體說明請參見進階功能。
autoplayPolicy	Object	播放器自適應靜音自動播放策略。僅當`autoplay`設定為`true`時，本屬性生效。配置樣本如下： `autoplayPolicy: { fallbackToMute: true, // 有聲自動播放失敗後，是否降級為靜音自動播放，預設為false showUnmuteBtn: true, // 靜音自動播放時，是否置中顯示靜音大按鈕，預設為true }` 說明靜音自動播放成功後，會觸發`mutedAutoplay`事件。當播放器開啟自動播放（`autoplay`設定為`true`），並開啟了自適應靜音自動播放（`autoplayPolicy.fallbackToMute`設定為`true`）後，播放器首先會嘗試帶聲音的自動播放，如果失敗，則會降級嘗試靜音自動播放。請注意，靜音自動播放也不意味著會100%播放成功。
rePlay	Boolean	播放器自動迴圈播放。
useH5Prism	Boolean	指定使用H5播放器。
playsinline	Boolean	H5是否內建播放，有些Android瀏覽器不起作用。
skinRes	Url	皮膚圖片，不建議隨意修改該欄位，如要修改，請參見設定播放器皮膚。
skinLayout	Array \| Boolean	功能組件布局配置，不傳該欄位使用預設布局。取值：false表示隱藏所有功能組件。更多資訊，請參見配置skinLayout屬性。
skinLayoutIgnore	Array	需要隱藏的UI組件。組件名稱請參見點播組件參數說明。配置樣本如下： `skinLayoutIgnore: [ 'bigPlayButton', // 隱藏大播放按鈕 'controlBar.fullScreenButton' // 隱藏控制條上的全屏按鈕（通過點運算子進行子組件選擇） ]` 說明 skinLayoutIgnore的優先順序要高於skinLayout屬性。
controlBarVisibility	String	控制台的實現，取值： click：單擊播放器地區。 hover（預設值）：移動到播放器地區。 always：控制台一直顯示。 never：隱藏整個控制台。
showBarTime	Number	控制欄自動隱藏時間，單位：毫秒。
enableSystemMenu	Boolean	是否允許系統右鍵菜單顯示，預設為false。
format	String	指定播放地址格式，取值： mp4 hls或m3u8 flv mp3 預設為空白。
mediaType	String	指定返迴音頻還是視頻，只有使用vid的播放方式時支援，預設值為video。取值： video：視頻。 audio：針對只包含音訊視頻格式，比如音訊MP4。
qualitySort	String	指定排序方式，只有使用Vid + PlayAuth播放方式時支援。取值： desc：表示按倒序排序（即：從大到小排序）。 asc：表示按正序排序（即：從小到大排序）。預設值：asc。
definition	String	顯示視頻清晰度，多個使用半形逗號（,）分隔，比如：‘FD,LD’，此值是vid對應流清晰度的一個子集。取值： FD（流暢） LD（標清） SD（高清） HD（超清） OD（原畫） 2K（2K） 4K（4K）
defaultDefinition	String	預設視頻清晰度，此值是vid對應流的一個清晰度。取值： FD（流暢） LD（標清） SD（高清） HD（超清） OD（原畫） 2K（2K） 4K（4K）
autoPlayDelay	Number	延遲播放時間，單位：秒。
language	String	國際化，預設為zh-cn。如果未設定，則採用瀏覽器語言。取值： zh-cn：中文。 en-us：英文。
languageTexts	JSON	自訂國際化文本JSON結構，key的值需要和language屬性值對應起來。樣本：{jp:{Play:”Play”}}自訂值請參見JSON結構。
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：不顯示按鈕。
disableSeek	Boolean	禁用進度條的Seek，取值： true：禁用。 false（預設值）：不禁用。
encryptType	Number	設定是否播放阿里雲視頻加密（私人加密）視頻，預設值為0，取值： 0：播放不加密視頻。 1：播放私人加密視頻。說明私人加密採用VID+Playauth的方式進行播放。 Web端標準加密使用URL方式播放，請參見視頻加密播放。
progressMarkers	Array	進度條打點內容數組，更多資訊，請參見進度條標記。
vodRetry	Number	點播失敗重試次數，預設3次。
liveRetry	Number	直播播放失敗重試次數，預設5次。
hlsFrameChasing	Boolean	HLS直播模式下，是否開啟追幀。取值： true：開啟追幀。 false（預設值）：不開啟追幀。說明僅2.21.0以下版本Web播放器SDK支援設定本參數，2.21.0及以上版本如需在HLS直播模式下設定追幀，請參考`hlsOption.maxLiveSyncPlaybackRate`屬性。
chasingFirstParagraph	Number	第一段追幀，單位：秒。預設20秒。說明僅2.21.0以下版本Web播放器SDK支援設定本參數，2.21.0及以上版本如需在HLS直播模式下設定追幀，請參考`hlsOption.maxLiveSyncPlaybackRate`屬性。
chasingSecondParagraph	Number	第二段追幀，單位：秒。預設40秒。說明僅2.21.0以下版本Web播放器SDK支援設定本參數，2.21.0及以上版本如需在HLS直播模式下設定追幀，請參考`hlsOption.maxLiveSyncPlaybackRate`屬性。
chasingFirstSpeed	Number	第一段追幀的倍速，預設1.1倍速。說明僅2.21.0以下版本Web播放器SDK支援設定本參數，2.21.0及以上版本如需在HLS直播模式下設定追幀，請參考`hlsOption.maxLiveSyncPlaybackRate`屬性。
chasingSecondSpeed	Number	第二段追幀的倍速，預設1.2倍速。說明僅2.21.0以下版本Web播放器SDK支援設定本參數，2.21.0及以上版本如需在HLS直播模式下設定追幀，請參考`hlsOption.maxLiveSyncPlaybackRate`屬性。
hlsOption.maxLiveSyncPlaybackRate	Number	HLS直播模式下，設定直播追幀時的播放速度，預設為1，表示不追幀。配置樣本： `hlsOption: { maxLiveSyncPlaybackRate: 1.5, // 設定追幀的倍速 liveSyncDurationCount: 3 // 設定觸發追幀的延遲切片個數 }` 樣本含義：當直播延遲大於3個切片的時間長度時，播放器會以1.5倍速播放追趕進度到3個切片（考慮到播放器需要一定的緩衝以應對網路變化，請謹慎修改`liveSyncDurationCount`的值，該值太小可能會引發卡頓）。說明僅2.21.0及以上版本Web播放器SDK支援設定本參數。
flvFrameChasing	Boolean	FLV直播模式下，是否開啟追幀，取值： true：開啟追幀。 false：不開啟追幀。預設值為false。
keyShortCuts	Boolean	是否啟用快速鍵，取值： true：開啟快速鍵。 false：不開啟快速鍵。預設值為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外掛字幕，樣本如下： `textTracks: [ { kind: 'subtitles', label: '中文', src: '字幕地址', srclang: 'zh-CN', default: true }, { kind: 'subtitles', label: '英文（美國）', src: '字幕地址', srclang: 'en-US' } ],` 欄位解釋如下： kind：vtt類型，取值包括subtitles和captions。 label：用於顯示的字幕名稱。 srclang：字幕語言。 src：字幕地址，請允許跨域訪問。 default：是否設定為預設顯示字幕，取值為true和false。僅Web播放器SDK 2.15.7及以上版本支援設定該欄位。說明 Web播放器SDK 2.12.0及以上版本支援。 WebVTT外掛字幕暫不支援以下瀏覽器： IE 安卓QQ瀏覽器、OPPO/一加的系統瀏覽器其他劫持video標籤的瀏覽器字幕屬性的詳細說明可參考HTML規範。更多關於字幕的進階設定，請參見外掛字幕。
ratio	Number	設定播放器按照固定比例縮放。例如：已知視頻長寬比為16:9，通過設定播放器參數為`width: "100%", ratio: 16/9`，如此播放器則可以和視頻內容保持比例一致，並且可以隨頁面縮放而自動等比例縮放。
extLanguageTexts	Object	播放器SDK內建了一套中英文介面文案，您可以通過本屬性自訂部分介面的顯示文案。以修改解析度的顯示文案為例：HD預設顯示為高清，可以通過以下方式修改HD顯示為1080p。 `extLanguageTexts: { 'zh-cn': { 'HD': "1080p" } }`
speedLevels	Array	設定自訂倍速列表數組，key表示倍速數值，text表示UI文本，若不傳則會使用預設列表。參數取值樣本如下： `speedLevels: [ {"key": 0.25, "text": "0.25"}, {"key": 0.5, "text": "0.5"}, {"key": 1, "text": "原速"}, {"key": 1.25, "text": "1.25"}, {"key": 1.5, "text": "1.5"}, {"key": 2,"text": "2"} ]`
logo	Array	設定自訂Logo圖片。樣本如下： `logo: [{ width: 30, position: 'bottom-right', origin: 'content', src: 'a.png' }, { width: 20, position: 'bottom-right', offsetY: -20, origin: 'content', src: 'b.png' }]` 欄位解釋如下： src：Logo圖片地址。 origin：定位參照物。取值如下： box：播放器 content：視頻內容 width/height：Logo的寬高，單位是百分比（根據origin計算），如果只指定一邊，則另一邊按圖片比例縮放。 position：Logo的相對位置，相對origin定位。取值如下： top-left：左上 top-right：右上 bottom-left：左下 bottom-right：右下 offsetX/offsetY：相對於position的位移，單位：百分比%（根據origin計算）。
license	Object	如需使用播放品質監控（舊版）、單點追查、播放H.265/H.266編碼協議視頻流等增值功能，請先填寫Web播放器SDK增值服務申請表單申請License授權後，再按如下方式接入License： `// domian為申請License授權時所填寫的網域名稱 // Key為License密鑰 license: { domain: "example.com", key: "example-key" }`
mute	Boolean	設定是否靜音播放。在瀏覽器禁止自動播放時可以通過配置此參數進行靜音自動播放。詳情請參見進階功能。
clickPause	Boolean	點擊視頻畫面進行暫停或播放。 true：啟用。 false：禁用。 PC端預設值為true，移動端預設值為false，請勿與dbClickSkip屬性同時使用以避免互動衝突。
disablePip	Boolean	隱藏瀏覽器內建的畫中畫按鈕。說明僅Web播放器SDK 2.20.0及以上版本支援。僅Firefox瀏覽器116及以上版本支援。
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 秒開始播放。
dbClickFullscreen	Boolean	是否開啟雙擊全屏，預設在 PC 端開啟。
longPressFastForward	Boolean	長按倍速功能（僅支援移動端），取值： true（預設值）：啟用。 false：禁用。
dbClickSkip	Boolean	雙擊左側地區快退、雙擊右側地區快進功能（僅支援移動端），取值： true（預設值）：啟用。 false：禁用。請勿與clickPause屬性同時使用以避免互動衝突。
enableMockFullscreen	Boolean	網頁全屏功能。播放器預設呼叫瀏覽器全屏API，在 iOS瀏覽器及部分Android瀏覽器上全屏會被系統播放器接管，導致UI消失等問題。如需避免被接管，可開啟此參數以CSS實現偽全屏。預設值為false。

方法

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

// 方式一：
var player = new Aliplayer({}, function (player) {
  player.play();
});

// 方式二：
var player = new Aliplayer({});
function handleReady(player) {
  player.play();
};
player.on('ready', handleReady);

Aliplayer執行個體可以調用的方法如下：

play()

播放視頻。

函數定義

() => Player

pause()

暫停視頻。

(showPlayButton?: boolean) => Player

參數

名稱	參數類型	是否必選	說明
showPlayButton	Boolean	否	是否顯示播放按鈕。

replay()

重播視頻。

函數定義

() => Player

seek()

跳轉到指定時刻進行播放。

函數定義

(time: number) => Player

參數

名稱	參數類型	是否必選	說明
time	number	是	要跳轉的時刻，時間單位：秒。

dispose()

播放器銷毀。

函數定義

() => void

getCurrentTime()

擷取當前的播放時刻，返回的時間單位：秒。

函數定義

() => number

getDuration()

擷取視頻總時間長度，返回的單位為秒，這個需要在視頻載入完成以後才可以擷取到，可以在play事件後擷取。

函數定義

() => number

getVolume()

擷取當前的音量，傳回值為0~1的實數。iOS和部分Android會失效。

函數定義

() => number | undefined

setVolume()

設定音量。

函數定義

(volume: number) => void

參數

名稱	參數類型	是否必選	說明
volume	number	是	vol為0~1的實數，iOS和部分Android會失效。

mute()

設定靜音。

函數定義

(quiet?: boolean) => Player

參數

名稱	參數類型	是否必選	說明
quiet	boolean	否	靜音時是否隱藏左下角的文字提示。

unMute()

取消靜音。

函數定義

(quiet?: boolean) => Player

參數

名稱	參數類型	是否必選	說明
quiet	boolean	否	取消靜音時是否隱藏左下角的文字提示。

getPlayTime()

擷取使用者的真實播放時間長度（不包含暫停時間長度，倍速情況下統計真實物理時間），傳回值的單位是秒。

函數定義

() => number

loadByUrl()

切換視訊。目前只支援同種格式（如 MP4、HLS、FLV）之間切換，不同格式切換請銷毀執行個體後重新建立。

函數定義

(url: string, seconds?: number, autoPlay?: boolean) => void

參數

名稱	參數類型	是否必選	說明
url	string	是	要切換的視頻地址。
seconds	number	否	切換後的起播位置。
autoPlay	boolean	否	切換後是否自動播放。

replayByVidAndPlayAuth()

點播（VOD）視頻切換，僅支援同種格式視頻切換。

函數定義

(vid: string, playauth: string) => void

參數

名稱	參數類型	是否必選	說明
vid	string	是	視頻ID。
playauth	string	是	播放憑證。

replayByVidAndAuthInfo()

ApsaraVideo for Media Processing（MPS）視頻切換，僅支援同種格式視頻切換。

函數定義

(vid: string, accId: string, accSecret: string, stsToken: string, authInfo: string, domainRegion: string) => void

參數詳情請參見MPS播放。

replayByMediaAuth()

通用媒體服務視頻切換，僅支援同種格式視頻切換。

函數定義

(mediaAuth: string) => void

參數

名稱	參數類型	是否必選	說明
mediaAuth	string	是	播放憑證。

getBuildInComponent()

擷取內建UI組件（如全屏按鈕、進度條等）。

函數定義

(name: string) => BuildInComponent;

參數

名稱	參數類型	是否必選	說明
name	string	是	內建群組件名稱（如fullScreenButton）可參見配置skinLayout屬性，每個組件均支援hide/show方法控制隱藏/顯示。

setPlayerSize()

設定播放器尺寸大小。

函數定義

(width: string, height: string) => void

參數

名稱

參數類型

是否必選

說明

width

string

是

設定播放器大小，取值：

400px
60%

height

string

是

setSpeed()

手動設定播放的倍速。移動端可能會失效，比如Android微信。倍速播放UI預設是開啟的。

函數定義

(speed: number) => void

參數

名稱	參數類型	是否必選	說明
speed	number	是	支援0.5~2倍速播放。

說明

關掉倍速的方法：

目前無法單獨關閉或者自訂倍速，只能整體關掉設定。
通過hack方式關掉倍速是通過樣式覆蓋來實現的：
```
.prism-setting-speed {
   display: none !important;
 }
```

setTraceId()

傳入公用埋點，用於日誌跟蹤。

函數定義

(traceId: string) => void

參數

名稱	參數類型	是否必選	說明
traceId	string	是	唯一識別ID。

說明

Web播放器SDK 2.10.0及以上版本支援。

setSanpshotProperties()

設定截圖參數。

函數定義

(width: number, height: number, rate: number) => void

參數

名稱	參數類型	是否必選	說明
width	number	是	高度、寬度單位為px，截圖品質取值範圍為0-1之間的數字，預設是1。視頻截圖詳細說明請參見視頻截圖。
height	number	是
rate	number	是

fullscreenService.requestFullScreen()

播放器全屏。

函數定義

() => Player

fullscreenService.cancelFullScreen()

播放器退出全屏，iOS調用無效，。

函數定義

() => Player

fullscreenService.getIsFullScreen()

擷取播放器全屏狀態。

函數定義

() => boolean

getStatus()

擷取播放器狀態。傳回型別String取值樣本如下：

init：初始化。
ready：準備。
loading：載入中。
play：播放。
pause：暫停。
playing：現正播放。
waiting：等待緩衝。
error：錯誤。
ended：結束。

函數定義

() => string

liveShiftSerivce.setLiveTimeRange()

設定直播的開始結束時間，開啟直播時移功能時使用。

函數定義

(start: string, end: string) => void

參數

名稱	參數類型	是否必選	說明
start	string	是	start 直播開始時間。
end	string	是	end 直播結束時間。

樣本

player.liveShiftSerivce.setLiveTimeRange('2025/03/21 12:43:00', '2025/03/21 23:31:00')

setRotate()

設定播放器旋轉角度。

函數定義

(rotate: number) => void

參數

名稱	參數類型	是否必選	說明
rotate	number	是	正數表示正時針旋轉，負數表示逆時針旋轉。樣本：setRotate(90)。更多資訊，請參見設定顯示模式。

getRotate()

擷取播放器旋轉角度。

函數定義

() => number

更多資訊，請參見設定顯示模式。

setImage()

設定鏡像。

函數定義

(type: string) => void

參數

名稱

參數類型

是否必選

說明

type

string

是

取值：

horizon：水平。
vertical：垂直。

樣本：setImage(‘horizon’)。更多資訊，請參見設定顯示模式。

setCover()

設定封面。

函數定義

(coverUrl: string) => void

參數

名稱	參數類型	是否必選	說明
coverUrl	string	是	封面地址。

setProgressMarkers()

設定打點。

函數定義

(markers: Array<{ time: number, text: string }>) => void

參數

名稱

參數類型

是否必選

說明

markers

Array<markers>

是

markers：打點資料集合，必選；

marker.time：打點時間，必選；

marker.text：打點文字，必選；

詳見參數 progressMarkers。

setPreviewTime()

設定試看時間。

函數定義

(time: number) => void

參數

名稱	參數類型	是否必選	說明
time	number	是	單位：秒。更多資訊，請參見試看。

getPreviewTime()

擷取試看時間。

函數定義

() => number

isPreview()

是否試看。

函數定義

() => boolean

getCurrentPDT()

HLS的視頻格式支援即時擷取ProgramDateTime。

函數定義

() => number | undefined

setTextTracks()

設定一組WebVTT字幕。

函數定義

(textTracks: Array<{ kind: string, label: string, src: string, srclang: string }>) => void

參數

名稱

參數類型

是否必選

說明

textTracks

Array<object>

是

樣本如下：

player.setTextTracks([ { kind: 'subtitles', label: '中文', src: '字幕地址', srclang: 'zh-CN' },{ kind: 'subtitles', label: '英文（美國）', src: '字幕地址', srclang: 'en-US' }])

說明

Web播放器SDK 2.12.0及以上版本支援。

setLogo()

設定自訂Logo圖片。

函數定義

(logoList: Array<{ width: number, position: string, origin: string, src: string }>) => void

參數

名稱

參數類型

是否必選

說明

logoList

Array<object>

是

樣本如下：

player.setLogo([{
      width: 30,
      position: 'bottom-right',
      origin: 'content',
      src: 'a.jpg'
    },
    {
      width: 20,
      position: 'bottom-right',
      offsetY: -20,
      origin: 'content',
      src: 'b.jpg'
    }])

各欄位的詳細解釋參考屬性：logo。

setWatchTime()

動態更新當前視頻的 watchStartTime/watchEndTime。

函數定義

(start: number, end: number) => void

參數

名稱	參數類型	是否必選	說明
start	string	是	start 開始時間。
end	string	是	end 結束時間。

setNextWatchTime()

設定下一個視頻的 watchStartTime/watchEndTime。如果您要使用loadByUrl/replayByVidAndPlayAuth 切換視訊，且下一個視頻的播放區間和當前視頻不同，可以先調用 setNextWatchTime 設定下個視頻的區間。

函數定義

(start: number, end: number) => void

參數

名稱	參數類型	是否必選	說明
start	string	是	start 開始時間。
end	string	是	end 結束時間。

setStartEnd()

動態更新當前視頻的 start/end。

函數定義

(start: number, end: number) => void

參數

名稱	參數類型	是否必選	說明
start	string	是	start 開始時間。
end	string	是	end 結束時間。

setNextStartEnd()

設定下一個視頻的 start/end。如果您要使用 loadByUrl/replayByVidAndPlayAuth 切換視訊，且下一個視頻的截取區間和當前視頻不同，可以先調用 setNextStartEnd 設定下個視頻的區間。

函數定義

(start: number, end: number) => void

參數

名稱	參數類型	是否必選	說明
start	string	是	start 開始時間。
end	string	是	end 結束時間。

takeSnapshot()

截圖，返回的 base64 可以直接用 img.src 載入；可以使用 setSanpshotProperties 設定截圖品質，snapshotWatermark 設定截圖浮水印。

註：部分移動端瀏覽器由於 video 被劫持（如 UC、QQ 瀏覽器），可能無法使用截圖功能。

函數定義

() => { time: number, base64: string, binary: string, error: Error | null }

傳回值

名稱	參數類型	說明
time	string	截圖時間。
base64	string	截圖內容base64。
binary	string	截圖內容為二進位字串。
error	Error	截圖異常詳情。

showControlBar()

顯示控制條。

函數定義

() => void

hideControlBar()

隱藏控制條。

函數定義

() => void

事件

播放器事件

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

訂閱事件

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

function handleReady() {};
player.on('ready', handleReady);
// 有些事件會頻繁觸發，可以通過 player.one 只監聽一次
player.one('canplay', () => {});

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