cannam@85: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> cannam@85: <HTML> cannam@85: cannam@85: <HEAD> cannam@85: <TITLE> cannam@85: Secret Rabbit Code (aka libsamplerate) cannam@85: </TITLE> cannam@85: <META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)"> cannam@85: <META NAME="Version" CONTENT="libsamplerate-0.1.8"> cannam@85: <META NAME="Description" CONTENT="The Secret Rabbit Code Home Page"> cannam@85: <META NAME="Keywords" CONTENT="libsamplerate sound resample audio dsp Linux"> cannam@85: <LINK REL=StyleSheet HREF="SRC.css" TYPE="text/css" MEDIA="all"> cannam@85: </HEAD> cannam@85: cannam@85: <BODY TEXT="#FFFFFF" BGCOLOR="#000000" LINK="#FB1465" VLINK="#FB1465" ALINK="#FB1465"> cannam@85: <!-- pepper --> cannam@85: <CENTER> cannam@85: <IMG SRC="SRC.png" HEIGHT=100 WIDTH=760 ALT="SRC.png"> cannam@85: </CENTER> cannam@85: <!-- pepper --> cannam@85: <BR> cannam@85: <!-- pepper --> cannam@85: <TABLE ALIGN="center" WIDTH="98%"> cannam@85: <TR> cannam@85: <TD VALIGN="top"> cannam@85: <BR> cannam@85: <DIV CLASS="nav"> cannam@85: <BR> cannam@85: <A HREF="index.html">Home</A><BR> cannam@85: <BR> cannam@85: <A HREF="api_simple.html">Simple API</A><BR> cannam@85: <A HREF="api_full.html">Full API</A><BR> cannam@85: <A HREF="api_misc.html#ErrorReporting">Error Handling</A><BR> cannam@85: <A HREF="api_misc.html">Miscellaneous</A><BR> cannam@85: <BR> cannam@85: <DIV CLASS="block"> cannam@85: Author :<BR>Erik de Castro Lopo cannam@85: <!-- pepper --> cannam@85: <BR><BR> cannam@85: <!-- pepper --> cannam@85: cannam@85: </DIV> cannam@85: <IMG SRC= cannam@85: "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_api.dat" cannam@85: HEIGHT=30 WIDTH=100 ALT="counter.gif"> cannam@85: </DIV> cannam@85: cannam@85: </TD> cannam@85: <!-- pepper --> cannam@85: <!-- ######################################################################## --> cannam@85: <!-- pepper --> cannam@85: <TD VALIGN="top"> cannam@85: <DIV CLASS="block"> cannam@85: cannam@85: <H1><B>Miscellaneous API Documentation</B></H1> cannam@85: <A NAME="ErrorReporting"></A> cannam@85: <H3><BR>Error Reporting</H3> cannam@85: <P> cannam@85: Most of the API functions either return an integer error (ie <B>src_simple</B> cannam@85: and <B>src_process</B>) or return an integer error value via an int pointer cannam@85: parameter (<B>src_new</B>). cannam@85: These integer error values can be converted into a human readable text strings by cannam@85: calling the function: cannam@85: </P> cannam@85: <PRE> cannam@85: const char* src_strerror (int error) ; cannam@85: </PRE> cannam@85: <P> cannam@85: which will return an error string for valid error numbers, the string "No Error" cannam@85: for an error value of zero or a NULL pointer if no error message has been defined cannam@85: for that error value. cannam@85: </P> cannam@85: cannam@85: <A NAME="Converters"></A> cannam@85: <H3><BR>Converters</H3> cannam@85: <P> cannam@85: Secret Rabbit Code has a number of different converters which can be selected cannam@85: using the <B>converter_type</B> parameter when calling <B>src_simple</B> or cannam@85: <b>src_new</B>. cannam@85: Currently, the five converters available are: cannam@85: </P> cannam@85: <PRE> cannam@85: enum cannam@85: { cannam@85: SRC_SINC_BEST_QUALITY = 0, cannam@85: SRC_SINC_MEDIUM_QUALITY = 1, cannam@85: SRC_SINC_FASTEST = 2, cannam@85: SRC_ZERO_ORDER_HOLD = 3, cannam@85: SRC_LINEAR = 4 cannam@85: } ; cannam@85: </PRE> cannam@85: <P> cannam@85: As new converters are added, they will given a number corresponding to the cannam@85: next inetger. cannam@85: </P> cannam@85: cannam@85: <P> cannam@85: The details of these converters are as follows: cannam@85: </P> cannam@85: <UL> cannam@85: <LI> <B>SRC_SINC_BEST_QUALITY</B> - This is a bandlimited interpolator derived cannam@85: from the mathematical <B>sinc</B> function and this is the highest cannam@85: quality sinc based converter, providing a worst case Signal-to-Noise cannam@85: Ratio (SNR) of 97 decibels (dB) at a bandwidth of 97%. cannam@85: All three SRC_SINC_* converters are based on the techniques of cannam@85: <A HREF="http://ccrma-www.stanford.edu/~jos/resample/">Julius O. Smith</A> cannam@85: although this code was developed independantly. cannam@85: <LI> <B>SRC_SINC_MEDIUM_QUALITY</B> - This is another bandlimited interpolator cannam@85: much like the previous one. It has an SNR of 97dB and a bandwidth of 90%. cannam@85: The speed of the conversion is much faster than the previous one. cannam@85: <LI> <B>SRC_SINC_FASTEST</B> - This is the fastest bandlimited interpolator and cannam@85: has an SNR of 97dB and a bandwidth of 80%. cannam@85: <LI><B>SRC_ZERO_ORDER_HOLD</B> - A Zero Order Hold converter (interpolated value cannam@85: is equal to the last value). The quality is poor but the conversion speed is cannam@85: blindlingly fast. cannam@85: <li><b>SRC_LINEAR</b> - A linear converter. Again the quality is poor, but the cannam@85: conversion speed is blindingly fast. cannam@85: </UL> cannam@85: <P> cannam@85: There are two functions that give either a (text string) name or description cannam@85: for each converter: cannam@85: </P> cannam@85: <PRE> cannam@85: const char *src_get_name (int converter_type) ; cannam@85: const char *src_get_description (int converter_type) ; cannam@85: </PRE> cannam@85: <P> cannam@85: The name will typically be a short string for use in a dialog box, while the cannam@85: description string is longer. cannam@85: </P> cannam@85: <P> cannam@85: Both of these functions return a NULL pointer if there is no converter for the cannam@85: given <B>converter_type</B> value. cannam@85: Since the converters have consecutive <B>converter_type</B> values, the caller cannam@85: is easily able to figure out the number of converters at run time. cannam@85: This enables a binary dynamically linked against an old version of the library cannam@85: to know about converters from later versions of the library as they become cannam@85: available. cannam@85: </P> cannam@85: cannam@85: <A NAME="SRC_DATA"></A> cannam@85: <H3><BR>SRC_DATA</H3> cannam@85: <P> cannam@85: Both the simple and the full featured versions of the API use the <B>SRC_DATA</B> cannam@85: struct to pass audio and control data into the sample rate converter. cannam@85: This struct is defined as: cannam@85: </P> cannam@85: <PRE> cannam@85: typedef struct cannam@85: { float *data_in, *data_out ; cannam@85: cannam@85: long input_frames, output_frames ; cannam@85: long input_frames_used, output_frames_gen ; cannam@85: cannam@85: int end_of_input ; cannam@85: cannam@85: double src_ratio ; cannam@85: } SRC_DATA ; cannam@85: </PRE> cannam@85: <P> cannam@85: The <B>data_in</B> pointer is used to pass audio data into the converter while the cannam@85: <B>data_out</B> pointer supplies the converter with an array to hold the converter's cannam@85: output. cannam@85: For a converter which has been configured for mulitchannel operation, these pointers cannam@85: need to point to a single array of interleaved data. cannam@85: </P> cannam@85: <P> cannam@85: The <B>input_frames</B> and <B>output_frames</B> fields supply the converter with cannam@85: the lengths of the arrays (in frames) pointed to by the <B>data_in</B> and cannam@85: <b>data_out</B> pointers respectively. cannam@85: For monophinc data, these values would indicate the length of the arrays while cannam@85: for multi channel data these values would be equal to the the length of the array cannam@85: divided by the number of channels. cannam@85: </P> cannam@85: cannam@85: <P> cannam@85: The <B>end_of_input</B> field is only used when the sample rate converter is used cannam@85: by calling the <B>src_process</B> function. cannam@85: In this case it should be set to zero if more buffers are to be passed to the cannam@85: converter and 1 if the current buffer is the last. cannam@85: </P> cannam@85: <P> cannam@85: Finally, the <B>src_ratio</B> field specifies the conversion ratio defined as cannam@85: the input sample rate divided by the output sample rate. cannam@85: For a connected set of buffers, this value can be varies on each call to cannam@85: <B>src_process</B> resulting in a time varying sample rate conversion cannam@85: process. cannam@85: For time varying sample rate conversions, the ratio will be linearly cannam@85: interpolated between the <B>src_ratio</B> value of the previous call cannam@85: to <B>src_process</B> and the value for the current call. cannam@85: </P> cannam@85: <P> cannam@85: The <B>input_frames_used</B> and <B>output_frames_gen</B> fields are set by the cannam@85: converter to inform the caller of the number of frames consumed from the cannam@85: <B>data_in</B> array and the number of frames generated in the <B>data_out</B> cannam@85: array respectively. cannam@85: These values are for the current call to <B>src_process</B> only. cannam@85: </P> cannam@85: cannam@85: <A NAME="Aux"></A> cannam@85: <H3><BR>Auxillary Functions</H3> cannam@85: <P> cannam@85: There are four auxillary functions for converting arrays of float data cannam@85: to and from short or int data. cannam@85: These functions are defined as: cannam@85: </P> cannam@85: <PRE> cannam@85: void src_short_to_float_array (const short *in, float *out, int len) ; cannam@85: void src_float_to_short_array (const float *in, short *out, int len) ; cannam@85: void src_int_to_float_array (const int *in, float *out, int len) ; cannam@85: void src_float_to_int_array (const float *in, int *out, int len) ; cannam@85: </PRE> cannam@85: <P> cannam@85: The float data is assumed to be in the range [-1.0, 1.0] and it is cannam@85: automatically scaled on the conversion to and from float. cannam@85: On the float to short/int conversion path, any data values which would overflow cannam@85: the range of short/int data are clipped. cannam@85: </P> cannam@85: cannam@85: </DIV> cannam@85: </TD></TR> cannam@85: </TABLE> cannam@85: cannam@85: </BODY> cannam@85: </HTML> cannam@85: