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