ruby-mpd

Build Status Code Climate

ruby-mpd is a powerful object-oriented client for the Music Player Daemon, 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 as well as callbacks.

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.

Usage

Add to your Gemfile:

gem 'ruby-mpd'

Then bunde install, require and make a new MPD instance:

require ‘ruby-mpd’
mpd = MPD.new 'localhost', 6600

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

mpd = MPD.new 'localhost'
mpd = MPD.new

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

mpd.connect

When you are done, disconnect by calling disconnect.

mpd.disconnect

Note: In the past, one had to tackle the issue of the server possibly disconnecting the client at any time due to inactivity. Since 0.3.0, this is handled automatically via a reconnect mechanism.

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

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

Command documentation can be found here.

Commands

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

Options

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!

Ranges

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

The MPD protocol supports two commands find and search, where find is strict and will be case sensitive, as well as return only full matches, while search is "loose" -- case insensitive and allow partial matches.

For ease of use, ruby-mpd encapsulates both find and search in one method, MPD#where.

Searching is case loose by default, meaning it is case insensitive, and will do partial matching. To enable strict matching, enable the strict option.

This does not work for Playlist#searchadd.

mpd.where({artist: 'MyArtiSt'}, {strict: true})

Multiple query parameters can also be used:

mpd.where(artist: 'Bonobo', album: 'Black Sands')

Query keys can be any of of the tags supported by MPD (a list can be fetched via MPD#tags), or one of the two special parameters: :file to search by full path (relative to database root), and :any to match against all available tags.

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).

mpd.where({artist: 'MyArtiSt'}, {strict: true, add: true})

Queue searching

Queue searching works the same way (except by using MPD#queue_where), and it also accepts multiple search parameters (which seems to be undocumented in the MPD protocol specification).

Same as #where, it is "loose" by default, and it supports a :strict option.

mpd.queue_where(artist: 'James Brown', genre: 'Funk')
mpd.queue_where({artist: 'James Brown', genre: 'Funk'}, {strict: true})

Playlists

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 playlist.name # => "My playlist"
playlist.songs # => [MPD::Song, MPD::Song...]
playlist.rename('Awesomelist')
p playlist.name # => "Awesomelist"
playlist.add('awesome_track.mp3')

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 #searchadd. There is also no save method, as playlists get 'saved' by the daemon any time you do an action on them (add, delete, rename).

MPD::Playlist.new(mpd, 'name')

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

Callbacks

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.

To make use of callbacks, we need to:

  1. Setup a callback to be called when something happens.
  2. Create a MPD client instance 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}!"
end

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

# Using a Proc
proc = Proc.new { |volume| puts “Volume was set to #{volume}.” }
mpd.on :volume, &proc

# Using a method
def volume_change(value)
  puts “Volume changed to #{value}.”
end

handler = method(:volume_change)
mpd.on :volume, &handler

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 integers, elapsed and total, 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
end

# or
mpd.on :audio do |*args|
  puts args.join(‘,’)
end

Finally, the easiest step. In order for callbacks to work, create a MPD instance with callbacks enabled:

MPD.new ‘localhost’, 6600, { callbacks: 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.

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
  status
end

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?

Idle

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

There is the beginings of a test suite, that can be ran with:

$ bin/rspec spec/

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

  • MPD::Song, MPD::Directory.
  • Make stickers a mixin for Playlist, Song, Directory…
  • Namespace queue
  • Merge where and queue_where, by doing where(..., { in_queue: true})?