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