cannam@85: cannam@85:

Full API

cannam@85:

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

cannam@85:

cannam@85:       SRC_STATE* src_new (int converter_type, int channels, int *error) ;
cannam@85:       SRC_STATE* src_delete (SRC_STATE *state) ;
cannam@85: 
cannam@85:       int src_process (SRC_STATE *state, SRC_DATA *data) ;
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:

Initialisation

cannam@85:

cannam@85:       SRC_STATE* src_new (int converter_type, int channels, int *error) ;
cannam@85:

cannam@85:

cannam@85: The src_new function returns an anonymous pointer to a sample rate cannam@85: converter object, src_state. 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: The converter must be one of the supplied converter types documented cannam@85: here. cannam@85:

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

Cleanup

cannam@85:

cannam@85:       SRC_STATE* src_delete (SRC_STATE *state) ;
cannam@85:

cannam@85:

cannam@85: The src_delete function frees up all memory allocated for the given sample cannam@85: rate converter object and returns a NULL pointer. cannam@85: The caller is responsible for freeing any memory passed to the sample rate converter cannam@85: via the pointer to the SRC_DATA struct. cannam@85:

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

Process

cannam@85:

cannam@85:       int src_process (SRC_STATE *state, SRC_DATA *data) ;
cannam@85:

cannam@85:

cannam@85: The src_process function processes the data provided by the caller cannam@85: in an SRC_DATA struct using the sample rate converter object specified cannam@85: by the SRC_STATE pointer. cannam@85: When operating on streaming data, this function can be called over and over again, cannam@85: with each new call providing new input data and returning new output data. cannam@85:

cannam@85: cannam@85:

cannam@85: The SRC_DATA struct passed as the second parameter to the src_process cannam@85: function has the following fields: cannam@85:

cannam@85:

cannam@85:       typedef struct
cannam@85:       {   float  *data_in, *data_out ;
cannam@85: 
cannam@85:           long   input_frames, output_frames ;
cannam@85:           long   input_frames_used, output_frames_gen ;
cannam@85: 
cannam@85:           int    end_of_input ;
cannam@85: 
cannam@85:           double src_ratio ;
cannam@85:       } SRC_DATA ;
cannam@85:

cannam@85:

cannam@85: The fields of this struct which must be filled in by the caller are: cannam@85:

cannam@85:

cannam@85:       data_in       : A pointer to the input data samples.
cannam@85:       input_frames  : The number of frames of data pointed to by data_in.
cannam@85:       data_out      : A pointer to the output data samples.
cannam@85:       output_frames : Maximum number of frames pointer to by data_out.
cannam@85:       src_ratio     : Equal to output_sample_rate / input_sample_rate.
cannam@85:       end_of_input  : Equal to 0 if more input data is available and 1 
cannam@85:                       otherwise.
cannam@85:

cannam@85:

cannam@85: Note that the data_in and data_out arrays may not overlap. If they do, the cannam@85: library will return an error code. cannam@85:

cannam@85:

cannam@85: When the src_process function returns output_frames_gen will be cannam@85: set to the number of output frames generated and input_frames_used will cannam@85: be set to the number of input frames consumed to generate the provided number of cannam@85: output frames. cannam@85:

cannam@85: cannam@85:

cannam@85: The src_process function returns non-zero if an error occurs. cannam@85: The non-zero error return value can be decoded into a text string using the function cannam@85: documented here. cannam@85:

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

Reset

cannam@85:

cannam@85:       int src_reset (SRC_STATE *state) ;
cannam@85:

cannam@85:

cannam@85: The src_reset function resets the internal state of the sample rate cannam@85: converter object to the same state it had immediately after its creation using cannam@85: src_new. cannam@85: This should be called whenever a sample rate converter is to be used on two cannam@85: separate, unrelated pieces of audio. cannam@85:

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

Set Ratio

cannam@85:

cannam@85:       int src_set_ratio (SRC_STATE *state, double new_ratio) ;
cannam@85:

cannam@85: cannam@85:

cannam@85: When using the src_process or src_callback_process APIs and cannam@85: updating the src_ratio field of the SRC_STATE struct, the library cannam@85: will try to smoothly transition between the conversion ratio of the last call cannam@85: and the conversion ratio of the current call. cannam@85:

cannam@85: cannam@85:

cannam@85: If the user want to bypass this smooth transition and achieve a step response in cannam@85: the conversion ratio, the src_set_ratio function can be used to set the cannam@85: starting conversion ratio of the next call to src_process or cannam@85: src_callback_process. cannam@85:

cannam@85: cannam@85:

cannam@85: This function returns non-zero on error and the error return value can be cannam@85: decoded into a text string using the function documented cannam@85: here.

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