Callback API

The callback API consists of the following functions :

      typedef long (*src_callback_t) (void *cb_data, float **data) ;

      SRC_STATE* src_callback_new (src_callback_t func,
	                      int converter_type, int channels,
	                      int *error, void* cb_data) ;

      SRC_STATE* src_delete (SRC_STATE *state) ;

      long src_callback_read (SRC_STATE *state, double src_ratio,
	                       long frames, float *data) ;

      int src_reset (SRC_STATE *state) ;
      int src_set_ratio (SRC_STATE *state, double new_ratio) ;

Like the simple API and the full API, the callback based API is able to operate on interleaved multi channel data.

An example of the use of the callback based API can be found in the varispeed-play program in the examples/ directory of the source code tarball.

Initialisation

      SRC_STATE* src_callback_new (src_callback_t func,
	                      int converter_type, int channels,
	                      int *error, void* cb_data) ;

The src_callback_new function returns an anonymous pointer to a sample rate converter callback object, src_state. This is the same type of object as that returned by src_new, but with different internal state. Although these are the same object type, they cannot be used interchangeably. If an error occurs the function returns a NULL pointer and fills in the error value pointed to by the error pointer supplied by the caller.

The caller then passes the SRC_STATE object to the src_callback_read function to pull data out of the converter. When the caller is finished with the converter they should pass it to the clean up function src_delete.

The func parameter is a user supplied function which must match the src_callback_t type signature while cb_data is a pointer to data which be passed as the first parameter to the user supplied callback function. This function is called by the converter whenever it needs input data as a result of being calls to src_callback_read.

If the converter was initialised to work with more than one channel, the callback function must work with mutiple channels of interleaved data. The callback function should return the number of frames it supplying to the converter. For multi channel files, this return value should be the number of floats divided by the number of channels.

The converter must be one of the supplied converter types documented here.

The caller then passes the SRC_STATE pointer to the src_callback_read function to pull data out of the converter.

Callback Read

      long src_callback_read (SRC_STATE *state, double src_ratio,
	                       long frames, float *data) ;

The src_callback_read function is passed the SRC_STATE pointer returned by src_callback_new, the coversion ratio (output_sample_rate / input_sample_rate), the maximum number of output frames to generate and a pointer to a buffer in which to place the output data. For multi channel files, the data int the output buffer is stored in interleaved format.

The src_callback_read function returns the number of frames generated or zero if an error occurs or it runs out of input (ie the user supplied callback function returns zero and there is no more data buffered internally). If an error has occurred, the function src_error will return non-zero.