ApsaraVideo VOD：介面說明

名稱

類型

說明

id

String

播放器外層容器的DOM元素ID。

source

String

使用URL播放方式時，通過source屬性來指定視頻播放地址URL。

vid

String

媒體轉碼服務的媒體ID。

playauth

String

播放憑證，擷取播放憑證請參見擷取音視頻播放憑證。

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

視頻寬度，僅H5模式支援。更多資訊，請參見設定顯示模式。

videoHeight

String

視頻高度，僅H5模式支援。更多資訊，請參見設定顯示模式。

preload

Boolean

播放器自動載入，目前僅H5模式可用。

cover

String

播放器預設封面圖片，請填寫正確的圖片URL地址。需要autoplay值為false時，才生效。Flash播放器封面也需要開啟允許跨域訪問。

isLive

Boolean

播放內容是否為直播，直播時會禁止使用者拖動進度條。預設值為false，播放直播流時需要設定為true。

autoplay

Boolean

播放器是否自動播放，在移動端autoplay屬性會失效。取值：

• true：開啟自動播放。

• false（預設值）：關閉自動播放。

autoplayPolicy

Object

播放器自適應靜音自動播放策略。僅當autoplay設定為true時，本屬性生效。配置樣本如下：

autoplayPolicy: {
  fallbackToMute: true, // 有聲自動播放失敗後，是否降級為靜音自動播放，預設為false
  showUnmuteBtn: true, // 靜音自動播放時，是否置中顯示靜音大按鈕，預設為true
}

rePlay

Boolean

播放器自動迴圈播放。

useH5Prism

Boolean

指定使用H5播放器。

useFlashPrism

Boolean

指定使用Flash播放器。

playsinline

Boolean

H5是否內建播放，有些Android瀏覽器不起作用。

skinRes

Url

皮膚圖片，不建議隨意修改該欄位，如要修改，請參見設定播放器皮膚。

skinLayout

Array | Boolean

功能組件布局配置，不傳該欄位使用預設布局。取值：false表示隱藏所有功能組件。更多資訊，請參見配置skinLayout屬性。

skinLayoutIgnore

Array

需要隱藏的UI組件。組件名稱請參見點播組件參數說明。配置樣本如下：

skinLayoutIgnore: [
  'bigPlayButton', // 隱藏大播放按鈕
  'controlBar.fullScreenButton' // 隱藏控制條上的全屏按鈕（通過點運算子進行子組件選擇）
]

controlBarVisibility

String

控制台的實現，取值：

• click：單擊播放器地區。

• hover（預設值）：移動到播放器地區。

• always：控制台一直顯示。

• never：隱藏整個控制台。

showBarTime

Number

控制欄自動隱藏時間，單位：毫秒。

extraInfo

String

JSON串，用於定製性的介面參數，目前僅Flash支援，取值：

• fullTitle：測試頁面，全屏時顯示視頻標題。

• m3u8BufferLength：播放HLS檔案時載入緩衝，ts檔案長度，單位為秒。

enableSystemMenu

Boolean

是否允許系統右鍵菜單顯示，預設為false。

format

String

指定播放地址格式，取值：

• 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：不顯示按鈕。

disableSeek

Boolean

禁用進度條的Seek，取值：

• true：禁用。

• false（預設值）：不禁用。

encryptType

Number

設定是否播放阿里雲視頻加密（私人加密）視頻，預設值為0，取值：

• 0：播放不加密視頻。

• 1：播放私人加密視頻。

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倍速。

hlsOption.maxLiveSyncPlaybackRate

Number

HLS直播模式下，設定直播追幀時的播放速度，預設為1，表示不追幀。

• 配置樣本：

  hlsOption: {
    maxLiveSyncPlaybackRate: 1.5, // 設定追幀的倍速
    liveSyncDurationCount: 3 // 設定觸發追幀的延遲切片個數
  }

• 樣本含義：當直播延遲大於3個切片的時間長度時，播放器會以1.5倍速播放追趕進度到3個切片（考慮到播放器需要一定的緩衝以應對網路變化，請謹慎修改liveSyncDurationCount的值，該值太小可能會引發卡頓）。

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產生的唯一識別碼）並儲存在瀏覽器緩衝中。

textTracks

Array

設定WebVTT外掛字幕，樣本如下：

textTracks: [
  { kind: 'subtitles', label: '中文', src: '字幕地址', srclang: 'zh-CN', default: true },
	{ kind: 'subtitles', label: '英文（美國）', src: '字幕地址', srclang: 'en-US' }
],

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

點擊視頻畫面進行暫停或播放。

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 秒開始播放。

dbClickFullscreen

Boolean

是否開啟雙擊全屏，預設在 PC 端開啟。

名稱

說明

ready

播放器視頻初始化按鈕渲染完畢。播放器UI初始設定需要此事件後觸發，以避免UI被初始化所覆蓋。

play

視頻由暫停恢複為播放時觸發。

pause

視頻暫停時觸發。

canplay

能夠開始播放音頻和視頻時發生，會多次觸發，僅限H5播放器。

playing

播放中，會觸發多次。

ended

當前視頻播放完畢時觸發。

liveStreamStop

直播流中斷時觸發。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。列印日誌中的參數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的瀏覽器上播放視頻，會出現視頻黑屏，只有聲音播放，此時會觸發該事件。