=head1 NAME

Audio::XMMSClient::Playlist - Playlists for Audio::XMMSClient

=head1 SYNOPSIS

  use Audio::XMMSClient;

  my $conn = Audio::XMMSClient->new($client_name);
  $conn->connect or die $conn->get_last_error;

  my $playlist = $conn->playlist($playlist_name);
  $playlist->shuffle;

=head1 DESCRIPTION

This module provides an abstraction for L<Audio::XMMSClient>'s playlists.

=head1 METHODS

=head2 list_entries

=over 4

=item Arguments: none

=item Return Value: $result

=back

  my $result = $playlist->list_entries;

List playlists content.


=cut

=head2 create

=over 4

=item Arguments: none

=item Return Value: $result

=back

  my $result = $playlist->create;

Creates a new empty playlist.


=cut

=head2 current_pos

=over 4

=item Arguments: none

=item Return Value: $result

=back

  my $result = $playlist->current_pos;

Retrives the current position in the playlist.


=cut

=head2 shuffle

=over 4

=item Arguments; none

=item Return Value: $result

=back

  my $result = $playlist->shuffle;

Shuffles the playlist.


=cut

=head2 sort

=over 4

=item Arguments: \@properties

=item Return Value: $result

=back

  my $result = $playlist->sort([qw/artist album tracknr/]);

Sorts the playlist according to the list of C<\@properties>.


=cut

=head2 clear

=over 4

=item Arguments: none

=item Return Value: $result

=back

  my $result = $playlist->clear;

Clears the playlist.


=cut

=head2 insert_id

=over 4

=item Arguments: $position, $id

=item Return Value: $result

=back

  my $result = $playlist->insert_id(2, 1337);

Insert a medialib C<$id> at given C<$position>.


=cut

=head2 insert_args

=over 4

=item Arguments: $position, $url, @args?

=item Return Value: $result

=back

  my $result = $playlist->insert_args(1, 'file://path/to/media/file.sid', 'subtune=2');

Insert a C<$url> at C<$position> with C<@args>.


=cut

=head2 insert_url

=over 4

=item Arguments: $position, $url

=item Return Value: $result

=back

  my $result = $playlist->insert_url(0, 'file://path/to/media/file.flac');

Insert C<$url> at C<$position>.


=cut

=head2 insert_encoded

=over 4

=item Arguments: $position, $url

=item Return Value: $result

=back

  my $result = $playlist->insert_encoded(5, $url);

Like L</insert_url>, except it expects C<$url> to be encoded already.


=cut

=head2 insert_collection

=over 4

=item Arguments: $position, $collection, \@order

=item Return Value: $result

=back

  my $result = $playlist->insert_collection(5, $coll, [qw/artist album tracknr/]);

Queries the medialib for entries matching C<$collection>, orders the results
by C<\@order> and inserts them at C<$position>.


=cut

=head2 add_id

=over 4

=item Arguments: $id

=item Return Value: $result

=back

  my $result = $playlist->add_id(9667);

Add a medialib C<$id> to the end of the playlist.


=cut

=head2 add_args

=over 4

=item Arguments: $url, @args?

=item Return Value: $result

=back

  my $result = $playlist->add_args('file:///path/to/media/file.sid', 'subtune=7');

Add a C<$url> with the given C<@args> to the playlists end.


=cut

=head2 add_url

=over 4

=item Arguments: $url

=item Return Value: $result

=back

  my $result = $playlist->add_url('file:///path/to/media/file.flac');

Add a C<$url> to the end of the playlist.


=cut

=head2 add_encoded

=over 4

=item Arguments: $url

=item Return Value: $result

=back

  my $result = $playlist->add_encoded($url);

Like L</add_url>, except it expects C<$url> to be encoded already.


=cut

=head2 add_collection

=over 4

=item Arguments: $collection, \@order

=back

  my $result = $playlist->add_collection($coll, [qw/artist album/]);

Query the medialib for entries matching C<$coll>, sort the results by
C<\@order> and add the results to the end of the playlist.


=cut

=head2 move_entry

=over 4

=item Arguments: $current_position, $new_position

=item Return Value: $result

=back

  my $result = $playlist->move_entry(3, 0);

Moves a playlist entry from C<$current_position> to C<$new_position>.


=cut

=head2 remove_entry

=over 4

=item Arguments: $position

=item Return Value: $result

=back

  my $result = $playlist->remove_entry(6);

Removes the playlist entry at C<$position>.


=cut

=head2 remove

=over 4

=item Arguments: none

=item Return Value: $result

=back

  my $result = $playlist->remove;

Remove the playlist.


=cut

=head2 load

=over 4

=item Arguments: none

=item Return Value: $result

=back

  my $result = $playlist->load;

Load a playlist as the current active playlist.


=cut

=head2 radd

=over 4

=item Arguments: $url

=item Return Value: $result

=back

  my $result = $playlist->radd($url);

Adds a C<$url> recursivly to the playlist. The C<$url> should be absolute to the
server-side.


=cut

=head2 radd_encoded

=over 4

=item Arguments: $url

=item Return Value: $result

=back

  my $result = $playlist->radd_encoded($url);

Same as L</radd>, except it expects C<$url> to be encoded already.


=cut

=head1 AUTHOR

Florian Ragwitz <rafl@debian.org>

=head1 SEE ALSO

L<Audio::XMMSClient>, L<Audio::XMMSClient::Result>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2006-2007, Florian Ragwitz

This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself, either Perl version 5.8.8 or, at your option,
any later version of Perl 5 you may have available.


=cut