source: doc/develop.rst

Last change on this file was a10cd45, checked in by Paul Brossier <piem@piem.org>, 16 months ago

doc/develop.rst: fix title markup

  • Property mode set to 100644
File size: 3.9 KB

Developing with aubio

Here is a brief overview of the C library.

For a more detailed list of available functions, see the API documentation.

To report issues, ask questions, and request new features, use Github 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.

// 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.

// _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:

// _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:

// non-real time functions
uint_t aubio_foobar_reset(aubio_foobar_t * t);

Basic Types

// 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 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

The latest version of the API documentation is built using Doxygen and is available at:

https://aubio.org/doc/latest/

Contribute

Please report any issue and feature request at the Github issue tracker. Patches and pull-requests welcome!

Note: See TracBrowser for help on using the repository browser.