doc/python_module.rst: add note about aubio command
[aubio.git] / doc / python_module.rst
1 .. _python:
2
3 Python module
4 =============
5
6 The aubio extension for Python is available for Python 2.7 and Python 3.
7
8 Installing aubio with pip
9 -------------------------
10
11 aubio can now be installed using ``pip``:
12
13 .. code-block:: bash
14
15     $ pip install aubio
16
17 Building the module
18 -------------------
19
20 From ``aubio`` source directory, run the following:
21
22 .. code-block:: bash
23
24     $ ./setup.py clean
25     $ ./setup.py build
26     $ sudo ./setup.py install
27
28 Using aubio in python
29 ---------------------
30
31 Once the python module is installed, its version can be checked with:
32
33 .. code-block:: console
34
35     $ python -c "import aubio; print(aubio.version, aubio.float_type)"
36
37 The command line `aubio` is also installed:
38
39 .. code-block:: console
40
41     $ aubio -h
42
43 A simple example
44 ................
45
46 Here is a :download:`simple script <../python/demos/demo_source_simple.py>`
47 that reads all the samples from a media file:
48
49 .. literalinclude:: ../python/demos/demo_source_simple.py
50    :language: python
51
52 Filtering an input sound file
53 .............................
54
55 Here is a more complete example, :download:`demo_filter.py
56 <../python/demos/demo_filter.py>`. This files executes the following:
57
58 * read an input media file (``aubio.source``)
59
60 * filter it using an `A-weighting <https://en.wikipedia.org/wiki/A-weighting>`_
61   filter (``aubio.digital_filter``)
62
63 * write result to a new file (``aubio.sink``)
64
65 .. literalinclude:: ../python/demos/demo_filter.py
66    :language: python
67
68 More demos
69 ..........
70
71 Check out the `python demos folder`_ for more examples.
72
73 Python tests
74 ------------
75
76 A number of `python tests`_ are provided. To run them, use
77 ``python/tests/run_all_tests``.
78
79 .. _python demos folder: https://github.com/aubio/aubio/blob/master/python/demos
80 .. _demo_filter.py: https://github.com/aubio/aubio/blob/master/python/demos/demo_filter.py
81 .. _python tests: https://github.com/aubio/aubio/blob/master/python/tests
82