Audio::MPD(3)

NAME
Audio::MPD - class to talk to MPD (Music Player Daemon) servers

SYNOPSIS
    use Audio::MPD;

    my $mpd = Audio::MPD->new;
    $mpd->play;
    sleep 10;
    $mpd->next;

DESCRIPTION
"Audio::MPD" gives a clear object-oriented interface for talking to and controlling MPD (Music Player Daemon) servers. A connection to the MPD server is established as soon as a new "Audio::MPD" object is created.

Since mpd is still in 0.x versions, "Audio::MPD" sticks to latest mpd (0.14 as time of writing) protocol & behaviour, and does not try to maintain backward compatibility.

Note that the module will by default connect to mpd before sending any command, and will disconnect after the command has been issued. This scheme is far from optimal, but allows us not to care about timeout disconnections. Because of that, the "idle" command (new in mpd 0.14) is not (and will not) be supported in "Audio::MPD". This will be implemented in "POE::Component::Client::MPD".

/!\ Note that "Audio::MPD" is using high-level, blocking sockets. This means that if the mpd server is slow, or hangs for whatever reason, or even crash abruptly, the program will be hung forever in this sub. The "POE::Component::Client::MPD" module is way safer - you're advised to use it instead of "Audio::MPD". Or you can try to set "conntype" to $REUSE (see "Audio::MPD" constructor for more details), but you would be then on your own to deal with disconnections.

METHODS

  Constructor

new( [%opts] )
    This is the constructor for "Audio::MPD". One can specify the following options:

    host => $hostname
        defaults to environment var "MPD_HOST", then to 'localhost'. Note that "MPD_HOST" can be of the form password@host.

    port => $port
        defaults to environment var "MPD_PORT", then to 6600.

    password => $password
        defaults to environment var "MPD_PASSWORD", then to ''.

    conntype => $type
        change how the connection to mpd server is handled. It can be either $REUSE to reuse the same connection or $ONCE to open a new connection per command (default)

  Controlling the server

$mpd->ping()
    Sends a ping command to the mpd server.

$mpd->version()
    Return mpd's version number as advertised during connection. Note that mpd returns protocol version when connected. This protocol version can differ from the real mpd version. eg, mpd version 0.13.2 is "speaking" and thus advertising version 0.13.0.

$mpd->kill()
    Send a message to the MPD server telling it to shut down.

$mpd->password( [$password] )
    Change password used to communicate with MPD server to $password. Empty string is assumed if $password is not supplied.

$mpd->updatedb( [$path] )
    Force mpd to recan its collection. If $path (relative to MPD's music directory) is supplied, MPD will only scan it - otherwise, MPD will rescan its whole collection.

$mpd->urlhandlers()
    Return an array of supported URL schemes.

  Handling volume & output

$mpd->volume( [+][-]$volume )
    Sets the audio output volume percentage to absolute $volume. If $volume is prefixed by '+' or '-' then the volume is changed relatively by that value.

$mpd->output_enable( $output )
    Enable the specified audio output. $output is the ID of the audio output.

$mpd->output_disable( $output )
    Disable the specified audio output. $output is the ID of the audio output.

  Retrieving info from current state

$mpd->stats()
    Return an "Audio::MPD::Common::Stats" object with the current statistics of MPD. See the associated pod for more information.

$mpd->status()
    Return an "Audio::MPD::Common::Status" object with various information on current MPD server settings. Check the embedded pod for more information on the available accessors.

$mpd->current()
    Return an "Audio::MPD::Common::Item::Song" representing the song currently playing.

$mpd->song( [$song] )
    Return an "Audio::MPD::Common::Item::Song" representing the song number $song. If $song is not supplied, returns the current song.

$mpd->songid( [$songid] )
    Return an "Audio::MPD::Common::Item::Song" representing the song with id $songid. If $songid is not supplied, returns the current song.

  Altering MPD settings

$mpd->repeat( [$repeat] )
    Set the repeat mode to $repeat (1 or 0). If $repeat is not specified then the repeat mode is toggled.

$mpd->random( [$random] )
    Set the random mode to $random (1 or 0). If $random is not specified then the random mode is toggled.

$mpd->fade( [$seconds] )
    Enable crossfading and set the duration of crossfade between songs. If $seconds is not specified or $seconds is 0, then crossfading is disabled.

  Controlling playback

$mpd->play( [$song] )
    Begin playing playlist at song number $song. If no argument supplied, resume playing.

$mpd->playid( [$songid] )
    Begin playing playlist at song ID $songid. If no argument supplied, resume playing.

$mpd->pause( [$state] )
    Pause playback. If $state is 0 then the current track is unpaused, if $state is 1 then the current track is paused.

    Note that if $state is not given, pause state will be toggled.

$mpd->stop()
    Stop playback.

$mpd->next()
    Play next song in playlist.

$mpd->prev()
    Play previous song in playlist.

$mpd->seek( $time, [$song])
    Seek to $time seconds in song number $song. If $song number is not specified then the perl module will try and seek to $time in the current song.

$mpd->seekid( $time, $songid )
    Seek to $time seconds in song ID $songid. If $song number is not specified then the perl module will try and seek to $time in the current song.

  Searching the collection
To search the collection, use the "collection()" accessor, returning the associated "Audio::MPD::Collection" object. You will then be able to call:

    $mpd->collection->random_song;

See "Audio::MPD::Collection" documentation for more details on available methods.

  Handling the playlist
To update the playlist, use the "playlist()" accessor, returning the associated "Audio::MPD::Playlist" object. You will then be able to call:

    $mpd->playlist->clear;

See "Audio::MPD::Playlist" documentation for more details on available methods.

BUGS
Please report any bugs or feature requests to "bug-audio-mpd@rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Audio-MPD>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SEE ALSO
You can find more information on the mpd project on its homepage at <http://www.musicpd.org>.wikia.com>.

"Audio::MPD" development takes place on <audio-mpd@googlegroups.com>: feel free to join us. (use <http://groups.google.com/group/audio-mpd> to sign in). Our git repository is located at <git://repo.or.cz/audio-mpd.git>, and can be browsed at <http://repo.or.cz/w/audio-mpd.git>.

You can also look for information on this module at:

•   AnnoCPAN: Annotated CPAN documentation

    <http://annocpan.org/dist/Audio-MPD>

•   CPAN Ratings

    <http://cpanratings.perl.org/d/Audio-MPD>

•   Open bugs

    <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Audio-MPD>

AUTHOR
Jerome Quelin, "<jquelin@cpan.org>"

Original code by Tue Abrahamsen "<tue.abrahamsen@gmail.com>", documented by Nicholas J. Humfrey "<njh@aelius.com>".

COPYRIGHT & LICENSE
Copyright (c) 2005 Tue Abrahamsen, all rights reserved. Copyright (c) 2006 Nicolas J. Humfrey, all rights reserved. Copyright (c) 2007-2009 Jerome Quelin, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.