python/README.md

   1 Python aubio module
   2 ===================
   3
   4 This module wraps the aubio library for Python using the numpy module.
   5
   6 Using the Python aubio module
   7 -----------------------------
   8
   9 After installing python-aubio, you will be able to import the aubio module:
  10
  11     $ python
  12     [...]
  13     >>> import aubio
  14     >>> help(aubio.miditofreq)
  15
  16 Finding some inspiration
  17 ------------------------
  18
  19 Some examples are available in the `python/demos` directory. These scripts are
  20 small programs written in python and using python-aubio.
  21
  22 For instance, `demo_source.py` reads a media file.
  23
  24     $ ./python/demos/demo_source.py /path/to/sound/sample.wav
  25
  26 and `demo_timestretch_online.py` stretches the original file into a new one:
  27
  28     $ ./python/demo/demo_timestretch_online.py loop.wav stretched_loop.wav 0.92`
  29
  30 Note: you might need to install additional modules to run some of the demos.
  31 Some demos use [matplotlib](http://matplotlib.org/) to draw plots, others use
  32 [PySoundCard](https://github.com/bastibe/PySoundCard) to play and record
  33 sounds.
  34
  35 Testing the Python module
  36 -------------------------
  37
  38 Python tests are in `python/tests` and use the [nose2 python package][nose2].
  39
  40 To run the all the python tests, use the script:
  41
  42     $ ./python/tests/run_all_tests
  43
  44 Each test script can also be called one at a time. For instance:
  45
  46     $ ./python/tests/test_note2midi.py -v
  47
  48 [nose2]: https://github.com/nose-devs/nose2
  49
  50 Install in a virtualenv
  51 -----------------------
  52
  53 You should be able to install python-aubio directly from the top source
  54 directory of aubio.
  55
  56 First, create a virtualenv to hold the required python module:
  57
  58     $ virtualenv pyaubio
  59     $ source pyaubio/bin/activate
  60
  61 Now install and build the python extension using:
  62
  63     $ pip install .
  64
  65 Install requirements
  66 --------------------
  67
  68 Before compiling this module, you must have compiled libaubio.
  69
  70 A simple way to do this is with pip:
  71
  72     $ pip install -r requirements.txt
  73
  74 For more information about how this module works, please refer to the [Python/C
  75 API Reference Manual] (http://docs.python.org/c-api/index.html) and the
  76 [Numpy/C API Reference](http://docs.scipy.org/doc/numpy/reference/c-api.html).
  77
  78 Compiling python aubio
  79 ----------------------
  80
  81 To build the aubio Python module, run the following command from the top source
  82 directory of aubio:
  83
  84     $ ./setup.py build
  85
  86 Note: if libaubio was previously built using waf, the script will use it.
  87 Otherwise, the entire library will be built inside the python extension.
  88
  89 To find out more about `setup.py` options:
  90
  91     $ ./setup.py --help
  92
  93 Installing
  94 ----------
  95
  96 To install the Python module:
  97
  98     $ ./setup.py install
  99
 100 Alternatively, you may want to use the Python module without installing it by
 101 setting your PYTHONPATH, for instance as follows:
 102
 103     $ export PYTHONPATH=$PYTHONPATH:$PWD/`ls -rtd build/lib.* | head -1`:$PWD/tests
 104