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