[audio-libsamplerate.git] / libsamplerate / doc / api_misc.html

<!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&#37;.
		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&#37;.
		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&#37;.
	<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>
Commit	Line	Data
8529da43 MG	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<HTML>
	3
	4	<HEAD>
	5	<TITLE>
	6	Secret Rabbit Code (aka libsamplerate)
	7	</TITLE>
	8	<META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
	9	<META NAME="Version" CONTENT="libsamplerate-0.1.8">
	10	<META NAME="Description" CONTENT="The Secret Rabbit Code Home Page">
	11	<META NAME="Keywords" CONTENT="libsamplerate sound resample audio dsp Linux">
	12	<LINK REL=StyleSheet HREF="SRC.css" TYPE="text/css" MEDIA="all">
	13	</HEAD>
	14
	15	<BODY TEXT="#FFFFFF" BGCOLOR="#000000" LINK="#FB1465" VLINK="#FB1465" ALINK="#FB1465">
	16	<!-- pepper -->
	17	<CENTER>
	18	<IMG SRC="SRC.png" HEIGHT=100 WIDTH=760 ALT="SRC.png">
	19	</CENTER>
	20	<!-- pepper -->
	21	<BR>
	22	<!-- pepper -->
	23	<TABLE ALIGN="center" WIDTH="98%">
	24	<TR>
	25	<TD VALIGN="top">
	26	<BR>
	27	<DIV CLASS="nav">
	28	<BR>
	29	<A HREF="index.html">Home</A><BR>
	30	<BR>
	31	<A HREF="api_simple.html">Simple API</A><BR>
	32	<A HREF="api_full.html">Full API</A><BR>
	33	<A HREF="api_misc.html#ErrorReporting">Error Handling</A><BR>
	34	<A HREF="api_misc.html">Miscellaneous</A><BR>
	35	<BR>
	36	<DIV CLASS="block">
	37	Author :<BR>Erik de Castro Lopo
	38	<!-- pepper -->
	39	<BR><BR>
	40	<!-- pepper -->
	41
	42	</DIV>
	43	<IMG SRC=
	44	"/cgi-bin/Count.cgi?ft=6\|frgb=55;55;55\|tr=0\|md=6\|dd=B\|st=1\|sh=1\|df=src_api.dat"
	45	HEIGHT=30 WIDTH=100 ALT="counter.gif">
	46	</DIV>
	47
	48	</TD>
	49	<!-- pepper -->
	50	<!-- ######################################################################## -->
	51	<!-- pepper -->
	52	<TD VALIGN="top">
	53	<DIV CLASS="block">
	54
	55	<H1><B>Miscellaneous API Documentation</B></H1>
	56	<A NAME="ErrorReporting"></A>
	57	<H3><BR>Error Reporting</H3>
	58	<P>
	59	Most of the API functions either return an integer error (ie <B>src_simple</B>
	60	and <B>src_process</B>) or return an integer error value via an int pointer
	61	parameter (<B>src_new</B>).
	62	These integer error values can be converted into a human readable text strings by
	63	calling the function:
	64	</P>
