cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: Secret Rabbit Code (aka libsamplerate) cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85:
cannam@85: SRC.png cannam@85:
cannam@85: cannam@85:
cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85:
cannam@85:
cannam@85:
cannam@85:
cannam@85: Home
cannam@85:
cannam@85: Simple API
cannam@85: Full API
cannam@85: Callback API
cannam@85: Miscellaneous
cannam@85: Error Handling
cannam@85:
cannam@85:
cannam@85: Author :
Erik de Castro Lopo cannam@85: cannam@85:

cannam@85: cannam@85: cannam@85:
cannam@85: counter.gif cannam@85:
cannam@85: cannam@85: 		cannam@85:
cannam@85: cannam@85:

Callback API

cannam@85:

cannam@85: The callback API consists of the following functions : cannam@85:

cannam@85: 
cannam@85:       typedef long (*src_callback_t) (void *cb_data, float **data) ;
cannam@85: 
cannam@85:       SRC_STATE* src_callback_new (src_callback_t func,
cannam@85: 	                      int converter_type, int channels,
cannam@85: 	                      int *error, void* cb_data) ;
cannam@85: 
cannam@85:       SRC_STATE* src_delete (SRC_STATE *state) ;
cannam@85: 
cannam@85:       long src_callback_read (SRC_STATE *state, double src_ratio,
cannam@85: 	                       long frames, float *data) ;
cannam@85: 
cannam@85:       int src_reset (SRC_STATE *state) ;
cannam@85:       int src_set_ratio (SRC_STATE *state, double new_ratio) ;
cannam@85:
cannam@85:
cannam@85: cannam@85:

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

cannam@85: cannam@85:

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

cannam@85: cannam@85: cannam@85: cannam@85:


Initialisation

cannam@85: 
cannam@85:       SRC_STATE* src_callback_new (src_callback_t func,
cannam@85: 	                      int converter_type, int channels,
cannam@85: 	                      int *error, void* cb_data) ;
cannam@85:
cannam@85:

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

cannam@85:

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

cannam@85:

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

cannam@85:

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

cannam@85:

cannam@85: The converter must be one of the supplied converter types documented cannam@85: here. cannam@85:

cannam@85:

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

cannam@85: cannam@85: cannam@85: cannam@85:


Callback Read

cannam@85: 
cannam@85:       long src_callback_read (SRC_STATE *state, double src_ratio,
cannam@85: 	                       long frames, float *data) ;
cannam@85:
cannam@85:

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

cannam@85:

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

cannam@85: cannam@85:

cannam@85: See also : cannam@85: src_set_ratio cannam@85:

cannam@85: cannam@85: cannam@85: cannam@85:
cannam@85:
cannam@85: cannam@85: cannam@85: cannam@85: