libsamplerate/doc/api_simple.html

   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>Simple API</B></H1>
  57
  58 <P>
  59 <B>Important Note:</B>
  60 The simple API is not designed to work on small chunks of a larger piece of
  61 audio.
  62 If you attempt to use it this way you are doing it wrong and will not get the
  63 results you want.
  64 For processing audio data in chunks you <b>must</b> use the
  65         <a href="api_full.html">full api</a>
  66 or the
  67         <a href="api_callback.html">callback based api</a>.
  68 </P>
  69
  70 <br/><br/>
  71
  72 <P>
  73 The simple API consists of a single function :
  74 </P>
  75 <PRE>
  76       int src_simple (SRC_DATA *data, int converter_type, int channels) ;
  77 </PRE>
  78 <P>
  79 The use of this function rather than the more fully featured API requires the caller
  80 to know the total length of the input data before hand and that all input and output
  81 data can be held in the system's memory at once.
  82 It also assumes that there is a single constant ratio between input and output sample
  83 rates.
  84 <!--
  85 If these conditions cannot be met, the full featured API should be used instead.
  86 In addition, this documentation is complemented by this
  87 <A HREF="ex_simple.html">example code</A>. -->
  88 </P>
  89
  90 <P>
  91 Dealing with the easy stuff first, the <B>converter_type</B> parameter should be
  92 one of the values defined in <B>samplerate.h</B> and documented
  93 <A HREF="api_misc.html#Converters">here</A> while the <b>channels</b> parameter
  94 specifies the number of interleaved channels that the sample rate converter
  95 is being asked to process (number of input channels and output channels is always
  96 equal).
  97 There is no hard upper limit on the number of channels; it is limited purely
  98 by the amount of memory available.
  99 </P>
 100
 101
 102 <P>
 103 The first parameter to <B>src_simple</B> is a pointer to an <B>SRC_DATA</B> struct
 104 (more info <A HREF="api_misc.html#SRC_DATA">here</A>) defined as follows:
 105 </P>
 106 <PRE>
 107       typedef struct
 108       {   float  *data_in, *data_out ;
 109
 110           long   input_frames, output_frames ;
 111           long   input_frames_used, output_frames_gen ;
 112
 113           int    end_of_input ;
 114
 115           double src_ratio ;
 116       } SRC_DATA ;
 117 </PRE>
 118 <P>
 119 The fields of this struct which must be filled in by the caller are:
 120 </P>
 121 <PRE>
 122       data_in       : A pointer to the input data samples.
 123       input_frames  : The number of frames of data pointed to by data_in.
 124       data_out      : A pointer to the output data samples.
 125       output_frames : Maximum number of frames pointer to by data_out.
 126       src_ratio     : Equal to output_sample_rate / input_sample_rate.
 127 </PRE>
 128 <P>
 129 When the <B>src_simple</B> function returns <B>output_frames_gen</B> will be
 130 set to the number of output frames generated and <B>input_frames_used</B> will
 131 be set to the number of input frames used to generate the provided number of
 132 output frames.
 133 </P>
 134 <P>
 135 The <B>src_simple</B> function returns a non-zero value when an error occurs.
 136 See <A HREF="api_misc.html#ErrorReporting">here</A> for how to convert the error value into
 137 a text string.
 138 </P>
 139
 140 </DIV>
 141 </TD></TR>
 142 </TABLE>
 143
 144 </BODY>
 145 </HTML>
 146