Audio::XMMSClient - Interface to the xmms2 music player
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;
This module provides a perl interface to the xmms2 client library.
my $conn = Audio::XMMSClient->new('foo');
Creates a new Audio::XMMSClient instance. If $client_name is omitted it will use the name of your application (see $0/$PROGRAM_NAME in perlvar).
my $success = $conn->connect;
Tries to establish a connection to the xmms2 server. If $ipcpath is omitted it will fall back to $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 "get_last_error".
$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. \&func will be called with either one or two arguments. The first one will be a reference to the connection. $data, if passed, will be the second argument of the callback.
$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 "io_out_handle" or "io_in_handle" will notice the disconnection and handle it accordingly.
my $message = $conn->get_last_error;
Returns a string that descibes the last error (if any).
my $result = $conn->main_list_plugins;
Get a list of loaded plugins from the server. $type, which may be used to only get a list of plugins of a specific type, can be any of the following strings:
If $type is omitted "all" is assumed.
my $result = $conn->main_stats;
Get a list of statistics from the server.
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.
my $result = $conn->broadcast_quit;
Request the quit broadcast. Will be called when the server is terminating.
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.
my $result = $conn->medialib_move_entry(42, 'file:///new/path/to/file.flac');
Change the url property of an entry in the media library. Note that you need to handle the actual file move yourself.
my $result = $conn->medialib_remove_entry(1337);
Remove a entry with a given ID from the medialib.
my $result = $conn->medialib_add_entry;
Add a $url to the medialib. If you want to add mutiple files you should call "medialib_path_import".
my $result = $conn->medialib_add_entry_args(
"file:///data/HVSC/C64Music/Hubbard_Rob/Commando.sid",
"subtune=2",
);
Add a $url with arguments to the medialib.
my $result = $conn->medialib_add_entry_encoded($url);
Same as "medialib_add_entry", except it expects an encoded $url.
my $playlist = $conn->playlist('jrock');
Returns an Audio::XMMSClient::Playlist instance representing a playlist specified by $playlist_name. If no $playlist_name is given "_active" will be used.
my $result = $conn->medialib_import_path('file:///media/music/');
Import a all files recursivly from $path. $path must include the protocol, i.e. file://.
my $result = $conn->medialib_import_path_encoded($path);
Same as "medialib_import_path" except it expects $path to be url encoded. You probably want to use "medialib_import_path" unless you want to add a path that comes as a result from the daemon, such as from /xform_media_browse.
my $result = $conn->medialib_rehash;
Rehash the medialib. This will check that data for entry $id in the medialib still is the same as in its data in files. If $id is omitted or set to 0 the full medialib will be rehashed.
my $result = $conn->medialib_get_info(9667);
Retrieve information about entry $id from the medialib.
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.
my $result = $conn->broadcast_medialib_entry_changed;
Request the medialib_entry_changed broadcast. This will be called if a entry changes on the serverside.
my $result = $conn->medialib_entry_property_set_int(1337, 'leet_level', 42);
Associate an integer $value with a property $key for medialib entry $id. Uses default source which is client/<clientname>.
my $result = $conn->medialib_entry_property_set_int_with_source(9667, 'client/generic', 'rating', 3);
Same as "medialib_entry_property_set_int", except it also allows to set the $source for the given property.
my $result = $conn->medialib_entry_property_set_str(431, 'fingerprint', '13f3ad');
Same as "medialib_entry_property_set_int", except it sets a string $value.
my $result = $conn->medialib_entry_property_set_str_with_source(542, 'client/generic', 'lyrics', <<'EOL'); Hey, Ho, Supergaul.. ... EOL
Same as "medialib_entry_property_set_str", except it also allows to set the $source for the given property.
my $result = $conn->medialib_entry_property_remove(431, 'fingerprint');
Remove a custom field specified by $key in the medialib associated with the entry $id.
my $result = $conn->medialib_entry_property_remove_with_source(542, 'client/generic', 'lyrics');
Like "medialib_entry_property_remove", but also allows to specify the $source.
my $coll = $conn->coll_get('Funk', 'Collections');
Get the collection structure of the collection $name saved on the server in a given $namespace.
my $result = $conn->coll_sync;
Synchronize collection data to the database.
my $result = $conn->coll_list('Collections');
List all collections saved on the server in a given $namespace.
my $result = $conn->coll_save('Funk', $collection, 'Collections');
Saves a $collection on the server under a given $name, in a given $namespace.
my $result = $conn->coll_remove('Funk', 'Collections');
Remove a collection from the server.
my $result = $conn->coll_find(542, 'Collections');
Find all collections in a given $namespace which contain the medialib entry with the given $mediaid.
my $result = $conn->coll_rename('Funk', 'Funky Music', 'Collections');
Rename a collection within a $namespace.
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 $collection. The returned list might be refined using the following parameters:
The list of properties to order by. undef or an empty array reference to disable.
The offset at which to start retrieving results. 0 to disable.
The maximum number of entries to retrieve. 0 to disable.
The above parameters might be passed either positional or within a hash reference.
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:
The list of properties to order by. undef or an empty array reference to disable.
The offset at which to start retrieving results. 0 to disable.
The maximum number of entries to retrieve. 0 to disable.
The list of properties to retrieve (at least one property required).
The list of properties to group by. undef or an empty array reference to disable.
The above parameters might be passed either positional or within a hash reference.
my $result = $conn->coll_query($collection, \@spec);
List the properties of all media matched by the given collection. The structure of the return value is determined by the fetch specification.
A collections fetch specification.
The above parameters might be passed either positional or within a hash reference.
my $result = $conn->broadcast_collection_changed;
Request the collection changed broadcast from the server. Everytime someone manipulates a collection this will be emitted.
my $result = $conn->xform_media_browse('file:///media/music/');
Browse available media in a $url.
my $result = $conn->xform_media_browse_encoded($url);
Same as "xform_media_browse", except it expects url to be url encoded already.
my $result = $conn->bindata_add($data);
Add binary data to the servers bindata directory.
my $result = $conn->bindata_retrieve($hash);
Retrieve a file from the servers bindata directory, based on the $hash.
my $result = $conn->bindata_remove($hash);
Remove a file from the servers bindata directory, based on the $hash.
my $result = $conn->bindata_list;
List all bindata hashes stored on the server.
my $result = $conn->config_register_value('myclient.stop_playback_on_quit', 0);
Registers a configvalue called $key with a $default_value in the server.
my $result = $conn->config_set_value('myclient.stop_playback_on_quit', 1);
Sets a configvalue called $key to $value in the server.
my $result = $conn->config_get_value('myclient.stop_playback_on_quit');
Retrieves the value of a configvalue called $key from the server.
my $result = $conn->config_list_values;
Lists all configuration values.
my $result = $conn->broadcast_config_value_changed;
Requests the config_value_changed broadcast. This will be called when a configvalue has been updated.
my $result = $conn->broadcast_mediainfo_reader_status;
Request status for the mediainfo reader. It can be idle or working.
my $result = $conn->signal_mediainfo_reader_unindexed;
Request number of unindexed entries in medialib.
Get the absolute path to the user config dir.
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.
my $result = $conn->playback_stop;
Stops the current playback. This will make the server idle.
my $result = $conn->playback_pause;
Pause the current playback, will tell the output to not read nor write.
my $result = $conn->playback_start;
Starts playback if server is idle.
my $result = $conn->playback_seek_ms(1000);
Seek in the current playback. The time is specified in $milliseconds. The whence parameter specifies whether the time is absolute (seek mode 'set') or relative to the current point in the song (seek mode 'cur'). The default is to seek using an absolute time.
my $result = $conn->playback_seek_samples(5000);
Seek in the current playback. The time is specified in $samples. The whence parameter specifies whether the time is absolute (seek mode 'set') or relative to the current point in the song (seek mode 'cur'). The default is to seek using an absolute time.
my $result = $conn->broadcast_playback_status;
Requests the playback status broadcast. This will be called when events like play, stop and pause is triggered.
my $result = $conn->playback_status;
Request the playback status.
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.
my $result = $conn->playback_current_id;
Request the current playback id.
my $result = $conn->signal_playback_playtime;
Request the playback_playtime signal. Will update the time we have played the current entry.
my $result = $conn->playback_playtime;
Request the current playtime.
my $result = $conn->playback_volume_set('left', 75);
Set the $volume for a given $channel.
my $result = $conn->playback_volume_get;
Get the current playback volume.
my $result = $conn->broadcast_playback_volume_changed;
Request the playback_volume_changed broadcast. This will be called when the playback volume changed.
my $result = $conn->playlist_list;
List the existing playlists.
my $result = $conn->broadcast_playlist_changed;
Request the playlist changed broadcast from the server. Everytime someone manipulate the playlist this will be emitted.
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.
my $result = $conn->broadcast_playlist_loaded;
Request the playlist_loaded broadcast. This will be called if a playlist is loaded server-side.
my $result = $conn->playlist_current_active;
Retrive the name of the active playlist.
my $result = $conn->playlist_set_next(7);
Set next entry in the playlist to the absolute position $pos.
my $result = $conn->playlist_set_next_rel(-1);
Same as "playlist_set_next" but relative to the current position.
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 $path.
my $has_pending_output = $conn->io_want_out;
Check for pending output.
my $success = $conn->io_out_handle;
Write pending data. Should be called when the mainloop flags that writing is available on the socket.
my $success = $conn->io_in_handle;
Read available data. Should be called when the mainloop flags that reading is available on the socket.
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 NOT be done on this fd. "io_in_handle" and "io_out_handle" MUST be used to handle reading and writing.
$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 $data, if specified; flag is true if output is wanted, false if not.
$conn->loop;
Starts a select-based mainloop which may be terminated by calling /quit_loop.
$conn->quit_loop;
Terminates the mainloop started with /loop.
Florian Ragwitz <rafl@debian.org>
You can find documentation for this module with the perldoc command.
perldoc Audio::XMMSClient
You can also look for information at:
Audio::XMMSClient::Result, Audio::XMMSClient::Playlist, Audio::XMMSClient::Collection
Copyright (C) 2006-2008, 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.