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

Chris@41: Chris@41: Chris@41:
Chris@41: counter.gif Chris@41:
Chris@41: Chris@41: 		Chris@41:
Chris@41: Chris@41:

Full API

Chris@41:

Chris@41: The full API consists of the following functions : Chris@41:

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


Initialisation

Chris@41: 
Chris@41:       SRC_STATE* src_new (int converter_type, int channels, int *error) ;
Chris@41:
Chris@41:

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

Chris@41: Chris@41: Chris@41:


Cleanup

Chris@41: 
Chris@41:       SRC_STATE* src_delete (SRC_STATE *state) ;
Chris@41:
Chris@41:

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

Chris@41: Chris@41: Chris@41:


Process

Chris@41: 
Chris@41:       int src_process (SRC_STATE *state, SRC_DATA *data) ;
Chris@41:
Chris@41:

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

Chris@41: Chris@41:

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

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

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

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

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

Chris@41:

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

Chris@41: Chris@41:

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

Chris@41: Chris@41: Chris@41:


Reset

Chris@41: 
Chris@41:       int src_reset (SRC_STATE *state) ;
Chris@41:
Chris@41:

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

Chris@41: Chris@41: Chris@41:


Set Ratio

Chris@41: 
Chris@41:       int src_set_ratio (SRC_STATE *state, double new_ratio) ;
Chris@41:
Chris@41: Chris@41:

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

Chris@41: Chris@41:

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

Chris@41: Chris@41:

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

Chris@41: Chris@41: Chris@41: Chris@41:
Chris@41:
Chris@41: Chris@41: Chris@41: Chris@41: