Changeset 633400d for doc/develop.rst


Ignore:
Timestamp:
Dec 5, 2018, 10:34:39 PM (5 years ago)
Author:
Paul Brossier <piem@piem.org>
Branches:
feature/cnn, feature/crepe, feature/pitchshift, feature/timestretch, fix/ffmpeg5, master
Children:
283a619a
Parents:
5b46bc3 (diff), f19db54 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.
Message:

Merge branch 'master' into feature/pitchshift

File:
1 edited

Legend:

Unmodified
Added
Removed

  • doc/develop.rst

    r5b46bc3 r633400d  
    1 Developping with aubio
    2 ======================
     1.. _develop:
    32
    4 Read `Contribute`_ to report issues and request new features.
     3Developing with aubio
     4=====================
    55
    6 See `Doxygen documentation`_ for the complete documentation of the C library,
    7 built using `Doxygen <http://www.doxygen.org/>`_.
     6Here is a brief overview of the C library.
    87
    9 Below is a brief `Library overview`_.
     8For a more detailed list of available functions, see the `API documentation
     9<https://aubio.org/doc/latest/>`_.
    1010
    11 Library overview
    12 ----------------
     11To report issues, ask questions, and request new features, use `Github Issues
     12<https://github.com/aubio/aubio/issues>`_
    1313
    14 Here is a brief overview of the C library. See also the `Doxygen
    15 documentation`_ for a more detailed list of available functions.
     14Design Basics
     15-------------
    1616
    17 Vectors and matrix
    18 ``````````````````
     17The library is written in C and is optimised for speed and portability.
    1918
    20 ``fvec_t`` are used to hold vectors of float (``smpl_t``).
    21 
    22 .. literalinclude:: ../tests/src/test-fvec.c
    23    :language: C
    24    :lines: 7
    25 
     19All memory allocations take place in the `new_` methods. Each successful call
     20to `new_` should have a matching call to `del_` to deallocate the object.
    2621
    2722.. code-block:: C
    2823
    29         // set some elements
    30         vec->data[511] = 2.;
    31         vec->data[vec->length-2] = 1.;
     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);
    3228
    33 Similarly, ``fmat_t`` are used to hold matrix of floats.
     29The main computations are done in the `_do` methods.
    3430
    35 .. literalinclude:: ../tests/src/test-fmat.c
    36    :language: C
    37    :lines: 9-19
     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
     36Most 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
     45In 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
     52Basic 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
    3884
    3985Reading a sound file
    40 ````````````````````
    41 In this example, ``aubio_source`` is used to read a media file.
     86--------------------
    4287
    43 First, create the objects we need.
     88In this example, `aubio_source <https://aubio.org/doc/latest/source_8h.html>`_
     89is used to read a media file.
     90
     91First, define a few variables and allocate some memory.
    4492
    4593.. literalinclude:: ../tests/src/io/test-source.c
    … …  
    57105   :lines: 40-44
    58106
    59 At the end of the processing loop, clean-up and de-allocate memory:
     107At the end of the processing loop, memory is deallocated:
    60108
    61109.. literalinclude:: ../tests/src/io/test-source.c
    62110   :language: C
    63    :lines: 50-56
     111   :lines: 55-56
    64112
    65113See the complete example: :download:`test-source.c
    66114<../tests/src/io/test-source.c>`.
    67115
    68 Computing the spectrum
    69 ``````````````````````
     116Computing a spectrum
     117--------------------
    70118
    71119Now let's create a phase vocoder:
    … …  
    75123   :lines: 6-11
    76124
    77 The processing loop could know look like:
     125The processing loop could now look like:
    78126
    79127.. literalinclude:: ../tests/src/spectral/test-phasevoc.c
    80128   :language: C
    81    :lines: 21-35
     129   :lines: 20-37
     130
     131Time to clean up the previously allocated memory:
     132
     133.. literalinclude:: ../tests/src/spectral/test-phasevoc.c
     134   :language: C
     135   :lines: 39-44
    82136
    83137See the complete example: :download:`test-phasevoc.c
    … …  
    89143---------------------
    90144
    91 The latest version of the doxygen documentation is available at:
     145The latest version of the API documentation is built using `Doxygen
     146<http://www.doxygen.org/>`_ and is available at:
    92147
    93     https://aubio.org/doc/latest
     148    https://aubio.org/doc/latest/
    94149
    95150Contribute
    … …  
    98153Please report any issue and feature request at the `Github issue tracker
    99154<https://github.com/aubio/aubio/issues>`_. Patches and pull-requests welcome!
    100 
Note: See TracChangeset for help on using the changeset viewer.