cannam@126: cannam@126:

Full API

cannam@126:

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

cannam@126:

cannam@126:       SRC_STATE* src_new (int converter_type, int channels, int *error) ;
cannam@126:       SRC_STATE* src_delete (SRC_STATE *state) ;
cannam@126: 
cannam@126:       int src_process (SRC_STATE *state, SRC_DATA *data) ;
cannam@126:       int src_reset (SRC_STATE *state) ;
cannam@126:       int src_set_ratio (SRC_STATE *state, double new_ratio) ;
cannam@126:

cannam@126: cannam@126: cannam@126:

Initialisation

cannam@126:

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

cannam@126:

cannam@126: The src_new function returns an anonymous pointer to a sample rate cannam@126: converter object, src_state. cannam@126: If an error occurs the function returns a NULL pointer and fills in the cannam@126: error value pointed to by the error pointer supplied by the caller. cannam@126: The converter must be one of the supplied converter types documented cannam@126: here. cannam@126:

cannam@126: cannam@126: cannam@126:

Cleanup

cannam@126:

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

cannam@126:

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

cannam@126: cannam@126: cannam@126:

Process

cannam@126:

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

cannam@126:

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

cannam@126: cannam@126:

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

cannam@126:

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

cannam@126:

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

cannam@126:

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

cannam@126:

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

cannam@126:

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

cannam@126: cannam@126:

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

cannam@126: cannam@126: cannam@126:

Reset

cannam@126:

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

cannam@126:

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

cannam@126: cannam@126: cannam@126:

Set Ratio

cannam@126:

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

cannam@126: cannam@126:

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

cannam@126: cannam@126:

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

cannam@126: cannam@126:

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

cannam@126: cannam@126: cannam@126: cannam@126: