-# Here you will find some examples of python scripts and some evaluation
-# routines. The python interface for libaubio is generated using Swig.
-
-# To have it working before installation, you will need to set LD_LIBRARY_PATH.
-# for instance, to run the python script from within aubio/python/, you can use
-# '. README'
-
-export LD_LIBRARY_PATH=../src/.libs:../ext/.libs
-export PYTHONPATH=aubio/.libs
-
-echo """
-
-the aubio/ directory should be organised as follow:
-
- aubiowrapper.py,_aubiowrapper.so, aubio_wrap.c, aubio_wrap.o
- swig generated aubio interface
- aubioclass.py
- human usable interface
- plot/
- everything required to plot
- web/
- tools to use aubioweb.py
- bench/
- tools to explore a database of sound file and run benchmarks on it
- eval/
- tools to evaluate the performance of aubio extractors
- aubioweb.py
- a hack to pipe aubio in mod_python
-
-"""
+Python aubio module
+===================
+
+This module wraps the aubio library for Python using the numpy module.
+
+Before compiling this module, you must have compiled libaubio.
+
+For more information about how this module works, please refer to the [Python/C
+API Reference Manual] (http://docs.python.org/c-api/index.html) and the
+[Numpy/C API Reference](http://docs.scipy.org/doc/numpy/reference/c-api.html).
+
+Compiling python aubio
+----------------------
+
+After libaubio has been build successfully, and provided Python development
+headers and numpy can be found on your system, you should be able to build the
+aubio Python module:
+
+ $ ./setup.py build
+
+To find out more about `setup.py` options:
+
+ $ ./setup.py --help
+
+Installing
+----------
+
+To install the Python module:
+
+ $ ./setup.py install
+
+Using the Python module
+-----------------------
+
+Once the aubio library and the Python module are installed, you will be able to
+import the aubio module:
+
+ $ python
+ [...]
+ >>> import aubio
+ >>>
+
+Alternatively, you may want to use the Python module without installing it by
+setting PYTHONPATH:
+
+ $ export PYTHONPATH=$PYTHONPATH:$PWD/`ls -rtd build/lib.* | head -1`:$PWD/tests
+
+Testing the Python module
+-------------------------
+
+Once both the C library and the Python module have been built correctly, and
+after you have installed them (or setting the environment variable correctly),
+you should be able to run the tests:
+
+ $ ./tests/run_all_tests
+
+And to try out the demos:
+
+ $ ./demos/demo_source.py /path/to/sound/sample.wav
+
+You need to install additional modules to run some of the demos. For
+instance, several demos use [matplotlib](http://matplotlib.org/) to draw plots.
+Some more demos use [PySoundCard](https://github.com/bastibe/PySoundCard) to
+play and record sounds.