Amstramgram Media Player - Documentation

Introduction

Some options can't be modified once the player instance has been initialized. They are marked with a , like Instance...

However, most of them can be updated at the same time as the media source, through the src setter.
In this case, the new source passed to the player is an object with a src property and some other properties we want to update like poster, duration or button's label. This options are marked with a , like Src...

The and marks indicate that the options have respectively a getter and a setter.

Finally, options that can be directly set in the HTML code are marked with .
Note that options passed through javascript to the player instance take precedence over those set in the HTML code.

Some options only apply to the video player but I think you'll easily guess which ones.

appLabel

/**
 * @description : 	aria-label content of the player HTML wrapper.
 *
 * @type {string}
 */

 /*** Default for audio players ***/
appLabel = 'Audio Player'

 /*** Default for video players ***/
appLabel = 'Video Player'

alwaysShowHours

/**
 * @description : 	by default, the current time and duration indicators display timing informations
 * 				as 00:00 when media duration is less than an hour and 
 *				as 00:00:00 in the other cases.
 *				If this options is set to true, they're always displayed as 00:00:00
 *
 * @type {boolean}
 */

 /*** Default ***/
alwaysShowHours: false

autoplay

HTML


<video src="my_video.mp4" autoplay muted>

Javascript

/**
 * @description : 	try to automatically play the media
 *
 * @type {boolean}
 */

 /*** Default ***/
autoplay: false

Important !

Please be carefull !
You should know that browers policy about this feature has varied over time and could change further.
Most of the browsers won't autoplay a media unless it is muted.
You may find more informations about the autoplay policy here or here

compactMaxWidth

/**
 * @description : 	the UI arrangement changes according to the player width :
 *				The default distributes all the controls on a single line;
 *				The compact mode uses two lines : the second line is entirely used by the time rail;
 *				The mini mode hides some of the buttons.
 *
 * @type {number} 	Player width in pixels below which compact mode is applied.
 */

/*** Default ***/
compactMaxWidth: 600

If you prefer this compact mode to the classic one, just set this option to a large value, 1000000 for example.

crossOrigin

HTML


<!-- without crossorigin -->			
<video src="my_video.mp4">

<!-- crossorigin set to anonymous -->			
<video src="my_video.mp4" crossorigin="">
<!-- OR -->			
<video src="my_video.mp4" crossorigin="anonymous">

<!-- crossorigin set to use-credentials -->			
<video src="my_video.mp4" crossorigin="use-credentials">

Javascript


/**
 * @description : 	set the media crossorigin attribute.
 *				If undefined or null, no attribute is added.
 *				Note that a empty string will be interpreted as anonymous.
 *
 * @type {undefined | string}
 */

/*** Default ***/
crossOrigin: undefined

download


/**
 * @description : 	the download button properties.
 *
 * @type {object}
 *
 * @property {string} 		label		- The text displayed in the download button tooltip.
 * @property {boolean} 		disabled 	- The download button availability.
 * @property {boolean} 		hidden 	- The download button visibility.
 * @property {object} 		tooltip 	- The download button tooltip properties.
 * 	| @property {boolean} 	hidden 	- The tooltip visibility.
 * 	| @property {boolean} 	left 		- The tooltip position.
 */

/*** Default ***/
download: {
	label: "Download",
	disabled: false,
	hidden: false, 
	tooltip: {
		hidden: false,
		//If true, the tooltip is positioned to the left of the button;
		//if false, it's positioned to the right.
		left: true, 
	},
}

duration


/**
 * @description : 	set the media duration in seconds.
 *				This value is only used to display the media duration before the metadata are loaded.
 *				It's updated by the value given by the metadata as soon as they load.
 *
 * @type {number}
 */

/*** Default ***/
duration: 120

errorMessage


/**
 * @description : 	set the message displayed when the media can't be found.
 *
 * @type {string}
 */

/*** Default ***/
errorMessage: "Oups ! Media can't be found !!!"

format


/**
 * @description : 	set the video format.
 *				It could be a number or a ratio (eg 16 / 9 or 1.777777).
 *				The value is updated by the metadata as soon as they load.
 *
 * @type {number}
 */

/*** Default ***/
format: 16 / 9

fullscreen


/**
 * @description : 	the fullscreen button properties.
 *
 * @type {object}
 *
 * @property {object} 		label		- The label according to the button state
 * 	| @property {string} 		on 		- The text displayed in the fullscreen button tooltip 
 *									when button state is on.
 * 	| @property {string} 		off 		- The text displayed in the fullscreen button tooltip 
 *									when button state is off.
 * @property {boolean} 		disabled 	- The fullscreen button availability.
 * @property {boolean} 		hidden 	- The fullscreen button visibility.
 * @property {object} 		tooltip 	- The fullscreen button tooltip properties.
 * 	| @property {boolean} 	hidden 	- The tooltip visibility.
 * 	| @property {boolean} 	left 		- The tooltip position.
 */

/*** Default ***/
fullscreen: {
	label: {
		on: "Exit fullscreen",
		off: "Fullscreen",
	}
	disabled: false,
	hidden: false, 
	tooltip: {
		hidden: false,
		//If true, the tooltip is positioned to the left of the button;
		//if false, it's positioned to the right.
		left: true, 
	},
}

hideControlsDelay


/**
 * @description : 	set the delay in ms before video controls are hidden.
 *				Also used in audio players for vertical volume slider 
 *				on not mobile devices whose pointer is not mouse.
 *
 * @type {number}
 */

/*** Default ***/
hideControlsDelay: 5000

loop

HTML


<video src="my_video.mp4" loop>

Javascript


/**
 * @description : 	if true, the media plays on repeat.
 *
 * @type {boolean}
 */

/*** Default ***/
loop: false

miniMaxWidth


/**
 * @description : 	the UI arrangement changes according to the player width :
 *				The default distributes all the controls on a single line;
 *				The compact mode uses two lines : the second line is entirely used by the time rail;
 *				The mini mode hides some of the buttons.
 *
 * @type {number} 	Player width in pixels below which mini mode is applied.
 */

/*** Default ***/
miniMaxWidth: 500

If you prefer the minimal mode to the classic one, just set this option to a large value, 1000000 for example.
If you really don't like it, set the option value to 0.


/**
 * @description : 	the more button properties.
 *				The button is used in mini mode to show/hide non-essential buttons.
 *
 * @type {object}
 *
 * @property {object} 		label		- The label according to the button state
 * 	| @property {string} 		on 		- The text displayed in the more button tooltip 
 *									when button state is on.
 * 	| @property {string} 		off 		- The text displayed in the more button tooltip 
 *									when button state is off.
 * @property {object} 		tooltip 	- The more button tooltip properties.
 * 	| @property {boolean} 	hidden 	- The tooltip visibility.
 * 	| @property {boolean} 	left 		- The tooltip position.
*/

/*** Default ***/
more: {
	label: {
		on: "Show less",
		off: "Show more",
	}
	tooltip: {
		hidden: false,
		//If true, the tooltip is positioned to the left of the button;
		//if false, it's positioned to the right.
		left: true, 
	},
}

mute


/**
 * @description : 	the mute button properties.
 *
 * @type {object}
 *
 * @property {object} 		label		- The label according to the button state
 * 	| @property {string} 		on 		- The text displayed in the mute button tooltip 
 *									when button state is on.
 * 	| @property {string} 		off 		- The text displayed in the mute button tooltip 
 *									when button state is off.
 * @property {boolean} 		disabled 	- The mute button availability.
 * @property {boolean} 		hidden 	- The mute button visibility.
 * @property {object} 		tooltip 	- The mute button tooltip properties.
 * 	| @property {boolean} 	hidden 	- The tooltip visibility.
 * 	| @property {boolean} 	left 		- The tooltip position.
*/

/*** Default ***/
mute: { 
	label: {
		//When media is muted
		on: "Unmute",
		//When media is unmuted
		off: "Mute",
	}
	disabled: false,
	hidden: false,
	tooltip: {
		hidden: false,
		//If true, the tooltip is positioned to the left of the button;
		//if false, it's positioned to the right.
		left: true, 
	},
}


/**
 * @description : 	the next button properties.
 *
 * @type {object}
 *
 * @property {string} 		label		- The text displayed in the next button tooltip.
 * @property {boolean} 		disabled 	- The next button availability.
 * @property {boolean} 		hidden 	- The next button visibility.
 * @property {object} 		tooltip 	- The next button tooltip properties.
 * 	| @property {boolean} 	hidden 	- The tooltip visibility.
 * 	| @property {boolean} 	left 		- The tooltip position.
*/

