Amplitude · Custom Audio Players

The HTML5 audio tag is an easy way to add music or other sounds to a web page. The downside is that the browser draws the player buttons (play, pause, volume, …). Each browser draws them differently, and you can not change how they look. On a designed web page, the default audio player often looks out of place.

Amplitude solves that problem. It hides the browser’s built-in player and lets you build your own player out of plain HTML and CSS. You write normal HTML elements (a <div>, a <span>, a <button>, …), give them special CSS classes like amplitude-play, and Amplitude wires everything up for you. No deep JavaScript knowledge is needed.

The J1 Template ships three ready-made Amplitude players (Mini, Compact, Large) so you can drop a player into any page without writing any code at all. If you want to design your own player, the rest of this manual lists every CSS class and JavaScript method Amplitude supports.

15-60 Minutes to read

HTML Elements

Amplitude builds the player out of plain HTML elements that you mark with special CSS classes. There are two kinds:

Control elements react to clicks or taps. They have a class such as amplitude-play, amplitude-pause, or amplitude-next.
Display elements are filled in automatically with information about the song that is currently playing — the title, the artist, the cover image, the elapsed time, and so on.

You can use almost any HTML tag (<div>, <span>, <button>, …) for a control or display element, except for the cover image: that one must be an <img> tag, because Amplitude updates its src attribute to point to the active song’s artwork.

All elements are picked up automatically when Amplitude.init() runs. You do not need to register them by hand.

Structure for Elements

Every Amplitude element belongs to a scope — a fancy word for which song or playlist this element controls or displays. There are four possible scopes, from the broadest to the narrowest:

Global: Controls (or shows) whatever song is currently playing, no matter which playlist it belongs to.
Playlist: Controls (or shows) whatever is happening inside one specific playlist.
Song: Controls (or shows) one specific song from the global songs array.
Song In Playlist: Controls (or shows) one specific song inside one specific playlist.

Not every kind of element supports all four scopes. For example, the volume slider is always global — you can not have a different volume for each song or playlist.

To put an element into a particular scope, combine its CSS class with one or two data- attributes:

Global: class="amplitude-{element}"
Playlist: class="amplitude-{element}" data-amplitude-playlist="{playlist}"
Song: class="amplitude-{element}" data-amplitude-song-index="{song}"
Song In Playlist: class="amplitude-{element}" data-amplitude-song-index="{song}" data-amplitude-playlist="{playlist}"

One thing to note about the attribute data-amplitude-song-index on a song in a Playlist element: the index refers to the song’s position inside the playlist. This is different from a plain song element, where the same attribute refers to the song’s position in the global songs array.

In short:

Without data-amplitude-playlist, the index counts songs in the global songs array.
With data-amplitude-playlist, the index counts songs inside that one playlist.

Mixing the two is the most common cause of "the wrong song plays" bugs.

Interactive Elements

The interactive elements of Amplitude have event handlers bound to them that responds to a touch or click from a user. These elements build the functionality of the player you are designing. The scoping of these elements is handled by attributes that define the level of functionality each element has such as global, playlist, individual song or individual song in playlist. These are outlined in detail for each element.

Play Button

There are 4 different levels for a play button.

Global Play: Plays the current song whether it’s an individual song or in a playlist
Playlist Play: Plays the current song in the playlist.
Song Play: Plays an individual song by itself.
Song in a Playlist: Plays an individual song in a playlist.

The play button responds to the 'click' event on a desktop or a touchstart event on mobile devices.

Global Play Button

The global play button will play the active song whether or not the song is an individual song or in a playlist. To add a global play button simply add an HTML element with the class amplitude-play.

<span class="amplitude-play"></span>

Playlist Play Button

The playlist play button will play the active song in the playlist or it will play the first song in the playlist if the playlist is out of scope (meaning another playlist was being played or it’s the first playlist being played). To add a playlist play button, add an HTML element with the class of amplitude-play and the attribute data-amplitude-playlist="playlist_index".

<span class="amplitude-play" data-amplitude-playlist="{playlist_index}"></span>

Individual Song Play Button

The individual song play button will play the song defined by the data-amplitude-song-index="{song_index}" attribute.

<span class="amplitude-play" data-amplitude-song-index="{song_index}"></span>

Individual Song In Playlist Button

The individual playlist button is a combination of the attributes data-amplitude-song-index="{song_index}" and data-amplitude-playlist="{playlist}". This will play an individual song in a playlist as defined.

<span
  class="amplitude-play"
  data-amplitude-song-index="1"
  data-amplitude-playlist="test_playlist">
</span>

Pause Button

The pause button has 4 different levels.

Global Pause: Pauses the active song no matter if it’s individual or in a playlist.
Playlist Pause: Pauses the active song in the playlist.
Song Pause: Pauses an individual song.
Song In Playlist Pause: Pauses an individual song in a playlist.

The pause button responds to the 'click' event on a desktop or a 'touchstart' event on mobile.

Global Pause

The global pause button will pause whatever song is currently playing. To add a global pause button simply add an HTML element with the class of 'amplitude-pause'.

<span class="amplitude-pause"></span>

Playlist Pause

The playlist pause button will pause the active song in the playlist. It only works if the playlist defined in the attribute is playing the song.

<span class="amplitude-pause" data-amplitude-playlist="{playlist}"></span>

Individual Song Pause

The individual song pause button will pause the song defined by the attribute data-amplitude-song-index="song_index".

<span class="amplitude-pause" data-amplitude-song-index="{song_index}"></span>

Individual Song In Playlist Pause

If you want to pause an individual song in a playlist, you need to add both the data-amplitude-song-index="{song_index}" and the data-amplitude-playlist="{playlist}" attributes.

<span
  class="amplitude-pause"
  data-amplitude-song-index="{song_index}"
  data-amplitude-playlist="{playlist}">
