西瓜播放器 HTML5 video video.js 播放器 HTML5播放器 mp4 hls hls.js flv flv.js dash dash.js 无缝切换

配置

播放器在实例化的时候提供配置选项,开发者可以根据自己的需求进行选择性地配置。 播放器容器和视频资源地址是生成播放器示例必须提供的内容。

必选配置

选择器

播放器实例化的时候需要明确DOM的占位,video将要输出到该DOM下,播放器的尺寸与占位DOM一致。

new Player({
  id:'mse'
})

播放器容器id也可以用容器的 DOM 实例来代替。

new Player({
  el:document.querySelector('#mse'),
})

视频源

播放器支持单个或多个视频源,建议使用多个源视频,这样当第一个视频出现问题的时候会自动启用第二个视频源,以此类推。

  1. 单个视频源
new Player({
  el:document.querySelector('#mse'),
  url: '//abc.com/**/*.mp4'
});
  1. 多个视频源
new Player({
  el:document.querySelector('#mse'),
  url: [{src:'/mp4/',type:"video/mp4"},{src:'/mp5/',type:'video/mp4'}]
});

注意

选择器和视频源是播放器必须提供的配置项,缺一不可。

可选配置

尺寸

开发者可以为播放器设置尺寸大小。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  width: 600,
  height: 337.5
});
  • 配置项:width, height
  • 默认值:600, 337.5

流式布局

设置为流式布局,可使播放器宽度跟随父元素的宽度大小变化,且高度按照配置项中的高度和宽度的比例来变化(播放器宽高未设置时按照内部默认值来计算)。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  fluid: true
});
  • 配置项:fluid
  • 默认值:false

音量

开发者可以为播放器预设音量大小。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  volume: 0.6
});
  • 配置项:volume
  • 默认值:0.6
  • 参考值:0 ~ 1

自动播放

目前大多数浏览器厂商不建议播放器自动播放视频,开发者对此有特殊需求时可通过该配置项打开。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  autoplay: true
});
  • 配置项:autoplay
  • 默认值:false
  • 参考值:true | false

注意

根据浏览器规则,非静音状态下播放器的 autoplay 行为不一定会发生 参考。如果希望通过设置静音来保证 autoplay 确定发生,可在设置 autoplay: true 的同时配置 autoplayMuted : true

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  autoplay: true,
  autoplayMuted: true
});
  • 配置项:autoplayMuted
  • 默认值:false
  • 参考值:true | false

注意

在手机上 autoplay 部分机型无效。

封面图

封面图是当播放器初始化后在用户点击播放按钮前显示的图像。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  poster: '//abc.com/**/*.png'
});
  • 配置项:poster
  • 默认值:''
  • 参考值:'https://i.ytimg.com/vi/lK2ZbbQSHww/hqdefault.jpg'

倍速播放

播放器支持设置视频的当前播放速度。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  playbackRate: [0.5, 0.75, 1, 1.5, 2],
});
  • 配置项:playbackRate
  • 默认值:''
  • 参考值:[0.5, 0.75, 1, 1.5, 2]

视频旋转

用户点击旋转按钮后,视频会顺时针旋转90度。

let player = new Player({
    el:document.querySelector('#mse'),
 	url: 'video_url',
    rotate: true //设置rotate控件显示
});
player.on('rotate',function(deg) {
    console.log(deg);// 旋转时会触发rotate事件,角度有四个值90,180,270,0
})
  • 配置项:rotate
  • 默认值:false
  • 参考值:true

预览

用户将鼠标指针移动到进度条某处时进度条上方会出现该时刻的视频预览图,服务端提供sprite图(由多张视频预览小图组成)作为预览图资源。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  thumbnail: {
      pic_num: 44,
      width: 160,
      height: 90,
      col: 10,
      row: 10,
      urls: ['./xgplayer-demo-thumbnail-1.jpg','./xgplayer-demo-thumbnail-2.jpg'],
  },
});
配置项含义
pic_num该视频资源所需预览小图数量
width预览小图宽度
height预览小图高度
colsprite图每列的预览小图数量
rowsprite图每行的预览小图数量
urlssprite图的源地址数组

弹幕

用户观看视频时弹出的评论性字幕。与其它播放器弹幕效果不同的是,西瓜播放器通过算法设计实现了多条弹幕之间的不重叠和不碰撞,具体参考 前端算法之弹幕设计

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  bullet: {
      switch: 'on', //开启'on',关闭'off'
      url: './danmu.json',
      method: 'get'
  },
});
配置项含义
switch开启弹幕开关
url弹幕数据文件或接口地址
method获取弹幕数据方法

