From fbebc525117f18d5751e6951bc4ffcc51f70dcc4 Mon Sep 17 00:00:00 2001 From: jacqueline Date: Tue, 1 Aug 2023 14:00:31 +1000 Subject: Add libsamplerate for resampling decoder output --- .../libsamplerate-0.2.2/docs/api_misc.md | 145 +++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100755 lib/libsamplerate/libsamplerate-0.2.2/docs/api_misc.md (limited to 'lib/libsamplerate/libsamplerate-0.2.2/docs/api_misc.md') diff --git a/lib/libsamplerate/libsamplerate-0.2.2/docs/api_misc.md b/lib/libsamplerate/libsamplerate-0.2.2/docs/api_misc.md new file mode 100755 index 00000000..9e9a53ba --- /dev/null +++ b/lib/libsamplerate/libsamplerate-0.2.2/docs/api_misc.md @@ -0,0 +1,145 @@ +--- +layout: default +--- + +# Miscellaneous API Documentation + +## Error Reporting + +Most of the API functions either return an integer error (ie **src_simple** and +**src_process**) or return an integer error value via an int pointer parameter +(**src_new**). These integer error values can be converted into human-readable +text strings by calling the function: + +```c +const char* src_strerror (int error) ; +``` + +which will return an error string for valid error numbers, the string +\"No Error\" for an error value of zero or a NULL pointer if no error message +has been defined for that error value. + +## Converters + +Secret Rabbit Code has a number of different converters which can be selected +using the **converter_type** parameter when calling **src_simple** or +**src_new**. Currently, the five converters available are: + +```c +enum +{ + SRC_SINC_BEST_QUALITY = 0, + SRC_SINC_MEDIUM_QUALITY = 1, + SRC_SINC_FASTEST = 2, + SRC_ZERO_ORDER_HOLD = 3, + SRC_LINEAR = 4 +} ; +``` + +As new converters are added, they will be given a number corresponding to the next +integer. + +The details of these converters are as follows: + +- **SRC_SINC_BEST_QUALITY** - This is a bandlimited interpolator derived from + the mathematical **sinc** function and this is the highest quality sinc based + converter, providing a worst case Signal-to-Noise Ratio (SNR) of 97 decibels + (dB) at a bandwidth of 97%. All three SRC_SINC_* converters are based on the + techniques of [Julius O. Smith](http://ccrma.stanford.edu/~jos/resample/) + although this code was developed independently. +- **SRC_SINC_MEDIUM_QUALITY** - This is another bandlimited interpolator much + like the previous one. It has an SNR of 97dB and a bandwidth of 90%. The speed + of the conversion is much faster than the previous one. +- **SRC_SINC_FASTEST** - This is the fastest bandlimited interpolator and has an + SNR of 97dB and a bandwidth of 80%. +- **SRC_ZERO_ORDER_HOLD** - A Zero Order Hold converter (interpolated value is + equal to the last value). The quality is poor but the conversion speed is + blindlingly fast. Be aware that this interpolator is not bandlimited, and the + user is responsible for adding anti-aliasing filtering. +- **SRC_LINEAR** - A linear converter. Again the quality is poor, but the + conversion speed is blindingly fast. This interpolator is also not bandlimited, + and the user is responsible for adding anti-aliasing filtering. + +There are two functions that give either a (text string) name or description for +each converter: + +```c +const char *src_get_name (int converter_type) ; +const char *src_get_description (int converter_type) ; +``` + +The name will typically be a short string for use in a dialog box, while the +description string is longer. + +Both of these functions return a NULL pointer if there is no converter for the +given **converter_type** value. Since the converters have consecutive +**converter_type** values, the caller is easily able to figure out the number of +converters at run time. This enables a binary dynamically linked against an old +version of the library to know about converters from later versions of the +library as they become available. + +## SRC_DATA + +Both the simple and the full featured versions of the API use the **SRC_DATA** +struct to pass audio and control data into the sample rate converter. This +struct is defined as: + +```c +typedef struct +{ const float *data_in; + float *data_out ; + + long input_frames, output_frames ; + long input_frames_used, output_frames_gen ; + + int end_of_input ; + + double src_ratio ; +} SRC_DATA ; +``` + +The **data_in** pointer is used to pass audio data into the converter while the +**data_out** pointer supplies the converter with an array to hold the +converter's output. For a converter which has been configured for multichannel +operation, these pointers need to point to a single array of interleaved data. + +The **input_frames** and **output_frames** fields supply the converter with the +lengths of the arrays (in frames) pointed to by the **data_in** and **data_out** +pointers respectively. For monophonic data, these values would indicate the +length of the arrays while for multi channel data these values would be equal to +the length of the array divided by the number of channels. + +The **end_of_input** field is only used when the sample rate converter is used +by calling the **src_process** function. In this case it should be set to zero +if more buffers are to be passed to the converter and 1 if the current buffer is +the last. + +Finally, the **src_ratio** field specifies the conversion ratio defined as the +output sample rate divided by the input sample rate. For a connected set of +buffers, this value can vary on each call to **src_process** resulting in a +time varying sample rate conversion process. For time varying sample rate +conversions, the ratio will be linearly interpolated between the **src_ratio** +value of the previous call to **src_process** and the value for the current +call. + +The **input_frames_used** and **output_frames_gen** fields are set by the +converter to inform the caller of the number of frames consumed from the +**data_in** array and the number of frames generated in the **data_out** array +respectively. These values are for the current call to **src_process** only. + +## Auxiliary Functions + +There are four auxiliary functions for converting arrays of float data to and +from short or int data. These functions are defined as: + +```c +void src_short_to_float_array (const short *in, float *out, int len) ; +void src_float_to_short_array (const float *in, short *out, int len) ; +void src_int_to_float_array (const int *in, float *out, int len) ; +void src_float_to_int_array (const float *in, int *out, int len) ; +``` + +The float data is assumed to be in the range [-1.0, 1.0] and it is automatically +scaled on the conversion to and from float. On the float to short/int conversion +path, any data values which would overflow the range of short/int data are +clipped. -- cgit v1.2.3