README

vLitejs

vLitejs is a fast and lightweight JavaScript library for customizing video and audio player. Written in native JavaScript without dependency, it is built around an API of providers and plugins to extend these capabilities and keep the core with the minimal functionnalities.

HTML5 video and audio players are automatically included. Other providers like Youtube or Vimeo can be loaded on demand with the Provider API. Plugins uses the same logic and can be loaded on demand by the Plugin API. Others providers and plugins can be created and loaded by the library.

Why `vLitejs`?

If you are concerned about your app's loading performance, this library makes sense as it is extremely lightweight compared to the competition (only 6 KB).
It is quite rare to need to be compatible with HTML5, Youtube and Vimeo at the same time. The library contains by default only HTML5 capabilities and exposed the Provider API to extend capabilities with other providers.
If you need specific behaviors, the plugin API allows to extends the library capabilities.
If you need to create a video or audio player with a custom skin harmonized for all web browsers.

Sizes of the vLitejs bundle compared to the competition:

	vLitejs	Plyr	Videojs
Uncompressed	73 KB	310 KB	2000 KB
Compressed	26 KB	120 KB	537 KB
Gzip	6 KB	30 KB	149 KB

*vlitejs 4.0.0, plyr 3.6.4, videojs 7.11.4

Features

Video & audio - HTML5 video, HTML5 audio, Youtube, Vimeo.
Customization - Choose the control elements you want to display.
No dependency - Written in native Javascript without any framework.
Fullscreen - Supports native fullscreen API.
Provider API - Use the available providers or create your own.
Plugin API - Use the available plugins or create your own.
Streaming - Support HLS.js streaming playback.
Events - Standardized events for all web browsers, providers and plugins.
Autoload API - Youtube and Vimeo API are automatically loaded by their provider.
Subtitles - Supports multiple subtitle tracks (VTT).
Picture-in-Picture - Supports Picture-in-Picture API.
Playsinline - Supports the playsinline attribute.
SVG icons - SVG are inlined into the library, no sprites to includes.
Shortcuts - Supports keyboard shortcuts.
Accessibility - W3C and A11Y valid.

Examples

The project includes several examples of vLitejs implementation in the directory examples. Run the following commands to build the assets for the examples:

npm run build && npm run build:example

If you're interested in playing around with vLitejs, you can use the online code playground on JSFiddle:

Installation

NPM

NPM is the recommended installation method. Install vlitejs in your project with the following command:

npm install vlitejs --save-dev
# or
yarn add vlitejs  --dev

CDN

You can also download it and include it with a script tag. The library will be registered as the global variable window.Vlitejs.

<link href="https://cdn.jsdelivr.net/npm/vlitejs@4/dist/vlite.css" rel="stylesheet" crossorigin />
<script src="https://cdn.jsdelivr.net/npm/vlitejs@4" crossorigin></script>

You can browse the source of the NPM package at jsdelivr.com/package/npm/vlitejs.

How it works

HTML

HTML5 video

<video id="player" class="vlite-js" src="/path/to/video.mp4"></video>

HTML5 audio

<audio id="player" class="vlite-js" src="/path/to/audio.mp3"></audio>

Youtube

<div id="player" class="vlite-js" data-youtube-id="C4qgAaxB_pc"></div>

Vimeo

<div id="player" class="vlite-js" data-vimeo-id="162391385"></div>

Initialization

Import vLitejs styleheet and the JavaScript library as an ES6 modules.

import 'vlitejs/dist/vlite.css';
import Vlitejs from 'vlitejs';

The Vlitejs constructor accepts the following parameters:

Arguments	Type	Default	Description
selector	`String\\|HTMLElement`	`null`	Unique CSS selector string or `HTMLElement` to target the player
config	`Object`	`{}`	Player configuration (optional)

Initialize the player with a CSS selector string.

new Vlitejs('#player');

Or, initialize the player with an HTMLElement.

new Vlitejs(document.querySelector('#player'));

Configuration

The second arguments of the contructor is an optional object with the following parameters:

Arguments	Type	Default	Description
`options`	`Object`	`{}`	Player options
`onReady`	`Function\\|null`	`null`	Callback function executed when the player is ready
`provider`	`String`	`'html5'`	Player provider
`plugins`	`Array`	`[]`	Player plugins

new Vlitejs('#player', {
  options: {},
  onReady: function (player) {},
  provider: 'html5',
  plugins: []
});

Options

The player controls can be customized with the following parameters:

Options	Type	Default	Description
`controls`¹ ²	`Boolean`	`true`	Display the control bar of the video
`autoplay`	`Boolean`	`false`	Enable the autoplay of the media
`playPause`	`Boolean`	`true`	Display the play/pause button on the control bar
`progressBar`	`Boolean`	`true`	Display the progress bar on the control bar
`time`	`Boolean`	`true`	Display the time information on the control bar
`volume`	`Boolean`	`true`	Display the volume button on the control bar
`fullscreen`¹	`Boolean`	`true`	Display the fullscreen button on the control bar
`poster`¹	`String\\|null`	`null`	Customize the video poster url
`bigPlay`¹	`Boolean`	`true`	Display the big play button on the poster video
`playsinline`¹	`Boolean`	`false`	Add the `playsinline` attribute to the video
`loop`	`Boolean`	`false`	Whether to loop the current media
`muted`¹	`Boolean`	`false`	Whether to mute the current media
`autoHide`¹	`Boolean`	`false`	Auto hide the control bar in the event of inactivity (3s)
`providerParams`³	`Object`	`{}`	Overrides the player parameters of the provider

¹ Video only.
² Vimeo provider requires a Plus or Pro account to use this feature (see Vimeo plans).
³ See Youtube embed options and Vimeo embed options.

The autoplay parameter automatically activates the muted option because the API can only be initiated by a user gesture (see Autoplay policy changes).

Example of customization for the autoHide and the poster options.

new Vlitejs('#player', {
  options: {
    autoHide: true,
    poster: '/path/to/poster.jpg'
  }
});

Player ready

The callback function onReady is automatically executed when the player is ready. The HTML5 video and audio listen to the canplay|loadedmetadata event. The Youtube and Vimeo provider listen to the onready event returned by their API.

The function exposes the player parameter as the player instance. You can use it to interact with the player instance and the player methods.

Example of a player muted when ready:

new Vlitejs('#player', {
  onReady: function (player) {
    this.player.mute();
  }
});

The onReady function can also be written with an arrow function.

Events

vLitejs exposes the following native Event on the .v-vlite element. Events are standardized for all providers, even for Youtube and Vimeo.

Event Type	Description
`play`	Sent when the playback state is no longer paused, after the play method or the autoplay
`pause`	Sent when the playback state is changed to paused
`progress`	Sent periodically to inform interested parties of progress downloading the media.
`timeupdate`	Sent when the `currentTime` of the media has changed
`volumechange`	Sent when audio volume changes
`enterfullscreen`¹	Sent when the video switches to fullscreen mode
`exitfullscreen`¹	Sent when the video exits fullscreen mode
`enterpip`¹	Sent when the video switches to picture-in-picture mode
`leavepip`¹	Sent when the video exits picture-in-picture mode
`trackenabled`¹	Sent when a track is enabled and displayed
`trackdisabled`¹	Sent when a track is disabled and hidden
`ended`	Sent when playback completes

¹ Video only.

Example of a listener when the media triggers a play event.

new Vlitejs('#player', {
  onReady: (player) => {
    player.on('play', () => {
      // The video starts playing
    });
  }
});

Events can also be declared outside of the onReady function.

const vlite = new Vlitejs('#player');

vlite.player.on('play', () => {
  // The video starts playing
});

Methods

The player instance exposes the following methods, accessible when the player is ready.

Method	Parameters	Promise	Description
`play()`	-	-	Start the playback
`pause()`	-	-	Pause the playback
`setVolume(volume)`	`Number`	-	Set the volume between 0 and 1
`getVolume()`	-	`Promise`	Get the volume
`getCurrentTime()`	-	`Promise`	Get the current time
`getDuration()`	-	`Promise`	Get the duration
`mute()`	-	-	Mute the volume
`unMmute()`	-	-	Unmute the volume
`seekTo(time)`	`Number`	-	Seek to a current time in seconds
`requestFullscreen()`	-	-	Request the fullscreen
`exitFullscreen()`	-	-	Exit the fullscreen
`getInstance()`	-	-	Get the player instance
`loading()`	`Boolean`	-	Set the loading status
`destroy()`	-	-	Destroy the player

Example of media duration recovery.

new Vlitejs('#player', {
  onReady: (player) => {
    player.getDuration().then((duration) => {
      // The duration is available in the "duration" parameter
    });
  }
});

Custom CSS properties

The player exposes some custom CSS properties, locally scopped under the .v-vlite selector. You can use them to customize the design.

Name	Value	Description
`--vlite-colorPrimary`	`#ff7f15`	Primary color
`--vlite-transition`	`0.25s ease`	Transition
`--vlite-controlBarHeight`	`50px`	Control bar height
`--vlite-controlBarHorizontalPadding`	`10px`	Control bar horizontal padding
`--vlite-controlBarBackground`	`linear-gradient(to top, #000 -50%, transparent)`	Control bar background
`--vlite-controlsColor`	`#fff\\|#000`	Controls color (video\|audio)
`--vlite-controlsOpacity`	`0.9`	Controls opacity
`--vlite-controlsIconWidth`	`28px`	Controls icon width
`--vlite-controlsIconHeight`	`28px`	Controls icon height
`--vlite-progressBarHeight`	`5px`	Progress bar height
`--vlite-progressBarBackground`	`rgba(0 0 0 / 25%)`	Progress bar background

Shortcuts

The player accepts the following keyboard shortcuts.

Key	Action
`space`	Toggle playback
`Esc`	Exit the fullscreen
`←`	Seek backward of `5s`
`→`	Seek forward of `5s`
`↑`	Increase volume of `5%`
`↓`	Decrease volume of `5%`

Browser support

vLitejs supports the latest 2 versions of most modern browsers with the .browserslistrc config.

Browser	Supported
Chrome	✅
Firefox	✅
Opera	✅
Edge	✅
Safari	✅
iOS Safari	✅

Contributors

Many thanks to Victor Schirm for the vLitejs logo.

Licence

vLitejs is licensed under the MIT License. Created with ♡ by @yoriiis.

Usage no npm install needed!