Media Player

NPM Version
NPM Filesize
Build Status

Media Player is a tiny, responsive, international, accessible, cross browser,
easily customizable media player written in plain vanilla JavaScript.

Media Player Screenshot

Media Player can be controlled with any pointer or keyboard, whether it’s to
play, pause, move across the timeline, mute, unmute, adjust the volume, enter
or leave fullscreen, or download the source.

Diagram of Media Player

Media Player is designed for developers who want complete visual control over
the component. It’s also for developers who want to hack at or extend the
player without any fuss. The player itself does all the heavy lifting; semantic
markup, accessibility management, language, fullscreen, text direction,
providing pointer-agnostic scrubbable timelines, and lots of other cool
sounding stuff.

Diagram of Time Slider


Add the required JavaScript and default CSS to your page.

<script src=""></script>
<link rel="stylesheet" src=""></script>

Node Usage

npm install --save mediaplayer

Import the library and create a new Media Player using any media element:

import MediaPlayer from 'mediaplayer';

// get target from media with controls
const $target = document.querySelector('audio[controls], video[controls]');

// assign media player from target (all these options represent the defaults)
const player = new MediaPlayer(
    prefix: 'media',
    lang: {
      play: 'play',
      pause: 'pause',
      mute: 'mute',
      unmute: 'unmute',
      volume: 'volume',
      currentTime: 'current time',
      remainingTime: 'remaining time',
      enterFullscreen: 'enter fullscreen',
      leaveFullscreen: 'leave fullscreen',
      download: 'download'
    svgs: {
      play: '#symbol-play',
      pause: '#symbol-pause',
      mute: '#symbol-mute',
      unmute: '#symbol-unmute',
      volume: '#symbol-volume',
      currentTime: '#symbol-currentTime',
      remainingTime: '#symbol-remainingTime',
      enterFullscreen: '#symbol-enterFullscreen',
      leaveFullscreen: '#symbol-leaveFullscreen',
      download: '#symbol-download'
    timeDir: 'ltr',
    volumeDir: 'ltr'

The prefix option is used to prefix flat class names, which are otherwise:

.media-player {}

  .media-media { /* video or audio element */ }

  .media-toolbar {} {} { /* play svg */ } { /* pause svg */ } {} { /* mute svg */ } { /* unmute svg */ } { /* plain text */ } { /* plain text */ } {} { /* full volume */ } { /* current volume */ } {} { /* full duration */ } { /* elapsed time */ } {} { /* download svg */ } {} { /* enter full screen svg */ } { /* leave full screen svg */ }

Note the convenience classes like media-control, media-symbol,
media-slider, media-range and media-range-meter. These make it easier to
style a group of controls or to add new controls.

Because flexbox is used to arrange the controls, the order property can be
used to easily rearrange them.

The lang object is used to provide accessible labels to each control in any
language. Undefined labels will use English labels.

The svgs object is used to assign SVG sprites to each control in each state.
There may be IE limitations when using external sources with your SVGs, so read
SVG use with External Source for details and solutions.

Media Player Instance

All DOM generated by Media Player is easily accessible from its instance.

new Media(mediaElement, options);
  • media: the original media target
  • toolbar: the toolbar containing all the media controls
  • play: the play button
  • playSymbol: the play image
  • pauseSymbol: the pause image
  • mute: the mute button
  • muteSymbol: the image seen before clicking mute
  • unmuteSymbol: the image used after clicking mute
  • currentTime: the current time element
  • currentTimeText: the current time text node
  • remainingTime: the remaining time element
  • remainingTimeText: the remaining time text node
  • time: the time slider
  • timeRange: the time slider range
  • timeMeter: the time slider meter
  • volume: the volume slider
  • volumeRange: the volume slider range
  • volumeMeter: the volume slider meter
  • download: the download button
  • downloadSymbol: the download image
  • enterFullscreenSymbol: the full screen enter image
  • leaveFullscreenSymbol: the full screen leave image


Volume and time controls sliders allow you to drag volume up or down and time
backward or forward. By default, these sliders work left-to-right, meaning that
dragging the slider to the right advances the control. This behavior is
expected in a right-to-left environment as well.

These control can be configured to work in any direction — right-to-left
(rtl), top-to-bottom (ttb), bottom-to-top (btt) — with the following

new MediaPlayer(audioElement, {
  volumeDir: 'btt', // (volume will drag bottom to top)
  timeDir: 'ttb' // (time will drag top to bottom)


Media Player automatically assigns ARIA roles and labels to
its controls, which always reflect the present state of the media player.
Special slider roles are used for volume and time which are then given helpful
keyboard controls.


Three new events are dispatched by Media Player. playchange
dispatches whenever play or pause toggles. timechange dispatches more rapidly
than timeupdate. canplaystart dispatches the first time media can play

Keyboard Controls

Spacebar, Enter / Return

When focused on the play button or the timeline slider, pressing the
spacebar or enter / return toggles the playback of the media.

When focused on the mute button or the volume slider, pressing the
spacebar or enter / return toggles the muting of the media.


When focused on the play button or the timeline slider, pressing
right arrow or up arrow moves the time forward, while pressing
left arrow or down arrow moves the time backward. Time is moved by 10
seconds, unless shift is also pressed, in which case it moves 30 seconds.

When focused on the mute button or the volume slider, pressing
right arrow or up arrow increases the volume, while pressing
left arrow or down arrow decreases the volume. Volume is moved by 1%,
unless shift is also pressed, in which case it moves 10%.

Browser compatibility

Media Player works in all browsers supporting Audio, Video, and SVG elements.
This includes Chrome, Edge, Firefox, Internet Explorer 9+, Opera, and Safari 6+.
Older versions of Edge and Internet Explorer may need additional assistance
loading SVGs from an external URL.

Read SVG use with External Source for details and solutions.



Media Player and its icons use the CC0 “No Rights Reserved” license.

Media Player adds up to 2.47 kB of JS and 582 B of CSS to your project.