Configuration

xgplayer provide configuration options when instantiated, and you can configure them selectively according to your own requirements. The player container and the video resource address are the content must provide when using the player.

Required Configuration

Selector

During instantiation, you should provide the DOM container of the player and the video will be shown in the DOM. The size of the player will be consistent with the DOM automatically.

new Player({
  id:'mse'
})

The player container id can also be replaced by the DOM instantiation.

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

Video Source

new Player({
  el:document.querySelector('#mse'),
  url: '//abc.com/**/*.mp4'
});

Note

The selector and video source are the indispensable configuration options.

Optional Configuration

Size

You can set the size for the player.

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  width: 600,
  height: 337.5
});

option: width, height
default value: 600, 337.5

Fluid

The fluid layout allows the player's width varies to follow the width of the parent element's change, and the height varies according to the height and width proportion of the configuration item (the player's width and height is the internal default value when width and height are not set).

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

option: fluid
default: false
reference: true | false

Volume

You can set the initial volume level for the player.

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

option: volume
default value: 0.6
reference: 0~1

Autoplay

Most browser manufacturers disallow autoplay, and you can set videos to autoplay with this option when needs.

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

option: autoplay
default value: false
reference: true | false

Note

Most browsers allow autoplay with muted. In order to ensure autoplay a success, xgplayer will ignore the volume config and autoplay with muted when you config 'autoplay: true'.

Note

In some phones the autoplay are invalid.

Poster

The poster is recommended when you want to preload the video at startup while giving the player a custom look and feel.

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  poster: '//abc.com/**/*.png'
});

option: poster
default value: ''
reference: 'https://i.ytimg.com/vi/lK2ZbbQSHww/hqdefault.jpg'

PlaybackRate

You can set the playback rate for the player.

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  playbackRate: [0.5, 0.75, 1, 1.5, 2],
});

option: playbackRate
default value: ''
reference: [0.5, 0.75, 1, 1.5, 2]

VideoRotate

When you click the rotate button, the video will rotate 90 degrees.

let player = new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
    rotate: {   //video rotate config
        innerRotate: true, //only ratate inner video
        clockwise: false // rotate direction is clockwise or anticlockwise
    }
});
// The rotate event is fired when rotated, and the angle has four values of 90, 180, 270, 0.
player.on('rotate',function(deg) {
    console.log(deg);
})

default value：{ innerRotate: false, clockwise: false }

Note

when innerRotate is false, the width and height of the player need to match the resolution of the video.

Thumbnail

When hovering on the progress-bar the preview picture of this point will appear above the bar. For the thumbnail source the server should provide the sprite pictures which consist of several small preview pictures.

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'],
  },
});

Item	Meaning
pic_num	The number of this video's small preview pictures
width	The width of the small preview picture
height	The height of the small preview picture
col	The small picture number in every column of the sprite picture
row	The small picture number in every row of the sprite picture
urls	The source array of the sprite pictures

PlayNext

The video jump plays the next episode and a list of video resources is required.

let player = new Player({
    el:document.querySelector('#mse'),
    url: 'video_url',
    playNextBtn: {
      urlList: [
        'url1',
        'url2',
        'url3'
      ],
    }
});

Download

Video download control, click to download the video.

let player = new Player({
    download: true
});

option：download
default value：false
reference：true

Danmu

The pop-up critical captions of the playing video. Unlike the other video players, xgplayer can show the bullet subtitles without overlap and impact.

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  danmu: {
    comments: [
      {
        duration: 15000,
        id: '1',
        start: 3000,
        prior: true,
        color: true,
        txt: '长弹幕长弹幕长弹幕长弹幕长弹幕长弹幕长弹幕长弹幕长弹幕长弹幕',
        style: {
          color: '#ff9500',
          fontSize: '20px',
          border: 'solid 1px #ff9500',
          borderRadius: '50px',
          padding: '5px 11px',
          backgroundColor: 'rgba(255, 255, 255, 0.1)'
        },
        mode: 'top'
        // el: DOM // A customizable DOM element as Danmu, which will ignore txt and style.
      }
    ],
    area: { // Danmu display area
      start: 0, // The ratio of the top of the area to the height of the player at the top of the player
      end: 1 // The ratio of the bottom of the area to the height of the player at the top of the player
    },
    closeDefaultBtn: true, // By default, the switch provided by the xgplayer is used.
    defaultOff: true // Default initialization Danmu
  }
});

Item	Meaning
comments	the bullet subtitle array
area	the bullet subtitle's display area
closeDefaultBtn	the switch provided by the xgplayer defaultly
defaultOff	initialize the bullet subtitle defaultly

The bullet subtitle control related API.

player.danmu.start() //to init and play danmu
player.danmu.pause() //pause danmu's playing
player.danmu.play() //continute to play danmu
player.danmu.stop() //stop play and danmu disappear
player.danmu.sendComment({  //send danmu
    duration: 15000, // ms
    id: 'id',
    start: 3000,
    txt: 'danmu content',
    style: {
        color: '#ff9500',
        fontSize: '20px',
        border: 'solid 1px #ff9500',
        borderRadius: '50px',
        padding: '5px 11px',
        backgroundColor: 'rgba(255, 255, 255, 0.1)'
    }
})
player.danmu.setCommentDuration (id, duration)
player.danmu.setAllDuration (mode, duration)
player.danmu.setCommentID (oldID, newID)
player.danmu.hide (mode) //scroll | top | bottom | color
player.danmu.show (mode) //scroll | top | bottom | color

Panel

Integrate the control functions of the Danmu, opacity, danmu speed, font size, etc. into the control panel.

notice

The control panel is a sub-configuration in the danmu configuration that needs to be turned on or off in the danmu configuration.

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  danmu: {
    panel: true,
    comments: [],
    area: {  
      start: 0,
      end: 1
    },
    closeDefaultBtn: true,
    defaultOff: true
  }
});

option：panel
default value：false
reference：true | false

The control panel related functions:

Item	Meaning
hide mode	scroll, top, bottom, color
display area	player viewable area from top to bottom. 0, 1/4, 1/2, 3/4, fullscreen
opacity	danmu's opacity
dnamu speed	15000ms, 10000ms, 5000ms
font size	10px, 20px, 30px

Loading page

The Xgplayer's video loading page uses the Xgplayer logo and red theme by default,and developers can replace the loading page style(logo,background adn loading effects).

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  enterLogo:{ // video loading page logo
    url: '/logo.png',
    width: 231,
    height: 42
  },
  enterBg:{ // video loading page background
    color: 'rgba(0,0,0,0.87)'
  },
  enterTips:{ // video loading page effects
    background: 'linear-gradient(to right, rgba(0,0,0,0.87), #3D96FD, rgba(86,195,248), #3D96FD, rgba(0,0,0,0.87))'
  }
});

Controls style

Xgplayer will provide some interfaces for helping developers replace the controls style. Now replacing the svg path of center buttons(Play, Pause, Replay) and changing the logo page(the logo, backgound and loading animation) which shown in loading the video are available.

new Player({
  el:document.querySelector('#mse'),
  url: '/mp4/',
  centerBtn: {
    pausePath: 'M576,363L810,512L576,661zM342,214L576,363L576,661L342,810z',
    playPath: 'M598,214h170v596h-170v-596zM256 810v-596h170v596h-170z',
    replayPath: 'M8.22708362,13.8757234 L11.2677371,12.6472196 C11.7798067,12.4403301 12.3626381,12.6877273 12.5695276,13.1997969 L12.9441342,14.1269807 C13.1510237,14.6390502 12.9036264,15.2218816 12.3915569,15.4287712 L6.8284538,17.6764107 L5.90126995,18.0510173 C5.38920044,18.2579068 4.80636901,18.0105096 4.5994795,17.49844 L1.97723335,11.0081531 C1.77034384,10.4960836 2.0177411,9.91325213 2.52981061,9.70636262 L3.45699446,9.33175602 C3.96906396,9.12486652 4.5518954,9.37226378 4.75878491,9.88433329 L5.67885163,12.1615783 C7.99551726,6.6766934 13.3983951,3 19.5,3 C27.7842712,3 34.5,9.71572875 34.5,18 C34.5,26.2842712 27.7842712,33 19.5,33 C15.4573596,33 11.6658607,31.3912946 8.87004692,28.5831991 C8.28554571,27.9961303 8.28762719,27.0463851 8.87469603,26.4618839 C9.46176488,25.8773827 10.4115101,25.8794641 10.9960113,26.466533 C13.2344327,28.7147875 16.263503,30 19.5,30 C26.127417,30 31.5,24.627417 31.5,18 C31.5,11.372583 26.127417,6 19.5,6 C14.4183772,6 9.94214483,9.18783811 8.22708362,13.8757234 Z'
  },
  enterLogo:{
    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))'
  }
});

TextTrack

Xgplayer supports textTracks with WebVTT format files, and you can switch, close or open the textTrack in playing video. WebVTT format see WebVTT MDN.

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  textTrack: [
    {
      src: "./textTrack-1.vtt",
      kind: "subtitles",
      label: "textTrack1",
      srclang: "zh",
      default: true
    },
    {
      src: "./textTrack-2.vtt",
      kind: "subtitles",
      label: "textTrack2",
      srclang: "en",
      default: false
    }
  ],
  textTrackStyle: {
    "background-color": "#ff0",
    "color": "#000",
    "font-size": "26px",
  }
});

option: textTrack
meaning: textTracks info array
default: []

Param	sence	optional value
src	textTrack file URL, essential
kind	textTrack type, optional	See
label	textTrack label, essential
srclang	textTrack text language, optional	zh, en...
default	default textTrack	true, false

option: textTrackStyle
meaning: textTrack CSS style config
default: {}

Picture-in-Picture

Picture-in-Picture supports that users watch videos with the small window when they want to read the other content of the page. And they can drag the small window to change the fix position in the page.

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

option: pip
default value: false
reference: true | false

cssFullscreen

Style full screen function does not hide the current browser's tab bar, navigation bar, just full screen inside the current page.

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

option: cssFullscreen
default value: false
reference: true | false

screenShot

The screenshot function allows the user to take a screenshot of the current video playback window. The screenshot size is the size of the current video playback window. The screenshot defaults to .png format.

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

option: screenShot
default value: false
reference: true | false

Preview local videos

Support users to preview local videos online.

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  preview: {
    uploadEl: uploadDom
  }
});

option: uploadEl
meaning: DOM element for placing related controls for uploading video files.

Progress bar special point marker

Support for marking important places on the progress bar.

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  progressDot: [{time: 10}, {time: 22}, {time: 56}]
});

option: progressDot
meaning: Play time corresponding to the marker point Support for dynamic add/delete the marker point

player.addProgressDot(time) // add marker
player.removeProgressDot(time) // delete marker
player.removeAllProgressDot() // delete all markers

Keyboard shortcuts

You can use this configuration item to enable keyboard shortcuts: press the → key to fast forward for 10 seconds, press the ← key to back down for 10 seconds, press the ↑ key to increase the volume, press the ↓ key to decrease the volume, and press the space key to switch the play/pause state.

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

option: keyShortcut
default value: 'on'
reference: 'on' | 'off'

Video click configure

After the video triggers the click event on the PC, the video switches to the play/pause state, and the dblclick event is triggered to enter/exit the full screen; the video triggers the touchend event on the mobile terminal to switch the play/pause state. The corresponding function can be turned off via the configuration item.

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  closeVideoClick: true, // Turn off the default click trigger video pause/play feature
  closeVideoDblclick: true, // Turn off the default dblclick trigger to enter/exit full screen
  closeVideoTouch: true // Turn off the default touchend trigger video pause/play function
});

option: closeVideoClick
default value: false
reference: true | false
option: closeVideoDblclick
default value: false
reference: true | false
option: closeVideoTouch
default value: false
reference: true | false

Turn off built-in controls

The player optimizes and assembles the basic functions of the native video. If you do not want to use the built-in controls, you can turn off the configuration with this option and develop similar plugins for replacement.

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  ignores: ['replay']
});

option: ignores
default value: []
reference: ['time', 'definition', 'error', 'fullscreen', 'i18n', 'loading', 'mobile', 'pc', 'play', 'poster', 'progress', 'replay', 'start', 'volume']

Param	sence
time	current layingtime
definition	definition switching
error	error notification
fullscreen	fullscreen switching
i18n	multilingual switching
loading	loading instruction
mobile	mobile phone interaction
pc	pc video interaction
play	play control bar playback, pause button
poster	poster plugin
progress	video progress bar
replay	replay interactions and prompts
start	initialize play button
volume	volume control

Turn off controls

The player controls are composed of play/pause, seek, volume, fullscreen and so on. You can close all these with this option.

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

option: controls
default value: true
reference: true|false

controls list

You can close part of the controls with this option.

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  controlsList: ['nodownload']
});

option: controlsList
default value: ['nodownload'],
reference: ['nodownload','nofullscreen','noremoteplayback']

Note

Only valid for native video, use ignores option for custom UI.

Airplay

With the airplay option you can transfer the videos in the IOS device to the device which supports airplay for playing. Check Reference for more information.

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

option: airplay
default value: ''
reference: true | false

