Merge branch 'master' into feature/quietmode
[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 Links
19 -----
20
21 - [module documentation][doc_python]
22 - [installation instructions][doc_python_install]
23 - [aubio manual][manual]
24 - [aubio homepage][homepage]
25 - [issue tracker][bugtracker]
26
27 Demos
28 -----
29
30 Some examples are available in the [`python/demos` folder][demos_dir]. Each
31 script is a command line program which accepts one ore more argument.
32
33 **Notes**: installing additional modules is required to run some of the demos.
34
35 ### Analysis
36
37 - `demo_source.py` uses aubio to read audio samples from media files
38 - `demo_onset_plot.py` detects attacks in a sound file and plots the results
39   using [matplotlib]
40 - `demo_pitch.py` looks for fundamental frequency in a sound file and plots the
41   results using [matplotlib]
42 - `demo_spectrogram.py`, `demo_specdesc.py`, `demo_mfcc.py` for spectral
43   analysis.
44
45 ### Real-time
46
47 - `demo_pyaudio.py` and `demo_tapthebeat.py` use [pyaudio]
48 - `demo_pysoundcard_play.py`, `demo_pysoundcard.py` use [PySoundCard]
49 - `demo_alsa.py` uses [pyalsaaudio]
50
51 ### Others
52
53 - `demo_timestretch.py` can change the duration of an input file and write the
54   new sound to disk,
55 - `demo_wav2midi.py` detects the notes in a file and uses [mido] to write the
56   results into a MIDI file
57
58 ### Example
59
60 Use `demo_timestretch_online.py` to slow down `loop.wav`, write the results in
61 `stretched_loop.wav`:
62
63     $ python demo_timestretch_online.py loop.wav stretched_loop.wav 0.92
64
65 Built with
66 ----------
67
68 The core of aubio is written in C for portability and speed. In addition to
69 [NumPy], aubio can be optionally built to use one or more of the following
70 libraries:
71
72 - media file reading:
73
74     - [ffmpeg] / [avcodec] to decode and read audio from almost any format,
75     - [libsndfile] to read audio from uncompressed sound files,
76     - [libsamplerate] to re-sample audio signals,
77     - [CoreAudio] to read all media formats supported by macOS, iOS, and tvOS.
78
79 - hardware acceleration:
80
81     - [Atlas] and [Blas], for accelerated vector and matrix computations,
82     - [fftw3], to compute fast Fourier Transforms of any size,
83     - [Accelerate] for accelerated FFT and matrix computations (macOS/iOS),
84     - [Intel IPP], accelerated vector computation and FFT implementation.
85
86 [ffmpeg]: https://ffmpeg.org
87 [avcodec]: https://libav.org
88 [libsndfile]: http://www.mega-nerd.com/libsndfile/
89 [libsamplerate]: http://www.mega-nerd.com/SRC/
90 [CoreAudio]: https://developer.apple.com/reference/coreaudio
91 [Atlas]: http://math-atlas.sourceforge.net/
92 [Blas]: https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms
93 [fftw3]: http://fftw.org
94 [Accelerate]: https://developer.apple.com/reference/accelerate
95 [Intel IPP]: https://software.intel.com/en-us/intel-ipp
96
97 [demos_dir]:https://github.com/aubio/aubio/tree/master/python/demos
98 [pyaudio]:https://people.csail.mit.edu/hubert/pyaudio/
99 [PySoundCard]:https://github.com/bastibe/PySoundCard
100 [pyalsaaudio]:https://larsimmisch.github.io/pyalsaaudio/
101 [mido]:https://mido.readthedocs.io
102
103 [manual]: https://aubio.org/manual/latest/
104 [doc_python]: https://aubio.org/manual/latest/python.html
105 [doc_python_install]: https://aubio.org/manual/latest/python_module.html
106 [homepage]: https://aubio.org
107 [NumPy]: https://www.numpy.org
108 [bugtracker]: https://github.com/aubio/aubio/issues
109 [matplotlib]:https://matplotlib.org/