xmmsclient

Functions

xmmsclient.userconfdir_get()

Get the user configuration directory, where XMMS2 stores its user-specific configuration files. Clients may store their configuration under the ‘clients’ subdirectory. This varies from platform to platform so should always be retrieved at runtime.

Classes

class xmmsclient.XmmsSync(clientname=None, xmms=None)

A wrapper for the xmmsclient.Xmms class which simplifies synchronous communication with the XMMS2 daemon.

Instances of this class may be used just like regular xmmsclient.Xmms objects, except that instead of returning an XmmsResult instance, the value associated with the result is returned. If the XmmsResult indicates an error, an XmmsError is raised instead of returning the value.

>>> import xmmsclient
>>> xc = xmmsclient.XmmsSync('clientname')
>>> xc.connect()
>>> xc.playback_start()
class xmmsclient.XmmsLoop

A simple main loop to drive async communication.

>>> import xmmsclient
>>> def handle_stats(result):
>>>   print(result.value())
>>> xc = xmmsclient.XmmsLoop('clientname')
>>> xc.connect()
>>> xc.stats(cb=handle_stats)
>>> xc.loop()
exit_loop(self)

Exits from the loop call

loop(self)

Main client loop for most python clients. Call this to run the client once everything has been set up. This function blocks until exit_loop is called. One can override loop_iter to perform extra processing.

loop_iter(self, infd=None, outfd=None, errfd=None, timeout=-1)

Run one iteration of the main loop. Should be overridden to add custom operations in the main loop.

Returns:The tuple returned by select.select to be used by overridding methods in subclasses.
loop_tickle(self)
class xmmsclient.Xmms(clientname=None)
This is the class representing the XMMS2 client itself. The methods in this class may be used to control and interact with XMMS2.
client_id
clientname
source_preference
bindata_add(self, data, cb=None)

Add a datafile to the server

Returns:The result of the operation.
Return type:XmmsResult
bindata_list(self, cb=None)

List all bindata hashes stored on the server

Returns:The result of the operation.
Return type:XmmsResult
bindata_remove(self, hash, cb=None)

Remove a datafile from the server

Returns:The result of the operation.
Return type:XmmsResult
bindata_retrieve(self, hash, cb=None)

Retrieve a datafile from the server

Returns:The result of the operation.
Return type:XmmsResult
broadcast_c2c_client_connected(self, cb=None)

Broadcast received whenever a new client connects to the server

Returns:The result of the operation.
Return type:XmmsResult
broadcast_c2c_client_disconnected(self, cb=None)

Broadcast received whenever a client disconnects from the server

Returns:The result of the operation.
Return type:XmmsResult
broadcast_c2c_ready(self, cb=None)

Broadcast reveiced whenever a client’s service api is ready

Returns:the result of the operation.
Return type:XmmsResult
broadcast_collection_changed(self, cb=None)

Set a method to handle the collection changed broadcast from the XMMS2 daemon.

Return type:XmmsResult
broadcast_config_value_changed(self, cb=None)

Set a method to handle the config value changed broadcast from the XMMS2 daemon.(i.e. some configuration value has been modified) Updated data is sent whenever a config value is modified.

Returns:The modified config key and its value.
Return type:XmmsResult
broadcast_mediainfo_reader_status(self, cb=None)

Tell daemon to send you the status of the mediainfo reader

Returns:The result of the operation.
Return type:XmmsResult
broadcast_medialib_entry_added(self, cb=None)

Set a method to handle the medialib entry added broadcast from the XMMS2 daemon. (i.e. a new entry has been added)

Return type:XmmsResult
broadcast_medialib_entry_changed(self, cb=None)
Deprecated:Use broadcast_medialib_entry_updated instead.
broadcast_medialib_entry_removed(self, cb=None)

Set a method to handle the medialib entry removed broadcast from the XMMS2 daemon. (i.e. an entry has been removed)

Return type:XmmsResult
broadcast_medialib_entry_updated(self, cb=None)

Set a method to handle the medialib entry updated broadcast from the XMMS2 daemon. Updated data is sent when the metadata for a song is updated in the medialib.

Return type:XmmsResult
broadcast_playback_current_id(self, cb=None)

Set a method to handle the playback id broadcast from the XMMS2 daemon.

Return type:XmmsResult
broadcast_playback_status(self, cb=None)

Set a method to handle the playback status broadcast from the XMMS2 daemon.

Return type:XmmsResult
broadcast_playback_volume_changed(self, cb=None)

Set a broadcast callback for volume updates

Return type:XmmsResult
broadcast_playlist_changed(self, cb=None)

Set a method to handle the playlist changed broadcast from the XMMS2 daemon. Updated data is sent whenever the daemon’s playlist changes.

Return type:XmmsResult
broadcast_playlist_current_pos(self, cb=None)

Set a method to handle the playlist current position updates from the XMMS2 daemon. This is triggered whenever the daemon jumps from one playlist position to another. (not when moving a playlist item from one position to another)

Return type:XmmsResult
broadcast_playlist_loaded(self, cb=None)

Set a broadcast callback for loaded playlist event

Return type:XmmsResult
c2c_get_connected_clients(self, cb=None)

Get a list of clients connected to the xmms2 server

Returns:The result of the operation.
Return type:XmmsResult
c2c_get_own_id(self)
Return type:int
c2c_get_ready_clients(self, cb=None)

Get a list of clients connected to the xmms2 server

Returns:The result of the operation.
Return type:XmmsResult
c2c_ready(self, cb=None)

Notify the server that client services are ready for query. This method is called XmmsServiceNamespace.register() and don’t need to be called explicitly.

Returns:The result of the operation.
Return type:XmmsResult
coll_get(self, name, ns='Collections', cb=None)

Retrieve a Collection

Returns:The result of the operation.
Return type:XmmsResult
coll_idlist_from_playlist_file(self, path, cb=None)

Create an idlist from a playlist.

Returns:The result of the operation.
Return type:XmmsResult
coll_list(self, ns='Collections', cb=None)

List collections

Returns:The result of the operation.
Return type:XmmsResult
coll_query(self, Collection coll, fetch, cb=None)

Retrive a list of ids of the media matching the collection

Returns:The result of the operation.
Return type:XmmsResult
coll_query_ids(self, Collection coll, start=0, leng=0, order=None, cb=None)

Retrive a list of ids of the media matching the collection

Returns:The result of the operation.
Return type:XmmsResult
coll_query_infos(self, Collection coll, fields, start=0, leng=0, order=None, groupby=None, cb=None)

Retrive a list of mediainfo of the media matching the collection

Returns:The result of the operation.
Return type:XmmsResult
coll_remove(self, name, ns='Collections', cb=None)

Remove a collection on server.

Returns:The result of the operation.
Return type:XmmsResult
coll_rename(self, oldname, newname, ns='Collections', cb=None)

Rename a collection.

Returns:The result of the operation.
Return type:XmmsResult
coll_save(self, Collection coll, name, ns='Collections', cb=None)

Save a collection on server.

Returns:The result of the operation.
Return type:XmmsResult
config_get_value(self, key, cb=None)

Get the configuration value of a given key, from the daemon.

Returns:The result of the operation.
Return type:XmmsResult
config_list_values(self, cb=None)

Get list of configuration keys on the daemon. Use config_get_value to retrieve the values corresponding to the configuration keys.

Returns:The result of the operation.
Return type:XmmsResult
config_register_value(self, valuename, defaultvalue, cb=None)

Register a new configvalue. This should be called in the initcode as XMMS2 won’t allow set/get on values that haven’t been registered.

Returns:The result of the operation.
Return type:XmmsResult
config_set_value(self, key, val, cb=None)

Set a configuration value on the daemon, given a key.

Returns:The result of the operation.
Return type:XmmsResult
connect(self, path=None, disconnect_func=None)

Connect to the appropriate IPC path, for communication with the XMMS2 daemon. This path defaults to /tmp/xmms-ipc-<username> if not specified. Call this once you have instantiated the object:

>>> import xmmsclient
>>> xc = xmmsclient.Xmms('clientname')
>>> xc.connect()

You can provide a disconnect callback function to be activated when the daemon disconnects.(e.g. daemon quit) This function typically has to exit the main loop used by your application. For example, if using loop, your callback should call exit_loop at some point.

disconnect(self)
get_fd(self)

Get the underlying file descriptor used for communication with the XMMS2 daemon. You can use this in a client to ensure that the IPC link is still active and safe to use.(e.g by calling select() or poll())

Returns:IPC file descriptor
Return type:int
get_source_preference(self)
ioin(self)

Read data from the daemon, when available. Note: This is a low level function that should only be used in certain circumstances. e.g. a custom event loop

ioout(self)

Write data out to the daemon, when available. Note: This is a low level function that should only be used in certain circumstances. e.g. a custom event loop

is_connected(self)
medialib_add_entry(self, path, cb=None, encoded=False)

Add an entry to the MediaLib.

Returns:The result of the operation.
Return type:XmmsResult
medialib_add_entry_encoded(self, path, cb=None)
Deprecated:Use medialib_add_entry instead.
medialib_get_id(self, url, cb=None, encoded=False)

Search for an entry (URL) in the medialib and return its ID number.

Returns:The result of the operation.
Return type:XmmsResult
medialib_get_info(self, int id, cb=None)
Returns:Information about the medialib entry position specified.
Return type:XmmsResult
medialib_import_path(self, path, cb=None, encoded=False)

Import metadata from all files recursively from the directory passed as argument.

Returns:The result of the operation.
Return type:XmmsResult
medialib_move_entry(self, int id, url, cb=None, encoded=False)

Set a new url for an entry in the medialib.

Returns:The result of the operation.
Return type:XmmsResult
medialib_path_import(self, path, cb=None, encoded=False)
Deprecated:Use medialib_import_path instead.
medialib_path_import_encoded(self, path, cb=None)
Deprecated:Use medialib_import_path instead.
medialib_property_remove(self, int id, key, source=None, cb=None)

Remove a value from a medialib entry. Source is optional.

Returns:The result of the operation.
Return type:XmmsResult
medialib_property_set(self, int id, key, value, source=None, cb=None)

Associate a value with a medialib entry. Source is optional.

Returns:The result of the operation.
Return type:XmmsResult
medialib_rehash(self, int id=0, cb=None)

Force the medialib to check that metadata stored is up to date.

Returns:The result of the operation.
Return type:XmmsResult
medialib_remove_entry(self, int id, cb=None)

Remove an entry from the medialib.

Returns:The result of the operation.
Return type:XmmsResult
playback_current_id(self, cb=None)
Returns:The medialib id of the item currently selected.
Return type:XmmsResult
playback_pause(self, cb=None)

Instruct the XMMS2 daemon to pause playback.

Returns:The result of the operation.
Return type:XmmsResult
playback_playtime(self, cb=None)

Return playtime on current file/stream. This is essentially a more direct version of signal_playback_playtime

Returns:The result of the operation (playtime in milliseconds).
Return type:XmmsResult
playback_seek_ms(self, int ms, xmms_playback_seek_mode_t whence=PLAYBACK_SEEK_SET, cb=None)

Seek to a time position in the current file or stream in playback.

Returns:The result of the operation.
Return type:XmmsResult
playback_seek_samples(self, int samples, xmms_playback_seek_mode_t whence=PLAYBACK_SEEK_SET, cb=None)

Seek to a number of samples in the current file or stream in playback.

Returns:The result of the operation.
Return type:XmmsResult
playback_start(self, cb=None)

Instruct the XMMS2 daemon to start playing the currently selected file from the playlist.

Returns:The result of the operation.
Return type:XmmsResult
playback_status(self, cb=None)

Get current playback status from XMMS2 daemon. This is essentially the more direct version of broadcast_playback_status. Possible return values are: PLAYBACK_STATUS_STOP, PLAYBACK_STATUS_PLAY, PLAYBACK_STATUS_PAUSE

