cannam@126: cannam@126: cannam@126: cannam@126: cannam@126: cannam@126: Secret Rabbit Code (aka libsamplerate) cannam@126: cannam@126: cannam@126: cannam@126: cannam@126: cannam@126: cannam@126: cannam@126: cannam@126: cannam@126: cannam@126:
cannam@126: SRC.png cannam@126:
cannam@126: cannam@126:
cannam@126: cannam@126: cannam@126: cannam@126: cannam@126: cannam@126: cannam@126: cannam@126: cannam@126:
cannam@126:
cannam@126:
cannam@126:
cannam@126: Home
cannam@126: License
cannam@126: History
cannam@126: Download
cannam@126: Quality
cannam@126: API
cannam@126: Bug Reporting
cannam@126: On Win32
cannam@126: FAQ
cannam@126: Mailing Lists
cannam@126: ChangeLog
cannam@126:
cannam@126:
cannam@126: Author :
Erik de Castro Lopo cannam@126: cannam@126:

cannam@126: cannam@126: cannam@126:
cannam@126: counter.gif cannam@126:
cannam@126: cannam@126: 		cannam@126:
cannam@126: cannam@126:

Frequently Asked Questions

cannam@126:

cannam@126: Q1 : Is it normal for the output of libsamplerate to be louder cannam@126: than its input?

cannam@126: Q2 : On Unix/Linux/MacOSX, what is the best way of detecting cannam@126: the presence and location of libsamplerate and its header file using cannam@126: autoconf?

cannam@126: Q3 : If I upsample and downsample to the original rate, for cannam@126: example 44.1->96->44.1, do I get an identical signal as the one before the cannam@126: up/down resampling?

cannam@126: Q4 : If I ran src_simple (libsamplerate) on small chunks (160 cannam@126: frames) would that sound bad?

cannam@126: Q5 : I'm using libsamplerate but the high quality settings cannam@126: sound worse than the SRC_LINEAR converter. Why?

cannam@126: Q6 : I'm use the SRC_SINC_* converters and up-sampling by a ratio of cannam@126: 2. I reset the converter and put in 1000 samples and I expect to get 2000 cannam@126: samples out, but I'm getting less than that. Why?

cannam@126: Q7 : I have input and output sample rates that are integer cannam@126: values, but the API wants me to divide one by the other and put the result cannam@126: in a floating point number. Won't this case problems for long running cannam@126: conversions?

cannam@126:

cannam@126:
cannam@126: cannam@126: cannam@126:


Q1 : Is it normal for the output of libsamplerate to be louder cannam@126: than its input?

cannam@126:

cannam@126: The output of libsamplerate will be roughly the same volume as the input. cannam@126: However, even if the input is strictly in the range (-1.0, 1.0), it is still cannam@126: possible for the output to contain peak values outside this range. cannam@126:

cannam@126:

cannam@126: Consider four consecutive samples of [0.5 0.999 0.999 0.5]. cannam@126: If we are up sampling by a factor of two we need to insert samples between cannam@126: each of the existing samples. cannam@126: Its pretty obvious then, that the sample between the two 0.999 values should cannam@126: and will be bigger than 0.999. cannam@126:

cannam@126:

cannam@126: This means that anyone using libsamplerate should normalize its output before cannam@126: doing things like saving the audio to a 16 bit WAV file. cannam@126:

cannam@126: cannam@126: cannam@126: cannam@126: cannam@126: cannam@126:


Q2 : On Unix/Linux/MacOSX, what is the best way of detecting cannam@126: the presence and location of libsamplerate and its header file using cannam@126: autoconf?

cannam@126: cannam@126:

cannam@126: libsamplerate uses the pkg-config (man pkg-config) method of registering itself cannam@126: with the host system. cannam@126: The best way of detecting its presence is using something like this in configure.ac cannam@126: (or configure.in): cannam@126:

cannam@126: cannam@126: 
cannam@126:     PKG_CHECK_MODULES(SAMPLERATE, samplerate >= 0.1.3,
cannam@126:             ac_cv_samplerate=1, ac_cv_samplerate=0)
cannam@126: 
cannam@126:     AC_DEFINE_UNQUOTED([HAVE_SAMPLERATE],${ac_cv_samplerate},
cannam@126:             [Set to 1 if you have libsamplerate.])
cannam@126: 
cannam@126:     AC_SUBST(SAMPLERATE_CFLAGS)
cannam@126:     AC_SUBST(SAMPLERATE_LIBS)
cannam@126:
cannam@126:

cannam@126: This will automatically set the SAMPLERATE_CFLAGS and SAMPLERATE_LIBS cannam@126: variables which can be used in Makefile.am or Makefile.in like this: cannam@126:

cannam@126: 
cannam@126:         SAMPLERATE_CFLAGS = @SAMPLERATE_CFLAGS@
cannam@126:         SAMPLERATE_LIBS = @SAMPLERATE_LIBS@
cannam@126:
cannam@126: cannam@126:

cannam@126: If you install libsamplerate from source, you will probably need to set the cannam@126: PKG_CONFIG_PATH environment variable's suggested at the end of the cannam@126: libsamplerate configure process. For instance on my system I get this: cannam@126:

cannam@126: 
cannam@126:     -=-=-=-=-=-=-=-=-=-= Configuration Complete =-=-=-=-=-=-=-=-=-=-=-
cannam@126: 
cannam@126:       Configuration summary :
cannam@126: 
cannam@126:         Version : ..................... 0.1.3
cannam@126:         Enable debugging : ............ no
cannam@126: 
cannam@126:       Tools :
cannam@126: 
cannam@126:         Compiler is GCC : ............. yes
cannam@126:         GCC major version : ........... 3
cannam@126: 
cannam@126:       Extra tools required for testing and examples :
cannam@126: 
cannam@126:         Have FFTW : ................... yes
cannam@126:         Have libsndfile : ............. yes
cannam@126:         Have libefence : .............. no
cannam@126: 
cannam@126:       Installation directories :
cannam@126: 
cannam@126:         Library directory : ........... /usr/local/lib
cannam@126:         Program directory : ........... /usr/local/bin
cannam@126:         Pkgconfig directory : ......... /usr/local/lib/pkgconfig
cannam@126:
cannam@126: cannam@126: cannam@126: cannam@126: cannam@126: cannam@126:


Q3 : If I upsample and downsample to the original rate, for cannam@126: example 44.1->96->44.1, do I get an identical signal as the one before the cannam@126: up/down resampling?

cannam@126:

cannam@126: The short answer is that for the general case, no, you don't. cannam@126: The long answer is that for some signals, with some converters, you will cannam@126: get very, very close. cannam@126:

cannam@126:

cannam@126: In order to resample correctly (ie using the SRC_SINC_* converters), cannam@126: filtering needs to be applied, regardless of whether its upsampling or cannam@126: downsampling. cannam@126: This filter needs to attenuate all frequencies above 0.5 times the minimum of cannam@126: the source and destination sample rate (call this fshmin). cannam@126: Since the filter needed to achieve full attenuation at this point, it has to cannam@126: start rolling off a some frequency below this point. cannam@126: It is this rolloff of the very highest frequencies which causes some of the cannam@126: loss. cannam@126:

cannam@126:

cannam@126: The other factor is that the filter itself can introduce transient artifacts cannam@126: which causes the output to be different to the input. cannam@126:

cannam@126: cannam@126: cannam@126: cannam@126: cannam@126:


Q4 : If I ran src_simple on small chunks (say 160 frames) would that cannam@126: sound bad?

cannam@126:

cannam@126: Well if you are after odd sound effects, it might sound OK. cannam@126: If you are after high quality sample rate conversion you will be disappointed. cannam@126:

cannam@126:

cannam@126: The src_simple() was designed to provide a simple to use interface for people cannam@126: who wanted to do sample rate conversion on say, a whole file all at once. cannam@126:

cannam@126: cannam@126: cannam@126: cannam@126: cannam@126:


Q5 : I'm using libsamplerate but the high quality settings cannam@126: sound worse than the SRC_LINEAR converter. Why?

cannam@126:

cannam@126: There are two possible problems. cannam@126: Firstly, if you are using the src_simple() function on successive blocks cannam@126: of a stream of samples, you will get bad results. The src_simple() function cannam@126: is designed for use on a whole sound file, all at once, not on contiguous cannam@126: segments of the same sound file. cannam@126: To fix the problem, you need to move to the src_process() API or the callback cannam@126: based API. cannam@126:

cannam@126:

cannam@126: If you are already using the src_process() API or the callback based API and cannam@126: the high quality settings sound worse than SRC_LINEAR, then you have other cannam@126: problems. cannam@126: Read on for more debugging hints. cannam@126:

cannam@126:

cannam@126: All of the higher quality converters need to keep state while doing conversions cannam@126: on segments of a large chunk of audio. cannam@126: This state information is kept inside the private data pointed to by the cannam@126: SRC_STATE pointer returned by the src_new() function. cannam@126: This means, that when you want to start doing sample rate conversion on a cannam@126: stream of data, you should call src_new() to get a new SRC_STATE pointer cannam@126: (or alternatively, call src_reset() on an existing SRC_STATE pointer). cannam@126: You should then pass this SRC_STATE pointer to the src_process() function cannam@126: with each new block of audio data. cannam@126: When you have completed the conversion, you can then call src_delete() on cannam@126: the SRC_STATE pointer. cannam@126:

cannam@126:

cannam@126: If you are doing all of the above correctly, you need to examine your usage cannam@126: of the values passed to src_process() in the cannam@126: SRC_DATA cannam@126: struct. cannam@126: Specifically: cannam@126:

cannam@126:
    cannam@126:
  • Check that input_frames and output_frames fields are being set in cannam@126: terms of frames (number of sample values times channels) instead cannam@126: of just the number of samples. cannam@126:
  • Check that you are using the return values input_frames_used and cannam@126: output_frames_gen to update your source and destination pointers cannam@126: correctly. cannam@126:
  • Check that you are updating the data_in and data_out pointers cannam@126: correctly for each successive call. cannam@126:
cannam@126:

cannam@126: While doing the above, it is probably useful to compare what you are doing to cannam@126: what is done in the example programs in the examples/ directory of the source cannam@126: code tarball. cannam@126:

cannam@126:

cannam@126: If you have done all of the above and are still having problems then its cannam@126: probably time to email the author with the smallest chunk of code that cannam@126: adequately demonstrates your problem. cannam@126: This chunk should not need to be any more than 100 lines of code. cannam@126:

cannam@126: cannam@126: cannam@126: cannam@126: cannam@126:


Q6 : I'm use the SRC_SINC_* converters and up-sampling by a ratio of cannam@126: 2. I reset the converter and put in 1000 samples and I expect to get 2000 cannam@126: samples out, but I'm getting less than that. Why?

cannam@126:

cannam@126: The short answer is that there is a transport delay inside the converter itself. cannam@126: Long answer follows. cannam@126:

cannam@126:

cannam@126: By way of example, the first time you call src_process() you might only get 1900 cannam@126: samples out. cannam@126: However, after that first call all subsequent calls will probably get you about cannam@126: 2000 samples out for every 1000 samples you put in. cannam@126:

cannam@126:

cannam@126: The main problems people have with this transport delay is that they need to read cannam@126: out an exact number of samples and the transport delay scews this up. cannam@126: The best way to overcome this problem is to always supply more samples on the cannam@126: input than is actually needed to create the required number of output samples. cannam@126: With reference to the example above, if you always supply 1500 samples at the cannam@126: input, you will always get 2000 samples at the output. cannam@126: You will always need to keep track of the number of input frames used on each cannam@126: call to src_process() and deal with these values appropriately. cannam@126:

cannam@126: cannam@126: cannam@126: cannam@126: cannam@126:


Q7 : I have input and output sample rates that are integer cannam@126: values, but the API wants me to divide one by the other and put the result cannam@126: in a floating point number. Won't this case problems for long running cannam@126: conversions?

cannam@126:

cannam@126: The short answer is no, the precision of the ratio is many orders of magnitude cannam@126: more than is really needed. cannam@126:

cannam@126:

cannam@126: For the long answer, lets do come calculations. cannam@126: Firstly, the src_ratio field is double precision floating point number cannam@126: which has cannam@126: cannam@126: 53 bits of precision. cannam@126:

cannam@126:

cannam@126: That means that the maximum error in your ratio converted to a double is one cannam@126: bit in 2^53 which means the the double float value would be wrong by one sample cannam@126: after 9007199254740992 samples have passed or wrong by more than half a sample cannam@126: wrong after half that many (4503599627370496 samples) have passed. cannam@126:

cannam@126:

cannam@126: Now if for example our output sample rate is 96kHz then cannam@126:

cannam@126: 
cannam@126:     4503599627370496 samples at 96kHz is 46912496118 seconds
cannam@126:     46912496118 seconds is 781874935 minutes
cannam@126:     781874935 minutes is 13031248 hours
cannam@126:     13031248 hours is 542968 days
cannam@126:     542968 days is 1486 years
cannam@126:
cannam@126:

cannam@126: So, after 1486 years, the input will be wrong by more than half of one sampling cannam@126: period. cannam@126:

cannam@126:

cannam@126: All this assumes that the crystal oscillators uses to sample the audio stream cannam@126: is perfect. cannam@126: This is not the case. cannam@126: According to cannam@126: cannam@126: this web site, cannam@126: the accuracy of standard crystal oscillators (XO, TCXO, OCXO) is at best cannam@126: 1 in 100 million. cannam@126: The src_ratio is therefore 45035996 times more accurate than the cannam@126: crystal clock source used to sample the original audio signal and any potential cannam@126: problem with the src_ratio being a floating point number will be cannam@126: completely swamped by sampling inaccuracies. cannam@126:

cannam@126: cannam@126: cannam@126: cannam@126:
cannam@126:
cannam@126: cannam@126: cannam@126: cannam@126: