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