</span>

Play Pause Button

The play/pause button is probably the most common button to be implemented when working with Amplitude. Depending on the global state, playlist state and/or song state, this element will get a class that is amplitude-playing or amplitude-paused that can be styled accordingly. It’s common to set a play or pause button image as a background in CSS so when the interaction occurs, the proper button appears.

There are 4 levels of Play/Pause buttons.

Global Play/Pause: Plays or pauses the active song no matter if it’s an individual song or part of a playlist.
Playlist Play/Pause: Plays or pauses the active song in the scope of the playlist.
Song Play/Pause: Plays or pauses an individual song.
Song In Playlist Play/Pause: Plays or pauses an individual song in the playlist.

Global Play/Pause

The global play pause button plays or pauses the current song depending on the state of the Amplitude player. This button does not account for whether the song is in a playlist or an individual song, it’s whatever song is active the functionality works on.

<span class="amplitude-play-pause"></span>

Playlist Play/Pause

The playlist play pause button plays or pauses the current song in a playlist. If a song is being played outside of a playlist when clicked, the playlist will play the first song in the playlist assigned to the button clicked and pause the other song. To add a playlist play pause button add an element with the class of amplitude-play-pause and an attribute of data-amplitude-playlist="{playlist-index}".

<span class="amplitude-play-pause" data-amplitude-playlist="{playlist}"></span>

Song Play/Pause

The song play pause button plays or pauses an individual song when clicked.

<span class="amplitude-play-pause" data-amplitude-song-index="{song_index}"></span>

Song In Playlist Play/Pause

The song in playlist play pause button plays or pauses an individual song in a playlist when clicked. This is defined by a combination of the data-amplitude-song-index="{song_index}" attributes and the data-amplitude-playlist="{playlist}" attributes.

<span
  class="amplitude-play-pause"
  data-amplitude-song-index="{song_index}"
  data-amplitude-playlist="{playlist}">
</span>

Stop Button

Stops playing the current song for a player. There is only one level for the stop button: global.

The stop button simply stops the active song. On a desktop, this will respond to the 'click' event and a 'touchstart' on mobile. To add a stop button simply add the following HTML element:

<span class="amplitude-stop"></span>

Mute Button

Mutes the current song in a player. There is only one level for the mute button: global.

The mute button is another global element that mutes the active song. On a desktop, this element will respond to the 'click' event and a 'touchstart' on mobile. There are two classes that get added to the mute button so you can style it according to the state of the player.

When the player is not muted the class amplitude-not-muted is added to the element and amplitude-muted is added when the player is muted.

<span class="amplitude-mute"></span>

Volume Up

Increases the current volume. There is only one level for the volume up button: global.

The volume up button increments the volume by the amount defined in the config. By default the increment is 5. To change the increment you must adjust the volume_increment setting in the Amplitude.init() method. This element will respond to a click on desktop or a touchstart event on mobile. On iPhones, the user can not adjust the volume through the web page. To add a volume up element add:

<span class="amplitude-volume-up"></span>

Each click increases the volume by the amount you set with volume_increment in Amplitude.init(). The default value is 5%.

Volume Down

Decreases the current volume. There is only one level for the volume down button: global.

The volume down button decrements the volume by the amount defined in the config. By default the decrement is 5. To change the decrement you must adjust the volume_decrement setting in the Amplitude.init() method. This element will respond to a 'click' on desktop or a 'touchstart' event on mobile. On iPhones, the user can not adjust the volume through the web page. To add a volume down element add:

<span class="amplitude-volume-down"></span>

Each click lowers the volume by the amount you set with volume_decrement in Amplitude.init(). The default value is 5%.

Volume Slider

Increases or Decreases the current volume by sliding the range element. There is only one level for the volume slider: global.

The volume slider MUST be an HTML 5 range input element. This allows the user to slide the volume to where they want. On desktop and mobile, this element listens to a 'change' or 'input' event. It will not work on iPhones since iOS doesn’t allow the user to adjust the volume through anything but the volume up and down hardware buttons. To add a volume slider, add the following HTML code:

<input type="range" class="amplitude-volume-slider">

Next Button

Amplitude extends functionality for the audio tag by allowing designers and developers to build playlists. When a next button has been added Amplitude will go to the next song in the state of the player.

There are two levels of the next button.

Global Next - Will go to the next song in the state no matter what state the player is in. If the player is playing a specific playlist, the global next button will go to the next song in the list.
Playlist Next - Will go to the next song in the playlist.

The next button will either go sequentially down the indexes or the next index in the shuffled songs array. If the player is playing a playlist, then the global next button will operate on that playlist.

Global Next Button

To add a global next button add the following HTML code:

<span class="amplitude-next"></span>

Playlist Next Button

To add a playlist next button add the following HTML code:

<span class="amplitude-next" data-amplitude-playlist="{playlist_key}"></span>

The playlist next button has a data-amplitude-playlist attribute with the key for the playlist it’s corresponding to.

A quick note on the playlist next buttons. If you have two playlists (A & B), and you are playing playlist A, but press a next button that is relating to playlist B, the next button won’t do anything.

Previous Button

Similar to the next button, the previous button goes to the previous song in the state of the player. There are two levels of the previous button.

Global Previous: Will go to the previous song in the state no matter what state the player is in.
Playlist Previous: Will go to the previous song in the playlist no matter the state.

The previous button will go sequentially down the indexes or to the previous index in the shuffled songs array. If the player is playing a playlist, the global previous button will operate on that playlist.

Global Previous Button

To add a global previous button add the following HTML code:

<span class="amplitude-prev"></span>

Playlist Previous Button

To add a playlist previous button add the following HTML code:

<span class="amplitude-prev" data-amplitude-playlist="{playlist_key}"></span>

