libaudioop.tex 9.32 KB
Newer Older
1
\section{Built-in Module \sectcode{audioop}}
2 3
\bimodindex{audioop}

4 5
The \code{audioop} module contains some useful operations on sound fragments.
It operates on sound fragments consisting of signed integer samples
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
8, 16 or 32 bits wide, stored in Python strings.  This is the same
format as used by the \code{al} and \code{sunaudiodev} modules.  All
scalar items are integers, unless specified otherwise.

A few of the more complicated operations only take 16-bit samples,
otherwise the sample size (in bytes) is always a parameter of the operation.

The module defines the following variables and functions:

\renewcommand{\indexsubitem}{(in module audioop)}
\begin{excdesc}{error}
This exception is raised on all errors, such as unknown number of bytes
per sample, etc.
\end{excdesc}

\begin{funcdesc}{add}{fragment1\, fragment2\, width}
22 23 24 25
Return a fragment which is the addition of the two samples passed as
parameters.  \var{width} is the sample width in bytes, either
\code{1}, \code{2} or \code{4}.  Both fragments should have the same
length.
26 27 28
\end{funcdesc}

\begin{funcdesc}{adpcm2lin}{adpcmfragment\, width\, state}
29 30 31 32
Decode an Intel/DVI ADPCM coded fragment to a linear fragment.  See
the description of \code{lin2adpcm} for details on ADPCM coding.
Return a tuple \code{(\var{sample}, \var{newstate})} where the sample
has the width specified in \var{width}.
33 34 35
\end{funcdesc}

\begin{funcdesc}{adpcm32lin}{adpcmfragment\, width\, state}
36 37
Decode an alternative 3-bit ADPCM code.  See \code{lin2adpcm3} for
details.
38 39 40
\end{funcdesc}

\begin{funcdesc}{avg}{fragment\, width}
41
Return the average over all samples in the fragment.
42 43 44
\end{funcdesc}

\begin{funcdesc}{avgpp}{fragment\, width}
45 46 47
Return the average peak-peak value over all samples in the fragment.
No filtering is done, so the usefulness of this routine is
questionable.
48 49 50
\end{funcdesc}

\begin{funcdesc}{bias}{fragment\, width\, bias}
51 52
Return a fragment that is the original fragment with a bias added to
each sample.
53 54 55
\end{funcdesc}

\begin{funcdesc}{cross}{fragment\, width}
56 57
Return the number of zero crossings in the fragment passed as an
argument.
58 59 60
\end{funcdesc}

\begin{funcdesc}{findfactor}{fragment\, reference}
61 62 63 64 65
Return a factor \var{F} such that
\code{rms(add(fragment, mul(reference, -F)))} is minimal, i.e.,
return the factor with which you should multiply \var{reference} to
make it match as well as possible to \var{fragment}.  The fragments
should both contain 2-byte samples.
66 67 68 69 70

The time taken by this routine is proportional to \code{len(fragment)}. 
\end{funcdesc}

\begin{funcdesc}{findfit}{fragment\, reference}
71 72 73 74 75
This routine (which only accepts 2-byte sample fragments)

Try to match \var{reference} as well as possible to a portion of
\var{fragment} (which should be the longer fragment).  This is
(conceptually) done by taking slices out of \var{fragment}, using
76
\code{findfactor} to compute the best match, and minimizing the
77 78
result.  The fragments should both contain 2-byte samples.  Return a
tuple \code{(\var{offset}, \var{factor})} where \var{offset} is the
79
(integer) offset into \var{fragment} where the optimal match started
80 81
and \var{factor} is the (floating-point) factor as per
\code{findfactor}.
82 83 84
\end{funcdesc}

\begin{funcdesc}{findmax}{fragment\, length}
85 86 87 88
Search \var{fragment} for a slice of length \var{length} samples (not
bytes!)\ with maximum energy, i.e., return \var{i} for which
\code{rms(fragment[i*2:(i+length)*2])} is maximal.  The fragments
should both contain 2-byte samples.
89 90 91 92 93

The routine takes time proportional to \code{len(fragment)}.
\end{funcdesc}

\begin{funcdesc}{getsample}{fragment\, width\, index}
94
Return the value of sample \var{index} from the fragment.
95 96 97
\end{funcdesc}

\begin{funcdesc}{lin2lin}{fragment\, width\, newwidth}
98
Convert samples between 1-, 2- and 4-byte formats.
99 100 101
\end{funcdesc}

\begin{funcdesc}{lin2adpcm}{fragment\, width\, state}
102 103 104 105 106
Convert samples to 4 bit Intel/DVI ADPCM encoding.  ADPCM coding is an
adaptive coding scheme, whereby each 4 bit number is the difference
between one sample and the next, divided by a (varying) step.  The
Intel/DVI ADPCM algorithm has been selected for use by the IMA, so it
may well become a standard.
107

108
\code{State} is a tuple containing the state of the coder.  The coder
109 110
returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the
\var{newstate} should be passed to the next call of lin2adpcm.  In the
111 112
initial call \code{None} can be passed as the state.  \var{adpcmfrag}
is the ADPCM coded fragment packed 2 4-bit values per byte.
113 114 115 116 117
\end{funcdesc}

\begin{funcdesc}{lin2adpcm3}{fragment\, width\, state}
This is an alternative ADPCM coder that uses only 3 bits per sample.
It is not compatible with the Intel/DVI ADPCM coder and its output is
118
not packed (due to laziness on the side of the author).  Its use is
119 120 121 122
discouraged.
\end{funcdesc}

\begin{funcdesc}{lin2ulaw}{fragment\, width}
123 124 125 126
Convert samples in the audio fragment to U-LAW encoding and return
this as a Python string.  U-LAW is an audio encoding format whereby
you get a dynamic range of about 14 bits using only 8 bit samples.  It
is used by the Sun audio hardware, among others.
127 128 129
\end{funcdesc}

\begin{funcdesc}{minmax}{fragment\, width}
130 131
Return a tuple consisting of the minimum and maximum values of all
samples in the sound fragment.
132 133 134
\end{funcdesc}

\begin{funcdesc}{max}{fragment\, width}
135 136
Return the maximum of the {\em absolute value} of all samples in a
fragment.
137 138 139
\end{funcdesc}

\begin{funcdesc}{maxpp}{fragment\, width}
140
Return the maximum peak-peak value in the sound fragment.
141 142 143
\end{funcdesc}

\begin{funcdesc}{mul}{fragment\, width\, factor}
144
Return a fragment that has all samples in the original framgent
145
multiplied by the floating-point value \var{factor}.  Overflow is
146 147 148 149
silently ignored.
\end{funcdesc}

\begin{funcdesc}{reverse}{fragment\, width}
150
Reverse the samples in a fragment and returns the modified fragment.
151 152
\end{funcdesc}

153 154
\begin{funcdesc}{rms}{fragment\, width}
Return the root-mean-square of the fragment, i.e.
155 156 157 158 159 160 161 162 163 164 165 166 167
\iftexi
the square root of the quotient of the sum of all squared sample value,
divided by the sumber of samples.
\else
% in eqn: sqrt { sum S sub i sup 2  over n }
\begin{displaymath}
\catcode`_=8
\sqrt{\frac{\sum{{S_{i}}^{2}}}{n}}
\end{displaymath}
\fi
This is a measure of the power in an audio signal.
\end{funcdesc}

168
\begin{funcdesc}{tomono}{fragment\, width\, lfactor\, rfactor} 
169 170 171
Convert a stereo fragment to a mono fragment.  The left channel is
multiplied by \var{lfactor} and the right channel by \var{rfactor}
before adding the two channels to give a mono signal.
172 173 174
\end{funcdesc}

\begin{funcdesc}{tostereo}{fragment\, width\, lfactor\, rfactor}
175 176 177 178
Generate a stereo fragment from a mono fragment.  Each pair of samples
in the stereo fragment are computed from the mono sample, whereby left
channel samples are multiplied by \var{lfactor} and right channel
samples by \var{rfactor}.
179 180
\end{funcdesc}

181
\begin{funcdesc}{ulaw2lin}{fragment\, width}
182 183 184
Convert sound fragments in ULAW encoding to linearly encoded sound
fragments.  ULAW encoding always uses 8 bits samples, so \var{width}
refers only to the sample width of the output fragment here.
185 186 187
\end{funcdesc}

Note that operations such as \code{mul} or \code{max} make no
188
distinction between mono and stereo fragments, i.e.\ all samples are
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
treated equal.  If this is a problem the stereo fragment should be split
into two mono fragments first and recombined later.  Here is an example
of how to do that:
\bcode\begin{verbatim}
def mul_stereo(sample, width, lfactor, rfactor):
    lsample = audioop.tomono(sample, width, 1, 0)
    rsample = audioop.tomono(sample, width, 0, 1)
    lsample = audioop.mul(sample, width, lfactor)
    rsample = audioop.mul(sample, width, rfactor)
    lsample = audioop.tostereo(lsample, width, 1, 0)
    rsample = audioop.tostereo(rsample, width, 0, 1)
    return audioop.add(lsample, rsample, width)
\end{verbatim}\ecode

If you use the ADPCM coder to build network packets and you want your
204
protocol to be stateless (i.e.\ to be able to tolerate packet loss)
205
you should not only transmit the data but also the state.  Note that
206
you should send the \var{initial} state (the one you passed to
207
\code{lin2adpcm}) along to the decoder, not the final state (as returned by
208
the coder).  If you want to use \code{struct} to store the state in
209 210 211 212
binary you can code the first element (the predicted value) in 16 bits
and the second (the delta index) in 8.

The ADPCM coders have never been tried against other ADPCM coders,
213
only against themselves.  It could well be that I misinterpreted the
214 215 216 217
standards in which case they will not be interoperable with the
respective standards.

The \code{find...} routines might look a bit funny at first sight.
218
They are primarily meant to do echo cancellation.  A reasonably
219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235
fast way to do this is to pick the most energetic piece of the output
sample, locate that in the input sample and subtract the whole output
sample from the input sample:
\bcode\begin{verbatim}
def echocancel(outputdata, inputdata):
    pos = audioop.findmax(outputdata, 800)    # one tenth second
    out_test = outputdata[pos*2:]
    in_test = inputdata[pos*2:]
    ipos, factor = audioop.findfit(in_test, out_test)
    # Optional (for better cancellation):
    # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)], 
    #              out_test)
    prefill = '\0'*(pos+ipos)*2
    postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
    outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill
    return audioop.add(inputdata, outputdata, 2)
\end{verbatim}\ecode