MPD.js

MPD

new MPD(_port, _host, _password)

The global MPD function is the main interface and only global varialbe of the MPD.js library.
This function returns an object representing an MPD web client.
All other methods documented here are member functions of the object returned by a call to the MPD function.

Parameters:
Name Type Argument Default Description
_port Integer <optional>

the portnumber our client should try to cennect to our winsockifyed MPD instance with
_host String <optional>
 document.URL

hostname to try to connect to, defaults to the domain of the current page
_password String <optional>

password to connect with (if needed)
Source:
Example
//EXAMPLE USAGE//
//retrives a MPD client interface on port 8800
var mpd_client = MPD(8800);
//set handler for when the state changes
mpd_client.on('StateChanged', updateUiFunction);

Methods

on(event_name, handler)

adds an event handler

Parameters:
Name Type Description
event_name String

what sort of event to listen for. must be one of the following: 'Error', 'Event', 'UnhandledEvent', 'AuthFailure', 'DatabaseChanging', 'DataLoaded', 'OutputChanged', 'StateChanged', 'QueueChanged', 'PlaylistsChanged', 'PlaylistChanged','Connect', 'Disconnect'
handler errorEventHandler | disconnectEventHandler | connectEventHandler | playlistsChangedEventHandler | queueChangedEventHandler | outputChangedEventHandler | stateChangedEventHandler | dataLoadedEventHandler | databaseChangingEventHandler | unhandledEventHandler | eventHandler | errorEventHandler

function called when the given event happens
Source:
Throws:

an Error if you try to listen to an invalid event type

Type
Error

getState() → {state}

returns an object representation of the current state of MPD as the client understands it right now
this does NOT map to the client's functional API

Source:
Returns:

object representing the current state of MPD

Type
state

disableLogging()

call to turn off logging to the console

Source:

enableLogging()

call to turn logging to the console on (debugging)

Source:

getPort() → {Integer}

return the port number this client was instansiated with and thet it is (attempting to) connect with

Source:
Returns:

the port number the MPD client is (trying to be) connected to

Type
Integer

getHost() → {String}

return the host this client was instansiated with and thet it is (attempting to) connect with

Source:
Returns:

the host name the MPD client is (trying to be) connected to

Type
String

getProtocolVersion() → {String}

gets the protocol versing reported on connection

Source:
Returns:

string desxriping the protocol version i.e. "1.18.0"

Type
String

isConnected() → {Boolean}

retruns if we are connected or not

Source:
Returns:

true if we are connected, false if we are not

Type
Boolean

getPlaystate() → {String}

Returns a string enum describing the playback state

Source:
Returns:
  • 'play', 'pause', 'stop'
Type
String

getVolume() → {Float}

returns the current volume

Source:
Returns:

between 0 and 1

Type
Float

isRepeat() → {Boolean}

returns if we are in repeat mode or not

Source:
Returns:

true if we are in repeat mode, false otherwise

Type
Boolean

isSingle() → {Boolean}

returns if we are in single mode or not

Source:
Returns:

true if we are in single mode, false otherwise

Type
Boolean

isConsume() → {Boolean}

returns if we are in consume mode or not

Source:
Returns:

true if we are in consume mode, false otherwise

Type
Boolean

isRandom() → {Boolean}

returns if we are in random playback mode or not

Source:
Returns:

true if we are in random mode, false otherwise

Type
Boolean

getCrossfadeTime() → {Number}

ammount of time (in seconds) the MPD server is set to crossfade songs. 0 means disabled

Source:
Returns:

true if we are in random mode, false otherwise

Type
Number

getMixRampThreashold() → {Float}

honestly don't know what this is, has something to do with some sort of fading mode I never use, but MPD reports it so I'm making an accessor for it in case someone else wants to use it

Source:
Returns:
Type
Float

getCurrentSong() → {Song}

gets the currently playing song

Source:
Returns:
Type
Song

getCurrentSongTime() → {Float}

gets the time of the current song. will calculate it based on the reported time, and how long it's been since that happened

Source:
Returns:
Type
Float

getCurrentSongID() → {Integer}

get's the queue id of the currently playing song

Source:
Returns:
Type
Integer

getCurrentSongQueueIndex() → {Integer}

gets the position on the queue of the song currently playing

Source:
Returns:
Type
Integer

getNextSong() → {Song}

gets the song next to be played

Source:
Returns:
Type
Song

getNextSongID() → {Integer}

gets the queue id of the next song to play

Source:
Returns:
Type
Integer

getNextSongQueueIndex() → {Integer}

returns the position on the queue of the next song on the queue to play

Source:
Returns:
Type
Integer

getQueue() → {Queue}

get the whole queue

Source:
Returns:
Type
Queue

getQueueVersion() → {Integer}

returns the version of the queue, this number changes every time the queue does

Source:
Returns:
Type
Integer

getPlaylist(playlist, onDone)

fetches a playlist from MPD identified by it's name

Parameters:
Name Type Description
playlist String

name - the name of the playlist you want
onDone playlistCallback

function to call with the playlist when we get it
Source:

getPlaylists() → {Array.<String>}

returns an array of strings that is the list of the names of all available saved playlists

Source:
Returns:
Type
Array.<String>

getOutputs() → {Array.<Output>}

returns an array of Output objects

Source:
Returns:
Type
Array.<Output>

outputIsEnabled(id)

returns true if the output is enabled, false otherwise

Parameters:
Name Type Description
id Integer
  • the identifier of the output
Source:

enableOutput(id)

turns on the output specified by the id

Parameters:
Name Type Description
id Integer
  • the identifier of the output to turn on
Source:

disableOutput(id)

turns off the output specified by the id

Parameters:
Name Type Description
id Integer
  • the identifier of the output to turn off
Source:

enablePlayConsume()

turns on consume mode

Source:

disablePlayConsume()

turns off consume mode

Source:

setCrossfade(time)

turns on crossfade

Parameters:
Name Type Description
time String
  • time to crossfade in seconds, 0 to disable
Source:

enableRandomPlay()

turns on random play mode

Source:

disableRandomPlay()

turns off random play mode

Source:

enableRepeatPlay()

turns on repeat play mode

Source:

disableRepeatPlay()

turns of repeat play mode

Source:

enableSinglePlay()

turns on single play mode

Source:

disableSinglePlay()

turns of single play mode

Source:

setMixRampDb(decibels)

Sets the threshold at which songs will be overlapped. Like crossfading but doesn't fade the track volume, just overlaps. The songs need to have MixRamp tags added by an external tool. 0dB is the normalized maximum volume so use negative values, I prefer -17dB. In the absence of mixramp tags crossfading will be used. See http: // sourceforge.net/projects/mixramp

Parameters:
Name Type Description
decibels Float
Source:

setMixRampDelay(seconds)

Additional time subtracted from the overlap calculated by mixrampdb. A value of "nan" disables MixRamp overlapping and falls back to crossfading.

Parameters:
Name Type Description
seconds float | string

time in seconds or "nan" to disable
Source:

setVolume(volume)

Sets volume, the range of volume is 0-1.

Parameters:
Name Type Description
volume Float

0-1
Source:

play(queue_position)

Begins playing if not playing already. optional parameter starts playing a particular song

Parameters:
Name Type Argument Default Description
queue_position Integer <optional>
 <current song>

the song to start playing
Source:

playById(song_id)

Begins playing the playlist at song identified by the passed song_id.

Parameters:
Name Type Description
song_id Integer

the queue id of the song you want to start playing
Source:

pause(do_pause)

pauses/resumes playing

Parameters:
Name Type Argument Default Description
do_pause Boolean <optional>
 true

true if you want to pause, false if you want to be unpaused
Source:

next()

Plays next song in the queue.

Source:

previous()

Plays previous song in the queue.

Source:

seek(time)

Seeks to the position time (in seconds) within the current song. If prefixed by '+' or '-', then the time is relative to the current playing position.

Parameters:
Name Type Description
time float | string

what point in the current song to seek to or string with a signed float in it for relative seeking. i.e. "+0.1" to seek 0.1 seconds into the future, "-0.1" to seek 0.1 seconds into the past
Source:

stop()

Stops playing.

Source:

addSongToQueueByFile(pathname)

Adds the file to the playlist (directories add recursively).

Parameters:
Name Type Description
pathname String

of a single file or directory. relative to MPD's mussic root directory
Source:

clearQueue()

Clears the current queue

Source:

removeSongFromQueueByPosition(position)

Deletes a song from the queue

Parameters:
Name Type Description
position Integer

index into the queue to the song you don't want to be on the queue any more
Source:

removeSongsFromQueueByRange(start, end)

Deletes a range of songs from the playlist.

Parameters:
Name Type Description
start Integer

the queue index of the first song on the playlist you want to remove
end Integer

the queue index of the last song on the playlist you want to remove
Source:

removeSongFromQueueById(id)

Deletes the song identified with the passed queue id from the playlist

Parameters:
Name Type Description
id Integer

the queue id of the song you want to remove from the queue
Source:

moveSongOnQueueByPosition(position, to)

a song from one position on the queue to a different position

Parameters:
Name Type Description
position Integer

the position of the song to move
to Integer

where you want the sang to go
Source:

moveSongsOnQueueByPosition(start, end, to)

moves a range of songs on the queue

Parameters:
Name Type Description
start Integer

the queue index of the first song on the queue you want to move
end Integer

the queue index of the last song on the queue you want to move
to Integer

the queue index were the first song should end up
Source:

moveSongOnQueueById(id, to)

moves the song identified with the passed queue id to the passed queue index

Parameters:
Name Type Description
id Integer

queue id of the song you want to move
to Integer

the queue indes you want it to be
Source:

shuffleQueue()

Shuffles the current playlist.

Source:

swapSongsOnQueueByPosition(pos1, pos2)

Swaps the positions of two songs identified by their queue indexes

Parameters:
Name Type Description
pos1 Integer

queue index of the first song
pos2 Integer

queue index of the second song
Source:

swapSongsOnQueueById(id1, id2)

Swaps the positions of two songs identified by their queue ids

Parameters:
Name Type Description
id1 Integer

queue id of the first song
id2 Integer

queue id of the second song
Source:

appendPlaylistToQueue(playlist_name)

Loads the given playlist to the end of the current queue.

Parameters:
Name Type Description
playlist_name String

the name of the playlist you want to append to the queue
Source:

loadPlaylistIntoQueue(playlist_name)

Loads the given playlist into the current queue replacing it.

Parameters:
Name Type Description
playlist_name String

the name of the playlist you want to append to the queue
Source:

saveQueueToPlaylist(playlist_name)

Saves the current queue as a the given playlist, overwrites exsisting playlist of that name if it exsists, otherwise makes a new one

Parameters:
Name Type Description
playlist_name String

the name of the playlist you want to use as your new queue
Source:

addSongToPlaylistByFile(playlist_name, filename)

adds the given song (filename) to the given playlist

Parameters:
Name Type Description
playlist_name String

the playlist to add the song to
filename String

the filename of the song you want to add
Source:

clearPlaylist(playlist_name)

Clears the playlist leaving it still in exsistance, but empty

Parameters:
Name Type Description
playlist_name String

the poor unfortunate playlist you want to hollow out
Source:

removeSongFromPlaylistByPosition(playlist_name, position)

Deletes the song at the given position from the given playlist

Parameters:
Name Type Description
playlist_name String

the name of the playlist with a song on it that you think shouldn't be there anymore
position Integer

the position in the playlist of the song you want to remove
Source:

moveSongOnPlaylistByPosition(playlist_name, from, to)

moves the song from one position on the playlist to another

Parameters:
Name Type Description
playlist_name String

the name of the playlist on which you want to move a song
from Integer

position on the playlist of the song you want to move
to Integer

the position to which you want to move the song
Source:

renamePlaylist(playlist_name, new_name)

Renames the playlist

Parameters:
Name Type Description
playlist_name String

the name is it right now
new_name String

the name it should be
Source:

deletePlaylist(playlist_name)

this kills the playlist

Parameters:
Name Type Description
playlist_name String

the name of the playlist you want to obliterate and never see any trace of again
Source:

updateDatabase()

Updates the music database: find new files, remove deleted files, update modified files.

Source:

getDirectoryContents(path, onDone)

Parameters:
Name Type Argument Description
path String <optional>

path to the directory you are interested in relative to MPD's music root directory (root is a blank string, never start with '/')
onDone directoryContentsCallback
Source:

getTagTypes() → {Array.<String>}

return an array of strings which are all of the valid tags
note there might be more undocumented tags that you can use just fine not listed here (like musicbrainz)

Source:
Returns:
Type
Array.<String>

tagSearch(params, onDone)

params is a {tag => value} object, valid tags are enumerated in getTagTypes.
onDone is a function that should be called on complete, will be passed an array of strings that are the values of the tag identified by tag_type that are on songs that match the search critaria

Parameters:
Name Type Description
params Array.<Object>

Array of objects that maps a tag to a value that you want to find matches on that tag for {tag => value}. For a list of acceptable tag/keys @see getTagTypes. For a list of acceptable values for a given tag @see getTagOptions.
onDone searchResultsCallback

function called when the search results have come back, is passed the results as it's only parameter
Source:
Example
client.tagSearch(
    'album',
    {artist:'bearsuit'},
    function(albums){
       //albums == ["Cat Spectacular", "Team Pingpong", "OH:IO", "The Phantom Forest"]
       //which are all of the albums of the band Bearsuit
    }
);

params is a {tag => value} object, valid tags are enumerated in getTagTypes, onDone is a function that should be called on complete, will be passed an array of song objects

Parameters:
Name Type Description
params Array.<Object>

Array of objects that maps a tag to a value that you want to find matches on that tag for {tag => value}. For a list of acceptable tag/keys @see getTagTypes. For a list of acceptable values for a given tag @see getTagOptions.
onDone searchResultsCallback

function called when the search results have come back, is passed the results as it's only parameter
Source:

searchCount(params, onDone)

like search except just for finding how many results you'll get (for faster live updates while criteria are edited)
params is a {tag => value} object, valid tags are enumerated in getTagTypes, onDone is a function that should be called on complete, will be passed the numver of results the search would produce

Parameters:
Name Type Description
params Array.<Object>

Array of objects that maps a tag to a value that you want to find matches on that tag for {tag => value} For a list of acceptable tag/keys @see getTagTypes. For a list of acceptable values for a given tag @see getTagOptions.
onDone searchCountCallback

function called when the search results have come back, is passed the results as it's only parameter
Source:

authorize(password)

set the password for this client

Parameters:
Name Type Description
password String
Source:

<inner> setInited()

change the state and deal with what happens when that state changes

Source:

<inner> processComandQueue()

get the next command off the queue and process it

Source:

<inner> defaultErrorHandler()

what to do by default if a command fails

Source:

<inner> getRawLines()

fetch outstanding lines from MPD

Source:

<inner> tagHandler()

handles the 'tagtypes' command

Source:

<inner> outputHandler()

deal with the result of the 'outputs' command

Source:

<inner> cancelLoad()

deal with getting an error during initial data load

Source:

<static> getErrorCodes() → {Object}

return an enum that maps error numbers to something that is almost readable

Source:
Returns:
Type
Object