lib/Audio/MPD.pm

   1 #
   2 # This program is free software; you can redistribute it and/or modify
   3 # it under the terms of the GNU General Public License as published by
   4 # the Free Software Foundation; either version 2 of the License, or
   5 # (at your option) any later version.
   6 #
   7 # This program is distributed in the hope that it will be useful,
   8 # but WITHOUT ANY WARRANTY; without even the implied warranty of
   9 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  10 # GNU General Public License for more details.
  11 #
  12 # You should have received a copy of the GNU General Public License
  13 # along with this program; if not, write to the Free Software
  14 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  15 #
  16 #
  17
  18 package Audio::MPD;
  19
  20 use warnings;
  21 use strict;
  22
  23 use Audio::MPD::Collection;
  24 use Audio::MPD::Item;
  25 use Audio::MPD::Status;
  26 use Encode;
  27 use IO::Socket;
  28
  29
  30 use base qw[ Class::Accessor::Fast ];
  31 __PACKAGE__->mk_accessors( qw[ _host _password _port collection version ] );
  32
  33
  34 our $VERSION = '0.16.2';
  35
  36
  37 #--
  38 # Constructor
  39
  40 #
  41 # my $mpd = Audio::MPD->new( [$hostname], [$port], [$password] )
  42 #
  43 # This is the constructor for Audio::MPD. One can specify a $hostname, a
  44 # $port, and a $password.
  45 # If none is specified then defaults to environment vars MPD_HOST, MPD_PORT
  46 # and MPD_PASSWORD. If those aren't set, defaults to 'localhost', 6600 and ''.
  47 #
  48 sub new {
  49     my $class = shift;
  50     my ($host, $port, $password) = @_;
  51
  52     # use mpd defaults.
  53     $host     = $ENV{MPD_HOST}     || 'localhost' unless defined $host;
  54     $port     = $ENV{MPD_PORT}     || '6600'      unless defined $port;
  55     $password = $ENV{MPD_PASSWORD} || ''          unless defined $password;
  56
  57     # create & bless the object.
  58     my $self = {
  59         _host     => $host,
  60         _port     => $port,
  61         _password => $password,
  62     };
  63     bless $self, $class;
  64
  65     # create the collection object and store it.
  66     $self->collection( Audio::MPD::Collection->new($self) );
  67
  68     # try to issue a ping to test connection - this can die.
  69     $self->ping;
  70
  71     return $self;
  72 }
  73
  74
  75 #--
  76 # Private methods
  77
  78
  79 #
  80 # my @result = $mpd->_send_command( $command );
  81 #
  82 # This method is central to the module. It is responsible for interacting with
  83 # mpd by sending the $command and reading output - that will be returned as an
  84 # array of chomped lines (status line will not be returned).
  85 #
  86 # Note that currently, this method will connect to mpd before sending any
  87 # command, and will disconnect after the command has been issued. This scheme
  88 # is far from optimal, but allows us not to care about timeout disconnections.
  89 #
  90 # /!\ Note that we're using high-level, blocking sockets. This means that if
  91 # the mpd server is slow, or hangs for whatever reason, or even crash abruptly,
  92 # the program will be hung forever in this sub. The POE::Component::Client::MPD
  93 # module is way safer - you're advised to use it instead of Audio::MPD.
  94 #
  95 # This method can die on several conditions:
  96 #  - if the server cannot be reached,
  97 #  - if it's not an mpd server,
  98 #  - if the password is incorrect,
  99 #  - or if the command is an invalid mpd command.
 100 # In the latter case, the mpd error message will be returned.
 101 #
 102 sub _send_command {
 103     my ($self, $command) = @_;
 104
 105     # try to connect to mpd.
 106     my $socket = IO::Socket::INET->new(
 107         PeerAddr => $self->_host,
 108         PeerPort => $self->_port
 109     )
 110     or die "Could not create socket: $!\n";
 111     my $line;
 112
 113     # parse version information.
 114     $line = $socket->getline;
 115     chomp $line;
 116     die "Not a mpd server - welcome string was: [$line]\n"
 117         if $line !~ /^OK MPD (.+)$/;
 118     $self->version($1);
 119
 120     # send password.
 121     if ( $self->_password ) {
 122         $socket->print( 'password ' . encode('utf-8', $self->_password) . "\n" );
 123         $line = $socket->getline;
 124         die $line if $line =~ s/^ACK //;
 125     }
 126
 127     # ok, now we're connected - let's issue the command.
 128     $socket->print( encode('utf-8', $command) );
 129     my @output;
 130     while (defined ( $line = $socket->getline ) ) {
 131         chomp $line;
 132         die $line if $line =~ s/^ACK //; # oops - error.
 133         last if $line =~ /^OK/;          # end of output.
 134         push @output, decode('utf-8', $line);
 135     }
 136
 137     # close the socket.
 138     $socket->close;
 139
 140     return @output;
 141 }
 142
 143
 144 #
 145 # my @items = $mpd->_cooked_command_as_items( $command );
 146 #
 147 # Lots of Audio::MPD methods are using _send_command() and then parse the
 148 # output as a collection of Audio::MPD::Item. This method is meant to
 149 # factorize this code, and will parse the raw output of _send_command() in
 150 # a cooked list of items.
 151 #
 152 sub _cooked_command_as_items {
 153     my ($self, $command) = @_;
 154
 155     my @lines = $self->_send_command($command);
 156     my (@items, %param);
 157
 158     # parse lines in reverse order since "file:" or "directory:" lines
 159     # come first. therefore, let's first store every other parameter,
 160     # and the last line will trigger the object creation.
 161     # of course, since we want to preserve the playlist order, this means
 162     # that we're going to unshift the objects instead of push.
 163     foreach my $line (reverse @lines) {
 164         my ($k,$v) = split /:\s+/, $line, 2;
 165         $param{$k} = $v;
 166         next unless $k eq 'file' || $k eq 'directory'; # last param of item
 167         unshift @items, Audio::MPD::Item->new(%param);
 168         %param = ();
 169     }
 170
 171     return @items;
 172 }
 173
 174
 175 #
 176 # my @list = $mpd->_cooked_command_strip_first_field( $command );
 177 #
 178 # Lots of Audio::MPD methods are using _send_command() and then parse the
 179 # output to remove the first field (with the colon ":" acting as separator).
 180 # This method is meant to factorize this code, and will parse the raw output
 181 # of _send_command() in a cooked list of strings.
 182 #
 183 sub _cooked_command_strip_first_field {
 184     my ($self, $command) = @_;
 185
 186     my @list =
 187         map { ( split(/:\s+/, $_, 2) )[1] }
 188         $self->_send_command($command);
 189     return @list;
 190 }
 191
 192
 193 #--
 194 # Public methods
 195
 196 # -- MPD interaction: general commands
 197
 198 #
 199 # $mpd->ping;
 200 #
 201 # Sends a ping command to the mpd server.
 202 #
 203 sub ping {
 204     my ($self) = @_;
 205     $self->_send_command( "ping\n" );
 206 }
 207
 208
 209 #
 210 # my $version = $mpd->version;
 211 #
 212 # Return version of MPD server's connected.
 213 #
 214 # sub version {} # implemented as an accessor.
 215 #
 216
 217
 218 #
 219 # $mpd->kill;
 220 #
 221 # Send a message to the MPD server telling it to shut down.
 222 #
 223 sub kill {
 224     my ($self) = @_;
 225     $self->_send_command("kill\n");
 226 }
 227
 228
 229 #
 230 # $mpd->password( [$password] )
 231 #
 232 # Change password used to communicate with MPD server to $password.
 233 # Empty string is assumed if $password is not supplied.
 234 #
 235 sub password {
 236     my ($self, $passwd) = @_;
 237     $passwd ||= '';
 238     $self->_password($passwd);
 239     $self->ping; # ping sends a command, and thus the password is sent
 240 }
 241
 242
 243 #
 244 # $mpd->updatedb( [$path] );
 245 #
 246 # Force mpd to recan its collection. If $path (relative to MPD's music
 247 # directory) is supplied, MPD will only scan it - otherwise, MPD will rescan
 248 # its whole collection.
 249 #
 250 sub updatedb {
 251     my ($self, $path) = @_;
 252     $path ||= '';
 253     $self->_send_command("update $path\n");
 254 }
 255
 256
 257 #
 258 # my @handlers = $mpd->urlhandlers;
 259 #
 260 # Return an array of supported URL schemes.
 261 #
 262 sub urlhandlers {
 263     my ($self) = @_;
 264     return $self->_cooked_command_strip_first_field("urlhandlers\n");
 265 }
 266
 267
 268 # -- MPD interaction: handling volume & output
 269
 270 #
 271 # $mpd->volume( [+][-]$volume );
 272 #
 273 # Sets the audio output volume percentage to absolute $volume.
 274 # If $volume is prefixed by '+' or '-' then the volume is changed relatively
 275 # by that value.
 276 #
 277 sub volume {
 278     my ($self, $volume) = @_;
 279
 280     if ($volume =~ /^(-|\+)(\d+)/ )  {
 281         my $current = $self->status->volume;
 282         $volume = $1 eq '+' ? $current + $2 : $current - $2;
 283     }
 284     $self->_send_command("setvol $volume\n");
 285 }
 286
 287
 288 #
 289 # $mpd->output_enable( $output );
 290 #
 291 # Enable the specified audio output. $output is the ID of the audio output.
 292 #
 293 sub output_enable {
 294     my ($self, $output) = @_;
 295     $self->_send_command("enableoutput $output\n");
 296 }
 297
 298
 299 #
 300 # $mpd->output_disable( $output );
 301 #
 302 # Disable the specified audio output. $output is the ID of the audio output.
 303 #
 304 sub output_disable {
 305     my ($self, $output) = @_;
 306     $self->_send_command("disableoutput $output\n");
 307 }
 308
 309
 310
 311 # -- MPD interaction: retrieving info from current state
 312
 313 #
 314 # $mpd->stats;
 315 #
 316 # Return a hashref with the number of artists, albums, songs in the database,
 317 # as well as mpd uptime, the playtime of the playlist / the database and the
 318 # last update of the database.
 319 #
 320 sub stats {
 321     my ($self) = @_;
 322     my %kv =
 323         map { my ($k,$v) = split(/:\s+/, $_, 2); ($k => $v) }
 324         $self->_send_command( "stats\n" );
 325     return \%kv;
 326 }
 327
 328
 329 #
 330 # my $status = $mpd->status;
 331 #
 332 # Return an Audio::MPD::Status object with various information on current
 333 # MPD server settings. Check the embedded pod for more information on the
 334 # available accessors.
 335 #
 336 sub status {
 337     my ($self) = @_;
 338     my @output = $self->_send_command( "status\n" );
 339     my $status = Audio::MPD::Status->new( @output );
 340     return $status;
 341 }
 342
 343
 344 #
 345 # my $list = $mpd->playlist;
 346 #
 347 # Return an arrayref of C<Audio::MPD::Item::Song>s, one for each of the
 348 # songs in the current playlist.
 349 #
 350 sub playlist {
 351     my ($self) = @_;
 352
 353     my @list = $self->_cooked_command_as_items("playlistinfo\n");
 354     return \@list;
 355 }
 356
 357
 358 #
 359 # my $list = $mpd->pl_changes( $plversion );
 360 #
 361 # Return a list with all the songs (as API::Song objects) added to
 362 # the playlist since playlist $plversion.
 363 #
 364 sub pl_changes {
 365     my ($self, $plid) = @_;
 366
 367     return $self->_cooked_command_as_items("plchanges $plid\n");
 368 }
 369
 370
 371 #
 372 # my $song = $mpd->current;
 373 #
 374 # Return an C<Audio::MPD::Item::Song> representing the song currently playing.
 375 #
 376 sub current {
 377     my ($self) = @_;
 378     my ($item) = $self->_cooked_command_as_items("currentsong\n");
 379     return $item;
 380 }
 381
 382
 383 #
 384 # my $song = $mpd->song( [$song] )
 385 #
 386 # Return an C<Audio::MPD::Item::Song> representing the song number C<$song>.
 387 # If C<$song> is not supplied, returns the current song.
 388 #
 389 sub song {
 390     my ($self, $song) = @_;
 391     return $self->current unless defined $song;
 392     my ($item) = $self->_cooked_command_as_items("playlistinfo $song\n");
 393     return $item;
 394 }
 395
 396
 397 #
 398 # my $song = $mpd->songid( [$songid] )
 399 #
 400 # Return an C<Audio::MPD::Item::Song> representing the song with id C<$songid>.
 401 # If C<$songid> is not supplied, returns the current song.
 402 #
 403 sub songid {
 404     my ($self, $songid) = @_;
 405     return $self->current unless defined $songid;
 406     my ($item) = $self->_cooked_command_as_items("playlistid $songid\n");
 407     return $item;
 408 }
 409
 410
 411 # -- MPD interaction: altering settings
 412
 413 #
 414 # $mpd->repeat( [$repeat] );
 415 #
 416 # Set the repeat mode to $repeat (1 or 0). If $repeat is not specified then
 417 # the repeat mode is toggled.
 418 #
 419 sub repeat {
 420     my ($self, $mode) = @_;
 421
 422     $mode = not $self->status->repeat
 423         unless defined $mode; # toggle if no param
 424     $mode = $mode ? 1 : 0;               # force integer
 425     $self->_send_command("repeat $mode\n");
 426 }
 427
 428
 429 #
 430 # $mpd->random( [$random] );
 431 #
 432 # Set the random mode to $random (1 or 0). If $random is not specified then
 433 # the random mode is toggled.
 434 #
 435 sub random {
 436     my ($self, $mode) = @_;
 437
 438     $mode = not $self->status->random
 439         unless defined $mode; # toggle if no param
 440     $mode = $mode ? 1 : 0;               # force integer
 441     $self->_send_command("random $mode\n");
 442 }
 443
 444
 445 #
 446 # $mpd->fade( [$seconds] );
 447 #
 448 # Enable crossfading and set the duration of crossfade between songs. If
 449 # $seconds is not specified or $seconds is 0, then crossfading is disabled.
 450 #
 451 sub fade {
 452     my ($self, $value) = @_;
 453     $value ||= 0;
 454     $self->_send_command("crossfade $value\n");
 455 }
 456
 457
 458 # -- MPD interaction: controlling playback
 459
 460 #
 461 # $mpd->play( [$song] );
 462 #
 463 # Begin playing playlist at song number $song. If no argument supplied,
 464 # resume playing.
 465 #
 466 sub play {
 467     my ($self, $number) = @_;
 468     $number = '' unless defined $number;
 469     $self->_send_command("play $number\n");
 470 }
 471
 472 #
 473 # $mpd->playid( [$songid] );
 474 #
 475 # Begin playing playlist at song ID $songid. If no argument supplied,
 476 # resume playing.
 477 #
 478 sub playid {
 479     my ($self, $number) = @_;
 480     $number ||= '';
 481     $self->_send_command("playid $number\n");
 482 }
 483
 484
 485 #
 486 # $mpd->pause( [$sate] );
 487 #
 488 # Pause playback. If $state is 0 then the current track is unpaused, if
 489 # $state is 1 then the current track is paused.
 490 #
 491 # Note that if $state is not given, pause state will be toggled.
 492 #
 493 sub pause {
 494     my ($self, $state) = @_;
 495     $state ||= ''; # default is to toggle
 496     $self->_send_command("pause $state\n");
 497 }
 498
 499
 500 #
 501 # $mpd->stop;
 502 #
 503 # Stop playback.
 504 #
 505 sub stop {
 506     my ($self) = @_;
 507     $self->_send_command("stop\n");
 508 }
 509
 510
 511 #
 512 # $mpd->next;
 513 #
 514 # Play next song in playlist.
 515 #
 516 sub next {
 517     my ($self) = @_;
 518     $self->_send_command("next\n");
 519 }
 520
 521 #
 522 # $mpd->prev;
 523 #
 524 # Play previous song in playlist.
 525 #
 526 sub prev {
 527     my($self) = shift;
 528     $self->_send_command("previous\n");
 529 }
 530
 531
 532 #
 533 # $mpd->seek( $time, [$song]);
 534 #
 535 # Seek to $time seconds in song number $song. If $song number is not specified
 536 # then the perl module will try and seek to $time in the current song.
 537 #
 538 sub seek {
 539     my ($self, $time, $song) = @_;
 540     $time ||= 0; $time = int $time;
 541     $song = $self->status->song if not defined $song; # seek in current song
 542     $self->_send_command( "seek $song $time\n" );
 543 }
 544
 545
 546 #
 547 # $mpd->seekid( $time, $songid );
 548 #
 549 # Seek to $time seconds in song ID $songid. If $song number is not specified
 550 # then the perl module will try and seek to $time in the current song.
 551 #
 552 sub seekid {
 553     my ($self, $time, $song) = @_;
 554     $time ||= 0; $time = int $time;
 555     $song = $self->status->songid if not defined $song; # seek in current song
 556     $self->_send_command( "seekid $song $time\n" );
 557 }
 558
 559
 560 # -- MPD interaction: handling playlist
 561
 562 #
 563 # $mpd->add( $path );
 564 #
 565 # Add the song identified by $path (relative to MPD's music directory) to
 566 # the current playlist. No return value.
 567 #
 568 sub add {
 569     my ($self, $path) = @_;
 570     $self->_send_command( qq[add "$path"\n] );
 571 }
 572
 573
 574 #
 575 # $mpd->delete( $song [, $song [...] ] );
 576 #
 577 # Remove song number $song from the current playlist. No return value.
 578 #
 579 sub delete {
 580     my ($self, @songs) = @_;
 581     my $command =
 582           "command_list_begin\n"
 583         . join( '', map { "delete $_\n" } @songs )
 584         . "command_list_end\n";
 585     $self->_send_command( $command );
 586 }
 587
 588
 589 #
 590 # $mpd->deleteid( $songid [, $songid [...] ]);
 591 #
 592 # Remove the specified $songid from the current playlist. No return value.
 593 #
 594 sub deleteid {
 595     my ($self, @songs) = @_;
 596     my $command =
 597           "command_list_begin\n"
 598         . join( '', map { "deleteid $_\n" } @songs )
 599         . "command_list_end\n";
 600     $self->_send_command( $command );
 601 }
 602
 603
 604 #
 605 # $mpd->clear;
 606 #
 607 # Remove all the songs from the current playlist. No return value.
 608 #
 609 sub clear {
 610     my ($self) = @_;
 611     $self->_send_command("clear\n");
 612 }
 613
 614
 615 #
 616 # $mpd->crop;
 617 #
 618 #  Remove all of the songs from the current playlist *except* the current one.
 619 #
 620 sub crop {
 621     my ($self) = @_;
 622
 623     my $status = $self->status;
 624     my $cur = $status->song;
 625     my $len = $status->playlistlength - 1;
 626
 627     my $command =
 628           "command_list_begin\n"
 629         . join( '', map { $_  != $cur ? "delete $_\n" : '' } reverse 0..$len )
 630         . "command_list_end\n";
 631     $self->_send_command( $command );
 632 }
 633
 634
 635
 636 sub swap {
 637     my ($self, $from, $to) = @_;
 638     $self->_send_command("swap $from $to\n");
 639 }
 640
 641 sub swapid {
 642     my ($self, $from, $to) = @_;
 643     $self->_send_command("swapid $from $to\n");
 644 }
 645
 646 sub shuffle {
 647     my ($self) = @_;
 648     $self->_send_command("shuffle\n");
 649 }
 650
 651 sub move {
 652     my ($self, $song, $pos) = @_;
 653     $self->_send_command("move $song $pos\n");
 654 }
 655
 656 sub moveid {
 657     my ($self, $song, $pos) = @_;
 658     $self->_send_command("moveid $song $pos\n");
 659 }
 660
 661 sub load {
 662     my ($self, $playlist) = @_;
 663     return unless defined $playlist;
 664     $self->_send_command( qq[load "$playlist"\n] );
 665 }
 666
 667 sub save {
 668     my ($self, $playlist) = @_;
 669     return unless defined $playlist;
 670     $self->_send_command( qq[save "$playlist"\n] );
 671
 672 =begin FIXME
 673
 674     if(!$self->_process_feedback)
 675     {
 676         # Does the playlist already exist?
 677         if(${$self->get_error}[0] eq '56' && $config{'OVERWRITE_PLAYLIST'})
 678         {
 679             $self->rm($playlist);
 680             $self->save($playlist);
 681             return 1;
 682         }
 683     }
 684     return 1;
 685
 686 =end FIXME
 687
 688 =cut
 689
 690 }
 691
 692 sub rm {
 693     my ($self, $playlist) = @_;
 694     return unless defined $playlist;
 695     $self->_send_command( qq[rm "$playlist"\n] );
 696 }
 697
 698
 699
 700 ###############################################################
 701 #                     CUSTOM METHODS                          #
 702 #-------------------------------------------------------------#
 703 #   This section contains all methods not directly accessing  #
 704 #   MPD, but may be useful for most people using the module.  #
 705 ###############################################################
 706
 707
 708 sub get_time_format {
 709     my ($self) = shift;
 710
 711     # Get the time from MPD; example: 49:395 (seconds so far:total seconds)
 712     my ($sofar, $total) = split /:/, $self->status->time;
 713     return sprintf "%d:%02d/%d:%02d",
 714         ($sofar / 60), # minutes so far
 715         ($sofar % 60), # seconds - minutes so far
 716         ($total / 60), # minutes total
 717         ($total % 60);# seconds - minutes total
 718 }
 719
 720 sub get_time_info {
 721     my ($self) = @_;
 722
 723     # Get the time from MPD; example: 49:395 (seconds so far:total seconds)
 724     my ($sofar, $total) = split /:/, $self->status->time;
 725     my $left = $total - $sofar;
 726
 727     # Store seconds for everything
 728     my $rv = {};
 729     $rv->{seconds_so_far} = $sofar;
 730     $rv->{seconds_total}  = $total;
 731     $rv->{seconds_left}   = $left;
 732
 733     # Store the percentage; use one decimal point
 734     $rv->{percentage} =
 735     $rv->{seconds_total}
 736     ? 100*$rv->{seconds_so_far}/$rv->{seconds_total}
 737     : 0;
 738     $rv->{percentage} = sprintf "%.1f",$rv->{percentage};
 739
 740
 741     # Parse the time so far
 742     my $min_so_far = ($sofar / 60);
 743     my $sec_so_far = ($sofar % 60);
 744
 745     $rv->{time_so_far} = sprintf("%d:%02d", $min_so_far, $sec_so_far);
 746     $rv->{minutes_so_far} = sprintf("%00d", $min_so_far);
 747     $rv->{seconds_so_far} = sprintf("%00d", $sec_so_far);
 748
 749
 750     # Parse the total time
 751     my $min_tot = ($total / 60);
 752     my $sec_tot = ($total % 60);
 753
 754     $rv->{time_total} = sprintf("%d:%02d", $min_tot, $sec_tot);
 755     $rv->{minutes} = $min_tot;
 756     $rv->{seconds} = $sec_tot;
 757
 758     # Parse the time left
 759     my $min_left = ($left / 60);
 760     my $sec_left = ($left % 60);
 761     $rv->{time_left} = sprintf("-%d:%02d", $min_left, $sec_left);
 762
 763     return $rv;
 764 }
 765
 766
 767 1;
 768
 769
 770
 771 __END__
 772
 773 =pod
 774
 775 =head1 NAME
 776
 777 Audio::MPD - Class for talking to MPD (Music Player Daemon) servers
 778
 779
 780 =head1 SYNOPSIS
 781
 782     use Audio::MPD;
 783
 784     my $mpd = Audio::MPD->new();
 785     $mpd->play();
 786     sleep 10;
 787     $mpd->next();
 788
 789
 790 =head1 DESCRIPTION
 791
 792 Audio::MPD gives a clear object-oriented interface for talking to and
 793 controlling MPD (Music Player Daemon) servers. A connection to the MPD
 794 server is established as soon as a new Audio::MPD object is created.
 795 Commands are then sent to the server as the class's methods are called.
 796
 797
 798 =head1 METHODS
 799
 800 =head2 Constructor
 801
 802 =over 4
 803
 804 =item new( [$host] [, $port] [, $password] )
 805
 806 This is the constructor for Audio::MPD. One can specify a $hostname, a
 807 $port, and a $password.
 808
 809 If none is specified then defaults to environment vars MPD_HOST, MPD_PORT
 810 and MPD_PASSWORD. If those aren't set, defaults to 'localhost', 6600 and ''.
 811
 812 =back
 813
 814
 815 =head2 Controlling the server
 816
 817 =over 4
 818
 819 =item $mpd->ping()
 820
 821 Sends a ping command to the mpd server.
 822
 823
 824 =item $mpd->version()
 825
 826 Return the version number for the server we are connected to.
 827
 828
 829 =item $mpd->kill()
 830
 831 Send a message to the MPD server telling it to shut down.
 832
 833
 834 =item $mpd->password( [$password] )
 835
 836 Change password used to communicate with MPD server to $password.
 837 Empty string is assumed if $password is not supplied.
 838
 839
 840 =item $mpd->updatedb( [$path] )
 841
 842 Force mpd to recan its collection. If $path (relative to MPD's music directory)
 843 is supplied, MPD will only scan it - otherwise, MPD will rescan its whole
 844 collection.
 845
 846
 847 =item $mpd->urlhandlers()
 848
 849 Return an array of supported URL schemes.
 850
 851
 852 =back
 853
 854
 855 =head2 Handling volume & output
 856
 857 =over 4
 858
 859 =item $mpd->volume( [+][-]$volume )
 860
 861 Sets the audio output volume percentage to absolute $volume.
 862 If $volume is prefixed by '+' or '-' then the volume is changed relatively
 863 by that value.
 864
 865
 866 =item $mpd->output_enable( $output )
 867
 868 Enable the specified audio output. $output is the ID of the audio output.
 869
 870
 871 =item $mpd->output_disable( $output )
 872
 873 Disable the specified audio output. $output is the ID of the audio output.
 874
 875 =back
 876
 877
 878 =head2 Retrieving info from current state
 879
 880 =over 4
 881
 882 =item $mpd->stats()
 883
 884 Return a hashref with the number of artists, albums, songs in the database,
 885 as well as mpd uptime, the playtime of the playlist / the database and the
 886 last update of the database
 887
 888
 889 =item $mpd->status()
 890
 891 Return an C<Audio::MPD::Status> object with various information on current
 892 MPD server settings. Check the embedded pod for more information on the
 893 available accessors.
 894
 895
 896 =item $mpd->playlist( )
 897
 898 Return an arrayref of C<Audio::MPD::Item::Song>s, one for each of the
 899 songs in the current playlist.
 900
 901
 902 =item $mpd->pl_changes( $plversion )
 903
 904 Return a list with all the songs (as API::Song objects) added to
 905 the playlist since playlist $plversion.
 906
 907
 908 =item $mpd->current( )
 909
 910 Return an C<Audio::MPD::Item::Song> representing the song currently playing.
 911
 912
 913 =item $mpd->song( [$song] )
 914
 915 Return an C<Audio::MPD::Item::Song> representing the song number C<$song>. If
 916 C<$song> is not supplied, returns the current song.
 917
 918
 919 =item $mpd->songid( [$songid] )
 920
 921 Return an C<Audio::MPD::Item::Song> representing the song with id C<$songid>.
 922 If C<$songid> is not supplied, returns the current song.
 923
 924 =back
 925
 926
 927 =head2 Altering MPD settings
 928
 929 =over 4
 930
 931 =item $mpd->repeat( [$repeat] )
 932
 933 Set the repeat mode to $repeat (1 or 0). If $repeat is not specified then
 934 the repeat mode is toggled.
 935
 936
 937 =item $mpd->random( [$random] )
 938
 939 Set the random mode to $random (1 or 0). If $random is not specified then
 940 the random mode is toggled.
 941
 942
 943 =item $mpd->fade( [$seconds] )
 944
 945 Enable crossfading and set the duration of crossfade between songs.
 946 If $seconds is not specified or $seconds is 0, then crossfading is disabled.
 947
 948 =back
 949
 950
 951 =head2 Controlling playback
 952
 953 =over 4
 954
 955 =item $mpd->play( [$song] )
 956
 957 Begin playing playlist at song number $song. If no argument supplied,
 958 resume playing.
 959
 960
 961 =item $mpd->playid( [$songid] )
 962
 963 Begin playing playlist at song ID $songid. If no argument supplied,
 964 resume playing.
 965
 966
 967 =item $mpd->pause( [$state] )
 968
 969 Pause playback. If C<$state> is 0 then the current track is unpaused,
 970 if $state is 1 then the current track is paused.
 971
 972 Note that if C<$state> is not given, pause state will be toggled.
 973
 974
 975 =item $mpd->stop()
 976
 977 Stop playback.
 978
 979
 980 =item $mpd->next()
 981
 982 Play next song in playlist.
 983
 984
 985 =item $mpd->prev()
 986
 987 Play previous song in playlist.
 988
 989
 990 =item $mpd->seek( $time, [$song])
 991
 992 Seek to $time seconds in song number $song. If $song number is not specified
 993 then the perl module will try and seek to $time in the current song.
 994
 995
 996 =item $mpd->seekid( $time, $songid )
 997
 998 Seek to $time seconds in song ID $songid. If $song number is not specified
 999 then the perl module will try and seek to $time in the current song.
1000
1001 =back
1002
1003
1004 =head2 Handling playlist
1005
1006 =over 4
1007
1008 =item $mpd->add( $path )
1009
1010 Add the song identified by $path (relative to MPD's music directory) to the
1011 current playlist. No return value.
1012
1013
1014 =item $mpd->delete( $song )
1015
1016 Remove song number $song from the current playlist. No return value.
1017
1018
1019 =item $mpd->deleteid( $songid )
1020
1021 Remove the specified $songid from the current playlist. No return value.
1022
1023
1024 =item $mpd->clear()
1025
1026 Remove all the songs from the current playlist. No return value.
1027
1028
1029 =item $mpd->crop()
1030
1031 Remove all of the songs from the current playlist *except* the
1032 song currently playing.
1033
1034
1035 =item $mpd->swap( $song1, $song2 )
1036
1037 Swap positions of song number $song1 and $song2 on the current playlist. No
1038 return value.
1039
1040
1041 =item $mpd->swapid( $songid1, $songid2 )
1042
1043 Swap the postions of song ID $songid1 with song ID $songid2 on the current
1044 playlist. No return value.
1045
1046
1047 =item $mpd->move( $song, $newpos )
1048
1049 Move song number $song to the position $newpos. No return value.
1050
1051
1052 =item $mpd->moveid( $songid, $newpos )
1053
1054 Move song ID $songid to the position $newpos. No return value.
1055
1056
1057 =item $mpd->shuffle()
1058
1059 Shuffle the current playlist. No return value.
1060
1061
1062 =item $mpd->load( $playlist )
1063
1064 Load list of songs from specified $playlist file. No return value.
1065
1066
1067 =item $mpd->save( $playlist )
1068
1069 Save the current playlist to a file called $playlist in MPD's playlist
1070 directory. No return value.
1071
1072
1073 =item $mpd->rm( $playlist )
1074
1075 Delete playlist named $playlist from MPD's playlist directory. No return value.
1076
1077 =back
1078
1079
1080 =head2 Retrieving information from current playlist
1081
1082 =over 4
1083
1084 =item $mpd->get_time_format( )
1085
1086 Returns the current position and duration of the current song.
1087 String is formatted at "M:SS/M:SS", with current time first and total time
1088 after.
1089
1090
1091 =item $mpd->get_time_info( )
1092
1093 Return current timing information in various different formats
1094 contained in a hashref with the following keys:
1095
1096 =over 4
1097
1098 =item minutes_so_far
1099
1100 =item seconds_so_far
1101
1102 =item time_so_far
1103
1104 =item minutes
1105
1106 =item seconds
1107
1108 =item percentage
1109
1110 =item time_total
1111
1112 =item seconds_total
1113
1114 =item seconds_left
1115
1116 =item time_left
1117
1118 =back
1119
1120 =back
1121
1122
1123 =head2 Searching the collection
1124
1125 To search the collection, use the C<collection()> accessor, returning the
1126 associated C<Audio::MPD::Collection> object. You will then be able to call:
1127
1128     $mpd->collection->random_song();
1129
1130 See C<Audio::MPD::Collection> documentation for more details on available
1131 methods.
1132
1133
1134 =head1 SEE ALSO
1135
1136 You can find more information on the mpd project on its homepage at
1137 L<http://www.musicpd.org>, or its wiki L<http://mpd.wikia.com>.
1138
1139 Regarding this Perl module, you can report bugs on CPAN via
1140 L<http://rt.cpan.org/Public/Bug/Report.html?Queue=Audio-MPD>.
1141
1142 Audio::MPD development takes place on <audio-mpd@googlegroups.com>: feel free
1143 to join us. (use L<http://groups.google.com/group/audio-mpd> to sign in). Our
1144 subversion repository is located at L<https://svn.musicpd.org>.
1145
1146
1147
1148 =head1 AUTHORS
1149
1150 Jerome Quelin <jquelin@cpan.org>
1151
1152 Original code by Tue Abrahamsen <tue.abrahamsen@gmail.com>, documented by
1153 Nicholas J. Humfrey <njh@aelius.com>.
1154
1155
1156
1157 =head1 COPYRIGHT AND LICENSE
1158
1159 Copyright (c) 2005 Tue Abrahamsen <tue.abrahamsen@gmail.com>
1160
1161 Copyright (c) 2006 Nicholas J. Humfrey <njh@aelius.com>
1162
1163 Copyright (c) 2007 Jerome Quelin <jquelin@cpan.org>
1164
1165
1166 This program is free software; you can redistribute it and/or modify
1167 it under the terms of the GNU General Public License as published by
1168 the Free Software Foundation; either version 2 of the License, or
1169 (at your option) any later version.
1170
1171 This program is distributed in the hope that it will be useful,
1172 but WITHOUT ANY WARRANTY; without even the implied warranty of
1173 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
1174 GNU General Public License for more details.
1175
1176 =cut
1177