APM Player

A DOM-based javascript UI library for HTML5 audio, created for use on American Public Media and Minnesota Public Radio's websites.
Supports live streams and archived playback.

The library was designed for backwards compatibility with older javascript build systems, or even no build system, so it supports usage in a




`

The script is then accessible in the global namespace in your javascript by using window.ApmPlayer

Usage

This library is DOM-based (i.e. it doesn't use something like props in React, but stores its configuration in the DOM).
It is invoked on a particular DOM element and expects various child elements to exist within that DOM element.

$3

At a minimum, the library needs a containing element and an

`html


- js-player-play: The play/pause button. To change state of the button (to alternate between a play and pause icon), you can put the appropriate icons inside the button and show/hide based on the CSS state class applied to js-player. Can be multiple elements.
- js-player-timeline: The outer container of the scrubber. Must be a single element.
- js-player-progress: The element indicating the time elapsed inside the scrubber. Must be contained inside js-player-timeline. Must be a single element.
- js-player-buffered: The element indicating the loaded audio buffers. Must be contained inside js-player-timeline and should not contain any elements (or they will be overwritten). Must be a single element.
- js-player-volume: The outer container of the volume bar. Must be a single element.
- js-player-volume-current: The element indicating the current volume. Must be contained inside js-player-volume. Must be a single element.
- js-player-mute: The audio mute button. To change state of the button (to alternate between a mute and unmute icon), you can put the appropriate icons inside the button and show/hide based on the CSS state class applied to js-player. Must be a single element.
- js-player-duration: Displays the total length (in hh:mm:ss) of the audio which is currently loaded. Must be a single element.
- js-player-currentTime: Displays the current time of the currently loaded audio. Must be a single element.

#### DOM Example

The actual structure of the DOM is flexible, allowing for lots of different possible layouts, but here's an example of what it could look like (taken from The Current and abbreviated):

`html


Notice the additional classes used on elements with js- classes. The additional classes should be used for styling, not the js- classes, as those are meant to be only javascript hooks.

$3

URLs to the audio files should be supplied to the data-src attribute on the main container element (.js-player in this example).
Once playback is initiated, the library will create the appropriate element(s) inside the

The player can handle multiple audio sources, allowing the browser to use fallback formats if the OS or browser don't have the preferred codecs.

#### Audio object array

The most explicit, and generally preferred, way of defining the audio used in the player is by supplying an array with objects that detail the url and type of audio.
This is preferred if you know what formats your audio use so that the library doesn't have to guess based on the file extension.

Assume a JSON object that looks like this:

`json
[
{
"url": "https://example.com/my-audio.aac",
"type": "audio/aac"
},
{
"url": "https://example.com/my-audio.mp3",
"type": "audio/mpeg"
}
]
`

This provides a file in the AAC codec, which should use the audio/aac file container type as the preferred format, and the browser will fall back to the MP3 file (type audio/mpeg) if it can't play AAC audio.

To apply this to the DOM it should look like this. The JSON can use single quotes here instead of double quotes if preferred:

`html


For reference, once this is parsed by the library after playback has been initiated, the

`html

`

#### Audio filename array

If your data source that provides the audio urls doesn't provide information about the codec, you can just pass an array of url strings and the library will try to figure out the MIME types based on the filename:

`html


`html

`

If the library can't tell what type a file is from the filename, it will omit the type attribute from that element.
The browser may still be able to play that audio file, but it might not work correctly.

#### Audio string

The library also accepts a simple string as the data-src:

`html


`html

`

$3

The overall state of the player is communicated in the DOM by is-* classes on the main DOM element (the js-player element).
Any visual state changes of the player (alternating between the play and pause icons, for example) should use CSS to inherit the is-* class.

An exception to this rule of state classes is that the progress bar (scrubber) and the volume slider are set by javascript-driven inline styles to determine their width/height.

#### Player State Classes

All possible player state classes:

- is-playing: Added to the container after audio playback has been initiated or unpaused. Removed when audio is paused. If finite-length audio reches its end, this class is removed.
- is-paused: Added to the container when audio is paused. Removed when audio is playing. If the audio is a live stream (infinite length), this class is removed when the user "pauses" the stream because the audio is unloaded instead of just paused. This also means that when finite-length audio reaches its end, this class does not get added.
- is-loading: Added to the container when the browser is loading the audio file. Removed once playback has begun.
- is-muted: Added to the container if audio is muted (volume == 0). Removed if volume is greater than 0.

#### Player State Example

For example, to alternate between the play and pause icons, you might do something like this in the CSS, assuming the DOM example above:

`css
/ The default state, shows the play icon /
.player-play { display: block; }

/ The default state, hides the pause icon /
.player-pause { display: none; }

/ Using the is-playing class applied to containing .js-player to show the pause icon and hide the play icon /
.is-playing .player-play { display: none; }
.is-playing .player-pause { display: block; }
`

$3

Invoking the library in your app is fairly straightforward, and can be done in a few different ways depending on how you included the script in your app.

#### ES6/Require.js Setup

Assuming you imported or required the player using the existing exported name Player into your js file, invoke the script on your DOM element:

`javascript
// your custom js file

// The DOM element container
const playerElement = document.querySelector('.js-player');
// Create new instance of the Player class
const player = new Player(playerElement);

// Don't forget to initialize
player.init();
`

#### Global Setup

If you included the player library in your project in a