Class MPD
In: lib/librmpd.rb
Parent: Object

librmpd.rb

 librmpd.rb is another Ruby MPD Library with a goal of greater
 ease of use, more functionality, and thread safety

 Author:: Andrew Rader (bitwise_mcgee AT yahoo.com | http://nymb.us)
 Copyright:: Copyright (c) 2006 Andrew Rader
 License:: Distributed under the GNU GPL v2 (See COPYING file)

 This was written with MPD version 0.11.5 (http://www.musicpd.org)

 The main class is the MPD class. This provides the functionality for
 talking to the server as well as setting up callbacks for when events
 occur (such as song changes, state changes, etc). The use of callbacks
 is optional, if they are used a seperate thread will continuously poll
 the server on its status, when something is changed, your program will
 be notified via any callbacks you have set. Most methods are the same
 as specified in the MPD Server Protocol, however some have been modified
 or renamed. Most notable is the list* and lsinfo functions have been
 replace with more sane methods (such as `files` for all files)

Usage

 First create an MPD object

  require 'rubygems'
  require 'librmpd'

  mpd = MPD.new 'localhost', 6600

 and connect it to the server

  mpd.connect

 You can now issue any of the commands. Each command is documented below.

Callbacks

 Callbacks are a way to easily setup your client as event based, rather
 than polling based. This means rather than having to check for changes
 in the server, you setup a few methods that will be called when those
 changes occur. For example, you could have a 'state_changed' method
 that will be called whenever the server changes state. You could then
 have this method change a label to reflect to the new state.

 To use callbacks in your program, first setup your callback methods. For
 example, say you have the class MyClient. Simply define whatever
 callbacks you want inside your class. See the documentation on the
 callback type constants in the MPD class for details on how each callback
 is called

 Once you have your callback methods defined, use the register_callback
 methods to inform librmpd about them. You can have multiple callbacks
 for each type of callback without problems. Simply use object.method('method_name')
 to get a reference to a Method object. Pass this object to the
 register_callback (along with the proper type value), and you're set.

 An Example:

   class MyClient
    ...
    def state_callback( newstate )
     puts "MPD Changed State: #{newstate}"
    end
    ...
   end

   client = MyClient.new
   mpd = MPD.new
   mpd.register_callback(client.method('state_callback'), MPD::STATE_CALLBACK)

   # Connect and Enable Callbacks
   mpd.connect( true )

 In order for the callback to be used, you must enable callbacks when you
 connect by passing true to the connect method. Now, whenever the state changes
 on the server, myclientobj's state_callback method will be called (and passed
 the new state as an argument)

Methods

add   albums   artists   clear   clearerror   connect   connected?   crossfade   crossfade=   current_song   delete   deleteid   directories   disconnect   files   find   kill   list   load   move   moveid   new   next   password   pause=   paused?   ping   play   playid   playing?   playlist   playlist_changes   playlist_version   playlists   previous   random=   random?   register_callback   remove_playlist   repeat=   repeat?   rm   save   search   seek   seekid   shuffle   song_at_pos   song_with_id   songs   songs_by_artist   stats   status   stop   stopped?   swap   swapid   update   volume   volume=  

Classes and Modules

Class MPD::Song

Constants

STATE_CALLBACK = 0   STATE_CALLBACK: This is used to listen for changes in the server state

The callback will always be called with a single string argument which may an empty string.

CURRENT_SONG_CALLBACK = 1   CURRENT_SONG_CALLBACK: This is used to listen for changes in the current

song being played by the server.

The callback will always be called with a single argument, an MPD::Song object, or, if there were problems, nil

PLAYLIST_CALLBACK = 2   PLAYLIST_CALLBACK: This is used to listen for when changes in the playlist are made.

The callback will always be called with a single argument, an integer value for the current playlist or 0 if there were problems

TIME_CALLBACK = 3   TIME_CALLBACK: This is used to listen for when the playback time changes

The callback will always be called with two arguments. The first is the integer number of seconds elapsed (or 0 if errors), the second is the total number of seconds in the song (or 0 if errors)

VOLUME_CALLBACK = 4   VOLUME_CALLBACK: This is used to listen for when the volume changes

The callback will always be called with a single argument, an integer value of the volume (or 0 on errors)

REPEAT_CALLBACK = 5   REPEAT_CALLBACK: This is used to listen for changes to the repeat flag

The callback will always be called with a single argument, a boolean true or false depending on if the repeat flag is set / unset

RANDOM_CALLBACK = 6   RANDOM_CALLBACK: This is used to listen for changed to the random flag

The callback will always be called with a single argument, a boolean true or false depending on if the random flag is set / unset

PLAYLIST_LENGTH_CALLBACK = 7   PLAYLIST_LENGTH_CALLBACK: This is used to listen for changes to the playlist length

The callback will always be called with a single argument, an integer value of the current playlist‘s length (or 0 on errors)

CROSSFADE_CALLBACK = 8   CROSSFADE_CALLBACK: This is used to listen for changes in the crossfade setting

The callback will always be called with a single argument, an integer value of the number of seconds the crossfade is set to (or 0 on errsors)

CURRENT_SONGID_CALLBACK = 9   CURRENT_SONGID_CALLBACK: This is used to listen for changes in the current song‘s songid

The callback will always be called with a single argument, an integer value of the id of the current song (or 0 on errors)

BITRATE_CALLBACK = 10   BITRATE_CALLBACK: This is used to listen for changes in the playback bitrate

The callback will always be called with a single argument, an integer value of the bitrate of the playback (or 0 on errors)

AUDIO_CALLBACK = 11   AUDIO_CALLBACK: This is used to listen for changes in the audio quality data (sample rate etc)

The callback will always be called with three arguments, first, an integer holding the sample rate (or 0 on errors), next an integer holding the number of bits (or 0 on errors), finally an integer holding the number of channels (or 0 on errors)

CONNECTION_CALLBACK = 12   CONNECTION_CALLBACK: This is used to listen for changes in the connection to the server

The callback will always be called with a single argument, a boolean true if the client is now connected to the server, and a boolean false if it has been disconnected

Public Class methods

Initialize an MPD object with the specified hostname and port When called without arguments, ‘localhost’ and 6600 are used

Public Instance methods

Add the file path to the playlist. If path is a directory, it will be added recursively.

Returns true if this was successful, Raises a RuntimeError if the command failed

Lists all of the albums in the database The optional argument is for specifying an artist to list the albums for

Returns an Array of Album names (Strings), Raises a RuntimeError if the command failed

Lists all of the artists in the database

Returns an Array of Artist names (Strings), Raises a RuntimeError if the command failed

Clears the current playlist

Returns true if this was successful, Raises a RuntimeError if the command failed

Clears the current error message reported in status ( This is also accomplished by any command that starts playback )

Returns true if this was successful, Raises a RuntimeError if the command failed

Connect to the daemon When called without any arguments, this will just connect to the server and wait for your commands When called with true as an argument, this will enable callbacks by starting a seperate polling thread. This polling thread will also automatically reconnect If is disconnected for whatever reason.

connect will return OK plus the version string if successful, otherwise an error will be raised

If connect is called on an already connected instance, a RuntimeError is raised

Check if the client is connected

This will return true only if the server responds otherwise false is returned

Read the crossfade between songs in seconds, Raises a RuntimeError if the command failed

Set the crossfade between songs in seconds

Raises a RuntimeError if the command failed

Read the currently playing song

Returns a Song object with the current song‘s data, Raises a RuntimeError if the command failed

Delete the song from the playlist, where pos is the song‘s position in the playlist

Returns true if successful, Raises a RuntimeError if the command failed

Delete the song with the songid from the playlist

Returns true if successful, Raises a RuntimeError if the command failed

List all of the directories in the database, starting at path. If path isn‘t specified, the root of the database is used

Returns an Array of directory names (Strings), Raises a RuntimeError if the command failed

Disconnect from the server. This has no effect if the client is not connected. Reconnect using the connect method. This will also stop the callback thread, thus disabling callbacks

List all of the files in the database, starting at path. If path isn‘t specified, the root of the database is used

Returns an Array of file names (Strings). Raises a RuntimeError if the command failed

Finds songs in the database that are EXACTLY matched by the what argument. type should be ‘album’, ‘artist’, or ‘title‘

This returns an Array of MPD::Songs, Raises a RuntimeError if the command failed

Kills MPD

Returns true if successful. Raises a RuntimeError if the command failed

This is used by the albums and artists methods type should be ‘album’ or ‘artist’. If type is ‘album’ then arg can be a specific artist to list the albums for

Returns an Array of Strings, Raises a RuntimeError if the command failed

Loads the playlist name.m3u (do not pass the m3u extension when calling) from the playlist directory. Use `playlists` to what playlists are available

Returns true if successful, Raises a RuntimeError if the command failed

Move the song at `from` to `to` in the playlist

Returns true if successful, Raises a RuntimeError if the command failed

Move the song with the `songid` to `to` in the playlist

Returns true if successful, Raises a RuntimeError if the command failed

Plays the next song in the playlist

Returns true if successful, Raises a RuntimeError if the command failed

This is used for authentication with the server `pass` is simply the plaintext password

Raises a RuntimeError if the command failed

Set / Unset paused playback

Returns true if successful, Raises a RuntimeError if the command failed

Returns true if MPD is paused, Raises a RuntimeError if the command failed

Ping the server

Returns true if successful, Raises a RuntimeError if the command failed

Begin playing the playist. Optionally specify the pos to start on

Returns true if successful, Raises a RuntimeError if the command failed

Begin playing the playlist. Optionally specify the songid to start on

Returns true if successful, Raises a RuntimeError if the command failed

Returns true if the server‘s state is set to ‘play’, Raises a RuntimeError if the command failed

List the current playlist This is the same as playlistinfo w/o args

Returns an Array of MPD::Songs, Raises a RuntimeError if the command failed

List the changes since the specified version in the playlist

Returns an Array of MPD::Songs, Raises a RuntimeError if the command failed

Returns the current playlist version number, Raises a RuntimeError if the command failed

List all of the playlists in the database

Returns an Array of playlist names (Strings)

Plays the previous song in the playlist

Returns true if successful, Raises a RuntimeError if the command failed

Enable / Disable random playback, Raises a RuntimeError if the command failed

Returns true if random playback is currently enabled, Raises a RuntimeError if the command failed

This will store the given method onto the given type‘s callback list. First you must get a reference to the method to call by the following:

  callback_method = my_object.method 'method name'

Then you can call register_callback:

  mpd.register_callback( callback_method, MPD::STATE_CALLBACK )

Now my_object‘s ‘method name’ method will be called whenever the state changes

Enable / Disable repeat, Raises a RuntimeError if the command failed

Returns true if repeat is enabled, Raises a RuntimeError if the command failed

Removes (PERMANENTLY!) the playlist `playlist.m3u` from the playlist directory

Returns true if successful, Raises a RuntimeError if the command failed

Saves the current playlist to `playlist`.m3u in the playlist directory

Returns true if successful, Raises a RuntimeError if the command failed

Searches for any song that contains `what` in the `type` field `type` can be ‘title’, ‘artist’, ‘album’ or ‘filename’ Searches are NOT case sensitive

Returns an Array of MPD::Songs, Raises a RuntimeError if the command failed

Seeks to the position `time` (in seconds) of the song at `pos` in the playlist

Returns true if successful, Raises a RuntimeError if the command failed

Seeks to the position `time` (in seconds) of the song with the id `songid`

Returns true if successful, Raises a RuntimeError if the command failed

Shuffles the playlist, Raises a RuntimeError if the command failed

Returns the MPD::Song at the position `pos` in the playlist, Raises a RuntimeError if the command failed

Returns the MPD::Song with the `songid` in the playlist, Raises a RuntimeError if the command failed

List all of the songs in the database starting at path. If path isn‘t specified, the root of the database is used

Returns an Array of MPD::Songs, Raises a RuntimeError if the command failed

List all of the songs by an artist

Returns an Array of MPD::Songs by the artist `artist`, Raises a RuntimeError if the command failed

Returns a Hash of MPD‘s stats, Raises a RuntimeError if the command failed

Returns a Hash of the current status, Raises a RuntimeError if the command failed

Stop playing

Returns true if successful, Raises a RuntimeError if the command failed

Returns true if the server‘s state is ‘stop’, Raises a RuntimeError if the command failed

Swaps the song at position `posA` with the song as position `posB` in the playlist

Returns true if successful, Raises a RuntimeError if the command failed

Swaps the song with the id `songidA` with the song with the id `songidB`

Returns true if successful, Raises a RuntimeError if the command failed

Tell the server to update the database. Optionally, specify the path to update

Returns the volume, Raises a RuntimeError if the command failed

Set the volume The argument `vol` will automatically be bounded to 0 - 100

Raises a RuntimeError if the command failed

[Validate]