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

cannam@126: cannam@126: cannam@126:
cannam@126: counter.gif cannam@126:
cannam@126: cannam@126: 		cannam@126:
cannam@126: cannam@126:

Miscellaneous API Documentation

cannam@126: cannam@126:


Error Reporting

cannam@126:

cannam@126: Most of the API functions either return an integer error (ie src_simple cannam@126: and src_process) or return an integer error value via an int pointer cannam@126: parameter (src_new). cannam@126: These integer error values can be converted into a human readable text strings by cannam@126: calling the function: cannam@126:

cannam@126: 
cannam@126:       const char* src_strerror (int error) ;
cannam@126:
cannam@126:

cannam@126: which will return an error string for valid error numbers, the string "No Error" cannam@126: for an error value of zero or a NULL pointer if no error message has been defined cannam@126: for that error value. cannam@126:

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


Converters

cannam@126:

cannam@126: Secret Rabbit Code has a number of different converters which can be selected cannam@126: using the converter_type parameter when calling src_simple or cannam@126: src_new. cannam@126: Currently, the five converters available are: cannam@126:

cannam@126: 
cannam@126:       enum
cannam@126:       {    
cannam@126:           SRC_SINC_BEST_QUALITY       = 0,
cannam@126:           SRC_SINC_MEDIUM_QUALITY     = 1,
cannam@126:           SRC_SINC_FASTEST            = 2,
cannam@126:           SRC_ZERO_ORDER_HOLD         = 3,
cannam@126:           SRC_LINEAR                  = 4
cannam@126:       } ;
cannam@126:
cannam@126:

cannam@126: As new converters are added, they will given a number corresponding to the cannam@126: next inetger. cannam@126:

cannam@126: cannam@126:

cannam@126: The details of these converters are as follows: cannam@126:

cannam@126:
    cannam@126:
  • SRC_SINC_BEST_QUALITY - This is a bandlimited interpolator derived cannam@126: from the mathematical sinc function and this is the highest cannam@126: quality sinc based converter, providing a worst case Signal-to-Noise cannam@126: Ratio (SNR) of 97 decibels (dB) at a bandwidth of 97%. cannam@126: All three SRC_SINC_* converters are based on the techniques of cannam@126: Julius O. Smith cannam@126: although this code was developed independantly. cannam@126:
  • SRC_SINC_MEDIUM_QUALITY - This is another bandlimited interpolator cannam@126: much like the previous one. It has an SNR of 97dB and a bandwidth of 90%. cannam@126: The speed of the conversion is much faster than the previous one. cannam@126:
  • SRC_SINC_FASTEST - This is the fastest bandlimited interpolator and cannam@126: has an SNR of 97dB and a bandwidth of 80%. cannam@126:
  • SRC_ZERO_ORDER_HOLD - A Zero Order Hold converter (interpolated value cannam@126: is equal to the last value). The quality is poor but the conversion speed is cannam@126: blindlingly fast. cannam@126:
  • SRC_LINEAR - A linear converter. Again the quality is poor, but the cannam@126: conversion speed is blindingly fast. cannam@126:
cannam@126:

cannam@126: There are two functions that give either a (text string) name or description cannam@126: for each converter: cannam@126:

cannam@126: 
cannam@126:       const char *src_get_name (int converter_type) ;
cannam@126:       const char *src_get_description (int converter_type) ;
cannam@126:
cannam@126:

cannam@126: The name will typically be a short string for use in a dialog box, while the cannam@126: description string is longer. cannam@126:

cannam@126:

cannam@126: Both of these functions return a NULL pointer if there is no converter for the cannam@126: given converter_type value. cannam@126: Since the converters have consecutive converter_type values, the caller cannam@126: is easily able to figure out the number of converters at run time. cannam@126: This enables a binary dynamically linked against an old version of the library cannam@126: to know about converters from later versions of the library as they become cannam@126: available. cannam@126:

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


SRC_DATA

cannam@126:

cannam@126: Both the simple and the full featured versions of the API use the SRC_DATA cannam@126: struct to pass audio and control data into the sample rate converter. cannam@126: This struct is defined as: 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 data_in pointer is used to pass audio data into the converter while the cannam@126: data_out pointer supplies the converter with an array to hold the converter's cannam@126: output. cannam@126: For a converter which has been configured for mulitchannel operation, these pointers cannam@126: need to point to a single array of interleaved data. cannam@126:

cannam@126:

cannam@126: The input_frames and output_frames fields supply the converter with cannam@126: the lengths of the arrays (in frames) pointed to by the data_in and cannam@126: data_out pointers respectively. cannam@126: For monophinc data, these values would indicate the length of the arrays while cannam@126: for multi channel data these values would be equal to the the length of the array cannam@126: divided by the number of channels. cannam@126:

cannam@126: cannam@126:

cannam@126: The end_of_input field is only used when the sample rate converter is used cannam@126: by calling the src_process function. cannam@126: In this case it should be set to zero if more buffers are to be passed to the cannam@126: converter and 1 if the current buffer is the last. cannam@126:

cannam@126:

cannam@126: Finally, the src_ratio field specifies the conversion ratio defined as cannam@126: the input sample rate divided by the output sample rate. cannam@126: For a connected set of buffers, this value can be varies on each call to cannam@126: src_process resulting in a time varying sample rate conversion cannam@126: process. cannam@126: For time varying sample rate conversions, the ratio will be linearly cannam@126: interpolated between the src_ratio value of the previous call cannam@126: to src_process and the value for the current call. cannam@126:

cannam@126:

cannam@126: The input_frames_used and output_frames_gen fields are set by the cannam@126: converter to inform the caller of the number of frames consumed from the cannam@126: data_in array and the number of frames generated in the data_out cannam@126: array respectively. cannam@126: These values are for the current call to src_process only. cannam@126:

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


Auxillary Functions

cannam@126:

cannam@126: There are four auxillary functions for converting arrays of float data cannam@126: to and from short or int data. cannam@126: These functions are defined as: cannam@126:

cannam@126: 
cannam@126:     void src_short_to_float_array (const short *in, float *out, int len) ;
cannam@126:     void src_float_to_short_array (const float *in, short *out, int len) ;
cannam@126:     void src_int_to_float_array (const int *in, float *out, int len) ;
cannam@126:     void src_float_to_int_array (const float *in, int *out, int len) ;
cannam@126:
cannam@126:

cannam@126: The float data is assumed to be in the range [-1.0, 1.0] and it is cannam@126: automatically scaled on the conversion to and from float. cannam@126: On the float to short/int conversion path, any data values which would overflow cannam@126: the range of short/int data are clipped. cannam@126:

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