doc/develop.rst

   1 .. _develop:
   2
   3 Developing with aubio
   4 =====================
   5
   6 Here is a brief overview of the C library.
   7
   8 For a more detailed list of available functions, see the `API documentation
   9 <https://aubio.org/doc/latest/>`_.
  10
  11 To report issues, ask questions, and request new features, use `Github Issues
  12 <https://github.com/aubio/aubio/issues>`_
  13
  14 Design Basics
  15 -------------
  16
  17 The library is written in C and is optimised for speed and portability.
  18
  19 All memory allocations take place in the `new_` methods. Each successful call
  20 to `new_` should have a matching call to `del_` to deallocate the object.
  21
  22 .. code-block:: C
  23
  24    // new_ to create an object foobar
  25    aubio_foobar_t * new_aubio_foobar(void * args);
  26    // del_ to delete foobar
  27    void del_aubio_foobar (aubio_foobar_t * foobar);
  28
  29 The main computations are done in the `_do` methods.
  30
  31 .. code-block:: C
  32
  33    // _do to process output = foobar(input)
  34    audio_foobar_do (aubio_foobar_t * foobar, fvec_t * input, cvec_t * output);
  35
  36 Most parameters can be read and written at any time:
  37
  38 .. code-block:: C
  39
  40    // _get_param to get foobar.param
  41    smpl_t aubio_foobar_get_a_parameter (aubio_foobar_t * foobar);
  42    // _set_param to set foobar.param
  43    uint_t aubio_foobar_set_a_parameter (aubio_foobar_t * foobar, smpl_t a_parameter);
  44
  45 In some case, more functions are available:
  46
  47 .. code-block:: C
  48
  49    // non-real time functions
  50    uint_t aubio_foobar_reset(aubio_foobar_t * t);
  51
  52 Basic Types
  53 -----------
  54
  55 .. code-block:: C
  56
  57     // integers
  58     uint_t n = 10;                 // unsigned
  59     sint_t delay = -90;            // signed
  60
  61     // float
  62     smpl_t a = -90.;               // simple precision
  63     lsmp_t f = 0.024;              // double precision
  64
  65     // vector of floats (simple precision)
  66     fvec_t * vec = new_fvec(n);
  67     vec->data[0] = 1;
  68     vec->data[vec->length-1] = 1.; // vec->data has n elements
  69     fvec_print(vec);
  70     del_fvec(vec);
  71
  72     // complex data
  73     cvec_t * fftgrain = new_cvec(n);
  74     vec->norm[0] = 1.;             // vec->norm has n/2+1 elements
  75     vec->phas[n/2] = 3.1415;       // vec->phas as well
  76     del_cvec(fftgrain);
  77
  78     // matrix
  79     fmat_t * mat = new_fmat (height, length);
  80     mat->data[height-1][0] = 1;    // mat->data has height rows
  81     mat->data[0][length-1] = 10;   // mat->data[0] has length columns
  82     del_fmat(mat);
  83
  84
  85 Reading a sound file
  86 --------------------
  87
  88 In this example, `aubio_source <https://aubio.org/doc/latest/source_8h.html>`_
  89 is used to read a media file.
  90
  91 First, define a few variables and allocate some memory.
  92
  93 .. literalinclude:: ../tests/src/io/test-source.c
  94    :language: C
  95    :lines: 22-24, 30-32, 34
  96
  97 .. note::
  98    With ``samplerate = 0``, ``aubio_source`` will be created with the file's
  99    original samplerate.
 100
 101 Now for the processing loop:
 102
 103 .. literalinclude:: ../tests/src/io/test-source.c
 104    :language: C
 105    :lines: 40-44
 106
 107 At the end of the processing loop, memory is deallocated:
 108
 109 .. literalinclude:: ../tests/src/io/test-source.c
 110    :language: C
 111    :lines: 55-56
 112
 113 See the complete example: :download:`test-source.c
 114 <../tests/src/io/test-source.c>`.
 115
 116 Computing a spectrum
 117 --------------------
 118
 119 Now let's create a phase vocoder:
 120
 121 .. literalinclude:: ../tests/src/spectral/test-phasevoc.c
 122    :language: C
 123    :lines: 6-11
 124
 125 The processing loop could now look like:
 126
 127 .. literalinclude:: ../tests/src/spectral/test-phasevoc.c
 128    :language: C
 129    :lines: 20-37
 130
 131 Time to clean up the previously allocated memory:
 132
 133 .. literalinclude:: ../tests/src/spectral/test-phasevoc.c
 134    :language: C
 135    :lines: 39-44
 136
 137 See the complete example: :download:`test-phasevoc.c
 138 <../tests/src/spectral/test-phasevoc.c>`.
 139
 140 .. _doxygen-documentation:
 141
 142 Doxygen documentation
 143 ---------------------
 144
 145 The latest version of the API documentation is built using `Doxygen
 146 <http://www.doxygen.org/>`_ and is available at:
 147
 148     https://aubio.org/doc/latest/
 149
 150 Contribute
 151 ----------
 152
 153 Please report any issue and feature request at the `Github issue tracker
 154 <https://github.com/aubio/aubio/issues>`_. Patches and pull-requests welcome!