/ 
Audio-XMMSClient-0.03
River stage one • 2 direct dependents • 2 total dependents
/ Audio::XMMSClient

NAME

Audio::XMMSClient - Interface to the xmms2 music player

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;

DESCRIPTION

This module provides a perl interface to the xmms2 client library.

METHODS

new

Arguments: $client_name?
Return Value: $connection
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).

connect

Arguments: $ipcpath?
Return Value: $success
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".

disconnect_callback_set

Arguments: \&func, $data?
Return Value: none
$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.

io_disconnect

Arguments: none
Return Value: none
$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.

get_last_error

Arguments: none
Return Value: $error_message
my $message = $conn->get_last_error;

Returns a string that descibes the last error (if any).

plugin_list

Arguments: $type?
Return Value: $result
my $result = $conn->plugin_list;

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:

  • output

  • playlist

  • effect

  • xform

  • all

If $type is omitted "all" is assumed.

main_stats

Arguments: none
Return Value: $result
my $result = $conn->main_stats;

Get a list of statistics from the server.

quit

Arguments: none
Return Value: $result
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.

broadcast_quit

Arguments: none
Return Value: $result
my $result = $conn->broadcast_quit;

Request the quit broadcast. Will be called when the server is terminating.

medialib_get_id

Arguments: $url
Return Value: $result
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.

medialib_remove_entry

Arguments: $entry
Return Value: $result
my $result = $conn->medialib_remove_entry(1337);

Remove a entry with a given ID from the medialib.

medialib_add_entry

Arguments: $url
Return Value: $result
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".

medialib_add_entry_args

Arguments: $url, @args?
Return Value: $result
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.

medialib_add_entry_encoded

Arguments: $url
Return Value: $result
my $result = $conn->medialib_add_entry_encoded($url);

Same as "medialib_add_entry", except it expects an encoded $url.

playlist

Arguments: $playlist_name?
Return Value: $playlist
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.

medialib_path_import

Arguments: $path
Return Value: $result
my $result = $conn->medialib_path_import('file:///media/music/');

Import a all files recursivly from $path. $path must include the protocol, i.e. file://.

medialib_path_import_encoded

Arguments: $path
Return Value: $result
my $result = $conn->medialib_path_import_encoded($path);

Same as "medialib_path_import" except it expects $path to be url encoded. You probably want to use "medialib_path_import" unless you want to add a path that comes as a result from the daemon, such as from /xform_media_browse.

medialib_rehash

Arguments: $id?
Return Value: $result
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.

medialib_get_info

Arguments: $id
Return Value: $result
my $result = $conn->medialib_get_info(9667);

Retrieve information about entry $id from the medialib.

broadcast_medialib_entry_added

Arguments: none
Return Value: $result
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.

broadcast_medialib_entry_changed

Arguments: none
Return Value: $result
my $result = $conn->broadcast_medialib_entry_changed;

Request the medialib_entry_changed broadcast. This will be called if a entry changes on the serverside.

medialib_entry_property_set_int

Arguments: $id, $key, $value
Return Value: $result
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>.

medialib_entry_property_set_int_with_source

Arguments: $source, $id, $key, $valu
Return Value: $result
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.

medialib_entry_property_set_str

Arguments: $id, $key, $value
Return Value: $result
my $result = $conn->medialib_entry_property_set_str(431, 'fingerprint', '13f3ad');

Same as "medialib_entry_property_set_int", except it sets a string $value.

medialib_entry_property_set_str_with_source

Arguments: $id, $source, $key, $value
Return Value: $result
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.

medialib_entry_property_remove

Arguments: $id, $key
Return Value: $result
my $result = $conn->medialib_entry_property_remove(431, 'fingerprint');

Remove a custom field specified by $key in the medialib associated with the entry $id.

medialib_entry_property_remove_with_source

Arguments: $id, $source, $key
Return Value: $result
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.

coll_get

Arguments: $name, $namespace
Return Value: $collection
my $coll = $conn->coll_get('Funk', 'Collections');

Get the collection structure of the collection $name saved on the server in a given $namespace.

coll_list

Arguments: $namespace
Return Value: $result
my $result = $conn->coll_list('Collections');

List all collections saved on the server in a given $namespace.

coll_save

Arguments: $coll, $name, $namespace
Return Value: $result
my $result = $conn->coll_save('Funk', $collection, 'Collections');

Saves a $collection on the server under a given $name, in a given $namespace.

coll_remove

Arguments: $name, $namespace
Return Value: $result
my $result = $conn->coll_remove('Funk', 'Collections');

Remove a collection from the server.

coll_find

Arguments: $mediaid, $namespace
Return Value: $result
my $result = $conn->coll_find(542, 'Collections');

Find all collections in a given $namespace which contain the medialib entry with the given $mediaid.

coll_rename

Arguments: $from, $to, $namespace
Return Value: $result
my $result = $conn->coll_rename('Funk', 'Funky Music', 'Collections');

Rename a collection within a $namespace.

coll_query_ids

Arguments: $collection, \%args
Arguments: $collection, \@order?, $limit_start?, $limit_len?
Return Value: $result
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:

  • order

    The list of properties to order by. undef or an empty array reference to disable.

  • limit_start

    The offset at which to start retrieving results. 0 to disable.

  • limit_len

    The maximum number of entries to retrieve. 0 to disable.

The above parameters might be passed either positional or within a hash reference.

coll_query_infos

Arguments: $collection, \%args
Arguments: $collection, \@order?, $limit_start?, $limit_len?, \@fetch?, \@group?
Return Value: $result
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:

  • order

    The list of properties to order by. undef or an empty array reference to disable.

  • limit_start

    The offset at which to start retrieving results. 0 to disable.

  • limit_len

    The maximum number of entries to retrieve. 0 to disable.

  • fetch

    The list of properties to retrieve (at least one property required).

  • group

    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.

broadcast_collection_changed

Arguments: none
Return Value: $result
my $result = $conn->broadcast_collection_changed;

Request the collection changed broadcast from the server. Everytime someone manipulates a collection this will be emitted.

xform_media_browse

Arguments: $url
Return Value: $result
my $result = $conn->xform_media_browse('file:///media/music/');

Browse available media in a $url.

xform_media_browse_encoded

Arguments: $url
Return Value: $result
my $result = $conn->xform_media_browse_encoded($url);

Same as "xform_media_browse", except it expects url to be url encoded already.

bindata_add

Arguments: $data
Return Value: $result
my $result = $conn->bindata_add($data);

Add binary data to the servers bindata directory.

bindata_retrieve

Arguments: $hash
Return Value: $result
my $result = $conn->bindata_retrieve($hash);

Retrieve a file from the servers bindata directory, based on the $hash.

bindata_remove

Arguments: $hash
Return Value: $result
my $result = $conn->bindata_remove($hash);

Remove a file from the servers bindata directory, based on the $hash.

configval_register

Arguments: $key, $default_value
Return Value: $result
my $result = $conn->configval_register('myclient.stop_playback_on_quit', 0);

Registers a configvalue called $key with a $default_value in the server.

configval_set

Arguments: $key, $value
Return Value: $result
my $result = $conn->configval_set('myclient.stop_playback_on_quit', 1);

Sets a configvalue called $key to $value in the server.

configval_get

Arguments: $key
Return Value: $result
my $result = $conn->configval_get('myclient.stop_playback_on_quit');

Retrieves the value of a configvalue called $key from the server.

configval_list

Arguments: none
Return Value: $result
my $result = $conn->configval_list;

Lists all configuration values.

broadcast_configval_changed

Arguments: none
Return Value: $result
my $result = $conn->broadcast_configval_changed;

Requests the configval_changed broadcast. This will be called when a configvalue has been updated.

signal_visualisation_data

Arguments: none
Return Value: $result
my $result = $conn->signal_visualisation_data;

Request the visualisation data signal.

broadcast_mediainfo_reader_status

Arguments: none
Return Value: $result
my $result = $conn->broadcast_mediainfo_reader_status;

Request status for the mediainfo reader. It can be idle or working.

signal_mediainfo_reader_unindexed

Arguments: none
Return Value: $result
my $result = $conn->signal_mediainfo_reader_unindexed;

Request number of unindexed entries in medialib.

userconfdir_get

Arguments: none
Return Value: $path

Get the absolute path to the user config dir.

playback_tickle

Arguments: none
Return Value: $result
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.

playback_stop

Arguments: none
Return Value: $result
my $result = $conn->playback_stop;

Stops the current playback. This will make the server idle.

playback_pause

Arguments: none
Return Value: $result
my $result = $conn->playback_pause;

Pause the current playback, will tell the output to not read nor write.

playback_start

Arguments: none
Return Value: $result
my $result = $conn->playback_start;

Starts playback if server is idle.

playback_seek_ms

Arguments: $milliseconds
Return Value: $result
my $result = $conn->playback_seek_ms(1000);

Seek to a absolute time in the current playback. The time is specified in $milliseconds.

playback_seek_ms_rel

Arguments: $milliseconds
Return Value: $result
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 $milliseconds.

playback_seek_samples

Arguments: $samples
Return Value: $result
my $result = $conn->playback_seek_samples(5000);

Seek to a absoulte number of $samples in the current playback.

playback_seek_samples_rel

Arguments: $samples
Return Value: $result
my $result = $conn->playback_seek_samples_rel(-5000);

Seek to a number of $samples relative to the current position in the current playback.

broadcast_playback_status

Arguments: none
Return Value: $result
my $result = $conn->broadcast_playback_status;

Requests the playback status broadcast. This will be called when events like play, stop and pause is triggered.

playback_status

Arguments: none
Return Value: $result
my $result = $conn->playback_status;

Request the playback status.

broadcast_playback_current_id

Arguments: none
Return Value: $result
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.

playback_current_id

Arguments: none
Return Value: $result
my $result = $conn->playback_current_id;

Request the current playback id.

signal_playback_playtime

Arguments: none
Return Value: $result
my $result = $conn->signal_playback_playtime;

Request the playback_playtime signal. Will update the time we have played the current entry.

playback_playtime

Arguments: none
Return Value: $result
my $result = $conn->playback_playtime;

Request the current playtime.

playback_volume_set

Arguments: $channel, $volume
Return Value: $result
my $result = $conn->playback_volume_set('left', 75);

Set the $volume for a given $channel.

playback_volume_get

Arguments: none
Return Value: $result
my $result = $conn->playback_volume_get;

Get the current playback volume.

broadcast_playback_volume_changed

Arguments: none
Return Value: $result
my $result = $conn->broadcast_playback_volume_changed;

Request the playback_volume_changed broadcast. This will be called when the playback volume changed.

playlist_list

Arguments: none
Return Value: $result
my $result = $conn->playlist_list;

List the existing playlists.

broadcast_playlist_changed

Arguments: none
Return Value: $result
my $result = $conn->broadcast_playlist_changed;

Request the playlist changed broadcast from the server. Everytime someone manipulate the playlist this will be emitted.

broadcast_playlist_current_pos

Arguments: none
Return Value: $result
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.

broadcast_playlist_loaded

Arguments: none
Return Value: $result
my $result = $conn->broadcast_playlist_loaded;

Request the playlist_loaded broadcast. This will be called if a playlist is loaded server-side.

playlist_current_active

Arguments: none
Return Value: $result
my $result = $conn->playlist_current_active;

Retrive the name of the active playlist.

playlist_set_next

Arguments: $pos
Return Value: $result
my $result = $conn->playlist_set_next(7);

Set next entry in the playlist to the absolute position $pos.

playlist_set_next_rel

Arguments: $pos
Return Value: $result
my $result = $conn->playlist_set_next_rel(-1);

Same as "playlist_set_next" but relative to the current position.

coll_idlist_from_playlist_file

Arguments: $path
Return Value: $result
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.

io_want_out

Arguments: none
Return Value: 1 | 0
my $has_pending_output = $conn->io_want_out;

Check for pending output.

io_out_handle

Arguments: none
Return Value: $success
my $success = $conn->io_out_handle;

Write pending data. Should be called when the mainloop flags that writing is available on the socket.

io_in_handle

Arguments: none
Return Value: $success
my $success = $conn->io_in_handle;

Read available data. Should be called when the mainloop flags that reading is available on the socket.

io_fd_get

Arguments: none
Return Value: $fd | -1
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.

io_need_out_callback_set

Arguments: \&func, $data?
Return Value: none
$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.

AUTHOR

Florian Ragwitz <rafl@debian.org>

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Audio::XMMSClient

You can also look for information at:

SEE ALSO

Audio::XMMSClient::Result, Audio::XMMSClient::Playlist, Audio::XMMSClient::Collection

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.