65	<PRE>
66	const char* src_strerror (int error) ;
67	</PRE>
68	<P>
69	which will return an error string for valid error numbers, the string "No Error"
70	for an error value of zero or a NULL pointer if no error message has been defined
71	for that error value.
72	</P>
73
74	<A NAME="Converters"></A>
75	<H3><BR>Converters</H3>
76	<P>
77	Secret Rabbit Code has a number of different converters which can be selected
78	using the <B>converter_type</B> parameter when calling <B>src_simple</B> or
79	<b>src_new</B>.
80	Currently, the five converters available are:
81	</P>
82	<PRE>
83	enum
84	{
85	SRC_SINC_BEST_QUALITY = 0,
86	SRC_SINC_MEDIUM_QUALITY = 1,
87	SRC_SINC_FASTEST = 2,
88	SRC_ZERO_ORDER_HOLD = 3,
89	SRC_LINEAR = 4
90	} ;
91	</PRE>
92	<P>
93	As new converters are added, they will given a number corresponding to the
94	next inetger.
95	</P>
96
97	<P>
98	The details of these converters are as follows:
99	</P>
100	<UL>
101	<LI> <B>SRC_SINC_BEST_QUALITY</B> - This is a bandlimited interpolator derived
102	from the mathematical <B>sinc</B> function and this is the highest
103	quality sinc based converter, providing a worst case Signal-to-Noise
104	Ratio (SNR) of 97 decibels (dB) at a bandwidth of 97%.
105	All three SRC_SINC_* converters are based on the techniques of
106	<A HREF="http://ccrma-www.stanford.edu/~jos/resample/">Julius O. Smith</A>
107	although this code was developed independantly.
108	<LI> <B>SRC_SINC_MEDIUM_QUALITY</B> - This is another bandlimited interpolator
109	much like the previous one. It has an SNR of 97dB and a bandwidth of 90%.
110	The speed of the conversion is much faster than the previous one.
111	<LI> <B>SRC_SINC_FASTEST</B> - This is the fastest bandlimited interpolator and
112	has an SNR of 97dB and a bandwidth of 80%.
113	<LI><B>SRC_ZERO_ORDER_HOLD</B> - A Zero Order Hold converter (interpolated value
114	is equal to the last value). The quality is poor but the conversion speed is
115	blindlingly fast.
116	<li><b>SRC_LINEAR</b> - A linear converter. Again the quality is poor, but the
117	conversion speed is blindingly fast.
118	</UL>
119	<P>
120	There are two functions that give either a (text string) name or description
121	for each converter:
122	</P>
123	<PRE>
124	const char *src_get_name (int converter_type) ;
125	const char *src_get_description (int converter_type) ;
126	</PRE>
127	<P>
128	The name will typically be a short string for use in a dialog box, while the
129	description string is longer.
130	</P>
131	<P>
132	Both of these functions return a NULL pointer if there is no converter for the
133	given <B>converter_type</B> value.
134	Since the converters have consecutive <B>converter_type</B> values, the caller
135	is easily able to figure out the number of converters at run time.
136	This enables a binary dynamically linked against an old version of the library
137	to know about converters from later versions of the library as they become
138	available.
139	</P>
140
141	<A NAME="SRC_DATA"></A>
142	<H3><BR>SRC_DATA</H3>
143	<P>
144	Both the simple and the full featured versions of the API use the <B>SRC_DATA</B>
145	struct to pass audio and control data into the sample rate converter.
146	This struct is defined as:
147	</P>
148	<PRE>
149	typedef struct
150	{ float data_in, data_out ;
151
152	long input_frames, output_frames ;
153	long input_frames_used, output_frames_gen ;
154
155	int end_of_input ;
156
157	double src_ratio ;
158	} SRC_DATA ;
159	</PRE>
160	<P>
161	The <B>data_in</B> pointer is used to pass audio data into the converter while the
162	<B>data_out</B> pointer supplies the converter with an array to hold the converter's
163	output.
164	For a converter which has been configured for mulitchannel operation, these pointers
165	need to point to a single array of interleaved data.
166	</P>
167	<P>
168	The <B>input_frames</B> and <B>output_frames</B> fields supply the converter with
169	the lengths of the arrays (in frames) pointed to by the <B>data_in</B> and
170	<b>data_out</B> pointers respectively.
171	For monophinc data, these values would indicate the length of the arrays while
172	for multi channel data these values would be equal to the the length of the array
173	divided by the number of channels.
174	</P>
175
176	<P>
177	The <B>end_of_input</B> field is only used when the sample rate converter is used
178	by calling the <B>src_process</B> function.
179	In this case it should be set to zero if more buffers are to be passed to the
180	converter and 1 if the current buffer is the last.
181	</P>
182	<P>
183	Finally, the <B>src_ratio</B> field specifies the conversion ratio defined as
184	the input sample rate divided by the output sample rate.
185	For a connected set of buffers, this value can be varies on each call to
186	<B>src_process</B> resulting in a time varying sample rate conversion
187	process.
188	For time varying sample rate conversions, the ratio will be linearly
189	interpolated between the <B>src_ratio</B> value of the previous call
190	to <B>src_process</B> and the value for the current call.
191	</P>
192	<P>
193	The <B>input_frames_used</B> and <B>output_frames_gen</B> fields are set by the
194	converter to inform the caller of the number of frames consumed from the
195	<B>data_in</B> array and the number of frames generated in the <B>data_out</B>
196	array respectively.
197	These values are for the current call to <B>src_process</B> only.
198	</P>
199
200	<A NAME="Aux"></A>
201	<H3><BR>Auxillary Functions</H3>
202	<P>
203	There are four auxillary functions for converting arrays of float data
204	to and from short or int data.
205	These functions are defined as:
206	</P>
207	<PRE>
208	void src_short_to_float_array (const short in, float out, int len) ;
209	void src_float_to_short_array (const float in, short out, int len) ;
210	void src_int_to_float_array (const int in, float out, int len) ;
211	void src_float_to_int_array (const float in, int out, int len) ;
212	</PRE>
213	<P>
214	The float data is assumed to be in the range [-1.0, 1.0] and it is
215	automatically scaled on the conversion to and from float.
216	On the float to short/int conversion path, any data values which would overflow
217	the range of short/int data are clipped.
218	</P>
219
220	</DIV>
221	</TD></TR>
222	</TABLE>
223
224	</BODY>
225	</HTML>
226