Doc/libaudioop.tex

   1 \section{Built-in module \sectcode{audioop}}
   2 \bimodindex{audioop}
   3
   4 The audioop module contains some useful operations on sound fragments.
   5 It operates on sound fragments consisting of signed integer samples of
   6 8, 16 or 32 bits wide, stored in Python strings.  This is the same
   7 format as used by the \code{al} and \code{sunaudiodev} modules.  All
   8 scalar items are integers, unless specified otherwise.
   9
  10 A few of the more complicated operations only take 16-bit samples,
  11 otherwise the sample size (in bytes) is always a parameter of the operation.
  12
  13 The module defines the following variables and functions:
  14
  15 \renewcommand{\indexsubitem}{(in module audioop)}
  16 \begin{excdesc}{error}
  17 This exception is raised on all errors, such as unknown number of bytes
  18 per sample, etc.
  19 \end{excdesc}
  20
  21 \begin{funcdesc}{add}{fragment1\, fragment2\, width}
  22 This function returns a fragment that is the addition of the two samples
  23 passed as parameters. \var{width} is the sample width in bytes, either
  24 \code{1}, \code{2} or \code{4}. Both fragments should have the same length.
  25 \end{funcdesc}
  26
  27 \begin{funcdesc}{adpcm2lin}{adpcmfragment\, width\, state}
  28 This routine decodes an Intel/DVI ADPCM coded fragment to a linear
  29 fragment. See the description of \code{lin2adpcm} for details on ADPCM
  30 coding. The routine returns a tuple
  31 \code{(\var{sample}, \var{newstate})}
  32 where the sample has the width specified in \var{width}.
  33 \end{funcdesc}
  34
  35 \begin{funcdesc}{adpcm32lin}{adpcmfragment\, width\, state}
  36 This routine decodes an alternative 3-bit ADPCM code. See
  37 \code{lin2adpcm3} for details.
  38 \end{funcdesc}
  39
  40 \begin{funcdesc}{avg}{fragment\, width}
  41 This function returns the average over all samples in the fragment.
  42 \end{funcdesc}
  43
  44 \begin{funcdesc}{avgpp}{fragment\, width}
  45 This function returns the average peak-peak value over all samples in
  46 the fragment. No filtering is done, so the usefulness of this routine
  47 is questionable.
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{bias}{fragment\, width\, bias}
  51 This function returns a fragment that is the original fragment with a
  52 bias added to each sample.
  53 \end{funcdesc}
  54
  55 \begin{funcdesc}{cross}{fragment\, width}
  56 This function returns the number of zero crossings in the fragment
  57 passed as an argument.
  58 \end{funcdesc}
  59
  60 \begin{funcdesc}{findfactor}{fragment\, reference}
  61 This routine (which only accepts 2-byte sample fragments) calculates a
  62 factor \var{F} such that \code{rms(add(fragment, mul(reference, -F)))}
  63 is minimal, i.e. it calculates the factor with which you should
  64 multiply \var{reference} to make it match as good as possible to
  65 \var{fragment}. The fragments should be the same size.
  66
  67 The time taken by this routine is proportional to \code{len(fragment)}.
  68 \end{funcdesc}
  69
  70 \begin{funcdesc}{findfit}{fragment\, reference}
  71 This routine (which only accepts 2-byte sample fragments) tries to
  72 match \var{reference} as good as possible to a portion of
  73 \var{fragment} (which should be the longer fragment). It
  74 (conceptually) does this by taking slices out of \var{fragment}, using
  75 \code{findfactor} to compute the best match, and minimizing the
  76 result.
  77 It returns a tuple \code{(\var{offset}, \var{factor})} with \var{offset} the
  78 (integer) offset into \var{fragment} where the optimal match started
  79 and \var{factor} the floating-point factor as per \code{findfactor}.
  80 \end{funcdesc}
  81
  82 \begin{funcdesc}{findmax}{fragment\, length}
  83 This routine (which only accepts 2-byte sample fragments) searches
  84 \var{fragment} for a slice of length \var{length} samples (not bytes!)
  85 with maximum energy, i.e. it returns \var{i} for which
  86 \code{rms(fragment[i*2:(i+length)*2])} is maximal.
  87
  88 The routine takes time proportional to \code{len(fragment)}.
  89 \end{funcdesc}
  90
  91 \begin{funcdesc}{getsample}{fragment\, width\, index}
  92 This function returns the value of sample \var{index} from the
  93 fragment.
  94 \end{funcdesc}
  95
  96 \begin{funcdesc}{lin2lin}{fragment\, width\, newwidth}
  97 This function converts samples between 1-, 2- and 4-byte formats.
  98 \end{funcdesc}
  99
 100 \begin{funcdesc}{lin2adpcm}{fragment\, width\, state}
 101 This function converts samples to 4 bit Intel/DVI ADPCM encoding.
 102 ADPCM coding is an adaptive coding scheme, whereby each 4 bit number
 103 is the difference between one sample and the next, divided by a
 104 (varying) step. The Intel/DVI ADPCM algorithm has been selected for
 105 use by the IMA, so it may well become a standard.
 106
 107 \code{State} is a tuple containing the state of the coder. The coder
 108 returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the
 109 \var{newstate} should be passed to the next call of lin2adpcm.  In the
 110 initial call \code{None} can be passed as the state. \var{adpcmfrag} is
 111 the ADPCM coded fragment packed 2 4-bit values per byte.
 112 \end{funcdesc}
 113
 114 \begin{funcdesc}{lin2adpcm3}{fragment\, width\, state}
 115 This is an alternative ADPCM coder that uses only 3 bits per sample.
 116 It is not compatible with the Intel/DVI ADPCM coder and its output is
 117 not packed (due to laziness on the side of the author). Its use is
 118 discouraged.
 119 \end{funcdesc}
 120
 121 \begin{funcdesc}{lin2ulaw}{fragment\, width}
 122 This function converts samples in the audio fragment to U-LAW encoding
 123 and returns this as a Python string. U-LAW is an audio encoding format
 124 whereby you get a dynamic range of about 14 bits using only 8 bit
 125 samples. It is used by the Sun audio hardware, among others.
 126 \end{funcdesc}
 127
 128 \begin{funcdesc}{minmax}{fragment\, width}
 129 This function returns a tuple consisting of the minimum and maximum
 130 values of all samples in the sound fragment.
 131 \end{funcdesc}
 132
 133 \begin{funcdesc}{max}{fragment\, width}
 134 This function returns the maximum of the {\em absolute value} of all
 135 samples in a fragment.
 136 \end{funcdesc}
 137
 138 \begin{funcdesc}{maxpp}{fragment\, width}
 139 This function returns the maximum peak-peak value in the sound fragment.
 140 \end{funcdesc}
 141
 142 \begin{funcdesc}{mul}{fragment\, width\, factor}
 143 Mul returns a fragment that has all samples in the original framgent
 144 multiplied by the floating-point value \var{factor}. Overflow is
 145 silently ignored.
 146 \end{funcdesc}
 147
 148 \begin{funcdesc}{reverse}{fragment\, width}
 149 This function reverses the samples in a fragment and returns the
 150 modified fragment.
 151 \end{funcdesc}
 152
 153 \begin{funcdesc}{tomono}{fragment\, width\, lfactor\, rfactor}
 154 This function converts a stereo fragment to a mono fragment. The left
 155 channel is multiplied by \var{lfactor} and the right channel by
 156 \var{rfactor} before adding the two channels to give a mono signal.
 157 \end{funcdesc}
 158
 159 \begin{funcdesc}{tostereo}{fragment\, width\, lfactor\, rfactor}
 160 This function generates a stereo fragment from a mono fragment. Each
 161 pair of samples in the stereo fragment are computed from the mono
 162 sample, whereby left channel samples are multiplied by \var{lfactor}
 163 and right channel samples by \var{rfactor}.
 164 \end{funcdesc}
 165
 166 \begin{funcdesc}{mul}{fragment\, width\, factor}
 167 Mul returns a fragment that has all samples in the original framgent
 168 multiplied by the floating-point value \var{factor}. Overflow is
 169 silently ignored.
 170 \end{funcdesc}
 171
 172 \begin{funcdesc}{rms}{fragment\, width\, factor}
 173 Returns the root-mean-square of the fragment, i.e.
 174 \iftexi
 175 the square root of the quotient of the sum of all squared sample value,
 176 divided by the sumber of samples.
 177 \else
 178 % in eqn: sqrt { sum S sub i sup 2  over n }
 179 \begin{displaymath}
 180 \catcode`_=8
 181 \sqrt{\frac{\sum{{S_{i}}^{2}}}{n}}
 182 \end{displaymath}
 183 \fi
 184 This is a measure of the power in an audio signal.
 185 \end{funcdesc}
 186
 187 \begin{funcdesc}{ulaw2lin}{fragment\, width}
 188 This function converts sound fragments in ULAW encoding to linearly
 189 encoded sound fragments. ULAW encoding always uses 8 bits samples, so
 190 \var{width} refers only to the sample width of the output fragment here.
 191 \end{funcdesc}
 192
 193 Note that operations such as \code{mul} or \code{max} make no
 194 distinction between mono and stereo fragments, i.e. all samples are
 195 treated equal.  If this is a problem the stereo fragment should be split
 196 into two mono fragments first and recombined later.  Here is an example
 197 of how to do that:
 198 \bcode\begin{verbatim}
 199 def mul_stereo(sample, width, lfactor, rfactor):
 200     lsample = audioop.tomono(sample, width, 1, 0)
 201     rsample = audioop.tomono(sample, width, 0, 1)
 202     lsample = audioop.mul(sample, width, lfactor)
 203     rsample = audioop.mul(sample, width, rfactor)
 204     lsample = audioop.tostereo(lsample, width, 1, 0)
 205     rsample = audioop.tostereo(rsample, width, 0, 1)
 206     return audioop.add(lsample, rsample, width)
 207 \end{verbatim}\ecode
 208
 209 If you use the ADPCM coder to build network packets and you want your
 210 protocol to be stateless (i.e. to be able to tolerate packet loss)
 211 you should not only transmit the data but also the state. Note that
 212 you should send the \var{initial} state (the one you passed to
 213 lin2adpcm) along to the decoder, not the final state (as returned by
 214 the coder). If you want to use \code{struct} to store the state in
 215 binary you can code the first element (the predicted value) in 16 bits
 216 and the second (the delta index) in 8.
 217
 218 The ADPCM coders have never been tried against other ADPCM coders,
 219 only against themselves. It could well be that I misinterpreted the
 220 standards in which case they will not be interoperable with the
 221 respective standards.
 222
 223 The \code{find...} routines might look a bit funny at first sight.
 224 They are primarily meant for doing echo cancellation. A reasonably
 225 fast way to do this is to pick the most energetic piece of the output
 226 sample, locate that in the input sample and subtract the whole output
 227 sample from the input sample:
 228 \bcode\begin{verbatim}
 229 def echocancel(outputdata, inputdata):
 230     pos = audioop.findmax(outputdata, 800)    # one tenth second
 231     out_test = outputdata[pos*2:]
 232     in_test = inputdata[pos*2:]
 233     ipos, factor = audioop.findfit(in_test, out_test)
 234     # Optional (for better cancellation):
 235     # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
 236     #              out_test)
 237     prefill = '\0'*(pos+ipos)*2
 238     postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
 239     outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill
 240     return audioop.add(inputdata, outputdata, 2)
 241 \end{verbatim}\ecode