Returns:Current playback status
Return type:XmmsResult
playback_stop(self, cb=None)

Instruct the XMMS2 daemon to stop playing the file currently being played.

Returns:The result of the operation.
Return type:XmmsResult
playback_tickle(self, cb=None)

Instruct the XMMS2 daemon to move on to the next playlist item.

Returns:The result of the operation.
Return type:XmmsResult
playback_volume_get(self, cb=None)

Get the playback for all channels

Return type:XmmsResult
playback_volume_set(self, channel, int volume, cb=None)

Set the playback volume for specified channel

Return type:XmmsResult
playlist_add_collection(self, Collection coll, order=None, playlist=None, cb=None)

Add the content of a collection to the playlist.

Returns:The result of the operation.
Return type:XmmsResult
playlist_add_encoded(self, url, playlist=None, cb=None)
Deprecated:Use playlist_add_url instead.
playlist_add_id(self, int id, playlist=None, cb=None)

Add a medialib id to the playlist.

Returns:The result of the operation.
Return type:XmmsResult
playlist_add_url(self, url, playlist=None, cb=None, encoded=False)

Add a path or URL to a playable media item to the playlist. Playable media items may be files or streams. Requires a string ‘url’ as argument.

Returns:The result of the operation.
Return type:XmmsResult
playlist_clear(self, playlist=None, cb=None)

Clear the playlist.

Returns:The result of the operation.
Return type:XmmsResult
playlist_create(self, playlist, cb=None)

Create a new playlist.

Returns:The result of the operation.
Return type:XmmsResult
playlist_current_active(self, cb=None)

Returns the name of the current active playlist

Return type:XmmsResult
playlist_current_pos(self, playlist=None, cb=None)

Returns the current position in the playlist. This value will always be equal to, or larger than 0. The first entry in the list is 0.

Return type:XmmsResult
playlist_insert_collection(self, int pos, Collection coll, order=None, playlist=None, cb=None)

Insert the content of a collection to the playlist. Requires an int ‘pos’ and an int ‘id’ as argument.

Returns:The result of the operation.
Return type:XmmsResult
playlist_insert_encoded(self, int pos, url, playlist=None, cb=None)
Deprecated:Use playlist_insert_url instead.
playlist_insert_id(self, int pos, int id, playlist=None, cb=None)

Insert a medialib to the playlist. Requires an int pos and an int id as argument.

Returns:The result of the operation.
Return type:XmmsResult
playlist_insert_url(self, int pos, url, playlist=None, cb=None, encoded=False)

Insert a path or URL to a playable media item to the playlist. Playable media items may be files or streams. Requires an int ‘pos’ and a string ‘url’ as argument.

Returns:The result of the operation.
Return type:XmmsResult
playlist_list(self, cb=None)

Lists the playlists

Returns:The result of the operation.
Return type:XmmsResult
playlist_list_entries(self, playlist=None, cb=None)

Get the current playlist. This function returns a list of IDs of the files/streams currently in the playlist. Use medialib_get_info to retrieve more specific information.

Returns:The current playlist.
Return type:XmmsResult
playlist_load(self, playlist, cb=None)

Load the playlist as current playlist

Returns:The result of the operation.
Return type:XmmsResult
playlist_move(self, int cur_pos, int new_pos, playlist=None, cb=None)

Moves a playlist entry to a new position.

Returns:The result of the operation.
Return type:XmmsResult
playlist_radd(self, url, playlist=None, cb=None, encoded=False)

Add a directory to the playlist. Requires a string ‘url’ as argument.

Returns:The result of the operation.
Return type:XmmsResult
playlist_radd_encoded(self, url, playlist=None, cb=None)
Deprecated:Use playlist_radd instead.
playlist_remove(self, playlist, cb=None)

Remove the playlist from the server

Returns:The result of the operation.
Return type:XmmsResult
playlist_remove_entry(self, int id, playlist=None, cb=None)

Remove a certain media item from the playlist. Requires a number ‘id’ as argument.

Returns:The result of the operation.
Return type:XmmsResult
playlist_rinsert(self, int pos, url, playlist=None, cb=None, encoded=False)

Insert a directory in the playlist. Requires an int ‘pos’ and a string ‘url’ as argument.

Returns:The result of the operation.
Return type:XmmsResult
playlist_rinsert_encoded(self, int pos, url, playlist=None, cb=None)
Deprecated:Use playlist_rinsert instead.
playlist_set_next(self, int position, cb=None)

Sets the position to move to, next, in the playlist. Calling playback_tickle will perform the jump to that position.

Return type:XmmsResult
playlist_set_next_rel(self, int position, cb=None)

Sets the position in the playlist. Same as playlist_set_next but sets the next position relative to the current position. You can do set_next_rel(-1) to move backwards for example.

Return type:XmmsResult
playlist_shuffle(self, playlist=None, cb=None)

Instruct the XMMS2 daemon to shuffle the playlist.

Returns:The result of the operation.
Return type:XmmsResult
playlist_sort(self, props, playlist=None, cb=None)

Sorts the playlist according to the properties specified.

Returns:The result of the operation.
Return type:XmmsResult
plugin_list(self, typ, cb=None)

Get a list of loaded plugins from the server

Returns:The result of the operation.
Return type:XmmsResult
quit(self, cb=None)

Tell the XMMS2 daemon to quit.

Returns:The result of the operation.
Return type:XmmsResult
sc_broadcast_emit(self, broadcast, value=None)

Emit a broadcast message to subscribed clients

Returns:whether notifications were successfully queued
Return type:bool
sc_broadcast_subscribe(self, int dest, broadcast, cb=None)

Subscribe to a broadcast from another client

Returns:The result of the operation.
Return type:XmmsResult
sc_call(self, int dest, method, args=(), kargs=<???>, cb=None)

Call a remote method

Returns:The result of the operation.
Return type:XmmsResult
sc_init(self)

Initialize client-to-client features. Client-to-client features won’t work with the synchronous client wrapper

Returns:whether client-to-client is initialized.
Return type:bool
sc_introspect_broadcast(self, int dest, path, cb=None)

Get informations about a broadcast on a remote client

Returns:The result of the operation.
Return type:XmmsResult
sc_introspect_constant(self, int dest, path, cb=None)

Get informations about a constant on a remote client

Returns:The result of the operation.
Return type:XmmsResult
sc_introspect_docstring(self, int dest, path, cb=None)

Get the docstring for a given path on a remote client

Returns:The result of the operation.
Return type:XmmsResult
sc_introspect_method(self, int dest, path, cb=None)

Get informations about a method on a remote client

Returns:The result of the operation.
Return type:XmmsResult
sc_introspect_namespace(self, int dest, path=(), cb=None)

Get informations about a namespace on a remote client

Returns:The result of the operation.
Return type:XmmsResult
set_need_out_fun(self, fun)

Set a function to be called when there’s data to be sent to the server.

set_source_preference(self, sources)
signal_mediainfo_reader_unindexed(self, cb=None)

Tell daemon to send you the number of unindexed files in the mlib

Returns:The result of the operation.
Return type:XmmsResult
signal_playback_playtime(self, cb=None)

Set a method to handle the playback playtime signal from the XMMS2 daemon.

Return type:XmmsResult
stats(self, cb=None)

Get statistics information from the server

Returns:The result of the operation.
Return type:XmmsResult
visualization_chunk_get(self, int handle, int drawtime=0, bool blocking=False)

Fetches the next available data chunk

Returns:Visualization chunk.
Return type:XmmsVisChunk
visualization_errored(self, int handle)

Whether the visualization got an error.

Returns:True if the visualization got an error, False otherwise.
Return type:bool
visualization_init(self, cb=None)

Get a new visualization handle.

Returns:The result of the operation
Return type:XmmsResult
visualization_properties_set(self, int handle, props={}, cb=None)

Set visualization’s properties.

Returns:The result of the operation
Return type:XmmsResult
visualization_property_set(self, int handle, key, value, cb=None)

Set a visualization’s property.

Returns:The result of the operation
Return type:XmmsResult
visualization_shutdown(self, int handle)

Shutdown and destroy a visualization. After this, handle is no longer valid.

visualization_start(self, int handle, cb=None)

Starts the visualization.

Returns:The result of the operation
Return type:XmmsResult
visualization_started(self, int handle)

Whether the visualization is started or not.

Returns:True if the visualization is started, False otherwise.
Return type:bool
visualization_version(self, cb=None)

Get the version of the visualization plugin installed on the server.

Returns:The result of the operation.
Return type:XmmsResult
want_ioout(self)

Check if there’s data to send to the server.

xform_media_browse(self, url, cb=None, encoded=False)

Browse files from xform plugins.

Returns:The result of the operation.
Return type:XmmsResult
xform_media_browse_encoded(self, url, cb=None)
Deprecated:Use xform_media_browse instead.
class xmmsclient.XmmsValue(sourcepref=None, pyval=None)
copy(self, cls=None)
get_bin(self)

Get data from the result structure as binary data.

Returns:The binary data as bytes.
Return type:bytes
get_coll(self)

Get data from the result structure as a Collection.

Return type:Collection
get_dict(self)
Returns:A dictionary containing media info.
get_dict_iter(self)
Returns:An iterator on dict items ((key, value) pairs).
get_error(self)
Returns:Error string from the result.
Return type:String
get_float(self)

Get data from the result structure as an float.

Returns:A float from the result.
Return type:float
get_int(self)

Get data from the result structure as an int.

Returns:An integer from the result.
Return type:int
get_list(self)
Returns:A list of dicts from the result structure.
get_list_iter(self)
Returns:An iterator on a list.
get_propdict(self)
Returns:A source dict.
get_string(self)

Get data from the result structure as a string.

Returns:A string from the result.
Return type:string
get_type(self)

Return the type of the value.

Returns:The return value is one of the VALUE_TYPE_* constants.
is_error(self)
Returns:Whether the value represents an error or not.
Return type:Boolean
iserror(self)
Deprecated:Use XmmsValue.is_error instead.
Returns:Whether the value represents an error or not.
Return type:bool
set_pyval(self, pyval)
value(self)

This can be used instead of most get_* functions in this class.

Returns:Return value of appropriate data type contained in this result.
class xmmsclient.XmmsValueC2C
destination
id
payload
sender
class xmmsclient.XmmsLoop

A simple main loop to drive async communication.

>>> import xmmsclient
>>> def handle_stats(result):
>>>   print(result.value())
>>> xc = xmmsclient.XmmsLoop('clientname')
>>> xc.connect()
>>> xc.stats(cb=handle_stats)
>>> xc.loop()
exit_loop(self)

Exits from the loop call

loop(self)

Main client loop for most python clients. Call this to run the client once everything has been set up. This function blocks until exit_loop is called. One can override loop_iter to perform extra processing.

loop_iter(self, infd=None, outfd=None, errfd=None, timeout=-1)

Run one iteration of the main loop. Should be overridden to add custom operations in the main loop.

Returns:The tuple returned by select.select to be used by overridding methods in subclasses.
loop_tickle(self)
class xmmsclient.xmmsapi.XmmsResult

Class containing the results of some operation

callback
disconnect(self)
is_error(self)
Returns:Whether the result represents an error or not.
Return type:bool
iserror(self)
Deprecated:Use XmmsResult.is_error instead.
value(self)
wait(self)

Wait for the result from the daemon.

xmmsvalue(self)
xvalue
class xmmsclient.xmmsapi.XmmsVisChunk
get_buffer(self)

Get the chunk buffer

Returns:chunk data as a string
get_data(self)

Get chunk data as a list.

Returns:A list of int

Exceptions

exception xmmsclient.xmmsvalue.XmmsError
exception xmmsclient.xmmsapi.VisualizationError
exception xmmsclient.xmmsapi.XmmsDisconnectException