ApsaraVideo VOD：進階功能

播放控制

自動播放

• Web播放器SDK支援自動播放。

  由於瀏覽器自身的限制，在Web播放器SDK中無法通過設定autoplay屬性或者調用play()方法實現自動播放。只有視頻靜音才可以實現自動播放或者通過使用者行為手動觸發播放（例如：初始化後，手動調用setVolume方法對視頻進行靜音處理）。

  說明

  • 案頭端瀏覽器有以下限制：

    • Safari瀏覽器：macOS High Sierra Safari 11及以上版本限制自動播放。

    • Chrome瀏覽器：Chrome 55及以上版本限制自動播放。

  • 移動端瀏覽器不排除部分瀏覽器和WebView允許自動播放，Android系統中較為常見。

  • 微信、QQ瀏覽器等其他瀏覽器劫持視頻播放時，即使視頻靜音也將無法實現自動播放，更多資訊請參見瀏覽器劫持視頻播放說明。

  以下樣本以H5模式下的URL播放方式為例展示如何設定視頻靜音自動播放：

  • 2.20.3及以上版本

    var player = new Aliplayer({
      "id": "player-con",
      //您的播放地址。樣本：example.aliyundoc.com/video/****.mp4
      "source":"<your URL>",
      "autoplay": true,
      "mute": true
      }, function (player) {});

  • 2.20.3以下版本

    //初始化後，手動對視頻進行靜音處理
    var player = new Aliplayer({
      "id": "player-con",
      //您的播放地址。樣本：example.aliyundoc.com/video/****.mp4
      "source":"<your URL>",  
      "autoplay": true
      }, function (player) {
      player.mute()
      //[或者] player.setVolume(0)
      }
    );

• iOS端微信支援自動播放。樣本如下：

  <div id="player-con"></div>
  <script src="http://res.wx.qq.com/open/js/jweixin-1.6.0.js"></script>
  <script>
  wx.config({
      // 配置資訊, 即使不正確也能使用 wx.ready
      debug: false,    //false代表關閉偵錯模式，true代表開啟偵錯模式
      appId: '',       //appId
      timestamp: 1,    //產生簽名的時間戳記
      nonceStr: '',    //產生簽名的隨機串
      signature: '',   //簽名
      jsApiList: []    //需要使用的JS介面列表
  });
  wx.ready(function() {
    // 在此處初始化播放器
    createPlayer();
  });
  
  function createPlayer() {
    var player = new Aliplayer({
      id: 'player-con',
      source: '',
      autoplay: true
    });
  }
  </script>

連續播放

自訂播放器外觀和控制項

Web播放器SDK支援自訂播放器外觀（播放器皮膚）、控制項（播放器控制欄UI、報錯UI等）是否顯示以及顯示的位置。

• 播放器控制欄UI

  通過修改skinLayout屬性定製組件是否顯示及顯示位置。更多資訊，請參見配置skinLayout屬性。

  • ApsaraVideo for VODH5模式預設配置

    skinLayout:[
       {name: "bigPlayButton", align: "blabs", x: 30, y: 80},
        {name: "H5Loading", align: "cc"},
        {name: "errorDisplay", align: "tlabs", x: 0, y: 0},
        {name: "infoDisplay"},
        {name:"tooltip", align:"blabs",x: 0, y: 56},
        {name: "thumbnail"},
        {
          name: "controlBar", align: "blabs", x: 0, y: 0,
          children: [
            {name: "progress", align: "blabs", x: 0, y: 44},
            {name: "playButton", align: "tl", x: 15, y: 12},
            {name: "timeDisplay", align: "tl", x: 10, y: 7},
            {name: "fullScreenButton", align: "tr", x: 10, y: 12},
            {name:"subtitle", align:"tr",x:15, y:12},
            {name:"setting", align:"tr",x:15, y:12},
            {name: "volume", align: "tr", x: 5, y: 10}
          ]
        }
      ]

  • ApsaraVideo for VODFlash模式預設配置

    skinLayout:[
        {name:"bigPlayButton", align:"blabs", x:30, y:80},
        {
          name:"controlBar", align:"blabs", x:0, y:0,
          children: [
            {name:"progress", align:"tlabs", x: 0, y:0},
            {name:"playButton", align:"tl", x:15, y:26},
            {name:"nextButton", align:"tl", x:10, y:26},
            {name:"timeDisplay", align:"tl", x:10, y:24},
            {name:"fullScreenButton", align:"tr", x:10, y:25},
            {name:"streamButton", align:"tr", x:10, y:23},
            {name:"volume", align:"tr", x:10, y:25}
          ]
        },
        {
          name:"fullControlBar", align:"tlabs", x:0, y:0,
          children: [
            {name:"fullTitle", align:"tl", x:25, y:6},
            {name:"fullNormalScreenButton", align:"tr", x:24, y:13},
            {name:"fullTimeDisplay", align:"tr", x:10, y:12},
            {name:"fullZoom", align:"cc"}
          ]
        }
    ]

• 報錯UI

  Web播放器SDK提供預設的報錯UI，同時提供兩種自訂錯誤UI的方式。詳細資料，請參見H5自訂錯誤UI。

  • 通過CSS自訂皮膚

    保留播放器原有的布局和顯示，通過重寫CSS自訂皮膚，修改背景顏色、是否顯示、字型、位置等。

  • 重寫UI

    重寫UI需要訂閱錯誤事件。

• Web播放器SDK皮膚

  Web播放器SDK UI不能滿足業務需求時，可以通過配置播放器CSS樣式來具體指定播放器皮膚。

  H5模式播放器皮膚設定

  說明

  具體可以參照播放器的CSS設定檔aliplayer-min.css。以下代碼以大播放按鈕為例，更多資訊請參見設定播放器皮膚。

  .prism-player .prism-big-play-btn {
    width: 90px;
    height: 90px;
    background: url("//gw.alicdn.com/tps/TB1YuE3KFXXXXaAXFXXXXXXXXXX-256-512.png") no-repeat -2px -2px;
  }

  Flash模式播放器皮膚設定

  在http://[domain]/[path]/目錄下存放skin.png與skin.xml檔案，並在player的輸入參數中添加skinRes："http://domain/path/skin"。

  說明

  以下代碼以大播放按鈕為例，更多資訊請參見設定播放器皮膚。

  <SubTexture name="bigPlayDown" x="2" y="94" width="90" height="90"/>
  <SubTexture name="bigPlayOver" x="94" y="2" width="90" height="90"/>
  <SubTexture name="bigPlayUp" x="2" y="2" width="90" height="90"/>

自訂視頻封面圖

點播上傳的每一個視頻都設定了封面圖片，並提供了多種設定和修改視頻封面的方法。視頻上傳前可以選擇指定的圖片作為封面，或進行視頻截圖並選擇一張作為封面。視頻上傳完成後也可以對封面進行更新。設定封面的方法如下：

• 通過點播控制台設定封面。具體操作，請參見設定視頻封面。

• 通過播放器屬性cover設定封面。

  var player = new Aliplayer({
   "id": "player-con",
   "source":"//player.alicdn.com/video/aliyunm****.mp4",
    "cover":"封面地址",
  },
   function () { } 
  );

視頻截圖

Web播放器SDK 2.1.0以上的版本支援在視頻播放過程中截圖。截取的圖片為image或jpeg類型。截圖功能需要單獨開啟，截圖返回的資料包括當前播放時間、base64和二進位的圖片。

開啟截圖功能

• H5模式下開啟截圖功能

  重要

  FLV視頻在Safari瀏覽器下不支援截圖功能。即使啟用截圖按鈕也不會出現。此外，H5模式下的截圖是通過Canvas實現的，播放網域名稱需添加允許跨域訪問的Header，詳情請參見配置跨域訪問。

  在skinLayout數組裡添加snapshot UI。樣本如下：

      skinLayout:[
      {name: "bigPlayButton", align: "blabs", x: 30, y: 80},
      {
        name: "H5Loading", align: "cc"
      },
      {name: "errorDisplay", align: "tlabs", x: 0, y: 0},
      {name: "infoDisplay"},
      {name:"tooltip", align:"blabs",x: 0, y: 56},
      {name: "thumbnail"},
      {
        name: "controlBar", align: "blabs", x: 0, y: 0,
        children: [
          {name: "progress", align: "blabs", x: 0, y: 44},
          {name: "playButton", align: "tl", x: 15, y: 12},
          {name: "timeDisplay", align: "tl", x: 10, y: 7},
          {name: "fullScreenButton", align: "tr", x: 10, y: 12},
          {name:"subtitle", align:"tr",x:15, y:12},
          {name:"setting", align:"tr",x:15, y:12},
          {name: "volume", align: "tr", x: 15, y: 10},
          {name: "snapshot", align: "tr", x: 5, y: 12},
        ]
      }
    ]

  H5模式下截圖需要設定video的允許匿名跨域訪問屬性。樣本如下：

    extraInfo:{
      crossOrigin:"anonymous"
    }

• Flash模式下開啟截圖功能

  說明

  RTMP流不支援截圖。

  Flash模式下通過snapshot屬性開啟，設定snapshot值為true。

設定截圖的大小和品質

//將截圖的寬度、高度、和品質分別設定為300、200、0.9
//高度、寬度單位為px，品質可取值0-1之間的數字，預設是1
player.setSanpshotProperties(300,200,0.9)

訂閱截圖事件

player.on("snapshoted", function(data) {
     console.log(data.paramData.time);
     console.log(data.paramData.base64);
     console.log(data.paramData.binary);
 });

截圖浮水印

snapshotWatermark:{
    left:"100",
    top:"100",
    text:"測試浮水印",
    font:"italic bold 48px 宋體",
    strokeColor:"red",
    fillColor:'green'
  }

const player = new Aliplayer({
  "id": "player-con",
  "source": "https://player.alicdn.com/video/aliyunmedia.mp4",
  "width": "100%",
}, function (player) {
    console.log("The player is created");
  }
);

let lastTime = 0;
player.on('timeupdate', () => {
  if (!player.tag.seeking) {
    // 更新最近一次的播放位置
    lastTime = player.getCurrentTime();
  }
})

player.on('seeking', () => {
  var delta = player.getCurrentTime() - lastTime;
  if (Math.abs(delta) > 0.01) {
    console.log("Seeking is disabled");
    // 判斷為拖動，自動跳回原來的位置
    // (iOS QQ瀏覽器無效，因為QQ瀏覽器不支援擷取和修改currentTime屬性)
    player.tag.currentTime = lastTime;
  }
});

player.on('ended', function() {
    lastTime = 0;
});

長視頻情境

多碼率HLS網路自適應切換

多碼率指的是source只傳入一個多碼率的地址（a master playlist），然後指定參數isVBR:true。多碼率支援根據網路環境自適應切換視訊清晰度，也支援手動切換。

擷取當前播放地址

多碼率：player._hls.levels[player._hls.currentLevel]

varplayer = newAliplayer({
 "id":"player-con",
 "source":"自適應url地址",
 "isVBR":true,
 },
 function () { } 
);

配置完成的效果圖如下：

外掛字幕

// 切換字幕
var lang = 'zh-Hans/en-US';
player._ccService.switch(lang);
player._ccService.updateUI(lang); // API預設不會更新UI，如有需要請手動調用

// 開啟字幕
var result = player._ccService.open();
player._ccService.updateUI(result.language);

// 關閉字幕
player._ccService.close();
player._ccService.updateUI();

  .prism-cue > div:first-child,
  video::cue {
    font-size: 14px !important;
    color: #000 !important;
    background-color: rgba(255, 255, 255, .8) !important;
  }

多音軌

播放器無需額外設定。效果圖如下：

多語言

Web播放器SDK預設支援中文和英文，並且依賴於瀏覽器的語言設定自動啟用中文或英文資源。除了支援這兩種資源外，還提供自訂語言的能力，支援其他國際語言。另外Web播放器SDK還支援點播服務的多地區，可以支援Vid+playauth播放方式播放東南亞和歐洲的視頻資源。

語言設定屬性

var player = new Aliplayer({
    id: "player-con",
    source: "",
    width: "100%",
    height: "500px",
    autoplay: true,
    language: "en-us",
  }, function (player) {
    console.log("播放器建立成功");
  });

英文版本播放器

var player = new Aliplayer({
 "id": "player-con",
 "source": "",
 "language": "en-us" //zh-cn：中文。en-us：英文。
 },
 function (player) {}
);

自訂語言

當需要支援中文和英文之外的語言時，需要使用自訂語言的功能， 這時可以通過languageTexts屬性指定語言資源屬性，languageTexts使用對象字面量的形式，language屬性的值為key，JSON value值為指定語言翻譯的資源內容。範例程式碼如下：

var player = new Aliplayer({
 "id": "player-con",
 "source": "",
 "language": "CustomLanguage",//自己命名，string類型即可
"languageTexts":{
    "CustomLanguage":{
        "Pasue":"CustomLanguage暫停"
        //其他播放器的欄位，參考https://player.alicdn.com/lang.json？spm=a2c4g.11186623.0.0.5a746515vnwUSi&file=lang.json
            }
        }
    },
    function (player) {} 
);

支援多地區播放

當前點播服務支援下面的地區：上海、法蘭克福、新加坡，Web播放器SDK的Vid+playauth播放和STS播放支援多地區的播放，當知道使用者需要播放哪個地區的視頻時，播放器會調用此地區的點播服務，擷取視頻的播放地址。

• Vid+playauth播放：從playauth裡面解析出Region，擷取對應地區的視頻，因此不用特意再指定播放哪個地區的視頻。

• STS播放：通過播放器提供的Region屬性指定播放哪個地區的視頻，Region預設值為'cn-shanghai'，可選值包含：cn-shanghai、eu-central-1、ap-southeast-1，範例程式碼如下：

  var player = new Aliplayer({
      id: "player-con",
      width: "100%",
      height: "500px",
      autoplay: true,
      language: "en-us",
      vid : '1e067a2831b641db90d570b6480f****',
      accessKeyId: '',//STS臨時AK對的存取金鑰ID，產生STS安全性權杖時返回。
      securityToken: '',//STS安全性權杖，需要調用STS服務的AssumeRole介面產生。
      accessKeySecret: ''//STS臨時AK對的存取金鑰，產生STS安全性權杖時返回。
      region:'eu-central-1',//法蘭克福地區
    }, function (player) {
      console.log("播放器建立成功");
    });

播放H.265/H.266編碼協議視頻流

使用前須知

• Web播放器SDK從2.14.0版本開始支援播放H.265編碼協議的視頻流，從2.20.2版本開始支援播放H.266編碼協議的視頻流。如需使用此功能，您需要先申請License授權併購買播放器SDK下的Web播放H.265增值服務，詳情請參見管理License。

• Web播放器SDK中H.265/H.266編碼協議的音視頻支援格式，請參見協議支援。

• 使用H.265/H.266編碼協議視頻流播放功能前，請先瞭解對播放器的環境要求以及與瀏覽器的相容性等資訊，具體如下：

  專案	說明
  環境要求	播放器會分段以AJAX的方式請求視頻資源，因此需要視頻服務支援以下特性： 支援 range 請求。 支援OPTIONS請求（Firefox等瀏覽器在發起帶range header的ajax請求時，會先發起一個OPTIONS請求）。
  相容性	H.265 iOS 11及以上版本的裝置原生支援播放H.265視頻。 部分Android裝置的瀏覽器已支援硬解碼H.265視頻，例如系統內建瀏覽器、微信瀏覽器、UC瀏覽器、QQ 瀏覽器等。 對於Chrome、Edge、Firefox等瀏覽器軟解碼的情境，其相容性取決於瀏覽器對WebAssembly API的支援，支援情況請參見WebAssembly。其中，Chrome瀏覽器（以及Chromium核心瀏覽器）由於歷史版本的WebAssembly效能問題，需要為74及以上版本。 H.266 目前尚未有瀏覽器原生支援H.266播放，所以播放器統一使用軟解方案，對瀏覽器WebAssembly API的相容性有一定要求，支援情況請參見WebAssembly。其中，Chrome瀏覽器（以及Chromium核心瀏覽器）由於歷史版本的WebAssembly效能問題，需要為74及以上版本。 iOS 16.4以下、Android大部分中低端機型無法軟解H.266。
  軟解碼效能	H.265 案頭端瀏覽器多線程最高支援2K/30fps的視頻，單線程最高支援1080/30fps的視頻。 移動端瀏覽器單線程最高支援720/30fps的視頻。移動端軟解碼效能主要取決於晶片效能，經測試，以下晶片可以單線程流暢軟解碼720/30fps的視頻。 驍龍855及以上 麒麟820及以上 天璣800及以上 H.266 案頭端瀏覽器多線程最高支援1080/30fps的視頻，單線程最高支援720/30fps的視頻。 移動端瀏覽器單線程最高支援720/30fps的視頻。移動端軟解碼效能主要取決於晶片效能，經測試，以下晶片可以單線程流暢軟解碼720/30fps的視頻。 驍龍855及以上 麒麟820及以上

快速接入

<div class="prism-player" id="player-con"></div>
<script>
var options = {
  id: "player-con",
  source: "//demo.example.com/video/test/h265/test_480p_mp4_h265.mp4",
  enableH265: true,
  license: {
    domain: "example.com",
    key: "example-key"
  }
}
var player = new Aliplayer(options);
</script>

<div class="prism-player" id="player-con"></div>
<script>
var options = {
  id: "player-con",
  source: "//demo.example.com/video/test/h266/test_480p_mp4_h266.mp4",
  enableH266: true,
  license: {
    domain: "example.com",
    key: "example-key"
  }
}
var player = new Aliplayer(options);
</script>

{
  //...其他參數
  source: JSON.stringify({
      FD: '//h265_fd.mp4',
      HD: '//h265_hd.mp4'
    }),
}

解碼方案選擇邏輯

降級播放

player.on('error', (e) => {
        var code = String(e.paramData.error_code);
    if (['4300', '4301', '4302', '4303', '4304'].indexOf(code) > -1) {
      // 遇到 API 不支援、或解碼錯誤，請提示使用者或降級
    }
});

player.on('h265DecoderOverload', (e) => {
    var data = e.paramData;
    // data.decodedFps - 當前軟解的每秒解碼幀數
    // data.fps - 當前視訊框架率
    // data.playbackRate - 當前播放速率
    // 當 decodedFps < (fps * playbackRate) 超過5秒時，會觸發此事件，此時可能播放卡頓，應考慮提示使用者或降級
});
                            

  var player;

  // 建立播放器
  function createPlayer(_options) {
    player && player.dispose();
    player = new Aliplayer(_options);
    player.on('error', (e) => {
      var code = String(e.paramData.error_code);
      if (['4300', '4301', '4302', '4303', '4304'].indexOf(code) > -1) {
        fallbackTo264(_options)
      }
    });
    player.on('h265DecoderOverload', () => {
      // 建議觸發2次之後再降級，因為觸發1次可能由於解碼波動導致
      fallbackTo264(_options)
    })
    return player;
  }

  // 降級
  function fallbackTo264(_options) {
      // 指定source為降級的H.264視頻地址
      _options.source = '//h264.mp4';
      // 關閉enableH265，跳過codec嗅探
      _options.enableH265 = false;
      createPlayer(_options);
  }

  // 初始化
  var options = {
    id: "player-con",
    source: "//h265.mp4",
    enableH265: true
  }
  createPlayer(options)

player.on('error', (e) => {
        var code = String(e.paramData.error_code);
    if (['4300', '4301', '4302', '4303', '4304'].indexOf(code) > -1) {
      // 遇到 API 不支援、或解碼錯誤，請提示使用者或降級
    }
});          

  var player;

  // 建立播放器
  function createPlayer(_options) {
    player && player.dispose();
    player = new Aliplayer(_options);
    player.on('error', (e) => {
      var code = String(e.paramData.error_code);
      if (['4300', '4301', '4302', '4303', '4304'].indexOf(code) > -1) {
        fallbackTo264(_options)
      }
    });
    return player;
  }

  // 降級
  function fallbackTo264(_options) {
      // 指定source為降級的H.264視頻地址
      _options.source = '//h264.mp4';
      // 關閉enableH266，跳過codec嗅探
      _options.enableH266 = false;
      createPlayer(_options);
  }

  // 初始化
  var options = {
    id: "player-con",
    source: "//h266.mp4",
    enableH266: true
  }
  createPlayer(options)

API

介面說明中列出了Web播放器SDK所支援的所有屬性、方法和事件，並對其作出了詳細的解釋和樣本說明。其中，H.265/H.266僅支援部分屬性、方法和事件的設定，具體支援情況如下所示：

• 支援的屬性

  source、autoplay、rePlay、preload、cover、width、height、skinLayout、waitingTimeout、vodRetry、keyShortCuts、keyFastForwardStep

