chickadee » mpd-client

mpd-client

Interface to the Music Player Daemon.

Documentation

This extension allows convenient access to the tcp interface of MPD.

Connecting to MPD and obtaining connection/server information

(mpd:connect [HOST] [PORT] [PASSWORD]) procedure

Connects to the MPD instance running on HOST (defaults to localhost) at PORT (defaults to 6600). Optionally authenticates using PASSWORD. Returns an MPD connection object.

(mpd:reconnect CONN) procedure

Reconnects the given MPD connection object. This function should normally not be needed as the library automatically reconnects if needed.

(mpd-conn? CONN) procedure

Returns #t if CONN is an MPD connection object, #f otherwise.

(mpd:host CONN) procedure

Returns the hostname field of the MPD connection object CONN.

(mpd:port CONN) procedure

Returns the port field of the MPD connection object CONN.

(mpd:password CONN) procedure

Returns the password field of the MPD connection object CONN. This is either a string containing the plain text password or #f if no authentication should be done.

(mpd:version CONN) procedure

Returns the version field of the MPD connection object CONN which contains the version number received by the MPD server.

(mpd:close CONN) procedure

Closes the connection to MPD. CONN should not be used anymore after calling this function.

(mpd:ping CONN) procedure

Sends a ping command to the MPD server, reconnecting if necessary.

(mpd:clear-error CONN) procedure

Clears the current error message (which is returned by (mpd:status)). This is also done by any command that starts playback.

(mpd:stats CONN) procedure

Returns an alist containing various stats:

#;6> (pp (mpd:stats m))
((artists . 183)
 (albums . 429)
 (songs . 6200)
 (uptime . 130260)
 (playtime . 49958)
 (db_playtime . 1773229)
 (db_update . 1152376960.0))
#;7>
(mpd:status CONN) procedure

Return an alist describing the current status of MPD:

#;9> (pp (mpd:status m))
((volume . 78)
 (repeat . #f)
 (random . #f)
 (playlist . 78)
 (playlistlength . 77)
 (xfade . 0)
 (state . play)
 (song . 12)
 (songid . 12)
 (time 31 623)
 (bitrate . 128)
 (audio 44100 16 2))
#;10>
(mpd:kill CONN) procedure

Kill MPD.

(mpd:send-password CONN PASSWORD) procedure

Sends PASSWORD (a string containing the plain text password) to the server for authentication. Normally, this not needed as the password can be specified when creating the connection which has the advantage that it's automatically sent after having reconnected.

(mpd:commands CONN) procedure

Returns a list of commands the current user has access to.

(mpd:not-commands CONN) procedure

Returns a list of commands the current user doesn't have access to.

Controlling playback

(mpd:play/pos CONN POS) procedure

Start playing at position POS.

(mpd:play/id CONN ID) procedure

Start playing at song with id ID.

(mpd:seek/pos CONN POS SECS) procedure

Seeks to SECS in the song at position POSITION.

(mpd:seek/id CONN ID SECS) procedure

Seeks to SECS in the song with id ID.

(mpd:next CONN) procedure

Play the next song in the playlist.

(mpd:previous CONN) procedure

Play the previous song in the playlist.

(mpd:stop CONN) procedure

Stop playback.

(mpd:pause CONN PAUSE?) procedure

Pause if PAUSE? is true, resume playing otherwise.

(mpd:random CONN RANDOM?) procedure

Enable or disable random.

(mpd:repeat CONN REPEAT?) procedure

Enable or disable repeat.

(mpd:crossfade CONN SECS) procedure

Sets the cross fading setting to SECS seconds (0 = disabled).

(mpd:set-vol CONN VOLUME) procedure

Sets the volume to VOLUME (a fixnum in the range 0-100).

Managing output devices

(mpd:outputs CONN) procedure

Returns a list of alists describing the available output devices.

(mpd:enable-output CONN ID) procedure

Enables the output device with id ID.

(mpd:disable-output CONN ID) procedure

Disables the output device with id ID.

Querying and modifying the current playlist

(mpd:playlist/pos CONN [POS]) procedure

Return a list of alists describing the songs in the current playlist. (Optionally only the song at position POS). See below for an example of the result format.

(mpd:playlist/id CONN [ID]) procedure

Return a list of alists describing the songs in the current playlist. (Optionally only the song with id ID):

#;10>  (pp (mpd:playlist/id m 12))
(((Id . 12)
  (Pos . 12)
  (Time . 623)
  (Title . "the leper affinity")
  (Track . 1)
  (Album . "blackwater park")
  (Artist . "opeth")
  (file . "metal/opeth/blackwater park/01 the leper affinity.mp3")))
#;11>
(mpd:current-song CONN) procedure

Returns an alist with information about the current song (the same information that (mpd:playlist/id) returns).

(mpd:pl-changes CONN VERSION) procedure

Return a list of alists describing new songs since playlist version VERSION. Note: to detect songs that were deleted at the end of the playlist, use the playlistlength returned by (mpd:status).

(mpd:pl-changes/pos+id CONN VERSION) procedure

Similar to mpd:pl-changes but only returns the position and id of each song.

(mpd:add CONN PATH) procedure

Adds PATH (a string naming a file or directory) to the end of the current playlist. Directories are added recursively. Increments playlist version by 1 for each added song.

(mpd:add/id CONN PATH) procedure

Similar to mpd:add but returns a list of ids of the newly added songs.

(mpd:move/pos CONN FROM TO) procedure

Move song at position FROM to TO. The playlist version is incremented by 1.

(mpd:move/id CONN ID TO) procedure

Move song with id ID to TO. The playlist version is incremented by 1.

(mpd:swap/pos CONN POS1 POS2) procedure

Swap position of the two songs given by playlist positions POS1 and POS2.

(mpd:swap/id CONN ID1 ID2) procedure

Swap position of the two songs given by ids ID1 and ID2.

(mpd:delete/pos CONN POS) procedure

Remove the song at position POS from playlist. The playlist version is incremented by 1.

(mpd:delete/id CONN ID) procedure

Remove the song with id ID from playlist. The playlist version is incremented by 1.

(mpd:shuffle CONN) procedure

Shuffles the current playlist and increments the playlist version by 1.

(mpd:clear CONN) procedure

Clears the current playlist, incrementing playlist version by 1.

Managing stored playlist

(mpd:load-playlist CONN PLAYLIST) procedure

Loads the playlist named "PLAYLIST.m3u" from the playlist directory. The playlist version is incremented by the number of songs added.

(mpd:rm-playlist CONN PLAYLIST) procedure

Removes the playlist named "PLAYLIST.m3u" from the playlist directory.

(mpd:save-playlist CONN PLAYLIST) procedure

Saves the current playlist to "PLAYLIST.m3u" in the playlist directory.

Querying/Updating song database

(mpd:find CONN TYPE STRING) procedure

Searches for songs and returns a list of alists. TYPE is e.g. 'title, 'album or 'artist. STRING is the search string (which must match exactly).

(mpd:find/album CONN ALBUM) procedure

Returns a list of alists describing songs on album ALBUM (a string).

#;13> (pp (mpd:find/album m "catch 33"))
(((Time . 101)
  (Title . "autonomy lost")
  (Track . 1)
  (Album . "catch 33")
  (Artist . "meshuggah")
  (file . "metal/meshuggah/catch 33/01 autonomy lost.mp3"))
 ((Time . 96)
  (Title . "imprint of the un-saved")
  (Track . 2)
  (Album . "catch 33")
  (Artist . "meshuggah")
  (file . "metal/meshuggah/catch 33/02 imprint of the un-saved.mp3"))
...
#;14>
(mpd:find/artist CONN ARTIST) procedure

Returns a list of alists describing songs from ARTIST (a string).

(mpd:find/title CONN TITLE) procedure

Returns a list of alists describing songs with title TITLE (a string).

(mpd:search CONN TYPE SEARCHSTRING) procedure

Returns a list of alists describing the matching songs. TYPE is e.g. 'title, 'album or 'artist. SEARCHSTRING is the string which is searched for (not case sensitive, doesn't need to be an exact match).

(mpd:search/album CONN SEARCHSTRING) procedure

Returns a list of alists describing songs whose album names contain SEARCHSTRING (not case sensitive).

(mpd:search/artist CONN SEARCHSTRING) procedure

Returns a list of alists describing songs whose artist names contain SEARCHSTRING (not case sensitive).

(mpd:search/title CONN SEARCHSTRING) procedure

Returns a list of alists describing songs whose titles contain SEARCHSTRING (not case sensitive).

(mpd:search/filename CONN SEARCHSTRING) procedure

Returns a list of alists describing songs whose filenames contain SEARCHSTRING (not case sensitive).

(mpd:list CONN TYPE [LIMIT STRING]) procedure

Return a list of values of metadata TYPE (e.g. 'title, 'album or 'artist), optionally limited by LIMIT and STRING. E.g. (mpd:list m 'album 'artist "nevermore") to get a list of all albums by Nevermore.

(mpd:list-artists CONN) procedure

Returns a list of all known artists.

(mpd:list-albums CONN [ARTIST]) procedure

Returns a list of all known albums, optionally limited by ARTIST.

(mpd:list-all CONN [PATH]) procedure

Returns a list of filenames of all songs (below PATH, if given).

(mpd:list-all/info CONN [PATH]) procedure

Like (mpd:list-all), but also returns metadata. The data is returned as a list of alists.

(mpd:ls/info CONN [DIR]) procedure

Returns a list of alists describing the contents of DIR (a string). This function is like (mpd:list-all/info), but doesn't operate recursively.

(mpd:update CONN [PATH]) procedure

Updates MPD's database, removing old songs and adding new songs. Optionally, the update process can be limited to PATH (a string naming a file or directory).

Examples

#!/usr/local/bin/csi -script

(require-extension mpd-client srfi-18 utils)

(define mpd (mpd:connect))

(define (get-mpd-status)
  (let ((status (mpd:status mpd)))
    (list (alist-ref 'songid status)
          (alist-ref 'state status))))

(define (get-songname id)
  (let ((info (car (mpd:playlist/id mpd id))))
    (or (alist-ref 'Title info)
        (pathname-strip-directory
         (alist-ref 'file info)))))

(let loop ((status (get-mpd-status)) (old-status #f))
  (unless (equal? status old-status)
    (let ((song (car status))
          (state (cadr status)))
      (cond
       ((eq? state 'play)
        (printf "Now playing: ~a\n"
                (if song
                    (get-songname song)
                    "(unknown song)")))

       ((eq? state 'stop)
        (printf "STOP\n")))))
  (thread-sleep! 1)
  (loop (get-mpd-status) status))

About this egg

Author

Hans Bulfone

Version history

1.12
Added regex as a dependency; converted eggdoc documentation to wiki format [Ivan Raikov]
1.1
Added new commands supported by recent versions of MPD
1.02
Fixed a bug that caused playlists to be returned incorrectly by mpd:ls/info et al.
1.01
Fixed typo in documentation
1.0
Initial release

License

Copyright (c) 2006-2007, Hans Bulfone
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice,
      this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of the author nor the names of his contributors may
      be used to endorse or promote products derived from this software
      without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Contents »