[doc] rewrite python/README.md demo section
[aubio.git] / python / README.md
1 aubio
2 =====
3
4 aubio is a collection of tools for music and audio analysis.
5
6 This package integrates the aubio library with [NumPy] to provide a set of
7 efficient tools to process and analyse audio signals, including:
8
9 - read audio from any media file, including videos and remote streams
10 - high quality phase vocoder, spectral filterbanks, and linear filters
11 - Mel-Frequency Cepstrum Coefficients and standard spectral descriptors
12 - detection of note attacks (onset)
13 - pitch tracking (fundamental frequency estimation)
14 - beat detection and tempo tracking
15
16 aubio works with both Python 2 and Python 3.
17
18 Built with
19 ----------
20
21 The core of aubio is written in C for portability and speed. In addition to
22 [NumPy], aubio can be optionally built to use one or more of the following
23 libraries:
24
25 - media file reading:
26
27     - [ffmpeg](https://ffmpeg.org) / [avcodec](https://libav.org) to decode and
28       read audio from almost any format,
29     - [libsndfile](http://www.mega-nerd.com/libsndfile/) to read audio from
30       uncompressed sound files,
31     - [libsamplerate](http://www.mega-nerd.com/SRC/) to re-sample audio signals
32     - [CoreAudio](https://developer.apple.com/reference/coreaudio) to read all
33       media files supported natively on macOS, iOS, and tvOS.
34
35 - hardware acceleration:
36
37     - [Atlas](http://math-atlas.sourceforge.net/) and
38       [Blas](https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms),
39       for accelerated vector and matrix computations,
40     - [fftw3](http://fftw.org), to compute fast Fourier Transforms of any size.
41     - [Accelerate](https://developer.apple.com/reference/accelerate) for
42       hardware accelerated FFT and matrix computations on macOs and iOS,
43     - [Intel IPP](https://software.intel.com/en-us/intel-ipp), accelerated
44       vector computation and FFT implementation,
45
46 Documentation
47 -------------
48
49 - [module documentation][doc_python]
50 - [installation][doc_python_install]
51 - [aubio manual][manual]
52 - [aubio homepage][homepage]
53
54 [manual]: https://aubio.org/manual/latest/
55 [doc_python]: https://aubio.org/manual/latest/python.html
56 [doc_python_install]: https://aubio.org/manual/latest/python_module.html
57 [homepage]: https://aubio.org
58 [NumPy]: https://www.numpy.org
59
60 Demos scripts
61 -------------
62
63 Some examples are available in the [`python/demos`][demos_dir] folder. These
64 scripts are small programs written in python and using python-aubio.
65
66 **Notes**: installing additional modules is required to run some of the demos.
67
68 ### Analysis
69
70 - `demo_source.py` uses aubio to read audio samples from media files
71 - `demo_onset_plot.py` detects attacks in a sound file and plots the results
72   using [matplotlib]
73 - `demo_pitch.py` looks for fundamental frequency in a sound file and plots the
74   results using [matplotlib]
75 - `demo_spectrogram.py`, `demo_specdesc.py`, `demo_mfcc.py` for spectral
76   analysis.
77
78 ### Real-time
79
80 - `demo_pyaudio.py` and `demo_tapthebeat.py` use [pyaudio]
81 - `demo_pysoundcard_play.py`, `demo_pysoundcard.py` use [PySoundCard]
82 - `demo_alsa.py` uses [pyalsaaudio]
83
84 ### Others
85
86 - `demo_timestretch.py` can change the duration of an input file and write the
87   new sound to disk,
88 - `demo_wav2midi.py` detects the notes in a file and uses [mido] to write the
89   results into a MIDI file
90
91 ### Example
92
93 Use `demo_timestretch_online.py` to slow down `loop.wav`, write the results in
94 `stretched_loop.wav`:
95
96     $ python demo_timestretch_online.py loop.wav stretched_loop.wav 0.92
97
98 [demos_dir]:https://github.com/aubio/aubio/tree/master/python/demos
99 [pyaudio]:https://people.csail.mit.edu/hubert/pyaudio/
100 [PySoundCard]:https://github.com/bastibe/PySoundCard
101 [pyalsaaudio]:https://larsimmisch.github.io/pyalsaaudio/
102 [mido]:https://mido.readthedocs.io
103 [matplotlib]:https://matplotlib.org/