The Python amaroK bindings
*********************************************************

This is a fairly complete amaroK remote control class, extremely useful for amaroK scripts and other applications.  Basically, you can remote control amaroK by calling methods from an amaroKProxy instance.  In addition, it implements the Observer/Observable pattern so you can deal with events in an object-oriented, loosely coupled fashion.  Even better, you can call an amaroKProxy instance's collection.getSong(filename) method to get a Song object, with track, artist, album name, and elegant "Artist - Track name" strings.

Nearly all DCOP functions for communication with amaroK are implemented.

It will use KDE bindings' DCOP module if available, otherwise it will default to the command-line DCOP dcop command, through python-commandsplus.  If using KDE bindings, a slave process is spawned, and IPC is used to marshal and unmarshal function calls, so as to not contaminate your application's sys.modules with KDE's Python modules.  This all happens automatically in the background.

To use it, you import the module in your script and instantiate an amaroKProxy instance, then call your instance's startMonitoring() method, which will start reading from standard input, monitoring for amaroK's events.  You can then sleep(1) until your instance's .isAlive() method returns False (which means amaroK is now gone.

amaroKProxy is an Observable class, and so are its members:
	- player
	- contextBrowser
This means that you can implement Observer objects or Threads in your amaroK script, and have them be notified of amaroK events, instead of having to read standard input and act accordingly (plus error-prone exceptional condition handling).


PREREQUISITES

This software requires:
- Python 2.2 or later
- The Python commandsplus module
- The Python Observable module


INSTALLATION

To install, use:

   python setup.py install # to build and install directly
   python setup.py bdist_rpm # to prepare an RPM


HELP

The module is NOT heavily documented.  Rely on kdcop and browsing the sources for your research.


FEEDBACK: REPORTING BUGS, PATCHES, ETC.

dragonfear@gmail.com for the moment


LICENSE AND LEGAL NOTICE

This software is under the GPL.  See the file COPYING for licensing
information.  Contact me if you need us to license this software under
a different license.


AUTHORS

Manuel Amador (Rudd-O) <dragonfear@gmail.com>
