ref: 4eb48e69f34d56f4a72e454c5927a6fe8781bb66
dir: /doc/develop.rst/
.. _develop:
Developing with aubio
=====================
Here is a brief overview of the C library.
For a more detailed list of available functions, see the `API documentation
<https://aubio.org/doc/latest/>`_.
To report issues, ask questions, and request new features, use `Github Issues
<https://github.com/aubio/aubio/issues>`_
Design Basics
-------------
The library is written in C and is optimised for speed and portability.
All memory allocations take place in the `new_` methods. Each successful call
to `new_` should have a matching call to `del_` to deallocate the object.
.. code-block:: C
// new_ to create an object foobar
aubio_foobar_t * new_aubio_foobar(void * args);
// del_ to delete foobar
void del_aubio_foobar (aubio_foobar_t * foobar);
The main computations are done in the `_do` methods.
.. code-block:: C
// _do to process output = foobar(input)
audio_foobar_do (aubio_foobar_t * foobar, fvec_t * input, cvec_t * output);
Most parameters can be read and written at any time:
.. code-block:: C
// _get_param to get foobar.param
smpl_t aubio_foobar_get_a_parameter (aubio_foobar_t * foobar);
// _set_param to set foobar.param
uint_t aubio_foobar_set_a_parameter (aubio_foobar_t * foobar, smpl_t a_parameter);
In some case, more functions are available:
.. code-block:: C
// non-real time functions
uint_t aubio_foobar_reset(aubio_foobar_t * t);
Basic Types
-----------
.. code-block:: C
// integers
uint_t n = 10; // unsigned
sint_t delay = -90; // signed
// float
smpl_t a = -90.; // simple precision
lsmp_t f = 0.024; // double precision
// vector of floats (simple precision)
fvec_t * vec = new_fvec(n);
vec->data[0] = 1;
vec->data[vec->length-1] = 1.; // vec->data has n elements
fvec_print(vec);
del_fvec(vec);
// complex data
cvec_t * fftgrain = new_cvec(n);
vec->norm[0] = 1.; // vec->norm has n/2+1 elements
vec->phas[n/2] = 3.1415; // vec->phas as well
del_cvec(fftgrain);
// matrix
fmat_t * mat = new_fmat (height, length);
mat->data[height-1][0] = 1; // mat->data has height rows
mat->data[0][length-1] = 10; // mat->data[0] has length columns
del_fmat(mat);
Reading a sound file
--------------------
In this example, `aubio_source <https://aubio.org/doc/latest/source_8h.html>`_
is used to read a media file.
First, define a few variables and allocate some memory.
.. literalinclude:: ../tests/src/io/test-source.c
:language: C
:lines: 22-24, 30-32, 34
.. note::
With ``samplerate = 0``, ``aubio_source`` will be created with the file's
original samplerate.
Now for the processing loop:
.. literalinclude:: ../tests/src/io/test-source.c
:language: C
:lines: 40-44
At the end of the processing loop, memory is deallocated:
.. literalinclude:: ../tests/src/io/test-source.c
:language: C
:lines: 55-56
See the complete example: :download:`test-source.c
<../tests/src/io/test-source.c>`.
Computing a spectrum
--------------------
Now let's create a phase vocoder:
.. literalinclude:: ../tests/src/spectral/test-phasevoc.c
:language: C
:lines: 6-11
The processing loop could now look like:
.. literalinclude:: ../tests/src/spectral/test-phasevoc.c
:language: C
:lines: 20-37
Time to clean up the previously allocated memory:
.. literalinclude:: ../tests/src/spectral/test-phasevoc.c
:language: C
:lines: 39-44
See the complete example: :download:`test-phasevoc.c
<../tests/src/spectral/test-phasevoc.c>`.
.. _doxygen-documentation:
Doxygen documentation
---------------------
The latest version of the API documentation is built using `Doxygen
<http://www.doxygen.org/>`_ and is available at:
https://aubio.org/doc/latest/
Contribute
----------
Please report any issue and feature request at the `Github issue tracker
<https://github.com/aubio/aubio/issues>`_. Patches and pull-requests welcome!