API design

The design of each 'object' in aubio is as follows.

The private structure, which members are defined in the '.c' source file and not directly accessible from outside this file.

typedef struct _aubio_foo_t aubio_foo_t;

The creation function, which should take as little parameters as required, yet be general enough to be flexible. All the memory allocation required for this object should take place in this function.

aubio_foo_t * new_aubio_foo (char_t * mode,
      uint_t buf_size, uint_t hop_size, uint_t channels, uint_t samplerate);

The processing function, should be always be named object_name_do. In general it should take one input and one output, although some exceptions may happen.

void aubio_foo_do (aubio_foo_t *o, fvec_t * in, fvec_t * out);

The setter functions, which take one or more arguments, should always return an unsigned int. Unless specified in the documentation, it should be assumed that these functions are not real time, since they could have to do some memory allocation operation, for instance to re-size vectors.

uint_t aubio_foo_set_param1 (aubio_foo_t * o, smpl_t param1);
uint_t aubio_foo_set_param2 (aubio_foo_t * o, fvec_t * param2);

Similarly, getter functions can be used to get some data or observe about what is going on inside the object.

cvec_t * aubio_foo_get_feature1 (aubio_foo_t * bt);
smpl_t aubio_foo_get_confidence (aubio_foo_t * bt);

Optionally, parameters can have a getter function. The return type of a getter is same as the type of the parameter to get.

smpl_t aubio_foo_get_param1 (aubio_foo_t * bt);

The function to destroy the object should take only one argument, this object, and not return anything:

void del_aubio_foo(aubio_tempo_t * o);

This design should allow for some flexibility without breaking the ABI compatibility. For instance, adding parameters and modifying the object members should be transparent for developers using aubio. The choice of the parameters for the new_ functions are very important. Here are some guidelines about these.

• Unless the object really requires it, do not add an argument to its new_ function.
• If you pass the number of channels, pass it last.
• If it you pass the sampling rate, pass it last, after the number of channels.