/*** Default ***/
next: {
	label: "Next",
	disabled: true,
	hidden: true, 
	tooltip: {
		hidden: false,
		//If true, the tooltip is positioned to the left of the button;
		//if false, it's positioned to the right.
		left: false, 
	},
}

pip


/**
 * @description : 	the PIP (Picture In Picture) button properties.
 *
 * @type {object}
 *
 * @property {string} 		label		- The label according to the PIP button state.
 * 	| @property {string} 		on 		- The text displayed in the PIP button tooltip 
 *									when button state is on.
 * 	| @property {string} 		off 		- The text displayed in the PIP button tooltip 
 *									when button state is off.
 * @property {object} 		tooltip 	- The PIP button tooltip properties.
 * 	| @property {boolean} 	hidden 	- The tooltip visibility.
 * 	| @property {boolean} 	left 		- The tooltip position.
*/

/*** Default ***/
pip: { 
	label: {
		on: "Disable PIP",
		off: "PIP",
	}
	tooltip: {
		hidden: false,
		//If true, the tooltip is positioned to the left of the button;
		//if false, it's positioned to the right.
		left: true, 
	},
}

Note that the button won't be visible at all if the browser doesn't support the Picture In Picture API feature.

playbackRate


/**
 * @description : 	set the playback rate. 
 *
 * @type {number}
 */

/*** Default ***/
playbackRate: 1

playsInline

HTML


<video src="my_video.mp4" playsinline>

Javascript


/**
 * @description : 	set the video playsInline attribute.
 *
 * @type {boolean}
 */

/*** Default ***/
playsInline: true

playPause


/**
 * @description : 	the playPause button properties.
 *
 * @type {object}
 *
 * @property {string} 		label		- The label according to the playPause button state.
 * 	| @property {string} 		on 		- The text displayed in the playPause button tooltip 
 *									when button state is on.
 * 	| @property {string} 		off 		- The text displayed in the playPause button tooltip 
 *									when button state is off.
 * @property {object} 		tooltip 	- The playPause button tooltip properties.
 * 	| @property {boolean} 	hidden 	- The tooltip visibility.
 * 	| @property {boolean} 	left 		- The tooltip position.
*/

/*** Default ***/
playPause: { 
	label: {
		//When media is playing
		on: "Pause",
		//When media is paused
		off: "Play",
	}
	tooltip: {
		hidden: false,
		//If true, the tooltip is positioned to the left of the button;
		//if false, it's positioned to the right.
		left: false, 
	},
}

poster

HTML


<video src="my_video.mp4" poster="path_to_the_poster.jpg">

Javascript


/**
 * @description : 	defines the video poster path.
 *
 * @type {string}
 */

/*** Default ***/
poster: ""

preload

HTML


<video src="my_video.mp4" preload="none">

Javascript


/**
 * @description : 	set the value of the preload attribute.
 *
 * @type {'auto'|'metadata'|'none'}
 */

/*** Default ***/
preload: 'none'

Take care when you plan to use several players on the same page : some browsers (especialy mobile) refuse to preload more than a few medias.
In the same way, if you provide multiple sources in HTML, you should set the HTML preload attribute to "none" so that the browser does not preload the first source.


/**
 * @description : 	the previous button properties.
 *
 * @type {object}
 *
 * @property {string} 		label		- The text displayed in the previous button tooltip.
 * @property {boolean} 		disabled 	- The previous button availability.
 * @property {boolean} 		hidden 	- The previous button visibility.
 * @property {object} 		tooltip 	- The previous button tooltip properties.
 * 	| @property {boolean} 	hidden 	- The tooltip visibility.
 * 	| @property {boolean} 	left 		- The tooltip position.
*/

/*** Default ***/
previous: {
	label: "Previous",
	disabled: true,
	hidden: true, 
	tooltip: {
		hidden: false,
		//If true, the tooltip is positioned to the left of the button;
		//if false, it's positioned to the right.
		left: false, 
	},
}

settings


/**
 * @description : 	the settings button properties.
 *
 * @type {object}
 *
 * @property {boolean} 	hidden 			- The settings button visibility.
 * @property {string} 	qualityLabel 		- The text of the quality selection header.
 * @property {string} 	playbackRatesLabel 	- The text of the playback rates selection header.
 * @property {array} 	playbackRates 		- Array of available playback rates.
 * @property {string} 	subsLabel 			- The text of the subtitles selection header.
*/

