Mercurial > hg > sv-dependency-builds
diff src/libsamplerate-0.1.9/doc/api_misc.html @ 41:481f5f8c5634
Current libsamplerate source
| author | Chris Cannam |
|---|---|
| date | Tue, 18 Oct 2016 13:24:45 +0100 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/libsamplerate-0.1.9/doc/api_misc.html Tue Oct 18 13:24:45 2016 +0100 @@ -0,0 +1,226 @@ +<!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> +