--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<HTML>
+
+<HEAD>
+ <TITLE>
+ Secret Rabbit Code (aka libsamplerate)
+ </TITLE>
+ <META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
+ <META NAME="Version" CONTENT="libsamplerate-0.1.8">
+ <META NAME="Description" CONTENT="The Secret Rabbit Code Home Page">
+ <META NAME="Keywords" CONTENT="libsamplerate sound resample audio dsp Linux">
+ <LINK REL=StyleSheet HREF="SRC.css" TYPE="text/css" MEDIA="all">
+</HEAD>
+
+<BODY TEXT="#FFFFFF" BGCOLOR="#000000" LINK="#FB1465" VLINK="#FB1465" ALINK="#FB1465">
+<!-- pepper -->
+<CENTER>
+ <IMG SRC="SRC.png" HEIGHT=100 WIDTH=760 ALT="SRC.png">
+</CENTER>
+<!-- pepper -->
+<BR>
+<!-- pepper -->
+<TABLE ALIGN="center" WIDTH="98%">
+<TR>
+<TD VALIGN="top">
+<BR>
+<DIV CLASS="nav">
+ <BR>
+ <A HREF="index.html">Home</A><BR>
+ <BR>
+ <A HREF="api_simple.html">Simple API</A><BR>
+ <A HREF="api_full.html">Full API</A><BR>
+ <A HREF="api_misc.html#ErrorReporting">Error Handling</A><BR>
+ <A HREF="api_misc.html">Miscellaneous</A><BR>
+<BR>
+<DIV CLASS="block">
+Author :<BR>Erik de Castro Lopo
+<!-- pepper -->
+<BR><BR>
+<!-- pepper -->
+
+</DIV>
+ <IMG SRC=
+ "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_api.dat"
+ HEIGHT=30 WIDTH=100 ALT="counter.gif">
+</DIV>
+
+</TD>
+<!-- pepper -->
+<!-- ######################################################################## -->
+<!-- pepper -->
+<TD VALIGN="top">
+<DIV CLASS="block">
+
+<H1><B>Miscellaneous API Documentation</B></H1>
+<A NAME="ErrorReporting"></A>
+<H3><BR>Error Reporting</H3>
+<P>
+Most of the API functions either return an integer error (ie <B>src_simple</B>
+and <B>src_process</B>) or return an integer error value via an int pointer
+parameter (<B>src_new</B>).
+These integer error values can be converted into a human readable text strings by
+calling the function:
+</P>
+<PRE>
+ const char* src_strerror (int error) ;
+</PRE>
+<P>
+which will return an error string for valid error numbers, the string "No Error"
+for an error value of zero or a NULL pointer if no error message has been defined
+for that error value.
+</P>
+
+<A NAME="Converters"></A>
+<H3><BR>Converters</H3>
+<P>
+Secret Rabbit Code has a number of different converters which can be selected
+using the <B>converter_type</B> parameter when calling <B>src_simple</B> or
+<b>src_new</B>.
+Currently, the five converters available are:
+</P>
+<PRE>
+ enum
+ {
+ SRC_SINC_BEST_QUALITY = 0,
+ SRC_SINC_MEDIUM_QUALITY = 1,
+ SRC_SINC_FASTEST = 2,
+ SRC_ZERO_ORDER_HOLD = 3,
+ SRC_LINEAR = 4
+ } ;
+</PRE>
+<P>
+As new converters are added, they will given a number corresponding to the
+next inetger.
+</P>
+
+<P>
+The details of these converters are as follows:
+</P>
+<UL>
+ <LI> <B>SRC_SINC_BEST_QUALITY</B> - This is a bandlimited interpolator derived
+ from the mathematical <B>sinc</B> function and this is the highest
+ quality sinc based converter, providing a worst case Signal-to-Noise
+ Ratio (SNR) of 97 decibels (dB) at a bandwidth of 97%.
+ All three SRC_SINC_* converters are based on the techniques of
+ <A HREF="http://ccrma-www.stanford.edu/~jos/resample/">Julius O. Smith</A>
+ although this code was developed independantly.
+ <LI> <B>SRC_SINC_MEDIUM_QUALITY</B> - This is another bandlimited interpolator
+ much like the previous one. It has an SNR of 97dB and a bandwidth of 90%.
+ The speed of the conversion is much faster than the previous one.
+ <LI> <B>SRC_SINC_FASTEST</B> - This is the fastest bandlimited interpolator and
+ has an SNR of 97dB and a bandwidth of 80%.
+ <LI><B>SRC_ZERO_ORDER_HOLD</B> - A Zero Order Hold converter (interpolated value
+ is equal to the last value). The quality is poor but the conversion speed is
+ blindlingly fast.
+ <li><b>SRC_LINEAR</b> - A linear converter. Again the quality is poor, but the
+ conversion speed is blindingly fast.
+</UL>
+<P>
+There are two functions that give either a (text string) name or description
+for each converter:
+</P>
+<PRE>
+ const char *src_get_name (int converter_type) ;
+ const char *src_get_description (int converter_type) ;
+</PRE>
+<P>
+The name will typically be a short string for use in a dialog box, while the
+description string is longer.
+</P>
+<P>
+Both of these functions return a NULL pointer if there is no converter for the
+given <B>converter_type</B> value.
+Since the converters have consecutive <B>converter_type</B> values, the caller
+is easily able to figure out the number of converters at run time.
+This enables a binary dynamically linked against an old version of the library
+to know about converters from later versions of the library as they become
+available.
+</P>
+
+<A NAME="SRC_DATA"></A>
+<H3><BR>SRC_DATA</H3>
+<P>
+Both the simple and the full featured versions of the API use the <B>SRC_DATA</B>
+struct to pass audio and control data into the sample rate converter.
+This struct is defined as:
+</P>
+<PRE>
+ typedef struct
+ { float *data_in, *data_out ;
+
+ long input_frames, output_frames ;
+ long input_frames_used, output_frames_gen ;
+
+ int end_of_input ;
+
+ double src_ratio ;
+ } SRC_DATA ;
+</PRE>
+<P>
+The <B>data_in</B> pointer is used to pass audio data into the converter while the
+<B>data_out</B> pointer supplies the converter with an array to hold the converter's
+output.
+For a converter which has been configured for mulitchannel operation, these pointers
+need to point to a single array of interleaved data.
+</P>
+<P>
+The <B>input_frames</B> and <B>output_frames</B> fields supply the converter with
+the lengths of the arrays (in frames) pointed to by the <B>data_in</B> and
+<b>data_out</B> pointers respectively.
+For monophinc data, these values would indicate the length of the arrays while
+for multi channel data these values would be equal to the the length of the array
+divided by the number of channels.
+</P>
+
+<P>
+The <B>end_of_input</B> field is only used when the sample rate converter is used
+by calling the <B>src_process</B> function.
+In this case it should be set to zero if more buffers are to be passed to the
+converter and 1 if the current buffer is the last.
+</P>
+<P>
+Finally, the <B>src_ratio</B> field specifies the conversion ratio defined as
+the input sample rate divided by the output sample rate.
+For a connected set of buffers, this value can be varies on each call to
+<B>src_process</B> resulting in a time varying sample rate conversion
+process.
+For time varying sample rate conversions, the ratio will be linearly
+interpolated between the <B>src_ratio</B> value of the previous call
+to <B>src_process</B> and the value for the current call.
+</P>
+<P>
+The <B>input_frames_used</B> and <B>output_frames_gen</B> fields are set by the
+converter to inform the caller of the number of frames consumed from the
+<B>data_in</B> array and the number of frames generated in the <B>data_out</B>
+array respectively.
+These values are for the current call to <B>src_process</B> only.
+</P>
+
+<A NAME="Aux"></A>
+<H3><BR>Auxillary Functions</H3>
+<P>
+There are four auxillary functions for converting arrays of float data
+to and from short or int data.
+These functions are defined as:
+</P>
+<PRE>
+ void src_short_to_float_array (const short *in, float *out, int len) ;
+ void src_float_to_short_array (const float *in, short *out, int len) ;
+ void src_int_to_float_array (const int *in, float *out, int len) ;
+ void src_float_to_int_array (const float *in, int *out, int len) ;
+</PRE>
+<P>
+The float data is assumed to be in the range [-1.0, 1.0] and it is
+automatically scaled on the conversion to and from float.
+On the float to short/int conversion path, any data values which would overflow
+the range of short/int data are clipped.
+</P>
+
+</DIV>
+</TD></TR>
+</TABLE>
+
+</BODY>
+</HTML>
+
projects / audio-libsamplerate.git / blobdiff