Overview
--------

This is PyXMMS, a Python interface to XMMS (the X MultiMedia System), an audio
and video player for Unix-like platforms.

As of version 2.00, PyXMMS consists of two components:
    - a set of Python bindings for all the xmms_remote_* functions accessible
      through the libxmms library (which comes with XMMS), plus a few
      higher-level functions that I (Florent Rougon) find useful;
    - a Python wrapper around the functions for configuration file management
      in libxmms.

In short, the first component allows you to control XMMS from a Python program
while the second component is for Python programs that need to manage the XMMS
main configuration file (reading or writing).

These two components are accessible by means of the xmms.control and
xmms.config modules respectively.


License
-------

PyXMMS is free software, licensed under the GNU GPL.


Documentation
-------------

PyXMMS is fully documented through Python docstrings.

The easiest way to browse the PyXMMS documentation is to go through the
following steps (as a normal user, from the PyXMMS base directory):
  - build PyXMMS:

        python ./setup.py build

    If this step fails (perhaps you are missing required libraries, or your
    Python version is not supported), read the INSTALL file.

  - build the documentation (this uses the pydoc module):

        python ./build-documentation.py

Then, you'll have all the documentation for the Python version used in these
steps in the "doc" directory (see Compatibility below).


Otherwise, you can browse the documentation in an interactive Python session
if you have already installed PyXMMS (see the INSTALL file) or if you have
built PyXMMS and are in the appropriate directory for your platform and Python
version (for instance, build/lib.linux-i686-2.3). Then, if you are interested
in "item" (a function or class name, or the module name) from the "module"
module (xmms.control or xmms.config, for instance), you can type at a Python
command prompt:

    import module; help(item)


If PyXMMS is installed, you can also read the documentation with a Web browser
if you use pydoc as an HTTP server. For instance:

    pydoc -p 1234                   (does not need root privileges if
                                     the chosen port is greater than 1024)

will start an HTTP server listening on the 1234 port and serving the
documentation for your whole Python installation. Then, you just have to point
your browser to http://localhost:1234/

See the pydoc module's documentation for more information.


Compatibility
-------------

This version of PyXMMS should work with Python 2.3 and later versions.


Upgrading from PyXMMS 1 to PyXMMS 2
-----------------------------------

A few changes have been made to the control component between PyXMMS 1.07 and
PyXMMS 2.00, so you should read the following paragraphs so that you use the
new API for new code and update old code to conform to it. However, *all
changes are backward-compatible for now* (except the cosmetic issue with
exception messages---see below).

Also, talking about a "new API" is a bit of an overstatement. Here are the
changes:
  - Due to the addition of the 'config' component, xmms was made into a
    package, containing two main modules, xmms.control and xmms.config.
    Therefore all the stuff that was under the xmms module in PyXMMS 1 (e.g.,
    xmms.play) is now under xmms.control (e.g., xmms.control.play). You will
    still find these things under xmms to preserve compatibility, but should
    not rely on this in the long term. Don't forget to import xmms.control!
  - For consistency with other Python modules, xmms.PyXMMSGenericException has
    been replaced by xmms.error, after a looooooooong transition period.
  - The complete_message method of PyXMMS exceptions (subclasses of 'error')
    does not add a full stop at the end of the message embedded in an
    exception instance any more, so that your program can decide whether it
    wants the full stop or not. This is the only backward-incompatible change
    between PyXMMS 1.07 and PyXMMS 2.00.


Home page
---------

PyXMMS' home page is currently (2007-02-07) at:

  http://people.via.ecp.fr/~flo/