Emeric Vigier | eebea67 | 2012-08-06 17:36:30 -0400 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <HTML> |
| 3 | |
| 4 | <HEAD> |
| 5 | <TITLE> |
| 6 | Secret Rabbit Code (aka libsamplerate) |
| 7 | </TITLE> |
| 8 | <META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)"> |
| 9 | <META NAME="Version" CONTENT="libsamplerate-0.1.8"> |
| 10 | <META NAME="Description" CONTENT="The Secret Rabbit Code Home Page"> |
| 11 | <META NAME="Keywords" CONTENT="libsamplerate sound resample audio dsp Linux"> |
| 12 | <LINK REL=StyleSheet HREF="SRC.css" TYPE="text/css" MEDIA="all"> |
| 13 | </HEAD> |
| 14 | |
| 15 | <BODY TEXT="#FFFFFF" BGCOLOR="#000000" LINK="#FB1465" VLINK="#FB1465" ALINK="#FB1465"> |
| 16 | <!-- pepper --> |
| 17 | <CENTER> |
| 18 | <IMG SRC="SRC.png" HEIGHT=100 WIDTH=760 ALT="SRC.png"> |
| 19 | </CENTER> |
| 20 | <!-- pepper --> |
| 21 | <BR> |
| 22 | <!-- pepper --> |
| 23 | <TABLE ALIGN="center" WIDTH="98%"> |
| 24 | <TR> |
| 25 | <TD VALIGN="top"> |
| 26 | <BR> |
| 27 | <DIV CLASS="nav"> |
| 28 | <BR> |
| 29 | <A HREF="index.html">Home</A><BR> |
| 30 | <BR> |
| 31 | <A HREF="api_simple.html">Simple API</A><BR> |
| 32 | <A HREF="api_full.html">Full API</A><BR> |
| 33 | <A HREF="api_misc.html#ErrorReporting">Error Handling</A><BR> |
| 34 | <A HREF="api_misc.html">Miscellaneous</A><BR> |
| 35 | <BR> |
| 36 | <DIV CLASS="block"> |
| 37 | Author :<BR>Erik de Castro Lopo |
| 38 | <!-- pepper --> |
| 39 | <BR><BR> |
| 40 | <!-- pepper --> |
| 41 | |
| 42 | </DIV> |
| 43 | <IMG SRC= |
| 44 | "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_api.dat" |
| 45 | HEIGHT=30 WIDTH=100 ALT="counter.gif"> |
| 46 | </DIV> |
| 47 | |
| 48 | </TD> |
| 49 | <!-- pepper --> |
| 50 | <!-- ######################################################################## --> |
| 51 | <!-- pepper --> |
| 52 | <TD VALIGN="top"> |
| 53 | <DIV CLASS="block"> |
| 54 | |
| 55 | <H1><B>Miscellaneous API Documentation</B></H1> |
| 56 | <A NAME="ErrorReporting"></A> |
| 57 | <H3><BR>Error Reporting</H3> |
| 58 | <P> |
| 59 | Most of the API functions either return an integer error (ie <B>src_simple</B> |
| 60 | and <B>src_process</B>) or return an integer error value via an int pointer |
| 61 | parameter (<B>src_new</B>). |
| 62 | These integer error values can be converted into a human readable text strings by |
| 63 | calling the function: |
| 64 | </P> |
| 65 | <PRE> |
| 66 | const char* src_strerror (int error) ; |
| 67 | </PRE> |
| 68 | <P> |
| 69 | which will return an error string for valid error numbers, the string "No Error" |
| 70 | for an error value of zero or a NULL pointer if no error message has been defined |
| 71 | for that error value. |
| 72 | </P> |
| 73 | |
| 74 | <A NAME="Converters"></A> |
| 75 | <H3><BR>Converters</H3> |
| 76 | <P> |
| 77 | Secret Rabbit Code has a number of different converters which can be selected |
| 78 | using the <B>converter_type</B> parameter when calling <B>src_simple</B> or |
| 79 | <b>src_new</B>. |
| 80 | Currently, the five converters available are: |
| 81 | </P> |
| 82 | <PRE> |
| 83 | enum |
| 84 | { |
| 85 | SRC_SINC_BEST_QUALITY = 0, |
| 86 | SRC_SINC_MEDIUM_QUALITY = 1, |
| 87 | SRC_SINC_FASTEST = 2, |
| 88 | SRC_ZERO_ORDER_HOLD = 3, |
| 89 | SRC_LINEAR = 4 |
| 90 | } ; |
| 91 | </PRE> |
| 92 | <P> |
| 93 | As new converters are added, they will given a number corresponding to the |
| 94 | next inetger. |
| 95 | </P> |
| 96 | |
| 97 | <P> |
| 98 | The details of these converters are as follows: |
| 99 | </P> |
| 100 | <UL> |
| 101 | <LI> <B>SRC_SINC_BEST_QUALITY</B> - This is a bandlimited interpolator derived |
| 102 | from the mathematical <B>sinc</B> function and this is the highest |
| 103 | quality sinc based converter, providing a worst case Signal-to-Noise |
| 104 | Ratio (SNR) of 97 decibels (dB) at a bandwidth of 97%. |
| 105 | All three SRC_SINC_* converters are based on the techniques of |
| 106 | <A HREF="http://ccrma-www.stanford.edu/~jos/resample/">Julius O. Smith</A> |
| 107 | although this code was developed independantly. |
| 108 | <LI> <B>SRC_SINC_MEDIUM_QUALITY</B> - This is another bandlimited interpolator |
| 109 | much like the previous one. It has an SNR of 97dB and a bandwidth of 90%. |
| 110 | The speed of the conversion is much faster than the previous one. |
| 111 | <LI> <B>SRC_SINC_FASTEST</B> - This is the fastest bandlimited interpolator and |
| 112 | has an SNR of 97dB and a bandwidth of 80%. |
| 113 | <LI><B>SRC_ZERO_ORDER_HOLD</B> - A Zero Order Hold converter (interpolated value |
| 114 | is equal to the last value). The quality is poor but the conversion speed is |
| 115 | blindlingly fast. |
| 116 | <li><b>SRC_LINEAR</b> - A linear converter. Again the quality is poor, but the |
| 117 | conversion speed is blindingly fast. |
| 118 | </UL> |
| 119 | <P> |
| 120 | There are two functions that give either a (text string) name or description |
| 121 | for each converter: |
| 122 | </P> |
| 123 | <PRE> |
| 124 | const char *src_get_name (int converter_type) ; |
| 125 | const char *src_get_description (int converter_type) ; |
| 126 | </PRE> |
| 127 | <P> |
| 128 | The name will typically be a short string for use in a dialog box, while the |
| 129 | description string is longer. |
| 130 | </P> |
| 131 | <P> |
| 132 | Both of these functions return a NULL pointer if there is no converter for the |
| 133 | given <B>converter_type</B> value. |
| 134 | Since the converters have consecutive <B>converter_type</B> values, the caller |
| 135 | is easily able to figure out the number of converters at run time. |
| 136 | This enables a binary dynamically linked against an old version of the library |
| 137 | to know about converters from later versions of the library as they become |
| 138 | available. |
| 139 | </P> |
| 140 | |
| 141 | <A NAME="SRC_DATA"></A> |
| 142 | <H3><BR>SRC_DATA</H3> |
| 143 | <P> |
| 144 | Both the simple and the full featured versions of the API use the <B>SRC_DATA</B> |
| 145 | struct to pass audio and control data into the sample rate converter. |
| 146 | This struct is defined as: |
| 147 | </P> |
| 148 | <PRE> |
| 149 | typedef struct |
| 150 | { float *data_in, *data_out ; |
| 151 | |
| 152 | long input_frames, output_frames ; |
| 153 | long input_frames_used, output_frames_gen ; |
| 154 | |
| 155 | int end_of_input ; |
| 156 | |
| 157 | double src_ratio ; |
| 158 | } SRC_DATA ; |
| 159 | </PRE> |
| 160 | <P> |
| 161 | The <B>data_in</B> pointer is used to pass audio data into the converter while the |
| 162 | <B>data_out</B> pointer supplies the converter with an array to hold the converter's |
| 163 | output. |
| 164 | For a converter which has been configured for mulitchannel operation, these pointers |
| 165 | need to point to a single array of interleaved data. |
| 166 | </P> |
| 167 | <P> |
| 168 | The <B>input_frames</B> and <B>output_frames</B> fields supply the converter with |
| 169 | the lengths of the arrays (in frames) pointed to by the <B>data_in</B> and |
| 170 | <b>data_out</B> pointers respectively. |
| 171 | For monophinc data, these values would indicate the length of the arrays while |
| 172 | for multi channel data these values would be equal to the the length of the array |
| 173 | divided by the number of channels. |
| 174 | </P> |
| 175 | |
| 176 | <P> |
| 177 | The <B>end_of_input</B> field is only used when the sample rate converter is used |
| 178 | by calling the <B>src_process</B> function. |
| 179 | In this case it should be set to zero if more buffers are to be passed to the |
| 180 | converter and 1 if the current buffer is the last. |
| 181 | </P> |
| 182 | <P> |
| 183 | Finally, the <B>src_ratio</B> field specifies the conversion ratio defined as |
| 184 | the input sample rate divided by the output sample rate. |
| 185 | For a connected set of buffers, this value can be varies on each call to |
| 186 | <B>src_process</B> resulting in a time varying sample rate conversion |
| 187 | process. |
| 188 | For time varying sample rate conversions, the ratio will be linearly |
| 189 | interpolated between the <B>src_ratio</B> value of the previous call |
| 190 | to <B>src_process</B> and the value for the current call. |
| 191 | </P> |
| 192 | <P> |
| 193 | The <B>input_frames_used</B> and <B>output_frames_gen</B> fields are set by the |
| 194 | converter to inform the caller of the number of frames consumed from the |
| 195 | <B>data_in</B> array and the number of frames generated in the <B>data_out</B> |
| 196 | array respectively. |
| 197 | These values are for the current call to <B>src_process</B> only. |
| 198 | </P> |
| 199 | |
| 200 | <A NAME="Aux"></A> |
| 201 | <H3><BR>Auxillary Functions</H3> |
| 202 | <P> |
| 203 | There are four auxillary functions for converting arrays of float data |
| 204 | to and from short or int data. |
| 205 | These functions are defined as: |
| 206 | </P> |
| 207 | <PRE> |
| 208 | void src_short_to_float_array (const short *in, float *out, int len) ; |
| 209 | void src_float_to_short_array (const float *in, short *out, int len) ; |
| 210 | void src_int_to_float_array (const int *in, float *out, int len) ; |
| 211 | void src_float_to_int_array (const float *in, int *out, int len) ; |
| 212 | </PRE> |
| 213 | <P> |
| 214 | The float data is assumed to be in the range [-1.0, 1.0] and it is |
| 215 | automatically scaled on the conversion to and from float. |
| 216 | On the float to short/int conversion path, any data values which would overflow |
| 217 | the range of short/int data are clipped. |
| 218 | </P> |
| 219 | |
| 220 | </DIV> |
| 221 | </TD></TR> |
| 222 | </TABLE> |
| 223 | |
| 224 | </BODY> |
| 225 | </HTML> |
| 226 | |