XMMSCLIENT(1)

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).

  main_list_plugins

Arguments: $type?
Return Value: $result

  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:

•   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_move_entry

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

  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_import_path

Arguments: $path
Return Value: $result

  my $result = $conn->medialib_import_path('file:///media/music/');

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

  medialib_import_path_encoded

Arguments: $path
Return Value: $result

  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".

  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_updated

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_sync

Arguments: none
Return Value: $result

  my $result = $conn->coll_sync;

Synchronize collection data to the database.

  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.

  coll_query

Arguments: $collection, \@spec
Return Value: $result

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.

•   spec

    A collections fetch specification.

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.

  bindata_list

Arguments: none
Return Value: $result

  my $result = $conn->bindata_list;

List all bindata hashes stored on the server.

  config_register_value

Arguments: $key, $default_value
Return Value: $result

  my $result = $conn->config_register_value('myclient.stop_playback_on_quit', 0);

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

  config_set_value

Arguments: $key, $value
Return Value: $result

  my $result = $conn->config_set_value('myclient.stop_playback_on_quit', 1);

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

  config_get_value

Arguments: $key
Return Value: $result

  my $result = $conn->config_get_value('myclient.stop_playback_on_quit');

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

  config_list_values

Arguments: none
Return Value: $result

  my $result = $conn->config_list_values;

Lists all configuration values.

  broadcast_config_value_changed

Arguments: none
Return Value: $result

  my $result = $conn->broadcast_config_value_changed;

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

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

  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.

  playback_seek_samples

Arguments: $samples
Return Value: $result

  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.

  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.

  loop

Arguments: none
Return Value: none

  $conn->loop;

Starts a select-based mainloop which may be terminated by calling "/quit_loop".

  quit_loop

Arguments: none
Return Value: none

  $conn->quit_loop;

Terminates the mainloop started with "/loop".

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:

•   AnnoCPAN: Annotated CPAN documentation

    <http://annocpan.org/dist/Audio-XMMSClient>

•   CPAN Ratings

    <http://cpanratings.perl.org/d/Audio-XMMSClient>

•   RT: CPAN's request tracker

    <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Audio-XMMSClient>

•   Search CPAN

    <http://search.cpan.org/dist/Audio-XMMSClient>

SEE ALSO
Audio::XMMSClient::Result, Audio::XMMSClient::Playlist, Audio::XMMSClient::Collection

COPYRIGHT AND LICENSE
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.