弹幕数据定义示例如下,其中danmaku_id为每条弹幕的唯一ID,text是文字内容,duration是弹幕在播放器可见区域内运动的总时长(单位:秒),text_color是弹幕文字颜色,text_scale是文字大小,offset_time是弹幕出现的时刻(单位:毫秒)。

{
  "data": [
     {"danmaku_id": "1", "text": "这是弹幕", "duration": 12, "text_color": "0x00f", "text_scale": 1,"offset_time": 1000},
     {"danmaku_id": "2", "text": "1234567890", "duration": 15, "text_color": "0xf00", "text_scale": 2,"offset_time": 2000},
     {"danmaku_id": "3", "text": "这是弹幕", "duration": 8, "text_color": "0x0f0", "text_scale": 1,"offset_time": 3000},
     {"danmaku_id": "4", "text": "这是弹幕", "duration": 7, "text_color": "0x00f", "text_scale": 3,"offset_time": 4000},
     {"danmaku_id": "5", "text": "1234567890", "duration": 10, "text_color": "0x00f", "text_scale": 1,"offset_time": 5000},
     {"danmaku_id": "6", "text": "西瓜播放器", "duration": 9, "text_color": "0x00f", "text_scale": 1,"offset_time": 6000},
     {"danmaku_id": "7", "text": "这是弹幕", "duration": 22, "text_color": "0x00f", "text_scale": 1,"offset_time": 7000},
     {"danmaku_id": "8", "text": "1234567890", "duration": 10, "text_color": "0x00f", "text_scale": 2,"offset_time": 8000},
     {"danmaku_id": "9", "text": "西瓜播放器", "duration": 20, "text_color": "0xf00", "text_scale": 1,"offset_time": 9000},
     {"danmaku_id": "10", "text": "这是弹幕", "duration": 12, "text_color": "0x0f0", "text_scale": 1,"offset_time": 10000}
  ]
}

加载页

西瓜播放器的视频加载页面默认使用“西瓜视频”Logo和红色主题,开发者可对加载页面样式(Logo、背景和加载特效)进行替换配置。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  enterLogo:{ //视频加载页logo
    url: '/logo.png',
    width: 231,
    height: 42
  },
  enterBg:{ //视频加载页背景
    color: 'rgba(0,0,0,0.87)'
  },
  enterTips:{ //视频加载页加载特效
    background: 'linear-gradient(to right, rgba(0,0,0,0.87), #3D96FD, rgba(86,195,248), #3D96FD, rgba(0,0,0,0.87))'
  }
});

控件样式

播放器会陆续提供一些接口帮助开发者对部分控件的样式进行直接替换,目前已支持对画面中央按钮(播放、暂停、重播)的svg path进行配置。可以将相关svg信息写在外部文件中并提供该文件地址,也可直接把相关svg信息写在配置项中。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  controlStyle: './controlStyle.json'
});
{
  "centerBtn": {
    "pausePath": "path1",
    "playPath": "path2",
    "replayPath": "path3"
  }
}

或者

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  centerBtn: { //画面中央按钮(播放、暂停、重播)
    pausePath: 'path1',
    playPath: 'path2',
    replayPath: 'path3'
  }
});

除了svg,也支持使用图片显示画面中央按钮。

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  centerBtn: {
    type: 'img',
    url: {
      play: 'play.png',
      pause: 'pause.png',
      replay: 'replay.png'
    },
    width: '128px',
    height: '128px'
  }
});

外挂字幕

播放器支持加载多条WebVTT格式的外挂字幕,并可在播放过程中切换或关闭、打开字幕。外挂字幕格式可参考 WebVTT MDN

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  textTrack: [
    {
      src: "./textTrack-1.vtt",
      kind: "subtitles",
      label: "字幕1",
      srclang: "zh",
      default: true
    },
    {
      src: "./textTrack-2.vtt",
      kind: "subtitles",
      label: "字幕2",
      srclang: "en",
      default: false
    }
  ],
  textTrackStyle: {
    "background-color": "#ff0",
    "color": "#000",
    "font-size": "26px",
  }
});
  • 配置项:textTrack
  • 含义:多条字幕信息组成的数组
  • 默认值:[]
参数意义可选值
src字幕文件的URL,必需
kind字幕类型,可选参考
label字幕标签,必需
srclang字幕文本语言,可选zh, en...
default默认字幕true, false
  • 配置项:textTrackStyle
  • 含义:字幕相关CSS样式配置
  • 默认值:{}

