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

Showing the changes to docs (20 of 38 files). Show all

Unified · Split

20 files

docs/SRC.css +48 −0
docs/SRC.png +0 −0
docs/_config.yml +8 −0
docs/_layouts/default.html +51 −0
docs/api.md +46 −0
docs/api_callback.md +88 −0
docs/api_full.md +146 −0
docs/api_misc.md +143 −0
docs/api_simple.md +71 −0
docs/bugs.md +37 −0
docs/download.md +15 −0
docs/faq.md +193 −0
docs/foo_dsp_src9.png +0 −0
docs/history.md +34 −0
docs/index.md +39 −0
docs/license.md +12 −0
docs/lists.md +17 −0
docs/paypal.png +0 −0
docs/quality.md +84 −0
docs/win32.md +15 −0

@@ -0,0 +1,48 @@
	1	+a:link {
	2	+ color: #FB1465;
	3	+}
	4	+
	5	+a:active, a:visited {
	6	+ color: #FB1465;
	7	+}
	8	+
	9	+body {
	10	+ background: black;
	11	+ color: white;
	12	+ font-family: arial, helvetica, sans-serif;
	13	+}
	14	+
	15	+h1, h2, h3, h4, h5, h6 {
	16	+ color: #FB1465;
	17	+}
	18	+
	19	+code, kbd, samp, var {
	20	+ font-family: courier, monospace;
	21	+ font-size: 1em;
	22	+}
	23	+
	24	+main {
	25	+ padding-left: 3%;
	26	+ padding-right: 3%;
	27	+}
	28	+
	29	+pre {
	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.png+0−0

Binary file not shown.

docs/_config.yml+8−0

@@ -0,0 +1,8 @@
	1	+---
	2	+author: Erik de Castro Lopo, erikd@mega-nerd.com
	3	+description: An audio Sample Rate Conversion library
	4	+keywords: libsamplerate, sound, resample, audio, dsp, Linux
	5	+version: 0.1.8
	6	+
	7	+markdown: 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> Erik de Castro 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	+---
	2	+layout: default
	3	+---
	4	+
	5	+# Applications Programming Interface
	6	+
	7	+The publically callable functions of libsamplerate are all listed in the
	8	+\<samplerate.h\> header file. In order to use any of the functionality of
	9	+libsamplerate, you need to add
	10	+
	11	+```c
	12	+#include <samplerate.h>
	13	+```
	14	+
	15	+to the top of any function that call any of the following functions. You will
	16	+also need to link you binary with the libsamplerate library.
	17	+
	18	+The 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
	33	+data.
	34	+
	35	+The 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	+
	41	+All three versions of the API are restricted to operating on buffers of ISO C
	42	+Standard float data. However, there are two [auxillary functions](api_misc.md#auxillary-functions)
	43	+for converting arrays of float data to and from short data.
	44	+
	45	+Note: The tests/ and examples/ directories of the source code
	46	+distribution contain numerous example programs showing the use of the library.

docs/api_callback.md+88−0

@@ -0,0 +1,88 @@
	1	+---
	2	+layout: default
	3	+---
	4	+
	5	+# Callback API
	6	+
	7	+The callback API consists of the following functions :
	8	+
	9	+```c
	10	+typedef long (src_callback_t) (void cb_data, float **data) ;
	11	+
	12	+SRC_STATE* src_callback_new (src_callback_t func,
	13	+ int converter_type, int channels,
	14	+ int error, void cb_data) ;
	15	+
	16	+SRC_STATE* src_delete (SRC_STATE *state) ;
	17	+
	18	+long src_callback_read (SRC_STATE *state, double src_ratio,
	19	+ long frames, float *data) ;
	20	+
	21	+int src_reset (SRC_STATE *state) ;
	22	+int src_set_ratio (SRC_STATE *state, double new_ratio) ;
	23	+```
	24	+
	25	+Like the [simple API](api_simple.md) and the [full API](api_full.md), the
	26	+callback based API is able to operate on interleaved multi channel data.
	27	+
	28	+An 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
	30	+tarball.
	31	+
	32	+## Initialisation
	33	+
	34	+```c
	35	+SRC_STATE* src_callback_new (src_callback_t func,
	36	+ int converter_type, int channels,
	37	+ int error, void cb_data) ;
	38	+```
	39	+
	40	+The src_callback_new function returns an anonymous pointer to a sample rate
	41	+converter callback object, src_state. This is the same type of object as that
	42	+returned by [src\_new](api_full.md#initialisation), but with different internal
	43	+state. Although these are the same object type, they cannot be used
	44	+interchangeably. If an error occurs the function returns a NULL pointer and
	45	+fills in the error value pointed to by the error pointer supplied by the
	46	+caller.
	47	+
	48	+The caller then passes the SRC_STATE object to the src_callback_read
	49	+function to pull data out of the converter. When the caller is finished with the
	50	+converter they should pass it to the clean up function [src_delete](api_full.md#cleanup).
	51	+
	52	+The 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
	54	+be passed as the first parameter to the user supplied callback function. This
	55	+function is called by the converter whenever it needs input data as a result of
	56	+being calls to src_callback_read.
	57	+
	58	+If the converter was initialised to work with more than one channel, the
	59	+callback function must work with mutiple channels of interleaved data. The
	60	+callback function should return the number of frames it supplying to the
	61	+converter. For multi channel files, this return value should be the number of
	62	+floats divided by the number of channels.
	63	+
	64	+The converter must be one of the supplied converter types documented [here](api_misc.md#converters).
	65	+
	66	+The caller then passes the SRC_STATE pointer to the src_callback_read
	67	+function to pull data out of the converter.
	68	+
	69	+## Callback Read
	70	+
	71	+```c
	72	+long src_callback_read (SRC_STATE *state, double src_ratio,
	73	+ long frames, float *data) ;
	74	+```
	75	+
	76	+The src_callback_read function is passed the [SRC_STATE](api_misc.md#src_data)
	77	+pointer returned by src_callback_new, the coversion ratio
	78	+(output_sample_rate / input_sample_rate), the maximum number of output frames to
	79	+generate and a pointer to a buffer in which to place the output data. For multi
	80	+channel files, the data int the output buffer is stored in interleaved format.
	81	+
	82	+The src_callback_read function returns the number of frames generated or
	83	+zero if an error occurs or it runs out of input (ie the user supplied callback
	84	+function returns zero and there is no more data buffered internally). If an
	85	+error has occurred, the function [src_error](api_misc.md#error-reporting)
	86	+will return non-zero.
	87	+
	88	+See also : [src_set_ratio](api_full.md#set-ratio)

docs/api_full.md+146−0

@@ -0,0 +1,146 @@
	1	+---
	2	+layout: default
	3	+---
	4	+
	5	+# Full API
	6	+
	7	+The full API consists of the following functions :
	8	+
	9	+```c
	10	+SRC_STATE* src_new (int converter_type, int channels, int *error) ;
	11	+SRC_STATE* src_delete (SRC_STATE *state) ;
	12	+
	13	+int src_process (SRC_STATE state, SRC_DATA data) ;
	14	+int src_reset (SRC_STATE *state) ;
	15	+int src_set_ratio (SRC_STATE *state, double new_ratio) ;
	16	+```
	17	+
	18	+## Initialisation
	19	+
	20	+```c
	21	+SRC_STATE* src_new (int converter_type, int channels, int *error) ;
	22	+```
	23	+
	24	+The src\_new function returns an anonymous pointer to a sample rate
	25	+converter object, src\_state. If an error occurs the function returns a
	26	+NULL pointer and fills in the error value pointed to by the error
	27	+pointer supplied by the caller. The converter must be one of the
	28	+supplied converter types documented [here](api_misc.md#converters).
	29	+
	30	+## Cleanup
	31	+
	32	+```c
	33	+SRC_STATE* src_delete (SRC_STATE *state) ;
	34	+```
	35	+
	36	+The src\_delete function frees up all memory allocated for the given
	37	+sample rate converter object and returns a NULL pointer. The caller is
	38	+responsible for freeing any memory passed to the sample rate converter
	39	+via the pointer to the SRC\_DATA struct.
	40	+
	41	+## Process
	42	+
	43	+```c
	44	+int src_process (SRC_STATE state, SRC_DATA data) ;
	45	+```
	46	+
	47	+The src\_process function processes the data provided by the caller
	48	+in an SRC\_DATA struct using the sample rate converter object
	49	+specified by the SRC\_STATE pointer. When operating on streaming
	50	+data, this function can be called over and over again, with each new
	51	+call providing new input data and returning new output data.
	52	+
	53	+The SRC\_DATA struct passed as the second parameter to the
	54	+src\_process function has the following fields:
	55	+
	56	+```c
	57	+typedef 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	+
	70	+The fields of this struct which must be filled in by the caller are:
	71	+
	72	+data_in
	73	+: A pointer to the input data samples.
	74	+
	75	+input_frames
	76	+: The number of frames of data pointed to by data_in.
	77	+
	78	+data_out
	79	+: A pointer to the output data samples.
	80	+
	81	+output_frames
	82	+: Maximum number of frames pointer to by data_out.
	83	+
	84	+src_ratio
	85	+: Equal to output_sample_rate / input_sample_rate.
	86	+
	87	+end_of_input
	88	+: Equal to 0 if more input data is available and 1 otherwise.
	89	+
	90	+Note that the data\_in and data\_out arrays may not overlap. If they do,
	91	+the library will return an error code.
	92	+
	93	+When the src\_process function returns output\_frames\_gen will
	94	+be set to the number of output frames generated and
	95	+input\_frames\_used will be set to the number of input frames
	96	+consumed to generate the provided number of output frames.
	97	+
	98	+The src\_process function returns non-zero if an error occurs. The
	99	+non-zero error return value can be decoded into a text string using the
	100	+function documented [here](api_misc.md#error-reporting).
	101	+
	102	+## Reset
	103	+
	104	+```c
	105	+int src_reset (SRC_STATE *state) ;
	106	+```
	107	+
	108	+The src\_reset function resets the internal state of the sample rate
	109	+converter object to the same state it had immediately after its creation
	110	+using src\_new. This should be called whenever a sample rate
	111	+converter is to be used on two separate, unrelated pieces of audio.
	112	+
	113	+## Clone
	114	+
	115	+```c
	116	+SRC_STATE* src_clone (SRC_STATE state, int error) ;
	117	+```
	118	+
	119	+The src_clone function creates a copy of the internal state of the sample
	120	+rate converter object. The output of the next call to src\_process will be
	121	+identical for both the original and cloned state (given the same SRC_DATA
	122	+input). This could be used to later resume sample rate conversion at a specific
	123	+location in a stream with the same state, which may be useful in real-time
	124	+applications.
	125	+
	126	+If an error occurs the function returns a NULL pointer and fills in the
	127	+error value pointed to by the error pointer supplied by the caller.
	128	+
	129	+## Set Ratio
	130	+
	131	+```c
	132	+int src_set_ratio (SRC_STATE *state, double new_ratio) ;
	133	+```
	134	+
	135	+When 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
	137	+smoothly transition between the conversion ratio of the last call and the
	138	+conversion ratio of the current call.
	139	+
	140	+If the user want to bypass this smooth transition and achieve a step response in
	141	+the conversion ratio, the src_set_ratio function can be used to set the
	142	+starting conversion ratio of the next call to src_process or
	143	+src_callback_process.
	144	+
	145	+This function returns non-zero on error and the error return value can be
	146	+decoded 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	+---
	2	+layout: default
	3	+---
	4	+
	5	+# Miscellaneous API Documentation
	6	+
	7	+## Error Reporting
	8	+
	9	+Most 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
	12	+text strings by calling the function:
	13	+
	14	+```c
	15	+const char* src_strerror (int error) ;
	16	+```
	17	+
	18	+which 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
	20	+has been defined for that error value.
	21	+
	22	+## Converters
	23	+
	24	+Secret Rabbit Code has a number of different converters which can be selected
	25	+using the converter_type parameter when calling src_simple or
	26	+src_new. Currently, the five converters available are:
	27	+
	28	+```c
	29	+enum
	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	+
	39	+As new converters are added, they will given a number corresponding to the next
	40	+integer.
	41	+
	42	+The 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	+
	61	+There are two functions that give either a (text string) name or description for
	62	+each converter:
	63	+
	64	+```c
	65	+const char *src_get_name (int converter_type) ;
	66	+const char *src_get_description (int converter_type) ;
	67	+```
	68	+
	69	+The name will typically be a short string for use in a dialog box, while the
	70	+description string is longer.
	71	+
	72	+Both of these functions return a NULL pointer if there is no converter for the
	73	+given converter_type value. Since the converters have consecutive
	74	+converter_type values, the caller is easily able to figure out the number of
	75	+converters at run time. This enables a binary dynamically linked against an old
	76	+version of the library to know about converters from later versions of the
	77	+library as they become available.
	78	+
	79	+## SRC_DATA
	80	+
	81	+Both the simple and the full featured versions of the API use the SRC_DATA
	82	+struct to pass audio and control data into the sample rate converter. This
	83	+struct is defined as:
	84	+
	85	+```c
	86	+typedef 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	+
	99	+The 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
	101	+converter's output. For a converter which has been configured for mulitchannel
	102	+operation, these pointers need to point to a single array of interleaved data.
	103	+
	104	+The input_frames and output_frames fields supply the converter with the
	105	+lengths of the arrays (in frames) pointed to by the data_in and data_out
	106	+pointers respectively. For monophinc data, these values would indicate the
	107	+length of the arrays while for multi channel data these values would be equal to
	108	+the the length of the array divided by the number of channels.
	109	+
	110	+The end_of_input field is only used when the sample rate converter is used
	111	+by calling the src_process function. In this case it should be set to zero
	112	+if more buffers are to be passed to the converter and 1 if the current buffer is
	113	+the last.
	114	+
	115	+Finally, the src_ratio field specifies the conversion ratio defined as the
	116	+output sample rate divided by the input sample rate. For a connected set of
	117	+buffers, this value can be varies on each call to src_process resulting in a
	118	+time varying sample rate conversion process. For time varying sample rate
	119	+conversions, the ratio will be linearly interpolated between the src_ratio
	120	+value of the previous call to src_process and the value for the current
	121	+call.
	122	+
	123	+The input_frames_used and output_frames_gen fields are set by the
	124	+converter 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
	126	+respectively. These values are for the current call to src_process only.
	127	+
	128	+## Auxillary Functions
	129	+
	130	+There are four auxillary functions for converting arrays of float data to and
	131	+from short or int data. These functions are defined as:
	132	+
	133	+```c
	134	+void src_short_to_float_array (const short in, float out, int len) ;
	135	+void src_float_to_short_array (const float in, short out, int len) ;
	136	+void src_int_to_float_array (const int in, float out, int len) ;
	137	+void src_float_to_int_array (const float in, int out, int len) ;
	138	+```
	139	+
	140	+The float data is assumed to be in the range [-1.0, 1.0] and it is automatically
	141	+scaled on the conversion to and from float. On the float to short/int conversion
	142	+path, any data values which would overflow the range of short/int data are
	143	+clipped.

docs/api_simple.md+71−0

@@ -0,0 +1,71 @@
	1	+---
	2	+layout: default
	3	+---
	4	+
	5	+# Simple API
	6	+
	7	+Important Note: The simple API is not designed to work on small chunks of a
	8	+larger piece of audio. If you attempt to use it this way you are doing it wrong
	9	+and 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	+
	12	+The simple API consists of a single function:
	13	+
	14	+```c
	15	+int src_simple (SRC_DATA *data, int converter_type, int channels) ;
	16	+```
	17	+
	18	+The use of this function rather than the more fully featured API requires the
	19	+caller to know the total length of the input data before hand and that all input
	20	+and output data can be held in the system's memory at once. It also assumes that
	21	+there is a single constant ratio between input and output sample rates.
	22	+
	23	+Dealing with the easy stuff first, the converter_type parameter should be
	24	+one of the values defined in samplerate.h and documented [here](api_misc.md#converters)
	25	+while the channels parameter specifies the number of interleaved channels
	26	+that the sample rate converter is being asked to process (number of input
	27	+channels and output channels is always equal). There is no hard upper limit on
	28	+the number of channels; it is limited purely by the amount of memory available.
	29	+
	30	+The 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
	34	+typedef 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	+
	47	+The fields of this struct which must be filled in by the caller are:
	48	+
	49	+data_in
	50	+: A pointer to the input data samples.
	51	+
	52	+input_frames
	53	+: The number of frames of data pointed to by data_in.
	54	+
	55	+data_out
	56	+: A pointer to the output data samples.
	57	+
	58	+output_frames
	59	+: Maximum number of frames pointer to by data_out.
	60	+
	61	+src_ratio
	62	+: Equal to output_sample_rate / input_sample_rate.
	63	+
	64	+When the src_simple function returns output_frames_gen will be set to
	65	+the number of output frames generated and input_frames_used will be set to
	66	+the number of input frames used to generate the provided number of output
	67	+frames.
	68	+
	69	+The 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
	71	+text string.

docs/bugs.md+37−0

@@ -0,0 +1,37 @@
	1	+---
	2	+layout: default
	3	+---
	4	+
	5	+# Bug Reporting
	6	+
	7	+If you are a user and have a problem using libsamplerate with another piece of
	8	+software, you should contact the author of that other software and get them to
	9	+explore their use of this library and possibly submit a bug report. If you are a
	10	+coder and think you have found a bug in libsamplerate then read on.
	11	+
	12	+Secret Rabbit Code is an extremely complex piece of code but I do think that it
	13	+is relatively bug free. In addition, the source code distribution includes a
	14	+comprehensive test suite for regression testing. This means it is extremely
	15	+unlikely that new bugs creep in when modifications are made to the code.
	16	+
	17	+SRC is also not the most simple library to use which means that I do get a
	18	+number of bug reports which turn out to be bugs in the user's program rather
	19	+than bugs in SRC. Up until now, I have investigated each bug report as
	20	+thoroughly as possible. Unfortunately, this chews up a lot of my time which
	21	+could otherwise be spent improving SRC, working on other Free Software or
	22	+spending time with my family.
	23	+
	24	+I have therefore decided, that I cannot investigate any bug report unless the
	25	+person reporting the problem can supply me with a short self contained test
	26	+program or a modification to one of the existing test programs in the tests/
	27	+directory of the source code distribution. The test program should meet the
	28	+following 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	+
	36	+Supplying a good test program will maximize the speed with which your bug report
	37	+gets dealt with.

docs/download.md+15−0

@@ -0,0 +1,15 @@
	1	+---
	2	+layout: default
	3	+---
	4	+
	5	+# Download
	6	+
	7	+The latest version of Secret Rabbit Code is {{ site.version }}.
	8	+
	9	+Download it on [GitHub releases page](https://github.com/libsndfile/libsamplerate/releases/latest).
	10	+
	11	+Compiling libsamplerate is relatively easy. The INSTALL file in the top level
	12	+directory gives instructions on compiling and installing libsamplerate on
	13	+Unix-like systems (including MacOSX). For Win32 there are instructions in the
	14	+docs/ directory of the tarball. These instructions are mirrored
	15	+[here](win32.md).

docs/faq.md+193−0

@@ -0,0 +1,193 @@
	1	+---
	2	+layout: default
	3	+---
	4	+
	5	+# Frequently Asked Questions
	6	+
	7	+1. [Q1 : Is it normal for the output of libsamplerate to be louder than its input?](#Q001)
	8	+2. [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)
	9	+3. [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)
	10	+4. [Q4 : If I ran src\_simple (libsamplerate) on small chunks (160 frames) would that sound bad?](#Q004)
	11	+5. [Q5 : I\'m using libsamplerate but the high quality settings sound worse than the SRC\_LINEAR converter. Why?](#Q005)
	12	+6. [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)
	13	+7. [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	+
	17	+The output of libsamplerate will be roughly the same volume as the input.
	18	+However, even if the input is strictly in the range (-1.0, 1.0), it is still
	19	+possible for the output to contain peak values outside this range.
	20	+
	21	+Consider four consecutive samples of [0.5 0.999 0.999 0.5]. If we are up
	22	+sampling by a factor of two we need to insert samples between each of the
	23	+existing samples. Its pretty obvious then, that the sample between the two 0.999
	24	+values should and will be bigger than 0.999.
	25	+
	26	+This means that anyone using libsamplerate should normalize its output before
	27	+doing 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	+
	31	+libsamplerate uses the pkg-config (man pkg-config) method of registering itself
	32	+with the host system. The best way of detecting its presence is using something
	33	+like 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	+
	44	+This will automatically set the SAMPLERATE_CFLAGS and SAMPLERATE_LIBS
	45	+variables which can be used in Makefile.am or Makefile.in like this:
	46	+
	47	+ SAMPLERATE_CFLAGS = @SAMPLERATE_CFLAGS@
	48	+ SAMPLERATE_LIBS = @SAMPLERATE_LIBS@
	49	+
	50	+If 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
	52	+libsamplerate 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	+
	80	+The short answer is that for the general case, no, you don't. The long answer is
	81	+that for some signals, with some converters, you will get very, very close.
	82	+
	83	+In order to resample correctly (ie using the SRC_SINC_* converters),
	84	+filtering needs to be applied, regardless of whether its upsampling or
	85	+downsampling. This filter needs to attenuate all frequencies above 0.5 times the
	86	+minimum of the source and destination sample rate (call this fshmin). Since the
	87	+filter needed to achieve full attenuation at this point, it has to start rolling
	88	+off a some frequency below this point. It is this rolloff of the very highest
	89	+frequencies which causes some of the loss.
	90	+
	91	+The other factor is that the filter itself can introduce transient artifacts
	92	+which 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	+
	96	+Well if you are after odd sound effects, it might sound OK. If you are after
	97	+high quality sample rate conversion you will be disappointed.
	98	+
	99	+The src_simple() was designed to provide a simple to use interface for people
	100	+who 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	+
	104	+There are two possible problems. Firstly, if you are using the src_simple()
	105	+function on successive blocks of a stream of samples, you will get bad results.
	106	+The src_simple() function is designed for use on a whole sound file, all at
	107	+once, not on contiguous segments of the same sound file. To fix the problem, you
	108	+need to move to the src_process() API or the callback based API.
	109	+
	110	+If you are already using the src_process() API or the callback based API and the
	111	+high quality settings sound worse than SRC_LINEAR, then you have other problems.
	112	+Read on for more debugging hints.
	113	+
	114	+All of the higher quality converters need to keep state while doing conversions
	115	+on segments of a large chunk of audio. This state information is kept inside the
	116	+private data pointed to by the SRC_STATE pointer returned by the src_new()
	117	+function. This means, that when you want to start doing sample rate conversion
	118	+on 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
	120	+should then pass this SRC_STATE pointer to the src_process() function with each
	121	+new block of audio data. When you have completed the conversion, you can then
	122	+call src_delete() on the SRC_STATE pointer.
	123	+
	124	+If you are doing all of the above correctly, you need to examine your usage of
	125	+the values passed to src\_process() in the [SRC_DATA](api_misc.md#src_data)
	126	+struct. 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	+
	136	+While doing the above, it is probably useful to compare what you are doing to
	137	+what is done in the example programs in the examples/ directory of the source
	138	+code tarball.
	139	+
	140	+If you have done all of the above and are still having problems then its
	141	+probably time to email the author with the smallest chunk of code that
	142	+adequately demonstrates your problem. This chunk should not need to be any more
	143	+than 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	+
	147	+The short answer is that there is a transport delay inside the converter itself.
	148	+Long answer follows.
	149	+
	150	+By way of example, the first time you call src_process() you might only get 1900
	151	+samples out. However, after that first call all subsequent calls will probably
	152	+get you about 2000 samples out for every 1000 samples you put in.
	153	+
	154	+The main problems people have with this transport delay is that they need to
	155	+read out an exact number of samples and the transport delay scews this up. The
	156	+best way to overcome this problem is to always supply more samples on the input
	157	+than is actually needed to create the required number of output samples. With
	158	+reference to the example above, if you always supply 1500 samples at the input,
	159	+you will always get 2000 samples at the output. You will always need to keep
	160	+track of the number of input frames used on each call to src_process() and deal
	161	+with 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	+
	165	+The short answer is no, the precision of the ratio is many orders of magnitude
	166	+more than is really needed.
	167	+
	168	+For the long answer, lets do come calculations. Firstly, the `src_ratio` field
	169	+is double precision floating point number which has [53 bits of precision](http://en.wikipedia.org/wiki/Double_precision).
	170	+
	171	+That means that the maximum error in your ratio converted to a double is one bit
	172	+in 2^53 which means the the double float value would be wrong by one sample
	173	+after 9007199254740992 samples have passed or wrong by more than half a sample
	174	+wrong after half that many (4503599627370496 samples) have passed.
	175	+
	176	+Now 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	+
	184	+So, after 1486 years, the input will be wrong by more than half of one sampling
	185	+period.
	186	+
	187	+All this assumes that the crystal oscillators uses to sample the audio stream is
	188	+perfect. This is not the case. According to [this web site](http://www.ieee-uffc.org/freqcontrol/quartz/vig/vigcomp.htm),
	189	+the accuracy of standard crystal oscillators (XO, TCXO, OCXO) is at best 1 in
	190	+100 million. The `src_ratio` is therefore 45035996 times more accurate than the
	191	+crystal clock source used to sample the original audio signal and any potential
	192	+problem with the `src_ratio` being a floating point number will be completely
	193	+swamped by sampling inaccuracies.

docs/foo_dsp_src9.png+0−0

Binary file not shown.

docs/history.md+34−0

@@ -0,0 +1,34 @@
	1	+---
	2	+layout: 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	+---
	2	+layout: default
	3	+title: Libsamplerate home page
	4	+---
	5	+
	6	+{: .indent_block}
	7	+*"Choosing a sample rate coverter wasn't easy. We ran numerous tests with Secret
	8	+Rabbit Code and other sample rate converters, then compared them all. In the
	9	+end, SRC outperformed the others, including some extremely well known and
	10	+popular software. We had one issue with SRC, but after emailing Erik, he got
	11	+back to us immediately with an answer. Choosing SRC was a no brainer."*
	12	+Ryan Smith, International Marketing Manager,
	13	+[Emersys Corp.](http://emersys.co.kr/), South Korea.
	14	+Product : [Maven3D](http://maven3d.com)
	15	+
	16	+Secret Rabbit Code (aka libsamplerate) is a Sample Rate
	17	+Converter for audio. One example of where such a thing would be useful is
	18	+converting audio from the CD sample rate of 44.1kHz to the 48kHz sample rate
	19	+used by DAT players.
	20	+
	21	+SRC is capable of arbitrary and time varying conversions; from downsampling
	22	+by a factor of 256 to upsampling by the same factor. Arbitrary in this case
	23	+means that the ratio of input and output sample rates can be an irrational
	24	+number. The conversion ratio can also vary with time for speeding up and slowing
	25	+down effects.
	26	+
	27	+SRC provides a small set of converters to allow quality to be traded off
	28	+against computation cost. The current best converter provides a signal-to-noise
	29	+ratio of 145dB with -3dB passband extending from DC to 96% of the theoretical
	30	+best bandwidth for a given pair of input and output sample rates.
	31	+
	32	+Since the library has few dependencies beyond that provided by the standard C
	33	+library, it should compile and work on just about any operating system. It is
	34	+known to work on Linux, MacOSX, [Win32](win32.md) and Solaris. With some
	35	+relatively minor hacking it should also be relatively easy to port it to
	36	+embedded systems and digital signal processors.
	37	+
	38	+In addition, the library comes with a comprehensive test suite which can
	39	+validate the performance of the library on new platforms.

docs/license.md+12−0

@@ -0,0 +1,12 @@
	1	+---
	2	+layout: default
	3	+---
	4	+
	5	+# License
	6	+
	7	+From its first release in 2002, Secret Rabbit Code was under a dual licensing
	8	+scheme where people could chose to use it under the terms of the GNU General
	9	+Public License or pay for a commercial use license.
	10	+
	11	+In 2016, thanks to a generous offer from Epic Games International, Secret Rabbit
	12	+Code was relicensed under the 2-clause BSD license.

docs/lists.md+17−0

@@ -0,0 +1,17 @@
	1	+---
	2	+layout: default
	3	+---
	4	+
	5	+# Mailing Lists
	6	+
	7	+There 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.png+0−0

Binary file not shown.

docs/quality.md+84−0

@@ -0,0 +1,84 @@
	1	+---
	2	+layout: default
	3	+---
	4	+
	5	+# SRC Quality
	6	+
	7	+This document not yet complete.
	8	+
	9	+When measuring the performance of a Sample Rate Converter, there are three
	10	+factors 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	+
	24	+There are a number of sample rate converters available for downloading but I
	25	+will 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	+
	45	+It should be noted that the first three converters above are based on the
	46	+algorithm by [Julius O. Smith](http://www-ccrma.stanford.edu/~jos/resample/)
	47	+which emulates the conversion of the digital signal to an analogue one and then
	48	+sampling the analogue signal at the new sample rate.
	49	+
	50	+## Methodology
	51	+
	52	+Measuring the SNR of a converter is relatively straight forward. Generate an
	53	+input signal consisting of a windowed sine wave, sample rate convert it and
	54	+measure the signal-to-noise ratio of the output signal. A typical length for the
	55	+original file is 30000 samples.
	56	+
	57	+The bandwidth of a sample rate converter is a little more difficult to measure.
	58	+Currently this is done by generating two short files containing a windowed sine
	59	+wave. The frequencies of the sine waves are 0.35 and 0.495 of the sample rate.
	60	+These file are then upsampled by a factor of 2 using the converter under test.
	61	+If the attenutaion of the lower frquency is less than 3dB and higher frequency
	62	+is more than 3dB, it is then possible to iteratively increase the lower
	63	+frequency and decrease the upper frequency keeping the -3dB point bracketed.
	64	+When the distance between the upper and lower frequency is sufficiently small,
	65	+it is possible to obtain a very accurate estimate of the -3dB frequency.
	66	+
	67	+The speed of a sample rate converter is easy to measure; simply perform a
	68	+conversion on a large file or a number of smaller files and time the conversion
	69	+process.
	70	+
	71	+The above measurement techniques are built into a test program which is
	72	+delivered with the Secret Rabbit Code source code distibution. This program is
	73	+able to test the first four of the above converters.
	74	+
	75	+## SoX
	76	+
	77	+SoX provides three methods of resampling; a linear interpolator, a polyphase
	78	+resampler and the Julius O. Smith simulated analogue filter method.
	79	+
	80	+## Shibatch
	81	+
	82	+Shibach
	83	+
	84	+More Coming Soon.

docs/win32.md+15−0

@@ -0,0 +1,15 @@
	1	+---
	2	+layout: default
	3	+---
	4	+
	5	+# Compiling on Win32
	6	+
	7	+You can use [CMake](https://cmake.org/) to generate Visual Studio project. The
	8	+configuration process is described [here](https://cmake.org/runningcmake/).
	9	+
	10	+The libsamplerate library itself does not require any dependencies, but if you
	11	+want to build examples and tests, you will need the [libsndfile](https://github.com/libsndfile/libsndfile)
	12	+and [FFTW](http://www.fftw.org/) libraries. The easiest way to install them is
	13	+to use a package manager, such as [Vcpkg](https://github.com/microsoft/vcpkg). Their README.md contains detailed
	14	+installation instructions for supported platforms. Libsamplerate requires the
	15	+`libsndfile` and `fftw3` packages.

Update site documentation

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code