Class | MPD |
In: |
lib/librmpd.rb
|
Parent: | Object |
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)
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 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)
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 |
Initialize an MPD object with the specified hostname and port When called without arguments, ‘localhost’ and 6600 are used
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 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 currently playing song
Returns a Song object with the current song‘s data, 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
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
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
This is used for authentication with the server `pass` is simply the plaintext password
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
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
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
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 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
Set the volume The argument `vol` will automatically be bounded to 0 - 100
Raises a RuntimeError if the command failed