Emeric Vigier | eebea67 | 2012-08-06 17:36:30 -0400 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <HTML> |
| 3 | |
| 4 | <HEAD> |
| 5 | <TITLE> |
| 6 | Secret Rabbit Code (aka libsamplerate) |
| 7 | </TITLE> |
| 8 | <META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)"> |
| 9 | <META NAME="Version" CONTENT="libsamplerate-0.1.8"> |
| 10 | <META NAME="Description" CONTENT="The Secret Rabbit Code Home Page"> |
| 11 | <META NAME="Keywords" CONTENT="libsamplerate sound resample audio dsp Linux"> |
| 12 | <LINK REL=StyleSheet HREF="SRC.css" TYPE="text/css" MEDIA="all"> |
| 13 | </HEAD> |
| 14 | |
| 15 | <BODY TEXT="#FFFFFF" BGCOLOR="#000000" LINK="#FB1465" VLINK="#FB1465" ALINK="#FB1465"> |
| 16 | <!-- pepper --> |
| 17 | <CENTER> |
| 18 | <IMG SRC="SRC.png" HEIGHT=100 WIDTH=760 ALT="SRC.png"> |
| 19 | </CENTER> |
| 20 | <!-- pepper --> |
| 21 | <BR> |
| 22 | <!-- pepper --> |
| 23 | <TABLE ALIGN="center" WIDTH="98%"> |
| 24 | <TR> |
| 25 | <TD VALIGN="top"> |
| 26 | <BR> |
| 27 | <DIV CLASS="nav"> |
| 28 | <BR> |
| 29 | <A HREF="index.html">Home</A><BR> |
| 30 | <BR> |
| 31 | <A HREF="api_simple.html">Simple API</A><BR> |
| 32 | <A HREF="api_full.html">Full API</A><BR> |
| 33 | <A HREF="api_callback.html">Callback API</A><BR> |
| 34 | <A HREF="api_misc.html">Miscellaneous</A><BR> |
| 35 | <A HREF="api_misc.html#ErrorReporting">Error Handling</A><BR> |
| 36 | <BR> |
| 37 | <DIV CLASS="block"> |
| 38 | Author :<BR>Erik de Castro Lopo |
| 39 | <!-- pepper --> |
| 40 | <BR><BR> |
| 41 | <!-- pepper --> |
| 42 | |
| 43 | </DIV> |
| 44 | <IMG SRC= |
| 45 | "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_api.dat" |
| 46 | HEIGHT=30 WIDTH=100 ALT="counter.gif"> |
| 47 | </DIV> |
| 48 | |
| 49 | </TD> |
| 50 | <!-- pepper --> |
| 51 | <!-- ######################################################################## --> |
| 52 | <!-- pepper --> |
| 53 | <TD VALIGN="top"> |
| 54 | <DIV CLASS="block"> |
| 55 | |
| 56 | <H1><B>Full API</B></H1> |
| 57 | <P> |
| 58 | The full API consists of the following functions : |
| 59 | </P> |
| 60 | <PRE> |
| 61 | SRC_STATE* <A HREF="#Init">src_new</A> (int converter_type, int channels, int *error) ; |
| 62 | SRC_STATE* <A HREF="#CleanUp">src_delete</A> (SRC_STATE *state) ; |
| 63 | |
| 64 | int <A HREF="#Process">src_process</A> (SRC_STATE *state, SRC_DATA *data) ; |
| 65 | int <A HREF="#Reset">src_reset</A> (SRC_STATE *state) ; |
| 66 | int <A HREF="#SetRatio">src_set_ratio</A> (SRC_STATE *state, double new_ratio) ; |
| 67 | </PRE> |
| 68 | |
| 69 | <A NAME="Init"></A> |
| 70 | <H3><BR>Initialisation</H3> |
| 71 | <PRE> |
| 72 | SRC_STATE* src_new (int converter_type, int channels, int *error) ; |
| 73 | </PRE> |
| 74 | <P> |
| 75 | The <B>src_new</B> function returns an anonymous pointer to a sample rate |
| 76 | converter object, src_state. |
| 77 | If an error occurs the function returns a NULL pointer and fills in the |
| 78 | error value pointed to by the <B>error</B> pointer supplied by the caller. |
| 79 | The converter must be one of the supplied converter types documented |
| 80 | <A HREF="api_misc.html#Converters">here</A>. |
| 81 | </P> |
| 82 | |
| 83 | <A NAME="CleanUp"></A> |
| 84 | <H3><BR>Cleanup</H3> |
| 85 | <PRE> |
| 86 | SRC_STATE* src_delete (SRC_STATE *state) ; |
| 87 | </PRE> |
| 88 | <P> |
| 89 | The <B>src_delete</B> function frees up all memory allocated for the given sample |
| 90 | rate converter object and returns a NULL pointer. |
| 91 | The caller is responsible for freeing any memory passed to the sample rate converter |
| 92 | via the pointer to the <B>SRC_DATA</B> struct. |
| 93 | </P> |
| 94 | |
| 95 | <A NAME="Process"></A> |
| 96 | <H3><BR>Process</H3> |
| 97 | <PRE> |
| 98 | int src_process (SRC_STATE *state, SRC_DATA *data) ; |
| 99 | </PRE> |
| 100 | <P> |
| 101 | The <B>src_process</B> function processes the data provided by the caller |
| 102 | in an <B>SRC_DATA</B> struct using the sample rate converter object specified |
| 103 | by the <B>SRC_STATE</B> pointer. |
| 104 | When operating on streaming data, this function can be called over and over again, |
| 105 | with each new call providing new input data and returning new output data. |
| 106 | </P> |
| 107 | |
| 108 | <P> |
| 109 | The <B>SRC_DATA</B> struct passed as the second parameter to the <B>src_process</B> |
| 110 | function has the following fields: |
| 111 | </P> |
| 112 | <PRE> |
| 113 | typedef struct |
| 114 | { float *data_in, *data_out ; |
| 115 | |
| 116 | long input_frames, output_frames ; |
| 117 | long input_frames_used, output_frames_gen ; |
| 118 | |
| 119 | int end_of_input ; |
| 120 | |
| 121 | double src_ratio ; |
| 122 | } SRC_DATA ; |
| 123 | </PRE> |
| 124 | <P> |
| 125 | The fields of this struct which must be filled in by the caller are: |
| 126 | </P> |
| 127 | <PRE> |
| 128 | data_in : A pointer to the input data samples. |
| 129 | input_frames : The number of frames of data pointed to by data_in. |
| 130 | data_out : A pointer to the output data samples. |
| 131 | output_frames : Maximum number of frames pointer to by data_out. |
| 132 | src_ratio : Equal to output_sample_rate / input_sample_rate. |
| 133 | end_of_input : Equal to 0 if more input data is available and 1 |
| 134 | otherwise. |
| 135 | </PRE> |
| 136 | <P> |
| 137 | Note that the data_in and data_out arrays may not overlap. If they do, the |
| 138 | library will return an error code. |
| 139 | </P> |
| 140 | <P> |
| 141 | When the <B>src_process</B> function returns <B>output_frames_gen</B> will be |
| 142 | set to the number of output frames generated and <B>input_frames_used</B> will |
| 143 | be set to the number of input frames consumed to generate the provided number of |
| 144 | output frames. |
| 145 | </P> |
| 146 | |
| 147 | <P> |
| 148 | The <B>src_process</B> function returns non-zero if an error occurs. |
| 149 | The non-zero error return value can be decoded into a text string using the function |
| 150 | documented <A HREF="api_misc.html#ErrorReporting">here</A>. |
| 151 | </P> |
| 152 | |
| 153 | <A NAME="Reset"></A> |
| 154 | <H3><BR>Reset</H3> |
| 155 | <PRE> |
| 156 | int src_reset (SRC_STATE *state) ; |
| 157 | </PRE> |
| 158 | <P> |
| 159 | The <B>src_reset</B> function resets the internal state of the sample rate |
| 160 | converter object to the same state it had immediately after its creation using |
| 161 | <B>src_new</B>. |
| 162 | This should be called whenever a sample rate converter is to be used on two |
| 163 | separate, unrelated pieces of audio. |
| 164 | </P> |
| 165 | |
| 166 | <A NAME="SetRatio"></A> |
| 167 | <H3><BR>Set Ratio</H3> |
| 168 | <PRE> |
| 169 | int src_set_ratio (SRC_STATE *state, double new_ratio) ; |
| 170 | </PRE> |
| 171 | |
| 172 | <p> |
| 173 | When using the <B>src_process</B> or <B>src_callback_process</B> APIs and |
| 174 | updating the <B>src_ratio</B> field of the <B>SRC_STATE</B> struct, the library |
| 175 | will try to smoothly transition between the conversion ratio of the last call |
| 176 | and the conversion ratio of the current call. |
| 177 | <p/> |
| 178 | |
| 179 | <P> |
| 180 | If the user want to bypass this smooth transition and achieve a step response in |
| 181 | the conversion ratio, the <B>src_set_ratio</B> function can be used to set the |
| 182 | starting conversion ratio of the next call to <B>src_process</B> or |
| 183 | <B>src_callback_process</B>. |
| 184 | <p/> |
| 185 | |
| 186 | <P> |
| 187 | This function returns non-zero on error and the error return value can be |
| 188 | decoded into a text string using the function documented |
| 189 | <A HREF="api_misc.html#ErrorReporting">here</A>.</P> |
| 190 | |
| 191 | <!-- <A HREF="mailto:aldel@mega-nerd.com">For the spam bots</A> --> |
| 192 | |
| 193 | </DIV> |
| 194 | </TD></TR> |
| 195 | </TABLE> |
| 196 | |
| 197 | </BODY> |
| 198 | </HTML> |
| 199 | |