lib/Audio/MPD/Playlist.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::Playlist;
  19
  20 use strict;
  21 use warnings;
  22 use Scalar::Util qw[ weaken ];
  23
  24 use base qw[ Class::Accessor::Fast ];
  25 __PACKAGE__->mk_accessors( qw[ _mpd ] );
  26
  27
  28 #our ($VERSION) = '$Rev$' =~ /(\d+)/;
  29
  30
  31 #--
  32 # Constructor
  33
  34 #
  35 # my $collection = Audio::MPD::Playlist->new( $mpd );
  36 #
  37 # This will create the object, holding a back-reference to the Audio::MPD
  38 # object itself (for communication purposes). But in order to play safe and
  39 # to free the memory in time, this reference is weakened.
  40 #
  41 # Note that you're not supposed to call this constructor yourself, an
  42 # Audio::MPD::Playlist is automatically created for you during the creation
  43 # of an Audio::MPD object.
  44 #
  45 sub new {
  46     my ($pkg, $mpd) = @_;
  47
  48     my $self = { _mpd => $mpd };
  49     weaken( $self->{_mpd} );
  50     bless $self, $pkg;
  51     return $self;
  52 }
  53
  54
  55 #--
  56 # Public methods
  57
  58 # -- Playlist: retrieving information
  59
  60 #
  61 # my @items = $pl->as_items;
  62 #
  63 # Return an array of C<Audio::MPD::Item::Song>s, one for each of the
  64 # songs in the current playlist.
  65 #
  66 sub as_items {
  67     my ($self) = @_;
  68
  69     my @list = $self->_mpd->_cooked_command_as_items("playlistinfo\n");
  70     return @list;
  71 }
  72
  73
  74 #
  75 # my @items = $pl->items_changed_since( $plversion );
  76 #
  77 # Return a list with all the songs (as API::Song objects) added to
  78 # the playlist since playlist $plversion.
  79 #
  80 sub items_changed_since {
  81     my ($self, $plid) = @_;
  82     return $self->_mpd->_cooked_command_as_items("plchanges $plid\n");
  83 }
  84
  85
  86
  87 # -- Playlist: adding / removing songs
  88
  89 #
  90 # $pl->add( $path );
  91 #
  92 # Add the song identified by $path (relative to MPD's music directory) to
  93 # the current playlist. No return value.
  94 #
  95 sub add {
  96     my ($self, $path) = @_;
  97     $self->_mpd->_send_command( qq[add "$path"\n] );
  98 }
  99
 100
 101 #
 102 # $pl->delete( $song [, $song [...] ] );
 103 #
 104 # Remove song number $song (starting from 0) from the current playlist. No
 105 # return value.
 106 #
 107 sub delete {
 108     my ($self, @songs) = @_;
 109     my $command =
 110           "command_list_begin\n"
 111         . join( '', map { "delete $_\n" } @songs )
 112         . "command_list_end\n";
 113     $self->_mpd->_send_command( $command );
 114 }
 115
 116
 117 #
 118 # $pl->deleteid( $songid [, $songid [...] ]);
 119 #
 120 # Remove the specified $songid (as assigned by mpd when inserted in playlist)
 121 # from the current playlist. No return value.
 122 #
 123 sub deleteid {
 124     my ($self, @songs) = @_;
 125     my $command =
 126           "command_list_begin\n"
 127         . join( '', map { "deleteid $_\n" } @songs )
 128         . "command_list_end\n";
 129     $self->_mpd->_send_command( $command );
 130 }
 131
 132
 133 #
 134 # $pl->clear;
 135 #
 136 # Remove all the songs from the current playlist. No return value.
 137 #
 138 sub clear {
 139     my ($self) = @_;
 140     $self->_mpd->_send_command("clear\n");
 141 }
 142
 143
 144 #
 145 # $pl->crop;
 146 #
 147 #  Remove all of the songs from the current playlist *except* the current one.
 148 #
 149 sub crop {
 150     my ($self) = @_;
 151
 152     my $status = $self->_mpd->status;
 153     my $cur = $status->song;
 154     my $len = $status->playlistlength - 1;
 155
 156     my $command =
 157           "command_list_begin\n"
 158         . join( '', map { $_  != $cur ? "delete $_\n" : '' } reverse 0..$len )
 159         . "command_list_end\n";
 160     $self->_mpd->_send_command( $command );
 161 }
 162
 163
 164 # -- Playlist: changing playlist order
 165
 166 #
 167 # $pl->shuffle();
 168 #
 169 # Shuffle the current playlist. No return value.
 170 #
 171 sub shuffle {
 172     my ($self) = @_;
 173     $self->_mpd->_send_command("shuffle\n");
 174 }
 175
 176
 177 #
 178 # $pl->swap( $song1, $song2 );
 179 #
 180 # Swap positions of song number $song1 and $song2 in the current playlist.
 181 # No return value.
 182 #
 183 sub swap {
 184     my ($self, $from, $to) = @_;
 185     $self->_mpd->_send_command("swap $from $to\n");
 186 }
 187
 188
 189 #
 190 # $pl->swapid( $songid1, $songid2 );
 191 #
 192 # Swap the postions of song ID $songid1 with song ID $songid2 in the
 193 # current playlist. No return value.
 194 #
 195 sub swapid {
 196     my ($self, $from, $to) = @_;
 197     $self->_mpd->_send_command("swapid $from $to\n");
 198 }
 199
 200
 201 #
 202 # $pl->move( $song, $newpos );
 203 #
 204 # Move song number $song to the position $newpos. No return value.
 205 #
 206 sub move {
 207     my ($self, $song, $pos) = @_;
 208     $self->_mpd->_send_command("move $song $pos\n");
 209 }
 210
 211
 212 #
 213 # $pl->moveid( $songid, $newpos );
 214 #
 215 # Move song ID $songid to the position $newpos. No return value.
 216 #
 217 sub moveid {
 218     my ($self, $song, $pos) = @_;
 219     $self->_mpd->_send_command("moveid $song $pos\n");
 220 }
 221
 222
 223 # -- Playlist: managing playlists
 224
 225 #
 226 # $pl->load( $playlist );
 227 #
 228 # Load list of songs from specified $playlist file. No return value.
 229 #
 230 sub load {
 231     my ($self, $playlist) = @_;
 232     $self->_mpd->_send_command( qq[load "$playlist"\n] );
 233 }
 234
 235
 236 #
 237 # $pl->save( $playlist );
 238 #
 239 # Save the current playlist to a file called $playlist in MPD's playlist
 240 # directory. No return value.
 241 #
 242 sub save {
 243     my ($self, $playlist) = @_;
 244     $self->_mpd->_send_command( qq[save "$playlist"\n] );
 245 }
 246
 247
 248 #
 249 # $pl->rm( $playlist )
 250 #
 251 # Delete playlist named $playlist from MPD's playlist directory. No
 252 # return value.
 253 #
 254 sub rm {
 255     my ($self, $playlist) = @_;
 256     $self->_mpd->_send_command( qq[rm "$playlist"\n] );
 257 }
 258
 259
 260
 261 1;
 262
 263 __END__
 264
 265
 266 =head1 NAME
 267
 268 Audio::MPD::Playlist - an object to mess MPD's playlist
 269
 270
 271 =head1 SYNOPSIS
 272
 273     my $song = $mpd->playlist->randomize;
 274
 275
 276 =head1 DESCRIPTION
 277
 278 C<Audio::MPD::Playlist> is a class meant to access & update MPD's
 279 playlist.
 280
 281
 282 =head1 PUBLIC METHODS
 283
 284 =head2 Constructor
 285
 286 =over 4
 287
 288 =item new( $mpd )
 289
 290 This will create the object, holding a back-reference to the C<Audio::MPD>
 291 object itself (for communication purposes). But in order to play safe and
 292 to free the memory in time, this reference is weakened.
 293
 294 Note that you're not supposed to call this constructor yourself, an
 295 C<Audio::MPD::Playlist> is automatically created for you during the creation
 296 of an C<Audio::MPD> object.
 297
 298 =back
 299
 300
 301 =head2 Retrieving information
 302
 303 =over 4
 304
 305 =item $pl->as_items( )
 306
 307 Return an array of C<Audio::MPD::Item::Song>s, one for each of the
 308 songs in the current playlist.
 309
 310
 311 =item $pl->items_changed_since( $plversion )
 312
 313 Return a list with all the songs (as API::Song objects) added to
 314 the playlist since playlist $plversion.
 315
 316
 317 =back
 318
 319
 320 =head2 Adding / removing songs
 321
 322 =over 4
 323
 324 =item $pl->add( $path )
 325
 326 Add the song identified by C<$path> (relative to MPD's music directory) to the
 327 current playlist. No return value.
 328
 329
 330 =item $pl->delete( $song [, $song [...] ] )
 331
 332 Remove song number C<$song>s (starting from 0) from the current playlist. No
 333 return value.
 334
 335
 336 =item $pl->deleteid( $songid [, $songid [...] ] )
 337
 338 Remove the specified C<$songid>s (as assigned by mpd when inserted in playlist)
 339 from the current playlist. No return value.
 340
 341
 342 =item $pl->clear( )
 343
 344 Remove all the songs from the current playlist. No return value.
 345
 346
 347 =item $pl->crop( )
 348
 349 Remove all of the songs from the current playlist *except* the
 350 song currently playing.
 351
 352
 353 =back
 354
 355
 356 =head2 Changing playlist order
 357
 358 =over 4
 359
 360 =item $pl->shuffle( )
 361
 362 Shuffle the current playlist. No return value.
 363
 364
 365 =item $pl->swap( $song1, $song2 )
 366
 367 Swap positions of song number C<$song1> and C<$song2> in the current
 368 playlist. No return value.
 369
 370
 371 =item $pl->swapid( $songid1, $songid2 )
 372
 373 Swap the postions of song ID C<$songid1> with song ID C<$songid2> in the
 374 current playlist. No return value.
 375
 376
 377 =item $pl->move( $song, $newpos )
 378
 379 Move song number C<$song> to the position C<$newpos>. No return value.
 380
 381
 382 =item $pl->moveid( $songid, $newpos )
 383
 384 Move song ID C<$songid> to the position C<$newpos>. No return value.
 385
 386
 387 =back
 388
 389
 390 =head2 Managing playlists
 391
 392 =over 4
 393
 394 =item $pl->load( $playlist )
 395
 396 Load list of songs from specified C<$playlist> file. No return value.
 397
 398
 399 =item $pl->save( $playlist )
 400
 401 Save the current playlist to a file called C<$playlist> in MPD's playlist
 402 directory. No return value.
 403
 404
 405 =item $pl->rm( $playlist )
 406
 407 Delete playlist named C<$playlist> from MPD's playlist directory. No
 408 return value.
 409
 410
 411 =back
 412
 413
 414 =head1 SEE ALSO
 415
 416 You can find more information on the mpd project on its homepage at
 417 L<http://www.musicpd.org>, or its wiki L<http://mpd.wikia.com>.
 418
 419 Regarding this Perl module, you can report bugs on CPAN via
 420 L<http://rt.cpan.org/Public/Bug/Report.html?Queue=Audio-MPD>.
 421
 422 Audio::MPD development takes place on <audio-mpd@googlegroups.com>: feel free
 423 to join us. (use L<http://groups.google.com/group/audio-mpd> to sign in). Our
 424 subversion repository is located at L<https://svn.musicpd.org>.
 425
 426
 427 =head1 AUTHORS
 428
 429 Jerome Quelin <jquelin@cpan.org>
 430
 431
 432 =head1 COPYRIGHT AND LICENSE
 433
 434 Copyright (c) 2007 Jerome Quelin <jquelin@cpan.org>
 435
 436
 437 This program is free software; you can redistribute it and/or modify
 438 it under the terms of the GNU General Public License as published by
 439 the Free Software Foundation; either version 2 of the License, or
 440 (at your option) any later version.
 441
 442 This program is distributed in the hope that it will be useful,
 443 but WITHOUT ANY WARRANTY; without even the implied warranty of
 444 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 445 GNU General Public License for more details.
 446
 447 =cut