The playlist previous button has a data-amplitude-playlist attribute with the key for the playlist it’s corresponding to. Similar to the next buttons, if you have two playlists and you click a previous button scoped to the inactive playlist, then it won’t do anything.

Shuffle Button

The shuffle button has two levels:

Global Shuffle Button: Shuffles the songs array. This is used outside the scope of a playlist.
Playlist Shuffle Button: Shuffles all of the songs in a playlist. This state is kept on a per-playlist basis.

The shuffle button is also an extension of functionality added by Amplitude. It allows the developer/user to shuffle songs in a playlist or on a global level.

Playlists can have shuffle states independent of other playlists. When a song ends or the user goes to the next song, Amplitude will know whether or not the playlist should go to the next sequential user defined song or the next song in the shuffle array. When a playlist is shuffled or the global songs are shuffled a class of amplitude-shuffle-on is applied to the element. When shuffle is turned off, the class amplitude-shuffle-off is applied to the element.

Global Shuffle Button

To add a shuffle button add the following HTML code:

<span class="amplitude-shuffle"></span>

Playlist Shuffle Button

To add a playlist shuffle button add the following HTML code:

<span class="amplitude-shuffle" data-amplitude-playlist="{playlist_key}"></span>

This shuffle button contains the attribute that defines the playlist key. This will shuffle only the playlist defined.

Repeat Button

The repeat button, when active, will repeat the entire songs array when the last song has been played.

There are two levels to the Repeat Button:

Global Repeat: Repeats the songs in the songs array when the last song has finished.
Playlist Repeat: Repeats the playlist when the last song in the playlist has finished.

The buttons can be styled based off of the state of the classes applied to the button. When repeat is not on, the button will have a class of amplitude-repeat-off applied to the element and when repeat is on, the class amplitude-repeat-on applied to the element.

Global Repeat Button

To add the repeat button, add the following HTML code:

<span class="amplitude-repeat"></span>

Playlist Repeat Button

To add a playlist repeat button, add the following HTML code:

<span class="amplitude-repeat" data-amplitude-playlist="{playlist_key}"></span>

Repeat Song Button

There is only one level of the repeat song button:

Global - Repeats the current song when ended.

The repeat song button, when active, will repeat the individual song when the song has ended. The button can be styled based off of the state of classes applied to the button. When the repeat is not on, the button will have a class of amplitude-repeat-song-off and when on, amplitude-repeat-song-on.

To add the repeat song button, add the following HTML code:

<span class="amplitude-repeat-song"></span>

Playback Speed Button

There is only one level for the playback speed button: Global.

The playback speed button controls how fast the audio is played back through Amplitude. There are 3 speeds.

'1.0' which is the base speed.
'1.5' which is 1.5x as fast
'2.0' which is 2x as fast

When clicked, the playback speed button will add a class representing the speed the player is playing back at. The classes can be styled as well and are as follows:

'1.0' = 'amplitude-playback-speed-10'
'1.5' = 'amplitude-playback-speed-15'
'2.0' = 'amplitude-playback-speed-20'

To add a playback speed button simply add the following HTML code:

<span class="amplitude-playback-speed"></span>

There are 2 levels for the skip to link:

Individual Song: Skips to time defined for a song an individual song in the songs array.
Individual Song In Playlist: Skips to a time defined for an individual song in a playlist.

The skip to links allow the user to define spots in the audio like bookmarks that can be skipped to. They can reference a song in a playlist or an individual song depending on the attributes. If you want to link to a song in a playlist, you have to add the attribute data-amplitude-song-index="index" and data-amplitude-playlist="playlist". To make the skip work, you will also have to add an attribute data-amplitude-location="seconds" to link to in the song.

Individual Song Link

An example song link would be:

<span
  class="amplitude-skip-to"
  data-amplitude-song-index="{song_index}"
  data-amplitude-location="30">
</span>

This link will go to the song at the index defined and the location of the seconds defined by the data-amplitude-location attribute into the song.

Individual Song In Playlist Link

An example of an individual song in playlist link would be:

<span
  class="amplitude-skip-to"
  data-amplitude-song-index="{song_index}"
  data-amplitude-location="30"
  data-amplitude-playlist="{playlist}">
</span>

This will skip to 30 seconds into a song in the playlist defined. Remember, the index of the song in the playlist is scoped to the playlist!

Song Tracking Slider (HTML 5 Range)

There are 4 levels to the song tracking slider:

Global: This tracks whatever song is playing.
Playlist: This tracks the song currently playing in the playlist.
Individual Song: This tracks an individual song.
Individual Song In Playlist: This tracks an individual song within playlist.

Song tracking sliders are implemented with the HTML 5 range element. This provides a semantic way to navigate through a song. The HTML 5 range element provides functionality and you can style it, even if it’s a pain. However, if you are motivated, you can implement a custom song slider using some of the callbacks and public facing methods.

Note that features like the tracking slider and progress bar depend on the browser being able to request the audio file in arbitrary chunks. Firefox can work around lack of support from the server, but for these features to work properly, your server must support Content-Range HTTP headers.

Global Song Slider

To add a global song slider, add the following element:

<input
  type="range"
  class="amplitude-song-slider"
  step=".1">

The class name is amplitude-song-slider. the step attribute makes fine tuning the slider to react more to the current state of the song more fluid.

Playlist Song Slider

If you want to do an individual playlist, you can add the attribute of data-amplitude-playlist="{playlist_key}".

<input
  type="range"
  class="amplitude-song-slider"
  data-amplitude-playlist="{playlist_key}">

Individual Song Slider

You can also add a song slider for an individual song like this:

<input
  type="range"
  class="amplitude-song-slider"
  data-amplitude-song-index="{song_index}">

Individual Song In Playlist Slider

You can also add a song slider for an individual song in a playlist like this:

<input
  type="range"
  class="amplitude-song-slider"
  data-amplitude-playlist="{playlist_key}"
  data-amplitude-song-index="{song_index}">

Song Progress Bar

There are 4 levels where you can add a song progress bar:

Global: Displays the current progress for the audio being played.
Playlist: Displays the current progress if the current song is in the playlist.
Individual Song: Displays the current progress for an individual song.
Individual Song in a Playlist: Displays the individual song current progress for a song in the playlist.

The song progress bar must be implemented with the HTML 5 progress element. This allows you full customization over the design. These operate the same as the range except you will have to implement your own slider event handling.

Global Song Progress Bar

To add a song progress bar, add the following:

<progress class="amplitude-song-played-progress"></progress>

Playlist Song Progress Bar

To add a playlist song progress bar, add the following:

<progress
  class="amplitude-song-played-progress"
  data-amplitude-playlist="{playlist_key}">
</progress>

Individual Song Progress Bar

To add an individual song progress bar, add the following:

<progress
  class="amplitude-song-played-progress"
  data-amplitude-song-index="{song_index}">
</progress>

Individual Song In Playlist Progress Bar

<progress
  class="amplitude-song-played-progress"
  data-amplitude-playlist="{playlist_key}"
  data-amplitude-song-index="{song_index}">
</progress>

Song Buffered Progress Bar

There are 4 levels for a song buffered progress bar:

Global: Displays the percentage of the song buffered for the current song.
Playlist: Displays the percentage of the song buffered for the current playlist song.
Individual Song: Displays the percentage of the song buffered for anindividual song.
Individual Song In Playlist: Displays the percentage of the song buffered for an individual song in a playlist.

The Song Buffered Progress Bar has to be an HTML 5 progress element. This is the proper semantic element for this use case. This allows for a visual display of how much of the song has been buffered. You can do some CSS techniques to overlay this progress element over the song-played-progress element to make an all in one, or you could leave it by itself.

Global Song Buffered Progress Bar

To add a song buffered progress element, add the following:

<progress class="amplitude-buffered-progress" value="0"></progress>

Playlist Song Buffered Progress Bar

To add a playlist song buffered progress element, add the following:

<progress
  class="amplitude-buffered-progress"
  data-amplitude-playlist="{playlist_key}"
  value="0">
</progress>

Individual Song Buffered Progress Bar

To add an individual song buffered progress element, add the following:

<progress
  class="amplitude-buffered-progress"
  data-amplitude-song-index="{song_index}"
  value="0">
</progress>

Individual Song In Playlist Buffered Progress Bar

To add an individual song in playlist buffered progress element, add the following:

<progress
  class="amplitude-buffered-progress"
  data-amplitude-song-index="{song_index}"
  data-amplitude-playlist="{playlist_key}"
  value="0">
</progress>

Metadata

Meta data elements get their information filled in with meta data from the active song object or on initialization from the keyed song in the array. These can be any type of HTML element except when filling in cover_art_url, station_art_url, or podcast_episode_cover_art_url.

These specific keys have to be on an img tag since they update the src attribute of the tag. Every other attribute fills in the inner html of the tag.

Image Metadata

When defining a song object there are 3 different keys you can define image meta data with:

cover_art_url
station_art_url
podcast_episode_cover_art_url

These URLs point to an image that will be substituted out for the active song image.

Text Metadata

With text metadata describing a song, you can use whatever information you like and place it in whatever element you like. This give much more flexibility when using Amplitude in a variety of audio scenarios such as for radio stations and podcasts. To add an element that contains a piece of meta data regarding the now playing song simply add:

<span data-amplitude-song-info="{song_meta_index}"></span>

If it’s an element for a playlist add the key for the playlist:

<span
  data-amplitude-song-info="{song_meta_index}"
  data-amplitude-playlist="{playlist_index}">
</span>

Autofill Meta Data

Sometimes when building a player, you don’t know what every song is on load and need to load songs dynamically. With Amplitude this is not a problem. Amplitude will autofill the meta data for lists of songs if you do a combination of the following on the element.

data-amplitude-song-info: Defines the information you want injected into the element. This is the key of the song object.
data-amplitude-song-index: Defines the index of the song in the songs array that you want to inject into the element.

This is super convenient when loading songs dynamically either server side or loading after the page has loaded.

Playlist Meta Data

When you add a playlist, you can add all sorts of other metadata to the playlist object, similar to who song objects work. Amplitude also takes care of initializing this data on the screen if you have your meta data element keyed up correctly. Let’s say you have a playlist title field represented by title in the playlist element that you want to display on the screen. You’d add an element that has the following attributes:

<span
  data-amplitude-playlist-info="title"
  data-amplitude-playlist="{playlist_key}">
</span>

Essentially you have to add an attribute with the key of the element and the playlist key in a format like this:

<span
  data-amplitude-playlist-info="{info}"
  data-amplitude-playlist="{playlist_key}">
</span>

Metadata for Time

There are certain elements that contain time data about the active song. You can add these elements to your document and they will auto fill with the current status of the song. Like other elements, these can be either for the overall player, scoped in a playlist or for a specific song.

There are three sets of time meta data:

current time
song duration
time remaining

The song duration can only be set for the active song since the metadata isn’t preloaded for all of the songs. The time remaining is a count down for how much time is left for a song.

Current Time

Current Time Metadata is used for the overall player referencing the global playlist defined by the songs array configured for an Amplitude instance.

Table 1. Current Time
Name	Value	Description
`amplitude-current-time`	Current Time	Format Current Time - Displays in MM:SS Example `<span class="amplitude-current-time"></span>`
`amplitude-current-hours`	Current Hours	Example `<span class="amplitude-current-hours"></span>`
`amplitude-current-minutes`	Current Minutes	Example `<span class="amplitude-current-minutes"></span>`
`amplitude-current-seconds`	Current Seconds	Example `<span class="amplitude-current-seconds"></span>`

Duration Time

Duration Time Metadata is used for the overall player referencing the global playlist defined by the songs array configured for an Amplitude instance.

Table 2. Duration Time
Name	Value	Description
`amplitude-duration-time`	Duration Time	Format Duration Time - Displays in MM:SS Example `<span class="amplitude-duration-time"></span>`
`amplitude-duration-hours`	Duration Hours	Example `<span class="amplitude-duration-hours"></span>`
`amplitude-duration-minutes`	Duration Minutes	Example `<span class="amplitude-duration-minutes"></span>`
`amplitude-duration-seconds`	Duration Seconds	Example `<span class="amplitude-duration-seconds"></span>`

Metadata for a Playlist

Format

Current Time For Playlist - Displays in MM:SS

<span
  class="amplitude-current-time"
  data-amplitude-playlist="{playlist_key}">
</span>

Current Hours For Playlist

<span
  class="amplitude-current-hours"
  data-amplitude-playlist="{playlist_key}">
</span>

Current Minutes For Playlist

<span
  class="amplitude-current-minutes"
  data-amplitude-playlist="{playlist_key}">
</span>

Current Seconds For Playlist

<span
  class="amplitude-current-seconds"
  data-amplitude-playlist="{playlist_key}">
</span>

Metadata for a Song

Format

Current Time For Song

<span
  class="amplitude-current-time"
  data-amplitude-song-index="{song_index}">
</span>

Current Hours For Song

<span
  class="amplitude-current-hours"
  data-amplitude-song-index="{song_index}">
</span>

Current Minutes For Song

<span
  class="amplitude-current-minutes"
  data-amplitude-song-index="{song_index}">
</span>

Current Seconds For Song

<span
  class="amplitude-current-seconds"
  data-amplitude-song-index="{song_index}">
</span>

Metadata for a Song in a Playlist

Current Time For Song In Playlist

<span
  class="amplitude-current-time"
  data-amplitude-playlist="{playlist_key}"
  data-amplitude-song-index="{song_index}">
</span>

Current Hours For Song In Playlist

<span
  class="amplitude-current-hours"
  data-amplitude-playlist="{playlist_key}"
  data-amplitude-song-index="{song_index}">
</span>

Current Minutes For Song In Playlist

<span
  class="amplitude-current-minutes"
  data-amplitude-playlist="{playlist_key}"
  data-amplitude-song-index="{song_index}">
</span>

Current Seconds For Song In Playlist

<span
  class="amplitude-current-seconds"
  data-amplitude-playlist="{playlist_key}"
  data-amplitude-song-index="{song_index}">
</span>

Duration Time For Playlist - Displays in MM:SS

<span
  class="amplitude-duration-time"
  data-amplitude-playlist="{playlist_key}">
</span>

Duration Hours For Playlist

<span
  class="amplitude-duration-hours"
  data-amplitude-playlist="{playlist_key}">
</span>

Duration Minutes For Playlist

<span
  class="amplitude-duration-minutes"
  data-amplitude-playlist="{playlist_key}">
</span>

Duration Seconds For Playlist

<span
  class="amplitude-duration-seconds"
  data-amplitude-playlist="{playlist_key}">
</span>

Duration Time For Song - Displays in MM:SS

<span
  class="amplitude-duration-time"
  data-amplitude-song-index="{song_index}">
</span>

Duration Hours For Song

<span
  class="amplitude-duration-hours"
  data-amplitude-song-index="{song_index}">
</span>

Duration Minutes For Song

<span
  class="amplitude-duration-minutes"
  data-amplitude-song-index="{song_index}">
</span>

Duration Seconds For Song

<span
  class="amplitude-duration-seconds"
  data-amplitude-song-index="{song_index}">
</span>

Main Time Remaining For Song

<span class="amplitude-time-remaining"></span>

Playlist Main Time Remaining For Song

<span
  class="amplitude-time-remaining"
  data-amplitude-playlist="{playlist_key}">
</span>

Song Time Remaining

<span
  class="amplitude-time-remaining"
  data-amplitude-song-index="{song_index}">
</span>

Song Container

This is a unique element. What this does is allow you to assign a container to the visual representation of a song or a song in a playlist. When that song is currently playing, the class amplitude-active-song-container will be applied to the song container element. This way you can style the element to show the active song.

For a single song container it would be:

<div class="amplitude-song-container" data-amplitude-song-index="{X}"></div>

For a playlist song container it would be:

<div
  class="amplitude-song-container"
  data-amplitude-playlist="{playlist_key}"
  data-amplitude-song-index="{song_index}">
</div>

Methods

Amplitude exposes a number of public methods that you can call from your own JavaScript code. Most pages do not need any of them: the CSS classes (amplitude-play, amplitude-pause, …) and data attributes described above already cover normal use. You only need the methods below when you want to:

add or remove songs after the page has loaded,
read the current player state for a custom display, or
change a setting (volume increment, default album art, …) on the fly.

All methods are called on the global Amplitude object, for example Amplitude.play().

Bind new Elements

The bind new elements function should be called whenever a new song element is added to the page. This will bind all of the event handlers for that element.

Amplitude.bindNewElements()

Add a Playlist

This method allows you to add a playlist to Amplitude. To do this, you need a unique key for your playlist, the data describing your playlist such as title, author, etc. and an array of song objects for your playlist.

Amplitude.addPlaylist( key, data, songs );

The first argument is the key. Remember this is a JSON key and should be formatted as such.

The second argument is all of the data describing the playlist such as name, title, author, etc. in the form of a JSON object.

Finally, the third argument is an array of song objects. These are the songs that will be added to the playlist.

Add a Song

Adds a song to the Amplitude player. You will need to write a method yourself to add the visual side of things to fit your custom design, and then call the bindNewElements() method to make sure it works.

This method returns the index of the song added to the player.

Amplitude.addSong( {song_object} );

Prepend a Song

Adds a song to the beginning of the Amplitude player. After pre-pending the song, you will have to bindNewElements() method to make sure that any visuals are updated as well.

This method returns the index of the song added to the player.

Amplitude.prependSong( {song_object} );

Add a Song to a Playlist

Adds a song to a specific playlist within Amplitude. Once the song is added you will need to update the visual side of the player yourself. After you update the visual side, run the Amplitude.bindNewElements() method to make sure the functionality is there for the new element.

Amplitude.addSongToPlaylist( songObject, playlistKey )

Remove a Song

Removes a song from the global song array. You will have to remove the containing element by yourself.

Amplitude.removeSong( indexOfSong )

Remove a Song From Playlist

Removes a song from a playlist. You will have to update the visual side by yourself.

Amplitude.removeSongFromPlaylist( indexOfSongInPlaylist, playlistKey )

Play

This simply plays whatever song is active.

Amplitude.play()

Play a Song At Index

Plays whatever song is set in the config at the specified index.

Amplitude.playSongAtIndex( songIndex )

Play a Playlist Song At Index

Plays the song in a playlist at the specified index.

Amplitude.playPlaylistSongAtIndex( playlistIndex, playlistKey )

Play Now

In Amplitude 2.0 this was referred to as 'Dynamic Mode'. Now you can just pass a song to Amplitude and it will automatically play. If there are visual elements, then they will sync as well.

Amplitude.playNow( {song_object} );

Pause

This simply pauses whatever song is active.

Amplitude.pause()

Stop

This simply stops whatever song is active.

Amplitude.stop()

Plays the next song either in the playlist or globally.

Amplitude.next( playlistKey = null )

Plays the previous song either in the playlist or globally.

Amplitude.prev( playlistKey = null )

Allows the user to skip to a specific location in the song whether that song is in a playlist or not.

Amplitude.skipTo( seconds, songIndex, playlist = null )

Register Visualization

The other way to register a visualization is through the public Amplitude.registerVisualization( visualization, preferences ) method. The first parameter being the object included with the visualization file and the second parameter being a JSON object containing any of the parameters needed to overwrite defaults provided by the visualization.

  Amplitude.registerVisualization( visualization, preferences );

Setters

Setter methods change a value inside Amplitude while the player is running. Use them when you need to react to something that happens after Amplitude.init(), for example: a user changes the album art, your back-end sends new song meta data, or a different playlist is selected. Each setter takes one or two arguments and returns nothing.

Set Default Album Art

Sets the default album art for the player to the URL provided.

Amplitude.setDefaultAlbumArt( url )

Set Default Playlist Art

Sets the default playlist art.

Amplitude.setDefaultPlaylistArt( url )

Set Debug

To change the debug mode setting, you can call the setDebug method any time and start to receive data about the state of the player or turn off debugging.

Amplitude.setDebug( {bool} );

Set Delay

If you have multiple songs that your player is using you can change the amount of time you have as a delay between the songs. When one song ends, what is set will be the amount of time delayed before the next song starts.

Amplitude.setDelay( milliseconds )

Set Global Visualization

You can set the global visualization through the public method like this:

  Amplitude.setGlobalVisualization( visualizationKey );

Set Playlist Visualization

You can set the visualization through the public facing method like this:

  Amplitude.setPlaylistVisualization( playlist_key, visualization_key );

Set Individual Song Visualization

You can set the visualization for an individual song like so:

  Amplitude.setSongVisualization( songIndex, visualizationKey );

Set Individual Song In Playlist Visualization

You can set the visualization for an individual song in a playlist using:

Amplitude.setSongInPlaylistVisualization( playlistKey, songIndex, visualizationKey );

Set Shuffle

Sets the global shuffle state for Amplitude.

Amplitude.setShuffle( shuffleState )

Set Shuffle Playlist

Sets the shuffle state for a playlist.

Amplitude.setShufflePlaylist( playlistKey, shuffleState )

Set Repeat

Sets the global repeat status for Amplitude

Amplitude.setRepeat( repeatState )

Set Repeat Song

Sets the global state to determine if we should repeat the individual song upon completion.

Amplitude.setRepeatSong( repeatSongState )

Set Repeat Playlist

Sets the repeat for the playlist.

Amplitude.setRepeatPlaylist( playlistKey, repeatState )

Set Song Played Percentage

This method allows you to set the percentage of the active song. The method accepts a float between 0 and 100 for the percentage of the song to be set to.

Amplitude.setSongPlayedPercentage( percentage )

Set Song Meta Data

You can set the meta data for any song in your song objects. This is helpful if you are doing a live stream and have a call back that returns the information of what song is currently playing.

Amplitude.setSongMetaData( index, metaData )

The first parameter index is the index of the song in the songs array you are setting the meta data for. The metaData is an object that contains meta data similar to a song object. The keys that get passed will be updated on the song object at the index. The only key that can not be updated is the url.

Set Playlist Meta Data

You can set the metadata for the playlist. Similar to the songs object, you can do it for a playlist object.

Amplitude.setPlaylistMetaData( playlist, metaData )

The first argument playlist is the key of the playlist we are setting the meta data for and the second object metaData is the object containing all of the keys we are updating.

Getters

Getter methods read a value from Amplitude without changing anything. They are most useful when you need to display the current state of the player (the active song, the current volume, whether shuffle is on, …) in your own custom UI, or when you want to log information for debugging. Each getter returns the value directly, so you can assign it to a variable: const state = Amplitude.getPlayerState();

Get Analyser

Returns the Web Audio API Analyser. This allows for the user to bind to the active audio through the web audio API.

Amplitude.getAnalyser()

Get Config

Returns the current Amplitude configuration.

Amplitude.getConfig();

Get Delay

Gets the current delay between songs in milliseconds.

Amplitude.getDelay();

Get Player State

Returns the current state of the player whether it’s playing, paused, or stopped.

Amplitude.getPlayerState()

Get Active Playlist

This method will return the key of the active playlist.

Amplitude.getActivePlaylist()

Get Playback Speed

Returns the current playback speed for the player.

Amplitude.getPlaybackSpeed()

Get Repeat

Returns the state of the global repeat status for the player.

Amplitude.getRepeat()

Get Repeat Playlist

Returns the state of the repeat status for the playlist.

Amplitude.getRepeatPlaylist( playlistKey )

Get Shuffle

Returns the current state of the global shuffle status for the player.

Amplitude.getShuffle()

Get Shuffle Playlist

Returns the state of the shuffle flag for a playlist.

Amplitude.getShufflePlaylist( playlistKey )

Get Default Album Art

Returns the default album art URL set in the player.

Amplitude.getDefaultAlbumArt()

Get Default Playlist Art

Gets the default art for a playlist.

Amplitude.getDefaultPlaylistArt()

Get Active Song Metadata

Returns the active song’s metadata as a JSON object.

Amplitude.getActiveSongMetadata();

Get Active Playlist Metadata

Gets the active playlist’s metadata as a JSON object.

Amplitude.getActivePlaylistMetadata();

Get Active Index

This method returns the index of the active song in the songs array.

Amplitude.getActiveIndex()

Get Active Index State

This method returns the index of the active song in the songs array but accounts for if shuffle has been enabled or not.

Amplitude.getActiveIndexState()

Get Audio

This returns the actual audio element. This is mainly used for writing extensions but exposes the core of Amplitude. This returns the audio element used by Amplitude.

Amplitude.getAudio()

Get Buffered

This method returns the buffered percentage of the now playing song. This can be used to show how much of the song has been buffered and ready to be played.

Amplitude.getBuffered()

Get songs

This method returns all of the songs defined in Amplitude. It can be used for a variety of different functions. It’s extremely helpful if you are AJAX loading songs and want to see the contents of the song array.

Amplitude.getSongs()

Get Songs In Playlist

This method returns all of the songs in a playlist. Since the user defines a playlist with a key and the indexes of the songs, this will map the keys to the songs and return all of the songs in the playlist.

Amplitude.getSongsInPlaylist( playlistKey )

Get Songs State

This method returns the current order of the songs. It can be used for determining what song is next. If shuffle is on, it will return the shuffled list of songs.

Amplitude.getSongsState()

Get Songs State Playlist

This method returns the current order of the songs in a playlist. If needed this can be used to determine the next song in a playlist. This accounts for whether the playlist has been shuffled or not.

Amplitude.getSongsStatePlaylist( playlist )

Get Song Played Percentage

This method returns the percentage of the song played. When implementing a 3rd party tracking element, you can set the percentage of the element to the percentage played of the song.

Amplitude.getSongPlayedPercentage()

You can combine this method with the time_update callback and whenever the time updates your method can call Amplitude.getSongPlayedPercentage() and you can set your tracking element correctly.

Get Song Played Seconds

This method returns the current seconds the user is into the song.

Amplitude.getSongPlayedSeconds()

Get Song Duration

Returns the duration of the current song.

Amplitude.getSongDuration()

Get Song At Index

Returns a song’s metadata at a specific index.

Amplitude.getSongAtIndex( {index} );

Get Song At Playlist Index

Returns a song at a playlist’s index.

Amplitude.getSongAtPlaylistIndex( {playlistIndex}, {index} );

Get Version

This method returns the version of Amplitude being used.

Amplitude.getVersion()

Notes on Implementation

Amplitude 4.0 was one of the biggest releases thus far. We tried to limit the breaking changes, but in order to scale for the future we had to make a few.

Amplitude Attributes Have HTML5 Dataset Prefix

In order to make Amplitude validated properly by w3 terms, we prefixed all of the attributes on Amplitude elements to have the data- prefix. This makes all of the attributes compatible with the HTML5 dataset API.

What this means is any time you are defining a specific element for a song or playlist, you will have to use data-amplitude-song-index or data-amplitude-playlist. In 3.x releases, these were just amplitude-song-index or amplitude-playlist. In order to work with 4.0 and above, you will have to update these references.

Standard Attributes For Defining Elements

In versions 3.x, we had a variety of different attributes to define an element based on it’s level of use. For example, if we had a global play/pause button it’d be amplitude-main-play-pause="true" as an attribute.

This got really cumbersome with multiple elements existing on either a global level (controlling the entire player), a playlist level (controlling functions within a playlist), a song level (controlling an individual song), and a song in playlist level (controlling a song within a playlist).

Now everything is based on a combination of attributes. These are as follows:

Global Level: class="amplitude-{specialized-class}" Playlist Level: class="amplitude-{specialized-class}" data-amplitude-playlist="{playlist}" Song Level: class="amplitude-{specialized-class}" data-amplitude-song-index="{songIndex}" Song In Playlist: class="amplitude-{specialized-class}" data-amplitude-song-index="{songIndex}" data-amplitude-playlist="{playlist}" These combinations work for all elements that are in Amplitude. Now there are some elements that don’t span all of the scopes. Let’s take an amplitude-volume-up element. This only works on the global level. It wouldn’t make sense to have individual playlist volumes.

Playlist Song Indexes Are Scoped To Playlist

In versions 3.x song indexes are now scoped to playlists. What this means is that when you use data-amplitude-song-index on a song display in a playlist, it references the index of the song in the playlist instead of the songs array.

For example if song index 1 is used on the 'Hip Hop' playlist, it references song index 1 within that playlist. Before it was the index in the songs array.

Next And Previous Buttons Only Work In Playlists If Playlist Is Active

So there are two levels of next and previous buttons. The global level which will react to the state of the player and the playlist level. If a global level next button or previous button is clicked, it will either go to the next/previous song in the songs array if no playlist is active, or the next/previous song in the playlist if a playlist is active.

Now on the playlist level the buttons only go to the next/previous song in the playlist when clicked and ONLY if the playlist is active. If you click a next/previous button on a playlist that isn’t active, it doesn’t do anything. It will only print a debug message if debug is turned on.

Autoplay Configuration Has Been Removed

Most browsers do not support autoplay features anymore. The functionality to set up Amplitude for autoplay has been removed. If you initialize with autoplay, it will just be ignored.

That should be the migrations! If you ran into anything, please reach out and we can lend a hand!

Examples

The J1 Template suports audio files, e.g. mp3, using custom players based on Amplitude. Three types of AmplitudeJS players are build-in for the J1 template system:

Mini Player
Compact Player (default)
Large Player

Amplitude player for the J1 Template are mobile-friendly. Instead of clicking on the appropriate elements, touch events are applied to all mobile devices. The color scheme used matches the look and feel of the template to preserve the page design.

Native player

The examples below use only the built-in HTML5 audio engine of your browser. The audio file (e.g. an MP3) is loaded directly from the web server. No external service is involved. This is the simplest and most reliable way to add audio to a J1 page. Use a native player when you host the audio file yourself.

Mini player

In the context of complex components on a web page, like an audio player, a mini player refers to a minimized version of full players. It typically offers basic playback controls, such as pause, play, and volume adjustment, while taking up less screen space.

Emancipator · From Dusk To Dawn

Mini players are beneficial when you want to listen to audio in the background without dedicating the entire screen to the player. They are commonly found on music streaming services, podcast platforms, and websites with embedded audio content.

Compact player

The design of a Compact player is an efficient approach that involves condensing the player controls and display elements into a smaller area. It allows the audio player to fit neatly within the web page’s layout without overwhelming or dominating the content around it.

Emancipator · From Dusk To Dawn

The player aims to balance functionality and space efficiency, ensuring users can easily access and control the audio playback without sacrificing too much screen space or placing multiple players side-by-side.

Large player

The Large player is the full-featured Amplitude player. It shows the album cover at full size, displays a scrollable playlist next to the controls, and offers every button (play, pause, previous, next, shuffle, repeat, skip, volume) directly on the page. Use it whenever the player is the main content of a page or section.

Emancipator · From Dusk To Dawn

The large design provides the full functionality of an audio player to ensure users can easily control audio playback. The player behaves similarly to a compact player, but all controls are displayed in a single window; there is no need to open other widgets.

Player over YouTube

The examples below show how to play the audio track of a YouTube video through an Amplitude player. The J1 Template provides a small plugin called ytp that extends the standard Amplitude API so it can read YouTube as if it were a normal audio file. Only the audio part is played — the YouTube video itself is hidden.

The YouTube plugin is only available inside the J1 Template under the name ytp. At the moment it works only with the Large player.

Behind the scenes, the plugin loads a hidden YouTube <iframe> player and forwards every button click (play, pause, next, …) to it. From your point of view, the player looks and feels exactly like a normal audio player with a playlist — you do not have to learn the YouTube API to use it.

Bea and her Business

Bea (Wheeler) is a young British pop singer. She writes songs about real life, feelings, and growing up. Many people like her because her music is honest, funny, and authentic.

Bea and her Business · YouTube 2025

Diana Krall

Diana Krall is a famous Canadian jazz singer and pianist. She was born on November 16, 1964, in Nanaimo, British Columbia. She became a star with albums such as Stepping Out (1993) and When I Look in Your Eyes (1999), which earned her a Grammy for Best Jazz Vocal. Her style mixes classic jazz standards with her deep voice and strong piano skills.

Diana Krall · YouTube

HTML Elements

Structure for Elements

Interactive Elements

Play Button

Global Play Button

Playlist Play Button

Individual Song Play Button

Individual Song In Playlist Button

Pause Button

Global Pause

Playlist Pause

Individual Song Pause

Individual Song In Playlist Pause

Play Pause Button

Global Play/Pause

Playlist Play/Pause

Song Play/Pause

Song In Playlist Play/Pause

Stop Button

Mute Button

Volume Up

Volume Down

Volume Slider

Next Button

Global Next Button

Playlist Next Button

Previous Button

Global Previous Button

Playlist Previous Button

Shuffle Button

Global Shuffle Button

Playlist Shuffle Button

Repeat Button

Global Repeat Button

Playlist Repeat Button

Repeat Song Button

Playback Speed Button

Skip To Link

Individual Song Link

Individual Song In Playlist Link

Song Tracking Slider (HTML 5 Range)

Global Song Slider

Playlist Song Slider

Individual Song Slider

Individual Song In Playlist Slider

Song Progress Bar

Global Song Progress Bar

Playlist Song Progress Bar

Individual Song Progress Bar

Individual Song In Playlist Progress Bar

Song Buffered Progress Bar

Global Song Buffered Progress Bar

Playlist Song Buffered Progress Bar

Individual Song Buffered Progress Bar

Individual Song In Playlist Buffered Progress Bar

Metadata

Image Metadata

Text Metadata

Autofill Meta Data

Playlist Meta Data

Metadata for Time

Current Time

Duration Time

Metadata for a Playlist

Metadata for a Song

Metadata for a Song in a Playlist

Song Container

Methods

Bind new Elements

Add a Playlist

Add a Song

Prepend a Song

Add a Song to a Playlist

Remove a Song

Remove a Song From Playlist

Play

Play a Song At Index

Play a Playlist Song At Index

Play Now

Pause