Mercurial > hg > sv-dependency-builds

annotate src/libsamplerate-0.1.8/doc/faq.html @ 169:223a55898ab9 tip default

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add null config files
author Chris Cannam <cannam@all-day-breakfast.com>
date Mon, 02 Mar 2020 14:03:47 +0000
parents 545efbb81310
children
rev   line source
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 <A HREF="license.html">License</A><BR>
cannam@85 31 <A HREF="history.html">History</A><BR>
cannam@85 32 <A HREF="download.html">Download</A><BR>
cannam@85 33 <A HREF="quality.html">Quality</A><BR>
cannam@85 34 <A HREF="api.html">API</A><BR>
cannam@85 35 <A HREF="bugs.html">Bug Reporting</A><BR>
cannam@85 36 <A HREF="win32.html">On Win32</A><BR>
cannam@85 37 <A HREF="faq.html">FAQ</A><BR>
cannam@85 38 <A HREF="lists.html">Mailing Lists</A><BR>
cannam@85 39 <A HREF="ChangeLog">ChangeLog</A><BR>
cannam@85 40 <BR>
cannam@85 41 <DIV CLASS="block">
cannam@85 42 Author :<BR>Erik de Castro Lopo
cannam@85 43 <!-- pepper -->
cannam@85 44 <BR><BR>
cannam@85 45 <!-- pepper -->
cannam@85 46
cannam@85 47 </DIV>
cannam@85 48 <IMG SRC=
cannam@85 49 "/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 50 HEIGHT=30 WIDTH=100 ALT="counter.gif">
cannam@85 51 </DIV>
cannam@85 52
cannam@85 53 </TD>
cannam@85 54 <!-- pepper -->
cannam@85 55 <!-- ######################################################################## -->
cannam@85 56 <!-- pepper -->
cannam@85 57 <TD VALIGN="top">
cannam@85 58 <DIV CLASS="block">
cannam@85 59
cannam@85 60 <H1><B>Frequently Asked Questions</B></H1>
cannam@85 61 <P>
cannam@85 62 <A HREF="#Q001">Q1 : Is it normal for the output of libsamplerate to be louder
cannam@85 63 than its input?</A><BR><BR>
cannam@85 64 <A HREF="#Q002">Q2 : On Unix/Linux/MacOSX, what is the best way of detecting
cannam@85 65 the presence and location of libsamplerate and its header file using
cannam@85 66 autoconf?</A><BR><BR>
cannam@85 67 <A HREF="#Q003">Q3 : If I upsample and downsample to the original rate, for
cannam@85 68 example 44.1->96->44.1, do I get an identical signal as the one before the
cannam@85 69 up/down resampling?</A><BR><BR>
cannam@85 70 <A HREF="#Q004">Q4 : If I ran src_simple (libsamplerate) on small chunks (160
cannam@85 71 frames) would that sound bad?</A><BR><BR>
cannam@85 72 <A HREF="#Q005">Q5 : I'm using libsamplerate but the high quality settings
cannam@85 73 sound worse than the SRC_LINEAR converter. Why?</A><BR><BR>
cannam@85 74 <A HREF="#Q006">Q6 : I'm use the SRC_SINC_* converters and up-sampling by a ratio of
cannam@85 75 2. I reset the converter and put in 1000 samples and I expect to get 2000
cannam@85 76 samples out, but I'm getting less than that. Why?</A><BR><BR>
cannam@85 77 <A HREF="#Q007">Q7 : I have input and output sample rates that are integer
cannam@85 78 values, but the API wants me to divide one by the other and put the result
cannam@85 79 in a floating point number. Won't this case problems for long running
cannam@85 80 conversions?</A><BR><BR>
cannam@85 81 </P>
cannam@85 82 <HR>
cannam@85 83 <!-- ========================================================================= -->
cannam@85 84 <A NAME="Q001"></A>
cannam@85 85 <H2><BR><B>Q1 : Is it normal for the output of libsamplerate to be louder
cannam@85 86 than its input?</B></H2>
cannam@85 87 <P>
cannam@85 88 The output of libsamplerate will be roughly the same volume as the input.
cannam@85 89 However, even if the input is strictly in the range (-1.0, 1.0), it is still
cannam@85 90 possible for the output to contain peak values outside this range.
cannam@85 91 </P>
cannam@85 92 <P>
cannam@85 93 Consider four consecutive samples of [0.5 0.999 0.999 0.5].
cannam@85 94 If we are up sampling by a factor of two we need to insert samples between
cannam@85 95 each of the existing samples.
cannam@85 96 Its pretty obvious then, that the sample between the two 0.999 values should
cannam@85 97 and will be bigger than 0.999.
cannam@85 98 </P>
cannam@85 99 <P>
cannam@85 100 This means that anyone using libsamplerate should normalize its output before
cannam@85 101 doing things like saving the audio to a 16 bit WAV file.
cannam@85 102 </P>
cannam@85 103
cannam@85 104 <!-- pepper -->
cannam@85 105 <!-- ========================================================================= -->
cannam@85 106
cannam@85 107 <a NAME="Q002"></a>
cannam@85 108 <h2><br><b>Q2 : On Unix/Linux/MacOSX, what is the best way of detecting
cannam@85 109 the presence and location of libsamplerate and its header file using
cannam@85 110 autoconf?</b></h2>
cannam@85 111
cannam@85 112 <p>
cannam@85 113 libsamplerate uses the pkg-config (man pkg-config) method of registering itself
cannam@85 114 with the host system.
cannam@85 115 The best way of detecting its presence is using something like this in configure.ac
cannam@85 116 (or configure.in):
cannam@85 117 </p>
cannam@85 118
cannam@85 119 <pre>
cannam@85 120 PKG_CHECK_MODULES(SAMPLERATE, samplerate >= 0.1.3,
cannam@85 121 ac_cv_samplerate=1, ac_cv_samplerate=0)
cannam@85 122
cannam@85 123 AC_DEFINE_UNQUOTED([HAVE_SAMPLERATE],${ac_cv_samplerate},
cannam@85 124 [Set to 1 if you have libsamplerate.])
cannam@85 125
cannam@85 126 AC_SUBST(SAMPLERATE_CFLAGS)
cannam@85 127 AC_SUBST(SAMPLERATE_LIBS)
cannam@85 128 </pre>
cannam@85 129 <p>
cannam@85 130 This will automatically set the <b>SAMPLERATE_CFLAGS</b> and <b>SAMPLERATE_LIBS</b>
cannam@85 131 variables which can be used in Makefile.am or Makefile.in like this:
cannam@85 132 </p>
cannam@85 133 <pre>
cannam@85 134 SAMPLERATE_CFLAGS = @SAMPLERATE_CFLAGS@
cannam@85 135 SAMPLERATE_LIBS = @SAMPLERATE_LIBS@
cannam@85 136 </pre>
cannam@85 137
cannam@85 138 <p>
cannam@85 139 If you install libsamplerate from source, you will probably need to set the
cannam@85 140 <b>PKG_CONFIG_PATH</b> environment variable's suggested at the end of the
cannam@85 141 libsamplerate configure process. For instance on my system I get this:
cannam@85 142 </p>
cannam@85 143 <pre>
cannam@85 144 -=-=-=-=-=-=-=-=-=-= Configuration Complete =-=-=-=-=-=-=-=-=-=-=-
cannam@85 145
cannam@85 146 Configuration summary :
cannam@85 147
cannam@85 148 Version : ..................... 0.1.3
cannam@85 149 Enable debugging : ............ no
cannam@85 150
cannam@85 151 Tools :
cannam@85 152
cannam@85 153 Compiler is GCC : ............. yes
cannam@85 154 GCC major version : ........... 3
cannam@85 155
cannam@85 156 Extra tools required for testing and examples :
cannam@85 157
cannam@85 158 Have FFTW : ................... yes
cannam@85 159 Have libsndfile : ............. yes
cannam@85 160 Have libefence : .............. no
cannam@85 161
cannam@85 162 Installation directories :
cannam@85 163
cannam@85 164 Library directory : ........... /usr/local/lib
cannam@85 165 Program directory : ........... /usr/local/bin
cannam@85 166 Pkgconfig directory : ......... /usr/local/lib/pkgconfig
cannam@85 167 </pre>
cannam@85 168
cannam@85 169
cannam@85 170 <!-- pepper -->
cannam@85 171 <!-- ========================================================================= -->
cannam@85 172 <A NAME="Q003"></A>
cannam@85 173 <H2><BR><B>Q3 : If I upsample and downsample to the original rate, for
cannam@85 174 example 44.1->96->44.1, do I get an identical signal as the one before the
cannam@85 175 up/down resampling?</B></H2>
cannam@85 176 <P>
cannam@85 177 The short answer is that for the general case, no, you don't.
cannam@85 178 The long answer is that for some signals, with some converters, you will
cannam@85 179 get very, very close.
cannam@85 180 </P>
cannam@85 181 <P>
cannam@85 182 In order to resample correctly (ie using the <B>SRC_SINC_*</B> converters),
cannam@85 183 filtering needs to be applied, regardless of whether its upsampling or
cannam@85 184 downsampling.
cannam@85 185 This filter needs to attenuate all frequencies above 0.5 times the minimum of
cannam@85 186 the source and destination sample rate (call this fshmin).
cannam@85 187 Since the filter needed to achieve full attenuation at this point, it has to
cannam@85 188 start rolling off a some frequency below this point.
cannam@85 189 It is this rolloff of the very highest frequencies which causes some of the
cannam@85 190 loss.
cannam@85 191 </P>
cannam@85 192 <P>
cannam@85 193 The other factor is that the filter itself can introduce transient artifacts
cannam@85 194 which causes the output to be different to the input.
cannam@85 195 </P>
cannam@85 196
cannam@85 197 <!-- pepper -->
cannam@85 198 <!-- ========================================================================= -->
cannam@85 199 <A NAME="Q004"></A>
cannam@85 200 <H2><BR><B>Q4 : If I ran src_simple on small chunks (say 160 frames) would that
cannam@85 201 sound bad?</B></H2>
cannam@85 202 <P>
cannam@85 203 Well if you are after odd sound effects, it might sound OK.
cannam@85 204 If you are after high quality sample rate conversion you will be disappointed.
cannam@85 205 </P>
cannam@85 206 <P>
cannam@85 207 The src_simple() was designed to provide a simple to use interface for people
cannam@85 208 who wanted to do sample rate conversion on say, a whole file all at once.
cannam@85 209 </P>
cannam@85 210
cannam@85 211 <!-- pepper -->
cannam@85 212 <!-- ========================================================================= -->
cannam@85 213 <A NAME="Q005"></A>
cannam@85 214 <H2><BR><B>Q5 : I'm using libsamplerate but the high quality settings
cannam@85 215 sound worse than the SRC_LINEAR converter. Why?</B></H2>
cannam@85 216 <P>
cannam@85 217 There are two possible problems.
cannam@85 218 Firstly, if you are using the src_simple() function on successive blocks
cannam@85 219 of a stream of samples, you will get bad results. The src_simple() function
cannam@85 220 is designed for use on a whole sound file, all at once, not on contiguous
cannam@85 221 segments of the same sound file.
cannam@85 222 To fix the problem, you need to move to the src_process() API or the callback
cannam@85 223 based API.
cannam@85 224 </P>
cannam@85 225 <P>
cannam@85 226 If you are already using the src_process() API or the callback based API and
cannam@85 227 the high quality settings sound worse than SRC_LINEAR, then you have other
cannam@85 228 problems.
cannam@85 229 Read on for more debugging hints.
cannam@85 230 </P>
cannam@85 231 <P>
cannam@85 232 All of the higher quality converters need to keep state while doing conversions
cannam@85 233 on segments of a large chunk of audio.
cannam@85 234 This state information is kept inside the private data pointed to by the
cannam@85 235 SRC_STATE pointer returned by the src_new() function.
cannam@85 236 This means, that when you want to start doing sample rate conversion on a
cannam@85 237 stream of data, you should call src_new() to get a new SRC_STATE pointer
cannam@85 238 (or alternatively, call src_reset() on an existing SRC_STATE pointer).
cannam@85 239 You should then pass this SRC_STATE pointer to the src_process() function
cannam@85 240 with each new block of audio data.
cannam@85 241 When you have completed the conversion, you can then call src_delete() on
cannam@85 242 the SRC_STATE pointer.
cannam@85 243 </P>
cannam@85 244 <P>
cannam@85 245 If you are doing all of the above correctly, you need to examine your usage
cannam@85 246 of the values passed to src_process() in the
cannam@85 247 <A HREF="api_misc.html#SRC_DATA">SRC_DATA</A>
cannam@85 248 struct.
cannam@85 249 Specifically:
cannam@85 250 </P>
cannam@85 251 <UL>
cannam@85 252 <LI> Check that input_frames and output_frames fields are being set in
cannam@85 253 terms of frames (number of sample values times channels) instead
cannam@85 254 of just the number of samples.
cannam@85 255 <LI> Check that you are using the return values input_frames_used and
cannam@85 256 output_frames_gen to update your source and destination pointers
cannam@85 257 correctly.
cannam@85 258 <LI> Check that you are updating the data_in and data_out pointers
cannam@85 259 correctly for each successive call.
cannam@85 260 </UL>
cannam@85 261 <P>
cannam@85 262 While doing the above, it is probably useful to compare what you are doing to
cannam@85 263 what is done in the example programs in the examples/ directory of the source
cannam@85 264 code tarball.
cannam@85 265 </P>
cannam@85 266 <P>
cannam@85 267 If you have done all of the above and are still having problems then its
cannam@85 268 probably time to email the author with the smallest chunk of code that
cannam@85 269 adequately demonstrates your problem.
cannam@85 270 This chunk should not need to be any more than 100 lines of code.
cannam@85 271 </P>
cannam@85 272
cannam@85 273 <!-- pepper -->
cannam@85 274 <!-- ========================================================================= -->
cannam@85 275 <A NAME="Q006"></A>
cannam@85 276 <H2><BR><B>Q6 : I'm use the SRC_SINC_* converters and up-sampling by a ratio of
cannam@85 277 2. I reset the converter and put in 1000 samples and I expect to get 2000
cannam@85 278 samples out, but I'm getting less than that. Why?</B></H2>
cannam@85 279 <P>
cannam@85 280 The short answer is that there is a transport delay inside the converter itself.
cannam@85 281 Long answer follows.
cannam@85 282 </P>
cannam@85 283 <P>
cannam@85 284 By way of example, the first time you call src_process() you might only get 1900
cannam@85 285 samples out.
cannam@85 286 However, after that first call all subsequent calls will probably get you about
cannam@85 287 2000 samples out for every 1000 samples you put in.
cannam@85 288 </P>
cannam@85 289 <P>
cannam@85 290 The main problems people have with this transport delay is that they need to read
cannam@85 291 out an exact number of samples and the transport delay scews this up.
cannam@85 292 The best way to overcome this problem is to always supply more samples on the
cannam@85 293 input than is actually needed to create the required number of output samples.
cannam@85 294 With reference to the example above, if you always supply 1500 samples at the
cannam@85 295 input, you will always get 2000 samples at the output.
cannam@85 296 You will always need to keep track of the number of input frames used on each
cannam@85 297 call to src_process() and deal with these values appropriately.
cannam@85 298 </P>
cannam@85 299
cannam@85 300 <!-- pepper -->
cannam@85 301 <!-- ========================================================================= -->
cannam@85 302 <A NAME="Q007"></A>
cannam@85 303 <H2><BR><B>Q7 : I have input and output sample rates that are integer
cannam@85 304 values, but the API wants me to divide one by the other and put the result
cannam@85 305 in a floating point number. Won't this case problems for long running
cannam@85 306 conversions?</B></H2>
cannam@85 307 <P>
cannam@85 308 The short answer is no, the precision of the ratio is many orders of magnitude
cannam@85 309 more than is really needed.
cannam@85 310 </P>
cannam@85 311 <P>
cannam@85 312 For the long answer, lets do come calculations.
cannam@85 313 Firstly, the <tt>src_ratio</tt> field is double precision floating point number
cannam@85 314 which has
cannam@85 315 <a href="http://en.wikipedia.org/wiki/Double_precision">
cannam@85 316 53 bits of precision</a>.
cannam@85 317 </P>
cannam@85 318 <P>
cannam@85 319 That means that the maximum error in your ratio converted to a double is one
cannam@85 320 bit in 2^53 which means the the double float value would be wrong by one sample
cannam@85 321 after 9007199254740992 samples have passed or wrong by more than half a sample
cannam@85 322 wrong after half that many (4503599627370496 samples) have passed.
cannam@85 323 </P>
cannam@85 324 <P>
cannam@85 325 Now if for example our output sample rate is 96kHz then
cannam@85 326 </P>
cannam@85 327 <pre>
cannam@85 328 4503599627370496 samples at 96kHz is 46912496118 seconds
cannam@85 329 46912496118 seconds is 781874935 minutes
cannam@85 330 781874935 minutes is 13031248 hours
cannam@85 331 13031248 hours is 542968 days
cannam@85 332 542968 days is 1486 years
cannam@85 333 </pre>
cannam@85 334 <P>
cannam@85 335 So, after 1486 years, the input will be wrong by more than half of one sampling
cannam@85 336 period.
cannam@85 337 </P>
cannam@85 338 <p>
cannam@85 339 All this assumes that the crystal oscillators uses to sample the audio stream
cannam@85 340 is perfect.
cannam@85 341 This is not the case.
cannam@85 342 According to
cannam@85 343 <a href="http://www.ieee-uffc.org/freqcontrol/quartz/vig/vigcomp.htm">
cannam@85 344 this web site</a>,
cannam@85 345 the accuracy of standard crystal oscillators (XO, TCXO, OCXO) is at best
cannam@85 346 1 in 100 million.
cannam@85 347 The <tt>src_ratio</tt> is therefore 45035996 times more accurate than the
cannam@85 348 crystal clock source used to sample the original audio signal and any potential
cannam@85 349 problem with the <tt>src_ratio</tt> being a floating point number will be
cannam@85 350 completely swamped by sampling inaccuracies.
cannam@85 351 </p>
cannam@85 352
cannam@85 353 <!-- <A HREF="mailto:aldel@mega-nerd.com">For the spam bots</A> -->
cannam@85 354
cannam@85 355 </DIV>
cannam@85 356 </TD></TR>
cannam@85 357 </TABLE>
cannam@85 358
cannam@85 359 </BODY>
cannam@85 360 </HTML>
cannam@85 361