ruby-mpd is a powerful object-oriented Music Player Daemon library, forked from librmpd. librmpd is as of writing outdated by 6 years! This library tries to act as a successor, originally using librmpd as a base, however almost all of the codebase was rewritten. ruby-mpd supports all “modern” MPD features.

MPD Protocol

The Music Player Daemon protocol is implemented inside the library. The implementation brings the entire set of features to ruby, with support of the newest protocol commands. However some commands were remapped, some were converted to objects, as I felt they fit this way much more into ruby and are more intuitive.


gem install ruby-mpd


Require the library.

require 'ruby-mpd'

Then, make a new MPD instance:

mpd = 'localhost', 6600

You can also omit the host and port, and it will use the defaults.

mpd = 'localhost'
mpd =

Once you have an instance of the MPD class, connect to the server.


When you are done, disconnect by calling disconnect.


Note: The server may disconnect you at any time due to inactivity. This can be fixed by enabling callbacks (see the Callbacks section) or by issuing a `ping` command at certain intervals

Once connected, you can issue commands to talk to the server.

mpd.connect if mpd.stopped?
song = mpd.current_song
puts "Current Song: #{song.artist} - #{song.title}"

You can find command documentation can be found here.


Some commands require URI paths. ruby-mpd allows you to use MPD::Song objects directly and it extracts the file paths behind the scenes.

song = mpd.songs_by_artist('Elvis Presley').first # => MPD::Song
mpd.add song


Some commands accept “option hashes” besides their default values. For example, #move accepts an ID key instead of the position:

mpd.move(1, 10) # => move first song to position 10.
mpd.move({:id => 1}, 10) # => move the song with the ID of 1 to position 10.

Commands that accept ID's: #move, #delete, #play, #song_priority. #seek accepts both :pos and :id. Note: #swap and #swapid are still separate!


Some commands also allow ranges instead of numbers, specifying a range of songs. ruby-mpd correctly handles inclusive and exclusive ranges (1..10 vs 1…10). Negative range end means that we want the range to span until the end of the list.

For example, #queue allows us to return only a subset of the queue:

mpd.queue.count # => 20
mpd.queue(1..10).count # => 10
mpd.queue(5..-1).count # => 15 (from 5 to the end of the range)
mpd.queue(5...-1).count # => 15 (does the same)

Move also allows specifying ranges to move a range of songs instead of just one.

mpd.move 1, 10 # => move song 1 to position 10.
mpd.move 1..3, 10 # => move songs 1, 2 and 3 to position 10 (and 11 and 12).

Commands that support ranges: #delete, #move, #queue, #song_priority, #shuffle, MPD::Playlist#load.


Searching is case insensitive by default. To enable case sensitivity, pass a third argument with the key :case_sensitive. This does not work for Playlist#searchadd., 'MyArtiSt', :case_sensitive => true)

While searching, one can also enable the add option, which will automatically add the songs the query returned to the queue. In that case, the response will only return true, stating that the operation was successful (instead of returning an array)., 'MyArtiSt', {:case_sensitive => true, :add => true})


Playlists are one of the objects that map the MPD commands onto a simple to use object. Instead of going trough all those function calls, passing data along to get your results, you simply use the object in an object-oriented way:

mpd.playlists # => [MPD::Playlist, MPD::Playlist...]
playlist = mpd.playlists.first
p # => "My playlist"
playlist.songs # => [MPD::Song, MPD::Song...]
p # => "Awesomelist"

To create a new playlist, simply create a new object. The playlist will be created in the daemon's library automatically as soon as you use #add or #findadd. There is also no save method, as playlists get 'saved' by the daemon any time you do an action on them (add, delete, rename)., 'name')

Currently, one also has to pass in the MPD instance, as playlists are tied to a certain connection.


Callbacks are a simple way to make your client respond to events, rather that have to continuously ask the server for updates. This allows you to focus on displaying the data, rather that working overly hard to get it. This is done by having a background thread continuously check the server for changes. Because of this thead, enabling callbacks also means your client will stay connected to the server without having to worry about timeouts.

To make use of callbacks, we need to:

  1. Setup a callback to be called when something happens.

  2. Connect to the server with callbacks enabled.

Firstly, we need to create a callback block and subscribe it, so that will get triggered whenever a specific event happens. When the callback is triggered, it will also recieve the new values of the event that happened.

So how do we do this? We use the MPD#on method, which sets it all up for us. The argument takes a symbol with the name of the event. The function also requires a block, which is our actual callback that will get called.

mpd.on :volume do |volume|
  puts "Volume was set to #{volume}!"

One can also use separate methods or Procs and whatnot, just pass them in as a parameter.

# Proc
proc = {|volume| puts "Volume was set to #{volume}!" }
mpd.on :volume, &proc
# Method
def volume_change(value)
  puts "Volume changed to #{value}!"
method = self.method(:volume_change)
mpd.on :volume, &method

ruby-mpd supports callbacks for any of the keys returned by MPD#status, as well as :connection. Here's the full list of events, along with the variables it will return:

  • volume: The volume level as an Integer between 0-100.

  • repeat: true or false

  • random: true or false

  • single: true or false

  • consume: true or false

  • playlist: 31-bit unsigned Integer, the playlist version number.

  • playlistlength: Integer, the length of the playlist

  • state: :play, :stop, or :pause, state of the playback.

  • song: An MPD::Song object, representing the current song.

  • songid: playlist songid of the current song stopped on or playing.

  • nextsong: playlist song number of the next song to be played.

  • nextsongid: playlist songid of the next song to be played.

  • time: Returns two variables, *total* and *elapsed*, Integers representing seconds.

  • elapsed: Float, representing total time elapsed within the current song, but with higher accuracy.

  • bitrate: instantaneous bitrate in kbps.

  • xfade: crossfade in seconds

  • mixrampdb: mixramp threshold in dB (Float)

  • mixrampdelay: mixrampdelay in seconds

  • audio: Returns three variables: sampleRate, bits and channels.

  • updating_db: job id

  • error: if there is an error, returns message here

  • connection: Are we connected to the daemon? true or false

Note that if the callback returns more than one value, the callback needs more arguments in order to recieve those values:

mpd.on :audio do |sampleRate, bits, channels|
  puts bits
# or
mpd.on :audio do |*args|
  puts args.join(',')

Finally, the easiest step. In order for callbacks to work, connect to the server with callbacks enabled:

mpd.connect true

Easy as pie. The above will connect to the server like normal, but this time it will create a new thread that loops until you issue a `disconnect`. This loop checks the server, then sleeps for two tenths of a second, then loops. Because it's continuously polling the server, there's the added benefit of your client not being disconnected due to inactivity.

Not yet implemented

This section documents the features that are missing in this library at the moment.

Command lists

Command lists are not implemented yet. The proposed API would look like:

mpd.command_list do
  volume 80
  repeat true

What makes me not so eager to implement this is that MPD returns all values one after another. This gets fixed with command_list_ok_begin, which returns list_OK for every command used, however then we still get more than one response, and I can't think of a reasonable way to retun all of them back to the user. Maybe just ignore the return values?


To implement idle, what is needed is a lock that prevents sending commands to the daemon while waiting for the response (except noidle). An intermediate solution would be to queue the commands to send them later, when idle has returned the response.

Idle seems like a possible way to reimplement callbacks; make a separate connection and just use idle and when it returns, simply use idle again and again.


Tests fail at the moment, as they are 6 years old. The entire MPD server mock class either needs to be rewritten, or a mpd.conf along with a sample database and instructions for a controlled environment needs to be written.

TODO list

  • object oriented: song commands and dir commands in MPD::Song, MPD::Directory.

  • Make stickers a mixin for Playlist, Song, Directory…

  • Namespace queue

  • Playlist#rename -> Playlist#name=

  • Figure out a way to make passing the mpd instance to unnecessary.

  • Make parsing per-command (because playlist is an integer in the :status command and a string in :listplaylists, and :time is an array in status and integer in songs)

  • Per command parsing should also skip :directory and :playlist keys inside #songs command.