Developing with aubio — aubio 0.4.7 documentation

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

      uint_t samplerate = 0;
      uint_t hop_size = 256;
      uint_t n_frames = 0, read = 0;

      aubio_source_t* s =
        new_aubio_source(source_path, samplerate, hop_size);
      fvec_t *vec = new_fvec(hop_size);

Note

With `samplerate = 0`, `aubio_source` will be created with the file’s original samplerate.

Now for the processing loop:

      do {
        aubio_source_do(s, vec, &read);
        fvec_print (vec);
        n_frames += read;
      } while ( read == hop_size );

At the end of the processing loop, memory is deallocated:

      del_fvec (vec);
      del_aubio_source (s);

See the complete example: `test-source.c`.

## Computing a spectrum

Now let’s create a phase vocoder:

      uint_t win_s = 32; // window size
      uint_t hop_s = win_s / 4; // hop size

      fvec_t * in = new_fvec (hop_s); // input buffer
      cvec_t * fftgrain = new_cvec (win_s); // fft norm and phase
      fvec_t * out = new_fvec (hop_s); // output buffer

The processing loop could now look like:

      while ( n-- ) {
        // get some fresh input data
        // ..

        // execute phase vocoder
        aubio_pvoc_do (pv,in,fftgrain);

        // do something with fftgrain
        // ...
        cvec_print (fftgrain);

        // optionally rebuild the signal
        aubio_pvoc_rdo(pv,fftgrain,out);

        // and do something with the result
        // ...
        fvec_print (out);
      }

Time to clean up the previously allocated memory:

      // clean up
      del_fvec(in);
      del_cvec(fftgrain);
      del_fvec(out);
      del_aubio_pvoc(pv);
      aubio_cleanup();

See the complete example: `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!