cannam@126: cannam@126:

Simple API

cannam@126: cannam@126:

cannam@126: Important Note: cannam@126: The simple API is not designed to work on small chunks of a larger piece of cannam@126: audio. cannam@126: If you attempt to use it this way you are doing it wrong and will not get the cannam@126: results you want. cannam@126: For processing audio data in chunks you must use the cannam@126: full api cannam@126: or the cannam@126: callback based api. cannam@126:

cannam@126: cannam@126:

cannam@126: cannam@126:

cannam@126: The simple API consists of a single function : cannam@126:

cannam@126:

cannam@126:       int src_simple (SRC_DATA *data, int converter_type, int channels) ;
cannam@126:

cannam@126:

cannam@126: The use of this function rather than the more fully featured API requires the caller cannam@126: to know the total length of the input data before hand and that all input and output cannam@126: data can be held in the system's memory at once. cannam@126: It also assumes that there is a single constant ratio between input and output sample cannam@126: rates. cannam@126: cannam@126:

cannam@126: cannam@126:

cannam@126: Dealing with the easy stuff first, the converter_type parameter should be cannam@126: one of the values defined in samplerate.h and documented cannam@126: here while the channels parameter cannam@126: specifies the number of interleaved channels that the sample rate converter cannam@126: is being asked to process (number of input channels and output channels is always cannam@126: equal). cannam@126: There is no hard upper limit on the number of channels; it is limited purely cannam@126: by the amount of memory available. cannam@126:

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

cannam@126: The first parameter to src_simple is a pointer to an SRC_DATA struct cannam@126: (more info here) defined as follows: 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:

cannam@126:

cannam@126: When the src_simple 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 used to generate the provided number of cannam@126: output frames. cannam@126:

cannam@126:

cannam@126: The src_simple function returns a non-zero value when an error occurs. cannam@126: See here for how to convert the error value into cannam@126: a text string. cannam@126:

cannam@126: cannam@126: