进阶功能

播放控制

自动播放

• 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属性。

  • 视频点播H5模式默认配置

    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}
          ]
        }
      ]

  • 视频点播Flash模式默认配置

    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'
        // ... 其它参数
      })