• 支援的方法

  play、pause、replay、seek、dispose、getCurrentTime、getDuration、getVolume、setVolume、loadByUrl、setPlayerSize、setSpeed、setSanpshotProperties、fullscreenService、getStatus、setRotate、getRotate、setImage、setCover、setProgressMarkers、setPreviewTime、getPreviewTime、isPreview

• 支援的事件

  ready、play、pause、canplay、playing、ended、hideBar、showBar、waiting、timeupdate、snapshoted、requestFullScreen、cancelFullScreen、error、startSeek、completeSeek、h265PlayInfo、h266PlayInfo

  說明

  其中，h265PlayInfo和h266PlayInfo事件會通知當前H.265或H.266播放所使用的方案（renderType），和實際啟用的特性（simd/wasmThreads）。

錯誤碼

H.265/H.266播放相關錯誤碼如下，其他錯誤碼請參見介面說明。

搭建多線程環境

搭建樣本

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

H5模式直播時移

• 開通直播時移

  • 直播時移功能首先需要到阿里雲直播服務裡開通，更多資訊，請參見直播時移。

  • 播放器開啟時移功能時需要設定如下屬性：

    名稱	說明
    isLive	設定值為：true。
    liveTimeShiftUrl	時移資訊查詢URL。
    liveStartTime	直播開始時間。
    liveOverTime	直播結束時間。
    liveShiftSource	直播時移hls地址。 說明 只有在source為flv直播流是需要設定。
    liveShiftMinOffset	時移切片錄製需要時間，seek時間過於接近直播時間會因為切片未產生而 404，預設會有一個最小seek時間，可以通過此參數配置，單位是秒，預設值30（10秒一個切片，保證至少有3個切片）。

• 直播時移UI

  直播時移的UI構成主要是可時移地區的進度條，時間顯示：

  說明

  時間地區從左至右分別為：當前播放時間、直播結束時間、當前直播時間。

• 調整直播結束時間

  在播放過程中可以通過調用liveShiftSerivce.setLiveTimeRange方法調整直播開始/結束時間時，UI會做相應的變化。樣本如下：

  player.liveShiftSerivce.setLiveTimeRange(“”,’2018/01/04 20:00:00’)

• FLV直播和HLS時移切換

  由於延時的原因，請在直播流用flv格式，時移流用hls格式。

  Web播放器SDK支援模式：

  • source屬性指定flv直播地址。

  • liveShiftSource屬性指定hls的地址。

  樣本如下：

  {
   source:'http://localhost/live****/example.flv',
   liveShiftSource:'http://localhost/live****/example.m3u8',
  }

自訂部署Web播放器

Web播放器SDK的JS、CSS等資源預設存放在阿里雲CDN上，如需將其部署到您自己的伺服器，可參考如下方法實現。

1. 下載播放器資源。

   除了aliplayer-min.js和aliplayer-min.css兩個主檔案，Web播放器SDK還會動態引用其他的資源檔，因此您首先需要擷取完整的資源檔夾。

   下載地址：Web播放器自訂部署資源套件.tar.gz

2. 解壓並部署。

   解壓上一步下載的資源套件，將檔案夾中的所有子檔案部署到您的伺服器（不包含解壓後的父資料夾本身），注意請不要調整內部檔案的層級。

3. 使用自訂路徑初始化播放器。

   樣本說明：假設您自訂部署後的引用地址為下。

   https://player.alicdn.com/assets/skins/default/aliplayer-min.css
   https://player.alicdn.com/assets/aliplayer-min.js

   請參考下述步驟進行初始化。

   1. 在頁面頂部引用您的JS、CSS地址。

      <head>
        <link rel="stylesheet" href="https://player.alicdn.com/assets/skins/default/aliplayer-min.css" />
        <script charset="utf-8" type="text/javascript" src="https://player.alicdn.com/assets/aliplayer-min.js"></script>
      </head>

   2. 初始化播放器，並指定assetPrefix參數。

      assetPrefix參數為您自訂部署地址的首碼。如果播放器要播放HLS視頻，就會動態去引用https://player.alicdn.com/assets/hls/aliplayer-hls2-min.js檔案，請確保將檔案放置到了正確的地址。

      new Aliplayer({
        assetPrefix: 'https://player.alicdn.com/assets'
        // ... 其它參數
      })