Apls.js Documentation

Apls.js is an alternative playlist for Amplitude.js written in vanilla JavaScript. Its main features are that it doesn't require a JSON definition and HTML playlist (so you can create playlists easily and fast) and can play (multiple) lists created dynamically as well. In combination with a library like Dragula it is possible to sort the playlist(s) on the fly. View the demo to see it in action.

Prerequisites

Amplitude.js;
An (un)ordered playlist with ID (see below for specifications).
Optional: Dragula

Installation

1. Load Apls.min.js after amplitude.js.

2. Call Amplitude with the following options:


Amplitude.init({
    "songs": [{"url": ""}],
    "autoplay": false,
    "callbacks": {
        'time_update': function() {
            if ( Amplitude.getSongPlayedPercentage() > 99 ) {
                Apls.playNext();
            }
    }
})

It's possible to add more options when initializing Amplitude, but these are the minimum settings for Apls

3. Initialize Apls with the ID of the playlist; i.e. to use the playlist with ID 'tracks':

Apls.init('tracks')

Notice that it is possible to have multiple playlists in one page, Apls only needs the Id to start playing any of them.

There are some options available to set in Apls.init. These are the default options ('tracks' is used as example):


Apls.init('tracks', {
    autoplay: false, /* Set it to true to start playing as soon as the page is ready */
    continuous: false, /* Set it to true to play endlessly */
    playOne: false, /* Set it to true to play only one song */
    shuffle: false, /* Set it to true to play shuffled */
    refreshDivs: true, /* Set it to false to handle the update of the player divs when playing a new song */
    mainAlbum: 'mainAlbum' /* Div ID of the player's album */
    mainSong: 'mainSong' /* Div ID of the player's song */
    mainArtist: 'mainArtist' /* Div ID of the player's artist */
    tracks: tracks /* Array with songs as objects */
})

The Player

Apls.js works together with Amplitude but it replaces the following controls: Play, Play Next, Play Previous, Shuffle, Repeat One, Repeat All, Pause and Stop. In practice this means that to use Apls these controls will not use the system of classes implemented by Amplitude>, i.e. for the Play Previous, Play and Play Next buttons (visit the demo to see all the controls in action):


<button onclick="Apls.playPrev()"></button>
<button onclick="Apls.play()"></button>
<button onclick="Apls.playNext()"></button>

For Apls.js to set the album cover and the names of the artist and song of the current playing track, it needs the following divs or spans with their id:


<div><img id="mainAlbum" src="default.jpg"></div> <--! Will include the image of the album -->
<span id="mainArtist"></span>  <--! Will include the name of the artist -->
<span id="mainSong"></span>  <--! Will include the title of the song -->

The id of the divs and spans can be set in the initializing options of Apls.js. It is also possible to disable the option to set them automatically.

The remaining Amplitude.js controls must be used and styled accordingly to Amplitude's documentation.

The Playlist(s)

Apls.js needs at least one (un)ordered playlist with an Id. To use multiple playlists, each one needs its own Id.

Since version 0.30 of Apls, there are two ways to create the playlist:

Passing an array of tracks to Apls
Coding manually the playlist

a. Passing an array of songs to `Apls`

Define an array of song objects with properties id, url, image, artist, song before initializing Apls i.e.:


    var tracks = [{
        id: "pls1",
        url: "tracks/01.mp3",
        img: "img/cover01.jpg",
        artist: "Miguel de la bastide",
        song: "Viajero"
    },{
        id: "pls2",
        url: "tracks/02.mp3",
        img: "img/cover02.jpg",
        artist: "Gonzalez",
        song: "Gentle Threat"            
    },{
        id: "pls3",
        url: "tracks/03.mp3",
        img: "img/cover03.jpg",
        artist: "Giovanni Sollima",
        song: "Tierra Aria"        
    },{
        id: "pls4",
        url: "tracks/any.mp3",
        img: "img/Any.jpg",
        artist: "Puente de los alunados",
        song: "Viajero"
    },{
        id: "pls5",
        url: "tracks/more.mp3",
        img: "img/more.jpg",
        artist: "Veljo Tormis",
        song: "Home"            
    }
    ];

Initialize Apls passing tracks with the other options as described before:


        Apls.init('tracks', {
            autoplay: true, /* or false */
            // ... //
            tracks: tracks
        })

Or you can add tracks after Apls is initiated by using the method addSong():


        Apls.addSong(tracks);

Each <LI> element in the playlist is a track with the following characteristics:


<li id="pls1" data-track-url="tracks/01.mp3" data-album="img/cover01.jpg" onclick="Apls.play(this)">
<span class="artist">Name of the Artist</span> | <span class="song">Name of the song</span>
</li>

This will append tracks at the end of the current playlist.

b. Coding manually the HTML of the playlist

Create an (un)ordered list with Id:


<ul id="playlist">
</ul>

Every song will be included in a LI element with the following characteristics:


<li id="pls1" data-track-url="tracks/01.mp3" data-album="img/cover01.jpg" onclick="Apls.play(this)">
<span class="artist">Miguel de la Bastide</span> | <span class="song">Viajero</span>
</li>

id: optional. It is only necessary to request Apls to play a song by id (ie. Apls.playNow("pls1"));
data-track-url: mandatory. Contains the url of the song to play;
data-album, class="artist", class="song": optionals. Only necessary if Apls is updating the player divs.

A complete playlist will look like this:


<ul id='playlist'>
    <li id="pls1" data-track-url="tracks/01.mp3" data-album="img/cover01.jpg" onclick="Apls.play(this)">
    <span class="artist">Miguel de la Bastide</span> | <span class="song">Viajero</span>
    </li>
    <li id="pls2" data-track-url="tracks/02.mp3" data-album="img/cover02.jpg" onclick="Apls.play(this)">
    <span class="artist">Gonzalez</span> | <span class="song">Gentle Threat</span>
    </li>
    <li id="pls3" data-track-url="tracks/03.mp3" data-album="img/cover03.jpg" onclick="Apls.play(this)">
    <span class="artist">Giovanni Sollima</span> | <span class="song">Tierra Aria</span>
    </li>
    <li id="pls4" data-track-url="tracks/any.mp3" data-album="img/Any.jpg" onclick="Apls.play(this)">
    <span class="artist">Gerardo Nuñez</span> | <span class="song">Puente de los alunados</span>
    </li>
    <li id="pls5" data-track-url="tracks/more.mp3" data-album="img/more.jpg" onclick="Apls.play(this)">
    <span class="artist">Veljo Tormis</span> | <span class="song">Home</span>
    </li>                
</ul>

To start the playlist:


Apls.init('playlist');
Apls.play();

Or:


Apls.init('playlist', {autoplay: true});

It's possible to keep adding tracks dynamically (via Ajax, drag & drop, etc.). Apls will keep playing the playlist until the last track.

How to add new songs to the playlist

Create a new array with the song(s) as element(s):


    var newTracks = [
        {
            id: 'pls100', /* Optional. Useful to play a song by id */
            url: '/tracks/t100.mp3', /* Mandatory. Url of the song */
            album: 'img100.png', /* Optional, only useful if Apls is handling the player divs */
            song: 'Hello world!', /* Optional, only useful if Apls is handling the player divs */
            artist: 'Welcoming World' /* Optional, only useful if Apls is handling the player divs */
        },{
            // ... //
        },{
            // No limit in the number of songs to add //
        }
    ];

Add the newTracks array to Apls:


    Apls.addSong(newTracks);

The songs will be appended at the end of the active playlist.

Public functions

Add Song

Method to add new songs to the active playlist (see previous section):

Apls.addSong(newSongs)

Continuous

Set Amplitude to play endlessly. Call it again to return to normal play mode.

Apls.continuous()

Pause

Pause amplitude.

Apls.pause()

Play

Start or resume playing. It will add the class selected to the track playing. Useful for styling.

Apls.play()

Play Next

Play the next track in the (shuffled) playlist.

Apls.playNext()

Play Now

Play a track by ID

Apls.playNow(trackId)

Play One

Play one track only

Apls.playOne()

Play Prev

Play the previous track again.

Apls.playPrev()

Stop

Stop playing amplitude.

Apls.stop()

Refresh Divs

To manually update the player's main divs, set it to false:

Apls.refreshDivs(false)

Repeat

Play endlessly the current track. Call it again to disable it.

Apls.repeat()

Shuffle

Shuffle the playlist. Call it again to disable it.

Apls.shuffle()

Events

In normal playing mode, apls will fire the event playEnd after playing the last track of the playlist.

Helpers

Other functions available to developers to track apls:

isContinuous

Boolean. Returns the state of the continuous play mode.

Apls.isContinuous()

isPaused

Boolean. Only returns true if Apls.pause() was called first; remains false if Amplitude was paused by amplitude.pause().

Apls.isPaused()

isPlayOne

Boolean. Returns true if it will play only one song.

Apls.isPlayOne()

isRepeat

Boolean. Returns true if set up to repeat endlessly the current track.

Apls.isRepeat()

isShuffle

Boolean. Returns true if play mode is shuffle.

Apls.isShuffle()

playlist

Returns the current playlist's id.

Apls.playlist()

plsShuffled

Returns the shuffled playlist.

Apls.plsShuffled()

ver

Returns apls version.

Apls.ver()

License

2018, MIT license, by Daniel Ramos.