History

Update site documentation

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

evpobr committed 6 years ago

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

Showing the changes to docs/api_misc.md (1 of 38 files). Show all

Unified · Split

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.

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

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

Repository code

Go to file
t