/*** Default ***/
settings: {
	hidden: false, 
	qualityLabel: "QUALITY",
	playbackRatesLabel: "PLAYBACK SPEED",
	playbackRates: [['0.25 x', 0.25], ['0.5 x', 0.5], ['0.75 x', 0.75], ['Normal', 1], ['1.5 x', 1.5], ['2 x', 2], ['4 x', 4]],
	subsLabel: "SUBTITLES",
}

playbackRates is either an array of numbers or an array of two elements arrays.

In the first case, each number is an available playback speed and the settings panel simply lists them all.
So, if you set :
playbackRates: [ 0.25, 0.5, 0.75, 1, 1.5, 2, 4 ]
the panel settings panel will just display a vertical list of these numbers.

In the second case, the first element of each array is the string associated to the speed defined by the second element which is a number.

subtitles

HTML


<video src="my_video.mp4">
	<!-- Two subtitles tracks - English is set as default language -->
	<track label="English" kind="subtitles" srclang="en" src="my_english_subtitles.vtt" default>
	<track label="Français" kind="subtitles" srclang="fr" src="mes_sous-titres_francais.vtt">
</video>

Javascript


/**
 * @description : the subtitles button properties
 *
 * @type {object}
 *
 * @property {object} 		label		- The text displayed in the tooltip according to the button state.
 * 	| @property {string} 		on 		- The text displayed if the button is on.
 * 	| @property {string} 		off 		- The text displayed if the button is off.
 * @property {boolean} 		disabled 	- The subtitles button availability.
 * @property {boolean} 		hidden 	- The subtitles button visibility.
 * @property {object} 		tooltip 	- The subtitles button tooltip properties.
 * 	| @property {boolean} 	hidden 	- The tooltip visibility.
 * 	| @property {boolean} 	left 		- The tooltip position.
 * @property {boolean} 		state 	- The default button state (if true, the button is on).
 * @property {string} 		wrapper 	- A valid CSS selector referencing the HTML wrapper where to display the subtitles (see below).
 * @property {string} 		container 	- A valid CSS selector referencing the HTML container where to display the subtitles (see below).
 * @property {array} 		sources 	- An array of objects. Each object defines a subtitles source (see below).
 * @property {string} 		default 	- The default language code (see below).
 */

 /*** Default ***/
 subtitles: {
	label: {
		on: 'Disable subtitles',
		off: 'Enable subtitles',
	},
	disabled: false,
	hidden: false, 
	tooltip: {
		hidden: false,
		//If true, the tooltip is positioned to the left of the button;
		//If false, it's positioned to the right.
		left: true, 
	},
	state: false,
	wrapper: '',
	container: '',
	sources: [],
	default: 'en',
}

wrapper & container

wrapper and container properties allow to specify where the subtitles are displayed.
With some exceptions, they are not useful in the case of a video player since subtitles display is integrated to the UI.
However, we need it if we want to display the lyrics of a song played throuh an audio player as this is the case here.
The HTML code should be of this form :


<block>
	<inline-block id="my-subtitles-wrapper">
		<inline id="my-subtitles-container">
			<!-- HERE COME THE SUBTITLES -->
		</inline>
	</inline-block>
</block>

And so we will set :


subtitles: {
	wrapper: '#my-subtitles-wrapper',
	container: '#my-subtitles-container'
}

Note that the wrapper element automaticly gains the amst__hide-subtitles class when the subtitles button is off and the amst__subtitles-empty class each time there is no subtitle to display.

sources

sources property must be an array of objects, each object referencing a subtitles track.


/**
* @description : The subtitles sources
*
* @type {array}
*
* @property {string} 	src		- The path to the subtitles file.
* @property {string} 	srclang 	- The language code ('en-US', 'fr-FR', 'en', 'fr').
* @property {string} 	label 	- The language label displayed in the settings panel.
*/
				 
sources: [
	{
		src: 'path_to_the_english_subtitles_file.vtt',
		srclang: 'en',
		label: 'English',
	},
	{
		src: 'path_to_the_french_subtitles_file.vtt',
		srclang: 'fr',
		label: 'Français',
	},
]

default

The browser language property take precedence over the default language.
So, if you provide english and french subtitles with english set as default and if the user has a french browser, default language will be french.

skipTime


/**
 * @description : 	defines the value of the time skip applied to the playback 
 *				when left or right keyboard arrows are pressed.
 *				If it's a number, it simply defines this value in seconds.
 *				If it's a string on the form "5%", 
 *				the value is equal to the given percent of the total duration.
 *
 * @type {number|string}
 */

/*** Default ***/
skipTime: "1%"

src

HTML


<video src="my_video.mp4">

<!-- OR -->	

<video>
	<source>src="my_video480.mp4" data-quality="480P"</source>
	<!-- This will be the default source -->	
	<source>src="my_video720.mp4" data-quality="720P" data-default="true"</source>
	<source>src="my_video1080.mp4" data-quality="1080P"</source>
</video>

Demo here

Javascript



/**
 * @description : 	defines the media source.
 *				A simple string defines a single source.
 *				An array of several object defines multiple sources.
 *				Each object must have a src key pointing to a media file
 *				and a quality key whose content is displayed in the settings panel.
 *
 * @type {array|string}
 * 
 * @example :
 *  src : "path_audio.mp3"
 *
 *  OR
 *
 *  src : [
 *      {
 *          src: "path_audio_1.mp3",
 *          quality: "128 MP3",
 *          type: "audio/mpeg",
 *      },
 *      {
 *          src: "path_audio_2.mp3",
 *          quality: "256 MP3"
 *          type: "audio/mpeg",
 *      },
 *      {
 *          src: "path_audio_3.wav",
 *          quality: "WAV"
 *          type: "audio/wav",
 *      },
 *  ]
 */

/*** Default ***/
src: []

Note that if you provide a type for each source, the player will only retain those which the browser can play.
In the audio example above, the third source with audio/wav type won't be available in Internet Explorer.

thumbnails


/**
* @description : 	defines the thumbnails image properties.
*
* @type {object}
*
* @property {string} 	src 		- The image source.
* @property {integer} 	width 	- The width of one thumbnail in pixels.
* @property {number} 	int 		- The time interval between two thumbnails.
*/

/*** Default ***/
thumbnails: {
	src: undefined, 
	width: 120,
	int: 0,
}

See all the details here.

timeSliderHelpText


/**
 * @description : 	helper text for the time slider keyboard shortcuts.
 *
 * @type {string}
 */

/*** Default ***/
timeSliderHelpText: "Use Left/Right arrow keys to go backward/forward"

timeSliderLabel


/**
 * @description : 	title for time slider for WARIA purposes.
 *
 * @type {string}
 */

/*** Default ***/
timeSliderLabel: "Time slider"

touchSeekingInfoText


/**
 * @description : 	defines the information text displayed 
 * 				when the user horizontally swipes on video on a touch device.
 *
 * @type {string}
 */

/*** Default ***/
touchSeekingInfoText: "Tap & go !"

volume


/**
 * @description : 	set the initial media volume.
 * 				Note that if a volume is already stored in the session storage 
 *				for the player's volumeGroup, it will override this parameter 
 * 				unless the volumeForced option is set to true.
 *
 * @type {number between 0 and 1}
 */

/*** Default ***/
volume: 0.8

volumeBeforeMute


/**
 * @description : 	defines the media volume when a click occurs 
 * 				on the unmute button if the media was muted
 * 				on initialization.
 * 				Note that if a volume is already stored in the session storage 
 *				for the player's volumeGroup, it will override this parameter .
 *
 * @type {number between 0 and 1}
 */

/*** Default ***/
volumeBeforeMute: 0.8

volumeForced


/**
 * @description : 	if set to true, the volume passed as option
 * 				will be applied to all the players of the same volumeGroup
 *				and override the volume eventually stored in the Session Storage. 
 *
 * @type {boolean}
 */

/*** Default ***/
volumeForced: false

volumeGroup


/**
 * @description : 	defines the volumeGroup to which the player belongs.
 * 				When the volume of a player changes, 
 * 				all the volume of the same players group
 *				change accordingly. 
 *
 * @type {integer}
 */

/*** Default ***/
volumeGroup: 0

volumeHorizontal


/**
 * @description : 	ff false, the volume slider is displayed vertically.
 *
 * @type {boolean}
 */

/*** Default ***/
volumeHorizontal: true

volumeSliderHelpText


/**
 * @description : 	helper text for the volume slider keyboard shortcuts.
 *
 * @type {string}
 */

/*** Default ***/
volumeSliderHelpText: "Use Up/Down arrow keys to increase/decrease the volume"

volumeSliderLabel


/**
 * @description : 	title for volume slider for WARIA purposes.
 *
 * @type {string}
 */

/*** Default ***/
volumeSliderLabel: "Volume slider"