Plugin switch configuration

Through the configuration of the player, the plugin can be dynamically opened and closed as long as the function plugin reads the configuration.

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  pluginRule: ()=>{return true}
});

option: pluginRule
default value: ''
reference: function(){return true|false}

For example: we want to do traffic test with the MP4 plugin. Half of the users open the function, and half of the users do not open. You can achieve through the following code:

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

multilingual

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

The player will first get the lang configuration of html. If there is no configuration to directly read navigator.language, then the default is to use the great national language zh-cn. The player has both built-in Chinese and English languages, if not enough,it can be customized as well. Methods as below:

Define language

// 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',
  }
})

Import language

import Player from 'xgplayer';
import Language from './language';

let player=new Player({
  id: 'mse',
  url: '/mp4/',
  lang: 'jp'  
});

player.lang=Language;

Note

Note: If there are multiple languages, it's good to use a loop to assign to player.lang. Each assignment will not be covered but increased.

Definition switching configuration

Although the definition plugin configuration is a built-in control, it is quite special somewhere. It does not use the traditional configuration item but uses an event-driven approach. Because our definition design is more abstract, it not only supports explicit video address lists, but also supports virtual address lists, so it is event-driven.

Example

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

player.emit('resourceReady', [{name: '720P', url: 'url1'}, {name: '1080P', url: 'url2'}]);

Note

If you do not want to use the definition switch function, do not activate the resourceReady event; if there is only one address in the video address list, the definition switch control will automatically turn off.

Inline mode

This option opens the inline mode of ios and WeChat on the mobile phone, option:playsinline. Check Reference for more information.

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

option: playsinline
default value: false
reference: true | false

Mobile Debugging

To use this feature, please install weinreip on the developer computer，command: npm -g install weinre。When debugging the phone, configure the debug option at first, and then start the service on the command line. The specific command will prompt in page. More about weinre knowledge Reference

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  debug: {
    host:'10.2.106.238',
    port:9090
  }
});

option: debug
default value: {host:'127.0.0.1',port:9090}
reference: {host:${developerComputer Ip},port:9090}

WeChat playing in the same layer

same layer playing. Check Reference for more information.

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  'x5-video-player-type': 'h5',
  playsinline: false
});

option: x5-video-player-type
default value: ''
reference: 'h5'

WeChat full screen playing

Check Reference for more information.

new Player({
  el: document.querySelector('#mse'),
  url: 'video_url',
  'x5-video-player-fullscreen': false
});

option: x5-video-player-fullscreen
default value: ''
reference: true | false

WeChat horizontal and vertical screen control

Check Reference for more information.

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

option: x5-video-orientation
default value: ''
reference: 'landscape' | 'portraint'
- 'landscape' horizontal
- 'portraint' vertical

Custom configuration

If you customize the plugin and want to pass in the configuration parameters when the player is initialized, you can define it directly.

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

Inside the plug-in, it can get the configuration through player.config.[custom key]. Where player is the current player instance that all the plug-in definition function has.

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

# Configuration

# Required Configuration

# Selector

# Video Source

# Optional Configuration

# Size

# Fluid

# Volume

# Autoplay

# Poster

# PlaybackRate

# VideoRotate

# Thumbnail

# PlayNext

# Download

# Danmu

# Panel

# Loading page

# Controls style

# TextTrack

# Picture-in-Picture

# cssFullscreen

# screenShot

# Preview local videos

# Progress bar special point marker

# Keyboard shortcuts

# Video click configure

# Turn off built-in controls

# Turn off controls

# controls list

# Airplay

# Plugin switch configuration

# multilingual

# Definition switching configuration

# Inline mode

# Mobile Debugging

# WeChat playing in the same layer

# WeChat full screen playing

# WeChat horizontal and vertical screen control

# Custom configuration

Configuration

Required Configuration

Selector

Video Source

Optional Configuration

Size

Fluid

Volume

Autoplay

Poster

PlaybackRate

VideoRotate

Thumbnail

PlayNext

Download

Danmu

Panel

Loading page

Controls style

TextTrack

Picture-in-Picture

cssFullscreen

screenShot

Preview local videos

Progress bar special point marker

Keyboard shortcuts

Video click configure

Turn off built-in controls

Turn off controls

controls list

Airplay

Plugin switch configuration

multilingual

Definition switching configuration

Inline mode

Mobile Debugging

WeChat playing in the same layer

WeChat full screen playing

WeChat horizontal and vertical screen control

Custom configuration