j1-template 2024.3.17 → 2024.3.18

data/lib/starter_web/pages/public/manuals/integrations/amplitudejs/amplitudejs-api.adoc

@@ -1,2260 +0,0 @@
----
-title:                                  AmplitudeJS API
-title_extention:                        Integration for J1 Template
-tagline:                                User Guide
-
-date:                                   2024-04-17
-#last_modified:                         2024-01-01
-
-description: >
-                                        AmplitudeJS is a JavaScript library to control the design of audio media
-                                        elements on web pages. The concept allows designers to fully control the
-                                        look and feel of audio players without deep scripting knowledge.
-keywords: >
-                                        open source, free, template, jekyll, jekyllone, web,
-                                        sites, static, jamstack, bootstrap, html, html5, audio,
-                                        Amplitude
-
-categories:                             [ Manuals ]
-tags:                                   [ API, AmplitudeJS ]
-
-image:
-  path:                                 /assets/image/icons/videojs/videojs-poster.png
-  width:                                1920
-  height:                               1280
-
-regenerate:                             false
-personalization:                        true
-permalink:                              /pages/public/manuals/integrations/amplitudejs/amplitudejs_api/
-
-resources:                              [ amplitudejs, rouge ]
-resource_options:
-  - toccer:
-      collapseDepth:                    3
-  - attic:
-      slides:
-        - url:                          /assets/image/modules/attics/1920x1280/alexey-ruban.jpg
-          alt:                          Photo by Alexey Ruban on Unsplash
-          badge:
-            type:                       unsplash
-            author:                     Alexey Ruban
-            href:                       //unsplash.com/de/@intelligenciya
----
-
-// Page Initializer
-// =============================================================================
-// Enable the Liquid Preprocessor
-:page-liquid:
-
-// Set (local) page attributes here
-// -----------------------------------------------------------------------------
-// :page--attr:                         <attr-value>
-
-//  Load Liquid procedures
-// -----------------------------------------------------------------------------
-{% capture load_attributes %}themes/{{site.template.name}}/procedures/global/attributes_loader.proc{%endcapture%}
-
-// Load page attributes
-// -----------------------------------------------------------------------------
-{% include {{load_attributes}} scope="global" %}
-
-// Page content
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-// See: https://521dimensions.com/open-source/amplitudejs/docs
-// See: https://github.com/mediaelement/mediaelement-plugins
-// See: https://github.com/serversideup/amplitudejs/
-
-[role="dropcap"]
-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.
-
-mdi:clock-time-five-outline[24px, md-gray mr-2]
-*5-10 Minutes* to read
-
-
-// Include sub-documents (if any)
-// -----------------------------------------------------------------------------
-[role="mt-5"]
-== 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.
-
-[role="mt-4"]
-=== 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!
-
-[role="mt-4"]
-=== 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.
-
-[role="mt-4"]
-==== 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.
-
-[NOTE]
-====
-The play button responds to the 'click' event on a desktop or a
-*touchstart* event on *mobile* devices.
-====
-
-[role="mt-4"]
-===== 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`.
-
-[source, html]
-----
-<span class="amplitude-play"></span>
-----
-
-[role="mt-4"]
-===== 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"`.
-
-[source, html]
-----
-<span class="amplitude-play" data-amplitude-playlist="{playlist_index}"></span>
-----
-
-[role="mt-4"]
-===== Individual Song Play Button
-
-The individual song play button will play the song defined by the
-`data-amplitude-song-index="{song_index}"` attribute.
-
-[source, html]
-----
-<span class="amplitude-play" data-amplitude-song-index="{song_index}"></span>
-----
-
-[role="mt-4"]
-===== 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.
-
-[source, html]
-----
-<span
-  class="amplitude-play"
-  data-amplitude-song-index="1"
-  data-amplitude-playlist="test_playlist">
-</span>
-----
-
-[role="mt-4"]
-==== 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.
-
-[role="mt-4"]
-===== 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'.
-
-[source, html]
-----
-<span class="amplitude-pause"></span>
-----
-
-[role="mt-4"]
-===== 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.
-
-[source, html]
-----
-<span class="amplitude-pause" data-amplitude-playlist="{playlist}"></span>
-----
-
-[role="mt-4"]
-===== Individual Song Pause
-
-The individual song pause button will pause the song defined by the
-attribute `data-amplitude-song-index="song_index"`.
-
-[source, html]
-----
-<span class="amplitude-pause" data-amplitude-song-index="{song_index}"></span>
-----
-
-[role="mt-4"]
-===== 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.
-
-[source, html]
-----
-<span
-  class="amplitude-pause"
-  data-amplitude-song-index="{song_index}"
-  data-amplitude-playlist="{playlist}">
-</span>
-----
-
-[role="mt-4"]
-==== 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.
-
-[role="mt-4"]
-[[global-play-pause]]
-===== 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.
-
-[source, html]
-----
-<span class="amplitude-play-pause"></span>
-----
-
-[role="mt-4"]
-[[playlist-play-pause]]
-===== 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}`.
-
-[source, html]
-----
-<span class="amplitude-play-pause" data-amplitude-playlist="{playlist}"></span>
-----
-
-[role="mt-4"]
-[[song-play-pause]]
-===== Song Play/Pause
-
-The song play pause button plays or pauses an individual song when
-clicked.
-
-[source, html]
-----
-<span class="amplitude-play-pause" data-amplitude-song-index="{song_index}"></span>
-----
-
-[role="mt-4"]
-[[song-in-playlist-play-pause]]
-===== 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.
-
-[source, html]
-----
-<span
-  class="amplitude-play-pause"
-  data-amplitude-song-index="{song_index}"
-  data-amplitude-playlist="{playlist}">
-</span>
-----
-
-[role="mt-4"]
-==== 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:
-
-[source, html]
-----
-<span class="amplitude-stop"></span>
-----
-
-[role="mt-4"]
-==== 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.
-
-[source, html]
-----
-<span class="amplitude-mute"></span>
-----
-
-[role="mt-4"]
-==== 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:
-
-[source, html]
-----
-<span class="amplitude-volume-up"></span>
-----
-
-[NOTE]
-====
-The volume by the amount specified on init. The default value is 5%
-====
-
-[role="mt-4"]
-==== 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:
-
-[source, html]
-----
-<span class="amplitude-volume-down"></span>
-----
-
-[NOTE]
-====
-The volume by the amount specified on init. The default value is 5%
-====
-
-[role="mt-4"]
-==== 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:
-
-[source, html]
-----
-<input type="range" class="amplitude-volume-slider">
-----
-
-[role="mt-4"]
-==== 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.
-
-[role="mt-4"]
-===== Global Next Button
-
-To add a global next button add the following HTML code:
-
-[source, html]
-----
-<span class="amplitude-next"></span>
-----
-
-===== Playlist Next Button
-
-To add a playlist next button add the following HTML code:
-
-[source, html]
-----
-<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.
-
-[role="mt-4"]
-==== 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.
-
-[role="mt-4"]
-===== Global Previous Button
-
-To add a global previous button add the following HTML code:
-
-[source, html]
-----
-<span class="amplitude-prev"></span>
-----
-
-===== Playlist Previous Button
-
-To add a playlist previous button add the following HTML code:
-
-[source, html]
-----
-<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.
-
-[role="mt-4"]
-==== 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.
-
-[role="mt-4"]
-===== Global Shuffle Button
-
-To add a shuffle button add the following HTML code:
-
-[source, html]
-----
-<span class="amplitude-shuffle"></span>
-----
-
-[role="mt-4"]
-===== Playlist Shuffle Button
-
-To add a playlist shuffle button add the following HTML code:
-
-[source, html]
-----
-<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.
-
-[role="mt-4"]
-==== 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.
-
-[role="mt-4"]
-===== Global Repeat Button
-
-To add the repeat button, add the following HTML code:
-
-[source, html]
-----
-<span class="amplitude-repeat"></span>
-----
-
-[role="mt-4"]
-===== Playlist Repeat Button
-
-To add a playlist repeat button, add the following HTML code:
-
-[source, html]
-----
-<span class="amplitude-repeat" data-amplitude-playlist="{playlist_key}"></span>
-----
-
-[role="mt-4"]
-==== 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:
-
-[source, html]
-----
-<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:
-
-[source, html]
-----
-<span class="amplitude-playback-speed"></span>
-----
-
-[role="mt-4"]
-==== Skip To Link
-
-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.
-
-[role="mt-4"]
-===== Individual Song Link
-
-An example song link would be:
-
-[source, html]
-----
-<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.
-
-[role="mt-4"]
-===== Individual Song In Playlist Link
-
-An example of an individual song in playlist link would be:
-
-[source, html]
-----
-<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!
-
-[role="mt-4"]
-==== 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
-https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Range[Content-Range HTTP headers, {browser-window--new}].
-
-[role="mt-4"]
-===== Global Song Slider
-
-To add a global song slider, add the following element:
-
-[source, html]
-----
-<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.
-
-[role="mt-4"]
-===== Playlist Song Slider
-
-If you want to do an individual playlist, you can add the attribute of
-`data-amplitude-playlist="{playlist_key}"`.
-
-[source, html]
-----
-<input
-  type="range"
-  class="amplitude-song-slider"
-  data-amplitude-playlist="{playlist_key}">
-----
-
-[role="mt-4"]
-===== Individual Song Slider
-
-You can also add a song slider for an individual song like this:
-
-[source, html]
-----
-<input
-  type="range"
-  class="amplitude-song-slider"
-  data-amplitude-song-index="{song_index}">
-----
-
-[role="mt-4"]
-===== Individual Song In Playlist Slider
-
-You can also add a song slider for an individual song in a playlist like
-this:
-
-[source, html]
-----
-<input
-  type="range"
-  class="amplitude-song-slider"
-  data-amplitude-playlist="{playlist_key}"
-  data-amplitude-song-index="{song_index}">
-----
-
-[role="mt-4"]
-==== 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.
-
-[role="mt-4"]
-===== Global Song Progress Bar
-
-To add a song progress bar, add the following:
-
-[source, html]
-----
-<progress class="amplitude-song-played-progress"></progress>
-----
-
-[role="mt-4"]
-===== Playlist Song Progress Bar
-
-To add a playlist song progress bar, add the following:
-
-[source, html]
-----
-<progress
-  class="amplitude-song-played-progress"
-  data-amplitude-playlist="{playlist_key}">
-</progress>
-----
-
-[role="mt-4"]
-===== Individual Song Progress Bar
-
-To add an individual song progress bar, add the following:
-
-[source, html]
-----
-<progress
-  class="amplitude-song-played-progress"
-  data-amplitude-song-index="{song_index}">
-</progress>
-----
-
-[role="mt-4"]
-===== Individual Song In Playlist Progress Bar
-
-[source, html]
-----
-<progress
-  class="amplitude-song-played-progress"
-  data-amplitude-playlist="{playlist_key}"
-  data-amplitude-song-index="{song_index}">
-</progress>
-----
-
-[role="mt-4"]
-==== 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.
-
-[role="mt-4"]
-===== Global Song Buffered Progress Bar
-
-To add a song buffered progress element, add the following:
-
-[source, html]
-----
-<progress class="amplitude-buffered-progress" value="0"></progress>
-----
-
-[role="mt-4"]
-===== Playlist Song Buffered Progress Bar
-
-To add a playlist song buffered progress element, add the following:
-
-[source, html]
-----
-<progress
-  class="amplitude-buffered-progress"
-  data-amplitude-playlist="{playlist_key}"
-  value="0">
-</progress>
-----
-
-[role="mt-4"]
-===== Individual Song Buffered Progress Bar
-
-To add an individual song buffered progress element, add the following:
-
-[source, html]
-----
-<progress
-  class="amplitude-buffered-progress"
-  data-amplitude-song-index="{song_index}"
-  value="0">
-</progress>
-----
-
-[role="mt-4"]
-===== Individual Song In Playlist Buffered Progress Bar
-
-To add an individual song in playlist buffered progress element, add the
-following:
-
-[source, html]
-----
-<progress
-  class="amplitude-buffered-progress"
-  data-amplitude-song-index="{song_index}"
-  data-amplitude-playlist="{playlist_key}"
-  value="0">
-</progress>
-----
-
-
-[role="mt-5"]
-== 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.
-
-[role="mt-4"]
-=== 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.
-
-[role="mt-4"]
-=== 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:
-
-[source, html]
-----
-<span data-amplitude-song-info="{song_meta_index}"></span>
-----
-
-If it's an element for a playlist add the key for the playlist:
-
-[source, html]
-----
-<span
-  data-amplitude-song-info="{song_meta_index}"
-  data-amplitude-playlist="{playlist_index}">
-</span>
-----
-
-[role="mt-4"]
-=== 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.
-
-[role="mt-4"]
-=== 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:
-
-[source, html]
-----
-<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:
-
-[source, html]
-----
-<span
-  data-amplitude-playlist-info="{info}"
-  data-amplitude-playlist="{playlist_key}">
-</span>
-----
-
-[role="mt-4"]
-=== 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.
-
-[role="mt-4"]
-==== 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.
-
-.Current Time
-[cols="3,3a,6a", subs=+macros, options="header", width="100%", role="rtable mt-3"]
-|===
-|Name |Value |Description
-
-|`amplitude-current-time`
-|Current Time
-|
-.Format
-----
-Current Time - Displays in MM:SS
-----
-
-.Example
-[source, html]
-----
-<span class="amplitude-current-time"></span>
-----
-
-|`amplitude-current-hours`
-|Current Hours
-|
-.Example
-[source, html]
-----
-<span class="amplitude-current-hours"></span>
-----
-
-|`amplitude-current-minutes`
-|Current Minutes
-|
-.Example
-[source, html]
-----
-<span class="amplitude-current-minutes"></span>
-----
-
-|`amplitude-current-seconds`
-|Current Seconds
-|
-.Example
-[source, html]
-----
-<span class="amplitude-current-seconds"></span>
-----
-
-|===
-
-
-[role="mt-4"]
-==== 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.
-
-.Duration Time
-[cols="3,3a,6a", subs=+macros, options="header", width="100%", role="rtable mt-3"]
-|===
-|Name |Value |Description
-
-|`amplitude-duration-time`
-|Duration Hours
-|
-.Format
-----
-Duration Time - Displays in MM:SS
-----
-
-.Example
-[source, html]
-----
-<span class="amplitude-duration-time"></span>
-----
-
-|`amplitude-duration-hours`
-|Duration Hours
-|
-.Example
-[source, html]
-----
-<span class="amplitude-duration-hours"></span>
-----
-
-|`amplitude-duration-minutes`
-|Duration Minutes
-|
-.Example
-[source, html]
-----
-<span class="amplitude-duration-minutes"></span>
-----
-
-|`amplitude-duration-seconds`
-|Duration Seconds
-|
-.Example
-[source, html]
-----
-<span class="amplitude-duration-seconds"></span>
-----
-
-|===
-
-
-[role="mt-4"]
-==== Metadata for a Playlist
-
-.Format
-----
-Current Time For Playlist - Displays in MM:SS
-----
-
-[source, html]
-----
-<span
-  class="amplitude-current-time"
-  data-amplitude-playlist="{playlist_key}">
-</span>
-----
-
-Current Hours For Playlist
-
-[source, html]
-----
-<span
-  class="amplitude-current-hours"
-  data-amplitude-playlist="{playlist_key}">
-</span>
-----
-
-Current Minutes For Playlist
-
-[source, html]
-----
-<span
-  class="amplitude-current-minutes"
-  data-amplitude-playlist="{playlist_key}">
-</span>
-----
-
-Current Seconds For Playlist
-
-[source, html]
-----
-<span
-  class="amplitude-current-seconds"
-  data-amplitude-playlist="{playlist_key}">
-</span>
-----
-
-
-[role="mt-4"]
-==== Metadata for a Song
-
-.Format
-----
-Current Time For Song
-----
-
-[source, html]
-----
-<span
-  class="amplitude-current-time"
-  data-amplitude-song-index="{song_index}">
-</span>
-----
-
-.Current Hours For Song
-[source, html]
-----
-<span
-  class="amplitude-current-hours"
-  data-amplitude-song-index="{song_index}">
-</span>
-----
-
-Current Minutes For Song
-
-[source, html]
-----
-<span
-  class="amplitude-current-minutes"
-  data-amplitude-song-index="{song_index}">
-</span>
-----
-
-Current Seconds For Song
-
-[source, html]
-----
-<span
-  class="amplitude-current-seconds"
-  data-amplitude-song-index="{song_index}">
-</span>
-----
-
-[role="mt-4"]
-==== Metadata for a Song in a Playlist
-
-Current Time For Song In Playlist
-
-[source, html]
-----
-<span
-  class="amplitude-current-time"
-  data-amplitude-playlist="{playlist_key}"
-  data-amplitude-song-index="{song_index}">
-</span>
-----
-
-Current Hours For Song In Playlist
-[source, html]
-----
-<span
-  class="amplitude-current-hours"
-  data-amplitude-playlist="{playlist_key}"
-  data-amplitude-song-index="{song_index}">
-</span>
-----
-
-Current Minutes For Song In Playlist
-
-[source, html]
-----
-<span
-  class="amplitude-current-minutes"
-  data-amplitude-playlist="{playlist_key}"
-  data-amplitude-song-index="{song_index}">
-</span>
-----
-
-Current Seconds For Song In Playlist
-
-[source, html]
-----
-<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
-
-[source, html]
-----
-<span class="amplitude-duration-time"></span>
-----
-
-Duration Hours For Playlist
-
-[source, html]
-----
-<span
-  class="amplitude-duration-hours"
-  data-amplitude-playlist="{playlist_key}">
-</span>
-----
-
-Duration Minutes For Playlist
-
-[source, html]
-----
-<span
-  class="amplitude-duration-minutes"
-  data-amplitude-playlist="{playlist_key}">
-</span>
-----
-
-Duration Seconds For Playlist
-
-[source, html]
-----
-<span
-  class="amplitude-duration-seconds"
-  data-amplitude-playlist="{playlist_key}">
-</span>
-----
-
-Duration Time For Song - Displays in MM:SS
-
-[source, html]
-----
-<span
-  class="amplitude-duration-time"
-  data-amplitude-song-index="{song_index}">
-</span>
-----
-
-Duration Hours For Song
-
-[source, html]
-----
-<span
-  class="amplitude-duration-hours"
-  data-amplitude-song-index="{song_index}">
-</span>
-----
-
-Duration Minutes For Song
-
-[source, html]
-----
-<span
-  class="amplitude-duration-minutes"
-  data-amplitude-song-index="{song_index}">
-</span>
-----
-
-Duration Seconds For Song
-
-[source, html]
-----
-<span
-  class="amplitude-duration-seconds"
-  data-amplitude-song-index="{song_index}">
-</span>
-----
-
-Main Time Remaining For Song
-
-[source, html]
-----
-<span class="amplitude-time-remaining"></span>
-----
-
-Playlist Main Time Remaining For Song
-
-[source, html]
-----
-<span
-  class="amplitude-time-remaining"
-  data-amplitude-playlist="{playlist_key}">
-</span>
-----
-
-Song Time Remaining
-
-[source, html]
-----
-<span
-  class="amplitude-time-remaining"
-  data-amplitude-song-index="{song_index}">
-</span>
-----
-
-[role="mt-4"]
-=== 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:
-
-[source, html]
-----
-<div class="amplitude-song-container" data-amplitude-song-index="{X}"></div>
-----
-
-For a playlist song container it would be:
-
-[source, html]
-----
-<div
-  class="amplitude-song-container"
-  data-amplitude-playlist="{playlist_key}"
-  data-amplitude-song-index="{song_index}">
-</div>
-----
-
-[role="mt-5"]
-== 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.
-
-[role="mt-4"]
-=== 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.
-
-[source, js]
-----
-Amplitude.bindNewElements()
-----
-
-[role="mt-4"]
-=== 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.
-
-[source, js]
-----
-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.
-
-[role="mt-4"]
-=== 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.
-
-[source, js]
-----
-Amplitude.addSong( {song_object} );
-----
-
-[role="mt-4"]
-=== 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.
-
-[source, js]
-----
-Amplitude.prependSong( {song_object} );
-----
-
-[role="mt-4"]
-=== 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.
-
-[source, js]
-----
-Amplitude.addSongToPlaylist( songObject, playlistKey )
-----
-
-[role="mt-4"]
-=== Remove a Song
-
-Removes a song from the global song array. You will have to remove the
-containing element by yourself.
-
-[source, js]
-----
-Amplitude.removeSong( indexOfSong )
-----
-
-[role="mt-4"]
-=== Remove a Song From Playlist
-
-Removes a song from a playlist. You will have to update the visual side
-by yourself.
-
-[source, js]
-----
-Amplitude.removeSongFromPlaylist( indexOfSongInPlaylist, playlistKey )
-----
-
-[role="mt-4"]
-=== Play
-
-This simply plays whatever song is active.
-
-[source, js]
-----
-Amplitude.play()
-----
-
-[role="mt-4"]
-=== Play a Song At Index
-
-Plays whatever song is set in the config at the specified index.
-
-[source, js]
-----
-Amplitude.playSongAtIndex( songIndex )
-----
-
-[role="mt-4"]
-=== Play a Playlist Song At Index
-
-Plays the song in a playlist at the specified index.
-
-[source, js]
-----
-Amplitude.playPlaylistSongAtIndex( playlistIndex, playlistKey )
-----
-
-[role="mt-4"]
-=== 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.
-
-[source, js]
-----
-Amplitude.playNow( {song_object} );
-----
-
-[role="mt-4"]
-=== Pause
-
-This simply pauses whatever song is active.
-
-[source, js]
-----
-Amplitude.pause()
-----
-
-[role="mt-4"]
-=== Stop
-
-This simply stops whatever song is active.
-
-[source, js]
-----
-Amplitude.stop()
-----
-
-[role="mt-4"]
-=== Next
-
-Plays the next song either in the playlist or globally.
-
-[source, js]
-----
-Amplitude.next( playlistKey = null )
-----
-
-[role="mt-4"]
-=== Prev
-
-Plays the previous song either in the playlist or globally.
-
-[source, js]
-----
-Amplitude.prev( playlistKey = null )
-----
-
-[role="mt-4"]
-=== Skip To
-
-Allows the user to skip to a specific location in the song whether that
-song is in a playlist or not.
-
-[source, js]
-----
-Amplitude.skipTo( seconds, songIndex, playlist = null )
-----
-
-[role="mt-4"]
-=== 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.
-
-[source, js]
-----
-  Amplitude.registerVisualization( visualization, preferences );
-----
-
-
-[role="mt-5"]
-=== Setters
-
-Bla, bla ...
-
-[role="mt-4"]
-==== Set Default Album Art
-
-Sets the default album art for the player to the URL provided.
-
-[source, js]
-----
-Amplitude.setDefaultAlbumArt( url )
-----
-
-[role="mt-4"]
-==== Set Default Playlist Art
-
-Sets the default playlist art.
-
-[source, js]
-----
-Amplitude.setDefaultPlaylistArt( url )
-----
-
-[role="mt-4"]
-==== 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.
-
-[source, js]
-----
-Amplitude.setDebug( {bool} );
-----
-
-[role="mt-4"]
-==== 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.
-
-[source, js]
-----
-Amplitude.setDelay( milliseconds )
-----
-
-[role="mt-4"]
-==== Set Global Visualization
-
-You can set the global visualization through the public method like
-this:
-
-[source, js]
-----
-  Amplitude.setGlobalVisualization( visualizationKey );
-----
-
-[role="mt-4"]
-==== Set Playlist Visualization
-
-You can set the visualization through the public facing method like
-this:
-
-[source, js]
-----
-  Amplitude.setPlaylistVisualization( playlist_key, visualization_key );
-----
-
-[role="mt-4"]
-==== Set Individual Song Visualization
-
-You can set the visualization for an individual song like so:
-
-[source, js]
-----
-  Amplitude.setSongVisualization( songIndex, visualizationKey );
-----
-
-[role="mt-4"]
-==== Set Individual Song In Playlist Visualization
-
-You can set the visualization for an individual song in a playlist
-using:
-
-[source, js]
-----
-Amplitude.setSongInPlaylistVisualization( playlistKey, songIndex, visualizationKey );
-----
-
-[role="mt-4"]
-==== Set Shuffle
-
-Sets the global shuffle state for AmplitudeJS.
-
-[source, js]
-----
-Amplitude.setShuffle( shuffleState )
-----
-
-[role="mt-4"]
-==== Set Shuffle Playlist
-
-Sets the shuffle state for a playlist.
-
-[source, js]
-----
-Amplitude.setShufflePlaylist( playlistKey, shuffleState )
-----
-
-[role="mt-4"]
-==== Set Repeat
-
-Sets the global repeat status for AmplitudeJS
-
-[source, js]
-----
-Amplitude.setRepeat( repeatState )
-----
-
-[role="mt-4"]
-==== Set Repeat Song
-
-Sets the global state to determine if we should repeat the individual
-song upon completion.
-
-[source, js]
-----
-Amplitude.setRepeatSong( repeatSongState )
-----
-
-[role="mt-4"]
-==== Set Repeat Playlist
-
-Sets the repeat for the playlist.
-
-[source, js]
-----
-Amplitude.setRepeatPlaylist( playlistKey, repeatState )
-----
-
-[role="mt-4"]
-==== 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.
-
-[source, js]
-----
-Amplitude.setSongPlayedPercentage( percentage )
-----
-
-[role="mt-4"]
-==== 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.
-
-[source, js]
-----
-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`.
-
-[role="mt-4"]
-==== 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.
-
-[source, js]
-----
-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.
-
-[role="mt-5"]
-=== Getters
-
-Bla, bla ...
-
-[role="mt-4"]
-==== Get Analyser
-
-Returns the Web Audio API Analyser. This allows for the user to bind to
-the active audio through the web audio API.
-
-[source, js]
-----
-Amplitude.getAnalyser()
-----
-
-[role="mt-4"]
-==== Get Config
-
-Returns the current AmplitudeJS configuration.
-
-[source, js]
-----
-Amplitude.getConfig();
-----
-
-[role="mt-4"]
-==== Get Delay
-
-Gets the current delay between songs in milliseconds.
-
-[source, js]
-----
-Amplitude.getDelay();
-----
-
-[role="mt-4"]
-==== Get Player State
-
-Returns the current state of the player whether it's `playing`,
-`paused`, or `stopped`.
-
-[source, js]
-----
-Amplitude.getPlayerState()
-----
-
-[role="mt-4"]
-==== Get Active Playlist
-
-This method will return the key of the active playlist.
-
-[source, js]
-----
-Amplitude.getActivePlaylist()
-----
-
-[role="mt-4"]
-==== Get Playback Speed
-
-Returns the current playback speed for the player.
-
-[source, js]
-----
-Amplitude.getPlaybackSpeed()
-----
-
-[role="mt-4"]
-==== Get Repeat
-
-Returns the state of the global repeat status for the player.
-
-[source, js]
-----
-Amplitude.getRepeat()
-----
-
-[role="mt-4"]
-==== Get Repeat Playlist
-
-Returns the state of the repeat status for the playlist.
-
-[source, js]
-----
-Amplitude.getRepeatPlaylist( playlistKey )
-----
-
-[role="mt-4"]
-==== Get Shuffle
-
-Returns the current state of the global shuffle status for the player.
-
-[source, js]
-----
-Amplitude.getShuffle()
-----
-
-[role="mt-4"]
-==== Get Shuffle Playlist
-
-Returns the state of the shuffle flag for a playlist.
-
-[source, js]
-----
-Amplitude.getShufflePlaylist( playlistKey )
-----
-
-[role="mt-4"]
-==== Get Default Album Art
-
-Returns the default album art URL set in the player.
-
-[source, js]
-----
-Amplitude.getDefaultAlbumArt()
-----
-
-[role="mt-4"]
-[[get-default-album-art-2]]
-==== Get Default Album Art
-
-Returns the URL of the default album art for the player.
-
-[source, js]
-----
-Amplitude.getDefaultAlbumArt()
-----
-
-[role="mt-4"]
-==== Get Default Playlist Art
-
-Gets the default art for a playlist.
-
-[source, js]
-----
-Amplitude.getDefaultPlaylistArt()
-----
-
-[role="mt-4"]
-==== Get Active Song Metadata
-
-Returns the active song's metadata as a JSON object.
-
-[source, js]
-----
-Amplitude.getActiveSongMetadata();
-----
-
-[role="mt-4"]
-==== Get Active Playlist Metadata
-
-Gets the active playlist's metadata as a JSON object.
-
-[source, js]
-----
-Amplitude.getActivePlaylistMetadata();
-----
-
-[role="mt-4"]
-==== Get Active Index
-
-This method returns the index of the active song in the songs array.
-
-[source, js]
-----
-Amplitude.getActiveIndex()
-----
-
-[role="mt-4"]
-==== 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.
-
-[source, js]
-----
-Amplitude.getActiveIndexState()
-----
-
-[role="mt-4"]
-==== 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.
-
-[source, js]
-----
-Amplitude.getAudio()
-----
-
-[role="mt-4"]
-==== 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.
-
-[source, js]
-----
-Amplitude.getBuffered()
-----
-
-[role="mt-4"]
-==== 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.
-
-[source, js]
-----
-Amplitude.getSongs()
-----
-
-[role="mt-4"]
-==== 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.
-
-[source, js]
-----
-Amplitude.getSongsInPlaylist( playlistKey )
-----
-
-[role="mt-4"]
-==== 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.
-
-[source, js]
-----
-Amplitude.getSongsState()
-----
-
-[role="mt-4"]
-==== 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.
-
-[source, js]
-----
-Amplitude.getSongsStatePlaylist( playlist )
-----
-
-[role="mt-4"]
-==== 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.
-
-[source, js]
-----
-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.
-
-[role="mt-4"]
-==== Get Song Played Seconds
-
-This method returns the current seconds the user is into the song.
-
-[source, js]
-----
-Amplitude.getSongPlayedSeconds()
-----
-
-[role="mt-4"]
-==== Get Song Duration
-
-Returns the duration of the current song.
-
-[source, js]
-----
-Amplitude.getSongDuration()Individual Song Slider
-----
-
-[role="mt-4"]
-==== Get Song At Index
-
-Returns a song's metadata at a specific index.
-
-[source, js]
-----
-Amplitude.getSongAtIndex( {index} );
-----
-
-[role="mt-4"]
-==== Get Song At Playlist Index
-
-Returns a song at a playlist's index.
-
-[source, js]
-----
-Amplitude.getSongAtPlaylistIndex( {playlistIndex}, {index} );
-----
-
-[role="mt-4"]
-==== Get Version
-
-This method returns the version of AmplitudeJS being used.
-
-[source, js]
-----
-Amplitude.getVersion()
-----
-
-[role="mt-5"]
-== 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.
-
-[role="mt-4"]
-=== 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
-https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset[HTML5 dataset API, {browser-window--new}].
-
-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.
-
-[role="mt-4"]
-=== 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.
-
-[role="mt-4"]
-=== 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.
-
-[role="mt-4"]
-=== 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.
-
-[role="mt-4"]
-=== 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!