=head1 NAME
Audio::XMMSClient - Interface to the xmms2 music player
=head1 SYNOPSIS
use Audio::XMMSClient;
my $conn = Audio::XMMSClient->new($client_name);
$conn->connect or die $c->get_last_error;
my $result = $c->playback_status;
$result->wait;
print $result->value;
=head1 DESCRIPTION
This module provides a perl interface to the xmms2 client library.
=head1 METHODS
=cut
=head2 new
=over 4
=item Arguments: $client_name?
=item Return Value: $connection
=back
my $conn = Audio::XMMSClient->new('foo');
Creates a new Audio::XMMSClient instance. If C<$client_name> is omitted it will
use the name of your application (see C<$0>/C<$PROGRAM_NAME> in L<perlvar>).
=cut
=head2 connect
=over 4
=item Arguments: $ipcpath?
=item Return Value: $success
=back
my $success = $conn->connect;
Tries to establish a connection to the xmms2 server. If C<$ipcpath> is omitted
it will fall back to C<$ENV{XMMS_PATH}> and, if that's unset as well, the
default ipcpath of libxmmsclient. If an error occurs a false value is returned
and a message describing the error can be obtained using L</get_last_error>.
=cut
=head2 disconnect_callback_set
=over 4
=item Arguments: \&func, $data?
=item Return Value: none
=back
$conn->disconnect_callback_set(sub { die 'got disconnected' });
Registers a function which will be called if the connection to the xmms2 server
gets abnormally terminated. C<\&func> will be called with either one or two
arguments. The first one will be a reference to the connection. C<$data>, if
passed, will be the second argument of the callback.
=cut
=head2 io_disconnect
=over 4
=item Arguments: none
=item Return Value: none
=back
$conn->io_disconnect;
Flags the connection as disconected. This is to be called when the mainloop
signals disconnection of the connection. This is optional, any call to
L</io_out_handle> or L</io_in_handle> will notice the disconnection and handle
it accordingly.
=cut
=head2 get_last_error
=over 4
=item Arguments: none
=item Return Value: $error_message
=back
my $message = $conn->get_last_error;
Returns a string that descibes the last error (if any).
=cut
=head2 plugin_list
=over 4
=item Arguments: $type?
=item Return Value: $result
=back
my $result = $conn->plugin_list;
Get a list of loaded plugins from the server. C<$type>, which may be used to
only get a list of plugins of a specific type, can be any of the following
strings:
=over 4
=item * output
=item * playlist
=item * effect
=item * xform
=item * all
=back
If C<$type> is omitted "all" is assumed.
=cut
=head2 main_stats
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->main_stats;
Get a list of statistics from the server.
=cut
=head2 quit
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->quit;
Tell the server to quit. This will terminate the server. If you only want to
disconnect just destroy all references to the connection instance.
=cut
=head2 broadcast_quit
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->broadcast_quit;
Request the quit broadcast. Will be called when the server is terminating.
=cut
=head2 medialib_get_id
=over 4
=item Arguments: $url
=item Return Value: $result
=back
my $result = $conn->medialib_get_id('file:///home/user/music/artist/album/track.flac');
Search for a entry (URL) in the medialib db and return its ID number.
=cut
=head2 medialib_remove_entry
=over 4
=item Arguments: $entry
=item Return Value: $result
=back
my $result = $conn->medialib_remove_entry(1337);
Remove a entry with a given ID from the medialib.
=cut
=head2 medialib_add_entry
=over 4
=item Arguments: $url
=item Return Value: $result
=back
my $result = $conn->medialib_add_entry;
Add a C<$url> to the medialib. If you want to add mutiple files you should call
L</medialib_path_import>.
=cut
=head2 medialib_add_entry_args
=over 4
=item Arguments: $url, @args?
=item Return Value: $result
=back
my $result = $conn->medialib_add_entry_args(
"file:///data/HVSC/C64Music/Hubbard_Rob/Commando.sid",
"subtune=2",
);
Add a C<$url> with arguments to the medialib.
=cut
=head2 medialib_add_entry_encoded
=over 4
=item Arguments: $url
=item Return Value: $result
=back
my $result = $conn->medialib_add_entry_encoded($url);
Same as L</medialib_add_entry>, except it expects an encoded C<$url>.
=cut
=head2 playlist
=over 4
=item Arguments: $playlist_name?
=item Return Value: $playlist
=back
my $playlist = $conn->playlist('jrock');
Returns an L<Audio::XMMSClient::Playlist> instance representing a playlist
specified by C<$playlist_name>. If no C<$playlist_name> is given "_active" will
be used.
=cut
=head2 medialib_path_import
=over 4
=item Arguments: $path
=item Return Value: $result
=back
my $result = $conn->medialib_path_import('file:///media/music/');
Import a all files recursivly from C<$path>. C<$path> must include the
protocol, i.e. file://.
=cut
=head2 medialib_path_import_encoded
=over 4
=item Arguments: $path
=item Return Value: $result
=back
my $result = $conn->medialib_path_import_encoded($path);
Same as L</medialib_path_import> except it expects C<$path> to be url encoded.
You probably want to use L</medialib_path_import> unless you want to add a path
that comes as a result from the daemon, such as from C</xform_media_browse>.
=cut
=head2 medialib_rehash
=over 4
=item Arguments: $id?
=item Return Value: $result
=back
my $result = $conn->medialib_rehash;
Rehash the medialib. This will check that data for entry C<$id> in the medialib
still is the same as in its data in files. If C<$id> is omitted or set to 0 the
full medialib will be rehashed.
=cut
=head2 medialib_get_info
=over 4
=item Arguments: $id
=item Return Value: $result
=back
my $result = $conn->medialib_get_info(9667);
Retrieve information about entry C<$id> from the medialib.
=cut
=head2 broadcast_medialib_entry_added
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->broadcast_medialib_entry_added;
Request the medialib_entry_added broadcast. This will be called if a new entry
is added to the medialib serverside.
=cut
=head2 broadcast_medialib_entry_changed
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->broadcast_medialib_entry_changed;
Request the medialib_entry_changed broadcast. This will be called if a entry
changes on the serverside.
=cut
=head2 medialib_entry_property_set_int
=over 4
=item Arguments: $id, $key, $value
=item Return Value: $result
=back
my $result = $conn->medialib_entry_property_set_int(1337, 'leet_level', 42);
Associate an integer C<$value> with a property C<$key> for medialib entry
C<$id>. Uses default source which is C<client/E<lt>clientnameE<gt>>.
=cut
=head2 medialib_entry_property_set_int_with_source
=over 4
=item Arguments: $source, $id, $key, $valu
=item Return Value: $result
=back
my $result = $conn->medialib_entry_property_set_int_with_source(9667, 'client/generic', 'rating', 3);
Same as L</medialib_entry_property_set_int>, except it also allows to set the
C<$source> for the given property.
=cut
=head2 medialib_entry_property_set_str
=over 4
=item Arguments: $id, $key, $value
=item Return Value: $result
=back
my $result = $conn->medialib_entry_property_set_str(431, 'fingerprint', '13f3ad');
Same as L</medialib_entry_property_set_int>, except it sets a string C<$value>.
=cut
=head2 medialib_entry_property_set_str_with_source
=over 4
=item Arguments: $id, $source, $key, $value
=item Return Value: $result
=back
my $result = $conn->medialib_entry_property_set_str_with_source(542, 'client/generic', 'lyrics', <<'EOL');
Hey, Ho, Supergaul..
...
EOL
Same as L</medialib_entry_property_set_str>, except it also allows to set the
C<$source> for the given property.
=cut
=head2 medialib_entry_property_remove
=over 4
=item Arguments: $id, $key
=item Return Value: $result
=back
my $result = $conn->medialib_entry_property_remove(431, 'fingerprint');
Remove a custom field specified by C<$key> in the medialib associated with the
entry C<$id>.
=cut
=head2 medialib_entry_property_remove_with_source
=over 4
=item Arguments: $id, $source, $key
=item Return Value: $result
=back
my $result = $conn->medialib_entry_property_remove_with_source(542, 'client/generic', 'lyrics');
Like L</medialib_entry_property_remove>, but also allows to specify the
C<$source>.
=cut
=head2 coll_get
=over 4
=item Arguments: $name, $namespace
=item Return Value: $collection
=back
my $coll = $conn->coll_get('Funk', 'Collections');
Get the collection structure of the collection C<$name> saved on the server in
a given C<$namespace>.
=cut
=head2 coll_list
=over 4
=item Arguments: $namespace
=item Return Value: $result
=back
my $result = $conn->coll_list('Collections');
List all collections saved on the server in a given C<$namespace>.
=cut
=head2 coll_save
=over 4
=item Arguments: $coll, $name, $namespace
=item Return Value: $result
=back
my $result = $conn->coll_save('Funk', $collection, 'Collections');
Saves a C<$collection> on the server under a given C<$name>, in a given
C<$namespace>.
=cut
=head2 coll_remove
=over 4
=item Arguments: $name, $namespace
=item Return Value: $result
=back
my $result = $conn->coll_remove('Funk', 'Collections');
Remove a collection from the server.
=cut
=head2 coll_find
=over 4
=item Arguments: $mediaid, $namespace
=item Return Value: $result
=back
my $result = $conn->coll_find(542, 'Collections');
Find all collections in a given C<$namespace> which contain the medialib entry
with the given C<$mediaid>.
=cut
=head2 coll_rename
=over 4
=item Arguments: $from, $to, $namespace
=item Return Value: $result
=back
my $result = $conn->coll_rename('Funk', 'Funky Music', 'Collections');
Rename a collection within a C<$namespace>.
=cut
=head2 coll_query_ids
=over 4
=item Arguments: $collection, \%args
=item Arguments: $collection, \@order?, $limit_start?, $limit_len?
=item Return Value: $result
=back
my $result = $conn->coll_query_ids($collection, {
order => [qw/artist album/],
limit_start => 0,
limit_len => 10,
});
List the ids of all media matched by a given C<$collection>. The returned list
might be refined using the following parameters:
=over 4
=item * order
The list of properties to order by. C<undef> or an empty array reference to
disable.
=item * limit_start
The offset at which to start retrieving results. C<0> to disable.
=item * limit_len
The maximum number of entries to retrieve. C<0> to disable.
=back
The above parameters might be passed either positional or within a hash
reference.
=cut
=head2 coll_query_infos
=over 4
=item Arguments: $collection, \%args
=item Arguments: $collection, \@order?, $limit_start?, $limit_len?, \@fetch?, \@group?
=item Return Value: $result
=back
my $result = $conn->coll_query_infos($collection, {
order => [qw/artist/],
limit_start => 0,
limit_len => 10,
fetch => [qw/artist/],
group => [qw/artist/],
});
List the properties of all media matched by the given collection. The returned
list might be refined using the following parameters:
=over 4
=item * order
The list of properties to order by. C<undef> or an empty array reference to
disable.
=item * limit_start
The offset at which to start retrieving results. C<0> to disable.
=item * limit_len
The maximum number of entries to retrieve. C<0> to disable.
=item * fetch
The list of properties to retrieve (at least one property required).
=item * group
The list of properties to group by. C<undef> or an empty array reference to
disable.
=back
The above parameters might be passed either positional or within a hash
reference.
=cut
=head2 broadcast_collection_changed
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->broadcast_collection_changed;
Request the collection changed broadcast from the server. Everytime someone
manipulates a collection this will be emitted.
=cut
=head2 xform_media_browse
=over 4
=item Arguments: $url
=item Return Value: $result
=back
my $result = $conn->xform_media_browse('file:///media/music/');
Browse available media in a C<$url>.
=cut
=head2 xform_media_browse_encoded
=over 4
=item Arguments: $url
=item Return Value: $result
=back
my $result = $conn->xform_media_browse_encoded($url);
Same as L</xform_media_browse>, except it expects C<url> to be url encoded
already.
=cut
=head2 bindata_add
=over 4
=item Arguments: $data
=item Return Value: $result
=back
my $result = $conn->bindata_add($data);
Add binary data to the servers bindata directory.
=cut
=head2 bindata_retrieve
=over 4
=item Arguments: $hash
=item Return Value: $result
=back
my $result = $conn->bindata_retrieve($hash);
Retrieve a file from the servers bindata directory, based on the C<$hash>.
=cut
=head2 bindata_remove
=over 4
=item Arguments: $hash
=item Return Value: $result
=back
my $result = $conn->bindata_remove($hash);
Remove a file from the servers bindata directory, based on the C<$hash>.
=cut
=head2 configval_register
=over 4
=item Arguments: $key, $default_value
=item Return Value: $result
=back
my $result = $conn->configval_register('myclient.stop_playback_on_quit', 0);
Registers a configvalue called C<$key> with a C<$default_value> in the server.
=cut
=head2 configval_set
=over 4
=item Arguments: $key, $value
=item Return Value: $result
=back
my $result = $conn->configval_set('myclient.stop_playback_on_quit', 1);
Sets a configvalue called C<$key> to C<$value> in the server.
=cut
=head2 configval_get
=over 4
=item Arguments: $key
=item Return Value: $result
=back
my $result = $conn->configval_get('myclient.stop_playback_on_quit');
Retrieves the value of a configvalue called C<$key> from the server.
=cut
=head2 configval_list
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->configval_list;
Lists all configuration values.
=cut
=head2 broadcast_configval_changed
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->broadcast_configval_changed;
Requests the configval_changed broadcast. This will be called when a
configvalue has been updated.
=cut
=head2 signal_visualisation_data
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->signal_visualisation_data;
Request the visualisation data signal.
=cut
=head2 broadcast_mediainfo_reader_status
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->broadcast_mediainfo_reader_status;
Request status for the mediainfo reader. It can be idle or working.
=cut
=head2 signal_mediainfo_reader_unindexed
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->signal_mediainfo_reader_unindexed;
Request number of unindexed entries in medialib.
=cut
=head2 userconfdir_get
=over 4
=item Arguments: none
=item Return Value: $path
=back
Get the absolute path to the user config dir.
=cut
=head2 playback_tickle
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->playback_tickle;
Stop decoding of current song. This will start decoding of the song set with
xmmsc_playlist_set_next, or the current song again if no
xmmsc_playlist_set_next was executed.
=cut
=head2 playback_stop
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->playback_stop;
Stops the current playback. This will make the server idle.
=cut
=head2 playback_pause
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->playback_pause;
Pause the current playback, will tell the output to not read nor write.
=cut
=head2 playback_start
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->playback_start;
Starts playback if server is idle.
=cut
=head2 playback_seek_ms
=over 4
=item Arguments: $milliseconds
=item Return Value: $result
=back
my $result = $conn->playback_seek_ms(1000);
Seek to a absolute time in the current playback. The time is specified in
C<$milliseconds>.
=cut
=head2 playback_seek_ms_rel
=over 4
=item Arguments: $milliseconds
=item Return Value: $result
=back
my $result = $conn->playback_seek_ms_rel(-1000);
Seek to a time relative to the current position in the current playback. Time
is specified in C<$milliseconds>.
=cut
=head2 playback_seek_samples
=over 4
=item Arguments: $samples
=item Return Value: $result
=back
my $result = $conn->playback_seek_samples(5000);
Seek to a absoulte number of C<$samples> in the current playback.
=cut
=head2 playback_seek_samples_rel
=over 4
=item Arguments: $samples
=item Return Value: $result
=back
my $result = $conn->playback_seek_samples_rel(-5000);
Seek to a number of C<$samples> relative to the current position in the current
playback.
=cut
=head2 broadcast_playback_status
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->broadcast_playback_status;
Requests the playback status broadcast. This will be called when events like
play, stop and pause is triggered.
=cut
=head2 playback_status
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->playback_status;
Request the playback status.
=cut
=head2 broadcast_playback_current_id
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->broadcast_playback_current_id;
Request the current id signal. This will be called then the current playing id
is changed. New song for example.
=cut
=head2 playback_current_id
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->playback_current_id;
Request the current playback id.
=cut
=head2 signal_playback_playtime
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->signal_playback_playtime;
Request the playback_playtime signal. Will update the time we have played the
current entry.
=cut
=head2 playback_playtime
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->playback_playtime;
Request the current playtime.
=cut
=head2 playback_volume_set
=over 4
=item Arguments: $channel, $volume
=item Return Value: $result
=back
my $result = $conn->playback_volume_set('left', 75);
Set the C<$volume> for a given C<$channel>.
=cut
=head2 playback_volume_get
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->playback_volume_get;
Get the current playback volume.
=cut
=head2 broadcast_playback_volume_changed
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->broadcast_playback_volume_changed;
Request the playback_volume_changed broadcast. This will be called when the
playback volume changed.
=cut
=head2 playlist_list
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->playlist_list;
List the existing playlists.
=cut
=head2 broadcast_playlist_changed
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->broadcast_playlist_changed;
Request the playlist changed broadcast from the server. Everytime someone
manipulate the playlist this will be emitted.
=cut
=head2 broadcast_playlist_current_pos
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->broadcast_playlist_current_pos;
Request the playlist current pos broadcast. When the position in the playlist
is changed this will be called.
=cut
=head2 broadcast_playlist_loaded
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->broadcast_playlist_loaded;
Request the playlist_loaded broadcast. This will be called if a playlist is
loaded server-side.
=cut
=head2 playlist_current_active
=over 4
=item Arguments: none
=item Return Value: $result
=back
my $result = $conn->playlist_current_active;
Retrive the name of the active playlist.
=cut
=head2 playlist_set_next
=over 4
=item Arguments: $pos
=item Return Value: $result
=back
my $result = $conn->playlist_set_next(7);
Set next entry in the playlist to the absolute position C<$pos>.
=cut
=head2 playlist_set_next_rel
=over 4
=item Arguments: $pos
=item Return Value: $result
=back
my $result = $conn->playlist_set_next_rel(-1);
Same as L</playlist_set_next> but relative to the current position.
=cut
=head2 coll_idlist_from_playlist_file
=over 4
=item Arguments: $path
=item Return Value: $result
=back
my $result = $conn->coll_idlist_from_playlist_file('file:///path/to/some/playlist.m3u');
Create a new collections structure with type idlist from a playlist file at
C<$path>.
=cut
=head2 io_want_out
=over 4
=item Arguments: none
=item Return Value: 1 | 0
=back
my $has_pending_output = $conn->io_want_out;
Check for pending output.
=cut
=head2 io_out_handle
=over 4
=item Arguments: none
=item Return Value: $success
=back
my $success = $conn->io_out_handle;
Write pending data. Should be called when the mainloop flags that writing is
available on the socket.
=cut
=head2 io_in_handle
=over 4
=item Arguments: none
=item Return Value: $success
=back
my $success = $conn->io_in_handle;
Read available data. Should be called when the mainloop flags that reading is
available on the socket.
=cut
=head2 io_fd_get
=over 4
=item Arguments: none
=item Return Value: $fd | -1
=back
my $fd = $conn->io_fd_get;
Retrieve filedescriptor for the connection. Returns -1 on error. This is to be
used in a mainloop to do poll/select on. Reading and writing should B<NOT> be
done on this fd. L</io_in_handle> and L</io_out_handle> B<MUST> be used to
handle reading and writing.
=cut
=head2 io_need_out_callback_set
=over 4
=item Arguments: \&func, $data?
=item Return Value: none
=back
$conn->io_need_out_callback_set(sub { ... });
Set callback for enabling/disabling writing.
If the mainloop doesn't provide a mechanism to run code before each iteration
this function allows registration of a callback to be called when output is
needed or not needed any more. The arguments to the callback are the
connection, flags and C<$data>, if specified; flag is true if output is wanted,
false if not.
=cut
=head1 AUTHOR
Florian Ragwitz <rafl@debian.org>
=head1 SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Audio::XMMSClient
You can also look for information at:
=over 4
=item * AnnoCPAN: Annotated CPAN documentation
L<http://annocpan.org/dist/Audio-XMMSClient>
=item * CPAN Ratings
L<http://cpanratings.perl.org/d/Audio-XMMSClient>
=item * RT: CPAN's request tracker
L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Audio-XMMSClient>
=item * Search CPAN
L<http://search.cpan.org/dist/Audio-XMMSClient>
=back
=head1 SEE ALSO
L<Audio::XMMSClient::Result>, L<Audio::XMMSClient::Playlist>, L<Audio::XMMSClient::Collection>
=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