History

Update site documentation

* Use GitHub's Jekyll static site generator. * Move all documentation to docs/ directory. * Convert HTML to Markdown.

evpobr committed 6 years ago

Commit 260c3f61 parent 01284e738 files · +1057 −2227Browse files

Unified · Split

38 files
  1. CMakeLists.txt +1 −1
  2. Makefile.am +4 −4
  3. NEWS +8 −0
  4. doc/SRC.css +0 −84
  5. doc/api.html +0 −127
  6. doc/api_callback.html +0 −176
  7. doc/api_full.html +0 −218
  8. doc/api_misc.html +0 −227
  9. doc/api_simple.html +0 −147
  10. doc/bugs.html +0 −116
  11. doc/download.html +0 −89
  12. doc/faq.html +0 −361
  13. doc/history.html +0 −102
  14. doc/index.html +0 −129
  15. doc/license.html +0 −80
  16. doc/lists.html +0 −91
  17. doc/quality.html +0 −179
  18. doc/win32.html +0 −99
  19. docs/SRC.css +48 −0
  20. docs/SRC.png +0 −0
  21. docs/_config.yml +8 −0
  22. docs/_layouts/default.html +51 −0
  23. docs/api.md +46 −0
  24. docs/api_callback.md +88 −0
  25. docs/api_full.md +146 −0
  26. docs/api_misc.md +143 −0
  27. docs/api_simple.md +71 −0
  28. docs/bugs.md +37 −0
  29. docs/download.md +15 −0
  30. docs/faq.md +193 −0
  31. docs/foo_dsp_src9.png +0 −0
  32. docs/history.md +34 −0
  33. docs/index.md +39 −0
  34. docs/license.md +12 −0
  35. docs/lists.md +17 −0
  36. docs/paypal.png +0 −0
  37. docs/quality.md +84 −0
  38. docs/win32.md +15 −0
CMakeLists.txt+1−1
@@ -373,7 +373,7 @@ if(LIBSAMPLERATE_INSTALL) · 372 unmodified lines
373 373
374 # Documentation374 # Documentation
375 375
376 install(DIRECTORY doc/ DESTINATION ${CMAKE_INSTALL_DOCDIR})376 install(DIRECTORY docs/ DESTINATION ${CMAKE_INSTALL_DOCDIR})
377endif()377endif()
378 378
379# Packaging support379# Packaging support
Makefile.am+4−4
@@ -49,12 +49,12 @@ check-asm: src/check_asm.sh src/src_sinc.s src/src_linear.s src/src_zoh.s · 48 unmodified lines
49AUTOHEADER=echo49AUTOHEADER=echo
50 50
51########51########
52# doc/ #52# docs/ #
53########53########
54 54
55dist_html_DATA = doc/SRC.png doc/SRC.css doc/index.html doc/license.html doc/history.html \55dist_doc_DATA = docs/SRC.png docs/SRC.css docs/index.md docs/license.md docs/history.md \
56 doc/download.html doc/lists.html doc/quality.html doc/win32.html doc/faq.html doc/api.html \56 docs/download.md docs/lists.md docs/quality.md docs/win32.md docs/faq.md docs/api.md \
57 doc/api_simple.html doc/api_callback.html doc/api_full.html doc/api_misc.html57 docs/api_simple.md docs/api_callback.md docs/api_full.md docs/api_misc.md
58 58
59#############59#############
60# examples/ #60# examples/ #
NEWS+8−0
@@ -1,3 +1,11 @@
1Unreleased
2
3 * Documentation:
4 * Move site to new URL: http://libsndfile.github.io/libsamplerate/
5 * Convert documentation pages from HTML to Markdown
6 * Use GitHub's Jekyll static site generator to generate static HTML pages
7 for site
8
1Version 0.1.9 (2016-09-23)9Version 0.1.9 (2016-09-23)
2 * Relicense under 2 clause BSD license.10 * Relicense under 2 clause BSD license.
3 * Minor bug fixes and upates.11 * Minor bug fixes and upates.
doc/SRC.css+0−84
@@ -1,84 +0,0 @@
1body {
2 background : black ;
3 color : white ;
4 font-family : arial, helvetica, sans-serif ;
5}
6td {
7 font-family : arial, helvetica, sans-serif ;
8 background : black ;
9 color : white ;
10}
11center {
12 font-family : arial, helvetica, sans-serif ;
13}
14div {
15 line-height: 1.3;
16}
17p {
18 font-family : arial, helvetica, sans-serif ;
19 text-align : left ;
20 line-height: 1.3;
21 margin-left : 3% ;
22 margin-right : 3% ;
23}
24.indent_block {
25 font-family : arial, helvetica, sans-serif ;
26 text-align : left ;
27 margin-left : 10% ;
28 margin-right : 10% ;
29}
30br {
31 font-family : arial, helvetica, sans-serif ;
32}
33form {
34 font-family : arial, helvetica, sans-serif ;
35}
36ul {
37 font-family : arial, helvetica, sans-serif ;
38 text-align : left ;
39 line-height: 1.3;
40 margin-left : 3% ;
41 margin-right : 6% ;
42}
43ol {
44 font-family : arial, helvetica, sans-serif ;
45 text-align : left ;
46 line-height: 1.3;
47 margin-left : 3% ;
48 margin-right : 6% ;
49}
50dl {
51 font-family : arial, helvetica, sans-serif ;
52 text-align : left ;
53 margin-left : 3% ;
54 margin-right : 3% ;
55}
56h1 {
57 font-size : xx-large ;
58 background : black ;
59 color : #FB1465 ;
60 text-align : left ;
61 margin-left : 3% ;
62 margin-right : 3% ;
63}
64h2 {
65 font-size : x-large ;
66 background : black ;
67 color : #FB1465 ;
68 text-align : left ;
69 margin-left : 3% ;
70 margin-right : 3% ;
71}
72h3 {
73 font-size : large ;
74 background : black ;
75 color : #FB1465 ;
76 text-align : left ;
77 margin-left : 3% ;
78 margin-right : 3% ;
79}
80pre {
81 font-family : courier, monospace ;
82 font-size : medium ;
83}
84
doc/api.html+0−127
@@ -1,127 +0,0 @@
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 <A HREF="license.html">License</A><BR>
31 <A HREF="history.html">History</A><BR>
32 <A HREF="download.html">Download</A><BR>
33 <A HREF="quality.html">Quality</A><BR>
34 <A HREF="api.html">API</A><BR>
35 <A HREF="bugs.html">Bug Reporting</A><BR>
36 <A HREF="win32.html">On Win32</A><BR>
37 <A HREF="faq.html">FAQ</A><BR>
38 <A HREF="lists.html">Mailing Lists</A><BR>
39 <A HREF="ChangeLog">ChangeLog</A><BR>
40<BR>
41<DIV CLASS="block">
42Author :<BR>Erik de Castro Lopo
43<!-- pepper -->
44<BR><BR>
45<!-- pepper -->
46
47</DIV>
48 <IMG SRC=
49 "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_api.dat"
50 HEIGHT=30 WIDTH=100 ALT="counter.gif">
51</DIV>
52
53</TD>
54<!-- pepper -->
55<!-- ######################################################################## -->
56<!-- pepper -->
57<TD VALIGN="top">
58<DIV CLASS="block">
59
60<H1><B>Applications Programming Interface</B></H1>
61<P>
62The publically callable functions of libsamplerate are all listed in the
63<B>&lt;samplerate.h&gt;</B> header file.
64In order to use any of the functionality of libsamplerate, you need to add
65</P>
66<PRE>
67 #include &lt;samplerate.h&gt;
68</PRE>
69<P>
70to the top of any function that call any of the following functions.
71You will also need to link you binary with the libsamplerate library.
72</P>
73<P>
74The API allows three methods for accessing the capabilies of the library:
75</P>
76<UL>
77 <LI>A <A HREF="api_simple.html">simple interface</A> which can sample rate convert
78 a single block of samples (one or more channels) in one go.
79 The simple API is less capable than the full API.
80 <LI>A <A HREF="api_full.html">more fully featured interface</A> which allows time
81 varying sample rate conversion on streaming data (again one or more
82 channels).
83 <LI>A <A HREF="api_callback.html">callback interface</A> which has the same
84 functionality as the interface above but allows the details of input and
85 output to be separated.
86 The output is generated by call a read function and the library calls a user
87 supplied callback function to obtain its input.
88 This interface is particularly well suited to applications where the output
89 sample rate is varied with time.
90</UL>
91
92<P>
93<b>NB :</b> All three access methods are able to process multi channel interleaved
94data.
95</P>
96
97<P>
98The parts of the API which are common to all three interfaces are:
99</P>
100<UL>
101 <LI> The <A HREF="api_misc.html#ErrorReporting">error reporting</A> mechanisim.
102 <LI> The available <A HREF="api_misc.html#Converters">converter</A> types.
103 <LI> The <A HREF="api_misc.html#SRC_DATA">SRC_DATA</A> struct.
104</UL>
105<P>
106All three versions of the API are restricted to operating on buffers of ISO C
107Standard <B>float</B> data.
108However, there are two
109 <A HREF="api_misc.html#Aux">auxillary functions</A>
110for converting arrays of float data to and from short data.
111</P>
112
113<P>
114<B>Note:</B> The <B>tests/</B> and <B>examples/</B> directories of the source code
115distribution contain numerous example programs showing the use of the library.
116</P>
117
118<!-- pepper -->
119<!-- <A HREF="mailto:aldel0305@mega-nerd.com">For the spam bots</A> -->
120<!-- pepper -->
121
122</DIV>
123</TD></TR>
124</TABLE>
125
126</BODY>
127</HTML>
doc/api_callback.html+0−176
@@ -1,176 +0,0 @@
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_callback.html">Callback API</A><BR>
34 <A HREF="api_misc.html">Miscellaneous</A><BR>
35 <A HREF="api_misc.html#ErrorReporting">Error Handling</A><BR>
36<BR>
37<DIV CLASS="block">
38Author :<BR>Erik de Castro Lopo
39<!-- pepper -->
40<BR><BR>
41<!-- pepper -->
42
43</DIV>
44 <IMG SRC=
45 "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_api.dat"
46 HEIGHT=30 WIDTH=100 ALT="counter.gif">
47</DIV>
48
49</TD>
50<!-- pepper -->
51<!-- ######################################################################## -->
52<!-- pepper -->
53<TD VALIGN="top">
54<DIV CLASS="block">
55
56<H1><B>Callback API</B></H1>
57<P>
58The callback API consists of the following functions :
59</P>
60<PRE>
61 typedef long (*src_callback_t) (void *cb_data, float **data) ;
62
63 SRC_STATE* <A HREF="#Init">src_callback_new</A> (src_callback_t func,
64 int converter_type, int channels,
65 int *error, void* cb_data) ;
66
67 SRC_STATE* <A HREF="api_full.html#CleanUp">src_delete</A> (SRC_STATE *state) ;
68
69 long <A HREF="#Read">src_callback_read</A> (SRC_STATE *state, double src_ratio,
70 long frames, float *data) ;
71
72 int <A HREF="api_full.html#Reset">src_reset</A> (SRC_STATE *state) ;
73 int <A HREF="api_full.html#SetRatio">src_set_ratio</A> (SRC_STATE *state, double new_ratio) ;
74</PRE>
75<BR>
76
77<P>
78Like the
79 <A HREF="api_simple.html">simple API</a>
80and the
81 <A HREF="api_full.html">full API</a>,
82the callback based API is able to operate on interleaved multi channel data.
83</P>
84
85<P>
86An example of the use of the callback based API can be found in the
87<B>varispeed-play</B> program in the <B>examples/</B> directory of the
88source code tarball.
89</P>
90
91<!-- pepper -->
92<A NAME="Init"></A>
93<H3><BR>Initialisation</H3>
94<PRE>
95 SRC_STATE* src_callback_new (src_callback_t func,
96 int converter_type, int channels,
97 int *error, void* cb_data) ;
98</PRE>
99<P>
100The <B>src_callback_new</B> function returns an anonymous pointer to a
101sample rate converter callback object, src_state.
102This is the same type of object as that returned by <A HREF="api_full.html#init">
103src_new</A>, but with different internal state.
104Although these are the same object type, they cannot be used interchangeably.
105If an error occurs the function returns a NULL pointer and fills in the
106error value pointed to by the <B>error</B> pointer supplied by the caller.
107</P>
108<P>
109The caller then passes the SRC_STATE object to the <B>src_callback_read</B>
110function to pull data out of the converter.
111When the caller is finished with the converter they should pass it to the
112clean up function <A HREF="api_full.html#CleanUp">src_delete</A>.
113</P>
114<P>
115The <B>func</B> parameter is a user supplied function which must match the
116<B>src_callback_t</B> type signature while <B>cb_data</B> is a pointer to
117data which be passed as the first parameter to the user supplied callback
118function.
119This function is called by the converter whenever it needs input data as a
120result of being calls to <B>src_callback_read</B>.
121</P>
122<P>
123If the converter was initialised to work with more than one channel, the
124callback function must work with mutiple channels of interleaved data.
125The callback function should return the number of frames it supplying to
126the converter.
127For multi channel files, this return value should be the number of floats
128divided by the number of channels.
129</P>
130<P>
131The converter must be one of the supplied converter types documented
132<A HREF="api_misc.html#Converters">here</A>.
133</P>
134<P>
135The caller then passes the SRC_STATE pointer to the <B>src_callback_read</B>
136function to pull data out of the converter.
137</P>
138
139<!-- pepper -->
140<A NAME="Read"></A>
141<H3><BR>Callback Read</H3>
142<PRE>
143 long src_callback_read (SRC_STATE *state, double src_ratio,
144 long frames, float *data) ;
145</PRE>
146<P>
147The <B>src_callback_read</B> function is passed the
148 <A HREF="api_misc.html#SRC_DATA"><B>SRC_STATE</B></A>
149pointer returned by <B>src_callback_new</B>, the coversion ratio
150(output_sample_rate / input_sample_rate), the maximum number of output frames
151to generate and a pointer to a buffer in which to place the output data.
152For multi channel files, the data int the output buffer is stored in
153interleaved format.
154</P>
155<P>
156The <B>src_callback_read</B> function returns the number of frames generated
157or zero if an error occurs or it runs out of input (ie the user supplied
158callback function returns zero and there is no more data buffered internally).
159If an error has occurred, the function <A HREF="api_misc.html#ErrorReporting">
160src_error</A> will return non-zero.
161</P>
162
163<P>
164See also :
165 <A HREF="api_full.html#SetRatio"><B>src_set_ratio</B></A>
166</P>
167
168<!-- pepper -->
169
170</DIV>
171</TD></TR>
172</TABLE>
173
174</BODY>
175</HTML>
176
doc/api_full.html+0−218
@@ -1,218 +0,0 @@
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_callback.html">Callback API</A><BR>
34 <A HREF="api_misc.html">Miscellaneous</A><BR>
35 <A HREF="api_misc.html#ErrorReporting">Error Handling</A><BR>
36<BR>
37<DIV CLASS="block">
38Author :<BR>Erik de Castro Lopo
39<!-- pepper -->
40<BR><BR>
41<!-- pepper -->
42
43</DIV>
44 <IMG SRC=
45 "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_api.dat"
46 HEIGHT=30 WIDTH=100 ALT="counter.gif">
47</DIV>
48
49</TD>
50<!-- pepper -->
51<!-- ######################################################################## -->
52<!-- pepper -->
53<TD VALIGN="top">
54<DIV CLASS="block">
55
56<H1><B>Full API</B></H1>
57<P>
58The full API consists of the following functions :
59</P>
60<PRE>
61 SRC_STATE* <A HREF="#Init">src_new</A> (int converter_type, int channels, int *error) ;
62 SRC_STATE* <A HREF="#CleanUp">src_delete</A> (SRC_STATE *state) ;
63
64 int <A HREF="#Process">src_process</A> (SRC_STATE *state, SRC_DATA *data) ;
65 int <A HREF="#Reset">src_reset</A> (SRC_STATE *state) ;
66 int <A HREF="#SetRatio">src_set_ratio</A> (SRC_STATE *state, double new_ratio) ;
67</PRE>
68
69<A NAME="Init"></A>
70<H3><BR>Initialisation</H3>
71<PRE>
72 SRC_STATE* src_new (int converter_type, int channels, int *error) ;
73</PRE>
74<P>
75The <B>src_new</B> function returns an anonymous pointer to a sample rate
76converter object, src_state.
77If an error occurs the function returns a NULL pointer and fills in the
78error value pointed to by the <B>error</B> pointer supplied by the caller.
79The converter must be one of the supplied converter types documented
80<A HREF="api_misc.html#Converters">here</A>.
81</P>
82
83<A NAME="CleanUp"></A>
84<H3><BR>Cleanup</H3>
85<PRE>
86 SRC_STATE* src_delete (SRC_STATE *state) ;
87</PRE>
88<P>
89The <B>src_delete</B> function frees up all memory allocated for the given sample
90rate converter object and returns a NULL pointer.
91The caller is responsible for freeing any memory passed to the sample rate converter
92via the pointer to the <B>SRC_DATA</B> struct.
93</P>
94
95<A NAME="Process"></A>
96<H3><BR>Process</H3>
97<PRE>
98 int src_process (SRC_STATE *state, SRC_DATA *data) ;
99</PRE>
100<P>
101The <B>src_process</B> function processes the data provided by the caller
102in an <B>SRC_DATA</B> struct using the sample rate converter object specified
103by the <B>SRC_STATE</B> pointer.
104When operating on streaming data, this function can be called over and over again,
105with each new call providing new input data and returning new output data.
106</P>
107
108<P>
109The <B>SRC_DATA</B> struct passed as the second parameter to the <B>src_process</B>
110function has the following fields:
111</P>
112<PRE>
113 typedef struct
114 { const float *data_in;
115 float *data_out;
116
117 long input_frames, output_frames ;
118 long input_frames_used, output_frames_gen ;
119
120 int end_of_input ;
121
122 double src_ratio ;
123 } SRC_DATA ;
124</PRE>
125<P>
126The fields of this struct which must be filled in by the caller are:
127</P>
128<PRE>
129 data_in : A pointer to the input data samples.
130 input_frames : The number of frames of data pointed to by data_in.
131 data_out : A pointer to the output data samples.
132 output_frames : Maximum number of frames pointer to by data_out.
133 src_ratio : Equal to output_sample_rate / input_sample_rate.
134 end_of_input : Equal to 0 if more input data is available and 1
135 otherwise.
136</PRE>
137<P>
138Note that the data_in and data_out arrays may not overlap. If they do, the
139library will return an error code.
140</P>
141<P>
142When the <B>src_process</B> function returns <B>output_frames_gen</B> will be
143set to the number of output frames generated and <B>input_frames_used</B> will
144be set to the number of input frames consumed to generate the provided number of
145output frames.
146</P>
147
148<P>
149The <B>src_process</B> function returns non-zero if an error occurs.
150The non-zero error return value can be decoded into a text string using the function
151documented <A HREF="api_misc.html#ErrorReporting">here</A>.
152</P>
153
154<A NAME="Reset"></A>
155<H3><BR>Reset</H3>
156<PRE>
157 int src_reset (SRC_STATE *state) ;
158</PRE>
159<P>
160The <B>src_reset</B> function resets the internal state of the sample rate
161converter object to the same state it had immediately after its creation using
162<B>src_new</B>.
163This should be called whenever a sample rate converter is to be used on two
164separate, unrelated pieces of audio.
165</P>
166
167<A NAME="Clone"></A>
168<H3><BR>Clone</H3>
169<PRE>
170 SRC_STATE* src_clone (SRC_STATE *state, int *error) ;
171</PRE>
172<P>
173The <B>src_clone</B> function creates a copy of the internal state of the sample
174rate converter object. The output of the next call to <B>src_process</B> will be
175identical for both the original and cloned state (given the same <B>SRC_DATA</B>
176input). This could be used to later resume sample rate conversion at a specific
177location in a stream with the same state, which may be useful in real-time
178applications.
179</P>
180<P>
181If an error occurs the function returns a NULL pointer and fills in the
182error value pointed to by the <B>error</B> pointer supplied by the caller.
183</P>
184
185<A NAME="SetRatio"></A>
186<H3><BR>Set Ratio</H3>
187<PRE>
188 int src_set_ratio (SRC_STATE *state, double new_ratio) ;
189</PRE>
190
191<p>
192When using the <B>src_process</B> or <B>src_callback_process</B> APIs and
193updating the <B>src_ratio</B> field of the <B>SRC_STATE</B> struct, the library
194will try to smoothly transition between the conversion ratio of the last call
195and the conversion ratio of the current call.
196<p/>
197
198<P>
199If the user want to bypass this smooth transition and achieve a step response in
200the conversion ratio, the <B>src_set_ratio</B> function can be used to set the
201starting conversion ratio of the next call to <B>src_process</B> or
202<B>src_callback_process</B>.
203<p/>
204
205<P>
206This function returns non-zero on error and the error return value can be
207decoded into a text string using the function documented
208<A HREF="api_misc.html#ErrorReporting">here</A>.</P>
209
210<!-- <A HREF="mailto:aldel@mega-nerd.com">For the spam bots</A> -->
211
212</DIV>
213</TD></TR>
214</TABLE>
215
216</BODY>
217</HTML>
218
doc/api_misc.html+0−227
@@ -1,227 +0,0 @@
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">
37Author :<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>
59Most of the API functions either return an integer error (ie <B>src_simple</B>
60and <B>src_process</B>) or return an integer error value via an int pointer
61parameter (<B>src_new</B>).
62These integer error values can be converted into a human readable text strings by
63calling the function:
64</P>
65<PRE>
66 const char* src_strerror (int error) ;
67</PRE>
68<P>
69which will return an error string for valid error numbers, the string "No Error"
70for an error value of zero or a NULL pointer if no error message has been defined
71for that error value.
72</P>
73
74<A NAME="Converters"></A>
75<H3><BR>Converters</H3>
76<P>
77Secret Rabbit Code has a number of different converters which can be selected
78using the <B>converter_type</B> parameter when calling <B>src_simple</B> or
79<b>src_new</B>.
80Currently, 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>
93As new converters are added, they will given a number corresponding to the
94next inetger.
95</P>
96
97<P>
98The 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&#37;.
105 All three SRC_SINC_* converters are based on the techniques of
106 <A HREF="http://ccrma.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&#37;.
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&#37;.
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>
120There are two functions that give either a (text string) name or description
121for 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>
128The name will typically be a short string for use in a dialog box, while the
129description string is longer.
130</P>
131<P>
132Both of these functions return a NULL pointer if there is no converter for the
133given <B>converter_type</B> value.
134Since the converters have consecutive <B>converter_type</B> values, the caller
135is easily able to figure out the number of converters at run time.
136This enables a binary dynamically linked against an old version of the library
137to know about converters from later versions of the library as they become
138available.
139</P>
140
141<A NAME="SRC_DATA"></A>
142<H3><BR>SRC_DATA</H3>
143<P>
144Both the simple and the full featured versions of the API use the <B>SRC_DATA</B>
145struct to pass audio and control data into the sample rate converter.
146This struct is defined as:
147</P>
148<PRE>
149 typedef struct
150 { const float *data_in;
151 float *data_out ;
152
153 long input_frames, output_frames ;
154 long input_frames_used, output_frames_gen ;
155
156 int end_of_input ;
157
158 double src_ratio ;
159 } SRC_DATA ;
160</PRE>
161<P>
162The <B>data_in</B> pointer is used to pass audio data into the converter while the
163<B>data_out</B> pointer supplies the converter with an array to hold the converter's
164output.
165For a converter which has been configured for mulitchannel operation, these pointers
166need to point to a single array of interleaved data.
167</P>
168<P>
169The <B>input_frames</B> and <B>output_frames</B> fields supply the converter with
170the lengths of the arrays (in frames) pointed to by the <B>data_in</B> and
171<b>data_out</B> pointers respectively.
172For monophinc data, these values would indicate the length of the arrays while
173for multi channel data these values would be equal to the the length of the array
174divided by the number of channels.
175</P>
176
177<P>
178The <B>end_of_input</B> field is only used when the sample rate converter is used
179by calling the <B>src_process</B> function.
180In this case it should be set to zero if more buffers are to be passed to the
181converter and 1 if the current buffer is the last.
182</P>
183<P>
184Finally, the <B>src_ratio</B> field specifies the conversion ratio defined as
185the output sample rate divided by the input sample rate.
186For a connected set of buffers, this value can be varies on each call to
187<B>src_process</B> resulting in a time varying sample rate conversion
188process.
189For time varying sample rate conversions, the ratio will be linearly
190interpolated between the <B>src_ratio</B> value of the previous call
191to <B>src_process</B> and the value for the current call.
192</P>
193<P>
194The <B>input_frames_used</B> and <B>output_frames_gen</B> fields are set by the
195converter to inform the caller of the number of frames consumed from the
196<B>data_in</B> array and the number of frames generated in the <B>data_out</B>
197array respectively.
198These values are for the current call to <B>src_process</B> only.
199</P>
200
201<A NAME="Aux"></A>
202<H3><BR>Auxillary Functions</H3>
203<P>
204There are four auxillary functions for converting arrays of float data
205to and from short or int data.
206These functions are defined as:
207</P>
208<PRE>
209 void src_short_to_float_array (const short *in, float *out, int len) ;
210 void src_float_to_short_array (const float *in, short *out, int len) ;
211 void src_int_to_float_array (const int *in, float *out, int len) ;
212 void src_float_to_int_array (const float *in, int *out, int len) ;
213</PRE>
214<P>
215The float data is assumed to be in the range [-1.0, 1.0] and it is
216automatically scaled on the conversion to and from float.
217On the float to short/int conversion path, any data values which would overflow
218the range of short/int data are clipped.
219</P>
220
221</DIV>
222</TD></TR>
223</TABLE>
224
225</BODY>
226</HTML>
227
doc/api_simple.html+0−147
@@ -1,147 +0,0 @@
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_callback.html">Callback API</A><BR>
34 <A HREF="api_misc.html">Miscellaneous</A><BR>
35 <A HREF="api_misc.html#ErrorReporting">Error Handling</A><BR>
36<BR>
37<DIV CLASS="block">
38Author :<BR>Erik de Castro Lopo
39<!-- pepper -->
40<BR><BR>
41<!-- pepper -->
42
43</DIV>
44 <IMG SRC=
45 "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_api.dat"
46 HEIGHT=30 WIDTH=100 ALT="counter.gif">
47</DIV>
48
49</TD>
50<!-- pepper -->
51<!-- ######################################################################## -->
52<!-- pepper -->
53<TD VALIGN="top">
54<DIV CLASS="block">
55
56<H1><B>Simple API</B></H1>
57
58<P>
59<B>Important Note:</B>
60The simple API is not designed to work on small chunks of a larger piece of
61audio.
62If you attempt to use it this way you are doing it wrong and will not get the
63results you want.
64For processing audio data in chunks you <b>must</b> use the
65 <a href="api_full.html">full api</a>
66or the
67 <a href="api_callback.html">callback based api</a>.
68</P>
69
70<br/><br/>
71
72<P>
73The simple API consists of a single function :
74</P>
75<PRE>
76 int src_simple (SRC_DATA *data, int converter_type, int channels) ;
77</PRE>
78<P>
79The use of this function rather than the more fully featured API requires the caller
80to know the total length of the input data before hand and that all input and output
81data can be held in the system's memory at once.
82It also assumes that there is a single constant ratio between input and output sample
83rates.
84<!--
85If these conditions cannot be met, the full featured API should be used instead.
86In addition, this documentation is complemented by this
87<A HREF="ex_simple.html">example code</A>. -->
88</P>
89
90<P>
91Dealing with the easy stuff first, the <B>converter_type</B> parameter should be
92one of the values defined in <B>samplerate.h</B> and documented
93<A HREF="api_misc.html#Converters">here</A> while the <b>channels</b> parameter
94specifies the number of interleaved channels that the sample rate converter
95is being asked to process (number of input channels and output channels is always
96equal).
97There is no hard upper limit on the number of channels; it is limited purely
98by the amount of memory available.
99</P>
100
101
102<P>
103The first parameter to <B>src_simple</B> is a pointer to an <B>SRC_DATA</B> struct
104(more info <A HREF="api_misc.html#SRC_DATA">here</A>) defined as follows:
105</P>
106<PRE>
107 typedef struct
108 { const float *data_in;
109 float *data_out ;
110
111 long input_frames, output_frames ;
112 long input_frames_used, output_frames_gen ;
113
114 int end_of_input ;
115
116 double src_ratio ;
117 } SRC_DATA ;
118</PRE>
119<P>
120The fields of this struct which must be filled in by the caller are:
121</P>
122<PRE>
123 data_in : A pointer to the input data samples.
124 input_frames : The number of frames of data pointed to by data_in.
125 data_out : A pointer to the output data samples.
126 output_frames : Maximum number of frames pointer to by data_out.
127 src_ratio : Equal to output_sample_rate / input_sample_rate.
128</PRE>
129<P>
130When the <B>src_simple</B> function returns <B>output_frames_gen</B> will be
131set to the number of output frames generated and <B>input_frames_used</B> will
132be set to the number of input frames used to generate the provided number of
133output frames.
134</P>
135<P>
136The <B>src_simple</B> function returns a non-zero value when an error occurs.
137See <A HREF="api_misc.html#ErrorReporting">here</A> for how to convert the error value into
138a text string.
139</P>
140
141</DIV>
142</TD></TR>
143</TABLE>
144
145</BODY>
146</HTML>
147
doc/bugs.html+0−116
@@ -1,116 +0,0 @@
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 <A HREF="license.html">License</A><BR>
31 <A HREF="history.html">History</A><BR>
32 <A HREF="download.html">Download</A><BR>
33 <A HREF="quality.html">Quality</A><BR>
34 <A HREF="api.html">API</A><BR>
35 <A HREF="bugs.html">Bug Reporting</A><BR>
36 <A HREF="win32.html">On Win32</A><BR>
37 <A HREF="faq.html">FAQ</A><BR>
38 <A HREF="lists.html">Mailing Lists</A><BR>
39 <A HREF="ChangeLog">ChangeLog</A><BR>
40<BR>
41<DIV CLASS="block">
42Author :<BR>Erik de Castro Lopo
43<!-- pepper -->
44<BR><BR>
45<!-- pepper -->
46
47</DIV>
48 <IMG SRC=
49 "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_bugs.dat"
50 HEIGHT=30 WIDTH=100 ALT="counter.gif">
51</DIV>
52
53</TD>
54<!-- pepper -->
55<!-- ######################################################################## -->
56<!-- pepper -->
57<TD VALIGN="top">
58<DIV CLASS="block">
59
60<H1><B>Bug Reporting</B></H1>
61<P>
62 If you are a user and have a problem using libsamplerate with another piece
63 of software, you should contact the author of that other software and get
64 them to explore their use of this library and possibly submit a bug report.
65 If you are a coder and think you have found a bug in libsamplerate then
66 read on.
67</P>
68<P>
69 Secret Rabbit Code is an extremely complex piece of code but I do think
70 that it is relatively bug free.
71 In addition, the source code distribution includes a comprehensive test
72 suite for regression testing.
73 This means it is extremely unlikely that new bugs creep in when
74 modifications are made to the code.
75</P>
76<P>
77 SRC is also not the most simple library to use which means that I do get
78 a number of bug reports which turn out to be bugs in the user's program
79 rather than bugs in SRC.
80 Up until now, I have investigated each bug report as thoroughly as
81 possible.
82 Unfortunately, this chews up a lot of my time which could otherwise be
83 spent improving SRC, working on other Free Software or spending time
84 with my family.
85</P>
86<P>
87 I have therefore decided, that I cannot investigate any bug report unless
88 the person reporting the problem can supply me with a short self contained
89 test program or a modification to one of the existing test programs in
90 the tests/ directory of the source code distribution.
91 The test program should meet the following criteria:
92</P>
93 <UL>
94 <LI>Written in C or C++.
95 <LI>Does not use any libraries or header files other than the ones which are
96 standard for the relevant languages. (Of course libsamplerate can be
97 used :-)).
98 <LI>It is the minimal program which can adequately display the problem.
99 <LI>It clearly displays the criteria for pass or fail.
100 </UL>
101<P>
102 Supplying a good test program will maximize the speed with which your bug
103 report gets dealt with.
104</P>
105
106<!-- pepper -->
107<!-- <A HREF="mailto:aldel0305@mega-nerd.com">For the spam bots</A> -->
108<!-- pepper -->
109
110</DIV>
111</TD></TR>
112</TABLE>
113
114</BODY>
115</HTML>
116
doc/download.html+0−89
@@ -1,89 +0,0 @@
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 <A HREF="license.html">License</A><BR>
31 <A HREF="history.html">History</A><BR>
32 <A HREF="download.html">Download</A><BR>
33 <A HREF="quality.html">Quality</A><BR>
34 <A HREF="api.html">API</A><BR>
35 <A HREF="bugs.html">Bug Reporting</A><BR>
36 <A HREF="win32.html">On Win32</A><BR>
37 <A HREF="faq.html">FAQ</A><BR>
38 <A HREF="lists.html">Mailing Lists</A><BR>
39 <A HREF="ChangeLog">ChangeLog</A><BR>
40<BR>
41<DIV CLASS="block">
42Author :<BR>Erik de Castro Lopo
43<!-- pepper -->
44<BR><BR>
45<!-- pepper -->
46
47</DIV>
48 <IMG SRC=
49 "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_dl.dat"
50 HEIGHT=30 WIDTH=100 ALT="counter.gif">
51</DIV>
52
53</TD>
54<!-- pepper -->
55<!-- ######################################################################## -->
56<!-- pepper -->
57<TD VALIGN="top">
58<DIV CLASS="block">
59
60<H1><B>Download</B></H1>
61<P>
62 The latest version of Secret Rabbit Code is 0.1.9.
63</P>
64<P>Download it on
65 <A HREF="https://github.com/libsndfile/libsamplerate/releases/latest">GitHub releases page</A>
66 and
67 <!-- A HREF="libsamplerate-0.1.8.tar.gz.asc">(GPG signature)</A -->
68
69</P>
70<P>
71 Compiling libsamplerate is relatively easy. The INSTALL file in the top
72 level directory gives instructions on compiling and installing
73 libsamplerate on Unix-like systems (including MacOSX). For Win32 there
74 are instructions in the doc/ directory of the tarball.
75 These instructions are mirrored
76 <A HREF="win32.html">here</A>.
77</P>
78
79<!-- pepper -->
80<!-- <A HREF="mailto:aldel0305@mega-nerd.com">For the spam bots</A> -->
81<!-- pepper -->
82
83</DIV>
84</TD></TR>
85</TABLE>
86
87</BODY>
88</HTML>
89
doc/faq.html+0−361
@@ -1,361 +0,0 @@
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 <A HREF="license.html">License</A><BR>
31 <A HREF="history.html">History</A><BR>
32 <A HREF="download.html">Download</A><BR>
33 <A HREF="quality.html">Quality</A><BR>
34 <A HREF="api.html">API</A><BR>
35 <A HREF="bugs.html">Bug Reporting</A><BR>
36 <A HREF="win32.html">On Win32</A><BR>
37 <A HREF="faq.html">FAQ</A><BR>
38 <A HREF="lists.html">Mailing Lists</A><BR>
39 <A HREF="ChangeLog">ChangeLog</A><BR>
40<BR>
41<DIV CLASS="block">
42Author :<BR>Erik de Castro Lopo
43<!-- pepper -->
44<BR><BR>
45<!-- pepper -->
46
47</DIV>
48 <IMG SRC=
49 "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_api.dat"
50 HEIGHT=30 WIDTH=100 ALT="counter.gif">
51</DIV>
52
53</TD>
54<!-- pepper -->
55<!-- ######################################################################## -->
56<!-- pepper -->
57<TD VALIGN="top">
58<DIV CLASS="block">
59
60<H1><B>Frequently Asked Questions</B></H1>
61<P>
62<A HREF="#Q001">Q1 : Is it normal for the output of libsamplerate to be louder
63 than its input?</A><BR><BR>
64<A HREF="#Q002">Q2 : On Unix/Linux/MacOSX, what is the best way of detecting
65 the presence and location of libsamplerate and its header file using
66 autoconf?</A><BR><BR>
67<A HREF="#Q003">Q3 : If I upsample and downsample to the original rate, for
68 example 44.1->96->44.1, do I get an identical signal as the one before the
69 up/down resampling?</A><BR><BR>
70<A HREF="#Q004">Q4 : If I ran src_simple (libsamplerate) on small chunks (160
71 frames) would that sound bad?</A><BR><BR>
72<A HREF="#Q005">Q5 : I'm using libsamplerate but the high quality settings
73 sound worse than the SRC_LINEAR converter. Why?</A><BR><BR>
74<A HREF="#Q006">Q6 : I'm use the SRC_SINC_* converters and up-sampling by a ratio of
75 2. I reset the converter and put in 1000 samples and I expect to get 2000
76 samples out, but I'm getting less than that. Why?</A><BR><BR>
77<A HREF="#Q007">Q7 : I have input and output sample rates that are integer
78 values, but the API wants me to divide one by the other and put the result
79 in a floating point number. Won't this case problems for long running
80 conversions?</A><BR><BR>
81</P>
82<HR>
83<!-- ========================================================================= -->
84<A NAME="Q001"></A>
85<H2><BR><B>Q1 : Is it normal for the output of libsamplerate to be louder
86 than its input?</B></H2>
87<P>
88The output of libsamplerate will be roughly the same volume as the input.
89However, even if the input is strictly in the range (-1.0, 1.0), it is still
90possible for the output to contain peak values outside this range.
91</P>
92<P>
93Consider four consecutive samples of [0.5 0.999 0.999 0.5].
94If we are up sampling by a factor of two we need to insert samples between
95each of the existing samples.
96Its pretty obvious then, that the sample between the two 0.999 values should
97and will be bigger than 0.999.
98</P>
99<P>
100This means that anyone using libsamplerate should normalize its output before
101doing things like saving the audio to a 16 bit WAV file.
102</P>
103
104<!-- pepper -->
105<!-- ========================================================================= -->
106
107<a NAME="Q002"></a>
108<h2><br><b>Q2 : On Unix/Linux/MacOSX, what is the best way of detecting
109 the presence and location of libsamplerate and its header file using
110 autoconf?</b></h2>
111
112<p>
113libsamplerate uses the pkg-config (man pkg-config) method of registering itself
114with the host system.
115The best way of detecting its presence is using something like this in configure.ac
116(or configure.in):
117</p>
118
119<pre>
120 PKG_CHECK_MODULES(SAMPLERATE, samplerate >= 0.1.3,
121 ac_cv_samplerate=1, ac_cv_samplerate=0)
122
123 AC_DEFINE_UNQUOTED([HAVE_SAMPLERATE],${ac_cv_samplerate},
124 [Set to 1 if you have libsamplerate.])
125
126 AC_SUBST(SAMPLERATE_CFLAGS)
127 AC_SUBST(SAMPLERATE_LIBS)
128</pre>
129<p>
130This will automatically set the <b>SAMPLERATE_CFLAGS</b> and <b>SAMPLERATE_LIBS</b>
131variables which can be used in Makefile.am or Makefile.in like this:
132</p>
133<pre>
134 SAMPLERATE_CFLAGS = @SAMPLERATE_CFLAGS@
135 SAMPLERATE_LIBS = @SAMPLERATE_LIBS@
136</pre>
137
138<p>
139If you install libsamplerate from source, you will probably need to set the
140<b>PKG_CONFIG_PATH</b> environment variable's suggested at the end of the
141libsamplerate configure process. For instance on my system I get this:
142</p>
143<pre>
144 -=-=-=-=-=-=-=-=-=-= Configuration Complete =-=-=-=-=-=-=-=-=-=-=-
145
146 Configuration summary :
147
148 Version : ..................... 0.1.3
149 Enable debugging : ............ no
150
151 Tools :
152
153 Compiler is GCC : ............. yes
154 GCC major version : ........... 3
155
156 Extra tools required for testing and examples :
157
158 Have FFTW : ................... yes
159 Have libsndfile : ............. yes
160 Have libefence : .............. no
161
162 Installation directories :
163
164 Library directory : ........... /usr/local/lib
165 Program directory : ........... /usr/local/bin
166 Pkgconfig directory : ......... /usr/local/lib/pkgconfig
167</pre>
168
169
170<!-- pepper -->
171<!-- ========================================================================= -->
172<A NAME="Q003"></A>
173<H2><BR><B>Q3 : If I upsample and downsample to the original rate, for
174 example 44.1->96->44.1, do I get an identical signal as the one before the
175 up/down resampling?</B></H2>
176<P>
177The short answer is that for the general case, no, you don't.
178The long answer is that for some signals, with some converters, you will
179get very, very close.
180</P>
181<P>
182In order to resample correctly (ie using the <B>SRC_SINC_*</B> converters),
183filtering needs to be applied, regardless of whether its upsampling or
184downsampling.
185This filter needs to attenuate all frequencies above 0.5 times the minimum of
186the source and destination sample rate (call this fshmin).
187Since the filter needed to achieve full attenuation at this point, it has to
188start rolling off a some frequency below this point.
189It is this rolloff of the very highest frequencies which causes some of the
190loss.
191</P>
192<P>
193The other factor is that the filter itself can introduce transient artifacts
194which causes the output to be different to the input.
195</P>
196
197<!-- pepper -->
198<!-- ========================================================================= -->
199<A NAME="Q004"></A>
200<H2><BR><B>Q4 : If I ran src_simple on small chunks (say 160 frames) would that
201sound bad?</B></H2>
202<P>
203Well if you are after odd sound effects, it might sound OK.
204If you are after high quality sample rate conversion you will be disappointed.
205</P>
206<P>
207The src_simple() was designed to provide a simple to use interface for people
208who wanted to do sample rate conversion on say, a whole file all at once.
209</P>
210
211<!-- pepper -->
212<!-- ========================================================================= -->
213<A NAME="Q005"></A>
214<H2><BR><B>Q5 : I'm using libsamplerate but the high quality settings
215 sound worse than the SRC_LINEAR converter. Why?</B></H2>
216<P>
217There are two possible problems.
218Firstly, if you are using the src_simple() function on successive blocks
219of a stream of samples, you will get bad results. The src_simple() function
220is designed for use on a whole sound file, all at once, not on contiguous
221segments of the same sound file.
222To fix the problem, you need to move to the src_process() API or the callback
223based API.
224</P>
225<P>
226If you are already using the src_process() API or the callback based API and
227the high quality settings sound worse than SRC_LINEAR, then you have other
228problems.
229Read on for more debugging hints.
230</P>
231<P>
232All of the higher quality converters need to keep state while doing conversions
233on segments of a large chunk of audio.
234This state information is kept inside the private data pointed to by the
235SRC_STATE pointer returned by the src_new() function.
236This means, that when you want to start doing sample rate conversion on a
237stream of data, you should call src_new() to get a new SRC_STATE pointer
238(or alternatively, call src_reset() on an existing SRC_STATE pointer).
239You should then pass this SRC_STATE pointer to the src_process() function
240with each new block of audio data.
241When you have completed the conversion, you can then call src_delete() on
242the SRC_STATE pointer.
243</P>
244<P>
245If you are doing all of the above correctly, you need to examine your usage
246of the values passed to src_process() in the
247 <A HREF="api_misc.html#SRC_DATA">SRC_DATA</A>
248struct.
249Specifically:
250</P>
251<UL>
252 <LI> Check that input_frames and output_frames fields are being set in
253 terms of frames (number of sample values times channels) instead
254 of just the number of samples.
255 <LI> Check that you are using the return values input_frames_used and
256 output_frames_gen to update your source and destination pointers
257 correctly.
258 <LI> Check that you are updating the data_in and data_out pointers
259 correctly for each successive call.
260</UL>
261<P>
262While doing the above, it is probably useful to compare what you are doing to
263what is done in the example programs in the examples/ directory of the source
264code tarball.
265</P>
266<P>
267If you have done all of the above and are still having problems then its
268probably time to email the author with the smallest chunk of code that
269adequately demonstrates your problem.
270This chunk should not need to be any more than 100 lines of code.
271</P>
272
273<!-- pepper -->
274<!-- ========================================================================= -->
275<A NAME="Q006"></A>
276<H2><BR><B>Q6 : I'm use the SRC_SINC_* converters and up-sampling by a ratio of
277 2. I reset the converter and put in 1000 samples and I expect to get 2000
278 samples out, but I'm getting less than that. Why?</B></H2>
279<P>
280The short answer is that there is a transport delay inside the converter itself.
281Long answer follows.
282</P>
283<P>
284By way of example, the first time you call src_process() you might only get 1900
285samples out.
286However, after that first call all subsequent calls will probably get you about
2872000 samples out for every 1000 samples you put in.
288</P>
289<P>
290The main problems people have with this transport delay is that they need to read
291out an exact number of samples and the transport delay scews this up.
292The best way to overcome this problem is to always supply more samples on the
293input than is actually needed to create the required number of output samples.
294With reference to the example above, if you always supply 1500 samples at the
295input, you will always get 2000 samples at the output.
296You will always need to keep track of the number of input frames used on each
297call to src_process() and deal with these values appropriately.
298</P>
299
300<!-- pepper -->
301<!-- ========================================================================= -->
302<A NAME="Q007"></A>
303<H2><BR><B>Q7 : I have input and output sample rates that are integer
304 values, but the API wants me to divide one by the other and put the result
305 in a floating point number. Won't this case problems for long running
306 conversions?</B></H2>
307<P>
308The short answer is no, the precision of the ratio is many orders of magnitude
309more than is really needed.
310</P>
311<P>
312For the long answer, lets do come calculations.
313Firstly, the <tt>src_ratio</tt> field is double precision floating point number
314which has
315 <a href="http://en.wikipedia.org/wiki/Double_precision">
316 53 bits of precision</a>.
317</P>
318<P>
319That means that the maximum error in your ratio converted to a double is one
320bit in 2^53 which means the the double float value would be wrong by one sample
321after 9007199254740992 samples have passed or wrong by more than half a sample
322wrong after half that many (4503599627370496 samples) have passed.
323</P>
324<P>
325Now if for example our output sample rate is 96kHz then
326</P>
327<pre>
328 4503599627370496 samples at 96kHz is 46912496118 seconds
329 46912496118 seconds is 781874935 minutes
330 781874935 minutes is 13031248 hours
331 13031248 hours is 542968 days
332 542968 days is 1486 years
333</pre>
334<P>
335So, after 1486 years, the input will be wrong by more than half of one sampling
336period.
337</P>
338<p>
339All this assumes that the crystal oscillators uses to sample the audio stream
340is perfect.
341This is not the case.
342According to
343 <a href="http://www.ieee-uffc.org/freqcontrol/quartz/vig/vigcomp.htm">
344 this web site</a>,
345the accuracy of standard crystal oscillators (XO, TCXO, OCXO) is at best
3461 in 100 million.
347The <tt>src_ratio</tt> is therefore 45035996 times more accurate than the
348crystal clock source used to sample the original audio signal and any potential
349problem with the <tt>src_ratio</tt> being a floating point number will be
350completely swamped by sampling inaccuracies.
351</p>
352
353<!-- <A HREF="mailto:aldel@mega-nerd.com">For the spam bots</A> -->
354
355</DIV>
356</TD></TR>
357</TABLE>
358
359</BODY>
360</HTML>
361
doc/history.html+0−102
@@ -1,102 +0,0 @@
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 <A HREF="license.html">License</A><BR>
31 <A HREF="history.html">History</A><BR>
32 <A HREF="download.html">Download</A><BR>
33 <A HREF="quality.html">Quality</A><BR>
34 <A HREF="api.html">API</A><BR>
35 <A HREF="bugs.html">Bug Reporting</A><BR>
36 <A HREF="win32.html">On Win32</A><BR>
37 <A HREF="faq.html">FAQ</A><BR>
38 <A HREF="lists.html">Mailing Lists</A><BR>
39 <A HREF="ChangeLog">ChangeLog</A><BR>
40<BR>
41<DIV CLASS="block">
42Author :<BR>Erik de Castro Lopo
43<!-- pepper -->
44<BR><BR>
45<!-- pepper -->
46
47</DIV>
48 <IMG SRC=
49 "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src.dat"
50 HEIGHT=30 WIDTH=100 ALT="counter.gif">
51</DIV>
52
53</TD>
54<!-- pepper -->
55<!-- ######################################################################## -->
56<!-- pepper -->
57<TD VALIGN="top">
58<DIV CLASS="block">
59
60<H1><B>History</B></H1>
61<UL>
62 <LI>Version 0.0.0 (Oct 06 2002) First alpha release (friends and family only).
63 <LI>Version 0.0.2 (Oct 10 2002) Second alpha release (fools rush in ....).
64 <LI>...
65 <LI>Version 0.0.7 (Nov 17 2002) The last mono only version.
66 <LI>Version 0.0.9 (Nov 21 2002) Full multi channel support. First pass at
67 documentation. Still not ready for release.
68 <LI>Version 0.0.11 (Nov 26 2002) Incorporated some suggestions from Conrad
69 Parker.
70 <LI>Version 0.0.12 (Nov 28 2002) First public release.
71 <LI>Version 0.0.13 (Dec 03 2002) Fixes for MacOSX and Solaris.
72 <LI>Version 0.0.14 (Jan 13 2003) Now compiles on Win32. Major code speedup.
73 Minor bug fixes.
74 <LI>Version 0.0.15 (May 02 2003) Minor bug fixes.
75 <LI>Version 0.1.0 (Mar 14 2004) Add callback API, functions for short to
76 float and float to short conversion. Minor bug fixes.
77 <LI>Version 0.1.1 (Jul 17 2004) Callback API bug fix. Bugfix for aggressive
78 gcc-3.4 optimisations.
79 <LI>Version 0.1.2 (Sep 12 2004) Callback API reset bug fix.
80 <LI>Version 0.1.3 (Mar 23 2008) Huge quality improvements to two best SINC
81 based converters.
82 <LI>Version 0.1.4 (Jul 02 2008) Fix segfault when using extremely low
83 conversion ratios.
84 <LI>Version 0.1.5 (Jan 11 2009) Optimisation resulting in dramatic throughput
85 improvements
86 (<a href="http://www.mega-nerd.com/erikd/Blog/CodeHacking/SecretRabbitCode/rel_0_1_5.html">
87 See here.</a>).
88 <LI>Version 0.1.6 (Jan 27 2009) Minor bug fix in test suite (account for
89 rounding error on x86_64).
90 <LI>Version 0.1.7 (Feb 14 2009) Fix a segfault bug. Fix compilation under
91 MSVC.
92 <LI>Version 0.1.8 (Aug 15 2011) Minor bug fixes and updates.
93 <LI>Version 0.1.9 (Sep 19 2016) Fix for a segfault. Relicense under BSD license.
94</UL>
95
96</DIV>
97</TD></TR>
98</TABLE>
99
100</BODY>
101</HTML>
102
doc/index.html+0−129
@@ -1,129 +0,0 @@
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 <A HREF="license.html">License</A><BR>
31 <A HREF="history.html">History</A><BR>
32 <A HREF="download.html">Download</A><BR>
33 <A HREF="quality.html">Quality</A><BR>
34 <A HREF="api.html">API</A><BR>
35 <A HREF="bugs.html">Bug Reporting</A><BR>
36 <A HREF="win32.html">On Win32</A><BR>
37 <A HREF="faq.html">FAQ</A><BR>
38 <A HREF="lists.html">Mailing Lists</A><BR>
39 <A HREF="ChangeLog">ChangeLog</A><BR>
40<BR>
41<DIV CLASS="block">
42Author :<BR>Erik de Castro Lopo
43<!-- pepper -->
44<BR><BR>
45<!-- pepper -->
46
47</DIV>
48 <IMG SRC=
49 "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src.dat"
50 HEIGHT=30 WIDTH=100 ALT="counter.gif">
51</DIV>
52
53</TD>
54<!-- pepper -->
55<!-- ######################################################################## -->
56<!-- pepper -->
57<TD VALIGN="top">
58<DIV CLASS="block">
59<BR>
60
61<TABLE ALIGN="center" WIDTH="80%">
62<TR><TD>
63<P>
64 <I>
65 "Choosing a sample rate coverter wasn't easy. We ran numerous tests with
66 Secret Rabbit Code and other sample rate converters, then compared them all.
67 In the end, SRC outperformed the others, including some extremely well known
68 and popular software. We had one issue with SRC, but after emailing Erik, he
69 got back to us immediately with an answer. Choosing SRC was a no brainer."
70 </I><BR>
71 Ryan Smith, International Marketing Manager, <BR>
72 <A HREF="http://emersys.co.kr/">Emersys Corp.</A>, South Korea.<BR>
73 Product : <A HREF="http://maven3d.com">Maven3D</A>
74
75</P>
76</TD></TR>
77</TABLE>
78<P>
79 <B>S</B>ecret <B>R</B>abbit <B>C</B>ode (aka libsamplerate) is a
80 <B>S</B>ample <B>R</B>ate <B>C</B>onverter for audio.
81 One example of where such a thing would be useful is converting audio
82 from the CD sample rate of 44.1kHz to the 48kHz sample rate used by
83 DAT players.
84</P>
85<!-- pepper -->
86<P>
87 <B>SRC</B> is capable of arbitrary and time varying conversions ; from
88 downsampling by a factor of 256 to upsampling by the same factor.
89 Arbitrary in this case means that the ratio of input and output
90 sample rates can be an irrational number.
91 The conversion ratio can also vary with time for speeding up and slowing
92 down effects.
93</P>
94<!-- pepper -->
95<P>
96 <B>SRC</B> provides a small set of converters to allow quality to
97 be traded off against computation cost.
98 The current best converter provides a signal-to-noise ratio of 145dB
99 with -3dB passband extending from DC to 96&#37; of the theoretical
100 best bandwidth for a given pair of input and output sample rates.
101</P>
102<!-- pepper -->
103<P>
104 Since the library has few dependencies beyond that provided by the
105 standard C library, it should compile and work on just about any
106 operating system.
107 It is known to work on Linux, MacOSX,
108 <A HREF="win32.html">Win32</A>
109 and Solaris.
110 With some relatively minor hacking it should also be relatively easy
111 to port it to embedded systems and digital signal processors.
112</P>
113<!-- pepper -->
114<P>
115 In addition, the library comes with a comprehensive test suite which
116 can validate the performance of the library on new platforms.
117</P>
118
119<!-- pepper -->
120<!-- <A HREF="mailto:aldel0305@mega-nerd.com">For the spam bots</A> -->
121<!-- pepper -->
122
123</DIV>
124</TD></TR>
125</TABLE>
126
127</BODY>
128</HTML>
129
doc/license.html+0−80
@@ -1,80 +0,0 @@
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 <A HREF="license.html">License</A><BR>
31 <A HREF="history.html">History</A><BR>
32 <A HREF="download.html">Download</A><BR>
33 <A HREF="quality.html">Quality</A><BR>
34 <A HREF="api.html">API</A><BR>
35 <A HREF="bugs.html">Bug Reporting</A><BR>
36 <A HREF="win32.html">On Win32</A><BR>
37 <A HREF="faq.html">FAQ</A><BR>
38 <A HREF="lists.html">Mailing Lists</A><BR>
39 <A HREF="ChangeLog">ChangeLog</A><BR>
40 <BR>
41<DIV CLASS="block">
42Author :<BR>Erik de Castro Lopo
43<!-- pepper -->
44<BR><BR>
45<!-- pepper -->
46
47</DIV>
48 <IMG SRC=
49 "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_lic.dat"
50 HEIGHT=30 WIDTH=100 ALT="counter.gif">
51</DIV>
52
53</TD>
54<!-- pepper -->
55<!-- ######################################################################## -->
56<!-- pepper -->
57<TD VALIGN="top">
58<DIV CLASS="block">
59
60<H1><B>License</B></H1>
61<!-- pepper -->
62<P>
63 From its first release in 2002, Secret Rabbit Code was under a dual
64 licensing scheme where people could chose to use it under the terms
65 of the GNU General Public License or pay for a commercial use
66 license.
67</P>
68<!-- pepper -->
69<P>
70 In 2016, thanks to a generous offer from Epic Games International,
71 Secret Rabbit Code was relicensed under the 2-clause BSD license.
72</P>
73<!-- pepper -->
74</DIV>
75</TD></TR>
76</TABLE>
77
78</BODY>
79</HTML>
80
doc/lists.html+0−91
@@ -1,91 +0,0 @@
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 <A HREF="license.html">License</A><BR>
31 <A HREF="history.html">History</A><BR>
32 <A HREF="download.html">Download</A><BR>
33 <A HREF="quality.html">Quality</A><BR>
34 <A HREF="api.html">API</A><BR>
35 <A HREF="bugs.html">Bug Reporting</A><BR>
36 <A HREF="win32.html">On Win32</A><BR>
37 <A HREF="faq.html">FAQ</A><BR>
38 <A HREF="lists.html">Mailing Lists</A><BR>
39 <A HREF="ChangeLog">ChangeLog</A><BR>
40<BR>
41<DIV CLASS="block">
42Author :<BR>Erik de Castro Lopo
43<!-- pepper -->
44<BR><BR>
45<!-- pepper -->
46
47</DIV>
48 <IMG SRC=
49 "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_lists.dat"
50 HEIGHT=30 WIDTH=100 ALT="counter.gif">
51</DIV>
52
53</TD>
54<!-- pepper -->
55<!-- ######################################################################## -->
56<!-- pepper -->
57<TD VALIGN="top">
58<DIV CLASS="block">
59
60<H1><B>Mailing Lists</B></H1>
61<P>
62There are currently two mailings lists for Secret Rabbit Code:<!-- pepper -->
63</P>
64<!-- pepper -->
65<UL>
66 <LI><B>sr&#99;-ann&#111;un&#99;e@mega-nerd.&#99;&#111;m</B>&nbsp;&nbsp;<!-- pepper -->
67
68 <A HREF="m&#97;ilt&#111;:sr&#99;-announ&#99;e-request@meg&#97;-nerd.&#99;om?subject=subscribe">Subscribe</A>
69 <BR>
70 A read only announcement list.<!-- pepper -->
71 <BR><BR>
72 <LI><B>sr&#99;@mega-nerd.&#99;&#111;m</B>&nbsp;&nbsp;<!-- pepper -->
73 <A HREF="m&#97;ilt&#111;:sr&#99;-request@meg&#97;-nerd.&#99;om?subject=subscribe">Subscribe</A>
74 <BR>
75 A general list which will also carry all the email from the announce list.
76 Posting to this list is restricted to subscribers. <!-- pepper -->
77</UL>
78<!-- pepper -->
79<P>
80
81</DIV>
82</TD></TR>
83</TABLE>
84
85<!-- pepper -->
86<!-- pepper -->
87<!-- pepper -->
88
89</BODY>
90</HTML>
91
doc/quality.html+0−179
@@ -1,179 +0,0 @@
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 <A HREF="license.html">License</A><BR>
31 <A HREF="history.html">History</A><BR>
32 <A HREF="download.html">Download</A><BR>
33 <A HREF="quality.html">Quality</A><BR>
34 <A HREF="api.html">API</A><BR>
35 <A HREF="bugs.html">Bug Reporting</A><BR>
36 <A HREF="win32.html">On Win32</A><BR>
37 <A HREF="faq.html">FAQ</A><BR>
38 <A HREF="lists.html">Mailing Lists</A><BR>
39 <A HREF="ChangeLog">ChangeLog</A><BR>
40<BR>
41<DIV CLASS="block">
42Author :<BR>Erik de Castro Lopo
43<!-- pepper -->
44<BR><BR>
45<!-- pepper -->
46
47</DIV>
48 <IMG SRC=
49 "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_qual.dat"
50 HEIGHT=30 WIDTH=100 ALT="counter.gif">
51</DIV>
52
53</TD>
54<!-- pepper -->
55<!-- ######################################################################## -->
56<!-- pepper -->
57<TD VALIGN="top">
58<DIV CLASS="block">
59
60<H1><B>SRC Quality</B></H1>
61<CENTER><P>
62 <B>This document not yet complete.</B><BR>
63</P></CENTER>
64<P>
65 When measuring the performance of a Sample Rate Converter, there are three
66 factors to consider:
67</P>
68<UL>
69 <LI><B>Signal-to-Noise Ratio</B> - a measure of how much noise the sample
70 rate conversion process adds to the signal.
71 This is measured in decibels (dB) and the higher this value the
72 better.
73 For most sample rate converters, the SNR will vary depending on
74 the input signal and the ratio between input and output sample
75 rates.
76 The only valid comparison of SNR is between the worst case for
77 for each converter.
78 <LI><B>Bandwidth</B> - most sample rate converters attenuate high
79 frequencies as part of their operation.
80 Bandwidth can be measured by finding the frequency where the
81 attenuation is 3dB and expressing that as a percentage of the full
82 bandwidth at that sampling rate.
83 <LI><B>Speed</B> - the faster the better <B>:-)</B>.
84</UL>
85
86<P>
87 There are a number of sample rate converters available for downloading
88 but I will limit the comparison ot Secret Rabbit Code to the following:
89</P>
90<UL>
91 <LI><A HREF="http://libsndfile.github.io/libsamplerate/download.html">sndfile-resample</A>
92 which is a program (which uses libsamplerate) from the <B>examples/</B>
93 directory of the Secret Rabbit Code source code distribution.
94 <LI><A HREF="https://ccrma.stanford.edu/~jos/resample/">
95 Resample</A>
96 by Julius O Smiths which seems to have been the first high quality converter
97 available as source code.
98 <LI><A HREF="http://www.tsp.ece.mcgill.ca/MMSP/Documents/Software/AFsp/ResampAudio.html">ResampAudio</A>
99 which is part of
100 <A HREF="http://www.tsp.ece.mcgill.ca/MMSP/Documents/Software/AFsp/AFsp.html">
101 Audio File Programs and Routines</A>
102 by Peter Kabal.
103 <LI><A HREF="http://home.sprynet.com/~cbagwell/sox.html">SoX</A> which is maintained
104 by Chris Bagwell.
105 SoX is also able to perform some low quality sample rate conversions but these
106 will not be investigated.
107 <LI><A HREF="http://shibatch.sourceforge.net/">Shibatch</A> which seems to be a
108 frequency domain sample rate converter.
109 Unfortunately, this converter does not handle arbitrary conversion ratios and
110 hence could not be properly compared to the other converters.
111 <LI><A HREF="http://sr-convert.sourceforge.net/">sr-convert</A> is another
112 converter which does not handle arbitrary conversion ratios.
113</UL>
114
115<P>
116It should be noted that the first three converters above are based on the algorithm
117by <A HREF="http://www-ccrma.stanford.edu/~jos/resample/"> Julius O. Smith</A>
118which emulates the conversion of the digital signal to an analogue one and then
119sampling the analogue signal at the new sample rate.
120</P>
121
122<!--+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-->
123
124<H3><B>Methodology</B></H3>
125<P>
126 Measuring the SNR of a converter is relatively straight forward.
127 Generate an input signal consisting of a windowed sine wave, sample rate
128 convert it and measure the signal-to-noise ratio of the output signal.
129 A typical length for the original file is 30000 samples.
130</P>
131<P>
132 The bandwidth of a sample rate converter is a little more difficult to measure.
133 Currently this is done by generating two short files containing a windowed
134 sine wave.
135 The frequencies of the sine waves are 0.35 and 0.495 of the sample rate.
136 These file are then upsampled by a factor of 2 using the converter under test.
137 If the attenutaion of the lower frquency is less than 3dB and higher frequency is
138 more than 3dB, it is then possible to iteratively increase the lower frequency
139 and decrease the upper frequency keeping the -3dB point bracketed.
140 When the distance between the upper and lower frequency is sufficiently small,
141 it is possible to obtain a very accurate estimate of the -3dB frequency.
142</P>
143<P>
144 The speed of a sample rate converter is easy to measure; simply perform a
145 conversion on a large file or a number of smaller files and time the conversion
146 process.
147</P>
148
149<P>
150 The above measurement techniques are built into a test program which is delivered
151 with the Secret Rabbit Code source code distibution.
152 This program is able to test the first four of the above converters.
153</P>
154<!--+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-->
155
156<H3><B>SoX</B></H3>
157<P>
158 SoX provides three methods of resampling; a linear interpolator, a polyphase
159 resampler and the Julius O. Smith simulated analogue filter method.
160</P>
161
162<H3><B>Shibatch</B></H3>
163<P>
164 Shibach
165</P>
166
167<P>
168 <B>More Coming Soon.</B>
169</P>
170
171<!-- <A HREF="mailto:aldel@mega-nerd.com">For the spam bots</A> -->
172
173</DIV>
174</TD></TR>
175</TABLE>
176
177</BODY>
178</HTML>
179
doc/win32.html+0−99
@@ -1,99 +0,0 @@
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 <A HREF="license.html">License</A><BR>
31 <A HREF="history.html">History</A><BR>
32 <A HREF="download.html">Download</A><BR>
33 <A HREF="quality.html">Quality</A><BR>
34 <A HREF="api.html">API</A><BR>
35 <A HREF="bugs.html">Bug Reporting</A><BR>
36 <A HREF="win32.html">On Win32</A><BR>
37 <A HREF="faq.html">FAQ</A><BR>
38 <A HREF="lists.html">Mailing Lists</A><BR>
39 <A HREF="ChangeLog">ChangeLog</A><BR>
40<BR>
41<DIV CLASS="block">
42Author :<BR>Erik de Castro Lopo
43<!-- pepper -->
44<BR><BR>
45<!-- pepper -->
46
47</DIV>
48 <IMG SRC=
49 "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_win32.dat"
50 HEIGHT=30 WIDTH=100 ALT="counter.gif">
51</DIV>
52
53</TD>
54<!-- pepper -->
55<!-- ######################################################################## -->
56<!-- pepper -->
57<TD VALIGN="top">
58<DIV CLASS="block">
59
60<H1>Compiling on Win32</H1>
61<P>
62 You can use <A HREF="https://cmake.org/">CMake</A> to generate Visual Studio project.
63 The configuration process is described <A HREF="https://cmake.org/runningcmake/">here</A>.
64</P>
65<P>
66 The libsamplerate library itself does not require any dependencies, but if you want to build
67 examples and tests, you will need the <A HREF="https://github.com/libsndfile/libsndfile">libsndfile</A>
68 and <A HREF="http://www.fftw.org/">FFTW</A> libraries. The easiest way to install them is to use a package
69 manager, such as <A HREF="">Vcpkg</A>. Their README.md contains detailed installation instructions for
70 supported platforms. Libsamplerate requires the <CODE>libsndfile</CODE> and <CODE>fftw3</CODE> packages.
71</P>
72<BR>
73
74<!--
75
76From here:
77
78 http://www.gimp.org/~tml/gimp/win32/downloads.html
79
80Download these files:
81
82 gettext-runtime-0.13.1.zip
83 glib-2.4.5-20040903.zip
84 libiconv-1.9.1.bin.woe32.zip
85 pkgconfig-0.15.zip
86
87and install them.
88
89-->
90
91<!-- <A HREF="mailto:aldel@mega-nerd.com">For the spam bots</A> -->
92
93</DIV>
94</TD></TR>
95</TABLE>
96
97</BODY>
98</HTML>
99
docs/SRC.css+48−0
@@ -0,0 +1,48 @@
1a:link {
2 color: #FB1465;
3}
4
5a:active, a:visited {
6 color: #FB1465;
7}
8
9body {
10 background: black;
11 color: white;
12 font-family: arial, helvetica, sans-serif;
13}
14
15h1, h2, h3, h4, h5, h6 {
16 color: #FB1465;
17}
18
19code, kbd, samp, var {
20 font-family: courier, monospace;
21 font-size: 1em;
22}
23
24main {
25 padding-left: 3%;
26 padding-right: 3%;
27}
28
29pre {
30 font-family: courier, monospace;
31 font-size: 1em;
32}
33
34.image-logo {
35 display: block;
36 margin-left: auto;
37 margin-right: auto;
38 margin-bottom: 1em;
39}
40
41.indent_block {
42 margin-left: 10%;
43 margin-right: 10%;
44}
45
46.nf {
47 font-weight: bold;
48}
docs/SRC.pngrenamed from doc/SRC.png+0−0

File renamed without changes.

docs/_config.yml+8−0
@@ -0,0 +1,8 @@
1---
2author: Erik de Castro Lopo, erikd@mega-nerd.com
3description: An audio Sample Rate Conversion library
4keywords: libsamplerate, sound, resample, audio, dsp, Linux
5version: 0.1.8
6
7markdown: kramdown
8---
docs/_layouts/default.html+51−0
@@ -0,0 +1,51 @@
1<!DOCTYPE html">
2<html lang="en">
3
4<head>
5 <meta charset="utf-8">
6 <meta name="viewport" content="width=device-width, initial-scale=1.0">
7 <meta name="description" content="{{ site.description | page.description }}">
8 <meta name="keywords" content="{{ site.keywords | page.keywords }}">
9 <title>{{ page.title }}</title>
10 <link rel="stylesheet" href="SRC.css" type="text/css" media="all">
11</HEAD>
12
13<body>
14 <footer>
15 <img src="SRC.png" class="image-logo" height=100 width=760 alt="SRC.png">
16 </footer>
17 <table align="center" width="98%">
18 <tr>
19 <td valign="top">
20 <nav>
21 <a href="index.html">Home</a><br>
22 <a href="license.html">License</a><br>
23 <a href="history.html">History</a><br>
24 <a href="download.html">Download</a><br>
25 <a href="quality.html">Quality</a><br>
26 <a href="api.html">API</a><br>
27 <a href="bugs.html">Bug Reporting</a><br>
28 <a href="win32.html">On Win32</a><br>
29 <a href="faq.html">FAQ</a><br>
30 <a href="lists.html">Mailing Lists</a><br>
31 <a href="https://github.com/libsndfile/libsamplerate/blob/master/ChangeLog">ChangeLog</a><br>
32 <nav>
33 <div class="block">
34 <p>Author:<br>&nbsp;Erik&nbsp;de&nbsp;Castro&nbsp;Lopo</p>
35 </div>
36 </td>
37 <td valign="top">
38 <main>
39 <article>
40
41 {{ content }}
42
43 </article>
44 </main>
45 </td>
46 </tr>
47 </table>
48
49</body>
50
51</html>
docs/api.md+46−0
@@ -0,0 +1,46 @@
1---
2layout: default
3---
4
5# Applications Programming Interface
6
7The publically callable functions of libsamplerate are all listed in the
8**\<samplerate.h\>** header file. In order to use any of the functionality of
9libsamplerate, you need to add
10
11```c
12#include <samplerate.h>
13```
14
15to the top of any function that call any of the following functions. You will
16also need to link you binary with the libsamplerate library.
17
18The API allows three methods for accessing the capabilies of the library:
19
20- A [simple interface](api_simple.md) which can sample rate convert a single
21 block of samples (one or more channels) in one go. The simple API is less
22 capable than the full API.
23- A [more fully featured interface](api_full.md) which allows time varying
24 sample rate conversion on streaming data (again one or more channels).
25- A [callback interface](api_callback.md) which has the same functionality as
26 the interface above but allows the details of input and output to be
27 separated. The output is generated by call a read function and the library
28 calls a user supplied callback function to obtain its input. This interface is
29 particularly well suited to applications where the output sample rate is
30 varied with time.
31
32**NB :** All three access methods are able to process multi channel interleaved
33data.
34
35The parts of the API which are common to all three interfaces are:
36
37- The [error reporting](api_misc.md#error-reporting) mechanisim.
38- The available [converter](api_misc.md#converters) types.
39- The [SRC_DATA](api_misc.md#src_data) struct.
40
41All three versions of the API are restricted to operating on buffers of ISO C
42Standard **float** data. However, there are two [auxillary functions](api_misc.md#auxillary-functions)
43for converting arrays of float data to and from short data.
44
45**Note:** The **tests/** and **examples/** directories of the source code
46distribution contain numerous example programs showing the use of the library.
docs/api_callback.md+88−0
@@ -0,0 +1,88 @@
1---
2layout: default
3---
4
5# Callback API
6
7The callback API consists of the following functions :
8
9```c
10typedef long (*src_callback_t) (void *cb_data, float **data) ;
11
12SRC_STATE* src_callback_new (src_callback_t func,
13 int converter_type, int channels,
14 int *error, void* cb_data) ;
15
16SRC_STATE* src_delete (SRC_STATE *state) ;
17
18long src_callback_read (SRC_STATE *state, double src_ratio,
19 long frames, float *data) ;
20
21int src_reset (SRC_STATE *state) ;
22int src_set_ratio (SRC_STATE *state, double new_ratio) ;
23```
24
25Like the [simple API](api_simple.md) and the [full API](api_full.md), the
26callback based API is able to operate on interleaved multi channel data.
27
28An example of the use of the callback based API can be found in the
29**varispeed-play** program in the **examples/** directory of the source code
30tarball.
31
32## Initialisation
33
34```c
35SRC_STATE* src_callback_new (src_callback_t func,
36 int converter_type, int channels,
37 int *error, void* cb_data) ;
38```
39
40The **src_callback_new** function returns an anonymous pointer to a sample rate
41converter callback object, src_state. This is the same type of object as that
42returned by [src\_new](api_full.md#initialisation), but with different internal
43state. Although these are the same object type, they cannot be used
44interchangeably. If an error occurs the function returns a NULL pointer and
45fills in the error value pointed to by the **error** pointer supplied by the
46caller.
47
48The caller then passes the SRC_STATE object to the **src_callback_read**
49function to pull data out of the converter. When the caller is finished with the
50converter they should pass it to the clean up function [src_delete](api_full.md#cleanup).
51
52The **func** parameter is a user supplied function which must match the
53**src_callback_t** type signature while **cb_data** is a pointer to data which
54be passed as the first parameter to the user supplied callback function. This
55function is called by the converter whenever it needs input data as a result of
56being calls to **src_callback_read**.
57
58If the converter was initialised to work with more than one channel, the
59callback function must work with mutiple channels of interleaved data. The
60callback function should return the number of frames it supplying to the
61converter. For multi channel files, this return value should be the number of
62floats divided by the number of channels.
63
64The converter must be one of the supplied converter types documented [here](api_misc.md#converters).
65
66The caller then passes the SRC_STATE pointer to the **src_callback_read**
67function to pull data out of the converter.
68
69## Callback Read
70
71```c
72long src_callback_read (SRC_STATE *state, double src_ratio,
73 long frames, float *data) ;
74```
75
76The **src_callback_read** function is passed the [**SRC_STATE**](api_misc.md#src_data)
77pointer returned by **src_callback_new**, the coversion ratio
78(output_sample_rate / input_sample_rate), the maximum number of output frames to
79generate and a pointer to a buffer in which to place the output data. For multi
80channel files, the data int the output buffer is stored in interleaved format.
81
82The **src_callback_read** function returns the number of frames generated or
83zero if an error occurs or it runs out of input (ie the user supplied callback
84function returns zero and there is no more data buffered internally). If an
85error has occurred, the function [src_error](api_misc.md#error-reporting)
86will return non-zero.
87
88See also : [**src_set_ratio**](api_full.md#set-ratio)
docs/api_full.md+146−0
@@ -0,0 +1,146 @@
1---
2layout: default
3---
4
5# Full API
6
7The full API consists of the following functions :
8
9```c
10SRC_STATE* src_new (int converter_type, int channels, int *error) ;
11SRC_STATE* src_delete (SRC_STATE *state) ;
12
13int src_process (SRC_STATE *state, SRC_DATA *data) ;
14int src_reset (SRC_STATE *state) ;
15int src_set_ratio (SRC_STATE *state, double new_ratio) ;
16```
17
18## Initialisation
19
20```c
21SRC_STATE* src_new (int converter_type, int channels, int *error) ;
22```
23
24The **src\_new** function returns an anonymous pointer to a sample rate
25converter object, src\_state. If an error occurs the function returns a
26NULL pointer and fills in the error value pointed to by the **error**
27pointer supplied by the caller. The converter must be one of the
28supplied converter types documented [here](api_misc.md#converters).
29
30## Cleanup
31
32```c
33SRC_STATE* src_delete (SRC_STATE *state) ;
34```
35
36The **src\_delete** function frees up all memory allocated for the given
37sample rate converter object and returns a NULL pointer. The caller is
38responsible for freeing any memory passed to the sample rate converter
39via the pointer to the **SRC\_DATA** struct.
40
41## Process
42
43```c
44int src_process (SRC_STATE *state, SRC_DATA *data) ;
45```
46
47The **src\_process** function processes the data provided by the caller
48in an **SRC\_DATA** struct using the sample rate converter object
49specified by the **SRC\_STATE** pointer. When operating on streaming
50data, this function can be called over and over again, with each new
51call providing new input data and returning new output data.
52
53The **SRC\_DATA** struct passed as the second parameter to the
54**src\_process** function has the following fields:
55
56```c
57typedef struct
58{ const float *data_in;
59 float *data_out;
60
61 long input_frames, output_frames ;
62 long input_frames_used, output_frames_gen ;
63
64 int end_of_input ;
65
66 double src_ratio ;
67} SRC_DATA ;
68```
69
70The fields of this struct which must be filled in by the caller are:
71
72data_in
73: A pointer to the input data samples.
74
75input_frames
76: The number of frames of data pointed to by data_in.
77
78data_out
79: A pointer to the output data samples.
80
81output_frames
82: Maximum number of frames pointer to by data_out.
83
84src_ratio
85: Equal to output_sample_rate / input_sample_rate.
86
87end_of_input
88: Equal to 0 if more input data is available and 1 otherwise.
89
90Note that the data\_in and data\_out arrays may not overlap. If they do,
91the library will return an error code.
92
93When the **src\_process** function returns **output\_frames\_gen** will
94be set to the number of output frames generated and
95**input\_frames\_used** will be set to the number of input frames
96consumed to generate the provided number of output frames.
97
98The **src\_process** function returns non-zero if an error occurs. The
99non-zero error return value can be decoded into a text string using the
100function documented [here](api_misc.md#error-reporting).
101
102## Reset
103
104```c
105int src_reset (SRC_STATE *state) ;
106```
107
108The **src\_reset** function resets the internal state of the sample rate
109converter object to the same state it had immediately after its creation
110using **src\_new**. This should be called whenever a sample rate
111converter is to be used on two separate, unrelated pieces of audio.
112
113## Clone
114
115```c
116SRC_STATE* src_clone (SRC_STATE *state, int *error) ;
117```
118
119The **src_clone** function creates a copy of the internal state of the sample
120rate converter object. The output of the next call to **src\_process** will be
121identical for both the original and cloned state (given the same **SRC_DATA**
122input). This could be used to later resume sample rate conversion at a specific
123location in a stream with the same state, which may be useful in real-time
124applications.
125
126If an error occurs the function returns a NULL pointer and fills in the
127error value pointed to by the **error** pointer supplied by the caller.
128
129## Set Ratio
130
131```c
132int src_set_ratio (SRC_STATE *state, double new_ratio) ;
133```
134
135When using the **src_process** or **src_callback_process** APIs and updating the
136**src_ratio** field of the **SRC_STATE** struct, the library will try to
137smoothly transition between the conversion ratio of the last call and the
138conversion ratio of the current call.
139
140If the user want to bypass this smooth transition and achieve a step response in
141the conversion ratio, the **src_set_ratio** function can be used to set the
142starting conversion ratio of the next call to **src_process** or
143**src_callback_process**.
144
145This function returns non-zero on error and the error return value can be
146decoded into a text string using the function documented [here](api_misc.md#error-reporting).
docs/api_misc.md+143−0
@@ -0,0 +1,143 @@
1---
2layout: default
3---
4
5# Miscellaneous API Documentation
6
7## Error Reporting
8
9Most of the API functions either return an integer error (ie **src_simple** and
10**src_process**) or return an integer error value via an int pointer parameter
11(**src_new**). These integer error values can be converted into a human readable
12text strings by calling the function:
13
14```c
15const char* src_strerror (int error) ;
16```
17
18which will return an error string for valid error numbers, the string
19\"No Error\" for an error value of zero or a NULL pointer if no error message
20has been defined for that error value.
21
22## Converters
23
24Secret Rabbit Code has a number of different converters which can be selected
25using the **converter_type** parameter when calling **src_simple** or
26**src_new**. Currently, the five converters available are:
27
28```c
29enum
30{
31 SRC_SINC_BEST_QUALITY = 0,
32 SRC_SINC_MEDIUM_QUALITY = 1,
33 SRC_SINC_FASTEST = 2,
34 SRC_ZERO_ORDER_HOLD = 3,
35 SRC_LINEAR = 4
36} ;
37```
38
39As new converters are added, they will given a number corresponding to the next
40integer.
41
42The details of these converters are as follows:
43
44- **SRC_SINC_BEST_QUALITY** - This is a bandlimited interpolator derived from
45 the mathematical **sinc** function and this is the highest quality sinc based
46 converter, providing a worst case Signal-to-Noise Ratio (SNR) of 97 decibels
47 (dB) at a bandwidth of 97%. All three SRC_SINC_* converters are based on the
48 techniques of [Julius O. Smith](http://ccrma.stanford.edu/~jos/resample/)
49 although this code was developed independantly.
50- **SRC_SINC_MEDIUM_QUALITY** - This is another bandlimited interpolator much
51 like the previous one. It has an SNR of 97dB and a bandwidth of 90%. The speed
52 of the conversion is much faster than the previous one.
53- **SRC_SINC_FASTEST** - This is the fastest bandlimited interpolator and has an
54 SNR of 97dB and a bandwidth of 80%.
55- **SRC_ZERO_ORDER_HOLD** - A Zero Order Hold converter (interpolated value is
56 equal to the last value). The quality is poor but the conversion speed is
57 blindlingly fast.
58- **SRC_LINEAR** - A linear converter. Again the quality is poor, but the
59 conversion speed is blindingly fast.
60
61There are two functions that give either a (text string) name or description for
62each converter:
63
64```c
65const char *src_get_name (int converter_type) ;
66const char *src_get_description (int converter_type) ;
67```
68
69The name will typically be a short string for use in a dialog box, while the
70description string is longer.
71
72Both of these functions return a NULL pointer if there is no converter for the
73given **converter_type** value. Since the converters have consecutive
74**converter_type** values, the caller is easily able to figure out the number of
75converters at run time. This enables a binary dynamically linked against an old
76version of the library to know about converters from later versions of the
77library as they become available.
78
79## SRC_DATA
80
81Both the simple and the full featured versions of the API use the **SRC_DATA**
82struct to pass audio and control data into the sample rate converter. This
83struct is defined as:
84
85```c
86typedef struct
87{ const float *data_in;
88 float *data_out ;
89
90 long input_frames, output_frames ;
91 long input_frames_used, output_frames_gen ;
92
93 int end_of_input ;
94
95 double src_ratio ;
96} SRC_DATA ;
97```
98
99The **data_in** pointer is used to pass audio data into the converter while the
100**data_out** pointer supplies the converter with an array to hold the
101converter's output. For a converter which has been configured for mulitchannel
102operation, these pointers need to point to a single array of interleaved data.
103
104The **input_frames** and **output_frames** fields supply the converter with the
105lengths of the arrays (in frames) pointed to by the **data_in** and **data_out**
106pointers respectively. For monophinc data, these values would indicate the
107length of the arrays while for multi channel data these values would be equal to
108the the length of the array divided by the number of channels.
109
110The **end_of_input** field is only used when the sample rate converter is used
111by calling the **src_process** function. In this case it should be set to zero
112if more buffers are to be passed to the converter and 1 if the current buffer is
113the last.
114
115Finally, the **src_ratio** field specifies the conversion ratio defined as the
116output sample rate divided by the input sample rate. For a connected set of
117buffers, this value can be varies on each call to **src_process** resulting in a
118time varying sample rate conversion process. For time varying sample rate
119conversions, the ratio will be linearly interpolated between the **src_ratio**
120value of the previous call to **src_process** and the value for the current
121call.
122
123The **input_frames_used** and **output_frames_gen** fields are set by the
124converter to inform the caller of the number of frames consumed from the
125**data_in** array and the number of frames generated in the **data_out** array
126respectively. These values are for the current call to **src_process** only.
127
128## Auxillary Functions
129
130There are four auxillary functions for converting arrays of float data to and
131from short or int data. These functions are defined as:
132
133```c
134void src_short_to_float_array (const short *in, float *out, int len) ;
135void src_float_to_short_array (const float *in, short *out, int len) ;
136void src_int_to_float_array (const int *in, float *out, int len) ;
137void src_float_to_int_array (const float *in, int *out, int len) ;
138```
139
140The float data is assumed to be in the range [-1.0, 1.0] and it is automatically
141scaled on the conversion to and from float. On the float to short/int conversion
142path, any data values which would overflow the range of short/int data are
143clipped.
docs/api_simple.md+71−0
@@ -0,0 +1,71 @@
1---
2layout: default
3---
4
5# Simple API
6
7**Important Note:** The simple API is not designed to work on small chunks of a
8larger piece of audio. If you attempt to use it this way you are doing it wrong
9and will not get the results you want. For processing audio data in chunks you
10**must** use the [full api](api_full.md) or the [callback based api](api_callback.md).
11
12The simple API consists of a single function:
13
14```c
15int src_simple (SRC_DATA *data, int converter_type, int channels) ;
16```
17
18The use of this function rather than the more fully featured API requires the
19caller to know the total length of the input data before hand and that all input
20and output data can be held in the system's memory at once. It also assumes that
21there is a single constant ratio between input and output sample rates.
22
23Dealing with the easy stuff first, the **converter_type** parameter should be
24one of the values defined in **samplerate.h** and documented [here](api_misc.md#converters)
25while the **channels** parameter specifies the number of interleaved channels
26that the sample rate converter is being asked to process (number of input
27channels and output channels is always equal). There is no hard upper limit on
28the number of channels; it is limited purely by the amount of memory available.
29
30The first parameter to **src_simple** is a pointer to an **SRC_DATA** struct
31(more info [here](api_misc.md#src_data)) defined as follows:
32
33```c
34typedef struct
35{ const float *data_in;
36 float *data_out ;
37
38 long input_frames, output_frames ;
39 long input_frames_used, output_frames_gen ;
40
41 int end_of_input ;
42
43 double src_ratio ;
44} SRC_DATA ;
45```
46
47The fields of this struct which must be filled in by the caller are:
48
49data_in
50: A pointer to the input data samples.
51
52input_frames
53: The number of frames of data pointed to by data_in.
54
55data_out
56: A pointer to the output data samples.
57
58output_frames
59: Maximum number of frames pointer to by data_out.
60
61src_ratio
62: Equal to output_sample_rate / input_sample_rate.
63
64When the **src_simple** function returns **output_frames_gen** will be set to
65the number of output frames generated and **input_frames_used** will be set to
66the number of input frames used to generate the provided number of output
67frames.
68
69The **src_simple** function returns a non-zero value when an error occurs. See
70[here](api_misc.md#error-reporting) for how to convert the error value into a
71text string.
docs/bugs.md+37−0
@@ -0,0 +1,37 @@
1---
2layout: default
3---
4
5# Bug Reporting
6
7If you are a user and have a problem using libsamplerate with another piece of
8software, you should contact the author of that other software and get them to
9explore their use of this library and possibly submit a bug report. If you are a
10coder and think you have found a bug in libsamplerate then read on.
11
12Secret Rabbit Code is an extremely complex piece of code but I do think that it
13is relatively bug free. In addition, the source code distribution includes a
14comprehensive test suite for regression testing. This means it is extremely
15unlikely that new bugs creep in when modifications are made to the code.
16
17SRC is also not the most simple library to use which means that I do get a
18number of bug reports which turn out to be bugs in the user's program rather
19than bugs in SRC. Up until now, I have investigated each bug report as
20thoroughly as possible. Unfortunately, this chews up a lot of my time which
21could otherwise be spent improving SRC, working on other Free Software or
22spending time with my family.
23
24I have therefore decided, that I cannot investigate any bug report unless the
25person reporting the problem can supply me with a short self contained test
26program or a modification to one of the existing test programs in the tests/
27directory of the source code distribution. The test program should meet the
28following criteria:
29
30- Written in C or C++.
31- Does not use any libraries or header files other than the ones which are
32 standard for the relevant languages. (Of course libsamplerate can be used :-)).
33- It is the minimal program which can adequately display the problem.
34- It clearly displays the criteria for pass or fail.
35
36Supplying a good test program will maximize the speed with which your bug report
37gets dealt with.
docs/download.md+15−0
@@ -0,0 +1,15 @@
1---
2layout: default
3---
4
5# Download
6
7The latest version of Secret Rabbit Code is {{ site.version }}.
8
9Download it on [GitHub releases page](https://github.com/libsndfile/libsamplerate/releases/latest).
10
11Compiling libsamplerate is relatively easy. The INSTALL file in the top level
12directory gives instructions on compiling and installing libsamplerate on
13Unix-like systems (including MacOSX). For Win32 there are instructions in the
14docs/ directory of the tarball. These instructions are mirrored
15[here](win32.md).
docs/faq.md+193−0
@@ -0,0 +1,193 @@
1---
2layout: default
3---
4
5# Frequently Asked Questions
6
71. [Q1 : Is it normal for the output of libsamplerate to be louder than its input?](#Q001)
82. [Q2 : On Unix/Linux/MacOSX, what is the best way of detecting the presence and location of libsamplerate and its header file using autoconf?](#Q002)
93. [Q3 : If I upsample and downsample to the original rate, for example 44.1-\>96-\>44.1, do I get an identical signal as the one before the up/down resampling?](#Q003)
104. [Q4 : If I ran src\_simple (libsamplerate) on small chunks (160 frames) would that sound bad?](#Q004)
115. [Q5 : I\'m using libsamplerate but the high quality settings sound worse than the SRC\_LINEAR converter. Why?](#Q005)
126. [Q6 : I\'m use the SRC\_SINC\_\* converters and up-sampling by a ratio of 2. I reset the converter and put in 1000 samples and I expect to get 2000 samples out, but I\'m getting less than that. Why?](#Q006)
137. [Q7 : I have input and output sample rates that are integer values, but the API wants me to divide one by the other and put the result in a floating point number. Won\'t this case problems for long running conversions?](#Q007)
14
15## Q1 : Is it normal for the output of libsamplerate to be louder than its input? {#Q001}
16
17The output of libsamplerate will be roughly the same volume as the input.
18However, even if the input is strictly in the range (-1.0, 1.0), it is still
19possible for the output to contain peak values outside this range.
20
21Consider four consecutive samples of [0.5 0.999 0.999 0.5]. If we are up
22sampling by a factor of two we need to insert samples between each of the
23existing samples. Its pretty obvious then, that the sample between the two 0.999
24values should and will be bigger than 0.999.
25
26This means that anyone using libsamplerate should normalize its output before
27doing things like saving the audio to a 16 bit WAV file.
28
29## Q2 : On Unix/Linux/MacOSX, what is the best way of detecting the presence and location of libsamplerate and its header file using autoconf? {#Q002}
30
31libsamplerate uses the pkg-config (man pkg-config) method of registering itself
32with the host system. The best way of detecting its presence is using something
33like this in configure.ac (or configure.in):
34
35 PKG_CHECK_MODULES(SAMPLERATE, samplerate >= 0.1.3,
36 ac_cv_samplerate=1, ac_cv_samplerate=0)
37
38 AC_DEFINE_UNQUOTED([HAVE_SAMPLERATE],${ac_cv_samplerate},
39 [Set to 1 if you have libsamplerate.])
40
41 AC_SUBST(SAMPLERATE_CFLAGS)
42 AC_SUBST(SAMPLERATE_LIBS)
43
44This will automatically set the **SAMPLERATE_CFLAGS** and **SAMPLERATE_LIBS**
45variables which can be used in Makefile.am or Makefile.in like this:
46
47 SAMPLERATE_CFLAGS = @SAMPLERATE_CFLAGS@
48 SAMPLERATE_LIBS = @SAMPLERATE_LIBS@
49
50If you install libsamplerate from source, you will probably need to set the
51**PKG_CONFIG_PATH** environment variable's suggested at the end of the
52libsamplerate configure process. For instance on my system I get this:
53
54 -=-=-=-=-=-=-=-=-=-= Configuration Complete =-=-=-=-=-=-=-=-=-=-=-
55
56 Configuration summary :
57
58 Version : ..................... 0.1.3
59 Enable debugging : ............ no
60
61 Tools :
62
63 Compiler is GCC : ............. yes
64 GCC major version : ........... 3
65
66 Extra tools required for testing and examples :
67
68 Have FFTW : ................... yes
69 Have libsndfile : ............. yes
70 Have libefence : .............. no
71
72 Installation directories :
73
74 Library directory : ........... /usr/local/lib
75 Program directory : ........... /usr/local/bin
76 Pkgconfig directory : ......... /usr/local/lib/pkgconfig
77
78## Q3 : If I upsample and downsample to the original rate, for example 44.1->96->44.1, do I get an identical signal as the one before the up/down resampling? {#Q003}
79
80The short answer is that for the general case, no, you don't. The long answer is
81that for some signals, with some converters, you will get very, very close.
82
83In order to resample correctly (ie using the **SRC_SINC_*** converters),
84filtering needs to be applied, regardless of whether its upsampling or
85downsampling. This filter needs to attenuate all frequencies above 0.5 times the
86minimum of the source and destination sample rate (call this fshmin). Since the
87filter needed to achieve full attenuation at this point, it has to start rolling
88off a some frequency below this point. It is this rolloff of the very highest
89frequencies which causes some of the loss.
90
91The other factor is that the filter itself can introduce transient artifacts
92which causes the output to be different to the input.
93
94## Q4 : If I ran src_simple on small chunks (say 160 frames) would that sound bad? {#Q004}
95
96Well if you are after odd sound effects, it might sound OK. If you are after
97high quality sample rate conversion you will be disappointed.
98
99The src_simple() was designed to provide a simple to use interface for people
100who wanted to do sample rate conversion on say, a whole file all at once.
101
102## Q5 : I'm using libsamplerate but the high quality settings sound worse than the SRC_LINEAR converter. Why? {#Q005}
103
104There are two possible problems. Firstly, if you are using the src_simple()
105function on successive blocks of a stream of samples, you will get bad results.
106The src_simple() function is designed for use on a whole sound file, all at
107once, not on contiguous segments of the same sound file. To fix the problem, you
108need to move to the src_process() API or the callback based API.
109
110If you are already using the src_process() API or the callback based API and the
111high quality settings sound worse than SRC_LINEAR, then you have other problems.
112Read on for more debugging hints.
113
114All of the higher quality converters need to keep state while doing conversions
115on segments of a large chunk of audio. This state information is kept inside the
116private data pointed to by the SRC_STATE pointer returned by the src_new()
117function. This means, that when you want to start doing sample rate conversion
118on a stream of data, you should call src_new() to get a new SRC_STATE pointer
119(or alternatively, call src_reset() on an existing SRC_STATE pointer). You
120should then pass this SRC_STATE pointer to the src_process() function with each
121new block of audio data. When you have completed the conversion, you can then
122call src_delete() on the SRC_STATE pointer.
123
124If you are doing all of the above correctly, you need to examine your usage of
125the values passed to src\_process() in the [SRC_DATA](api_misc.md#src_data)
126struct. Specifically:
127
128- Check that input_frames and output_frames fields are being set in terms of
129 frames (number of sample values times channels) instead of just the number of
130 samples.
131- Check that you are using the return values input_frames_used and
132 output_frames_gen to update your source and destination pointers correctly.
133- Check that you are updating the data_in and data_out pointers correctly for
134 each successive call.
135
136While doing the above, it is probably useful to compare what you are doing to
137what is done in the example programs in the examples/ directory of the source
138code tarball.
139
140If you have done all of the above and are still having problems then its
141probably time to email the author with the smallest chunk of code that
142adequately demonstrates your problem. This chunk should not need to be any more
143than 100 lines of code.
144
145## Q6 : I'm use the SRC_SINC_* converters and up-sampling by a ratio of 2. I reset the converter and put in 1000 samples and I expect to get 2000 samples out, but I'm getting less than that. Why? {#Q006}
146
147The short answer is that there is a transport delay inside the converter itself.
148Long answer follows.
149
150By way of example, the first time you call src_process() you might only get 1900
151samples out. However, after that first call all subsequent calls will probably
152get you about 2000 samples out for every 1000 samples you put in.
153
154The main problems people have with this transport delay is that they need to
155read out an exact number of samples and the transport delay scews this up. The
156best way to overcome this problem is to always supply more samples on the input
157than is actually needed to create the required number of output samples. With
158reference to the example above, if you always supply 1500 samples at the input,
159you will always get 2000 samples at the output. You will always need to keep
160track of the number of input frames used on each call to src_process() and deal
161with these values appropriately.
162
163## Q7 : I have input and output sample rates that are integer values, but the API wants me to divide one by the other and put the result in a floating point number. Won't this case problems for long running conversions? {#Q007}
164
165The short answer is no, the precision of the ratio is many orders of magnitude
166more than is really needed.
167
168For the long answer, lets do come calculations. Firstly, the `src_ratio` field
169is double precision floating point number which has [53 bits of precision](http://en.wikipedia.org/wiki/Double_precision).
170
171That means that the maximum error in your ratio converted to a double is one bit
172in 2^53 which means the the double float value would be wrong by one sample
173after 9007199254740992 samples have passed or wrong by more than half a sample
174wrong after half that many (4503599627370496 samples) have passed.
175
176Now if for example our output sample rate is 96kHz then
177
178 4503599627370496 samples at 96kHz is 46912496118 seconds
179 46912496118 seconds is 781874935 minutes
180 781874935 minutes is 13031248 hours
181 13031248 hours is 542968 days
182 542968 days is 1486 years
183
184So, after 1486 years, the input will be wrong by more than half of one sampling
185period.
186
187All this assumes that the crystal oscillators uses to sample the audio stream is
188perfect. This is not the case. According to [this web site](http://www.ieee-uffc.org/freqcontrol/quartz/vig/vigcomp.htm),
189the accuracy of standard crystal oscillators (XO, TCXO, OCXO) is at best 1 in
190100 million. The `src_ratio` is therefore 45035996 times more accurate than the
191crystal clock source used to sample the original audio signal and any potential
192problem with the `src_ratio` being a floating point number will be completely
193swamped by sampling inaccuracies.
docs/foo_dsp_src9.pngrenamed from doc/foo_dsp_src9.png+0−0

File renamed without changes.

docs/history.md+34−0
@@ -0,0 +1,34 @@
1---
2layout: default
3---
4
5# History
6
7- Version 0.0.0 (Oct 06 2002) First alpha release (friends and family only).
8- Version 0.0.2 (Oct 10 2002) Second alpha release (fools rush in ....).
9- ...
10- Version 0.0.7 (Nov 17 2002) The last mono only version.
11- Version 0.0.9 (Nov 21 2002) Full multi channel support. First pass at
12 documentation. Still not ready for release.
13- Version 0.0.11 (Nov 26 2002) Incorporated some suggestions from Conrad Parker.
14- Version 0.0.12 (Nov 28 2002) First public release.
15- Version 0.0.13 (Dec 03 2002) Fixes for MacOSX and Solaris.
16- Version 0.0.14 (Jan 13 2003) Now compiles on Win32. Major code speedup. Minor
17 bug fixes.
18- Version 0.0.15 (May 02 2003) Minor bug fixes.
19- Version 0.1.0 (Mar 14 2004) Add callback API, functions for short to float and
20 float to short conversion. Minor bug fixes.
21- Version 0.1.1 (Jul 17 2004) Callback API bug fix. Bugfix for aggressive
22 gcc-3.4 optimisations.
23- Version 0.1.2 (Sep 12 2004) Callback API reset bug fix.
24- Version 0.1.3 (Mar 23 2008) Huge quality improvements to two best SINC based
25 converters.
26- Version 0.1.4 (Jul 02 2008) Fix segfault when using extremely low conversion
27 ratios.
28- Version 0.1.5 (Jan 11 2009) Optimisation resulting in dramatic throughput
29 improvements ([See here.](http://www.mega-nerd.com/erikd/Blog/CodeHacking/SecretRabbitCode/rel_0_1_5.html)).
30- Version 0.1.6 (Jan 27 2009) Minor bug fix in test suite (account for rounding
31 error on x86_64).
32- Version 0.1.7 (Feb 14 2009) Fix a segfault bug. Fix compilation under MSVC.
33- Version 0.1.8 (Aug 15 2011) Minor bug fixes and updates.
34- Version 0.1.9 (Sep 19 2016) Fix for a segfault. Relicense under BSD license.
docs/index.md+39−0
@@ -0,0 +1,39 @@
1---
2layout: default
3title: Libsamplerate home page
4---
5
6{: .indent_block}
7*"Choosing a sample rate coverter wasn't easy. We ran numerous tests with Secret
8Rabbit Code and other sample rate converters, then compared them all. In the
9end, SRC outperformed the others, including some extremely well known and
10popular software. We had one issue with SRC, but after emailing Erik, he got
11back to us immediately with an answer. Choosing SRC was a no brainer."*
12Ryan Smith, International Marketing Manager,
13[Emersys Corp.](http://emersys.co.kr/), South Korea.
14Product : [Maven3D](http://maven3d.com)
15
16**S**ecret **R**abbit **C**ode (aka libsamplerate) is a **S**ample **R**ate
17**C**onverter for audio. One example of where such a thing would be useful is
18converting audio from the CD sample rate of 44.1kHz to the 48kHz sample rate
19used by DAT players.
20
21**SRC** is capable of arbitrary and time varying conversions; from downsampling
22by a factor of 256 to upsampling by the same factor. Arbitrary in this case
23means that the ratio of input and output sample rates can be an irrational
24number. The conversion ratio can also vary with time for speeding up and slowing
25down effects.
26
27**SRC** provides a small set of converters to allow quality to be traded off
28against computation cost. The current best converter provides a signal-to-noise
29ratio of 145dB with -3dB passband extending from DC to 96% of the theoretical
30best bandwidth for a given pair of input and output sample rates.
31
32Since the library has few dependencies beyond that provided by the standard C
33library, it should compile and work on just about any operating system. It is
34known to work on Linux, MacOSX, [Win32](win32.md) and Solaris. With some
35relatively minor hacking it should also be relatively easy to port it to
36embedded systems and digital signal processors.
37
38In addition, the library comes with a comprehensive test suite which can
39validate the performance of the library on new platforms.
docs/license.md+12−0
@@ -0,0 +1,12 @@
1---
2layout: default
3---
4
5# License
6
7From its first release in 2002, Secret Rabbit Code was under a dual licensing
8scheme where people could chose to use it under the terms of the GNU General
9Public License or pay for a commercial use license.
10
11In 2016, thanks to a generous offer from Epic Games International, Secret Rabbit
12Code was relicensed under the 2-clause BSD license.
docs/lists.md+17−0
@@ -0,0 +1,17 @@
1---
2layout: default
3---
4
5# Mailing Lists
6
7There are currently two mailings lists for Secret Rabbit Code:
8
9- **src-announce\@mega-nerd.com**  
10 [Subscribe](mailto:src-announce-request@mega-nerd.com?subject=subscribe)
11
12 A read only announcement list.
13- **src\@mega-nerd.com**  
14 [Subscribe](mailto:src-request@mega-nerd.com?subject=subscribe)
15
16 A general list which will also carry all the email from the announce
17 list. Posting to this list is restricted to subscribers.
docs/paypal.pngrenamed from doc/paypal.png+0−0

File renamed without changes.

docs/quality.md+84−0
@@ -0,0 +1,84 @@
1---
2layout: default
3---
4
5# SRC Quality
6
7**This document not yet complete.**
8
9When measuring the performance of a Sample Rate Converter, there are three
10factors to consider:
11
12- **Signal-to-Noise Ratio** - a measure of how much noise the sample rate
13 conversion process adds to the signal. This is measured in decibels (dB) and
14 the higher this value the better. For most sample rate converters, the SNR
15 will vary depending on the input signal and the ratio between input and output
16 sample rates. The only valid comparison of SNR is between the worst case for
17 each converter.
18- **Bandwidth** - most sample rate converters attenuate high frequencies as part
19 of their operation. Bandwidth can be measured by finding the frequency where
20 the attenuation is 3dB and expressing that as a percentage of the full
21 bandwidth at that sampling rate.
22- **Speed** - the faster the better **:-)**.
23
24There are a number of sample rate converters available for downloading but I
25will limit the comparison ot Secret Rabbit Code to the following:
26
27- [sndfile-resample](http://libsndfile.github.io/libsamplerate/download.html)
28 which is a program (which uses libsamplerate) from the **examples/** directory
29 of the Secret Rabbit Code source code distribution.
30- [Resample](https://ccrma.stanford.edu/~jos/resample/) by Julius O Smiths which
31 seems to have been the first high quality converter available as source code.
32- [ResampAudio](http://www.tsp.ece.mcgill.ca/MMSP/Documents/Software/AFsp/ResampAudio.html)
33 which is part of [Audio File Programs and Routines](http://www.tsp.ece.mcgill.ca/MMSP/Documents/Software/AFsp/AFsp.html)
34 by Peter Kabal.
35- [SoX](http://home.sprynet.com/~cbagwell/sox.html) which is maintained by Chris
36 Bagwell. SoX is also able to perform some low quality sample rate conversions
37 but these will not be investigated.
38- [Shibatch](http://shibatch.sourceforge.net/) which seems to be a frequency
39 domain sample rate converter. Unfortunately, this converter does not handle
40 arbitrary conversion ratios and hence could not be properly compared to the
41 other converters.
42- [sr-convert](http://sr-convert.sourceforge.net/) is another converter which
43 does not handle arbitrary conversion ratios.
44
45It should be noted that the first three converters above are based on the
46algorithm by [Julius O. Smith](http://www-ccrma.stanford.edu/~jos/resample/)
47which emulates the conversion of the digital signal to an analogue one and then
48sampling the analogue signal at the new sample rate.
49
50## Methodology
51
52Measuring the SNR of a converter is relatively straight forward. Generate an
53input signal consisting of a windowed sine wave, sample rate convert it and
54measure the signal-to-noise ratio of the output signal. A typical length for the
55original file is 30000 samples.
56
57The bandwidth of a sample rate converter is a little more difficult to measure.
58Currently this is done by generating two short files containing a windowed sine
59wave. The frequencies of the sine waves are 0.35 and 0.495 of the sample rate.
60These file are then upsampled by a factor of 2 using the converter under test.
61If the attenutaion of the lower frquency is less than 3dB and higher frequency
62is more than 3dB, it is then possible to iteratively increase the lower
63frequency and decrease the upper frequency keeping the -3dB point bracketed.
64When the distance between the upper and lower frequency is sufficiently small,
65it is possible to obtain a very accurate estimate of the -3dB frequency.
66
67The speed of a sample rate converter is easy to measure; simply perform a
68conversion on a large file or a number of smaller files and time the conversion
69process.
70
71The above measurement techniques are built into a test program which is
72delivered with the Secret Rabbit Code source code distibution. This program is
73able to test the first four of the above converters.
74
75## SoX
76
77SoX provides three methods of resampling; a linear interpolator, a polyphase
78resampler and the Julius O. Smith simulated analogue filter method.
79
80## Shibatch
81
82Shibach
83
84**More Coming Soon.**
docs/win32.md+15−0
@@ -0,0 +1,15 @@
1---
2layout: default
3---
4
5# Compiling on Win32
6
7You can use [CMake](https://cmake.org/) to generate Visual Studio project. The
8configuration process is described [here](https://cmake.org/runningcmake/).
9
10The libsamplerate library itself does not require any dependencies, but if you
11want to build examples and tests, you will need the [libsndfile](https://github.com/libsndfile/libsndfile)
12and [FFTW](http://www.fftw.org/) libraries. The easiest way to install them is
13to use a package manager, such as [Vcpkg](https://github.com/microsoft/vcpkg). Their README.md contains detailed
14installation instructions for supported platforms. Libsamplerate requires the
15`libsndfile` and `fftw3` packages.

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t