Merge branch 'master' into awhitening
[aubio.git] / doc / develop.rst
1 .. _develop:
2
3 Developping 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!