屬性和介面說明

更新時間：2025-10-10 12:02:04

播放器屬性

將所有參數以物件形式傳入播放器，可以設定的屬性包括：

名稱	類型	是否必填	描述
vid	string	是	上傳到保利威平台的音視訊的唯一ID
viewerInfo	object	可選	自訂觀眾資訊。設定後，播放器上報的觀看行為日誌中會附帶觀眾資訊。詳見觀眾資訊設定與統計。
wrap	string	可選	需要載入播放器的css選擇器
skin	string	可選	播放器皮膚（white / grey），如果使用自訂播放器皮膚，則不需傳該參數。
autoPlay	boolean	可選	是否自動播放。註：目前大多數瀏覽器都會限制自動播放，該參數可能無效。
loop	boolean	可選	是否循環播放
volume	number	可選	音量（範圍0~1）
speed	number \| boolean	可選	若傳入數值，則為預設倍速。若是布林值，則為false時可隱藏播放器介面上的倍速選項面板。
speedOptions	array	可選	倍速選項陣列，預設值為 [0.5, 0.75, 1.0, 1.25, 1.5, 2.0, 3.0]， speed類型為數值且不存在speedOptions陣列中時，會自動補充到陣列。
startTime	number	可選	從第幾秒開始播放，需小於視訊時長
playsafe	function \| string	可選	PC端播放加密音/視訊所需的授權憑證，若要在PC端播放加密音視訊才需要該參數，非加密音視訊可忽略。詳見：播放加密視訊。
playsafeUrl	string	可選	取得PC端播放加密音/視訊憑證的介面URL。與playsafe參數二選一。
sign	string	可選	行動端播放加密音/視訊所需的簽名，非加密音/視訊可忽略。詳見：播放加密視訊。
ts	string	可選	行動播放加密音/視訊需傳入的時間戳。

靜態屬性

可以透過 PlvAudioPlayer[key] 取得。

名稱	類型	描述
EventType	object	回呼事件的彙總。

實例屬性

每個播放器實例都有以下屬性：

名稱	類型	描述
audio	object	原生的 audio 物件。
currentTime	number	目前播放位置，單位：秒。
duration	number	目前音訊時長，單位：秒。
paused	boolean	目前是否暫停狀態。

播放器介面

API需要在播放器初始化完成之後呼叫，例如：

plvAudioPlayer.on('ready', function() {
  console.info('播放器初始化完毕');
  plvAudioPlayer.seek(100); // seek到第100秒
});

播放器介面列表如下：

名稱	參數類型	說明
play	/	開始播放
pause	/	暫停播放
(async) changeVid	(String\|Object)	切換媒體檔案。可傳入vid字串，或包含playsafe、sign、ts、vid屬性的物件。
seek	Number	跳轉到指定位置播放，參數單位為：秒。
setLoop	Boolean	是否循環播放
setSpeed	Number	設定倍速播放，參數取值(0,16]。非法值將設定為 1。
setVolume	Number	設定音量，參數取值[0,1]。非法值將設定為1。
stop	/	終止播放
(async) updateParam	/	更新播放器參數，音訊會結束播放並重新下載。支援本文檔中所列的播放器屬性參數。
destroy	/	銷毀目前播放器實例

播放器事件

播放器提供了一些常用的事件回呼，使用方法如：

plvAudioPlayer.on('ready', function() {
  console.info('ready');
});

事件列表如下：

名稱	說明
ready	播放器初始化完畢，播放器提供的方法需在此事件發生後才可以呼叫。參數回傳包含音訊資訊的data物件，可透過`data.audioInfo` 取得音訊相關資訊。
loadstart	在媒體開始載入時觸發。
play	媒體播放時觸發
playing	播放中，會觸發多次
pause	暫停時觸發
seeking	在跳躍操作開始時觸發
seeked	在跳躍操作完成時觸發
ratechange	在播放速率改變時觸發
timeupdate	目前播放時間點（currentTime屬性）改變時觸發
waiting	在一個待執行的操作（如播放）因等待另一個操作（如跳躍或載入）被延遲時觸發。
ended	播放結束時觸發
stop	stop方法完成後觸發
hlsError	播放hls檔案發生錯誤時觸發
serverError	發生播放錯誤時觸發，參數回傳保護報錯資訊的data物件，可以透過 `data.code` 取得報錯資訊的錯誤碼