cannam@126: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
cannam@126: <HTML>
cannam@126:
cannam@126: <HEAD>
cannam@126: <TITLE>
cannam@126: Secret Rabbit Code (aka libsamplerate)
cannam@126: </TITLE>
cannam@126: <META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
cannam@126: <META NAME="Version" CONTENT="libsamplerate-0.1.8">
cannam@126: <META NAME="Description" CONTENT="The Secret Rabbit Code Home Page">
cannam@126: <META NAME="Keywords" CONTENT="libsamplerate sound resample audio dsp Linux">
cannam@126: <LINK REL=StyleSheet HREF="SRC.css" TYPE="text/css" MEDIA="all">
cannam@126: </HEAD>
cannam@126:
cannam@126: <BODY TEXT="#FFFFFF" BGCOLOR="#000000" LINK="#FB1465" VLINK="#FB1465" ALINK="#FB1465">
cannam@126: <!-- pepper -->
cannam@126: <CENTER>
cannam@126: <IMG SRC="SRC.png" HEIGHT=100 WIDTH=760 ALT="SRC.png">
cannam@126: </CENTER>
cannam@126: <!-- pepper -->
cannam@126: <BR>
cannam@126: <!-- pepper -->
cannam@126: <TABLE ALIGN="center" WIDTH="98%">
cannam@126: <TR>
cannam@126: <TD VALIGN="top">
cannam@126: <BR>
cannam@126: <DIV CLASS="nav">
cannam@126: <BR>
cannam@126: <A HREF="index.html">Home</A><BR>
cannam@126: <A HREF="license.html">License</A><BR>
cannam@126: <A HREF="history.html">History</A><BR>
cannam@126: <A HREF="download.html">Download</A><BR>
cannam@126: <A HREF="quality.html">Quality</A><BR>
cannam@126: <A HREF="api.html">API</A><BR>
cannam@126: <A HREF="bugs.html">Bug Reporting</A><BR>
cannam@126: <A HREF="win32.html">On Win32</A><BR>
cannam@126: <A HREF="faq.html">FAQ</A><BR>
cannam@126: <A HREF="lists.html">Mailing Lists</A><BR>
cannam@126: <A HREF="ChangeLog">ChangeLog</A><BR>
cannam@126: <BR>
cannam@126: <DIV CLASS="block">
cannam@126: Author :<BR>Erik de Castro Lopo
cannam@126: <!-- pepper -->
cannam@126: <BR><BR>
cannam@126: <!-- pepper -->
cannam@126:
cannam@126: </DIV>
cannam@126: <IMG SRC=
cannam@126: "/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@126: HEIGHT=30 WIDTH=100 ALT="counter.gif">
cannam@126: </DIV>
cannam@126:
cannam@126: </TD>
cannam@126: <!-- pepper -->
cannam@126: <!-- ######################################################################## -->
cannam@126: <!-- pepper -->
cannam@126: <TD VALIGN="top">
cannam@126: <DIV CLASS="block">
cannam@126:
cannam@126: <H1><B>Frequently Asked Questions</B></H1>
cannam@126: <P>
cannam@126: <A HREF="#Q001">Q1 : Is it normal for the output of libsamplerate to be louder
cannam@126: than its input?</A><BR><BR>
cannam@126: <A HREF="#Q002">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?</A><BR><BR>
cannam@126: <A HREF="#Q003">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?</A><BR><BR>
cannam@126: <A HREF="#Q004">Q4 : If I ran src_simple (libsamplerate) on small chunks (160
cannam@126: frames) would that sound bad?</A><BR><BR>
cannam@126: <A HREF="#Q005">Q5 : I'm using libsamplerate but the high quality settings
cannam@126: sound worse than the SRC_LINEAR converter. Why?</A><BR><BR>
cannam@126: <A HREF="#Q006">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?</A><BR><BR>
cannam@126: <A HREF="#Q007">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?</A><BR><BR>
cannam@126: </P>
cannam@126: <HR>
cannam@126: <!-- ========================================================================= -->
cannam@126: <A NAME="Q001"></A>
cannam@126: <H2><BR><B>Q1 : Is it normal for the output of libsamplerate to be louder
cannam@126: than its input?</B></H2>
cannam@126: <P>
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: </P>
cannam@126: <P>
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: </P>
cannam@126: <P>
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: </P>
cannam@126:
cannam@126: <!-- pepper -->
cannam@126: <!-- ========================================================================= -->
cannam@126:
cannam@126: <a NAME="Q002"></a>
cannam@126: <h2><br><b>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?</b></h2>
cannam@126:
cannam@126: <p>
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: </p>
cannam@126:
cannam@126: <pre>
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: </pre>
cannam@126: <p>
cannam@126: This will automatically set the <b>SAMPLERATE_CFLAGS</b> and <b>SAMPLERATE_LIBS</b>
cannam@126: variables which can be used in Makefile.am or Makefile.in like this:
cannam@126: </p>
cannam@126: <pre>
cannam@126: SAMPLERATE_CFLAGS = @SAMPLERATE_CFLAGS@
cannam@126: SAMPLERATE_LIBS = @SAMPLERATE_LIBS@
cannam@126: </pre>
cannam@126:
cannam@126: <p>
cannam@126: If you install libsamplerate from source, you will probably need to set the
cannam@126: <b>PKG_CONFIG_PATH</b> environment variable's suggested at the end of the
cannam@126: libsamplerate configure process. For instance on my system I get this:
cannam@126: </p>
cannam@126: <pre>
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: </pre>
cannam@126:
cannam@126:
cannam@126: <!-- pepper -->
cannam@126: <!-- ========================================================================= -->
cannam@126: <A NAME="Q003"></A>
cannam@126: <H2><BR><B>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?</B></H2>
cannam@126: <P>
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: </P>
cannam@126: <P>
cannam@126: In order to resample correctly (ie using the <B>SRC_SINC_*</B> 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: </P>
cannam@126: <P>
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: </P>
cannam@126:
cannam@126: <!-- pepper -->
cannam@126: <!-- ========================================================================= -->
cannam@126: <A NAME="Q004"></A>
cannam@126: <H2><BR><B>Q4 : If I ran src_simple on small chunks (say 160 frames) would that
cannam@126: sound bad?</B></H2>
cannam@126: <P>
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: </P>
cannam@126: <P>
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: </P>
cannam@126:
cannam@126: <!-- pepper -->
cannam@126: <!-- ========================================================================= -->
cannam@126: <A NAME="Q005"></A>
cannam@126: <H2><BR><B>Q5 : I'm using libsamplerate but the high quality settings
cannam@126: sound worse than the SRC_LINEAR converter. Why?</B></H2>
cannam@126: <P>
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: </P>
cannam@126: <P>
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: </P>
cannam@126: <P>
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: </P>
cannam@126: <P>
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: <A HREF="api_misc.html#SRC_DATA">SRC_DATA</A>
cannam@126: struct.
cannam@126: Specifically:
cannam@126: </P>
cannam@126: <UL>
cannam@126: <LI> 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: <LI> 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: <LI> Check that you are updating the data_in and data_out pointers
cannam@126: correctly for each successive call.
cannam@126: </UL>
cannam@126: <P>
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: </P>
cannam@126: <P>
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: </P>
cannam@126:
cannam@126: <!-- pepper -->
cannam@126: <!-- ========================================================================= -->
cannam@126: <A NAME="Q006"></A>
cannam@126: <H2><BR><B>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?</B></H2>
cannam@126: <P>
cannam@126: The short answer is that there is a transport delay inside the converter itself.
cannam@126: Long answer follows.
cannam@126: </P>
cannam@126: <P>
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: </P>
cannam@126: <P>
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: </P>
cannam@126:
cannam@126: <!-- pepper -->
cannam@126: <!-- ========================================================================= -->
cannam@126: <A NAME="Q007"></A>
cannam@126: <H2><BR><B>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?</B></H2>
cannam@126: <P>
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: </P>
cannam@126: <P>
cannam@126: For the long answer, lets do come calculations.
cannam@126: Firstly, the <tt>src_ratio</tt> field is double precision floating point number
cannam@126: which has
cannam@126: <a href="http://en.wikipedia.org/wiki/Double_precision">
cannam@126: 53 bits of precision</a>.
cannam@126: </P>
cannam@126: <P>
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: </P>
cannam@126: <P>
cannam@126: Now if for example our output sample rate is 96kHz then
cannam@126: </P>
cannam@126: <pre>
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: </pre>
cannam@126: <P>
cannam@126: So, after 1486 years, the input will be wrong by more than half of one sampling
cannam@126: period.
cannam@126: </P>
cannam@126: <p>
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: <a href="http://www.ieee-uffc.org/freqcontrol/quartz/vig/vigcomp.htm">
cannam@126: this web site</a>,
cannam@126: the accuracy of standard crystal oscillators (XO, TCXO, OCXO) is at best
cannam@126: 1 in 100 million.
cannam@126: The <tt>src_ratio</tt> 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 <tt>src_ratio</tt> being a floating point number will be
cannam@126: completely swamped by sampling inaccuracies.
cannam@126: </p>
cannam@126:
cannam@126: <!-- <A HREF="mailto:aldel@mega-nerd.com">For the spam bots</A> -->
cannam@126:
cannam@126: </DIV>
cannam@126: </TD></TR>
cannam@126: </TABLE>
cannam@126:
cannam@126: </BODY>
cannam@126: </HTML>
cannam@126: