POE::Component::Client::MPD - full-blown poe-aware mpd client library
version 1.100430
use POE qw{ Component::Client::MPD }; POE::Component::Client::MPD->spawn( { host => 'localhost', port => 6600, password => 's3kr3t', # mpd password alias => 'mpd', # poe alias status_msgs_to => 'myapp', # session to send status info to } ); # ... later on ... $_[KERNEL]->post( mpd => 'next' );
POCOCM gives a clear message-passing interface (sitting on top of POE) for talking to and controlling MPD (Music Player Daemon) servers. A connection to the MPD server is established as soon as a new POCOCM object is created.
Commands are then sent to the server as messages are passed.
The hostname where MPD is running. Defaults to environment var MPD_HOST, then to 'localhost'. Note that MPD_HOST can be of the form password@host:port (each of password@ or :port can be omitted).
MPD_HOST
password@host:port
password@
:port
The port that MPD server listens to. Defaults to environment var MPD_PORT, then to parsed MPD_HOST (cf above), then to 6600.
MPD_PORT
The password to access special MPD functions. Defaults to environment var MPD_PASSWORD, then to parsed MPD_HOST (cf above), then to empty string.
MPD_PASSWORD
A string to alias the newly created POE session. Defaults to mpd.
mpd
A session (name or id) to whom to send connection status to. Optional, although recommended. No default. When this is done, pococm will send *additional* events to the session, such as: mpd_connected when pococm is connected, mpd_disconnected when pococm is disconnected, etc. You thus need to register some handlers for those events.
mpd_connected
mpd_disconnected
This method will create a POE session responsible for communicating with mpd. It will return the poe id of the session newly created. You can tune it by passing some arguments as a hash reference. See the attributes for allowed values.
The goal of a POCOCM session is to drive a remote MPD server. This can be achieved by a lot of events. Due to their sheer number, they have been regrouped logically in modules.
However, note that to use those events, you need to send them to the POCOCM session that you created with spawn() (see above). Indeed, the logical split is only internal: you are to use the same peer.
spawn()
For a list of public events that update and/or query MPD, see embedded pod in:
POE::Component::Client::MPD::Commands for general commands
POE::Component::Client::MPD::Playlist for playlist-related commands. Those events begin with pl..
pl.
POE::Component::Client::MPD::Collection for collection- related commands. Those events begin with coll..
coll.
Request the POCOCM to be shutdown. Leave mpd running. Generally sent when one wants to exit her program.
A POCOCM session will fire events, either to answer an incoming event, or to inform about some changes regarding the remote MPD server.
For each incoming event received by the POCOCM session, it will fire back one of the following answers:
mpd_result( $msg, $answer )
Indicates a success. $msg is a POE::Component::Client::MPD::Message object with the original request, to identify the issued command (see POE::Component::Client::MPD::Message pod for more information). Its status() attribute is true, further confirming success.
$msg
status()
$answer is what has been answered by the MPD server. Depending on the command, it can be either:
$answer
undef: commands play, etc.
undef
play
an Audio::MPD::Common::Stats object: command stats
stats
an Audio::MPD::Common::Status object: command status
status
an Audio::MPD::Common::Item object: commands song, etc.
song
an array reference: commands coll.files, etc.
coll.files
etc.
Refer to the documentation of each event to know what type of answer you can expect.
mpd_error( $msg, $errstr )
Indicates a failure. $msg is a POE::Component::Client::MPD::Message object with the original request, to identify the issued command (see POE::Component::Client::MPD::Message pod for more information). Its status() attribute is false, further confirming failure.
$errstr is what the error message as returned been answered by the MPD server.
$errstr
If you supplied the status_msgs_to attribute, the following events are fired to this peer by pococm:
status_msgs_to
mpd_connect_error( $reason )
Called when pococm-conn could not connect to a mpd server. It can be either retriable, or fatal. Check $reason for more information.
$reason
mpd_connected( )
Called when pococm-conn made sure we're talking to a mpd server.
mpd_disconnected( )
Called when pococm-conn has been disconnected from mpd server.
You can find more information on the mpd project on its homepage at http://www.musicpd.org, or its wiki http://mpd.wikia.com. You may want to have a look at Audio::MPD, a non-POE aware module to access MPD.
You can look for information on this module at:
Search CPAN
http://search.cpan.org/dist/POE-Component-Client-MPD
See open / report bugs
http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-Client-MPD
Mailing-list (same as Audio::MPD)
http://groups.google.com/group/audio-mpd
Git repository
http://github.com/jquelin/poe-component-client-mpd
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/POE-Component-Client-MPD
CPAN Ratings
http://cpanratings.perl.org/d/POE-Component-Client-MPD
Jerome Quelin
This software is copyright (c) 2007 by Jerome Quelin.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install POE::Component::Client::MPD, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE::Component::Client::MPD
CPAN shell
perl -MCPAN -e shell install POE::Component::Client::MPD
For more information on module installation, please visit the detailed CPAN module installation guide.