lib/Audio/MPD/Playlist.pm

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