Amstramgramvideoplayer NPM

Simple, elegant, ligthweight although powerfull and versatile HTML5 video player.

Features

Written in pure JavaScript, no dependencies required
Touch-devices support
Two UI modes : normal / compact
Preview thumbnails support (but not for evil iOS - see Compatibility)
SVG buttons included in css, no extra files to download
Previous, play/pause, next, fullscreen, download buttons
All buttons titles configurables
Display of current time and total duration
Sass so you can include in your build processes
Around 13.15 Ko gzipped (js + css)

BUT no subtitles, Youtube or Vimeo support.

Installation

You can use one of the following methods :

npm

npm -i -d amstramgramvideoplayer

Manually

Download amstramgramVideoPlayer.min.css from the dist/css folder and amstramgramVideoPlayer.min.js from the dist/iife folder.

Include them somewhere in your document :

<link rel="stylesheet" href="css/amstramgramVideoPlayer.min.css">
<script src="js/amstramgramVideoPlayer.min.js"></script>

Importing

Traditional approach

If you don't use JavaScript modules and include the file with a <script> tag, you don't have to import anything explicitly. AmstramgramVideoPlayer will be available in the global scope.

CommonJS

const AmstramgramVideoPlayer = require('amstramgramVideoPlayer');

ES2015 modules

import AmstramgramVideoPlayer from 'amstramgramVideoPlayer';

Sass

@import 'amstramgramVideoPlayer/css/amstramgramVideoPlayer.min.scss';

Usage

Initialize the script by running :

new AmstramgramVideoPlayer(document.querySelector('video'))

Customization

Before you create an instance, you can override the class default options :

AmstramgramVideoPlayer.options({
  // Custom options
});

When creating an instance, you can pass an object with custom options as the second parameter.

new AmstramgramVideoPlayer(document.querySelector('video'),{
  // Custom options
});

When setting the source, you can pass a simple string giving the video file path or an object including the source path and several other options as duration, poster, thumbnails and so on...

const player = new AmstramgramVideoPlayer(document.querySelector('video'));
player.src = {
  src: 'video file path',
  duration: 'duration of the video',
  poster: 'poster path',
  thumbnails: 'thumbnails path',
  ...
}

:small_orange_diamond: The following options can be set either by overriding the default options, when creating the instance or when updating the source :

:black_medium_small_square: autoplay {Boolean}
Default : false
If true, the attribute autoplay is added to the <video> tag. Please be aware that most of the browsers block this functionality if volume is not muted.

:black_medium_small_square: crossorigin {String} "anonymous" | "use-credentials"
Default : "anonymous"
Value of the attribute crossorigin for the <video> tag.

:blackmedium_small_square: download {Object}
Default :
{
label: "Télécharger",
disabled: false,
hidden: false
}
_Download button properties.

:black_medium_small_square: duration {Integer}
Default : 120
Video duration in seconds.
Updated on loadedmetadata event.

:black_medium_small_square: format {Number}
Default : 16/9
Video format ratio.
Updated on loadedmetadata event.

:blackmedium_small_square: fullscreen {Object}
Default :
{
label:
{
enter: "Plein Écran",
exit: "Quitter le plein écran",
},
disabled: false,
hidden: false
}
_Fullscreen button properties.

:black_medium_small_square: loop {Boolean}
Default : false
Attribute added to the <video> tag.

:blackmedium_small_square: next {Object}
Default :
{
label: "Suivant",
disabled: true,
hidden: true
}
_Next button properties.

:black_medium_small_square: playsinline {Boolean}
Default : true
When true, the attributes playsinline and webkit-playsinline are added to the <video> tag.

:black_medium_small_square: poster {String}
Default : undefined
Path of the image used as poster.

:black_medium_small_square: preload {String} "auto" | "metadata" | "none" | "preload"
Default : "none"
Value of the attribute preload for the <video> tag.

:blackmedium_small_square: previous {Object}
Default :
{
label: "Précédent",
disabled: true,
hidden: true
}
_Previous button properties.

:black_medium_small_square: skipTime {Number} or {String}
Default : "1%"
Value in seconds or percent of the total duration for the time skip applied when left or right keyboard arrows are pressed.

:black_medium_small_square: thumbnails {Object}
Default :
{
src: undefined,
number: 100,
}
src is a string defining the path of the image used for the preview thumbnails and number gives the number of thumbnails included.
This number makes it possible to deduce the width of a thumbnail from the natural width property of the image. Then, the height is simply deduce from the video ratio.
You can find all the details on how to generate the thumbnails file here

:black_medium_small_square: volume {Number}
Default : 0.8 on desktop, 1 on mobile and tablet.
Volume of the video.

:blackmedium_small_square: volumeButton {Object}
Default :
{
label:
{
mute: "Désactiver le son",
exit: "Activer le son",
},
disabled: false,
hidden: false
}
_Volume button properties.

:black_medium_small_square: volumeGroup {Integer}
Default : 0
More details here.

:small_orange_diamond: The following options can be set either by overriding the default options or when creating the instance :

:black_medium_small_square: hideControlsDelay {Integer}
Default : 5000
Delay in ms between any interaction with the UI and the hidding of the controls.

:black_medium_small_square: videoVolumeOrientation {String} "horizontal" | "vertical"
Default : "vertical"
If "horizontal", the volume slider is horizontally displayed. In all other cases, the slider is vertical.

:black_medium_small_square: railMinWidthForNormalUI {Integer}
Default : 600
Minimal width in pixels available for the time slider in the normal UI. If the available space is inferior to this number, the compact UI is displayed.

:small_orange_diamond: The following options can be set by overriding the default options :

:black_medium_small_square: appLabel {String}
Default : "Lecteur vidéo"
Text given to the player aria-label.

:blackmedium_small_square: pauseLabel {String}
Default : "Lecture"
Text given to the title and the aria-label of the _Pause button.

:blackmedium_small_square: playLabel {String}
Default : "Pause"
Text given to the title and the aria-label of the _Play button.

:black_medium_small_square: volumeHelpLabel {String}
Default : "Utilisez les flèches Haut/Bas du clavier pour augmenter ou diminuer le volume"
Text given to the volume slider title.

:black_medium_small_square: volumeSliderLabel {String}
Default : "Potentiomètre de volume"
Text given to the volume slider aria-label.

:small_orange_diamond: The following option can be set when creating the instance :

:black_medium_small_square: onInit {function}
Function called when the instance is initialised.

:small_orange_diamond: Some options can be set directly in the video tag :

autoplay, crossorigin, height, loop, muted, src, playsinline, poster, preload, width.

<video src="the video path" autoplay loop muted poster="the poster path"></video>

If specified, the attributes width an height are used to calculate the video ratio. Those options are overrided by the options set when initialising the instance.

API

Setters

src = `source`

source is either a string pointing to the video file source, either an object of the form :
{
src: {String}, giving the video file path - required,
and any of the options listed above
}

currentTime = `time`

time {Number}
Set the playback head position to the specified value, expressed in seconds.

volume = `vol`

vol {Number between 0 and 1}
Set the volume.

Getters

src

{String}
return the video file path.

currentTime

{Number}
return the current playback head position in seconds.

duration

{Number}
return the video duration in seconds.

media

{HTMLVideoElement}
return the HTML video element of the player.

paused

{Boolean}
return true if the video is paused, false if it's playing.

volume

{Number}
return the current volume of the video. 0 is muted, 1 is max.

Methods

pause()

Do what you may expect...

play()

Do what you may expect...

togglePlayPause()

Do what you may expect...

reset()

Pauses the video.
Stores the current picture in a canvas and displays it as a poster.
Set the src attribute to "".
Set the preload attribute to "none".
Finally restores the src attribute to its original value.

Used internally if the instance is playing and another one starts to play.
Provided just in case...

hideControls(`delayed` = `false`, `forced` = `false`)

Do what you may expect...
However... If delayed is set to true, the controls are hidden after a delay equal to the value given by the player option hideControlsDelay.
By default, the function is without effect if the video is paused (controls remains visible). But if you absolutly need to hide them while the video is paused, pass the second argument to true.

showControls()

Do what you may expect...

previous(`opt`)

Set the previous button properties.
opt is an object of the form :
{
label: {String}, // passed to the title attribute of the button.
hidden: {Boolean}, // if true, the button is hidden.
disabled: {Boolean}, // if true, the button is disabled (opacity to 0.5; click without effect).
}

next(`opt`)

Set the next button properties.
See previous() method above.

download(`opt`)

Set the download button properties.
See previous() method above.

fullscreen(`opt`)

Set the fullscreen button properties.
opt is an object of the form :
{
{label:
{
enter: {String}, // passed to the title attribute of the button when fullscreen mode is off.
exit: {String}, // passed to the title attribute of the button when fullscreen mode is on.
}
hidden: {Boolean}, // if true, the button is hidden.
disabled: {Boolean}, // if true, the button is disabled (opacity to 0.5; click without effect).
}

volumeButton(`opt`)

Set the volume button properties.
opt is an object of the form :
{
{label:
{
mute: {String}, // passed to the title attribute of the button when volume is > 0.
exit: {String}, // passed to the title attribute of the button when audio is muted.
}
hidden: {Boolean}, // if true, the button is hidden.
disabled: {Boolean}, // if true, the button is disabled (opacity to 0.5; click without effect).
}

Global properties

AmstramgramVideoPlayer.currentPlayer

Return the playing instance if there is one. Return undefined if no instance is playing,

AmstramgramVideoPlayer.players

Return an array ot all the created instances.

Events

You can access to all media events by the media getter of the instance.

const player = new AmstramgramVideoPlayer(document.querySelector('video'));
player.media.addEventListener('play', function(){
    console.log('Media is playing')
  }
);

on("previous", callback)

callback is a function called when a click event occurs on the Previous button

new AmstramgramVideoPlayer(document.querySelector('video'),{
  onInit: function(){
    this.on('previous', function(){
        console.log('Click event on Previous button')
      }
    );
  }
});

on("next", callback)

callback is a function called when a click event occurs on the Next button

const player = new AmstramgramVideoPlayer(document.querySelector('video'));
player.on('next', function(){
    console.log('Click detected on Next button')
  }
);

Compatibility

All modern browers on desktop, Android and iOS are supported.
However, because of its currents limitations, iOS won't display the thumbnails.
Internet Explorer 11 needs some polyfills (what a surprise !) :

If you have absolutly no idea about how to polyfill, copy the amstramgramVideoPlayerPolyfill.min.js file (from any dist folders) to your javascript directory and simply add those lines to the HEAD section of your HTML page :

<script>
  if (typeof Object.assign !== 'function' || !Array.from || !Array.prototype.includes || typeof window.CustomEvent !== "function") {
    var d = document,
        s = d.createElement('script');
    s.async = "false";
    s.src = "<path to amstramgramVideoPlayerPolyfill.min.js>";
    d.head.appendChild(s);
  } 
</script>

Thus, the polyfill file will only be downloaded if needed...

Thanks

Thanks to BrowserStack for providing the infrastructure that allows me to test in real browsers !

Donation

If you find this project useful and want to say thanks, you can buy me a cup of coffee, a beer, a computer, a sofa, a haunted manor or whatever you want...
...:blush:...

Credits

I've been mainly inspired by mediaelement.js, a pionneer in the long and difficult attempt to harmonise media players in HTML5.
Alternatively, I've also used plyr.js.
There is plenty of libraries of this kind. Most of them offer Flash fallback and Youtube, Vimeo and others integration. In turn, they are quite heavy...
This one is focused on lightweight.
The long term project is to extend it to audio.
So, stay tune !

License

video media player responsive

@infinitebrahmanuniverse/nolb-ams @everything-registry/sub-chunk-1128

1.0.1

4 years ago

1.0.0

4 years ago

Table of contents

Features

Installation

npm

Manually

Importing

Traditional approach

CommonJS

ES2015 modules

Sass

Usage

Customization

API

Setters

src = source

currentTime = time

volume = vol

Getters

src

currentTime

duration

media

paused

volume

Methods

pause()

play()

togglePlayPause()

reset()

hideControls(delayed = false, forced = false)

showControls()

previous(opt)

next(opt)

download(opt)

fullscreen(opt)

volumeButton(opt)

Global properties

AmstramgramVideoPlayer.currentPlayer

AmstramgramVideoPlayer.players

Events

on("previous", callback)

on("next", callback)

Compatibility

Thanks

Donation

Credits

License

src = `source`

currentTime = `time`

volume = `vol`

hideControls(`delayed` = `false`, `forced` = `false`)

previous(`opt`)

next(`opt`)

download(`opt`)

fullscreen(`opt`)

volumeButton(`opt`)