AmplitudeJS API · Control Audio Players

The audio tag in HTML5 is a great way to add audio media to web pages. However, the browser fully controls the audio playback interface, which can limit or even break a page’s design if audio media is used.

AmplitudeJS for the J1 Template offers a straightforward solution for web developers. It allows them to easily customize the appearance of their audio players without the need for complex scripting. By leveraging J1 Template and Amplitude’s API, web designers can craft unique interfaces that define the visual and functional aspects of a player’s audio control elements.

5-10 Minutes to read

Elements

AmplitudeJS comes with a variety of elements. Each element is picked up by a class prefixed with amplitude- and depending on the environment, an attribute that relates to the index of a song in your list of songs or a playlist you are using the element with. There are elements that some events are bound to such as play and next and other elements that get filled with meta data information about the active audio.

All elements can be styled simply based of off class or if you want to define specific ids in CSS. Besides album art, you could apply these classes to a variety of elements. Album art has to be an <img> element, but the other elements could be whatever.

Structure for Elements

AmplitudeJS has a standardized way to reference an element whether it’s a metadata element or an interactive element. There are 4 levels of elements:

Global: Global elements control whatever is playing no matter the scope, or display whatever is playing no matter the scope.
Playlist: Playlist elements control within the scope of the playlist and display what’s in the scope of the playlist.
Song: Song elements control what’s in the scope of the song and what’s displayed for the song.
Song In Playlist: Songs in playlist elements control what’s in the the scope of the song in the playlist.

Not all elements have all 4 levels of functionality. For example, any element that deals with volume does not have anything but a global scope meaning you can’t adjust volume for a single song or playlist it’s handled globally.

To scope an element or metadata display the following combination of classes and attributes should be provided:

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 s song in Playlist element is the index references the index of the song within the playlist! This is different than the song element that references the index of the song within the songs array!

Interactive Elements

The interactive elements of AmplitudeJS 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 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 AmplitudeJS. 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 3 levels of Play/Pause buttons.

Global Play/Pause - Plays or pauses the active song no matter if it’s independent 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 AmplitudeJS 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 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>

The volume by the amount specified on 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 increment 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 up element add:

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

The volume by the amount specified on 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

AmplitudeJS extends functionality for the audio tag by allowing designers and developers to build playlists. When a next button has been added AmplitudeJS 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 AmplitudeJS. 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, AmplitudeJS 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 where if shuffle is turned off ampltiude-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 eneded.

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 sate 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 AmplitudeJS. 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 AmplitudeJS 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 AmplitudeJS this is not a problem. AmplitudeJS 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. AmplitudeJS 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 AmplitudeJS 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 AmplitudeJS instance.

Table 2. Duration Time
Name	Value	Description
`amplitude-duration-time`	Duration Hours	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"></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

There are a variety of public functions that AmplitudeJS exposes to the user. These methods allow the user to change config variables, add new songs, play now, etc.

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 AmplitudeJS. 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 AmplitudeJS 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 AmplitudeJS 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 AmplitudeJS. 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 AmplitudeJS 2.0 this was referred to as 'Dynamic Mode'. Now you can just pass a song to AmplitudeJS 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

Bla, bla …

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 AmplitudeJS.

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 AmplitudeJS

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

Bla, bla …

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 AmplitudeJS 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 Album Art

Returns the URL of the default album art for 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 AmplitudeJS. This returns the audio element used by AmplitudeJS.

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 AmplitudeJS. 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()Individual Song Slider

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 AmplitudeJS being used.

Amplitude.getVersion()

Notes on Implementaion

AmplitudeJS 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.

AmplitudeJS Attributes Have HTML5 Dataset Prefix

In order to make AmplitudeJS validated properly by w3 terms, we prefixed all of the attributes on AmplitudeJS 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 AmplitudeJS. 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 AmplitudeJS 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!