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

Chris@0: Chris@0: Chris@0:
Chris@0: counter.gif Chris@0:
Chris@0: Chris@0: 		Chris@0:
Chris@0: Chris@0:

Full API

Chris@0:

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

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


Initialisation

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

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

Chris@0: Chris@0: Chris@0:


Cleanup

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

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

Chris@0: Chris@0: Chris@0:


Process

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

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

Chris@0: Chris@0:

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

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

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

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

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

Chris@0:

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

Chris@0: Chris@0:

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

Chris@0: Chris@0: Chris@0:


Reset

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

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

Chris@0: Chris@0: Chris@0:


Set Ratio

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

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

Chris@0: Chris@0:

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

Chris@0: Chris@0:

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

Chris@0: Chris@0: Chris@0: Chris@0:
Chris@0:
Chris@0: Chris@0: Chris@0: Chris@0: