The Accessible Audio Player is designed to be a versatile and easy-to-integrate audio solution for web applications. It comes packed with features including standard playback controls, volume adjustment, progress seeking, and robust playlist management. A key focus is on accessibility, ensuring full compatibility with screen readers and keyboard navigation. It supports various audio formats and can handle both static audio files and live streams seamlessly.
Getting Started
To use the player, you first need to include the accessible-audio-player.js file in your HTML document. The recommended way is by using an importmap and a script tag with type="module" in your <head>, as shown below. You can download the player file using the button above and place it in your project folder (or serve it from a CDN).
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1.0"/>
<title>Your Audio Page</title>
<link rel="stylesheet" href="style.css">
<!-- Import map for local modules -->
<script type="importmap">
{
"imports": {
"audioPlayer": "/accessible-audio-player.js"
}
}
</script>
</head>
<body>
<!-- Your page content -->
<!-- Add the player container here -->
<div id="my-audio-player-container"></div>
<script type="module">
import { AccessibleAudioPlayer } from 'audioPlayer';
// Your player initialization code here
window.addEventListener('DOMContentLoaded', () => {
new AccessibleAudioPlayer('#my-audio-player-container', {
// Player options go here
});
});
</script>
</body>
</html>
Next, create an empty HTML element, typically a div, where you want the player interface to appear. Give this element a unique ID or class that you can easily reference in your JavaScript. Place this element within your <body> where you want the player to render.
<div id="my-audio-player-container"></div>
<!-- Or if you prefer a class -->
<div class="audio-player-instance"></div>
Initialization
Initialize the player in your JavaScript by creating a new instance of the AccessibleAudioPlayer class. The constructor takes two arguments: the first is a CSS selector string (like '#my-audio-player-container') or a direct DOM element reference for your container. The second argument is an optional configuration object. You should typically do this after the DOM is loaded, for example, within a DOMContentLoaded listener.
The most common way to initialize is by providing a playlist array in the options. Each item in the array should be an object representing a track, with required properties like title and url (the audio source link), and an optional artist property. You can mix static file URLs (like MP3, Ogg) and streaming URLs in the same playlist.
import { AccessibleAudioPlayer } from 'audioPlayer';
window.addEventListener('DOMContentLoaded', () => {
const player = new AccessibleAudioPlayer('#my-audio-player-container', {
playlist: [
{
title: 'Sample Stream (Radio Paradise)',
url: 'https://stream.radioparadise.com/mp3-128',
artist: 'Radio Paradise'
},
{
title: 'Local MP3 File Example',
url: 'path/to/your/audio-file.mp3',
artist: 'Your Artist Name'
},
{
title: 'Another Ogg Track',
url: 'path/to/another-audio.ogg',
artist: 'Another Artist'
}
],
startTrack: 0
// autoplay: true
});
});
Alternatively, you can initialize the player with just a single audio source directly, without providing a full playlist array, by using the track option. This is useful for applications like a radio player where you only load one stream at a time. You can provide either a track object with title and url, or simply the URL string itself. When using the track option, the player effectively has a playlist of one item.
import { AccessibleAudioPlayer } from 'audioPlayer';
window.addEventListener('DOMContentLoaded', () => {
// Initialize with a single track object
const playerSingleTrack = new AccessibleAudioPlayer('#my-single-player-container', {
track: {
title: 'My Single Audio',
url: 'path/to/single-audio.wav',
artist: 'Just Me'
},
// autoplay: true
});
// Initialize with just a URL string
const playerSingleURL = new AccessibleAudioPlayer('#my-other-player-container', {
track: 'https://stream.example.com/my-radio-stream',
// autoplay: true
});
});
Remember that you need to have corresponding empty container elements (e.g., <div id="my-single-player-container"></div>) in your HTML for each player instance you create.
Player Interface and Controls
Once initialized, the player renders its full interface within the container you provided. The interface includes standard audio controls: Previous, Play/Pause, and Next buttons, a volume slider, and a mute toggle. It also displays the current track's title and artist.
**Playback Buttons:** The Play/Pause button toggles the playback state. The Previous and Next buttons navigate through the playlist if multiple tracks are present. If the player is currently playing and you press Previous within the first few seconds of a track, it will restart the current track instead of going to the previous one.
**Volume Controls:** A volume slider allows you to adjust the playback volume. The adjacent button acts as a mute toggle, silencing or restoring the sound without changing the slider position.
Playback Progress and Seeking
Below the controls, you'll find the progress bar, which visually represents the current playback position and buffered audio. On either side are displays for the current playback time and the total duration of the track.
For static audio files with a known duration, the progress bar allows **seeking**. You can click or tap anywhere on the bar to jump to that point in the track, or click and drag for continuous seeking. The progress bar also includes a buffered indicator showing which parts of the track have been downloaded and are ready to play.
For **live streams** or audio sources with an unknown duration, the progress bar and time displays adapt. The duration will not be shown, and the current time display may show "Live" or a similar indicator. Seeking is disabled for these sources, and the progress bar will reflect this state.
**Keyboard Seeking:** When the progress bar has focus (you can tab to it), you can use the Arrow keys (Left/Right to seek backward/forward by a few seconds) and Home/End keys (to jump to the start/end of the track, if seekable).
Managing the Playlist
If the player was initialized with a playlist, it will be displayed below the progress bar. The list shows each track by its title and artist.
**Selecting Tracks:** You can click on any track in the list to load and start playing that track. The currently playing track is highlighted in the list.
**Playlist Keyboard Navigation:** The playlist is fully navigable by keyboard. You can tab into the playlist section, use the Up and Down Arrow keys to move between tracks, and press Enter or Space to select and play the focused track. The currently playing track is automatically given a tabindex of 0 to make it easily reachable by keyboard users.
**Dynamic Playlist Updates:** You can change the player's playlist dynamically after initialization using the setPlaylist(newPlaylist, startTrack = 0, playNow = false) method. This method replaces the current playlist with a new one, optionally loads a specific starting track, and can begin playback immediately.
// Assuming 'player' is an existing AccessibleAudioPlayer instance
const newSongs = [
{ title: 'New Track One', url: 'path/to/new1.mp3' },
{ title: 'New Track Two', url: 'path/to/new2.ogg', artist: 'Someone New' }
];
player.setPlaylist(newSongs, 0, true);
To load just a single track dynamically, replacing any current playlist, use the loadTrack(trackSource, playNow = false) method. The trackSource can be a track object or a URL string.
// Assuming 'player' is an existing AccessibleAudioPlayer instance
player.loadTrack('https://stream.another-radio.com/stream', true);
// OR
player.loadTrack({ title: 'Podcast Episode', url: 'path/to/podcast.mp3' }, false);
Accessibility Features
The player is built with accessibility in mind. All interactive elements, such as buttons and the progress bar, are focusable via keyboard and provide meaningful ARIA attributes (like aria-label, aria-pressed, aria-valuenow, role="slider", aria-current) to assistive technologies like screen readers. Screen reader users will be informed about the player's state, current track, progress, and controls. Keyboard navigation is fully supported for all interactive parts of the player interface and the playlist.
Getting Player State
You can programmatically retrieve the current state of the player using the getState() method. It returns an object containing useful information about the currently loaded track, playback status, time, volume, and mute state.
// Assuming 'player' is an existing AccessibleAudioPlayer instance
const currentState = player.getState();
console.log('Current track:', currentState.track ? currentState.track.title : 'None');
console.log('Is playing:', currentState.playing);
console.log('Current time:', currentState.currentTime);
console.log('Volume:', currentState.volume);
Error Handling
The player includes basic error handling for audio loading and playback issues. Errors are typically logged to the browser console. In case of a fatal error for the current track, the player will pause and display an error message in the title area.
By following these steps and utilizing the available methods, you can effectively integrate and control the Accessible Audio Player in your web application, providing a rich and accessible audio experience for your users.