画中画

画中画功能支持用户在浏览网页其它内容时继续以小窗的形式观看视频,同时可以拖拽改变小窗在页面中的fix位置。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  pip: true
});
  • 配置项:pip
  • 默认值:false
  • 参考值:true | false

预览本地视频

支持用户在线预览本地视频。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  preview: {
    uploadEl: uploadDom
  }
});
  • 配置项:uploadEl
  • 含义:Dom元素,用于放置上传视频文件的相关控件

键盘快捷键

可通过该配置项开启键盘快捷键:按 → 键快进10秒, 按 ← 键后退10秒,按 ↑ 键调高音量,按 ↓ 键调低音量,按 space 键切换播放/暂停状态。

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  keyShortcut: 'on'
});
  • 配置项:keyShortcut
  • 默认值:'off'
  • 参考值:'on' | 'off'

关闭内置控件

xgplayer播放器对于原生video的基本功能进行了优化和封装,如果不想使用xgplayer内置控件,可以通过ignores配置项关闭,使用自己开发的相同功能插件进行替换。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  ignores: ['replay']
});
  • 配置项:ignores
  • 默认值:[]
  • 参考值: ['time', 'definition', 'error', 'fullscreen', 'i18n', 'loading', 'mobile', 'pc', 'play', 'poster', 'progress', 'replay', 'start', 'volume']
参数意义
time当前播放时间/视频时长
definition清晰度切换
error报错提示
fullscreen全屏切换
i18n多语种切换
loading加载提示
mobile手机交互
pc桌面视频交互
play控制条的播放、暂停按钮
poster封面图插件
progress视频进度条
replay重播交互与提示
start初始化播放按钮
volume音量控制

关闭控制条

播放器控制条由播放/暂停、定位、音量、全屏切换等元素组成,开发者可通过controls:false 将其全部关闭。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  controls: false
});
  • 配置项:controls
  • 默认值:true
  • 参考值 true|false

控制条选项配置

选择关闭部分控制条选项可以通过配置controlsList选项实现。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  controlsList: ['nodownload']
});
  • 配置项:controlsList
  • 默认值:['nodownload'],
  • 参考值:['nodownload','nofullscreen','noremoteplayback']

注意

只对原生video有效,对自定义UI请使用ignores选项

播放镜像

开启airplay选项可以将iOS设备上的视频传送到支持airplay的设备上进行播放,具体 参考

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  airplay: false
});
  • 配置项:airplay
  • 默认值:''
  • 参考值:true | false

功能插件开关配置

通过播放器的配置可以实现插件动态开启和关闭,只要在功能插件读取该配置即可。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  pluginRule: ()=>{return true}
});
  • 配置项:pluginRule
  • 默认值:''
  • 参考值:function(){return true|false}

比如:xgplayer-mp4插件想做流量测试,一半用户开启功能,一半用户不开启,就可以通过如下代码实现:

new Player({
  pluginRule:function(){return Math.random()>0.5}
})

多语种

<html lang='zh-cn'></html>

播放器会优先获取html的lang配置,如果没有配置就会直接读取navigator.language,若还取不到则默认使用zh-cn;播放器内置了汉语和英语两种语言,如果不够用,可以自定义。方法如下:

  1. 定义语言
// language.js
export default ({
  'jp':{
    HAVE_NOTHING: 'There is no information on whether audio/video is ready',
    HAVE_METADATA: 'audio/video metadata is ready ',
    HAVE_CURRENT_DATA: 'Data about the current play location is available, but there is not enough data to play the next frame/millisecond',
    HAVE_FUTURE_DATA: 'Current and at least one frame of data is available',
    HAVE_ENOUGH_DATA: 'The available data is sufficient to start playing',
    NETWORK_EMPTY: 'Audio/video has not been initialized',
    NETWORK_IDLE: 'Audio/video is active and has been selected for resources, but no network is used',
    NETWORK_LOADING: 'The browser is downloading the data',
    NETWORK_NO_SOURCE: 'No audio/video source was found',
    MEDIA_ERR_ABORTED: 'The fetch process is aborted by the user',
    MEDIA_ERR_NETWORK: 'An error occurred while downloading',
    MEDIA_ERR_DECODE: 'An error occurred while decoding',
    MEDIA_ERR_SRC_NOT_SUPPORTED: 'Audio/video is not supported',
    REPLAY: 'Replay',
    ERROR: 'Error,please click to refresh',
  },
  'en':{
    HAVE_NOTHING: 'There is no information on whether audio/video is ready',
    HAVE_METADATA: 'audio/video metadata is ready ',
    HAVE_CURRENT_DATA: 'Data about the current play location is available, but there is not enough data to play the next frame/millisecond',
    HAVE_FUTURE_DATA: 'Current and at least one frame of data is available',
    HAVE_ENOUGH_DATA: 'The available data is sufficient to start playing',
    NETWORK_EMPTY: 'Audio/video has not been initialized',
    NETWORK_IDLE: 'Audio/video is active and has been selected for resources, but no network is used',
    NETWORK_LOADING: 'The browser is downloading the data',
    NETWORK_NO_SOURCE: 'No audio/video source was found',
    MEDIA_ERR_ABORTED: 'The fetch process is aborted by the user',
    MEDIA_ERR_NETWORK: 'An error occurred while downloading',
    MEDIA_ERR_DECODE: 'An error occurred while decoding',
    MEDIA_ERR_SRC_NOT_SUPPORTED: 'Audio/video is not supported',
    REPLAY: 'Replay',
    ERROR: 'Error,please click to refresh',
  }
})
  1. 引用语言
import Player from 'xgplayer';
import Language from './language';

let player=new Player({
  id:'mse',
  url: 'video_url'
});

player.lang=Language;

注意

如果有多个语言,使用循环给player.lang赋值就好,每次赋值不会覆盖而是增加。

清晰度切换配置

清晰度插件配置虽然属于内置控件但是比较特殊,不采用传统的配置项而是采用事件驱动的方式。因为我们的清晰度设计更加抽象,不仅支持明确的视频地址列表,还要支持虚拟地址列表,所以采用事件驱动。

示例

let player = new Player({
  el:document.querySelector('#mse'),
  url: 'video_url'
});

player.emit('resourceReady', [{name: '高清', url: 'url1'}, {name: '超清', url: 'url2'}]);

注意

如果不想使用清晰度切换功能,不激活 resourceReady 事件就可以;如果视频地址列表只有一个地址,清晰度切换控件也会自动关闭。

白名单

手机上video表现各异,自定义UI会有意想不到的情况发生,为了安全起见,播放器在手机上会关掉自定义UI功能,开发者可以通过白名单的方式开启此项功能。whitelist是数组,数组的每项值可以是字符串、正则表达式、函数(箭头函数)均可,字符串和正则表达式都是对navigator.userAgent来判断,函数不限。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  whitelist: ['iPhone OS 9'],
  // whitelist: [(ua)=>{ return /iPhone OS 9/gi.test(ua); }],
  // whitelist: [/iPhone OS 9/gi]
});
  • 配置项:whitelist
  • 默认值:[]
  • 参考值:[字符串,正则,函数]

内联模式

该选项在手机观看时,开启ios和微信的内联模式,配置项:playsinline 知识 参考

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  playsinline: false
});
  • 配置项:playsinline
  • 默认值:false
  • 参考值:true | false

手机调试

要使用该功能,请先在开发者电脑安装 weinre,命令: npm -g install weinre。调试手机的时候,debug选项配置好,然后在命令行开启服务,具体命令页面中会提示。关于weinre知识 参考

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  debug: {
    host:'10.2.106.238',
    port:9090
  }
});
  • 配置项:debug
  • 默认值:{host:'127.0.0.1',port:9090}
  • 参考值:{host:${开发者电脑ip},port:9090}

微信同层播放

同层播放 参考

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  'x5-video-player-type': 'h5'
});
  • 配置项:x5-video-player-type
  • 默认值:''
  • 参考值:'h5'

微信全屏播放

具体 参考

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  'x5-video-player-fullscreen': false
});
  • 配置项:x5-video-player-fullscreen
  • 默认值:''
  • 参考值:true | false

微信横竖屏控制

具体 参考

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  'x5-video-orientation': 'portraint'
});
  • 配置项:x5-video-orientation

  • 默认值:''

  • 参考值:'landscape' | 'portraint'

    • 'landscape' 横屏
    • 'portraint' 竖屏

自定义配置

如果自定义插件,想通过播放器初始化的时候传递配置参数进来,可以直接定义。

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  customConfig:{
    //
  }
});

在插件内部通过player.config.customConfig拿到配置。其中 player 是插件定义函数都具备的当前播放器实例,customConfig是可以随便定义的,示例只是举例。