]>
Commit | Line | Data |
---|---|---|
8529da43 MG |
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 |